@camera.ui/transport 0.0.29 → 0.1.0

package/dist/index.js

@@ -1,5 +1,5 @@
+import { n as refusedByServer, t as classifyClose } from "./closeCodes-CltSRjdJ.js";
 import { n as isEndpointChange, r as isSameTarget, t as TransportEmitter } from "./contract-dt1m8U-o.js";
-import { t as classifyClose } from "./closeCodes-ClWJVOpq.js";
 import { Logger } from "@camera.ui/logger";
 //#region src/core/reducer.ts
 var DEFAULT_BACKOFF_MS = 5e3;
@@ -8,15 +8,15 @@ function reducer(phase, action, ctx) {
 		case "RESET": return phase.kind === "idle" ? phase : { kind: "idle" };
 		case "BOOT":
 			if (phase.kind !== "idle" && phase.kind !== "offline" && phase.kind !== "needs-auth") return phase;
-			return {
+			return withPending({
 				kind: "discovering",
 				instanceId: action.instanceId
-			};
+			}, phase);
 		case "USER_RETRY":
-			if (phase.kind === "offline" || phase.kind === "needs-auth") return {
+			if (phase.kind === "offline" || phase.kind === "needs-auth") return withPending({
 				kind: "discovering",
 				instanceId: phase.instanceId ?? ""
-			};
+			}, phase);
 			return phase;
 		case "PROBE_SUCCEEDED":
 			if (phase.kind !== "discovering") return phase;
@@ -52,7 +52,7 @@ function reducer(phase, action, ctx) {
 					}
 				};
 			}
-			if (phase.kind === "discovering") {
+			if (phase.kind === "discovering" || phase.kind === "offline") {
 				if (phase.pendingTokens && tokensEqual(phase.pendingTokens, action.tokens)) return phase;
 				return {
 					...phase,
@@ -96,7 +96,7 @@ function reducer(phase, action, ctx) {
 			if (phase.kind !== "offline") return phase;
 			const now = ctx.now();
 			const candidate = now + action.retryAfterMs;
-			if (candidate <= phase.nextRetryAt) return phase;
+			if (phase.backoffHint && candidate <= phase.nextRetryAt) return phase;
 			return {
 				...phase,
 				nextRetryAt: candidate,
@@ -109,6 +109,12 @@ function reducer(phase, action, ctx) {
 		}
 	}
 }
+function withPending(next, prev) {
+	return prev.kind === "offline" && prev.pendingTokens ? {
+		...next,
+		pendingTokens: prev.pendingTokens
+	} : next;
+}
 function tokensEqual(a, b) {
 	return a.access === b.access && a.refresh === b.refresh && a.accessExpiresAt === b.accessExpiresAt && a.refreshExpiresAt === b.refreshExpiresAt && a.proxySession === b.proxySession && a.proxySessionExpiresAt === b.proxySessionExpiresAt && a.proxyRefresh === b.proxyRefresh;
 }
@@ -311,8 +317,12 @@ function createBackgroundProbe(options) {
 				options.onResult?.("failed", "empty pool");
 				return "failed";
 			}
+			if (options.ready) {
+				await options.ready().catch(() => void 0);
+				if (disposed || options.kernel.phase.kind !== "online") return "skipped";
+			}
 			const lastTokens = options.lastTarget?.()?.tokens;
-			const { endpoint, value: tokens } = await raceFirst(pool.map((endpoint) => ({
+			const { endpoint, value } = await raceFirst(pool.map((endpoint) => ({
 				endpoint,
 				run: (signal) => options.probe({
 					endpoint,
@@ -333,10 +343,17 @@ function createBackgroundProbe(options) {
 			}
 			const current = phase.target.endpoint;
 			const same = current.url === endpoint.url && current.mode === endpoint.mode;
-			if (!same && options.prefer && options.prefer(current) && !options.prefer(endpoint) && options.isCurrentHealthy?.() === true) {
-				options.onResult?.("kept", current.url);
+			const preferredWinner = options.prefer?.(endpoint) ?? false;
+			const preferredCurrent = options.prefer?.(current) ?? false;
+			if (!same && options.isCurrentHealthy?.() === true && !(preferredWinner && !preferredCurrent)) {
+				if (value !== lastTokens) options.kernel.dispatch({
+					type: "TOKENS_REFRESHED",
+					tokens: value
+				});
+				options.onResult?.("kept", preferredWinner === preferredCurrent ? `${current.url} (same class as ${endpoint.url})` : current.url);
 				return "kept";
 			}
+			const tokens = value === lastTokens ? phase.target.tokens : value;
 			options.kernel.dispatch({
 				type: "ENDPOINT_SWAP",
 				endpoint,
@@ -379,8 +396,10 @@ function attachBackoff(options) {
 	const setTimer = options.setTimer ?? ((cb, ms) => setTimeout(cb, ms));
 	const clearTimer = options.clearTimer ?? ((h) => clearTimeout(h));
 	let timer;
+	let firesAt = 0;
 	let attempt = 0;
 	let detached = false;
+	const ownRetry = { type: "USER_RETRY" };
 	function cancelTimer(reason) {
 		if (timer !== void 0) {
 			clearTimer(timer);
@@ -388,34 +407,42 @@ function attachBackoff(options) {
 			if (reason) options.onCancelled?.(reason);
 		}
 	}
+	function fastDelay() {
+		const quick = options.firstAttemptDelayMs?.();
+		return typeof quick === "number" && quick >= 0 ? quick : void 0;
+	}
 	function scheduleFromPhase(phase, isReschedule) {
 		cancelTimer(isReschedule ? "rescheduled" : void 0);
 		const baseDelay = schedule[Math.min(attempt, schedule.length - 1)];
-		const quick = attempt === 0 ? options.firstAttemptDelayMs?.() : void 0;
-		const scheduleDelay = typeof quick === "number" && quick >= 0 ? Math.min(quick, baseDelay) : baseDelay;
-		const phaseDelay = Math.max(0, phase.nextRetryAt - now());
+		const quick = attempt === 0 ? fastDelay() : void 0;
+		const scheduleDelay = quick === void 0 ? baseDelay : Math.min(quick, baseDelay);
+		const phaseDelay = phase.backoffHint ? Math.max(0, phase.nextRetryAt - now()) : 0;
 		const delay = Math.max(scheduleDelay, phaseDelay);
 		options.onScheduled?.(attempt + 1, delay);
 		if (phase.backoffHint && phaseDelay > scheduleDelay) options.onHintApplied?.(delay, phase.backoffHint.source);
+		firesAt = now() + delay;
 		timer = setTimer(() => {
 			timer = void 0;
 			if (detached) return;
 			if (options.kernel.phase.kind !== "offline") return;
 			attempt += 1;
 			options.onFire?.(attempt);
-			options.kernel.dispatch({ type: "USER_RETRY" });
+			options.kernel.dispatch(ownRetry);
 		}, delay);
 	}
-	const unsubKernel = options.kernel.subscribe((next, prev) => {
+	const unsubKernel = options.kernel.subscribe((next, prev, action) => {
 		if (next.kind === "offline" && prev.kind !== "offline") {
 			scheduleFromPhase(next, false);
 			return;
 		}
-		if (next.kind === "offline" && prev.kind === "offline" && next.nextRetryAt !== prev.nextRetryAt) {
-			scheduleFromPhase(next, true);
+		if (next.kind === "offline" && prev.kind === "offline" && next.backoffHint !== prev.backoffHint) {
+			if (next.backoffHint && next.nextRetryAt > firesAt) scheduleFromPhase(next, true);
 			return;
 		}
-		if (prev.kind === "offline" && next.kind !== "offline") cancelTimer("phase-left-offline");
+		if (prev.kind === "offline" && next.kind !== "offline") {
+			cancelTimer("phase-left-offline");
+			if (action.type === "USER_RETRY" && action !== ownRetry && fastDelay() !== void 0) attempt = 0;
+		}
 		if (next.kind === "online" || next.kind === "idle") attempt = 0;
 	});
 	if (options.kernel.phase.kind === "offline") scheduleFromPhase(options.kernel.phase, false);
@@ -450,7 +477,16 @@ function attachCrossTab(options) {
 			return;
 		}
 		if (!parsed?.tokens?.access) return;
-		if (options.kernel.phase.kind !== "online") {
+		const payload = {
+			endpoint: parsed.endpoint,
+			tokens: parsed.tokens
+		};
+		const phase = options.kernel.phase;
+		if (options.accept && !options.accept(payload, phase.kind === "online" ? phase.target : null)) {
+			options.onTokensIgnored?.(payload);
+			return;
+		}
+		if (phase.kind !== "online") {
 			if (parsed.endpoint?.url) {
 				options.absorb?.({
 					endpoint: parsed.endpoint,
@@ -474,24 +510,37 @@ function attachCrossTab(options) {
 //#endregion
 //#region src/effects/degradedRecovery.ts
 var DEFAULT_GRACE_MS$1 = 1e4;
+var DEFAULT_MAX_BACKOFF_MS = 3e5;
 function attachDegradedRecovery(options) {
 	const graceMs = options.graceMs ?? DEFAULT_GRACE_MS$1;
+	const maxBackoffMs = options.maxBackoffMs ?? DEFAULT_MAX_BACKOFF_MS;
 	let timer = null;
 	let round = 0;
+	let backoff = 0;
+	let channels = "";
 	let detached = false;
-	function disarm() {
+	function clearTimer() {
 		if (timer !== null) {
 			clearTimeout(timer);
 			timer = null;
 		}
+	}
+	function disarm() {
+		clearTimer();
 		round = 0;
+		backoff = 0;
+		channels = "";
 	}
 	function arm() {
 		if (detached || timer !== null) return;
 		timer = setTimeout(() => {
 			timer = null;
 			escalate();
-		}, graceMs);
+		}, Math.min(graceMs * 2 ** backoff, maxBackoffMs));
+	}
+	function rearm() {
+		backoff = options.isReachable?.() ? backoff + 1 : 0;
+		arm();
 	}
 	async function escalate() {
 		if (detached || options.signal.current.kind !== "degraded") return;
@@ -503,7 +552,7 @@ function attachDegradedRecovery(options) {
 		if (outcome === "failed") {
 			if (options.isReachable?.()) {
 				options.onHold?.("probe failed but a channel is up — holding");
-				arm();
+				rearm();
 				return;
 			}
 			options.onOffline?.("degraded: endpoint unreachable");
@@ -513,13 +562,31 @@ function attachDegradedRecovery(options) {
 			});
 			return;
 		}
-		arm();
+		rearm();
+	}
+	function lostWanTarget() {
+		const phase = options.kernel.phase;
+		return phase.kind === "online" && phase.target.endpoint.mode === "direct-wan" && options.isReachable?.() === false;
+	}
+	function onDegraded(signal) {
+		const next = signal.channels.join(",");
+		if (next !== channels) {
+			channels = next;
+			if (backoff > 0) {
+				backoff = 0;
+				clearTimer();
+			}
+		}
+		if (round === 0 && lostWanTarget()) {
+			disarm();
+			escalate();
+		} else arm();
 	}
 	const unsub = options.signal.subscribe((next) => {
-		if (next.kind === "degraded") arm();
+		if (next.kind === "degraded") onDegraded(next);
 		else disarm();
 	});
-	if (options.signal.current.kind === "degraded") arm();
+	if (options.signal.current.kind === "degraded") onDegraded(options.signal.current);
 	return () => {
 		detached = true;
 		disarm();
@@ -557,19 +624,30 @@ function attachNetworkChange(options) {
 //#endregion
 //#region src/effects/persistence.ts
 var DEFAULT_KEY = "camera.ui:transport:target";
+var DEFAULT_READY_TIMEOUT_MS = 3e3;
 function attachPersistence(options) {
 	const key = options.key ?? DEFAULT_KEY;
 	const onError = options.onError ?? (() => {});
+	const readyTimeoutMs = options.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS;
 	let detached = false;
 	let cached = null;
-	restore();
+	let readyTimer;
+	let settleReady;
+	const ready = new Promise((resolve) => {
+		settleReady = () => {
+			clearTimeout(readyTimer);
+			resolve();
+		};
+	});
+	if (readyTimeoutMs > 0 && Number.isFinite(readyTimeoutMs)) readyTimer = setTimeout(settleReady, readyTimeoutMs);
+	restore().then(settleReady, settleReady);
 	async function restore() {
-		let raw;
-		try {
+		let raw = null;
+		for (let attempt = 0; attempt < 2; attempt++) try {
 			raw = await options.storage.get(key);
+			break;
 		} catch (err) {
 			onError("get", err);
-			raw = null;
 		}
 		if (detached) return;
 		if (cached !== null) {
@@ -625,10 +703,11 @@ function attachPersistence(options) {
 	}
 	const unsub = options.kernel.subscribe((next, prev) => {
 		if (detached) return;
-		if (next.kind === "discovering" && next.pendingTokens && (prev.kind !== "discovering" || prev.pendingTokens !== next.pendingTokens)) {
+		const pending = pendingTokensOf(next);
+		if (pending && pending !== pendingTokensOf(prev)) {
 			if (cached) persist({
 				endpoint: cached.endpoint,
-				tokens: next.pendingTokens
+				tokens: pending
 			});
 			return;
 		}
@@ -643,8 +722,10 @@ function attachPersistence(options) {
 	return {
 		detach: () => {
 			detached = true;
+			settleReady();
 			unsub();
 		},
+		ready,
 		peek: () => cached,
 		seed: async (target) => {
 			if (detached) return;
@@ -656,8 +737,14 @@ function attachPersistence(options) {
 		}
 	};
 }
-function localStorageAdapter(scope = globalThis.localStorage) {
-	if (!scope) throw new Error("localStorageAdapter: localStorage is not available in this environment");
+function pendingTokensOf(phase) {
+	return phase.kind === "discovering" || phase.kind === "offline" ? phase.pendingTokens : void 0;
+}
+function localStorageAdapter(scope) {
+	if (!scope) try {
+		scope = globalThis.localStorage;
+	} catch {}
+	if (!scope) return memoryStorageAdapter();
 	return {
 		get(k) {
 			return scope.getItem(k);
@@ -730,10 +817,18 @@ function makeProbeFailure(kind, message) {
 function isProbeFailure(err) {
 	return err instanceof Error && typeof err.kind === "string";
 }
+var CANCELED_RERUN_MS = 200;
+var MAX_CANCELED_ROUNDS = 3;
 function attachProbeLoop(options) {
 	let masterAbort;
 	let detached = false;
+	let canceledRounds = 0;
+	let rerunTimer;
 	function cancel() {
+		if (rerunTimer !== void 0) {
+			clearTimeout(rerunTimer);
+			rerunTimer = void 0;
+		}
 		if (masterAbort) {
 			masterAbort.abort();
 			masterAbort = void 0;
@@ -744,6 +839,8 @@ function attachProbeLoop(options) {
 		cancel();
 		const ctrl = new AbortController();
 		masterAbort = ctrl;
+		const startPhase = options.kernel.phase;
+		const pendingAtStart = startPhase.kind === "discovering" ? startPhase.pendingTokens : void 0;
 		let pool;
 		try {
 			options.onDiscoverStart?.();
@@ -770,6 +867,10 @@ function attachProbeLoop(options) {
 			});
 			return;
 		}
+		if (options.ready) {
+			await options.ready().catch(() => void 0);
+			if (ctrl.signal.aborted) return;
+		}
 		const lastTokens = options.lastTarget?.()?.tokens;
 		const candidates = pool.map((endpoint) => ({
 			endpoint,
@@ -795,7 +896,7 @@ function attachProbeLoop(options) {
 			}
 		}));
 		try {
-			const { endpoint, value: tokens } = await raceFirst(candidates, {
+			const { endpoint, value } = await raceFirst(candidates, {
 				timeoutByMode: options.timeoutByMode,
 				parentSignal: ctrl.signal,
 				prefer: options.prefer,
@@ -804,6 +905,9 @@ function attachProbeLoop(options) {
 				informative: (cause) => !(isProbeFailure(cause) && cause.kind === "aborted")
 			});
 			if (ctrl.signal.aborted) return;
+			const phase = options.kernel.phase;
+			const refreshed = phase.kind === "discovering" && phase.pendingTokens !== pendingAtStart ? phase.pendingTokens : void 0;
+			const tokens = value === lastTokens && refreshed ? refreshed : value;
 			options.kernel.dispatch({
 				type: "PROBE_SUCCEEDED",
 				endpoint,
@@ -812,13 +916,15 @@ function attachProbeLoop(options) {
 		} catch (err) {
 			if (ctrl.signal.aborted) return;
 			const underlying = err instanceof RaceFirstError ? err.cause : err;
-			if (isProbeFailure(underlying) && underlying.kind === "aborted") {
-				setTimeout(() => {
+			const allCanceled = isProbeFailure(underlying) && underlying.kind === "aborted";
+			if (allCanceled && ++canceledRounds < MAX_CANCELED_ROUNDS) {
+				rerunTimer = setTimeout(() => {
+					rerunTimer = void 0;
 					if (!detached && options.kernel.phase.kind === "discovering") runRound();
-				}, 200);
+				}, CANCELED_RERUN_MS);
 				return;
 			}
-			const reason = isProbeFailure(underlying) && underlying.kind === "needs-auth" ? "needs-auth" : underlying instanceof Error ? underlying.message : "all endpoints failed";
+			const reason = allCanceled ? `${underlying.message} (${canceledRounds} rounds, certificate blocked?)` : isProbeFailure(underlying) && underlying.kind === "needs-auth" ? "needs-auth" : underlying instanceof Error ? underlying.message : "all endpoints failed";
 			options.onAllFailed?.(reason);
 			options.kernel.dispatch({
 				type: "PROBE_FAILED_ALL",
@@ -827,6 +933,7 @@ function attachProbeLoop(options) {
 		}
 	}
 	const unsub = options.kernel.subscribe((next, prev) => {
+		if (next.kind !== prev.kind) canceledRounds = 0;
 		if (next.kind === "discovering" && prev.kind !== "discovering") runRound();
 		else if (next.kind !== "discovering" && prev.kind === "discovering") cancel();
 	});
@@ -842,22 +949,36 @@ function attachProbeLoop(options) {
 var DEFAULT_GRACE_MS = 5e3;
 var DEFAULT_MAX_TRANSIENT_RETRIES = 3;
 var DEFAULT_TRANSIENT_RETRY_DELAY_MS = 2e3;
+var DEFAULT_MIN_REFRESH_INTERVAL_MS = 3e4;
+var DEFAULT_REACHABLE_RETRY_DELAYS_MS = [1e4, 3e4];
+var DEFAULT_LOCK_TIMEOUT_MS = 15e3;
+var AUTH_ERROR_RETRY_GAP_MS = 5e3;
 var MAX_TIMER_DELAY_MS = 2 ** 31 - 1;
 function attachTokenLifecycle(options) {
 	const graceMs = options.graceMs ?? DEFAULT_GRACE_MS;
 	const maxTransientRetries = options.maxTransientRetries ?? DEFAULT_MAX_TRANSIENT_RETRIES;
 	const maxServerErrorRetries = options.maxServerErrorRetries ?? maxTransientRetries;
 	const transientRetryDelayMs = options.transientRetryDelayMs ?? DEFAULT_TRANSIENT_RETRY_DELAY_MS;
+	const minRefreshIntervalMs = options.minRefreshIntervalMs ?? DEFAULT_MIN_REFRESH_INTERVAL_MS;
+	const reachableRetryDelaysMs = options.reachableRetryDelaysMs?.length ? options.reachableRetryDelaysMs : DEFAULT_REACHABLE_RETRY_DELAYS_MS;
+	const lockTimeoutMs = options.lockTimeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS;
+	const lockWaitBounded = Number.isFinite(lockTimeoutMs) && lockTimeoutMs > 0;
 	const isTransient = options.isTransientError ?? (() => false);
 	const isServerError = options.isServerError ?? (() => false);
 	const now = options.now ?? (() => Date.now());
 	const setTimer = options.setTimer ?? ((cb, ms) => setTimeout(cb, ms));
 	const clearTimer = options.clearTimer ?? ((h) => clearTimeout(h));
 	let timer;
-	let inflight = false;
+	let inflight = null;
 	let detached = false;
 	let transientRetries = 0;
+	let slowRetries = 0;
+	let lastSlowFailureAt = 0;
 	let pendingAuthError = false;
+	let refreshFloorUntil;
+	let rotatedAccess;
+	let rejectedAccess;
+	let stopLockWait;
 	const cleanups = [];
 	function cancelTimer() {
 		if (timer !== void 0) {
@@ -865,11 +986,66 @@ function attachTokenLifecycle(options) {
 			timer = void 0;
 		}
 	}
+	function retryLater(reason, delayMs) {
+		cancelTimer();
+		timer = setTimer(() => {
+			timer = void 0;
+			triggerRefresh(reason);
+		}, delayMs);
+	}
+	function insideRefreshFloor() {
+		return refreshFloorUntil !== void 0 && now() < refreshFloorUntil;
+	}
+	function refreshFloorFor(tokens) {
+		const lifetimeMs = tokens.accessExpiresAt ? tokens.accessExpiresAt - now() : void 0;
+		if (lifetimeMs === void 0 || lifetimeMs <= graceMs) return minRefreshIntervalMs;
+		return Math.min(minRefreshIntervalMs, Math.max(graceMs, lifetimeMs - graceMs));
+	}
+	function needsNoRefresh(tokens) {
+		if (tokens.access === rotatedAccess && insideRefreshFloor()) return true;
+		if (tokens.access === rejectedAccess && tokens.refresh) return false;
+		return !!tokens.accessExpiresAt && tokens.accessExpiresAt > now() + graceMs;
+	}
+	function isCurrentAccess(access) {
+		const phase = options.kernel.phase;
+		return phase.kind === "online" && phase.target.tokens.access === access || options.getLatestTokens?.()?.access === access;
+	}
+	function underRefreshLock(fn) {
+		const acquire = options.acquireRefreshLock;
+		if (!acquire) return fn();
+		if (!lockWaitBounded) return acquire(fn);
+		return new Promise((resolve, reject) => {
+			const abort = new AbortController();
+			let waiting = true;
+			function stopWaiting() {
+				waiting = false;
+				clearTimer(handle);
+				if (stopLockWait === giveUp) stopLockWait = void 0;
+			}
+			function giveUp() {
+				if (!waiting) return;
+				stopWaiting();
+				abort.abort();
+				resolve(null);
+			}
+			const handle = setTimer(giveUp, Math.min(lockTimeoutMs, MAX_TIMER_DELAY_MS));
+			stopLockWait = giveUp;
+			acquire(() => {
+				if (!waiting) return Promise.resolve(null);
+				stopWaiting();
+				return fn();
+			}, abort.signal).then(resolve, (err) => {
+				stopWaiting();
+				reject(err);
+			});
+		});
+	}
 	function schedule(target) {
 		cancelTimer();
 		const exp = target.tokens.accessExpiresAt;
 		if (!exp) return;
-		const delayMs = Math.min(Math.max(0, exp - now() - graceMs), MAX_TIMER_DELAY_MS);
+		const floorAt = refreshFloorUntil ?? 0;
+		const delayMs = Math.min(Math.max(0, exp - now() - graceMs, floorAt - now()), MAX_TIMER_DELAY_MS);
 		options.onScheduled?.(delayMs, exp);
 		timer = setTimer(() => {
 			timer = void 0;
@@ -879,25 +1055,28 @@ function attachTokenLifecycle(options) {
 	async function triggerRefresh(reason) {
 		if (detached) {
 			options.onTriggerSkipped?.(reason, "detached", options.kernel.phase.kind);
-			return;
+			return false;
 		}
 		if (inflight) {
 			if (reason === "auth-error") pendingAuthError = true;
 			options.onTriggerSkipped?.(reason, "already-inflight", options.kernel.phase.kind);
-			return;
+			return inflight;
 		}
 		const phase = options.kernel.phase;
 		const target = phase.kind === "online" ? phase.target : null;
 		if (!target) {
 			options.onTriggerSkipped?.(reason, "no-target", phase.kind);
-			return;
+			return false;
 		}
-		inflight = true;
+		let settle;
+		let tokenComing = false;
+		let lockTimedOut = false;
+		inflight = new Promise((resolve) => settle = resolve);
 		options.onRefreshStart?.(reason);
 		try {
-			const result = await (options.acquireRefreshLock ?? ((fn) => fn()))(async () => {
+			let result = await underRefreshLock(async () => {
 				const fresh = options.getLatestTokens?.();
-				if (fresh?.accessExpiresAt && fresh.accessExpiresAt > now() + graceMs) {
+				if (fresh && needsNoRefresh(fresh)) {
 					options.kernel.dispatch({
 						type: "TOKENS_REFRESHED",
 						tokens: fresh
@@ -927,16 +1106,34 @@ function attachTokenLifecycle(options) {
 					skipped: false
 				};
 			});
-			if (detached) return;
+			if (detached) return false;
+			if (!result) {
+				const fresh = options.getLatestTokens?.();
+				if (!fresh || !needsNoRefresh(fresh)) {
+					lockTimedOut = true;
+					throw new Error(`refresh lock not granted within ${lockTimeoutMs} ms`);
+				}
+				options.kernel.dispatch({
+					type: "TOKENS_REFRESHED",
+					tokens: fresh
+				});
+				result = {
+					tokens: fresh,
+					skipped: true
+				};
+			}
 			transientRetries = 0;
+			slowRetries = 0;
+			const live = options.kernel.phase;
+			tokenComing = live.kind === "online" && live.target.tokens.access !== target.tokens.access;
 			if (result.skipped) {
 				options.onRefreshSkipped?.(reason, result.tokens);
 				const p = options.kernel.phase;
 				if (p.kind === "online" && timer === void 0) schedule(p.target);
 			} else options.onRefreshSuccess?.(reason, result.tokens);
 		} catch (err) {
-			if (detached) return;
-			const transient = isTransient(err);
+			if (detached) return false;
+			const transient = lockTimedOut || isTransient(err);
 			const serverError = transient && isServerError(err);
 			const budget = serverError ? maxServerErrorRetries : maxTransientRetries;
 			if (transient && transientRetries < budget) {
@@ -948,13 +1145,22 @@ function attachTokenLifecycle(options) {
 					retriesLeft,
 					willRetry: true
 				});
-				cancelTimer();
-				timer = setTimer(() => {
-					timer = void 0;
-					triggerRefresh(reason);
-				}, transientRetryDelayMs);
+				tokenComing = true;
+				retryLater(reason, transientRetryDelayMs);
+			} else if (transient && options.isReachable?.() === true) {
+				const delayMs = reachableRetryDelaysMs[Math.min(slowRetries, reachableRetryDelaysMs.length - 1)];
+				slowRetries++;
+				lastSlowFailureAt = now();
+				options.onRefreshError?.(reason, err, {
+					transient: true,
+					serverError,
+					retriesLeft: 0,
+					willRetry: true
+				});
+				retryLater(reason, delayMs);
 			} else {
 				transientRetries = 0;
+				slowRetries = 0;
 				options.onRefreshError?.(reason, err, {
 					transient,
 					serverError,
@@ -968,28 +1174,45 @@ function attachTokenLifecycle(options) {
 				});
 			}
 		} finally {
-			inflight = false;
+			inflight = null;
+			settle(tokenComing);
 			if (!detached && pendingAuthError) {
 				pendingAuthError = false;
-				triggerRefresh("auth-error");
+				triggerOnAuthError();
 			}
 		}
+		return tokenComing;
+	}
+	function triggerOnAuthError() {
+		if (slowRetries > 0 && now() - lastSlowFailureAt < AUTH_ERROR_RETRY_GAP_MS) {
+			options.onTriggerSkipped?.("auth-error", "throttled", options.kernel.phase.kind);
+			return Promise.resolve(false);
+		}
+		return triggerRefresh("auth-error");
 	}
 	const unsubKernel = options.kernel.subscribe((next, prev) => {
 		if (next.kind === "online") {
 			if (prev.kind !== "online" || prev.target.tokens.access !== next.target.tokens.access) {
+				if (prev.kind === "online") {
+					refreshFloorUntil = now() + refreshFloorFor(next.target.tokens);
+					rotatedAccess = next.target.tokens.access;
+				}
 				transientRetries = 0;
+				slowRetries = 0;
 				schedule(next.target);
 			}
 		} else {
 			cancelTimer();
 			transientRetries = 0;
+			slowRetries = 0;
 		}
 	});
 	cleanups.push(unsubKernel);
 	for (const transport of options.transports) {
-		const off = transport.on("auth-error", () => {
-			triggerRefresh("auth-error");
+		const off = transport.on("auth-error", (event) => {
+			if (event.access && isCurrentAccess(event.access)) rejectedAccess = event.access;
+			const refresh = triggerOnAuthError();
+			event.holdFor?.(refresh);
 		});
 		cleanups.push(off);
 	}
@@ -997,6 +1220,7 @@ function attachTokenLifecycle(options) {
 	function detach() {
 		detached = true;
 		cancelTimer();
+		stopLockWait?.();
 		for (const fn of cleanups) fn();
 	}
 	function wake() {
@@ -1019,7 +1243,12 @@ function attachTokenLifecycle(options) {
 			return;
 		}
 		const remaining = exp - now();
-		if (remaining < graceMs) {
+		if (remaining < graceMs && insideRefreshFloor()) options.onWakeChecked?.({
+			decision: "throttled",
+			remainingMs: remaining,
+			phase: phase.kind
+		});
+		else if (remaining < graceMs) {
 			options.onWakeChecked?.({
 				decision: "refresh-now",
 				remainingMs: remaining,
@@ -1037,6 +1266,24 @@ function attachTokenLifecycle(options) {
 		wake
 	};
 }
+function localAccessExpiry(access, serverExpiresAt, receivedAt = Date.now()) {
+	const claims = decodeJwtClaims(access);
+	const iat = claims?.iat;
+	const exp = claims?.exp;
+	if (typeof iat === "number" && typeof exp === "number" && exp > iat) return receivedAt + (exp - iat) * 1e3;
+	return serverExpiresAt;
+}
+function decodeJwtClaims(token) {
+	const payload = token.split(".")[1];
+	if (!payload) return null;
+	try {
+		const base64 = payload.replace(/-/g, "+").replace(/_/g, "/");
+		const claims = JSON.parse(atob(base64.padEnd(Math.ceil(base64.length / 4) * 4, "=")));
+		return typeof claims === "object" && claims !== null ? claims : null;
+	} catch {
+		return null;
+	}
+}
 function stringifyError(err) {
 	if (err instanceof Error) return err.message;
 	if (typeof err === "string") return err;
@@ -1065,10 +1312,9 @@ function attachTransportSync(options) {
 		applied.set(transport, target);
 		transport.apply(target).catch((err) => {
 			options.onError?.(transport, target, err);
-			if (applied.get(transport) === target) {
-				applied.delete(transport);
-				scheduleRetry(transport);
-			}
+			if (applied.get(transport) !== target || refusedByServer(err)) return;
+			applied.delete(transport);
+			scheduleRetry(transport);
 		});
 	}
 	function scheduleRetry(transport) {
@@ -1134,17 +1380,22 @@ function attachWorkerBridge(options) {
 		if (detached) return;
 		const msg = makeSync(phase);
 		let count = 0;
-		for (const host of options.hosts()) try {
-			host.postMessage(msg);
-			count++;
-			maybeAttachHostListener(host);
-		} catch (err) {
-			log.warn("broadcast postMessage failed", {
-				gen: msg.generation,
-				phase: phase.kind,
-				err
-			});
+		const present = /* @__PURE__ */ new Set();
+		for (const host of options.hosts()) {
+			present.add(host);
+			try {
+				host.postMessage(msg);
+				count++;
+				maybeAttachHostListener(host);
+			} catch (err) {
+				log.warn("broadcast postMessage failed", {
+					gen: msg.generation,
+					phase: phase.kind,
+					err
+				});
+			}
 		}
+		forgetDeparted(present);
 		options.onBroadcast?.(generation, count);
 	}
 	function syncOne(host) {
@@ -1207,6 +1458,13 @@ function attachWorkerBridge(options) {
 			host.removeEventListener?.("message", listener);
 		});
 	}
+	function forgetHost(host) {
+		hostListenerCleanups.get(host)?.();
+		hostListenerCleanups.delete(host);
+	}
+	function forgetDeparted(present) {
+		for (const host of hostListenerCleanups.keys()) if (!present.has(host)) forgetHost(host);
+	}
 	const unsubKernel = options.kernel.subscribe((next) => {
 		broadcast(next);
 	});
@@ -1225,13 +1483,19 @@ function attachWorkerBridge(options) {
 		},
 		revalidateWorkers() {
 			if (detached) return;
-			for (const host of options.hosts()) try {
-				host.postMessage({ type: "kernel-revalidate" });
-				maybeAttachHostListener(host);
-			} catch (err) {
-				log.warn("revalidate postMessage failed", err);
+			const present = /* @__PURE__ */ new Set();
+			for (const host of options.hosts()) {
+				present.add(host);
+				try {
+					host.postMessage({ type: "kernel-revalidate" });
+					maybeAttachHostListener(host);
+				} catch (err) {
+					log.warn("revalidate postMessage failed", err);
+				}
 			}
-		}
+			forgetDeparted(present);
+		},
+		forgetHost
 	};
 }
 //#endregion
@@ -1309,18 +1573,22 @@ function createConnectionJournal(options = {}) {
 //#endregion
 //#region src/signal.ts
 var DEFAULT_DEBOUNCE_MS = 1500;
+var DEFAULT_FIRST_CONNECT_TIMEOUT_MS = 15e3;
 function signalEquals(a, b) {
 	if (a.kind !== b.kind) return false;
-	if (a.kind === "degraded" && b.kind === "degraded") return a.channels.join(",") === b.channels.join(",");
+	if (a.kind === "degraded" && b.kind === "degraded") return a.reason === b.reason && a.channels.join(",") === b.channels.join(",");
 	if (a.kind === "offline" && b.kind === "offline") return a.retryAt === b.retryAt;
 	return true;
 }
 function createConnectionSignal(options) {
 	const debounceMs = options.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+	const firstConnectTimeoutMs = options.firstConnectTimeoutMs ?? DEFAULT_FIRST_CONNECT_TIMEOUT_MS;
 	const listeners = /* @__PURE__ */ new Set();
 	const cleanups = [];
 	let hasBeenOnline = false;
 	let anyChannelEverUp = false;
+	let firstConnectOverdue = false;
+	let firstConnectTimer = null;
 	let pendingTimer = null;
 	let pendingSignal = null;
 	let disposed = false;
@@ -1337,14 +1605,38 @@ function createConnectionSignal(options) {
 			case "online": {
 				const channels = options.transports.filter((t) => t.spec.phaseGating && !t.health().up).map((t) => t.spec.id);
 				if (channels.length === 0) return { kind: "online" };
-				return anyChannelEverUp ? {
+				if (anyChannelEverUp) return {
 					kind: "degraded",
 					channels
+				};
+				return firstConnectOverdue ? {
+					kind: "degraded",
+					channels,
+					reason: "first-connect"
 				} : { kind: "connecting" };
 			}
 		}
 	}
 	let current = compute();
+	function clearFirstConnectTimer() {
+		if (firstConnectTimer !== null) {
+			clearTimeout(firstConnectTimer);
+			firstConnectTimer = null;
+		}
+	}
+	function watchFirstConnect() {
+		if (options.kernel.phase.kind !== "online" || anyChannelEverUp) {
+			clearFirstConnectTimer();
+			firstConnectOverdue = false;
+			return;
+		}
+		if (firstConnectTimer !== null || firstConnectOverdue || !(firstConnectTimeoutMs > 0 && Number.isFinite(firstConnectTimeoutMs))) return;
+		firstConnectTimer = setTimeout(() => {
+			firstConnectTimer = null;
+			firstConnectOverdue = true;
+			apply(compute());
+		}, firstConnectTimeoutMs);
+	}
 	function clearPending() {
 		if (pendingTimer !== null) {
 			clearTimeout(pendingTimer);
@@ -1390,15 +1682,18 @@ function createConnectionSignal(options) {
 			hasBeenOnline = false;
 			anyChannelEverUp = false;
 		}
+		watchFirstConnect();
 		recompute();
 	}));
 	for (const transport of options.transports) {
 		cleanups.push(transport.on("up", () => {
 			anyChannelEverUp = true;
+			watchFirstConnect();
 			recompute();
 		}));
 		cleanups.push(transport.on("down", () => recompute()));
 	}
+	watchFirstConnect();
 	return {
 		get current() {
 			return current;
@@ -1412,10 +1707,11 @@ function createConnectionSignal(options) {
 		dispose() {
 			disposed = true;
 			clearPending();
+			clearFirstConnectTimer();
 			for (const fn of cleanups) fn();
 			listeners.clear();
 		}
 	};
 }
 //#endregion
-export { TransportEmitter, attachBackoff, attachCrossTab, attachDegradedRecovery, attachNetworkChange, attachPersistence, attachPresence, attachProbeLoop, attachTokenLifecycle, attachTransportSync, attachWorkerBridge, classifyClose, createBackgroundProbe, createConnectionJournal, createConnectionSignal, createKernel, isEndpointChange, isProbeFailure, isSameTarget, localStorageAdapter, makeProbeFailure, memoryStorageAdapter, raceFirst, reducer };
+export { TransportEmitter, attachBackoff, attachCrossTab, attachDegradedRecovery, attachNetworkChange, attachPersistence, attachPresence, attachProbeLoop, attachTokenLifecycle, attachTransportSync, attachWorkerBridge, classifyClose, createBackgroundProbe, createConnectionJournal, createConnectionSignal, createKernel, isEndpointChange, isProbeFailure, isSameTarget, localAccessExpiry, localStorageAdapter, makeProbeFailure, memoryStorageAdapter, raceFirst, reducer };