@ethlete/query 6.0.0-next.38 → 6.0.0-next.39

package/fesm2022/ethlete-query.mjs

@@ -2,7 +2,7 @@ import * as i0 from '@angular/core';
 import { inject, computed, DestroyRef, InjectionToken, Injector, EnvironmentInjector, ElementRef, ErrorHandler, createEnvironmentInjector, effect, untracked, signal, linkedSignal, runInInjectionContext, isDevMode, PLATFORM_ID, resource, DOCUMENT, VERSION, makeEnvironmentProviders, assertInInjectionContext, provideEnvironmentInitializer, ChangeDetectorRef, ViewContainerRef, TemplateRef, Input, Directive, input, Pipe, ViewEncapsulation, Component, NgZone } from '@angular/core';
 import { toObservable, takeUntilDestroyed, toSignal } from '@angular/core/rxjs-interop';
 import { UrlTree, Router, RedirectCommand, ActivatedRoute } from '@angular/router';
-import { filter, take, map, defer, from, Subject, Subscription, throwError, of, timer, switchMap, tap, retry, catchError, EMPTY, takeUntil, finalize, mergeMap, toArray, merge, takeWhile, firstValueFrom, concatMap, fromEvent, throttleTime, interval, combineLatest, Observable, startWith, pairwise, BehaviorSubject, ReplaySubject, shareReplay, skip, withLatestFrom, debounceTime } from 'rxjs';
+import { filter, take, map, defer, from, Subject, Subscription, throwError, of, timer, switchMap, tap, retry, catchError, EMPTY, takeUntil, finalize, mergeMap, toArray, merge, takeWhile, firstValueFrom, race, concatMap, fromEvent, throttleTime, interval, combineLatest, Observable, startWith, pairwise, BehaviorSubject, ReplaySubject, shareReplay, skip, withLatestFrom, debounceTime } from 'rxjs';
 import { defineStaticProvider, RuntimeError, clamp, randomId, defineRootProvider, isObject, injectUnsavedChangesCoordinator, injectRoute, getCookie, getDomain, deleteCookie, setCookie, CORE_VERSION, createDestroy, computedTillTruthy, defineProvider, toProvideFn, toInjectFn, nextFrame, injectQueryParams, injectQueryParamChanges, clone, equal, ET_PROPERTY_REMOVED, previousSignalValue } from '@ethlete/core';
 import { HttpClient, HttpEventType, HttpErrorResponse, HttpResponse, HttpHeaders, HttpStatusCode } from '@angular/common/http';
 import { getActiveConsumer, setActiveConsumer } from '@angular/core/primitives/signals';
@@ -1001,12 +1001,16 @@ const setupQueryState = (options) => {
         requestEventsSubscription.unsubscribe();
         requestEventsSubscription = request.events$.subscribe((event) => requestEvents$.next(event));
     };
+    options.destroyRef?.onDestroy(() => {
+        requestEventsSubscription.unsubscribe();
+        requestEvents$.complete();
+    });
     const executionState = computed(() => {
         const currentResponse = response();
         const currentError = error();
         const currentLoading = loading();
         if (currentLoading) {
-            if (currentResponse) {
+            if (currentResponse !== null) {
                 return {
                     type: 'loading',
                     hasCachedResponse: true,
@@ -1020,10 +1024,19 @@ const setupQueryState = (options) => {
                 loading: currentLoading,
             };
         }
+        else if (currentError && currentResponse !== null) {
+            return {
+                type: 'failure',
+                error: currentError,
+                hasCachedResponse: true,
+                cachedResponse: currentResponse,
+            };
+        }
         else if (currentError) {
             return {
                 type: 'failure',
                 error: currentError,
+                hasCachedResponse: false,
             };
         }
         else if (currentResponse !== null || latestHttpEvent()?.type === HttpEventType.Response) {
@@ -1239,6 +1252,7 @@ const createBaseQuery = (options) => {
         const devtoolsOverrides = createQueryDevtoolsOverridesRecorder();
         const state = setupQueryState({
             transformResponse: options.creator?.transformResponse,
+            destroyRef: deps.destroyRef,
             devtoolsStats,
             devtoolsFormLinks,
             devtoolsOverrides,
@@ -3504,13 +3518,14 @@ const createQueryKeyLockManager = (namespace) => {
         }
         keyStates.set(states);
     };
-    const hold = (key) => {
+    const hold = (key, options = {}) => {
         const isHolder = signal(false, /* @ts-ignore */
         ...(ngDevMode ? [{ debugName: "isHolder" }] : /* istanbul ignore next */ []));
         const abortController = new AbortController();
         const activeHold = { key, isHolder: isHolder.asReadonly() };
         let releaseHeldLock = null;
         let isReleased = false;
+        let wasGranted = false;
         activeHolds.add(activeHold);
         publishKeyStates();
         const release = () => {
@@ -3530,12 +3545,16 @@ const createQueryKeyLockManager = (namespace) => {
                 abortController.abort();
             }
         };
+        // A stealing request is granted on the spot, so it never queues and has nothing to abort - and
+        // the platform rejects `signal` together with `steal` outright.
+        const requestOptions = options.steal ? { steal: true } : { signal: abortController.signal };
         locks
-            .request(`${namespace}:${key}`, { signal: abortController.signal }, () => {
+            .request(`${namespace}:${key}`, requestOptions, () => {
             // Aborting a request the platform has already granted does nothing, so a release that raced
             // the grant lands here instead: take the lock and give it straight back.
             if (isReleased)
                 return Promise.resolve();
+            wasGranted = true;
             isHolder.set(true);
             publishKeyStates();
             return new Promise((resolve) => {
@@ -3547,6 +3566,13 @@ const createQueryKeyLockManager = (namespace) => {
             // standby hold ends. Nothing to recover from in either case - this tab is simply not the
             // holder, which is what the signal already says.
             isHolder.set(false);
+            // A hold that had the lock only ends in a rejection one way: another tab stole it. This one
+            // is over, so it leaves the published states behind and lets the caller decide what comes next.
+            if (!wasGranted || isReleased)
+                return;
+            activeHolds.delete(activeHold);
+            publishKeyStates();
+            options.onLost?.();
         });
         return { isHolder: activeHold.isHolder, release };
     };
@@ -5323,8 +5349,35 @@ const rescheduleDelayMs = 5000;
  * leadership over mid-flight simply never acts on it.
  */
 const delegatedRefreshRetryMs = 3000;
-/** How often a delegated refresh is re-asked for before the tab leaves it to the next 401. */
+/** How often a delegated refresh is re-asked for before this tab refreshes the tokens itself. */
 const maxDelegatedRefreshAttempts = 3;
+/**
+ * The same budget for a leader that answered with "a refresh started here". It is working on the
+ * refresh, so it gets longer than a silent one - but not forever, because the answer says a refresh
+ * started, not that it will ever finish.
+ */
+const maxDelegatedRefreshWindows = 6;
+/**
+ * How long before its expiry an access token counts as stale, which is the point a follower stops
+ * waiting for the leader. Long enough to run the delegation ladder before the token is worthless,
+ * short enough that a leader whose timer is merely throttled still gets to act first.
+ */
+const followerTakeoverGraceMs = 30000;
+/**
+ * How long a tab that took a refresh over holds the refresh lock at most. It is released as soon as
+ * the refresh reports back; this only bounds the wait for one that never does.
+ */
+const takeoverRefreshMaxLockHoldMs = 15000;
+/**
+ * The longest delay `setTimeout` can hold. Anything above it fires straight away, which would turn a
+ * long wait into a busy loop that spends every re-arm at once.
+ */
+const maxTimerDelayMs = 2147483647;
+/**
+ * The lock a tab must hold to spend the refresh token outside the leadership. Two followers go stale
+ * at the same instant - their access token is the same one - so the takeover needs a mutex of its own.
+ */
+const refreshLockName = (providerName) => `ethlete-auth:refresh:${providerName}`;
 /**
  * How often a scheduled refresh may re-arm before it waits for a new token pair. A tab that keeps
  * declining is either not the leader or busy issuing tokens; either way a 401 still forces a refresh.
@@ -5383,18 +5436,20 @@ const withRefreshQuery = (key, config) => {
         let unauthorizedRefreshStreak = 0;
         let delegatedRefreshAttempts = 0;
         let isWatchingDelegatedRefresh = false;
+        let hasLeaderAnsweredDelegation = false;
         // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
         const refreshQuery = () => context.queries[key];
         const executeRefresh = (reason) => {
             const currentRefreshToken = context.refreshToken();
             if (!currentRefreshToken)
                 return 'noToken';
-            if (!context.isLeader()) {
-                // A scheduled tick on a follower is pure duplicate: multi-tab sync keeps the access token
-                // identical across tabs, so the leader's own timer is due at the same instant and it is the
-                // only tab allowed to act. Delegation is for the 401 path, where this tab has a request that
-                // really failed and the leader has no way of knowing.
-                if (reason === 'scheduled')
+            if (reason !== 'takeover' && !context.isLeader()) {
+                // A scheduled tick on a follower is pure duplicate while the token still has life left: multi-tab
+                // sync keeps the access token identical across tabs, so the leader's own timer is due at the same
+                // instant and it is the only tab allowed to act. Once the token is stale that reasoning is spent -
+                // the leader had its moment and let it pass - so the tab delegates and, if that goes unanswered,
+                // takes the refresh over.
+                if (reason === 'scheduled' && !isAccessTokenStale())
                     return 'notLeader';
                 context.refreshCoordination?.request();
                 watchDelegatedRefresh(context.accessToken());
@@ -5424,16 +5479,28 @@ const withRefreshQuery = (key, config) => {
             // the request has to go out.
             lastRefreshTime = now;
             refreshQuery().execute(buildArgs(currentRefreshToken), { triggeredBy: 'token-refresh' });
+            // Answers every follower waiting on a delegated refresh, not just the one that asked: they all
+            // hold the same access token, so they all go stale at the same moment.
+            context.refreshCoordination?.announceStart();
             return 'executed';
         };
         /**
-         * Asks the leader again if a delegated refresh went unanswered - the request is a channel message
-         * with no ack, so a frozen leader, or one that handed the leadership over mid-flight, drops it
-         * silently. One watch at a time, and by the time it re-asks this tab may be the leader itself;
-         * `executeRefresh` re-decides that on every attempt.
+         * Asks the leader again if a delegated refresh went unanswered, and refreshes the tokens in this tab
+         * once the leader has run out of chances. A frozen leader keeps the lock that makes it the leader
+         * while it runs no timer and reads no message, so waiting for it is waiting for nothing.
+         *
+         * One watch at a time, and by the time it re-asks this tab may be the leader itself; `executeRefresh`
+         * re-decides that on every attempt.
          */
         function watchDelegatedRefresh(tokenAtRequest) {
-            if (isWatchingDelegatedRefresh || delegatedRefreshAttempts >= maxDelegatedRefreshAttempts)
+            if (isWatchingDelegatedRefresh)
+                return;
+            // A new ladder judges the leader by what it answers this time round, not by an answer from an hour
+            // ago - the tab that gave it may not even be open any more.
+            if (delegatedRefreshAttempts === 0)
+                hasLeaderAnsweredDelegation = false;
+            const budget = hasLeaderAnsweredDelegation ? maxDelegatedRefreshWindows : maxDelegatedRefreshAttempts;
+            if (delegatedRefreshAttempts >= budget)
                 return;
             delegatedRefreshAttempts++;
             isWatchingDelegatedRefresh = true;
@@ -5444,11 +5511,62 @@ const withRefreshQuery = (key, config) => {
                 // A new access token is the leader's answer - nothing to re-ask for.
                 if (context.accessToken() !== tokenAtRequest) {
                     delegatedRefreshAttempts = 0;
+                    hasLeaderAnsweredDelegation = false;
+                    return;
+                }
+                const spentBudget = hasLeaderAnsweredDelegation ? maxDelegatedRefreshWindows : maxDelegatedRefreshAttempts;
+                if (delegatedRefreshAttempts >= spentBudget) {
+                    void takeOverRefresh(tokenAtRequest);
                     return;
                 }
                 executeRefresh('unauthorized');
             });
         }
+        /** Runs the refresh and keeps the refresh lock until it reports back, or until the bound runs out. */
+        const runTakenOverRefresh = async () => {
+            const attempt = executeRefresh('takeover');
+            // The ladder starts over whatever came of it, including a takeover that could not run yet - a
+            // refresh already in flight, or the floor under the 401-driven ones. Leaving the budget spent
+            // would retire the only path a follower has to a token the leader is not going to issue.
+            delegatedRefreshAttempts = 0;
+            hasLeaderAnsweredDelegation = false;
+            if (attempt !== 'executed')
+                return;
+            await new Promise((resolve) => {
+                race(context.afterTokenRefresh$, timer(takeoverRefreshMaxLockHoldMs))
+                    .pipe(take(1), takeUntilDestroyed(destroyRef))
+                    .subscribe({ next: () => resolve(), complete: () => resolve() });
+            });
+        };
+        /**
+         * Spends the refresh token in this tab, after the leader failed to. Guarded by a lock of its own
+         * rather than by the leadership, which the unresponsive tab still holds: every follower runs out of
+         * patience at the same instant, and a single-use refresh token must not be spent twice.
+         *
+         * `ifAvailable` makes it a try-lock, so the tab that does not get the lock stands down instead of
+         * queueing for a turn it must no longer take - the winner's new token pair arrives over the sync
+         * channel long before then.
+         */
+        const takeOverRefresh = async (tokenAtRequest) => {
+            if (context.accessToken() !== tokenAtRequest)
+                return;
+            const locks = typeof navigator === 'undefined' ? undefined : navigator.locks;
+            if (!locks) {
+                await runTakenOverRefresh();
+                return;
+            }
+            await locks.request(refreshLockName(context.name), { ifAvailable: true }, async (lock) => {
+                if (!lock) {
+                    // Another tab is spending the refresh token right now. Start the ladder over rather than race
+                    // it: this tab hears about the pair it issues, and needs a way back if it never issues one.
+                    delegatedRefreshAttempts = 0;
+                    return;
+                }
+                if (context.accessToken() !== tokenAtRequest)
+                    return;
+                await runTakenOverRefresh();
+            });
+        };
         /**
          * How long a scheduled refresh that did not spend the refresh token waits before trying again.
          * `null` re-arms nothing, because only a new token pair can change the outcome - and that restarts
@@ -5463,11 +5581,14 @@ const withRefreshQuery = (key, config) => {
                     return Math.max(minRefreshInterval - (Date.now() - lastRefreshTime), rescheduleDelayMs);
                 case 'busy':
                     return rescheduleDelayMs;
-                // Both wait for the leader: `delegated` asked it to act, `notLeader` left it to its own timer.
-                // Coming back keeps this tab covered if the leadership moves here in the meantime.
                 case 'delegated':
-                case 'notLeader':
                     return minRefreshInterval;
+                // Left to the leader's own timer, which is due at the same instant as this one. Coming back at
+                // the staleness deadline instead of on a fixed interval is what makes the wait bounded: a fixed
+                // interval spends `maxRescheduleAttempts` within minutes of a token that can live for hours, and
+                // the tab is then left with no armed timer at all.
+                case 'notLeader':
+                    return Math.min(Math.max(msUntilAccessTokenIsStale() ?? minRefreshInterval, rescheduleDelayMs), maxTimerDelayMs);
             }
         };
         const calculateRefreshBuffer = (tokenLifetimeMs) => {
@@ -5480,8 +5601,8 @@ const withRefreshQuery = (key, config) => {
             const calculatedBuffer = tokenLifetimeMs * (1 - percentage);
             return Math.max(minBufferMs, Math.min(maxBufferMs, calculatedBuffer));
         };
-        /** When this access token is due to be refreshed, or `null` if it cannot be scheduled at all. */
-        const scheduledRefreshDelay = (token) => {
+        /** When this token expires, as a timestamp, or `null` if the expiry cannot be read off it. */
+        const tokenExpiresAt = (token) => {
             try {
                 const decoded = context.bearerDecryptFn ? context.bearerDecryptFn(token) : decryptBearer(token);
                 const bearerDataValue = patchQueryDevtoolsTokenPayload({
@@ -5496,29 +5617,61 @@ const withRefreshQuery = (key, config) => {
                     }
                     return null;
                 }
-                const tokenLifetimeMs = expiresIn * 1000 - Date.now();
-                if (tokenLifetimeMs <= 0) {
-                    if (!refreshIfExpired)
-                        return null;
-                    if (isDevMode()) {
-                        console.warn('Token is already expired, triggering immediate refresh');
-                    }
-                    return 0;
-                }
-                return Math.max(tokenLifetimeMs - calculateRefreshBuffer(tokenLifetimeMs), 0);
+                return expiresIn * 1000;
             }
             catch {
                 return null;
             }
         };
+        /** When this access token is due to be refreshed, or `null` if it cannot be scheduled at all. */
+        const scheduledRefreshDelay = (token) => {
+            const expiresAt = tokenExpiresAt(token);
+            if (expiresAt === null)
+                return null;
+            const tokenLifetimeMs = expiresAt - Date.now();
+            if (tokenLifetimeMs <= 0) {
+                if (!refreshIfExpired)
+                    return null;
+                if (isDevMode()) {
+                    console.warn('Token is already expired, triggering immediate refresh');
+                }
+                return 0;
+            }
+            return Math.max(tokenLifetimeMs - calculateRefreshBuffer(tokenLifetimeMs), 0);
+        };
+        /**
+         * How long this tab can still work with the access token it holds, or `null` without a readable
+         * expiry. Zero or less means a refresh has to happen now, whichever tab does it.
+         */
+        const msUntilAccessTokenIsStale = () => {
+            const token = context.accessToken();
+            if (!token)
+                return null;
+            const expiresAt = tokenExpiresAt(token);
+            return expiresAt === null ? null : expiresAt - followerTakeoverGraceMs - Date.now();
+        };
+        const isAccessTokenStale = () => {
+            const remainingMs = msUntilAccessTokenIsStale();
+            return remainingMs !== null && remainingMs <= 0;
+        };
         /**
          * The scheduled refresh, re-armed for as long as it keeps declining to spend the refresh token.
          * Without the re-arm a single declined attempt strands the session on a token nothing renews until
          * a request fails with a 401 - by which time the refresh token may be gone too.
          */
         const scheduledRefresh = (dueInMs, attemptsLeft) => (dueInMs <= 0 ? of(0) : timer(dueInMs)).pipe(concatMap(() => {
-            const retryInMs = retryScheduledIn(executeRefresh('scheduled'));
-            return retryInMs === null || attemptsLeft <= 0 ? EMPTY : scheduledRefresh(retryInMs, attemptsLeft - 1);
+            const attempt = executeRefresh('scheduled');
+            const retryInMs = retryScheduledIn(attempt);
+            if (retryInMs === null)
+                return EMPTY;
+            // Waiting on another tab does not spend the budget. Both outcomes come back at a deadline
+            // rather than on a fixed interval, and both end the moment a token pair arrives, because a
+            // new token restarts the schedule. Spending the budget on them leaves a follower whose
+            // leader never acts with no armed timer at all, which is the one state nothing recovers
+            // from: the tab then holds a dead token and cannot even ask for a new one.
+            if (attempt === 'notLeader' || attempt === 'delegated')
+                return scheduledRefresh(retryInMs, attemptsLeft);
+            return attemptsLeft <= 0 ? EMPTY : scheduledRefresh(retryInMs, attemptsLeft - 1);
         }));
         // A backgrounded tab's `timer()` does not fire on time - the browser throttles it, and a frozen
         // page stops running it altogether while keeping the Web Lock that makes it the leader. So the
@@ -5549,6 +5702,9 @@ const withRefreshQuery = (key, config) => {
             .pipe(switchMap(({ dueInMs }) => (dueInMs === null ? EMPTY : scheduledRefresh(dueInMs, maxRescheduleAttempts))), takeUntilDestroyed())
             .subscribe();
         context.refreshCoordination?.requests$.pipe(takeUntilDestroyed()).subscribe(() => executeRefresh('unauthorized'));
+        context.refreshCoordination?.starts$.pipe(takeUntilDestroyed()).subscribe(() => {
+            hasLeaderAnsweredDelegation = true;
+        });
         const onRefreshFailure = config.onRefreshFailure ??
             (({ error, logout }) => {
                 if (!retryableStatusCodes.includes(error.code))
@@ -5570,6 +5726,7 @@ const withRefreshQuery = (key, config) => {
                 if (event.type === 'request-success' && event.isSecure) {
                     unauthorizedRefreshStreak = 0;
                     delegatedRefreshAttempts = 0;
+                    hasLeaderAnsweredDelegation = false;
                     return;
                 }
                 if (event.type !== 'request-error' || !event.isSecure || event.error?.status !== 401)
@@ -5742,9 +5899,16 @@ const leaderLockName = (name) => `${LEADER_LOCK_NAMESPACE}:${leaderLockKey(name)
 /**
  * Web Locks has no "someone joined" event, so tabs announce themselves on this channel. Two messages
  * per tab lifetime, in place of the heartbeat this used to run once a second. It also carries a
- * follower's request for a refresh, which is the other thing a tab can only say to the leader.
+ * follower's request for a refresh and the leader's answer that one started, and the two messages the
+ * leadership moves to a visible tab with.
  */
 const presenceChannelName = (name) => `ethlete-auth-leader:${name}`;
+/**
+ * How long a visible tab waits for the leader to say it is still running before it takes the lock
+ * over. Long enough for a same-origin channel message and its answer on a busy main thread, short
+ * enough that the user does not sit in front of a session nothing can refresh.
+ */
+const leaderClaimTimeoutMs = 1500;
 const countLeaderRequests = (snapshot, lockName) => {
     const isLeaderLock = (info) => info.name === lockName;
     // Held plus pending is exactly the tab count: every tab requests this one lock, one gets it and the
@@ -5755,9 +5919,22 @@ const countLeaderRequests = (snapshot, lockName) => {
  * Elects the one tab that refreshes the session's tokens, over the
  * [Web Locks API](https://developer.mozilla.org/docs/Web/API/Web_Locks_API).
  *
- * The lock does the whole job: requests queue FIFO, so the tab that has been waiting longest takes
- * over, and a holder that closes, crashes or navigates away has its lock released by the platform.
- * No heartbeat, no timeout to tune, and no window in which two tabs both believe they are the leader.
+ * The lock does most of the job: requests queue FIFO, so a tab that closes, crashes or navigates away
+ * has its lock released by the platform and the next tab in line takes over. No heartbeat, no timeout
+ * to tune, and no window in which two tabs both believe they are the leader.
+ *
+ * What the queue cannot decide is *which* tab should lead. Its order is the order the tabs opened in,
+ * which says nothing about which of them is awake: a hidden tab has its timers throttled to about
+ * once a minute and a frozen one runs none at all, so a session led from one is a session nothing
+ * refreshes, while the tab the user is looking at sits queued behind it. So the leadership follows
+ * the user instead:
+ *
+ * - A tab that becomes hidden while leading gives the lock up and asks again, which puts it behind
+ *   whoever else wants it - and hands it straight back if nobody does.
+ * - A tab that becomes visible without leading claims the leadership, and every hidden tab gives way
+ *   to it. This is what brings the leadership back to a tab the user returns to.
+ * - A leader that answers neither - it is frozen, or the machine it runs on is asleep - has the lock
+ *   taken off it, because nothing it does not run can hand it over.
  *
  * Degrades to "this tab is the leader" without Web Locks - the same single-tab behavior the previous
  * `localStorage` implementation fell back to, and the only safe default: a session that refreshes its
@@ -5767,10 +5944,20 @@ const setupLeaderElection = (options) => {
     const destroyRef = inject(DestroyRef);
     const lockName = leaderLockName(options.name);
     const lockManager = createQueryKeyLockManager(LEADER_LOCK_NAMESPACE);
-    const hold = lockManager.hold(leaderLockKey(options.name));
     const instanceCount = signal(1, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "instanceCount" }] : /* istanbul ignore next */ []));
     const refreshRequests = new Subject();
+    const refreshStarts = new Subject();
+    let isDestroyed = false;
+    let isParticipating = true;
+    const requestLeadership = (requestOptions) => lockManager.hold(leaderLockKey(options.name), {
+        steal: requestOptions?.steal,
+        onLost: () => onLeadershipTaken(),
+    });
+    const hold = signal(requestLeadership(), /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "hold" }] : /* istanbul ignore next */ []));
+    const isLeader = computed(() => hold().isHolder(), /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "isLeader" }] : /* istanbul ignore next */ []));
     const noop = () => {
         /* nothing was set up */
     };
@@ -5778,16 +5965,18 @@ const setupLeaderElection = (options) => {
     // and asks nobody else for a refresh.
     if (!lockManager.isSupported) {
         return {
-            isLeader: hold.isHolder,
+            isLeader,
             instanceCount: instanceCount.asReadonly(),
             isSupported: false,
             requestRefresh: noop,
             refreshRequests$: refreshRequests.asObservable(),
+            announceRefreshStart: noop,
+            refreshStarts$: refreshStarts.asObservable(),
             cleanup: noop,
         };
     }
     const channel = typeof BroadcastChannel === 'undefined' ? null : new BroadcastChannel(presenceChannelName(options.name));
-    let isDestroyed = false;
+    const isPageVisible = () => typeof document === 'undefined' || document.visibilityState === 'visible';
     const recount = async () => {
         const snapshot = await navigator.locks.query();
         if (isDestroyed)
@@ -5796,8 +5985,65 @@ const setupLeaderElection = (options) => {
         // count of zero would say the app is not running in the tab reading it.
         instanceCount.set(Math.max(countLeaderRequests(snapshot, lockName), 1));
     };
-    const announce = () => channel?.postMessage({ type: 'presence' });
-    const requestRefresh = () => channel?.postMessage({ type: 'refresh-requested' });
+    const post = (message) => channel?.postMessage(message);
+    const announce = () => post({ type: 'presence' });
+    const requestRefresh = () => post({ type: 'refresh-requested' });
+    const announceRefreshStart = () => post({ type: 'refresh-started' });
+    /** Set while this tab has claimed the leadership and is waiting to hear whether the leader is alive. */
+    let claimTimeout;
+    const cancelClaim = () => {
+        clearTimeout(claimTimeout);
+        claimTimeout = undefined;
+    };
+    /** Asks for the lock again, which puts this tab behind every tab already waiting for it. */
+    const requeue = (requestOptions) => {
+        hold().release();
+        hold.set(requestLeadership(requestOptions));
+    };
+    /**
+     * Steps aside for the tabs that want the leadership. What a hidden tab does: its timers are
+     * throttled to about once a minute, so the refresh it is responsible for happens roughly whenever.
+     * It stays in the election, and gets the lock straight back if no other tab wants it.
+     */
+    const yieldLeadership = () => {
+        if (isDestroyed || !isParticipating)
+            return;
+        requeue();
+        void recount();
+    };
+    /**
+     * Takes the lock off the tab holding it, once asking has not worked. The last resort of
+     * {@link claimLeadership}: a frozen leader keeps its lock, answers nothing and refreshes nothing,
+     * and a handover between hidden tabs can land the lock on the next hidden tab in the queue.
+     */
+    const takeLeadershipOver = () => {
+        cancelClaim();
+        if (isDestroyed || !isParticipating || isLeader())
+            return;
+        requeue({ steal: true });
+        announce();
+        void recount();
+    };
+    /**
+     * Asks the tabs ahead of this one to give the leadership up, because the user is looking at this
+     * one. Hidden tabs give way on their own; a leader that says nothing at all has the lock taken off
+     * it once the wait runs out.
+     */
+    const claimLeadership = () => {
+        if (isDestroyed || !isParticipating || !channel || isLeader() || !isPageVisible())
+            return;
+        if (claimTimeout !== undefined)
+            return;
+        claimTimeout = setTimeout(takeLeadershipOver, leaderClaimTimeoutMs);
+        post({ type: 'claim' });
+    };
+    /** Rejoins the queue after another tab took the lock over, rather than leaving the election. */
+    const onLeadershipTaken = () => {
+        if (isDestroyed || !isParticipating)
+            return;
+        hold.set(requestLeadership());
+        void recount();
+    };
     if (channel) {
         channel.onmessage = (event) => {
             const message = event.data;
@@ -5805,39 +6051,134 @@ const setupLeaderElection = (options) => {
                 void recount();
                 return;
             }
+            if (message?.type === 'refresh-started') {
+                refreshStarts.next();
+                return;
+            }
+            if (message?.type === 'claim') {
+                // The answer goes out before the handover, and from the leader alone: it is the one thing that
+                // tells the claiming tab that a tab which is not answering *is* a tab that is not running.
+                if (isLeader())
+                    post({ type: 'leader-alive', isVisible: isPageVisible() });
+                // Every hidden tab gives way, not only the leader: a claim that only moved the lock one place
+                // along would land it on the next hidden tab in the queue.
+                if (!isPageVisible())
+                    yieldLeadership();
+                return;
+            }
+            if (message?.type === 'leader-alive') {
+                // One visible tab leading is as good as another, so a claim against one is over. A hidden
+                // leader is giving way instead, and the claim stays armed until it has: the release hands the
+                // lock to the first tab in the queue, which may be another hidden one.
+                if (message.isVisible)
+                    cancelClaim();
+                return;
+            }
             // Every tab hears the request; only the one that may spend the refresh token acts on it.
-            if (message?.type === 'refresh-requested' && hold.isHolder()) {
+            if (message?.type === 'refresh-requested' && isLeader()) {
                 refreshRequests.next();
             }
         };
     }
     effect(() => {
-        if (!hold.isHolder())
+        if (!isLeader())
             return;
+        cancelClaim();
         // Becoming the leader means the previous one went away. A tab that closed normally announced it
         // itself, one that crashed did not - so this is the moment to tell the others for free.
         announce();
         void recount();
     });
+    /**
+     * Leaves the election, because this tab is about to stop running. A frozen page keeps its lock while
+     * its timers do not fire, so a leader that stays in would be a leader that refreshes nothing, and
+     * every other tab would sit queued behind it until the user came back. The lock is not requested
+     * again here: the platform would grant it to this page just as well while it is frozen.
+     */
+    const leaveElection = () => {
+        if (isDestroyed || !isParticipating)
+            return;
+        isParticipating = false;
+        cancelClaim();
+        // Release before the goodbye: the tabs that recount on it should no longer see this one queued.
+        hold().release();
+        announce();
+    };
+    /** Takes part again, behind whichever tab took the leadership over in the meantime. */
+    const rejoinElection = () => {
+        if (isDestroyed || isParticipating)
+            return;
+        isParticipating = true;
+        hold.set(requestLeadership());
+        announce();
+        void recount();
+        // A page resumes because the user came back to it, so it is also the tab that should be leading.
+        claimLeadership();
+    };
+    const isRestoredFromCache = (event) => event.persisted === true;
+    const onFreeze = () => leaveElection();
+    const onResume = () => rejoinElection();
+    const onPageHide = (event) => {
+        if (isRestoredFromCache(event))
+            leaveElection();
+    };
+    const onPageShow = (event) => {
+        if (isRestoredFromCache(event))
+            rejoinElection();
+    };
+    const onVisibilityChange = () => {
+        if (isPageVisible()) {
+            claimLeadership();
+            return;
+        }
+        if (isLeader())
+            yieldLeadership();
+    };
+    // `freeze`/`resume` is Chromium's; `pagehide`/`pageshow` with `persisted` is how a page enters and
+    // leaves the back/forward cache, which stops it just as dead in browsers that fire no `freeze`.
+    if (typeof document !== 'undefined') {
+        document.addEventListener('freeze', onFreeze);
+        document.addEventListener('resume', onResume);
+        document.addEventListener('visibilitychange', onVisibilityChange);
+    }
+    if (typeof window !== 'undefined') {
+        window.addEventListener('pagehide', onPageHide);
+        window.addEventListener('pageshow', onPageShow);
+    }
     announce();
     void recount();
+    // A tab that opens while another one sleeps must not wait for a visibility change that already
+    // happened. The claim costs one message and settles itself when the leader answers.
+    claimLeadership();
     const cleanup = () => {
         if (isDestroyed)
             return;
         isDestroyed = true;
-        // Release before the goodbye: the tabs that recount on it should no longer see this one queued.
-        hold.release();
+        cancelClaim();
+        if (typeof document !== 'undefined') {
+            document.removeEventListener('freeze', onFreeze);
+            document.removeEventListener('resume', onResume);
+            document.removeEventListener('visibilitychange', onVisibilityChange);
+        }
+        if (typeof window !== 'undefined') {
+            window.removeEventListener('pagehide', onPageHide);
+            window.removeEventListener('pageshow', onPageShow);
+        }
+        hold().release();
         announce();
         channel?.close();
         refreshRequests.complete();
+        refreshStarts.complete();
     };
     destroyRef.onDestroy(cleanup);
     return {
-        isLeader: hold.isHolder,
+        isLeader,
         instanceCount: instanceCount.asReadonly(),
         isSupported: true,
         requestRefresh,
         refreshRequests$: refreshRequests.asObservable(),
+        announceRefreshStart,
+        refreshStarts$: refreshStarts.asObservable(),
         cleanup,
     };
 };
@@ -6013,10 +6354,38 @@ const setupMultiTabSync = (config, context) => {
         settleAdoption();
     };
     let adoptionTimeout;
+    const requestState = () => channel.postMessage({ type: 'state-request' });
+    /**
+     * A page that was frozen or held in the back/forward cache ran nothing while it was away, so the
+     * token pair it wakes up with is whatever it held when it stopped - the rotations it missed were
+     * broadcast to a tab that was not listening. Asking again is what stops it spending a refresh token
+     * that was already spent, which the server answers with a 401 and the provider with a logout for
+     * every tab.
+     */
+    const resyncAfterResume = () => {
+        if (!syncTokens || !context.accessToken())
+            return;
+        requestState();
+    };
+    const onResume = () => resyncAfterResume();
+    const onPageShow = (event) => {
+        if (event.persisted === true)
+            resyncAfterResume();
+    };
+    if (typeof document !== 'undefined') {
+        document.addEventListener('resume', onResume);
+    }
+    if (typeof window !== 'undefined') {
+        window.addEventListener('pageshow', onPageShow);
+    }
     const cleanup = () => {
         clearTimeout(adoptionTimeout);
         settleAdoption();
         remoteActivity.complete();
+        if (typeof document !== 'undefined')
+            document.removeEventListener('resume', onResume);
+        if (typeof window !== 'undefined')
+            window.removeEventListener('pageshow', onPageShow);
         channel.close();
     };
     destroyRef.onDestroy(cleanup);
@@ -6034,7 +6403,7 @@ const setupMultiTabSync = (config, context) => {
                 };
             });
             adoptionTimeout = setTimeout(settleAdoption, sessionAdoptionTimeoutMs);
-            channel.postMessage({ type: 'state-request' });
+            requestState();
             return { isPending: () => isAdoptionPending, settled };
         })()
         : undefined;
@@ -6092,7 +6461,8 @@ const SINGLE_TAB = /* @__PURE__ */ (() => {
 /**
  * Keeps one browser session consistent across the user's tabs: a login in one tab logs the others in,
  * a logout logs them out, and only one tab (the leader) performs the automatic token refresh so a
- * single-use refresh token is not spent twice.
+ * single-use refresh token is not spent twice. The leadership follows the tab the user is looking at,
+ * because a hidden tab has its timers throttled and a frozen one runs none at all.
  *
  * Off by default - a single-tab app, a kiosk or an embedded webview ships neither the
  * `BroadcastChannel` sync nor the Web Locks leader election without it. Degrades to "this tab is the
@@ -6157,7 +6527,12 @@ const withBearerAuthMultiTabSync = (config = {}) => {
         return {
             isLeader: () => election.isLeader(),
             leaderElection: instance,
-            refreshCoordination: { request: election.requestRefresh, requests$: election.refreshRequests$ },
+            refreshCoordination: {
+                request: election.requestRefresh,
+                requests$: election.refreshRequests$,
+                announceStart: election.announceRefreshStart,
+                starts$: election.refreshStarts$,
+            },
             sessionAdoption: sync.sessionAdoption,
             activityCoordination: sync.activityCoordination,
         };
@@ -7803,7 +8178,7 @@ const armQueryDevtoolsOverrideTransfer = (recorder, ops) => {
 
 // Generated from package.json by tools/scripts/generate-version.js - do not edit.
 /** The version of `@ethlete/query` this build was cut from. */
-const QUERY_VERSION = '6.0.0-next.38';
+const QUERY_VERSION = '6.0.0-next.39';
 
 /** How deep a schema is expanded before a nested branch is given up on. */
 const MAX_DEPTH = 12;
@@ -14234,8 +14609,8 @@ const defineQueryForm = (config) => {
         // Feed the URL value into the live model & bound controls; the effect no-ops (model === committed).
         model.set(clone(next));
     };
-    const applyFromUrl = (params) => {
-        const current = { ...committed() };
+    const applyFromUrl = (params, base = committed()) => {
+        const current = { ...base };
         let changed = false;
         for (const [key, def] of Object.entries(fieldDefs)) {
             const raw = params[paramKey(key)];
@@ -14313,7 +14688,9 @@ const defineQueryForm = (config) => {
             observeOptions = options;
             observing.set(true);
             if (options?.syncOnNavigation !== false) {
-                applyFromUrl(route.snapshot.queryParams);
+                // A value written before `observe()` sits in the model only, so the URL merges onto the model
+                // here. Against `committed()` any single URL param would drop that value.
+                applyFromUrl(route.snapshot.queryParams, model());
             }
             // Commit whatever the model holds now (URL-restored or programmatic defaults).
             flush();