fg-tracker-browser 0.3.0 → 0.5.0

package/dist/index.js

@@ -1,7 +1,9 @@
 import { createAnalytics, doNotTrackEnabled } from './analytics.js';
+import { createWebVitals } from './vitals.js';
 /** Header da chave do projeto enviado pelo SDK (a API aceita também o legado `x-stread-track-key`). */
 export const API_KEY_HEADER = 'x-fg-tracker-key';
 export { doNotTrackEnabled, pageUrl, referrerOrigin, screenBucket, utmParams, SESSION_COOKIE, VISITOR_COOKIE } from './analytics.js';
+export { MAX_REPORTS_PER_VIEW, MAX_VIEWS_PER_DOCUMENT, SOFT_VIEW_GRACE_MS, WEB_VITALS_THRESHOLDS } from './vitals.js';
 /**
  * fg-tracker-browser (CONTRATO.md §24): captura erros não tratados, guarda os
  * últimos breadcrumbs (cliques, navegação, console, fetch) e envia cada erro como
@@ -95,10 +97,23 @@ export function toJsonSafe(value, seen = new WeakSet()) {
         seen.delete(current);
     }
 }
+/**
+ * Atributos que identificam o evento e o ligam ao trace e ao serviço: o corte do `fitEvent` os
+ * guarda antes de qualquer outro (sem eles, o erro vira raiz solta no trace da API e some dos
+ * filtros de ambiente/serviço).
+ */
+const KEY_ATTRIBUTES = ['remoteParentSpanId', 'error.cause', 'serviceName', 'environment', 'release', 'level', 'client', 'mechanism', 'page', 'user.id', 'view.id', 'sampled', 'propagated', 'transport', 'aborted', 'host'];
+/** Valor curto o bastante para entrar no corte: texto cortado em `maxChars`, outro valor grande vira `[truncado]`. */
+function shortValue(value, maxChars) {
+    if (typeof value === 'string')
+        return truncateText(value, maxChars);
+    return utf8Bytes(JSON.stringify(value) ?? 'null') <= 512 ? value : '[truncado]';
+}
 /**
  * Cabe um evento em `MAX_EVENT_BYTES` (bytes UTF-8 do JSON): primeiro só os 5 últimos
- * breadcrumbs, depois stack e mensagem cortados, depois atributos curtos dentro de um orçamento
- * acumulado, e por fim só a marca. Marca `attributes['fg.truncated']`. Nunca lança.
+ * breadcrumbs, depois stack e mensagem cortados, depois as chaves de identidade e vínculo
+ * (`KEY_ATTRIBUTES`) e os atributos curtos dentro de um orçamento acumulado, e por fim só as
+ * chaves de identidade. Marca `attributes['fg.truncated']`. Nunca lança.
  */
 export function fitEvent(event, maxBytes = MAX_EVENT_BYTES) {
     const safe = toJsonSafe(event);
@@ -114,12 +129,16 @@ export function fitEvent(event, maxBytes = MAX_EVENT_BYTES) {
     let out = { ...safe, attributes, error };
     if (size(out) <= maxBytes)
         return out;
-    // Atributos curtos, na ordem, enquanto couberem no que sobra depois do resto do evento.
+    // Chaves de identidade e vínculo primeiro; depois atributos curtos, na ordem, enquanto couberem.
     const marker = { 'fg.truncated': true };
-    let budget = maxBytes - size({ ...out, attributes: marker });
-    const small = { ...marker };
+    const keys = { ...marker };
+    for (const key of KEY_ATTRIBUTES)
+        if (key in attributes && attributes[key] !== undefined)
+            keys[key] = shortValue(attributes[key], 256);
+    let budget = maxBytes - size({ ...out, attributes: keys });
+    const small = { ...keys };
     for (const [key, value] of Object.entries(attributes)) {
-        if (key === 'breadcrumbs' || key === 'fg.truncated')
+        if (key === 'breadcrumbs' || key === 'fg.truncated' || key in keys)
             continue;
         const json = JSON.stringify(value) ?? 'null';
         const candidate = utf8Bytes(json) <= 512 ? value : typeof value === 'string' ? truncateText(value, 128) : '[truncado]';
@@ -132,12 +151,15 @@ export function fitEvent(event, maxBytes = MAX_EVENT_BYTES) {
     out = { ...out, attributes: small };
     if (size(out) <= maxBytes)
         return out;
-    // Ainda grande (nome, rota ou erro enormes): só o essencial.
+    // Ainda grande (nome, rota ou erro enormes): só o essencial, com as chaves de identidade curtas.
+    const essential = { ...marker };
+    for (const [key, value] of Object.entries(keys))
+        essential[key] = shortValue(value, 128);
     out = {
         ...out,
         name: truncateText(String(out.name), 256),
         route: out.route === null ? null : truncateText(String(out.route), 256),
-        attributes: marker,
+        attributes: essential,
         error: out.error ? { name: truncateText(out.error.name, 100), message: truncateText(out.error.message, 500) } : null,
     };
     return out;
@@ -274,6 +296,8 @@ export function createBrowserTracker(options, env = globalThis) {
     let lastSignature = '';
     let lastAt = 0;
     let timer = null;
+    /** Web Vitals (opt-in); criado depois dos listeners, lido por `baseAttributes` (`view.id`). */
+    let vitals = null;
     const cleanups = [];
     const crumbOn = (type) => options.breadcrumbs?.[type] !== false;
     const log = (...args) => {
@@ -298,6 +322,9 @@ export function createBrowserTracker(options, env = globalThis) {
             viewport: env.window ? `${env.window.innerWidth}x${env.window.innerHeight}` : null,
             client: 'browser',
         };
+        const viewId = vitals?.viewId;
+        if (viewId)
+            attrs['view.id'] = viewId;
         if (options.serviceName)
             attrs.serviceName = options.serviceName;
         if (options.release)
@@ -450,13 +477,19 @@ export function createBrowserTracker(options, env = globalThis) {
         return flushing;
     };
     /**
-     * `pagehide`: o que está na fila (e o lote em voo sem keepalive) sai em pedaços de até 60 KiB
-     * por `sendBeacon` (ou `fetch` keepalive), erros primeiro, depois analytics, depois o resto,
-     * até o orçamento de ~64 KiB do navegador. O que não couber se perde (a página está saindo).
+     * Página oculta ou saindo: o que está na fila sai em pedaços de até 60 KiB por `sendBeacon` (ou
+     * `fetch` keepalive), erros primeiro, depois analytics, depois o resto, até o orçamento de ~64 KiB
+     * do navegador. O que não couber volta para a fila: numa troca de aba a página continua viva e o
+     * flush normal o envia; se ela estiver mesmo saindo, a memória vai junto (como antes).
+     *
+     * `unloading` (`pagehide`): o lote em voo sem keepalive também entra, porque o navegador o
+     * cancela no unload (o que dele não couber não volta: o cancelamento o devolve à fila). Numa simples
+     * ocultação esse lote continua em voo e fica de fora.
      */
-    const flushOnHide = () => {
-        // O lote em voo sem keepalive (o navegador o cancela), os lotes à espera neste flush e as filas.
-        const taken = [...(inFlight ?? []), ...outbox.splice(0).flatMap((chunk) => chunk.items)];
+    const flushOnHide = (unloading) => {
+        // Os lotes à espera neste flush, as filas e, saindo, o lote em voo sem keepalive.
+        const fromInFlight = new Set(unloading ? (inFlight ?? []).map((item) => item.event) : []);
+        const taken = [...(unloading ? (inFlight ?? []) : []), ...outbox.splice(0).flatMap((chunk) => chunk.items)];
         const pendingSpans = [...taken.flatMap((item) => (item.type === 'span' ? [item.event] : [])), ...queue.splice(0, queue.length)];
         const pendingAnalytics = [...taken.flatMap((item) => (item.type === 'analytics' ? [item.event] : [])), ...analyticsQueue.splice(0, analyticsQueue.length)];
         if (pendingSpans.length === 0 && pendingAnalytics.length === 0)
@@ -466,16 +499,22 @@ export function createBrowserTracker(options, env = globalThis) {
             ...pendingAnalytics.map((event) => ({ type: 'analytics', event })),
             ...pendingSpans.filter((event) => !event.error).map((event) => ({ type: 'span', event })),
         ];
-        // Seleciona, na ordem de prioridade, o que cabe no orçamento que sobra (o resto se perde).
+        // Seleciona, na ordem de prioridade, o que cabe no orçamento que sobra; o resto volta para a fila.
         let budget = KEEPALIVE_BUDGET_BYTES - keepaliveInFlight - 64;
         const selected = [];
+        const leftover = [];
         for (const item of ordered) {
             const size = utf8Bytes(JSON.stringify(item.event)) + 48;
-            if (size > budget)
+            if (size > budget) {
+                if (!fromInFlight.has(item.event))
+                    leftover.push(item);
                 continue;
+            }
             selected.push(item);
             budget -= size;
         }
+        if (leftover.length > 0)
+            requeue(leftover);
         const nav = env.navigator ?? env.window?.navigator;
         for (const chunk of buildChunks(selected, KEEPALIVE_BUDGET_BYTES)) {
             let sent = false;
@@ -488,11 +527,38 @@ export function createBrowserTracker(options, env = globalThis) {
                     sent = false;
                 }
             }
-            if (!sent)
-                void post(chunk, true);
+            // Sem beacon, fetch keepalive; com a página viva, uma falha devolve o pedaço à fila.
+            if (!sent) {
+                void post(chunk, true).then((outcome) => {
+                    if (!unloading && outcome !== 'ok' && outcome !== 'rejected')
+                        requeue(chunk.items);
+                });
+            }
         }
     };
-    const capture = (error, attributes = {}, level = 'error') => {
+    const fetchCauses = new WeakMap();
+    const linkCause = (key, link) => {
+        fetchCauses.set(key, fetchCauses.has(key) ? 'ambiguous' : (link ?? 'none'));
+    };
+    const causeOf = (error, explicit) => {
+        const candidates = [explicit];
+        let current = error;
+        for (let depth = 0; depth < 5 && current && typeof current === 'object'; depth += 1) {
+            candidates.push(current);
+            current = current.cause;
+        }
+        for (const candidate of candidates) {
+            if (candidate && typeof candidate === 'object') {
+                const hit = fetchCauses.get(candidate);
+                if (hit === 'ambiguous')
+                    return undefined;
+                if (hit && hit !== 'none')
+                    return hit;
+            }
+        }
+        return undefined;
+    };
+    const capture = (error, attributes = {}, level = 'error', explicitCause) => {
         if (!enabled)
             return;
         const err = toError(error);
@@ -508,9 +574,17 @@ export function createBrowserTracker(options, env = globalThis) {
             return;
         const loc = env.location ?? env.window?.location;
         const startedAt = now();
+        let cause;
+        try {
+            cause = causeOf(error, explicitCause);
+        }
+        catch {
+            cause = undefined;
+        }
         enqueue({
-            traceId: randomHex(16, env),
+            traceId: cause?.traceId ?? randomHex(16, env),
             spanId: randomHex(8, env),
+            // Continua raiz (o agrupamento da issue não muda); o waterfall a pendura sob o fetch.
             parentSpanId: null,
             kind: 'browser',
             name: `page:${loc ? normalizePath(loc.pathname) : '/'}`,
@@ -520,80 +594,330 @@ export function createBrowserTracker(options, env = globalThis) {
             startedAt,
             endedAt: startedAt,
             durationMs: 0,
-            attributes: { ...baseAttributes(), ...attributes, level, breadcrumbs: crumbs.slice(-maxBreadcrumbs) },
+            attributes: {
+                ...baseAttributes(),
+                ...attributes,
+                level,
+                breadcrumbs: crumbs.slice(-maxBreadcrumbs),
+                ...(cause ? { remoteParentSpanId: cause.spanId, 'error.cause': cause.transport } : {}),
+            },
             error: level === 'error' || level === 'warning' ? err : null,
         });
         addBreadcrumb({ type: 'error', level: level === 'info' ? 'info' : 'error', message: `${err.name}: ${err.message}`.slice(0, 200) });
         void flush();
     };
-    /* --------------------------------------------------------------- fetch */
-    const trackedFetch = async (input, init) => {
-        if (!baseFetch)
-            throw new Error('fetch indisponível');
-        const raw = typeof input === 'string' ? input : input instanceof URL ? input.toString() : input.url;
-        let url = null;
+    /** Decide amostragem e propagação de uma chamada HTTP (fetch ou XHR) para `url`. */
+    const startCall = (transport, method, url, canPropagate = true) => {
+        const sampled = enabled && (options.tracesSampleRate ?? 0) > 0 && Math.random() < (options.tracesSampleRate ?? 0);
+        const loc = env.location ?? env.window?.location;
+        const origin = loc?.origin;
+        const page = loc ? normalizePath(loc.pathname) : null;
+        return {
+            transport,
+            method,
+            url,
+            started: Date.now(),
+            status: null,
+            failure: null,
+            sampled,
+            propagated: canPropagate && sampled && shouldPropagate(url, options.propagateTraceTo, origin),
+            traceId: randomHex(16, env),
+            rootId: randomHex(8, env),
+            spanId: randomHex(8, env),
+            origin: sampled ? { name: `page:${page ?? '/'}`, route: page, attributes: { ...baseAttributes(), sampled: true }, viewId: vitals?.viewId ?? null } : null,
+        };
+    };
+    /**
+     * Breadcrumb e, se amostrada, trace (raiz `browser` + `http.client`) de uma chamada terminada.
+     * Cancelamento (`AbortError`, `xhr.abort()`) não é erro: `attributes.aborted`, sem `error`
+     * (não vira issue). Timeout, falha de rede e 5xx são.
+     */
+    const finishCall = (call) => {
+        const durationMs = Date.now() - call.started;
+        const aborted = call.failure?.name === 'AbortError';
+        const { method, url, status, failure } = call;
+        const target = `${url.origin}${normalizePath(url.pathname)}`;
+        if (crumbOn(call.transport)) {
+            addBreadcrumb({
+                type: call.transport,
+                category: 'http',
+                level: aborted ? 'warning' : (status && status >= 500) || failure ? 'error' : 'info',
+                message: `${method} ${target} → ${status ?? failure?.name ?? '?'}`,
+                // XHR sem query: a URL completa pode levar tokens (o fetch passa pela limpeza do envio).
+                data: { method, url: call.transport === 'xhr' ? `${url.origin}${url.pathname}` : url.href, status, durationMs, ...(aborted ? { aborted: true } : {}) },
+            });
+        }
+        if (!call.sampled || !call.origin)
+            return;
+        const startedAt = new Date(call.started).toISOString();
+        const endedAt = new Date(call.started + durationMs).toISOString();
+        const { viewId } = call.origin;
+        enqueue({ traceId: call.traceId, spanId: call.rootId, parentSpanId: null, kind: 'browser', name: call.origin.name, method: null, route: call.origin.route, statusCode: null, startedAt, endedAt, durationMs, attributes: call.origin.attributes, error: null });
+        enqueue({
+            traceId: call.traceId,
+            spanId: call.spanId,
+            parentSpanId: call.rootId,
+            kind: 'http.client',
+            name: `${method} ${target}`,
+            method,
+            route: normalizePath(url.pathname),
+            statusCode: status,
+            startedAt,
+            endedAt,
+            durationMs,
+            attributes: {
+                url: call.transport === 'xhr' ? `${url.origin}${url.pathname}` : url.href,
+                host: url.host,
+                propagated: call.propagated,
+                ...(call.transport === 'xhr' ? { transport: 'xhr' } : {}),
+                ...(aborted ? { aborted: true } : {}),
+                ...(viewId ? { 'view.id': viewId } : {}),
+                ...(options.serviceName ? { serviceName: options.serviceName } : {}),
+                ...(options.release ? { release: options.release } : {}),
+            },
+            error: aborted ? null : status && status >= 500 ? { name: 'HttpError', message: `HTTP ${status}` } : failure,
+        });
+    };
+    const resolveUrl = (raw) => {
         try {
-            url = new URL(raw, (env.location ?? env.window?.location)?.href);
+            return new URL(raw, (env.location ?? env.window?.location)?.href);
         }
         catch {
-            url = null;
+            return null;
         }
+    };
+    const trackedFetch = async (input, init) => {
+        if (!baseFetch)
+            throw new Error('fetch indisponível');
+        const raw = typeof input === 'string' ? input : input instanceof URL ? input.toString() : input.url;
+        const url = resolveUrl(raw);
         if (!url || raw.startsWith(endpoint))
             return baseFetch(input, init);
         const method = (init?.method ?? (input instanceof Request ? input.method : 'GET')).toUpperCase();
-        const sampled = enabled && (options.tracesSampleRate ?? 0) > 0 && Math.random() < (options.tracesSampleRate ?? 0);
-        const origin = (env.location ?? env.window?.location)?.origin;
-        const traceId = randomHex(16, env);
-        const rootId = randomHex(8, env);
-        const spanId = randomHex(8, env);
+        const call = startCall('fetch', method, url);
         let request = { input, init };
-        if (sampled && shouldPropagate(url, options.propagateTraceTo, origin)) {
+        if (call.propagated) {
             const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined));
-            headers.set('traceparent', `00-${traceId}-${spanId}-01`);
+            headers.set('traceparent', `00-${call.traceId}-${call.spanId}-01`);
             request = { input, init: { ...init, headers } };
         }
-        const started = Date.now();
-        const startedAt = new Date(started).toISOString();
-        let status = null;
-        let failure = null;
         try {
             const res = await baseFetch(request.input, request.init);
-            status = res.status;
+            call.status = res.status;
+            if (res && typeof res === 'object')
+                linkCause(res, call.propagated ? { traceId: call.traceId, spanId: call.spanId, transport: 'fetch' } : null);
             return res;
         }
         catch (err) {
-            failure = toError(err);
+            call.failure = toError(err);
+            if (err && typeof err === 'object')
+                linkCause(err, call.propagated ? { traceId: call.traceId, spanId: call.spanId, transport: 'fetch' } : null);
             throw err;
         }
         finally {
-            const durationMs = Date.now() - started;
-            if (crumbOn('fetch'))
-                addBreadcrumb({ type: 'fetch', category: 'http', level: status && status >= 500 ? 'error' : failure ? 'error' : 'info', message: `${method} ${url.origin}${normalizePath(url.pathname)} → ${status ?? failure?.name ?? '?'}`, data: { method, url: url.href, status, durationMs } });
-            if (sampled) {
-                const loc = env.location ?? env.window?.location;
-                const endedAt = new Date(started + durationMs).toISOString();
-                enqueue({ traceId, spanId: rootId, parentSpanId: null, kind: 'browser', name: `page:${loc ? normalizePath(loc.pathname) : '/'}`, method: null, route: loc ? normalizePath(loc.pathname) : null, statusCode: null, startedAt, endedAt, durationMs, attributes: { ...baseAttributes(), sampled: true }, error: null });
-                enqueue({ traceId, spanId, parentSpanId: rootId, kind: 'http.client', name: `${method} ${url.origin}${normalizePath(url.pathname)}`, method, route: normalizePath(url.pathname), statusCode: status, startedAt, endedAt, durationMs, attributes: { url: url.href, host: url.host, propagated: shouldPropagate(url, options.propagateTraceTo, origin), ...(options.serviceName ? { serviceName: options.serviceName } : {}), ...(options.release ? { release: options.release } : {}) }, error: status && status >= 500 ? { name: 'HttpError', message: `HTTP ${status}` } : failure });
+            finishCall(call);
+        }
+    };
+    /**
+     * XHR (`XMLHttpRequest.prototype`): breadcrumb `xhr` e o mesmo trace amostrado do fetch, com
+     * `traceparent` (só quando a aplicação não mandou o dela). O vínculo causal é o próprio objeto:
+     * `captureException(err, attrs, { cause: xhr })`; um XHR reusado em outra chamada fica ambíguo.
+     *
+     * Reabrir (`open()`) fecha a chamada anterior antes de trocar o estado: no `readystatechange` de
+     * DONE (a aplicação encadeia a próxima chamada no mesmo objeto, e o navegador não dispara mais
+     * `load`/`loadend` da anterior) ela fecha com o próprio resultado; ainda pendente, o navegador a
+     * cancela, e ela fecha como cancelada (`aborted`). Nunca recebe o resultado da nova. Reaberto no
+     * `onload`/`onerror`, o `loadend` da anterior ainda chega: a nova só aceita eventos finais em DONE.
+     *
+     * A chamada fecha no `readystatechange` para DONE, que vem antes de `load`/`error`/`abort`/
+     * `timeout`/`loadend`: um erro capturado no `onload`/`onloadend` da aplicação já encontra o
+     * breadcrumb dela (como no fetch, que fecha antes de devolver a resposta). O `loadend` é a rede
+     * de segurança. Cancelamento vem do `abort()` (marcado no protótipo) ou do evento `abort`.
+     */
+    const instrumentXhr = (Xhr) => {
+        const proto = Xhr?.prototype;
+        if (!proto || typeof proto.open !== 'function' || typeof proto.send !== 'function')
+            return null;
+        const originalOpen = proto.open;
+        const originalSend = proto.send;
+        const originalSetRequestHeader = proto.setRequestHeader;
+        const originalAbort = proto.abort;
+        const states = new WeakMap();
+        proto.open = function open(...args) {
+            try {
+                states.get(this)?.complete?.(this.readyState === 4 ? 'done' : 'pending');
+            }
+            catch (err) {
+                log('xhr: chamada anterior não registrada', err);
+            }
+            try {
+                const raw = args[1] instanceof URL ? args[1].toString() : String(args[1]);
+                states.set(this, { method: String(args[0] ?? 'GET').toUpperCase(), raw, url: resolveUrl(raw), appTraceparent: false, call: null, abortRequested: false, complete: null });
+            }
+            catch {
+                states.delete(this);
             }
+            return originalOpen.apply(this, args);
+        };
+        proto.setRequestHeader = function setRequestHeader(name, value) {
+            const state = states.get(this);
+            if (state && typeof name === 'string' && name.toLowerCase() === 'traceparent')
+                state.appTraceparent = true;
+            return originalSetRequestHeader.call(this, name, value);
+        };
+        if (typeof originalAbort === 'function') {
+            proto.abort = function abort() {
+                const state = states.get(this);
+                if (state?.call)
+                    state.abortRequested = true;
+                return originalAbort.call(this);
+            };
         }
+        proto.send = function send(body) {
+            const state = states.get(this);
+            if (!state || !state.url || state.raw.startsWith(endpoint) || state.url.href.startsWith(`${endpoint}/`))
+                return originalSend.call(this, body);
+            const xhr = this;
+            const call = startCall('xhr', state.method, state.url, !state.appTraceparent);
+            state.call = call;
+            let outcome = null;
+            let finished = false;
+            const listeners = [];
+            const finish = (thrown) => {
+                if (finished)
+                    return;
+                finished = true;
+                state.complete = null;
+                for (const [type, listener] of listeners)
+                    xhr.removeEventListener(type, listener);
+                // Defesa: o estado já é de outra chamada (o `open()` fecha a anterior antes de trocá-lo).
+                if (states.get(xhr) !== state || state.call !== call)
+                    return;
+                try {
+                    const status = typeof xhr.status === 'number' && xhr.status > 0 ? xhr.status : null;
+                    call.status = status;
+                    if (outcome === 'abort')
+                        call.failure = { name: 'AbortError', message: 'XHR cancelado (abort)' };
+                    else if (outcome === 'timeout')
+                        call.failure = { name: 'TimeoutError', message: 'XHR excedeu o timeout' };
+                    else if (thrown !== undefined)
+                        call.failure = toError(thrown);
+                    else if (outcome === 'error' || status === null)
+                        call.failure = { name: 'NetworkError', message: 'XHR falhou (rede)' };
+                    finishCall(call);
+                }
+                catch (err) {
+                    log('xhr: chamada não registrada', err);
+                }
+            };
+            // Eventos finais desta chamada só chegam com o objeto em DONE. Reaberto no onload/onerror da
+            // anterior, o navegador ainda dispara o loadend dela, com esta já em OPENED: esse é ignorado.
+            const ours = () => xhr.readyState === 4;
+            for (const type of ['abort', 'timeout', 'error']) {
+                const listener = () => {
+                    if (!ours())
+                        return;
+                    outcome ?? (outcome = type);
+                    finish();
+                };
+                listeners.push([type, listener]);
+            }
+            /** Causa de um DONE sem resposta que dá para saber sem esperar o evento: cancelamento pedido ou prazo vencido. */
+            const knownFailure = () => {
+                const timeoutMs = typeof xhr.timeout === 'number' ? xhr.timeout : 0;
+                if (state.abortRequested)
+                    return 'abort';
+                if (timeoutMs > 0 && Date.now() - call.started >= timeoutMs - 5)
+                    return 'timeout';
+                return null;
+            };
+            // DONE com resposta (ou cancelamento pedido, ou prazo vencido) fecha na hora; falha sem causa
+            // conhecida espera o evento seguinte (error/timeout), que vem na mesma tarefa.
+            const onState = () => {
+                if (xhr.readyState !== 4)
+                    return;
+                if (typeof xhr.status === 'number' && xhr.status > 0)
+                    finish();
+                else {
+                    const known = knownFailure();
+                    if (known) {
+                        outcome ?? (outcome = known);
+                        finish();
+                    }
+                }
+            };
+            // Reaberto: no DONE, o resultado é este (sem resposta e sem causa conhecida, falha de rede);
+            // pendente, o navegador cancela a chamada.
+            state.complete = (when) => {
+                if (when === 'pending')
+                    outcome ?? (outcome = 'abort');
+                else if (!(typeof xhr.status === 'number' && xhr.status > 0))
+                    outcome ?? (outcome = knownFailure());
+                finish();
+            };
+            listeners.push(['readystatechange', onState], ['loadend', () => ours() && finish()]);
+            for (const [type, listener] of listeners)
+                xhr.addEventListener(type, listener);
+            try {
+                if (call.propagated)
+                    originalSetRequestHeader.call(xhr, 'traceparent', `00-${call.traceId}-${call.spanId}-01`);
+            }
+            catch {
+                call.propagated = false;
+            }
+            // Antes de qualquer callback da aplicação (onload roda antes do loadend).
+            linkCause(xhr, call.propagated ? { traceId: call.traceId, spanId: call.spanId, transport: 'xhr' } : null);
+            try {
+                return originalSend.call(xhr, body);
+            }
+            catch (err) {
+                finish(err);
+                throw err;
+            }
+        };
+        return () => {
+            proto.open = originalOpen;
+            proto.send = originalSend;
+            proto.setRequestHeader = originalSetRequestHeader;
+            if (typeof originalAbort === 'function')
+                proto.abort = originalAbort;
+        };
     };
     /* ------------------------------------------------------------ analytics */
+    const pushAnalytics = (event) => {
+        analyticsQueue.push(event);
+        if (analyticsQueue.length > MAX_QUEUE)
+            analyticsQueue.splice(0, analyticsQueue.length - MAX_QUEUE);
+    };
     const analyticsRequested = options.analytics === true || options.trackPageviews === true;
     const analytics = enabled && analyticsRequested && !doNotTrackEnabled(env)
         ? createAnalytics(env, {
             consent: options.consent ?? 'granted',
             cookieDomain: options.cookieDomain,
             sanitizePath: options.sanitizePath ?? normalizePath,
-            onEvent: (event) => {
-                analyticsQueue.push(event);
-                if (analyticsQueue.length > MAX_QUEUE)
-                    analyticsQueue.splice(0, analyticsQueue.length - MAX_QUEUE);
-            },
+            onEvent: (event) => pushAnalytics(event),
         })
         : null;
     if (enabled && analyticsRequested && !analytics)
         log('Do Not Track ligado: analytics desativada');
     const autoPageviews = !!analytics && (options.trackPageviews ?? options.analytics) !== false;
+    /* ------------------------------------------------------------ web vitals */
+    // Opt-in e independente da analytics: sem cookie nem id de visitante (§24.1).
+    const vitalsConfig = options.webVitals === true ? {} : options.webVitals && typeof options.webVitals === 'object' ? options.webVitals : null;
+    if (enabled && env.window && vitalsConfig) {
+        vitals = createWebVitals(env, {
+            sampleRate: typeof vitalsConfig.sampleRate === 'number' && Number.isFinite(vitalsConfig.sampleRate) ? vitalsConfig.sampleRate : 1,
+            softNavigations: vitalsConfig.softNavigations !== false,
+            sanitizePath: options.sanitizePath ?? normalizePath,
+            serviceName: options.serviceName,
+            environment: options.environment,
+            release: options.release,
+            onEvent: (event) => pushAnalytics(event),
+            log,
+        });
+        if (!vitals)
+            log('web vitals: fora da amostra ou navegador sem PerformanceObserver');
+    }
     /* ------------------------------------------------------------ listeners */
     const win = env.window;
     if (win && enabled) {
@@ -614,15 +938,17 @@ export function createBrowserTracker(options, env = globalThis) {
             doc.addEventListener('click', onClick, true);
             cleanups.push(() => doc.removeEventListener('click', onClick, true));
         }
-        if (crumbOn('navigation') || autoPageviews) {
+        if (crumbOn('navigation') || autoPageviews || vitals) {
             const hist = env.history ?? win.history;
             const loc = env.location ?? win.location;
             const record = (from, to) => {
                 if (crumbOn('navigation'))
                     addBreadcrumb({ type: 'navigation', category: 'navigation', message: `${from} → ${to}`, data: { from, to } });
             };
-            // Pageview depois da troca de URL (pushState/replaceState/popstate); o dedupe ignora a mesma URL.
+            // Depois da troca de URL (pushState/replaceState/popstate): view nova dos Web Vitals se o
+            // caminho mudou, e pageview (o dedupe ignora a mesma URL).
             const pageview = () => {
+                vitals?.onLocationChange();
                 if (autoPageviews)
                     analytics?.page();
             };
@@ -671,9 +997,35 @@ export function createBrowserTracker(options, env = globalThis) {
                 win.fetch = original;
             });
         }
-        const onHide = () => flushOnHide();
+        if (crumbOn('xhr') && typeof win.XMLHttpRequest === 'function') {
+            const restore = instrumentXhr(win.XMLHttpRequest);
+            if (restore)
+                cleanups.push(restore);
+        }
+        // Página oculta (troca de aba, app em segundo plano no celular, saída): os Web Vitals fecham o
+        // retrato e a fila sai por beacon. No celular o `pagehide` pode nunca chegar depois disso.
+        if (doc) {
+            const onVisibility = (event) => {
+                if (doc.visibilityState !== 'hidden')
+                    return;
+                vitals?.onHidden(event?.timeStamp);
+                flushOnHide(false);
+            };
+            doc.addEventListener('visibilitychange', onVisibility);
+            cleanups.push(() => doc.removeEventListener('visibilitychange', onVisibility));
+        }
+        const onHide = () => {
+            vitals?.onPageHide();
+            flushOnHide(true);
+        };
         win.addEventListener('pagehide', onHide);
         cleanups.push(() => win.removeEventListener('pagehide', onHide));
+        const onShow = (event) => {
+            if (event?.persisted)
+                vitals?.onRestore(event.timeStamp);
+        };
+        win.addEventListener('pageshow', onShow);
+        cleanups.push(() => win.removeEventListener('pageshow', onShow));
         // Pageview da carga inicial.
         if (autoPageviews)
             analytics?.page();
@@ -688,7 +1040,7 @@ export function createBrowserTracker(options, env = globalThis) {
     if (!enabled)
         (env.console ?? console).warn('[fg-tracker-browser] apiKey ausente: SDK desabilitado.');
     return {
-        captureException: (error, attributes) => capture(error, attributes, 'error'),
+        captureException: (error, attributes, captureOptions) => capture(error, attributes, 'error', captureOptions?.cause),
         captureMessage: (message, level = 'info', attributes) => capture(new Error(message), { ...attributes, isMessage: true }, level),
         addBreadcrumb,
         setUser: (next) => {
@@ -709,6 +1061,7 @@ export function createBrowserTracker(options, env = globalThis) {
             analytics?.setConsent(consent);
         },
         close: () => {
+            vitals?.close();
             for (const cleanup of cleanups.splice(0))
                 cleanup();
             if (timer)
@@ -718,6 +1071,9 @@ export function createBrowserTracker(options, env = globalThis) {
         get breadcrumbs() {
             return crumbs;
         },
+        get viewId() {
+            return vitals?.viewId ?? null;
+        },
     };
 }
 let current = null;