@steve31415/baselib 3.19.1 → 3.20.1

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

@@ -50,6 +50,11 @@ export declare class BuildUpdateMonitor {
     private markAvailable;
     private maybeReload;
     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
+     * sync client's pushes and background catch-ups. */
+    private startPolling;
+    private stopPolling;
     private onVisibility;
     private onOnline;
 }

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

@@ -32,10 +32,8 @@ export class BuildUpdateMonitor {
         this.started = true;
         this.lifecycle += 1;
         this.stopSafety = this.deps.safety.subscribe(() => this.maybeReload());
-        this.interval = setInterval(() => {
-            if (document.visibilityState === 'visible')
-                void this.checkNow();
-        }, this.deps.pollMs ?? DEFAULT_POLL_MS);
+        if (document.visibilityState === 'visible')
+            this.startPolling();
         document.addEventListener('visibilitychange', this.onVisibility);
         window.addEventListener('online', this.onOnline);
         void this.checkNow();
@@ -45,9 +43,7 @@ export class BuildUpdateMonitor {
             return;
         this.started = false;
         this.lifecycle += 1;
-        if (this.interval)
-            clearInterval(this.interval);
-        this.interval = null;
+        this.stopPolling();
         this.stopSafety?.();
         this.stopSafety = null;
         document.removeEventListener('visibilitychange', this.onVisibility);
@@ -151,9 +147,30 @@ export class BuildUpdateMonitor {
         for (const listener of this.listeners)
             listener();
     }
+    /** 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
+     * sync client's pushes and background catch-ups. */
+    startPolling() {
+        if (this.interval)
+            return;
+        this.interval = setInterval(() => {
+            if (document.visibilityState === 'visible')
+                void this.checkNow();
+        }, this.deps.pollMs ?? DEFAULT_POLL_MS);
+    }
+    stopPolling() {
+        if (this.interval)
+            clearInterval(this.interval);
+        this.interval = null;
+    }
     onVisibility = () => {
-        if (document.visibilityState === 'visible')
+        if (document.visibilityState === 'visible') {
+            this.startPolling();
             void this.checkNow();
+        }
+        else {
+            this.stopPolling();
+        }
     };
     onOnline = () => {
         void this.checkNow();

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

@@ -1,5 +1,5 @@
 import type { Logger as BrowserLogger } from '../log-browser.js';
-import type { ClientEvent, EventBody, SyncEvent } from '../sync/index.js';
+import type { ClientEvent, EventBody, HttpEventOutcome, SyncEvent } from '../sync/index.js';
 import type { IndexedDbOutbox } from './outbox.js';
 export interface PendingEntry<C extends EventBody, Summary = unknown> {
     event: ClientEvent<C>;
@@ -39,6 +39,10 @@ export interface SyncBrowserRuntime {
     onVisibilityChange(listener: () => void): () => void;
     onOnline(listener: () => void): () => void;
     onPageHide(listener: () => void): () => void;
+    /** Page Lifecycle `freeze` / `resume` on `document`; optional, counted
+     * for instrumentation only. */
+    onFreeze?(listener: () => void): () => void;
+    onResume?(listener: () => void): () => void;
     setTimeout: typeof globalThis.setTimeout;
     clearTimeout: typeof globalThis.clearTimeout;
     setInterval: typeof globalThis.setInterval;
@@ -95,6 +99,18 @@ export interface SyncClientOptions<B, C extends EventBody, S extends EventBody,
     onBuildChanged?(): void;
     markPerformance?(name: 'outbox-start' | 'outbox-ready' | 'bootstrap-start' | 'bootstrap-response' | 'store-ready'): void;
     reconnectBeforeMs?: number;
+    /** While hidden and disconnected, one HTTP catch-up per this interval
+     * (default 5 min). */
+    backgroundCatchupMs?: number;
+    /** POSTs events to the app's batch endpoint (the beacon URL) and returns
+     * the per-event outcomes. Lets a hidden, disconnected page deliver pending
+     * edits and learn about rejections; without it the page beacons once. */
+    postEvents?(body: {
+        clientGuid: string;
+        events: ClientEvent<C>[];
+    }, signal: AbortSignal): Promise<{
+        outcomes: HttpEventOutcome[];
+    }>;
 }
 export declare class SyncClient<B, C extends EventBody, S extends EventBody, Summary = unknown> {
     private readonly options;
@@ -111,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;
@@ -134,6 +154,23 @@ export declare class SyncClient<B, C extends EventBody, S extends EventBody, Sum
     private reconciliationTail;
     private initialization;
     private disposed;
+    private hiddenSince;
+    private hiddenSocketFailed;
+    private beaconedWhileDormant;
+    private backgroundTickTimer;
+    private lastTickAt;
+    private catchupSlot;
+    private readonly httpApplied;
+    private connectReplyTimer;
+    private socketCreatedHidden;
+    private socketOpenedAt;
+    private plannedClose;
+    private outageCloseCode;
+    private outageInfo;
+    private lastContactAt;
+    private spellCounters;
+    private returnWindow;
+    private readonly counters;
     constructor(options: SyncClientOptions<B, C, S, Summary>);
     init(): Promise<void>;
     private initialize;
@@ -154,15 +191,41 @@ export declare class SyncClient<B, C extends EventBody, S extends EventBody, Sum
     state(): SyncClientState;
     subscribe(listener: (state: SyncClientState) => void): () => void;
     private installRuntimeListeners;
+    private isHidden;
+    private now;
+    /** Counters with the running hidden spell's time folded in. */
+    private snapshot;
+    private static delta;
+    private onBecameHidden;
+    private onBecameVisible;
+    private onOnline;
     private wakeConnection;
     /** Drops the current socket, if any, without treating it as an outage, and
      * connects at once. */
     private replaceSocket;
     private connect;
+    /** Hidden and disconnected: no WebSocket retries; HTTP catch-ups on a slow
+     * cadence instead (docs/SYNC-BACKGROUND-PLAN.md). */
+    private enterDormant;
+    private cancelBackgroundTick;
+    private backgroundTick;
+    private unsettledPending;
+    private postPendingOverHttp;
+    /** The background/return catch-up (review S5): one slot, a return aborts
+     * a background fetch in flight, both give up after 15 s. */
+    private runCatchup;
+    private withTimeout;
+    private openReturnWindow;
+    private maybeFinishReturnWindow;
+    /** One INFO per hidden spell: what the user saw change on return. */
+    private finishReturnWindow;
     private connectNow;
     private scheduleReconnect;
     private probeSession;
     private startOutage;
+    /** ERROR only after OUTAGE_ESCALATE_MS of visible, on-time outage; re-armed
+     * on each return so an outage that began hidden still escalates (S3). */
+    private armEscalation;
     private handleMessage;
     private handleSocketCatchup;
     /** Returns false when a forward gap prevented application. */
@@ -174,6 +237,9 @@ export declare class SyncClient<B, C extends EventBody, S extends EventBody, Sum
     private finishConfirmation;
     private finishRejection;
     private reconcileStore;
+    private armFailureTimer;
+    /** On return: a verdict needs 60 s of visible time (review B2). */
+    private rearmFailureTimers;
     private failUnconfirmed;
     private onSyncEstablished;
     private requestReload;

package/dist/sync-browser/client.js

@@ -15,6 +15,12 @@ const GAP_BUFFER_MAX = 1_000;
 const RECONCILE_MOVED_MAX_REFETCHES = 3;
 const CLOSE_NO_USER = 4403;
 const PROBE_AFTER_ATTEMPTS = 2;
+const DEFAULT_BACKGROUND_CATCHUP_MS = 5 * 60 * 1000;
+const BACKGROUND_FETCH_TIMEOUT_MS = 15_000;
+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;
 const SOCKET_CONNECTING = 0;
 const SOCKET_OPEN = 1;
 class LifecycleAbort {
@@ -41,7 +47,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;
@@ -64,6 +74,32 @@ export class SyncClient {
     reconciliationTail = Promise.resolve();
     initialization = null;
     disposed = false;
+    // Hidden-page state (docs/SYNC-BACKGROUND-PLAN.md).
+    hiddenSince = null;
+    hiddenSocketFailed = false;
+    beaconedWhileDormant = false;
+    backgroundTickTimer = null;
+    lastTickAt = null;
+    catchupSlot = null;
+    httpApplied = new Set();
+    connectReplyTimer = null;
+    socketCreatedHidden = false;
+    socketOpenedAt = null;
+    plannedClose = null;
+    outageCloseCode = 1006;
+    outageInfo = null;
+    lastContactAt = null;
+    spellCounters = null;
+    returnWindow = null;
+    counters = {
+        hiddenMs: 0,
+        freezes: 0,
+        resumes: 0,
+        watchdogKills: 0,
+        backgroundCatchups: 0,
+        backgroundCatchupFailures: 0,
+        backgroundSocketAttempts: 0,
+    };
     constructor(options) {
         this.options = options;
     }
@@ -178,7 +214,7 @@ export class SyncClient {
         const entry = { ...persisted, status: 'pending' };
         this.pending.set(event.eventGuid, entry);
         this.options.store.applyOptimistic(event);
-        this.failureTimers.set(event.eventGuid, this.options.runtime.setTimeout(() => this.failUnconfirmed(event.eventGuid), FAILURE_TIMEOUT_MS));
+        this.armFailureTimer(event.eventGuid);
         this.trySend(entry);
         this.updatePendingState();
         this.options.onSafetyChange?.();
@@ -219,10 +255,100 @@ export class SyncClient {
         return () => this.subscribers.delete(listener);
     }
     installRuntimeListeners() {
-        this.removeListeners.push(this.options.runtime.onVisibilityChange(() => {
-            if (this.options.runtime.visibility() === 'visible')
-                this.wakeConnection();
-        }), this.options.runtime.onOnline(() => this.wakeConnection()), this.options.runtime.onPageHide(() => this.flushViaBeacon()));
+        const runtime = this.options.runtime;
+        // Loaded hidden (a background tab): the spell starts now; the first
+        // connect still runs, and its failure goes dormant rather than retrying.
+        if (runtime.visibility() === 'hidden') {
+            this.hiddenSince = this.now();
+            this.spellCounters = this.snapshot();
+        }
+        this.removeListeners.push(runtime.onVisibilityChange(() => {
+            if (runtime.visibility() === 'visible')
+                this.onBecameVisible();
+            else
+                this.onBecameHidden();
+        }), runtime.onOnline(() => this.onOnline()), runtime.onPageHide(() => this.flushViaBeacon()));
+        const onFreeze = runtime.onFreeze?.(() => this.counters.freezes++);
+        const onResume = runtime.onResume?.(() => this.counters.resumes++);
+        if (onFreeze)
+            this.removeListeners.push(onFreeze);
+        if (onResume)
+            this.removeListeners.push(onResume);
+    }
+    isHidden() {
+        return this.hiddenSince !== null;
+    }
+    now() {
+        return this.options.runtime.now();
+    }
+    /** Counters with the running hidden spell's time folded in. */
+    snapshot() {
+        const hiddenMs = this.counters.hiddenMs + (this.hiddenSince === null ? 0 : Math.max(0, this.now() - this.hiddenSince));
+        return { ...this.counters, hiddenMs };
+    }
+    static delta(since, now) {
+        return {
+            hiddenMs: Math.max(0, now.hiddenMs - since.hiddenMs),
+            freezes: now.freezes - since.freezes,
+            resumes: now.resumes - since.resumes,
+            watchdogKills: now.watchdogKills - since.watchdogKills,
+            backgroundCatchups: now.backgroundCatchups - since.backgroundCatchups,
+            backgroundCatchupFailures: now.backgroundCatchupFailures - since.backgroundCatchupFailures,
+            backgroundSocketAttempts: now.backgroundSocketAttempts - since.backgroundSocketAttempts,
+        };
+    }
+    onBecameHidden() {
+        if (this.halted || this.disposed || this.hiddenSince !== null)
+            return;
+        this.finishReturnWindow();
+        this.hiddenSince = this.now();
+        this.spellCounters = this.snapshot();
+        this.hiddenSocketFailed = false;
+        this.beaconedWhileDormant = false;
+        if (this.connectReplyTimer !== null)
+            this.options.runtime.clearTimeout(this.connectReplyTimer);
+        this.connectReplyTimer = null;
+        // A ladder waiting to retry is cancelled: no reconnects while hidden.
+        if (this.socket === null)
+            this.enterDormant();
+    }
+    onBecameVisible() {
+        if (this.halted || this.disposed)
+            return;
+        const hiddenSince = this.hiddenSince;
+        if (hiddenSince !== null) {
+            const hiddenMs = Math.max(0, this.now() - hiddenSince);
+            const spell = this.spellCounters ?? this.snapshot();
+            this.counters.hiddenMs += hiddenMs;
+            this.hiddenSince = null;
+            this.spellCounters = null;
+            this.cancelBackgroundTick();
+            this.httpApplied.clear();
+            this.openReturnWindow(hiddenMs, spell);
+            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
+        // handshake may be slow. One HTTP round trip makes the page current.
+        void this.runCatchup('return');
+    }
+    onOnline() {
+        if (this.halted || this.disposed)
+            return;
+        if (this.isHidden()) {
+            if (this.socket === null) {
+                this.cancelBackgroundTick();
+                void this.backgroundTick();
+            }
+            return;
+        }
+        this.wakeConnection();
     }
     wakeConnection() {
         if (this.halted || this.disposed)
@@ -230,6 +356,15 @@ export class SyncClient {
         const socket = this.socket;
         if (socket?.readyState === SOCKET_OPEN) {
             this.sendConnect();
+            // A socket that looks open may be half-dead: no catch-up reply in 5 s
+            // replaces it.
+            if (this.connectReplyTimer !== null)
+                this.options.runtime.clearTimeout(this.connectReplyTimer);
+            this.connectReplyTimer = this.options.runtime.setTimeout(() => {
+                this.connectReplyTimer = null;
+                if (this.socket === socket && !this.isHidden())
+                    this.replaceSocket();
+            }, WAKE_CONNECT_REPLY_MS);
             return;
         }
         // A handshake still inside its watchdog window may just be slow: leave
@@ -269,14 +404,23 @@ export class SyncClient {
         catch (error) {
             this.options.logger.warn('socket creation failed', { error });
             this.startOutage(1006);
-            this.scheduleReconnect();
+            if (this.isHidden())
+                this.enterDormant();
+            else
+                this.scheduleReconnect();
             return;
         }
         this.socket = socket;
         this.socketCreatedAt = this.options.runtime.now();
+        this.socketCreatedHidden = this.isHidden();
+        this.socketOpenedAt = null;
+        if (this.socketCreatedHidden)
+            this.counters.backgroundSocketAttempts++;
         this.watchdogTimer = this.options.runtime.setTimeout(() => {
-            if (socket.readyState !== SOCKET_OPEN)
+            if (socket.readyState !== SOCKET_OPEN) {
+                this.counters.watchdogKills++;
                 socket.close();
+            }
         }, CONNECT_WATCHDOG_MS);
         socket.onopen = () => {
             if (this.socket !== socket) {
@@ -286,16 +430,21 @@ export class SyncClient {
             if (this.watchdogTimer !== null)
                 this.options.runtime.clearTimeout(this.watchdogTimer);
             this.watchdogTimer = null;
+            this.socketOpenedAt = this.now();
+            this.cancelBackgroundTick();
             this.sendConnect();
             this.pingTimer = this.options.runtime.setInterval(() => this.sendRaw({ type: 'ping' }), PING_INTERVAL_MS);
             this.rolloverTimer = this.options.runtime.setTimeout(() => {
                 this.options.logger.info('ws rollover', {});
+                this.plannedClose = socket;
                 socket.close();
             }, this.options.reconnectBeforeMs ?? DEFAULT_RECONNECT_BEFORE_MS);
         };
         socket.onmessage = (event) => {
-            if (this.socket === socket)
-                this.handleMessage(String(event.data));
+            if (this.socket !== socket)
+                return;
+            this.lastContactAt = this.now();
+            this.handleMessage(String(event.data));
         };
         socket.onerror = () => {
             // Browsers expose no useful detail; the close event owns recovery.
@@ -312,10 +461,219 @@ export class SyncClient {
                 this.halt();
                 return;
             }
-            this.startOutage(event.code);
-            this.scheduleReconnect();
+            const planned = this.plannedClose === socket;
+            this.plannedClose = null;
+            this.startOutage(event.code, event.wasClean === true);
+            if (!this.isHidden()) {
+                this.scheduleReconnect();
+                return;
+            }
+            if (planned) {
+                // Our own rollover: this spell's sockets have lasted; reconnect once.
+                this.connectNow();
+                return;
+            }
+            const openedAt = this.socketOpenedAt;
+            if (this.socketCreatedHidden && (openedAt === null || this.now() - openedAt < HIDDEN_SOCKET_MIN_LIFE_MS)) {
+                this.hiddenSocketFailed = true;
+            }
+            this.enterDormant();
+        };
+    }
+    /** Hidden and disconnected: no WebSocket retries; HTTP catch-ups on a slow
+     * cadence instead (docs/SYNC-BACKGROUND-PLAN.md). */
+    enterDormant() {
+        if (this.halted || this.disposed)
+            return;
+        if (this.reconnectTimer !== null)
+            this.options.runtime.clearTimeout(this.reconnectTimer);
+        if (this.countdownTimer !== null)
+            this.options.runtime.clearInterval(this.countdownTimer);
+        this.reconnectTimer = null;
+        this.countdownTimer = null;
+        this.publish({ kind: 'disconnected', pending: this.pendingCount() });
+        if (!this.options.postEvents && !this.beaconedWhileDormant && this.unsettledPending().length > 0) {
+            this.beaconedWhileDormant = true;
+            this.flushViaBeacon();
+        }
+        if (this.backgroundTickTimer !== null)
+            return;
+        const interval = this.options.backgroundCatchupMs ?? DEFAULT_BACKGROUND_CATCHUP_MS;
+        const due = this.lastTickAt === null ? 0 : Math.max(0, this.lastTickAt + interval - this.now());
+        this.backgroundTickTimer = this.options.runtime.setTimeout(() => {
+            this.backgroundTickTimer = null;
+            void this.backgroundTick();
+        }, Math.min(due, interval));
+    }
+    cancelBackgroundTick() {
+        if (this.backgroundTickTimer !== null)
+            this.options.runtime.clearTimeout(this.backgroundTickTimer);
+        this.backgroundTickTimer = null;
+    }
+    async backgroundTick() {
+        if (this.halted || this.disposed || !this.isHidden() || this.socket !== null)
+            return;
+        this.lastTickAt = this.now();
+        await this.postPendingOverHttp();
+        const ok = await this.runCatchup('background');
+        if (this.halted || this.disposed || !this.isHidden() || this.socket !== null)
+            return;
+        if (ok && !this.hiddenSocketFailed) {
+            // Desktop hidden sockets usually live; one attempt per tick, none after
+            // the first hidden failure in this spell (phones cut them in seconds).
+            this.connectNow();
+            return;
+        }
+        this.enterDormant();
+    }
+    unsettledPending() {
+        return [...this.pending.values()].filter((entry) => !this.settledPending.has(entry.event.eventGuid));
+    }
+    async postPendingOverHttp() {
+        const postEvents = this.options.postEvents;
+        if (!postEvents)
+            return;
+        const events = this.unsettledPending()
+            .filter((entry) => !this.httpApplied.has(entry.event.eventGuid))
+            .map((entry) => entry.event);
+        if (events.length === 0)
+            return;
+        try {
+            const { outcomes } = await this.withTimeout((signal) => postEvents({ clientGuid: this.options.clientGuid, events }, signal));
+            if (this.stopBeforeStoreMutation())
+                return;
+            for (const outcome of outcomes) {
+                if (outcome.status === 'rejected') {
+                    this.handleRejection({
+                        type: 'rejection',
+                        eventGuid: outcome.eventGuid,
+                        error: outcome.error ?? { code: 'rejected', message: 'rejected' },
+                    });
+                }
+                else {
+                    // Applied (or a duplicate): the catch-up's echo confirms it.
+                    this.httpApplied.add(outcome.eventGuid);
+                }
+            }
+        }
+        catch {
+            // Offline or timed out: the next tick, or the socket on return, retries.
+        }
+    }
+    /** The background/return catch-up (review S5): one slot, a return aborts
+     * a background fetch in flight, both give up after 15 s. */
+    async runCatchup(kind) {
+        if (this.halted || this.disposed)
+            return false;
+        if (this.catchupSlot !== null) {
+            if (kind === 'return' && this.catchupSlot.kind === 'background')
+                this.catchupSlot.controller.abort();
+            else
+                return false;
+        }
+        const controller = new AbortController();
+        const slot = { kind, controller };
+        this.catchupSlot = slot;
+        this.abortControllers.add(controller);
+        const timeout = this.options.runtime.setTimeout(() => controller.abort(), BACKGROUND_FETCH_TIMEOUT_MS);
+        let ok = false;
+        try {
+            const result = await this.options.fetchCatchup(this.options.store.currentSeq(), controller.signal);
+            if (controller.signal.aborted || this.stopBeforeStoreMutation())
+                return false;
+            ok = true;
+            this.lastContactAt = this.now();
+            if (result.buildId)
+                this.options.onBuildObserved?.(result.buildId);
+            else if (kind === 'background')
+                this.options.onBuildChanged?.();
+            if (result.reload) {
+                this.requestReload('server');
+            }
+            else {
+                for (const event of result.events)
+                    this.handleServerEvent(event);
+            }
+            return true;
+        }
+        catch {
+            return false;
+        }
+        finally {
+            this.options.runtime.clearTimeout(timeout);
+            this.abortControllers.delete(controller);
+            if (this.catchupSlot === slot)
+                this.catchupSlot = null;
+            if (kind === 'background') {
+                if (ok)
+                    this.counters.backgroundCatchups++;
+                else
+                    this.counters.backgroundCatchupFailures++;
+            }
+            if (kind === 'return' && this.returnWindow !== null) {
+                this.returnWindow.catchupDone = true;
+                this.returnWindow.catchupOk = ok;
+                this.maybeFinishReturnWindow();
+            }
+        }
+    }
+    async withTimeout(operation) {
+        const controller = new AbortController();
+        this.abortControllers.add(controller);
+        const timeout = this.options.runtime.setTimeout(() => controller.abort(), BACKGROUND_FETCH_TIMEOUT_MS);
+        try {
+            return await operation(controller.signal);
+        }
+        finally {
+            this.options.runtime.clearTimeout(timeout);
+            this.abortControllers.delete(controller);
+        }
+    }
+    openReturnWindow(hiddenMs, spell) {
+        this.finishReturnWindow();
+        const now = this.now();
+        this.returnWindow = {
+            visibleAt: now,
+            hiddenMs,
+            socketOpenAtReturn: this.socket?.readyState === SOCKET_OPEN,
+            sinceLastContactMs: this.lastContactAt === null ? null : Math.max(0, now - this.lastContactAt),
+            spell: SyncClient.delta(spell, this.snapshot()),
+            establishedAt: null,
+            catchupDone: false,
+            catchupOk: false,
+            eventsOnReturn: 0,
+            resyncOnReturn: 0,
+            timer: this.options.runtime.setTimeout(() => this.finishReturnWindow(), RETURN_REPORT_TIMEOUT_MS),
         };
     }
+    maybeFinishReturnWindow() {
+        const window = this.returnWindow;
+        if (window !== null && window.establishedAt !== null && window.catchupDone)
+            this.finishReturnWindow();
+    }
+    /** One INFO per hidden spell: what the user saw change on return. */
+    finishReturnWindow() {
+        const window = this.returnWindow;
+        if (window === null)
+            return;
+        this.returnWindow = null;
+        this.options.runtime.clearTimeout(window.timer);
+        this.options.logger.info('page returned to foreground', {
+            hiddenMs: window.hiddenMs,
+            socketOpenAtReturn: window.socketOpenAtReturn,
+            reconnectMs: window.establishedAt === null ? null : Math.max(0, window.establishedAt - window.visibleAt),
+            catchupOk: window.catchupOk,
+            eventsOnReturn: window.eventsOnReturn,
+            resyncOnReturn: window.resyncOnReturn,
+            sinceLastContactMs: window.sinceLastContactMs,
+            backgroundCatchups: window.spell.backgroundCatchups,
+            backgroundCatchupFailures: window.spell.backgroundCatchupFailures,
+            backgroundSocketAttempts: window.spell.backgroundSocketAttempts,
+            watchdogKills: window.spell.watchdogKills,
+            freezes: window.spell.freezes,
+            resumes: window.spell.resumes,
+        });
+    }
     connectNow() {
         if (this.reconnectTimer !== null)
             this.options.runtime.clearTimeout(this.reconnectTimer);
@@ -328,6 +686,7 @@ export class SyncClient {
     scheduleReconnect() {
         const delay = RECONNECT_DELAYS_SECONDS[Math.min(this.reconnectAttempts, RECONNECT_DELAYS_SECONDS.length - 1)];
         this.reconnectAttempts++;
+        this.totalAttempts++;
         if (this.reconnectAttempts >= PROBE_AFTER_ATTEMPTS)
             void this.probeSession();
         let remaining = delay;
@@ -371,13 +730,23 @@ export class SyncClient {
             this.probeInFlight = false;
         }
     }
-    startOutage(closeCode) {
+    startOutage(closeCode, wasClean = false) {
         if (this.outageStartedAt !== null)
             return;
         this.outageStartedAt = this.options.runtime.now();
         this.outageEscalated = false;
+        this.outageCloseCode = closeCode;
+        this.outageInfo = { closeCode, wasClean, visibleAtDrop: !this.isHidden(), counters: this.snapshot() };
+        this.armEscalation();
+    }
+    /** ERROR only after OUTAGE_ESCALATE_MS of visible, on-time outage; re-armed
+     * on each return so an outage that began hidden still escalates (S3). */
+    armEscalation() {
+        if (this.escalateTimer !== null)
+            this.options.runtime.clearTimeout(this.escalateTimer);
         this.escalateArmedAt = this.options.runtime.now();
         this.escalateTimer = this.options.runtime.setTimeout(() => {
+            this.escalateTimer = null;
             const late = this.options.runtime.now() - this.escalateArmedAt - OUTAGE_ESCALATE_MS;
             if (this.options.runtime.visibility() === 'hidden' || late > 5000)
                 return;
@@ -385,7 +754,7 @@ export class SyncClient {
                 this.outageEscalated = true;
                 this.options.logger.error('sync outage ongoing', {
                     durationMs: this.options.runtime.now() - this.outageStartedAt,
-                    closeCode,
+                    closeCode: this.outageCloseCode,
                     attempts: this.reconnectAttempts,
                 });
             }
@@ -415,6 +784,9 @@ export class SyncClient {
                 this.handleSocketCatchup(message);
                 return;
             case 'reload':
+                if (this.connectReplyTimer !== null)
+                    this.options.runtime.clearTimeout(this.connectReplyTimer);
+                this.connectReplyTimer = null;
                 this.requestReload('server');
                 return;
             case 'event':
@@ -426,6 +798,9 @@ export class SyncClient {
         }
     }
     handleSocketCatchup(message) {
+        if (this.connectReplyTimer !== null)
+            this.options.runtime.clearTimeout(this.connectReplyTimer);
+        this.connectReplyTimer = null;
         if (message.buildId)
             this.options.onBuildObserved?.(message.buildId);
         let complete = true;
@@ -446,8 +821,12 @@ export class SyncClient {
             return false;
         const currentSeq = this.options.store.currentSeq();
         if (event.seq <= currentSeq) {
-            if (this.pending.has(event.eventGuid))
+            // A second echo of an already-confirmed edit (socket and HTTP catch-up
+            // both deliver it on return) must not upgrade the settlement to a full
+            // reconcile (review S4).
+            if (this.pending.has(event.eventGuid) && !this.confirmedPending.has(event.eventGuid)) {
                 this.confirmPending(event.eventGuid, true);
+            }
             return true;
         }
         if (event.seq > currentSeq + 1) {
@@ -470,6 +849,8 @@ export class SyncClient {
             return false;
         }
         this.options.store.applyServerEvent(event);
+        if (this.returnWindow !== null && !this.pending.has(event.eventGuid))
+            this.returnWindow.eventsOnReturn++;
         if (this.stopBeforeStoreMutation())
             return false;
         this.options.store.setCurrentSeq(event.seq);
@@ -641,6 +1022,8 @@ export class SyncClient {
                     return true;
                 }
                 this.options.store.installBootstrap(bootstrap);
+                if (this.returnWindow !== null)
+                    this.returnWindow.resyncOnReturn++;
                 for (const [eventGuid, entry] of this.pending) {
                     if (this.settledPending.has(eventGuid))
                         continue;
@@ -655,7 +1038,24 @@ export class SyncClient {
             release();
         }
     }
+    armFailureTimer(eventGuid) {
+        this.clearFailureTimer(eventGuid);
+        this.failureTimers.set(eventGuid, this.options.runtime.setTimeout(() => this.failUnconfirmed(eventGuid), FAILURE_TIMEOUT_MS));
+    }
+    /** On return: a verdict needs 60 s of visible time (review B2). */
+    rearmFailureTimers() {
+        for (const [eventGuid, entry] of this.pending) {
+            if (entry.recovered || this.settledPending.has(eventGuid) || this.unresolvedFailures.has(eventGuid))
+                continue;
+            this.armFailureTimer(eventGuid);
+        }
+    }
     failUnconfirmed(eventGuid) {
+        this.failureTimers.delete(eventGuid);
+        // Hidden: no verdict and no re-arm (that would wake the page every
+        // minute); the return re-arms a full 60 s.
+        if (this.isHidden())
+            return;
         const entry = this.pending.get(eventGuid);
         if (!entry || entry.recovered)
             return;
@@ -667,24 +1067,51 @@ export class SyncClient {
     }
     onSyncEstablished() {
         if (this.outageStartedAt !== null) {
-            const durationMs = this.options.runtime.now() - this.outageStartedAt;
+            const durationMs = Math.max(0, this.options.runtime.now() - this.outageStartedAt);
+            // Failures are only counted (and the ladder only runs) while visible,
+            // 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,
+                hiddenMs: delta?.hiddenMs,
+                watchdogKills: delta?.watchdogKills,
+                backgroundCatchups: delta?.backgroundCatchups,
+                freezes: delta?.freezes,
+                resumes: delta?.resumes,
+            };
             if (this.outageEscalated) {
-                this.options.logger.info('sync outage recovered', { durationMs, attempts });
+                this.options.logger.info('sync outage recovered', fields);
             }
             else if (attempts >= 2) {
-                this.options.logger.warn('sync outage recovered', { durationMs, attempts });
+                this.options.logger.warn('sync outage recovered', fields);
             }
             else if (attempts === 1) {
-                this.options.logger.info('ws reconnected first try', { durationMs });
+                this.options.logger.info('ws reconnected first try', fields);
+            }
+            else {
+                this.options.logger.info('background sync outage recovered', fields);
             }
             this.outageStartedAt = null;
             this.outageEscalated = false;
+            this.outageInfo = null;
+        }
+        if (this.returnWindow !== null && this.returnWindow.establishedAt === null) {
+            this.returnWindow.establishedAt = this.now();
+            this.maybeFinishReturnWindow();
         }
         if (this.escalateTimer !== null)
             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);
@@ -900,6 +1327,9 @@ export class SyncClient {
         this.publish({ kind: 'expired', pending: this.pendingCount() });
     }
     clearConnectionTimers() {
+        if (this.connectReplyTimer !== null)
+            this.options.runtime.clearTimeout(this.connectReplyTimer);
+        this.connectReplyTimer = null;
         if (this.pingTimer !== null)
             this.options.runtime.clearInterval(this.pingTimer);
         if (this.watchdogTimer !== null)
@@ -922,6 +1352,10 @@ export class SyncClient {
             this.options.runtime.clearTimeout(this.resyncBackoffTimer);
         for (const timer of this.failureTimers.values())
             this.options.runtime.clearTimeout(timer);
+        this.cancelBackgroundTick();
+        if (this.returnWindow !== null)
+            this.options.runtime.clearTimeout(this.returnWindow.timer);
+        this.returnWindow = null;
         this.reconnectTimer = null;
         this.countdownTimer = null;
         this.escalateTimer = null;

package/package.json

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