@wildo-ai/saas-frontend-lib 1.0.1 → 1.1.0

package/dist/esm/core/requests/wildo-http-client.frontend.service.js

@@ -1,10 +1,15 @@
 import axios from 'axios';
 import { z } from 'zod';
-import { HttpStatusCode, WildoHeaderKeys } from '@wildo-ai/saas-models';
+import { HttpStatusCode, WildoHeaderKeys, summarizeZodIssues } from '@wildo-ai/saas-models';
 import { envLoader } from '../../core/runtime/env-variable-loader.frontend.service.js';
 import { LoggerFrontendService } from '../../core/monitoring/logger.frontend.service.js';
 import { getReadinessChecker } from './api-readiness-checker.frontend.service.js';
+import { getClientInstanceId } from './client-instance-id.frontend.service.js';
+import { isAuthoritativeRefreshRejection, isRefreshDevLenient, RENEWAL_TRANSIENTLY_FAILED_MARKER } from './auth-refresh-resilience.frontend.js';
 import { errorManagement } from '../../core/errors/error-management.frontend.service.js';
+import { isAbortOrCancelError } from './request-cancellation.frontend.utils.js';
+import { fullJitterBackoffMs, recoveryOffsetMs, staggerGapMs, sleep } from './network-backoff.frontend.utils.js';
+import { OfflineReplayPolicy, NetworkOfflineError, NetworkOfflineReason, defaultOfflineReplayPolicyForMethod, isNetworkOfflineRejection, } from './offline-replay-policy.frontend.js';
 import { frontendEventBus } from '../../core/events/event-bus.frontend.service.js';
 import { FrontendEvents } from '../../core/events/events.frontend.schemas.js';
 /**
@@ -28,11 +33,37 @@ export class WildoBackendHttpClient {
     isQueueProcessing = false;
     requestQueue = [];
     queueInterval = null;
+    // Anti-herd: whether the per-client recovery offset has already been applied
+    // to the CURRENT backlog. Set on the first drain after connectivity returns,
+    // reset whenever the queue is empty or the client is offline — so each distinct
+    // offline→online recovery re-rolls its own offset. (A steady online trickle
+    // never queues in the first place — requests only enqueue while offline — so
+    // this only re-rolls across genuine connectivity flaps, which is intended.)
+    queueRecoveryOffsetApplied = false;
     // Logging
     logger;
     logDebug;
     // Readiness checker
     readinessChecker;
+    /**
+     * In-flight GET sharing (audit I1). One resource-detail mount fires ~9 GETs
+     * from 7 independent consumers (header label, breadcrumb label, displayer
+     * read, RMM canonical seed, form canonical reads, read-backs) — several of
+     * them byte-identical requests in the same tick. Concurrent identical GETs
+     * (same URL + query params + silent flag) share ONE network flight; each
+     * participant receives its own `structuredClone` of the payload so no caller
+     * can observe another caller's mutations of the response.
+     *
+     * Deliberately conservative:
+     * - IN-FLIGHT sharing only — the entry is deleted the moment the flight
+     *   settles. There is NO cross-time cache / TTL, so correctness is unaffected.
+     * - GETs only. Mutations (POST/PUT/PATCH/DELETE) never dedup.
+     * - Requests carrying an `AbortSignal`, custom `headers`, or a
+     *   `responseType` bypass sharing entirely: a joiner must never be aborted
+     *   by another caller's signal (nor keep a flight alive past its own abort),
+     *   and header/response-type variance means the requests are not identical.
+     */
+    inflightGetRequests = new Map();
     // Frontend service identity cached at construction from VITE_FRONTEND_SERVICE_NAME.
     // Injected as X-Frontend-Service-Name header on every request.
     frontendServiceName;
@@ -53,8 +84,12 @@ export class WildoBackendHttpClient {
             timeout: 30000,
             maxConcurrentRequests: 30,
             retryDelay: 1000,
+            retryMaxDelayMs: 30000,
+            maxRetryAfterDelayMs: 30000,
             enableNetworkQueue: true,
             queueProcessInterval: 1000,
+            queueEntryTtlMs: 60000,
+            readinessWaitTimeoutMs: 10000,
             // Use environment variable as default, but allow override via config
             baseURL: config.baseURL || envConfig.apiBaseUrl,
             ...config,
@@ -87,11 +122,32 @@ export class WildoBackendHttpClient {
      * Setup sophisticated request and response interceptors
      */
     setupInterceptors() {
-        // Request interceptors (order matters - last added runs first)
+        // Request interceptors. ORDER MATTERS. In the browser (Vite/ESM) runtime the
+        // app ships in, axios executes request interceptors in REGISTRATION order, so
+        // the sequence below IS the execution order: networkInterruption →
+        // concurrency → loading → auth → authCookies → dispatch. The offline-queue
+        // design depends on networkInterruption running FIRST (so a parked/rejected
+        // request never enters the downstream interceptors and takes no concurrency
+        // slot). This ordering is pinned by a test — see the axios-order pin in
+        // __tests__/wildo-http-client.offline-queue.test.ts.
+        // (Note: the axios CJS build runs them in REVERSE; the browser runtime does
+        // not, and the offline queue only runs in the browser — navigator.onLine is
+        // undefined under Node, so setupNetworkMonitoring never marks it offline.)
         this.axiosInstance.interceptors.request.use(this.networkInterruptionInterceptor.bind(this), this.requestErrorHandler.bind(this));
         this.axiosInstance.interceptors.request.use(this.concurrencyControlInterceptor.bind(this), this.requestErrorHandler.bind(this));
         this.axiosInstance.interceptors.request.use(this.loadingRequestInterceptor.bind(this), this.requestErrorHandler.bind(this));
         this.axiosInstance.interceptors.request.use(this.authenticationInterceptor.bind(this), this.requestErrorHandler.bind(this));
+        // Auth-hardening Slice A Step 3 — `__wildo_refresh` is an `HttpOnly` /
+        // `SameSite=Strict` / `Path=/api/v1/auth` cookie. Browsers only attach it to
+        // cross-origin XHRs when `withCredentials: true` is set on the request.
+        // We scope this to `/auth/*` exclusively: every other API call stays
+        // bearer-only (Authorization header) and MUST NOT carry credentials —
+        // setting `withCredentials` globally would force the strict CORS
+        // posture (`Access-Control-Allow-Credentials: true` + exact-origin
+        // match) onto every endpoint, breaking the cheaper wildcard-allowed
+        // resource APIs. The cookie's own `Path=/api/v1/auth` browser-side gate is
+        // belt-and-braces with this URL prefix check.
+        this.axiosInstance.interceptors.request.use(this.authCookiesInterceptor.bind(this), this.requestErrorHandler.bind(this));
         // Response interceptors
         this.axiosInstance.interceptors.response.use(this.responseSuccessInterceptor.bind(this), this.responseErrorInterceptor.bind(this));
     }
@@ -106,9 +162,13 @@ export class WildoBackendHttpClient {
             const handleOffline = () => {
                 this.networkConnectionState = { connected: false, connectionType: 'unknown' };
             };
-            this.networkConnectionState = globalThis.navigator.onLine
-                ? { connected: true, connectionType: 'unknown' }
-                : { connected: false, connectionType: 'unknown' };
+            // Fail-OPEN on the initial read: only an EXPLICIT `onLine === false` marks
+            // us offline. `undefined`/`null` (a runtime that exposes `navigator` but not
+            // a reliable `onLine`) must default to CONNECTED — otherwise the offline
+            // queue and mutation-reject engage spuriously. Real offline transitions
+            // still arrive via the `offline` event below.
+            const explicitlyOffline = globalThis.navigator.onLine === false;
+            this.networkConnectionState = { connected: !explicitlyOffline, connectionType: 'unknown' };
             globalThis.addEventListener('online', handleOnline);
             globalThis.addEventListener('offline', handleOffline);
         }
@@ -124,21 +184,64 @@ export class WildoBackendHttpClient {
         }
     }
     /**
-     * Process queued requests when network is available
+     * Drain the offline queue when the network is back — WITHOUT stampeding.
+     *
+     * Anti-thundering-herd shape (see network-resilience plan, D3):
+     * - **Per-client recovery offset**: on the first drain after connectivity
+     *   returns, wait a random 0–2s so N clients that were all blocked on the same
+     *   outage don't release their backlog in the same instant. Rolled once per
+     *   backlog (reset when the queue empties), never on a steady-state trickle.
+     * - **Per-release stagger**: a small random gap between successive releases so
+     *   one client's own backlog spreads over time rather than firing as a burst.
+     * - **TTL expiry**: a queued READ that outlived `queueEntryTtlMs` is rejected as
+     *   stale instead of replayed against now-ancient state.
+     *
+     * `isQueueProcessing` is held across the awaits so the 1s interval never starts
+     * a second overlapping drain.
      */
-    processRequestQueue() {
+    async processRequestQueue() {
         if (this.isQueueProcessing)
             return;
+        // Idle / offline: nothing to drain. Reset the offset latch so the NEXT
+        // outage recovery re-rolls a fresh per-client offset.
+        if (!this.networkConnectionState.connected || this.requestQueue.length === 0) {
+            this.queueRecoveryOffsetApplied = false;
+            return;
+        }
         this.isQueueProcessing = true;
-        while (this.networkConnectionState.connected &&
-            this.requestQueue.length > 0 &&
-            this.currentConcurrency <= (this.config.maxConcurrentRequests || 30)) {
-            const queuedRequest = this.requestQueue.shift();
-            if (queuedRequest) {
+        try {
+            if (!this.queueRecoveryOffsetApplied) {
+                this.queueRecoveryOffsetApplied = true;
+                await sleep(recoveryOffsetMs());
+            }
+            const ttlMs = this.config.queueEntryTtlMs ?? 60000;
+            while (this.networkConnectionState.connected &&
+                this.requestQueue.length > 0 &&
+                this.currentConcurrency <= (this.config.maxConcurrentRequests || 30)) {
+                const queuedRequest = this.requestQueue.shift();
+                if (!queuedRequest)
+                    continue;
+                // Expire stale entries rather than replaying them against now-ancient
+                // state. Rejecting the parked promise returns the offline error straight
+                // to the caller — a parked read never entered concurrencyControlInterceptor
+                // (see the enqueue note above), so there is no concurrency slot or loading
+                // event to unwind here.
+                if (Date.now() - queuedRequest.enqueuedAt > ttlMs) {
+                    const staleError = new NetworkOfflineError(NetworkOfflineReason.QUEUE_ENTRY_EXPIRED, queuedRequest.config.url);
+                    staleError.config = queuedRequest.config;
+                    queuedRequest.reject(staleError);
+                    continue;
+                }
+                // Release the request: resolving continues the interceptor chain into
+                // concurrencyControlInterceptor (++), the loading interceptor (START), auth,
+                // then dispatch — all balanced by the response interceptor on completion.
                 queuedRequest.resolve(queuedRequest.config);
+                await sleep(staggerGapMs());
             }
         }
-        this.isQueueProcessing = false;
+        finally {
+            this.isQueueProcessing = false;
+        }
     }
     /**
      * Network interruption interceptor - queues requests when offline
@@ -146,10 +249,37 @@ export class WildoBackendHttpClient {
     async networkInterruptionInterceptor(config) {
         try {
             if (!this.networkConnectionState.connected) {
-                this.logger.error('HTTP Client - network not connected', { url: config.url });
+                const options = config;
+                const policy = options.offlineReplayPolicy
+                    ?? defaultOfflineReplayPolicyForMethod(config.method);
+                // Mutations are not safe to replay (no dedup, entries never expire) — fail
+                // fast with a typed offline rejection so the caller can prompt the user to
+                // retry, rather than silently double-submitting hours later. Reads fall
+                // through to the queue. The rejection propagates to the response-error
+                // interceptor, which recognises it (isNetworkOfflineRejection), releases
+                // the concurrency slot, and short-circuits without retry/classification.
+                if (policy === OfflineReplayPolicy.REJECT_WHEN_OFFLINE) {
+                    this.logger.warn('HTTP Client - rejecting request while offline (non-replayable)', {
+                        url: config.url,
+                        method: config.method,
+                    });
+                    const offlineError = new NetworkOfflineError(NetworkOfflineReason.MUTATION_REJECTED, config.url);
+                    offlineError.config = config;
+                    return Promise.reject(offlineError);
+                }
+                this.logDebug('HTTP Client - queueing request while offline', { url: config.url });
                 if (this.config.enableNetworkQueue) {
+                    // NO concurrency bookkeeping here. In the browser (Vite/ESM) runtime the
+                    // app ships in, axios runs request interceptors in REGISTRATION order, so
+                    // this networkInterruptionInterceptor (registered first) runs BEFORE
+                    // concurrencyControlInterceptor. A parked request therefore has NOT taken
+                    // a concurrency slot yet — the increment happens later, when the request
+                    // is released from the queue and the chain continues into
+                    // concurrencyControlInterceptor. So there is no phantom slot to release
+                    // (and no deadlock), and touching currentConcurrency here would corrupt
+                    // the counter. Verified by the interceptor-ordering pin test.
                     return new Promise((resolve, reject) => {
-                        this.requestQueue.push({ resolve, reject, config });
+                        this.requestQueue.push({ resolve, reject, config, enqueuedAt: Date.now() });
                     });
                 }
             }
@@ -182,6 +312,15 @@ export class WildoBackendHttpClient {
             // which frontend originated the call. Used by auth flows for redirects
             // and email links. Value is the configured frontend service identity.
             config.headers[WildoHeaderKeys.FRONTEND_SERVICE_NAME] = this.frontendServiceName;
+            // Client-install identification — OPT-IN, default OFF (Fork D / SD9). Read PER REQUEST rather
+            // than cached at construction: this client is built during bootstrap, before the app-config that
+            // carries `compliance.clientInstanceIdScope` has been fetched, so a construction-time read would
+            // permanently latch the fail-closed default. Returns undefined unless the application opted in,
+            // in which case the header is simply never set.
+            const clientInstanceId = getClientInstanceId();
+            if (clientInstanceId) {
+                config.headers[WildoHeaderKeys.CLIENT_INSTANCE_ID] = clientInstanceId;
+            }
             // W7.3a: Inject anonymous session headers when no auth token is present.
             // First request uses x-anonymous-session-init (raw UUID), subsequent use x-anonymous-session (JWT).
             if (!this.authToken && this.anonymousUserId) {
@@ -203,6 +342,26 @@ export class WildoBackendHttpClient {
             return config;
         }
     }
+    /**
+     * Auth-hardening Slice A Step 3 — request interceptor that enables
+     * `withCredentials: true` ONLY on `/auth/*` requests so the browser
+     * attaches the `__wildo_refresh` `HttpOnly` cookie to refresh / logout
+     * / authenticate / token-exchange round-trips. The check matches both
+     * relative (`/api/v1/auth/...`) and absolute URLs that contain `/auth/`
+     * as a path segment. All other requests stay bearer-only.
+     *
+     * NOTE: We deliberately do NOT enable `withCredentials` for non-auth
+     * routes — the rest of the API contract is bearer-only and the strict
+     * CORS-with-credentials posture would force every endpoint to switch
+     * from wildcard to exact-origin matching, breaking integrations.
+     */
+    authCookiesInterceptor(config) {
+        const url = config.url ?? '';
+        if (url.includes('/auth/')) {
+            config.withCredentials = true;
+        }
+        return config;
+    }
     /**
      * Request interceptor: emit LOADING_*_START if loading config is present.
      * Marks the config so the response interceptor knows to emit END.
@@ -296,9 +455,9 @@ export class WildoBackendHttpClient {
         return response.data;
     }
     /**
-     * Check if error should be retried (500 errors or network errors)
-     * Note: Retries are disabled in development mode by default (retryAttempts=0)
-     * to avoid log spam during debugging. This can be overridden via config.
+     * Check if error should be retried (500 errors, 429s with configured retry
+     * attempts, or network errors). Retries are disabled in development mode by
+     * default (retryAttempts=0) to avoid log spam during debugging.
      */
     shouldRetry(error) {
         // Don't retry if no config (can't retry without request config)
@@ -324,6 +483,14 @@ export class WildoBackendHttpClient {
             if (status >= 500 && status < 600) {
                 return true;
             }
+            if (status === HttpStatusCode.TOO_MANY_REQUESTS) {
+                const retryAfterDelay = this.getRetryAfterDelay(error);
+                const maxRetryAfterDelayMs = this.config.maxRetryAfterDelayMs ?? 30000;
+                return retryAfterDelay === undefined || retryAfterDelay <= maxRetryAfterDelayMs;
+            }
+            if (status === 408) {
+                return true;
+            }
             // Don't retry client errors (400-499) except 408 (Request Timeout)
             if (status >= 400 && status < 500 && status !== 408) {
                 return false;
@@ -352,18 +519,141 @@ export class WildoBackendHttpClient {
         }
         return false;
     }
+    getRetryAfterDelay(error) {
+        // `Retry-After` is a server back-pressure signal defined for BOTH 429 (rate
+        // limit) and 503 (service unavailable / warming up). Honoring it on 503 lets
+        // a load-shedding or just-restarted backend tell every client exactly when to
+        // come back — the single most effective cross-client de-herd lever, because
+        // the server dictates the spread instead of each client guessing. The value
+        // is clamped to `maxRetryAfterDelayMs` at the call site so a hostile/huge
+        // header can't park a request indefinitely.
+        const status = error?.response?.status;
+        if (status !== HttpStatusCode.TOO_MANY_REQUESTS && status !== HttpStatusCode.SERVICE_UNAVAILABLE) {
+            return undefined;
+        }
+        const headers = error.response.headers ?? {};
+        const retryAfterHeader = headers['retry-after'] ?? headers['Retry-After'];
+        const retryAfterFromHeader = this.parseRetryAfterHeader(retryAfterHeader);
+        if (retryAfterFromHeader !== undefined) {
+            return retryAfterFromHeader;
+        }
+        const details = error.response.data?.error?.details ?? error.response.data?.error?.context ?? error.context;
+        const retryAfterSeconds = details?.retryAfterSeconds ?? details?.retryAfter;
+        if ((typeof retryAfterSeconds === 'number' || typeof retryAfterSeconds === 'string')
+            && retryAfterSeconds !== '') {
+            const parsedRetryAfterSeconds = Number(retryAfterSeconds);
+            if (Number.isFinite(parsedRetryAfterSeconds)) {
+                return Math.max(0, parsedRetryAfterSeconds * 1000);
+            }
+        }
+        const resetHeader = headers[WildoHeaderKeys.RATE_LIMIT_RESET] ?? headers['X-RateLimit-Reset'];
+        const retryAfterFromResetHeader = this.parseRateLimitResetHeader(resetHeader);
+        if (retryAfterFromResetHeader !== undefined) {
+            return retryAfterFromResetHeader;
+        }
+        return undefined;
+    }
+    parseRateLimitResetHeader(value) {
+        const header = Array.isArray(value) ? value[0] : value;
+        if (typeof header !== 'string' || header.trim() === '') {
+            return undefined;
+        }
+        const numericValue = Number(header);
+        if (Number.isFinite(numericValue)) {
+            // Wildo currently sends seconds-until-reset. Some external APIs send
+            // epoch seconds, so support both shapes for future compatibility.
+            if (numericValue > 1_000_000_000) {
+                return Math.max(0, numericValue * 1000 - Date.now());
+            }
+            return Math.max(0, numericValue * 1000);
+        }
+        const retryAt = Date.parse(header);
+        if (Number.isFinite(retryAt)) {
+            return Math.max(0, retryAt - Date.now());
+        }
+        return undefined;
+    }
+    parseRetryAfterHeader(value) {
+        const header = Array.isArray(value) ? value[0] : value;
+        if (typeof header !== 'string' || header.trim() === '') {
+            return undefined;
+        }
+        const numericSeconds = Number(header);
+        if (Number.isFinite(numericSeconds)) {
+            return Math.max(0, numericSeconds * 1000);
+        }
+        const retryAt = Date.parse(header);
+        if (Number.isFinite(retryAt)) {
+            return Math.max(0, retryAt - Date.now());
+        }
+        return undefined;
+    }
     /**
-     * Calculate exponential backoff delay
+     * Jittered exponential backoff delay for a retry attempt (AWS "full jitter":
+     * a uniformly random value in [0, min(cap, base·2^attempt)]).
+     *
+     * The jitter is deliberate anti-thundering-herd: without it, every client that
+     * failed a request against a downed backend on the same round would retry at
+     * the identical 1s / 2s / 4s marks and re-collide on every round. Full jitter
+     * de-correlates them so recovery load spreads instead of pulsing.
+     *
+     * @param attempt Zero-based attempt index (0 = first retry).
      */
-    calculateRetryDelay(retryCount) {
+    calculateRetryDelay(attempt) {
         const baseDelay = this.config.retryDelay || 1000;
-        return baseDelay * Math.pow(2, retryCount);
+        const capMs = this.config.retryMaxDelayMs ?? 30000;
+        return fullJitterBackoffMs(attempt, baseDelay, capMs);
     }
     /**
      * Response error interceptor - handles errors, token renewal, and retries
      */
     async responseErrorInterceptor(error) {
         this.currentConcurrency--;
+        // ── Intentional cancellations are NOT transport failures ─────────────────
+        // A request aborted via `AbortController.abort()` — a superseded refetch, a
+        // component unmount, React StrictMode's mount→unmount→mount — rejects with an
+        // axios `CanceledError` (`__CANCEL__: true`, `code: 'ERR_CANCELED'`, and
+        // crucially NO `error.response`). Left unguarded, it falls all the way through
+        // to `handleHttpError`, which — seeing no `error.response` — resolves
+        // `getNetworkErrorBehavior()` and emits an `ERROR_OCCURED` for a HIGH-severity
+        // `{ errorType: NETWORK, httpStatus: undefined }` fault: a global "Network
+        // connectivity issue" toast PLUS a persistent notification-center entry.
+        //
+        // THAT misclassification is the real root cause of the spurious chart
+        // "Network connectivity issue" errors: a chart aborts its in-flight POST on
+        // every refetch/remount, and each abort was being reported as a connectivity
+        // failure even though nothing failed. It is framework-wide — every cancellable
+        // consumer (chart data, file upload, async uniqueness validation) had to add
+        // its OWN local cancel filter to paper over it. This is the single correct
+        // boundary for the concern: a cancellation is caller-initiated and must be
+        // invisible. Clear any loading state and reject the promise UNCHANGED (callers
+        // can still detect the cancel via `axios.isCancel` / `ERR_CANCELED` and ignore
+        // it), but never classify, emit, log, or retry it. The per-consumer guards
+        // remain as defense-in-depth; they simply no longer have a global toast to
+        // race against. `isAbortOrCancelError` is the shared cancel predicate (it
+        // matches the axios `CanceledError` shape AND the DOM `AbortError`), used
+        // identically here, in the RMM transport adapter, and in per-consumer guards.
+        if (isAbortOrCancelError(error)) {
+            if (error?.config)
+                this.emitLoadingEnd(error.config);
+            return Promise.reject(error);
+        }
+        // ── Offline rejections are policy decisions, NOT transport failures ───────
+        // A mutation rejected while offline, or a queued read that expired past its
+        // TTL, rejects with a `NetworkOfflineError`. In the browser (Vite/ESM) runtime
+        // the app ships in, a request-interceptor rejection returns straight to the
+        // caller and does NOT reach this response handler — so for the common case
+        // this guard is defense-in-depth, not the primary path. It matters in any
+        // runtime whose axios routes request-interceptor rejections through the
+        // response chain (the CJS build does): there it prevents the offline error
+        // from being retried (its message must never be mistaken for a network fault
+        // by `shouldRetry`) or classified into a global NETWORK toast. Either way the
+        // connectivity layer owns offline UX (one banner), not this per-request path.
+        if (isNetworkOfflineRejection(error)) {
+            if (error.config)
+                this.emitLoadingEnd(error.config);
+            return Promise.reject(error);
+        }
         this.logDebug('Response error interceptor', {
             url: error.config?.url,
             status: error.response?.status,
@@ -372,6 +662,31 @@ export class WildoBackendHttpClient {
             code: error.code,
             retryCount: error.config?.__retryCount || 0,
         });
+        // ── Backend unreachable ⇒ mark API readiness stale ───────────────────────
+        // No `error.response` means the request never received an HTTP answer: the
+        // backend is unreachable — down / restarting, connection refused, DNS
+        // failure, or a transport timeout. (Cancellations already returned above; any
+        // `error.response`, even a 5xx, means the backend DID answer and is up.)
+        //
+        // The per-base-URL `ApiReadinessChecker` is sticky-true once it has seen one
+        // healthy `/health/ready`, and is otherwise only re-armed on an explicit
+        // base-URL change. So when the backend restarts while this SPA stays alive
+        // (a dev/HMR recompile, or a rolling redeploy that doesn't reload the page),
+        // `ensureReady()` returns immediately and every subsequent request fires
+        // blindly at the still-warming backend, each surfacing its own genuine NETWORK
+        // error. Resetting here re-arms the gate: the NEXT request `await`s
+        // `/health/ready` (with backoff) until the backend is back, so only the
+        // request(s) that actually raced the outage surface an error — the rest wait
+        // and then succeed. Guarded on `getIsReady()` so a burst of concurrent
+        // failures during a single outage resets once (and re-polls once), not once
+        // per failed request.
+        if (!error.response && this.readinessChecker.getIsReady()) {
+            this.logDebug('Backend unreachable (no response) — resetting API readiness so the next request re-gates', {
+                url: error.config?.url,
+                code: error.code,
+            });
+            this.readinessChecker.reset();
+        }
         if (error.response) {
             const { status, data: errorData } = error.response;
             // Handle 401 Unauthorized errors
@@ -394,17 +709,52 @@ export class WildoBackendHttpClient {
                 // If it's a JWT failure and we have a renewal handler, try to renew
                 if (refreshableErrorCodes.includes(errorCode) && this.tokenRenewalHandler) {
                     try {
+                        this.logger.debug('HTTP 401 indicates access-token verification failure; attempting token renewal', {
+                            url: error.config?.url,
+                            errorCode,
+                        });
                         const newToken = await this.tokenRenewalHandler();
                         this.setAuthToken(newToken);
                         // Retry the original request with new token
                         if (error.config) {
+                            this.logger.debug('Retrying original request after successful token renewal', {
+                                url: error.config.url,
+                                method: error.config.method,
+                            });
                             error.config.headers[WildoHeaderKeys.AUTHORIZATION] = `Bearer ${newToken}`;
                             return this.axiosInstance(error.config);
                         }
                     }
                     catch (renewalError) {
-                        this.logger.error('Token renewal failed', { error: renewalError });
-                        this.clearAuthToken();
+                        // Only drop the in-memory bearer when the renewal was
+                        // AUTHORITATIVELY rejected (the backend genuinely refused the
+                        // refresh token) AND we are not in dev-leniency mode. On a
+                        // TRANSIENT failure (backend restarting / 5xx / timeout) we keep
+                        // the (expired) token so a later request re-triggers renewal once
+                        // the backend recovers — clearing it here would degrade every
+                        // subsequent request to a non-refreshable `no authentication
+                        // provided` 401 that never recovers without a reload. See
+                        // `auth-refresh-resilience.frontend.ts` for the classification.
+                        const authoritative = isAuthoritativeRefreshRejection(renewalError);
+                        if (authoritative && !isRefreshDevLenient()) {
+                            this.logger.error('Token renewal failed (authoritative); clearing bearer', { error: renewalError });
+                            this.clearAuthToken();
+                        }
+                        else {
+                            // Renewal could not complete, but the session is NOT provably dead
+                            // when the failure was transient. Tag the ORIGINAL request error so
+                            // a downstream recovery path (e.g. session restore) treats the
+                            // resulting 401 as retryable rather than as a dead-session logout.
+                            // Never tag an authoritative rejection (kept untagged → terminates).
+                            if (!authoritative) {
+                                error[RENEWAL_TRANSIENTLY_FAILED_MARKER] = true;
+                            }
+                            this.logger.warn('Token renewal failed transiently; preserving bearer for retry on next request', {
+                                error: renewalError,
+                                authoritative,
+                                devLenient: isRefreshDevLenient(),
+                            });
+                        }
                         if (error.config)
                             this.emitLoadingEnd(error.config);
                         return Promise.reject(error);
@@ -417,9 +767,14 @@ export class WildoBackendHttpClient {
                     'jwt_verification_failed',
                     'jwt_token_expired',
                     'authentication_invalid_token',
-                    'authentication_token_expired',
                 ];
-                if (tokenInvalidErrors.includes(errorCode)) {
+                // In dev-leniency mode we deliberately do NOT tear down the bearer on
+                // an "invalid token" 401 either — this is the same seam that runs on the
+                // refresh request's own 401 (`authentication_invalid_token`), and
+                // clearing here would contradict the renewal handler's decision to
+                // preserve the session for retry during a backend recompile. Production
+                // is unchanged.
+                if (tokenInvalidErrors.includes(errorCode) && !isRefreshDevLenient()) {
                     this.logDebug('Clearing auth token due to invalid token error', { errorCode });
                     this.clearAuthToken();
                 }
@@ -485,7 +840,14 @@ export class WildoBackendHttpClient {
         if (this.shouldRetry(error)) {
             const retryCount = (error.config.__retryCount || 0) + 1;
             error.config.__retryCount = retryCount;
-            const delay = this.calculateRetryDelay(retryCount - 1);
+            // Server `Retry-After` (429/503) takes precedence, but is clamped so a
+            // huge/hostile header can't park the request; otherwise fall back to
+            // jittered exponential backoff (already capped internally).
+            const maxRetryAfterDelayMs = this.config.maxRetryAfterDelayMs ?? 30000;
+            const retryAfterDelay = this.getRetryAfterDelay(error);
+            const delay = retryAfterDelay !== undefined
+                ? Math.min(retryAfterDelay, maxRetryAfterDelayMs)
+                : this.calculateRetryDelay(retryCount - 1);
             const maxRetries = this.config.retryAttempts ?? 0;
             this.logDebug(`Retrying request (attempt ${retryCount}/${maxRetries})`, {
                 url: error.config.url,
@@ -518,6 +880,7 @@ export class WildoBackendHttpClient {
         // Attach wildoError to the error object for callers to access
         error.wildoError = errorResult.wildoError;
         error.httpErrorBehavior = errorResult.behavior;
+        error.wildoErrorEventEmitted = errorResult.eventEmitted;
         if (error.config)
             this.emitLoadingEnd(error.config);
         return Promise.reject(error);
@@ -534,7 +897,11 @@ export class WildoBackendHttpClient {
         }
         catch (error) {
             if (error instanceof z.ZodError) {
-                throw new Error(`Response validation failed: ${error.message}`);
+                // `error.message` is Zod 4's `JSON.stringify(issues, null, 2)` blob —
+                // multi-line JSON in a thrown message reaches the browser console and
+                // every error-surfacing UI as an unreadable wall. Summarize to the
+                // failing paths instead.
+                throw new Error(`Response validation failed: ${summarizeZodIssues(error.issues)}`);
             }
             throw error;
         }
@@ -638,26 +1005,130 @@ export class WildoBackendHttpClient {
     }
     // Readiness check
     /**
-     * Ensure API is ready before making requests
-     * Waits for /health/ready to return healthy status
-     * Uses exponential backoff and never stops retrying
+     * Ensure API is ready before making requests — BOUNDED for the request path.
+     *
+     * Waits for /health/ready to report healthy, but only up to
+     * `readinessWaitTimeoutMs` (default 10s): past that, rejects with a typed
+     * `ApiNotReadyError` (name `ApiNotReadyError`, code `API_NOT_READY`) so the
+     * caller's error path runs — a toast, an inline error state, or a retry
+     * ladder that classifies it as TRANSIENT. Before this bound existed, the
+     * request path awaited the never-settling shared readiness promise, so after
+     * one connection loss EVERY subsequent request parked forever with no UI
+     * signal (audit B2).
+     *
+     * The shared background poll loop is deliberately NOT bounded — it keeps
+     * polling `/health/ready` with jittered backoff until the backend recovers,
+     * so a later request (or a caller's retry) finds the gate open again.
      */
     async ensureReady() {
-        await this.readinessChecker.waitForReady();
+        // When the browser reports offline, do NOT block on `/health/ready` — it can
+        // never succeed (the poll loops forever with backoff), which would hang every
+        // request at cold-start-offline BEFORE it reaches `networkInterruptionInterceptor`
+        // and defeat the whole offline policy (mutations should REJECT fast, reads
+        // should QUEUE). Skip the gate and let the request flow into the interceptor,
+        // which applies the policy. The `online` event re-arms normal gating.
+        if (!this.networkConnectionState.connected) {
+            return;
+        }
+        await this.readinessChecker.waitForReady(this.config.readinessWaitTimeoutMs ?? 10000);
     }
     // HTTP Methods
     /**
      * GET request
+     *
+     * Concurrent identical GETs share one in-flight network request — see
+     * {@link inflightGetRequests} for the sharing contract and its exclusions.
+     * Schema validation stays per-caller: each participant parses its own copy.
      */
     async get(url, options) {
         await this.ensureReady();
         this.logDebug('GET request initiated', { url });
-        const response = await this.axiosInstance.get(url, options);
+        const response = await this.executeGetWithInflightSharing(url, options);
         if (options?.schema) {
             return this.validateResponse(options.schema, response);
         }
         return response;
     }
+    /**
+     * Execute a GET, sharing the network flight with concurrent identical GETs.
+     *
+     * Every PARTICIPANT of a shared flight (creator included) receives its own
+     * `structuredClone` of the resolved payload: the RMM, displayers, and DTO
+     * metadata re-attachment all treat the response as an owned object, and
+     * handing N callers one shared object would let one caller's mutation leak
+     * into another's render. Non-shareable requests (signal / custom headers /
+     * responseType / unserialisable params) fall through to a plain request and
+     * return the original payload without cloning.
+     */
+    executeGetWithInflightSharing(url, options) {
+        const key = this.buildInflightGetKey(url, options);
+        if (key === null) {
+            return this.axiosInstance.get(url, options);
+        }
+        const existing = this.inflightGetRequests.get(key);
+        if (existing) {
+            this.logDebug('GET joined in-flight identical request', { url });
+            return existing.then((data) => structuredClone(data));
+        }
+        const flight = this.axiosInstance.get(url, options).finally(() => {
+            // In-flight only: drop the entry the moment the flight settles so a
+            // later GET always hits the network (no cross-time caching).
+            if (this.inflightGetRequests.get(key) === flight) {
+                this.inflightGetRequests.delete(key);
+            }
+        });
+        this.inflightGetRequests.set(key, flight);
+        return flight.then((data) => structuredClone(data));
+    }
+    /**
+     * Build the identity key for in-flight GET sharing, or `null` when this
+     * request must NOT be shared (see {@link inflightGetRequests}).
+     *
+     * `silent` participates in the key: the shared flight's error handling
+     * follows the creator's options, so a silent and a non-silent request must
+     * not share one flight (the non-silent caller would lose its global error
+     * surfacing, or the silent one would gain an unwanted toast).
+     */
+    buildInflightGetKey(url, options) {
+        if (options?.signal || options?.headers || options?.responseType) {
+            return null;
+        }
+        let paramsKey = '';
+        if (options?.params) {
+            try {
+                paramsKey = JSON.stringify(Object.entries(options.params).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+            }
+            catch {
+                // Unserialisable params (circular, exotic values) — never share.
+                return null;
+            }
+        }
+        return `${url}::${paramsKey}::${options?.silent === true ? 'silent' : 'loud'}`;
+    }
+    /**
+     * Fetch a file's bytes as a Blob over the AUTHENTICATED client.
+     *
+     * The transport half of resource-integrated file preview: an `<img>` / PDF.js
+     * cannot attach the bearer token, so the browser cannot load a protected file URL
+     * directly. Instead the caller fetches the bytes here (the auth interceptor adds
+     * the bearer, and the backend serve route authorizes via the linked resource's
+     * READ), then wraps the returned Blob in `URL.createObjectURL` for the element's
+     * `src` — revoking it on unmount. No consumable token, no public URL.
+     *
+     * @param url - The resource-integrated serve URL (already includes the fileId).
+     * @param options.signal - Abort signal to cancel an in-flight fetch on unmount.
+     */
+    async fetchFileBlob(url, options) {
+        await this.ensureReady();
+        this.logDebug('File blob request initiated', { url });
+        // The response interceptor unwraps `.data`; for `responseType: 'blob'` that IS
+        // the Blob body.
+        const response = await this.axiosInstance.get(url, {
+            responseType: 'blob',
+            signal: options?.signal,
+        });
+        return response;
+    }
     /**
      * POST request
      */
@@ -770,4 +1241,4 @@ export class WildoBackendHttpClient {
         }
     }
 }
-//# sourceMappingURL=wildo-http-client.frontend.service.js.map
+//# sourceMappingURL=wildo-http-client.frontend.service.js.map