@steve31415/baselib 3.31.0 → 3.33.0

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

@@ -65,10 +65,17 @@ export declare class BuildUpdateMonitor {
     /** Deployment push is intentionally only a prompt to ask canonical HTTP;
      *  it carries no traffic authority of its own and runs while hidden too. */
     observeDeploymentHint(): void;
+    /** Asks canonical HTTP for the traffic build. Nothing to ask once the page
+     * is reloading: the navigation aborts the request, so a check then can only
+     * log a false failure (digest, 2026-10-06: a page hidden and shown within
+     * 0.4 s ran its deferred reload on the hide and this check on the show). */
     checkNow(): Promise<void>;
     private observeTrafficBuild;
     private markAvailable;
     private maybeReload;
+    /** A method, not an inline test: TypeScript would keep the narrowing from
+     * checkNow's entry across its await. */
+    private isReloading;
     private justReturned;
     private setState;
     /** Polls only while visible: an interval in a hidden page would wake it

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

@@ -91,8 +91,12 @@ export class BuildUpdateMonitor {
     observeDeploymentHint() {
         void this.checkNow();
     }
+    /** Asks canonical HTTP for the traffic build. Nothing to ask once the page
+     * is reloading: the navigation aborts the request, so a check then can only
+     * log a false failure (digest, 2026-10-06: a page hidden and shown within
+     * 0.4 s ran its deferred reload on the hide and this check on the show). */
     async checkNow() {
-        if (!navigator.onLine)
+        if (!navigator.onLine || this.isReloading())
             return;
         const lifecycle = this.lifecycle;
         const requestNumber = ++this.requestNumber;
@@ -130,7 +134,8 @@ export class BuildUpdateMonitor {
         catch (error) {
             if (lifecycle !== this.lifecycle ||
                 requestNumber < this.appliedRequestNumber ||
-                !navigator.onLine)
+                !navigator.onLine ||
+                this.isReloading())
                 return;
             if (!this.checkFailure) {
                 this.checkFailure = true;
@@ -185,6 +190,11 @@ export class BuildUpdateMonitor {
         else
             location.reload();
     }
+    /** A method, not an inline test: TypeScript would keep the narrowing from
+     * checkNow's entry across its await. */
+    isReloading() {
+        return this.state.kind === 'reloading';
+    }
     justReturned() {
         return (document.visibilityState === 'visible' &&
             this.returnedAt !== null &&

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

@@ -32,6 +32,9 @@ export interface CatchupResult<S extends EventBody> {
 }
 export interface SyncBrowserRuntime {
     now(): number;
+    /** A monotonic clock (`performance.now()`), used only to tell a page that
+     * was not running from one that was. Defaults to `performance.now()`. */
+    monotonicNow?(): number;
     randomGuid(): string;
     createSocket(url: string): WebSocket;
     sendBeacon(url: string, body: Blob): boolean;
@@ -154,6 +157,8 @@ export declare class SyncClient<B, C extends EventBody, S extends EventBody, Sum
     private loopEscalated;
     private reconciliationTail;
     private initialization;
+    /** Non-null while the first bootstrap is loading, retries included. */
+    private firstLoadRetry;
     private disposed;
     private hiddenSince;
     private hiddenSocketFailed;
@@ -171,10 +176,21 @@ export declare class SyncClient<B, C extends EventBody, S extends EventBody, Sum
     private lastContactAt;
     private spellCounters;
     private returnWindow;
+    private clockOffset;
+    private stallCoveredUntil;
+    private visibleSinceMono;
     private readonly counters;
     constructor(options: SyncClientOptions<B, C, S, Summary>);
     init(): Promise<void>;
     private initialize;
+    /** The first bootstrap. One that gets no HTTP answer (fetch's TypeError: no
+     * network, or one that reaches nothing — a tab Android Chrome restored from
+     * its cache) is retried until it loads, while init() stays pending and the
+     * state says `disconnected`; any other failure rejects, as it always did
+     * (docs/SYNC-INIT-RECOVERY-PLAN.md). Rejects with a LifecycleAbort once
+     * halted, disposed, or abandoned by a failed outbox. */
+    private loadFirstBootstrap;
+    private createFirstLoadRetry;
     dispose(): void;
     submit(event: ClientEvent<C>, summary: Summary): Promise<void>;
     /** Current-tab entries only; recovered work is retried silently. */
@@ -192,6 +208,17 @@ export declare class SyncClient<B, C extends EventBody, S extends EventBody, Sum
     state(): SyncClientState;
     subscribe(listener: (state: SyncClientState) => void): () => void;
     private installRuntimeListeners;
+    private monoNow;
+    private rebaselineClocks;
+    /** Runs first in every client timer. A device asleep stops the monotonic
+     * clock and the timers with it, so the wall clock's lead over it grows by
+     * the sleep; a frozen page leaves both clocks running and its timers run
+     * late by the monotonic one. Overlapping late timers count once. Only time
+     * the page counted as visible is counted (hidden pages are throttled by
+     * design and their time is `hiddenMs`). */
+    private observeStall;
+    private setTimer;
+    private setRepeating;
     private isHidden;
     private now;
     /** Counters with the running hidden spell's time folded in. */

package/dist/sync-browser/client.js

@@ -1,3 +1,4 @@
+import { FirstLoadRetry } from './first-load-retry.js';
 const RECONNECT_DELAYS_SECONDS = [1, 2, 4, 8, 16, 30];
 const PING_INTERVAL_MS = 30_000;
 const CONNECT_WATCHDOG_MS = 10_000;
@@ -35,6 +36,9 @@ const RETURN_QUICK_RETRY_MS = 250;
  * resolves (notes, 2026-10-01: four minutes). Fast failures (offline) are
  * not logged. */
 const SLOW_HANDSHAKE_MS = 3_000;
+/** A timer that runs at least this late, or a wall-clock jump of at least
+ * this much past the monotonic clock, counts as time the page was stalled. */
+const STALL_MIN_MS = 1_000;
 const SOCKET_CONNECTING = 0;
 const SOCKET_OPEN = 1;
 class LifecycleAbort {
@@ -88,6 +92,8 @@ export class SyncClient {
     loopEscalated = false;
     reconciliationTail = Promise.resolve();
     initialization = null;
+    /** Non-null while the first bootstrap is loading, retries included. */
+    firstLoadRetry = null;
     disposed = false;
     // Hidden-page state (docs/SYNC-BACKGROUND-PLAN.md).
     hiddenSince = null;
@@ -106,8 +112,13 @@ export class SyncClient {
     lastContactAt = null;
     spellCounters = null;
     returnWindow = null;
+    // Stall accounting (Counters.stalledMs).
+    clockOffset = null;
+    stallCoveredUntil = 0;
+    visibleSinceMono = 0;
     counters = {
         hiddenMs: 0,
+        stalledMs: 0,
         freezes: 0,
         resumes: 0,
         watchdogKills: 0,
@@ -150,16 +161,7 @@ export class SyncClient {
             throw error;
         });
         this.options.markPerformance?.('bootstrap-start');
-        const bootstrapPromise = this.abortable((signal) => this.options.fetchBootstrap(signal))
-            .then((bootstrap) => {
-            this.options.markPerformance?.('bootstrap-response');
-            return bootstrap;
-        })
-            .catch((error) => {
-            if (!isLifecycleAbort(error))
-                this.options.logger.error('bootstrap failed', { error });
-            throw error;
-        });
+        const bootstrapPromise = this.loadFirstBootstrap();
         let recovered;
         let bootstrap;
         try {
@@ -169,6 +171,10 @@ export class SyncClient {
         }
         catch (error) {
             this.abortFetches();
+            this.firstLoadRetry?.stop();
+            // A halt or dispose is a deliberate stop, not a failed load.
+            if (this.halted || this.disposed)
+                return;
             throw isLifecycleAbort(error) ? error.reason : error;
         }
         if (this.stopBeforeStoreMutation())
@@ -194,11 +200,77 @@ export class SyncClient {
         this.installRuntimeListeners();
         this.connect();
     }
+    /** The first bootstrap. One that gets no HTTP answer (fetch's TypeError: no
+     * network, or one that reaches nothing — a tab Android Chrome restored from
+     * its cache) is retried until it loads, while init() stays pending and the
+     * state says `disconnected`; any other failure rejects, as it always did
+     * (docs/SYNC-INIT-RECOVERY-PLAN.md). Rejects with a LifecycleAbort once
+     * halted, disposed, or abandoned by a failed outbox. */
+    async loadFirstBootstrap() {
+        const retry = this.createFirstLoadRetry();
+        this.firstLoadRetry = retry;
+        try {
+            for (;;) {
+                const controller = new AbortController();
+                this.abortControllers.add(controller);
+                retry.attemptStarted(() => controller.abort());
+                try {
+                    const bootstrap = await this.options.fetchBootstrap(controller.signal);
+                    retry.attemptEnded('loaded');
+                    this.options.markPerformance?.('bootstrap-response');
+                    retry.recovered();
+                    return bootstrap;
+                }
+                catch (error) {
+                    retry.attemptEnded('failed');
+                    if (this.halted || this.disposed || retry.stopped)
+                        throw new LifecycleAbort(error);
+                    // An abort here is the retry replacing a stale attempt: no answer.
+                    if (!controller.signal.aborted && !(error instanceof TypeError)) {
+                        this.options.logger.error('bootstrap failed', { reachedServer: true, failures: retry.failures, error });
+                        this.publish({ kind: 'error', pending: this.pendingCount(), message: 'Failed to load' });
+                        throw error;
+                    }
+                    retry.failed(error);
+                    if (retry.failures === 1)
+                        this.publish({ kind: 'disconnected', pending: this.pendingCount() });
+                }
+                finally {
+                    this.abortControllers.delete(controller);
+                }
+                const proceed = await retry.next();
+                if (!proceed || this.stopBeforeStoreMutation())
+                    throw new LifecycleAbort('first load stopped');
+            }
+        }
+        finally {
+            retry.stop();
+            if (this.firstLoadRetry === retry)
+                this.firstLoadRetry = null;
+        }
+    }
+    createFirstLoadRetry() {
+        const runtime = this.options.runtime;
+        return new FirstLoadRetry({
+            now: () => this.now(),
+            visible: () => runtime.visibility() !== 'hidden',
+            setTimer: (callback, delayMs) => this.setTimer(callback, delayMs),
+            clearTimer: (timer) => runtime.clearTimeout(timer),
+            onOnline: (listener) => runtime.onOnline(listener),
+            onVisibilityChange: (listener) => runtime.onVisibilityChange(listener),
+            logger: this.options.logger,
+            visibleDelaysMs: RECONNECT_DELAYS_SECONDS.map((seconds) => seconds * 1000),
+            hiddenDelayMs: this.options.backgroundCatchupMs ?? DEFAULT_BACKGROUND_CATCHUP_MS,
+            escalateAfterMs: OUTAGE_ESCALATE_MS,
+            staleAttemptMs: CONNECT_WATCHDOG_MS,
+        });
+    }
     dispose() {
         if (this.disposed)
             return;
         this.disposed = true;
         this.abortFetches();
+        this.firstLoadRetry?.stop();
         for (const remove of this.removeListeners.splice(0))
             remove();
         this.clearAllTimers();
@@ -277,6 +349,7 @@ export class SyncClient {
     }
     installRuntimeListeners() {
         const runtime = this.options.runtime;
+        this.rebaselineClocks();
         // 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') {
@@ -296,6 +369,48 @@ export class SyncClient {
         if (onResume)
             this.removeListeners.push(onResume);
     }
+    monoNow() {
+        return this.options.runtime.monotonicNow?.() ?? performance.now();
+    }
+    rebaselineClocks() {
+        this.clockOffset = this.now() - this.monoNow();
+    }
+    /** Runs first in every client timer. A device asleep stops the monotonic
+     * clock and the timers with it, so the wall clock's lead over it grows by
+     * the sleep; a frozen page leaves both clocks running and its timers run
+     * late by the monotonic one. Overlapping late timers count once. Only time
+     * the page counted as visible is counted (hidden pages are throttled by
+     * design and their time is `hiddenMs`). */
+    observeStall(dueMono) {
+        const mono = this.monoNow();
+        const offset = this.now() - mono;
+        const visible = !this.isHidden();
+        if (visible && this.clockOffset !== null && offset - this.clockOffset >= STALL_MIN_MS) {
+            this.counters.stalledMs += offset - this.clockOffset;
+        }
+        this.clockOffset = offset;
+        if (visible && mono - dueMono >= STALL_MIN_MS) {
+            const from = Math.max(dueMono, this.stallCoveredUntil, this.visibleSinceMono);
+            if (mono > from)
+                this.counters.stalledMs += mono - from;
+            this.stallCoveredUntil = mono;
+        }
+    }
+    setTimer(callback, delayMs) {
+        const dueMono = this.monoNow() + delayMs;
+        return this.options.runtime.setTimeout(() => {
+            this.observeStall(dueMono);
+            callback();
+        }, delayMs);
+    }
+    setRepeating(callback, periodMs) {
+        let dueMono = this.monoNow() + periodMs;
+        return this.options.runtime.setInterval(() => {
+            this.observeStall(dueMono);
+            dueMono = this.monoNow() + periodMs;
+            callback();
+        }, periodMs);
+    }
     isHidden() {
         return this.hiddenSince !== null;
     }
@@ -310,6 +425,7 @@ export class SyncClient {
     static delta(since, now) {
         return {
             hiddenMs: Math.max(0, now.hiddenMs - since.hiddenMs),
+            stalledMs: now.stalledMs - since.stalledMs,
             freezes: now.freezes - since.freezes,
             resumes: now.resumes - since.resumes,
             watchdogKills: now.watchdogKills - since.watchdogKills,
@@ -323,6 +439,8 @@ export class SyncClient {
         if (this.halted || this.disposed || this.hiddenSince !== null)
             return;
         this.finishReturnWindow();
+        // A device that slept and then hid the page: the sleep counts as hidden.
+        this.rebaselineClocks();
         this.hiddenSince = this.now();
         this.spellCounters = this.snapshot();
         this.hiddenSocketFailed = false;
@@ -339,6 +457,8 @@ export class SyncClient {
             return;
         const hiddenSince = this.hiddenSince;
         if (hiddenSince !== null) {
+            this.rebaselineClocks();
+            this.visibleSinceMono = this.monoNow();
             const hiddenMs = Math.max(0, this.now() - hiddenSince);
             const spell = this.spellCounters ?? this.snapshot();
             this.counters.hiddenMs += hiddenMs;
@@ -382,7 +502,7 @@ export class SyncClient {
             // replaces it.
             if (this.connectReplyTimer !== null)
                 this.options.runtime.clearTimeout(this.connectReplyTimer);
-            this.connectReplyTimer = this.options.runtime.setTimeout(() => {
+            this.connectReplyTimer = this.setTimer(() => {
                 this.connectReplyTimer = null;
                 if (this.socket === socket && !this.isHidden())
                     this.replaceSocket();
@@ -452,7 +572,7 @@ export class SyncClient {
         if (this.socketCreatedHidden)
             this.counters.backgroundSocketAttempts++;
         let killedByWatchdog = false;
-        this.watchdogTimer = this.options.runtime.setTimeout(() => {
+        this.watchdogTimer = this.setTimer(() => {
             if (socket.readyState !== SOCKET_OPEN) {
                 this.counters.watchdogKills++;
                 killedByWatchdog = true;
@@ -479,8 +599,8 @@ export class SyncClient {
             }
             this.cancelBackgroundTick();
             this.sendConnect();
-            this.pingTimer = this.options.runtime.setInterval(() => this.sendRaw({ type: 'ping' }), PING_INTERVAL_MS);
-            this.rolloverTimer = this.options.runtime.setTimeout(() => {
+            this.pingTimer = this.setRepeating(() => this.sendRaw({ type: 'ping' }), PING_INTERVAL_MS);
+            this.rolloverTimer = this.setTimer(() => {
                 this.options.logger.info('ws rollover', {});
                 this.plannedClose = socket;
                 socket.close();
@@ -556,7 +676,7 @@ export class SyncClient {
             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 = this.setTimer(() => {
             this.backgroundTickTimer = null;
             void this.backgroundTick();
         }, Math.min(due, interval));
@@ -633,7 +753,7 @@ export class SyncClient {
         const slot = { kind, controller };
         this.catchupSlot = slot;
         this.abortControllers.add(controller);
-        const timeout = this.options.runtime.setTimeout(() => controller.abort(), BACKGROUND_FETCH_TIMEOUT_MS);
+        const timeout = this.setTimer(() => controller.abort(), BACKGROUND_FETCH_TIMEOUT_MS);
         let ok = false;
         try {
             const result = await this.options.fetchCatchup(this.options.store.currentSeq(), controller.signal);
@@ -678,7 +798,7 @@ export class SyncClient {
     async withTimeout(operation) {
         const controller = new AbortController();
         this.abortControllers.add(controller);
-        const timeout = this.options.runtime.setTimeout(() => controller.abort(), BACKGROUND_FETCH_TIMEOUT_MS);
+        const timeout = this.setTimer(() => controller.abort(), BACKGROUND_FETCH_TIMEOUT_MS);
         try {
             return await operation(controller.signal);
         }
@@ -704,7 +824,7 @@ export class SyncClient {
             failures: 0,
             firstFailure: null,
             quickRetryUsed: false,
-            timer: this.options.runtime.setTimeout(() => this.finishReturnWindow(), RETURN_REPORT_TIMEOUT_MS),
+            timer: this.setTimer(() => this.finishReturnWindow(), RETURN_REPORT_TIMEOUT_MS),
         };
     }
     maybeFinishReturnWindow() {
@@ -785,13 +905,13 @@ export class SyncClient {
         }
         let remaining = delay;
         this.publish({ kind: 'reconnecting', pending: this.pendingCount(), inSeconds: remaining });
-        this.countdownTimer = this.options.runtime.setInterval(() => {
+        this.countdownTimer = this.setRepeating(() => {
             remaining--;
             if (remaining > 0) {
                 this.publish({ kind: 'reconnecting', pending: this.pendingCount(), inSeconds: remaining });
             }
         }, 1000);
-        this.reconnectTimer = this.options.runtime.setTimeout(() => {
+        this.reconnectTimer = this.setTimer(() => {
             if (this.countdownTimer !== null)
                 this.options.runtime.clearInterval(this.countdownTimer);
             this.countdownTimer = null;
@@ -858,7 +978,7 @@ export class SyncClient {
         if (this.escalateTimer !== null)
             this.options.runtime.clearTimeout(this.escalateTimer);
         this.escalateArmedAt = this.options.runtime.now();
-        this.escalateTimer = this.options.runtime.setTimeout(() => {
+        this.escalateTimer = this.setTimer(() => {
             this.escalateTimer = null;
             const late = this.options.runtime.now() - this.escalateArmedAt - OUTAGE_ESCALATE_MS;
             if (this.options.runtime.visibility() === 'hidden' || late > 5000)
@@ -1153,7 +1273,7 @@ export class SyncClient {
     }
     armFailureTimer(eventGuid) {
         this.clearFailureTimer(eventGuid);
-        this.failureTimers.set(eventGuid, this.options.runtime.setTimeout(() => this.failUnconfirmed(eventGuid), FAILURE_TIMEOUT_MS));
+        this.failureTimers.set(eventGuid, this.setTimer(() => this.failUnconfirmed(eventGuid), FAILURE_TIMEOUT_MS));
     }
     /** On return: a verdict needs 60 s of visible time (review B2). */
     rearmFailureTimers() {
@@ -1195,6 +1315,7 @@ export class SyncClient {
                 wasClean: info?.wasClean,
                 visibleAtDrop: info?.visibleAtDrop,
                 hiddenMs: delta?.hiddenMs,
+                stalledMs: delta?.stalledMs,
                 watchdogKills: delta?.watchdogKills,
                 backgroundCatchups: delta?.backgroundCatchups,
                 httpPostedEvents: delta?.httpPostedEvents,
@@ -1332,7 +1453,7 @@ export class SyncClient {
             return;
         // A hidden tab's timer throttling may stretch this well past the nominal
         // delay; that only postpones recovery, it never breaks it.
-        this.resyncBackoffTimer = this.options.runtime.setTimeout(() => {
+        this.resyncBackoffTimer = this.setTimer(() => {
             this.resyncBackoffTimer = null;
             void this.resyncFromServer('retry after resync backoff');
         }, RESYNC_RETRY_MS);
@@ -1431,6 +1552,7 @@ export class SyncClient {
             return;
         this.halted = true;
         this.abortFetches();
+        this.firstLoadRetry?.stop();
         this.clearAllTimers();
         const socket = this.socket;
         this.socket = null;

package/dist/sync-browser/first-load-retry.d.ts

@@ -0,0 +1,58 @@
+import type { Logger } from '../log-browser.js';
+type TimeoutHandle = ReturnType<typeof globalThis.setTimeout>;
+export interface FirstLoadRetryOptions {
+    now(): number;
+    visible(): boolean;
+    setTimer(callback: () => void, delayMs: number): TimeoutHandle;
+    clearTimer(timer: TimeoutHandle): void;
+    onOnline(listener: () => void): () => void;
+    onVisibilityChange(listener: () => void): () => void;
+    logger: Pick<Logger, 'info' | 'warn' | 'error'>;
+    /** The wait after each failure while visible; the last one repeats. */
+    visibleDelaysMs: readonly number[];
+    hiddenDelayMs: number;
+    /** Not loaded after this much visible, on-time loading: one ERROR. */
+    escalateAfterMs: number;
+    /** A trigger replaces an attempt that has run this long; an attempt this
+     * long is logged (INFO `bootstrap slow`). */
+    staleAttemptMs: number;
+}
+export declare class FirstLoadRetry {
+    private readonly options;
+    private failureCount;
+    private readonly startedAt;
+    /** Ladder position of the next visible wait; a return restarts it. */
+    private step;
+    private escalated;
+    private escalateTimer;
+    private waitTimer;
+    private wake;
+    private attempt;
+    /** A trigger arrived during the running attempt: if it fails, no wait. */
+    private triggered;
+    private stoppedFlag;
+    private readonly removeListeners;
+    /** Created as the first attempt starts. */
+    constructor(options: FirstLoadRetryOptions);
+    get failures(): number;
+    get stopped(): boolean;
+    /** `abort` cancels this attempt (its fetch's AbortSignal). */
+    attemptStarted(abort: () => void): void;
+    attemptEnded(outcome: 'loaded' | 'failed'): void;
+    /** An attempt failed without an HTTP answer (or was replaced as stale).
+     * One WARN per streak. */
+    failed(error: unknown): void;
+    /** Resolves true when the next attempt is due (timer, `online`, a return
+     * to visible, or a trigger during the attempt that just failed), false
+     * once stopped. */
+    next(): Promise<boolean>;
+    recovered(): void;
+    /** Removes listeners and timers and ends a running wait (`next` → false). */
+    stop(): void;
+    private trigger;
+    private release;
+    /** ERROR only once the load has lasted `escalateAfterMs` in view, on time;
+     * re-armed on each return. */
+    private armEscalation;
+}
+export {};

package/dist/sync-browser/first-load-retry.js

@@ -0,0 +1,167 @@
+// First-load recovery (docs/SYNC-INIT-RECOVERY-PLAN.md): while the first
+// bootstrap has not loaded, this decides when the next attempt is due and
+// owns the streak's logs. SyncClient makes the attempts, one at a time; a
+// trigger (`online`, a return to visible) never starts a second attempt next
+// to a running one: it ends the wait between attempts, or marks the running
+// attempt so that its failure retries at once, or, when that attempt has
+// already run `staleAttemptMs`, aborts it so a fresh one starts.
+/** A timer this late ran after the device slept or the page was frozen. */
+const LATE_TIMER_MS = 1_000;
+/** An escalation timer this late: that time was not spent loading in front
+ * of the user (as the socket's `sync outage ongoing`). */
+const ESCALATE_LATE_TOLERANCE_MS = 5_000;
+export class FirstLoadRetry {
+    options;
+    failureCount = 0;
+    startedAt;
+    /** Ladder position of the next visible wait; a return restarts it. */
+    step = 0;
+    escalated = false;
+    escalateTimer = null;
+    waitTimer = null;
+    wake = null;
+    attempt = null;
+    /** A trigger arrived during the running attempt: if it fails, no wait. */
+    triggered = false;
+    stoppedFlag = false;
+    removeListeners;
+    /** Created as the first attempt starts. */
+    constructor(options) {
+        this.options = options;
+        this.startedAt = options.now();
+        this.removeListeners = [
+            options.onOnline(() => this.trigger()),
+            options.onVisibilityChange(() => {
+                if (!this.options.visible())
+                    return;
+                this.step = 0;
+                this.armEscalation();
+                this.trigger();
+            }),
+        ];
+        this.armEscalation();
+    }
+    get failures() {
+        return this.failureCount;
+    }
+    get stopped() {
+        return this.stoppedFlag;
+    }
+    /** `abort` cancels this attempt (its fetch's AbortSignal). */
+    attemptStarted(abort) {
+        this.attempt = { startedAt: this.options.now(), abort };
+        this.triggered = false;
+    }
+    attemptEnded(outcome) {
+        const attempt = this.attempt;
+        this.attempt = null;
+        if (attempt === null || this.stoppedFlag)
+            return;
+        const attemptMs = this.options.now() - attempt.startedAt;
+        if (attemptMs >= this.options.staleAttemptMs) {
+            this.options.logger.info('bootstrap slow', { attemptMs, outcome, failures: this.failureCount });
+        }
+    }
+    /** An attempt failed without an HTTP answer (or was replaced as stale).
+     * One WARN per streak. */
+    failed(error) {
+        this.failureCount++;
+        if (this.failureCount > 1)
+            return;
+        this.options.logger.warn('bootstrap failed', { reachedServer: false, hidden: !this.options.visible(), error });
+    }
+    /** Resolves true when the next attempt is due (timer, `online`, a return
+     * to visible, or a trigger during the attempt that just failed), false
+     * once stopped. */
+    next() {
+        if (this.stoppedFlag)
+            return Promise.resolve(false);
+        if (this.triggered) {
+            this.triggered = false;
+            return Promise.resolve(true);
+        }
+        const visible = this.options.visible();
+        const delays = this.options.visibleDelaysMs;
+        const delayMs = visible ? delays[Math.min(this.step, delays.length - 1)] : this.options.hiddenDelayMs;
+        if (visible)
+            this.step++;
+        const dueAt = this.options.now() + delayMs;
+        return new Promise((resolve) => {
+            this.wake = resolve;
+            this.waitTimer = this.options.setTimer(() => {
+                this.waitTimer = null;
+                // Late: the device slept or the page was frozen — a phone whose
+                // screen went off with the page in front sends no visibilitychange.
+                // Waking is a return: restart the ladder.
+                if (this.options.now() - dueAt >= LATE_TIMER_MS)
+                    this.step = 0;
+                this.release(true);
+            }, delayMs);
+        });
+    }
+    recovered() {
+        if (this.failureCount > 0) {
+            this.options.logger.info('bootstrap recovered', {
+                failures: this.failureCount,
+                loadingForMs: Math.max(0, this.options.now() - this.startedAt),
+                escalated: this.escalated,
+            });
+        }
+        this.stop();
+    }
+    /** Removes listeners and timers and ends a running wait (`next` → false). */
+    stop() {
+        if (this.stoppedFlag)
+            return;
+        this.stoppedFlag = true;
+        for (const remove of this.removeListeners.splice(0))
+            remove();
+        if (this.escalateTimer !== null)
+            this.options.clearTimer(this.escalateTimer);
+        this.escalateTimer = null;
+        this.release(false);
+    }
+    trigger() {
+        if (this.wake !== null) {
+            this.release(true);
+            return;
+        }
+        const attempt = this.attempt;
+        if (attempt === null)
+            return;
+        this.triggered = true;
+        // Probably hung: on a dead path a request can wait out the OS connect
+        // timeout (minutes), and this trigger says the network or page changed.
+        if (this.options.now() - attempt.startedAt >= this.options.staleAttemptMs)
+            attempt.abort();
+    }
+    release(proceed) {
+        if (this.waitTimer !== null)
+            this.options.clearTimer(this.waitTimer);
+        this.waitTimer = null;
+        const wake = this.wake;
+        this.wake = null;
+        wake?.(proceed);
+    }
+    /** ERROR only once the load has lasted `escalateAfterMs` in view, on time;
+     * re-armed on each return. */
+    armEscalation() {
+        if (this.stoppedFlag || this.escalated || !this.options.visible())
+            return;
+        if (this.escalateTimer !== null)
+            this.options.clearTimer(this.escalateTimer);
+        const armedAt = this.options.now();
+        this.escalateTimer = this.options.setTimer(() => {
+            this.escalateTimer = null;
+            const lateMs = this.options.now() - armedAt - this.options.escalateAfterMs;
+            if (!this.options.visible() || lateMs > ESCALATE_LATE_TOLERANCE_MS)
+                return;
+            this.escalated = true;
+            this.options.logger.error('bootstrap still failing', {
+                failures: this.failureCount,
+                loadingForMs: Math.max(0, this.options.now() - this.startedAt),
+                attemptMs: this.attempt === null ? null : this.options.now() - this.attempt.startedAt,
+            });
+        }, this.options.escalateAfterMs);
+    }
+}

package/package.json

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