@steve31415/baselib 3.20.1 → 3.22.0

package/dist/app-update-browser/build-update.d.ts

@@ -1,4 +1,10 @@
 import type { Logger } from '../log-browser.js';
+/** A newer build learned this soon after the page became visible was found
+ * *because* the user returned (a frozen tab learns of deploys only then):
+ * reloading now would replace the page just as the eyes land on it
+ * (plasticine-way PERFORMANCE.md, "No updates on foreground"). Such a reload
+ * waits for the page to be hidden again. */
+export declare const RETURN_RELOAD_DEFER_MS = 10000;
 export type BuildUpdateState = {
     kind: 'current';
 } | {
@@ -20,8 +26,17 @@ export interface BuildUpdateDeps {
     reload?: () => void;
     pollMs?: number;
     onTrafficBuildChange?: (buildId: string) => void;
+    /** Whether this document's HTML came from the browser cache without a
+     * request (default: `shellServedFromCache`). */
+    shellFromCache?: () => boolean;
 }
 export declare function pageBuildId(): string;
+/** True when this page's HTML was served from the browser cache without
+ * reaching the server. Android Chrome does this when it restores a tab whose
+ * renderer it killed in the background, even for a `no-cache` shell, so the
+ * restored page can run a build older than current traffic (reader,
+ * 2026-09-26/27: 9 of 15 phone page loads). */
+export declare function shellServedFromCache(): boolean;
 export declare class BuildUpdateMonitor {
     private deps;
     private state;
@@ -34,6 +49,11 @@ export declare class BuildUpdateMonitor {
     private appliedRequestNumber;
     private trafficBuild;
     private checkFailure;
+    /** When the page last went from hidden to visible, or was loaded visible
+     * from a cached shell (a restored tab is a return in all but name). */
+    private returnedAt;
+    private restoredFromCache;
+    private deferUntilHidden;
     constructor(deps: BuildUpdateDeps);
     getState: () => BuildUpdateState;
     subscribe: (listener: () => void) => (() => void);
@@ -49,6 +69,7 @@ export declare class BuildUpdateMonitor {
     private observeTrafficBuild;
     private markAvailable;
     private maybeReload;
+    private justReturned;
     private setState;
     /** Polls only while visible: an interval in a hidden page would wake it
      * every few minutes to do nothing. Hidden pages learn of deploys from the

package/dist/app-update-browser/build-update.js

@@ -2,10 +2,29 @@
 // sync observations are an opportunistic second signal. Reload policy is
 // separate and injected through ReloadSafety.
 const DEFAULT_POLL_MS = 5 * 60 * 1000;
+/** A newer build learned this soon after the page became visible was found
+ * *because* the user returned (a frozen tab learns of deploys only then):
+ * reloading now would replace the page just as the eyes land on it
+ * (plasticine-way PERFORMANCE.md, "No updates on foreground"). Such a reload
+ * waits for the page to be hidden again. */
+export const RETURN_RELOAD_DEFER_MS = 10_000;
 const LEGACY_BUILD = 'legacy-pre-build-id';
 export function pageBuildId() {
     return document.querySelector('meta[name="pw-build-id"]')?.content || 'development';
 }
+/** True when this page's HTML was served from the browser cache without
+ * reaching the server. Android Chrome does this when it restores a tab whose
+ * renderer it killed in the background, even for a `no-cache` shell, so the
+ * restored page can run a build older than current traffic (reader,
+ * 2026-09-26/27: 9 of 15 phone page loads). */
+export function shellServedFromCache() {
+    const entry = globalThis.performance?.getEntriesByType?.('navigation')[0];
+    if (!entry)
+        return false;
+    if (entry.deliveryType === 'cache')
+        return true;
+    return entry.transferSize === 0 && entry.decodedBodySize > 0;
+}
 export class BuildUpdateMonitor {
     deps;
     state = { kind: 'current' };
@@ -18,6 +37,11 @@ export class BuildUpdateMonitor {
     appliedRequestNumber = 0;
     trafficBuild = null;
     checkFailure = false;
+    /** When the page last went from hidden to visible, or was loaded visible
+     * from a cached shell (a restored tab is a return in all but name). */
+    returnedAt = null;
+    restoredFromCache = false;
+    deferUntilHidden = false;
     constructor(deps) {
         this.deps = deps;
     }
@@ -32,6 +56,13 @@ export class BuildUpdateMonitor {
         this.started = true;
         this.lifecycle += 1;
         this.stopSafety = this.deps.safety.subscribe(() => this.maybeReload());
+        // A tab restored from the cache shows whatever build it last loaded; a
+        // reload now would replace it just as it appears. Treat it as a return.
+        // (A hidden restore needs nothing: its reload is out of sight anyway.)
+        if (document.visibilityState === 'visible' && (this.deps.shellFromCache ?? shellServedFromCache)()) {
+            this.returnedAt = Date.now();
+            this.restoredFromCache = true;
+        }
         if (document.visibilityState === 'visible')
             this.startPolling();
         document.addEventListener('visibilitychange', this.onVisibility);
@@ -116,6 +147,7 @@ export class BuildUpdateMonitor {
         if (buildId === this.deps.currentBuildId) {
             if (this.state.kind === 'available')
                 this.setState({ kind: 'current' });
+            this.deferUntilHidden = false;
             return;
         }
         this.markAvailable(buildId);
@@ -129,12 +161,23 @@ export class BuildUpdateMonitor {
                 observedBuildId: buildId,
             });
             this.setState({ kind: 'available', buildId });
+            if (!this.deferUntilHidden && this.justReturned()) {
+                this.deferUntilHidden = true;
+                this.deps.logger.info('build reload deferred until hidden', {
+                    pageBuildId: this.deps.currentBuildId,
+                    observedBuildId: buildId,
+                    sinceReturnMs: Date.now() - (this.returnedAt ?? Date.now()),
+                    restoredFromCache: this.restoredFromCache,
+                });
+            }
         }
         this.maybeReload();
     }
     maybeReload() {
         if (this.state.kind !== 'available' || !this.deps.safety.isSafe())
             return;
+        if (this.deferUntilHidden && document.visibilityState === 'visible')
+            return;
         const buildId = this.state.buildId;
         this.setState({ kind: 'reloading', buildId });
         if (this.deps.reload)
@@ -142,6 +185,11 @@ export class BuildUpdateMonitor {
         else
             location.reload();
     }
+    justReturned() {
+        return (document.visibilityState === 'visible' &&
+            this.returnedAt !== null &&
+            Date.now() - this.returnedAt < RETURN_RELOAD_DEFER_MS);
+    }
     setState(state) {
         this.state = state;
         for (const listener of this.listeners)
@@ -165,11 +213,16 @@ export class BuildUpdateMonitor {
     }
     onVisibility = () => {
         if (document.visibilityState === 'visible') {
+            this.returnedAt = Date.now();
+            this.restoredFromCache = false;
             this.startPolling();
             void this.checkNow();
         }
         else {
+            this.returnedAt = null;
             this.stopPolling();
+            // A reload deferred at the return happens now, out of sight.
+            this.maybeReload();
         }
     };
     onOnline = () => {

package/dist/sync-browser/client.d.ts

@@ -220,6 +220,11 @@ export declare class SyncClient<B, C extends EventBody, S extends EventBody, Sum
     /** One INFO per hidden spell: what the user saw change on return. */
     private finishReturnWindow;
     private connectNow;
+    /** Records a visible socket failure inside a return window. */
+    private noteReturnFailure;
+    /** The first failure of a return, before sync is back, retries quickly
+     * (once per return); anything else takes the ladder. */
+    private takeQuickRetry;
     private scheduleReconnect;
     private probeSession;
     private startOutage;

package/dist/sync-browser/client.js

@@ -21,6 +21,12 @@ const WAKE_CONNECT_REPLY_MS = 5_000;
 /** A hidden attempt's socket that dies sooner than this counts as failed. */
 const HIDDEN_SOCKET_MIN_LIFE_MS = 60_000;
 const RETURN_REPORT_TIMEOUT_MS = 15_000;
+/** The first visible failure of a return retries after this instead of the
+ * ladder's 1 s. After a phone tab was frozen, its old socket turns out dead
+ * (its close lands ~30 ms after the return) or the first new handshake fails
+ * without reaching the server, while HTTP works at once; the ladder's 1 s
+ * step then made every such return take 1.5-2 s (reader, 2026-09-26). */
+const RETURN_QUICK_RETRY_MS = 250;
 const SOCKET_CONNECTING = 0;
 const SOCKET_OPEN = 1;
 class LifecycleAbort {
@@ -465,6 +471,7 @@ export class SyncClient {
             this.plannedClose = null;
             this.startOutage(event.code, event.wasClean === true);
             if (!this.isHidden()) {
+                this.noteReturnFailure(event.code);
                 this.scheduleReconnect();
                 return;
             }
@@ -643,6 +650,9 @@ export class SyncClient {
             catchupOk: false,
             eventsOnReturn: 0,
             resyncOnReturn: 0,
+            failures: 0,
+            firstFailure: null,
+            quickRetryUsed: false,
             timer: this.options.runtime.setTimeout(() => this.finishReturnWindow(), RETURN_REPORT_TIMEOUT_MS),
         };
     }
@@ -665,6 +675,11 @@ export class SyncClient {
             catchupOk: window.catchupOk,
             eventsOnReturn: window.eventsOnReturn,
             resyncOnReturn: window.resyncOnReturn,
+            returnFailures: window.failures,
+            firstFailureAfterReturnMs: window.firstFailure?.afterReturnMs ?? null,
+            firstFailureSocketAgeMs: window.firstFailure?.socketAgeMs ?? null,
+            firstFailureOpened: window.firstFailure?.opened ?? null,
+            firstFailureCloseCode: window.firstFailure?.closeCode ?? null,
             sinceLastContactMs: window.sinceLastContactMs,
             backgroundCatchups: window.spell.backgroundCatchups,
             backgroundCatchupFailures: window.spell.backgroundCatchupFailures,
@@ -683,8 +698,35 @@ export class SyncClient {
         this.countdownTimer = null;
         this.connect();
     }
+    /** Records a visible socket failure inside a return window. */
+    noteReturnFailure(closeCode) {
+        const window = this.returnWindow;
+        if (window === null || window.establishedAt !== null)
+            return;
+        window.failures++;
+        if (window.firstFailure !== null)
+            return;
+        const now = this.now();
+        window.firstFailure = {
+            afterReturnMs: Math.max(0, now - window.visibleAt),
+            socketAgeMs: Math.max(0, now - this.socketCreatedAt),
+            opened: this.socketOpenedAt !== null,
+            closeCode,
+        };
+    }
+    /** The first failure of a return, before sync is back, retries quickly
+     * (once per return); anything else takes the ladder. */
+    takeQuickRetry() {
+        const window = this.returnWindow;
+        if (window === null || window.establishedAt !== null || window.quickRetryUsed)
+            return false;
+        window.quickRetryUsed = true;
+        return true;
+    }
     scheduleReconnect() {
-        const delay = RECONNECT_DELAYS_SECONDS[Math.min(this.reconnectAttempts, RECONNECT_DELAYS_SECONDS.length - 1)];
+        const ladderSeconds = RECONNECT_DELAYS_SECONDS[Math.min(this.reconnectAttempts, RECONNECT_DELAYS_SECONDS.length - 1)];
+        const delayMs = this.takeQuickRetry() ? RETURN_QUICK_RETRY_MS : ladderSeconds * 1000;
+        const delay = Math.ceil(delayMs / 1000);
         this.reconnectAttempts++;
         this.totalAttempts++;
         if (this.reconnectAttempts >= PROBE_AFTER_ATTEMPTS)
@@ -703,7 +745,7 @@ export class SyncClient {
             this.countdownTimer = null;
             this.reconnectTimer = null;
             this.connect();
-        }, delay * 1000);
+        }, delayMs);
     }
     async probeSession() {
         if (this.halted || this.disposed || this.probeInFlight)

package/dist/sync-browser/index.d.ts

@@ -1,2 +1,3 @@
 export * from './outbox.js';
 export * from './client.js';
+export * from './quiet-status.js';

package/dist/sync-browser/index.js

@@ -1,2 +1,3 @@
 export * from './outbox.js';
 export * from './client.js';
+export * from './quiet-status.js';

package/dist/sync-browser/quiet-status.d.ts

@@ -0,0 +1,23 @@
+import type { SyncClientState } from './client.js';
+/** How long a quiet transition must last while visible before it shows.
+ * After a frozen phone tab returns, reconnecting took 1.5-2.1 s (reader,
+ * 2026-09-26); 3 s leaves margin over that. */
+export declare const QUIET_TRANSITION_GRACE_MS = 3000;
+/** A short-lived connection state with no unsynced edits behind it. */
+export declare function isQuietTransition(status: SyncClientState, pendingCount: number): boolean;
+/** What to show now: a quiet transition only after it has lasted the grace
+ * period of visible time (counted from when it began or the page last became
+ * visible, whichever is later; pass `visibleSince = now` while hidden); until
+ * then, whatever was shown before it (`null` = nothing yet). Anything else
+ * shows at once. */
+export declare function statusToShow<V>(args: {
+    view: V;
+    quiet: boolean;
+    quietSince: number | null;
+    visibleSince: number;
+    lastShown: V | null;
+    now: number;
+    graceMs?: number;
+}): V | null;
+/** When the running grace period began (for scheduling a re-render at its end). */
+export declare function quietGraceStart(quietSince: number | null, visibleSince: number, now: number): number;

package/dist/sync-browser/quiet-status.js

@@ -0,0 +1,34 @@
+// Whether a sync status indicator should admit to a reconnect yet. Pure, so
+// apps' pills (React or not) share one rule: a reconnect with nothing at
+// stake is shown only once it has lasted a grace period of *visible* time,
+// so returning to a tab doesn't flash "Connecting…"/"Offline" just as the
+// eyes land on it (plasticine-way PERFORMANCE.md, "No updates on
+// foreground"). Unsynced edits and errors always show at once.
+/** How long a quiet transition must last while visible before it shows.
+ * After a frozen phone tab returns, reconnecting took 1.5-2.1 s (reader,
+ * 2026-09-26); 3 s leaves margin over that. */
+export const QUIET_TRANSITION_GRACE_MS = 3000;
+/** A short-lived connection state with no unsynced edits behind it. */
+export function isQuietTransition(status, pendingCount) {
+    if (pendingCount > 0)
+        return false;
+    return (status.kind === 'starting' ||
+        status.kind === 'connecting' ||
+        status.kind === 'reconnecting' ||
+        status.kind === 'disconnected');
+}
+/** What to show now: a quiet transition only after it has lasted the grace
+ * period of visible time (counted from when it began or the page last became
+ * visible, whichever is later; pass `visibleSince = now` while hidden); until
+ * then, whatever was shown before it (`null` = nothing yet). Anything else
+ * shows at once. */
+export function statusToShow(args) {
+    const { view, quiet, quietSince, visibleSince, lastShown, now } = args;
+    if (!quiet)
+        return view;
+    return now - quietGraceStart(quietSince, visibleSince, now) >= (args.graceMs ?? QUIET_TRANSITION_GRACE_MS) ? view : lastShown;
+}
+/** When the running grace period began (for scheduling a re-render at its end). */
+export function quietGraceStart(quietSince, visibleSince, now) {
+    return Math.max(quietSince ?? now, visibleSince);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steve31415/baselib",
-  "version": "3.20.1",
+  "version": "3.22.0",
   "description": "Plasticine new-world shared platform library: logging, auth, service-to-service auth, db, HTTP, sync, app updates",
   "type": "module",
   "license": "MIT",