@steve31415/baselib 3.20.0 → 3.21.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';
 } | {
@@ -34,6 +40,9 @@ export declare class BuildUpdateMonitor {
     private appliedRequestNumber;
     private trafficBuild;
     private checkFailure;
+    /** When the page last went from hidden to visible (not page load). */
+    private returnedAt;
+    private deferUntilHidden;
     constructor(deps: BuildUpdateDeps);
     getState: () => BuildUpdateState;
     subscribe: (listener: () => void) => (() => void);
@@ -49,6 +58,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,6 +2,12 @@
 // 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';
@@ -18,6 +24,9 @@ export class BuildUpdateMonitor {
     appliedRequestNumber = 0;
     trafficBuild = null;
     checkFailure = false;
+    /** When the page last went from hidden to visible (not page load). */
+    returnedAt = null;
+    deferUntilHidden = false;
     constructor(deps) {
         this.deps = deps;
     }
@@ -116,6 +125,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 +139,22 @@ 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()),
+                });
+            }
         }
         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 +162,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 +190,15 @@ export class BuildUpdateMonitor {
     }
     onVisibility = () => {
         if (document.visibilityState === 'visible') {
+            this.returnedAt = Date.now();
             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

@@ -127,7 +127,11 @@ export declare class SyncClient<B, C extends EventBody, S extends EventBody, Sum
     private readonly abortControllers;
     private readonly removeListeners;
     private currentState;
+    /** Failed attempts in the current visible spell: drives the ladder and the
+     * outage log's `attempts` (what the user could have waited through). */
     private reconnectAttempts;
+    /** Failed visible attempts across the whole outage (every spell). */
+    private totalAttempts;
     private reconnectTimer;
     private countdownTimer;
     private pingTimer;
@@ -216,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 {
@@ -47,7 +53,11 @@ export class SyncClient {
     abortControllers = new Set();
     removeListeners = [];
     currentState = { kind: 'starting', pending: 0 };
+    /** Failed attempts in the current visible spell: drives the ladder and the
+     * outage log's `attempts` (what the user could have waited through). */
     reconnectAttempts = 0;
+    /** Failed visible attempts across the whole outage (every spell). */
+    totalAttempts = 0;
     reconnectTimer = null;
     countdownTimer = null;
     pingTimer = null;
@@ -324,6 +334,10 @@ export class SyncClient {
             this.rearmFailureTimers();
             if (this.outageStartedAt !== null && !this.outageEscalated)
                 this.armEscalation();
+            // Each return starts the ladder afresh: failures from earlier glances
+            // (a phone shown for a second, often before its network is back) must
+            // not stretch this return's retry to 8-30 s or add up to a WARN.
+            this.reconnectAttempts = 0;
         }
         this.wakeConnection();
         // Always: a socket that looks open may be dead (review S2), and a
@@ -457,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;
             }
@@ -635,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),
         };
     }
@@ -657,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,
@@ -675,9 +698,37 @@ 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)
             void this.probeSession();
         let remaining = delay;
@@ -694,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)
@@ -1060,13 +1111,15 @@ export class SyncClient {
         if (this.outageStartedAt !== null) {
             const durationMs = Math.max(0, this.options.runtime.now() - this.outageStartedAt);
             // Failures are only counted (and the ladder only runs) while visible,
-            // so `attempts` is what the user could have waited through.
+            // and the count restarts on each return, so `attempts` is what the
+            // user could have waited through; `totalAttempts` spans every spell.
             const attempts = this.reconnectAttempts;
             const info = this.outageInfo;
             const delta = info ? SyncClient.delta(info.counters, this.snapshot()) : null;
             const fields = {
                 durationMs,
                 attempts,
+                totalAttempts: this.totalAttempts,
                 closeCode: info?.closeCode,
                 wasClean: info?.wasClean,
                 visibleAtDrop: info?.visibleAtDrop,
@@ -1100,6 +1153,7 @@ export class SyncClient {
             this.options.runtime.clearTimeout(this.escalateTimer);
         this.escalateTimer = null;
         this.reconnectAttempts = 0;
+        this.totalAttempts = 0;
         for (const [eventGuid, entry] of this.pending) {
             if (this.settledPending.has(eventGuid)) {
                 this.retrySettlement(eventGuid);

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.0",
+  "version": "3.21.0",
   "description": "Plasticine new-world shared platform library: logging, auth, service-to-service auth, db, HTTP, sync, app updates",
   "type": "module",
   "license": "MIT",