@maple-dev/browser 0.12.0 → 0.13.0

package/README.md

@@ -28,8 +28,8 @@ MapleBrowser.init({
 
 That single call:
 
-- starts OTel browser tracing, auto-instrumenting `fetch`, exporting to Maple's
-  ingest (`POST /v1/traces`);
+- starts OTel browser tracing, auto-instrumenting `fetch` and `XMLHttpRequest`,
+  exporting to Maple's ingest (`POST /v1/traces`);
 - records the session with rrweb, chunking events (~5s / 100KB windows),
   gzipping them with the native `CompressionStream`, and uploading to
   `POST /v1/sessionReplays/blob`. rrweb ships in a lazy code-split chunk loaded
@@ -57,6 +57,11 @@ try {
 }
 ```
 
+`captureException` is safe before `init()`: calls are held (up to 30) and recorded when it runs.
+A thrown value that is not an `Error` (`throw "boom"`, `throw { code: 1 }`) is recorded with its
+fields as the message, and an uncaught one gets a single frame at the throw site rather than a
+stack from inside the SDK.
+
 Opt out of the global handlers with `tracing: { captureErrors: false }` — worth
 doing only when another tracker already owns them, or the same crash is recorded
 twice.
@@ -70,7 +75,10 @@ fingerprint to one contentless issue that buries the real ones. Add
 
 `fetch`/XHR responses with a 4xx or 5xx status are errors, typed by status, as the HTTP semantic
 conventions say for client spans. Narrow that with `errors: { captureHttpStatus: [[500, 599]] }`.
-A network failure is always an error.
+A request that never got a response is an error too, unless the connection went away while it was
+in flight: the page unloaded or was hidden, or the browser went offline (or was offline when it
+failed). Those stay `Unset` with `maple.connection_lost` set to `page_unload`, `page_hidden` or
+`offline`, since the browser cancelled them, not your API.
 
 ### Breadcrumbs
 
@@ -99,9 +107,10 @@ in production.
 
 ## Identifying users
 
-Pass `userId` to `init()` when you already know the signed-in user, or call
-`MapleBrowser.identify(user.id)` later. The id is attached to future session
-metadata rows and stamped as `user.id` on future browser-created spans.
+Pass `user` to `init()` when you already know the signed-in user
+(`user: { id: user.id, email: user.email }`), or call `MapleBrowser.identify(user.id)` later.
+The id is attached to future session metadata rows and stamped as `user.id` on future
+browser-created spans.
 
 ```ts
 MapleBrowser.identify(user.id)
@@ -182,7 +191,7 @@ MapleBrowser.init({
 
 Call these from your router's hooks to make one click one trace: a navigation
 span, the data-loading spans under it, and the `fetch` spans they start.
-[maple.dev/docs/frontend](https://maple.dev/docs/frontend) shows where for each
+[maple.dev/docs/session-replay/browser-sdk](https://maple.dev/docs/session-replay/browser-sdk#framework-examples) shows where for each
 framework.
 
 ```ts
@@ -196,12 +205,12 @@ MapleBrowser.endNavigation("/projects/:id") // the route is ready: its template
 - The first `startNavigation` opens a `pageload` span, joined to the server
   render's trace from a `Server-Timing: traceparent;desc="…"` entry or a
   `<meta name="traceparent">` tag; later calls open `navigate` spans, and end
-  one still open as `app.navigation.interrupted`.
+  one still open, marked `maple.navigation.interrupted`.
 - The document's `pageload` starts at navigation start, and gets child spans
   from the Navigation Timing entry once the page has loaded: `documentFetch`
   (with `dns`, `connect`, `request` and `response` under it), `domProcessing`
   and `loadEvent`.
-- `traced` returns `fn`'s result and rethrows its error unchanged. Only requests
+- `traced` takes a sync or async `fn`, returns its result and rethrows its error unchanged. Only requests
   started before `fn`'s first `await` nest under its span. An error it recorded
   isn't reported again by `captureException` or the global handlers.
 - All three are no-ops on the server, before `init()`, with tracing disabled or
@@ -220,6 +229,11 @@ instrumentTanStackRouter(router) // navigate /projects/$projectId
 ```
 
 Attach them after `MapleBrowser.init`: a navigation reported earlier uses up the page load.
+Attaching the same router twice (React StrictMode, HMR) keeps one instrumentation, and the
+unsubscribe they return ends a navigation still open as interrupted.
+
+`mapleReactErrorHandler(source, next)` replaces React's own console logging for that callback, so
+it hands the error on to `next` afterwards, `console.error` by default.
 
 ## Linking a marketing site to your app
 

package/dist/console-iNhlufZV.mjs

@@ -0,0 +1,183 @@
+import { I as safeEmit, L as truncateText, Y as isJsonObject, b as patchMethod } from "./sink-Ji0J42ul.mjs";
+//#region ../browser-session/src/replay/capture/console.ts
+const LEVELS = [
+	"log",
+	"info",
+	"warn",
+	"error",
+	"debug"
+];
+const MAX_MESSAGE = 2e3;
+/** No array logged into a 2,000-character message needs more elements than this. */
+const MAX_ARRAY_ELEMENTS = 100;
+/** Nor more keys of one object, or more levels of nesting. */
+const MAX_OBJECT_KEYS = 50;
+const MAX_DEPTH = 6;
+/**
+* Everyone capturing this module's console wrappers: breadcrumbs and replay can
+* both listen. One wrapper per level per page, toggled by whether anyone
+* listens, so starting and stopping capture across visibility changes does not
+* stack wrappers.
+*/
+const listeners = /* @__PURE__ */ new Set();
+let unpatch = [];
+/** Set while listeners run: a listener that logs must not be captured again. */
+let dispatching = false;
+function wrapLevel(level) {
+	return (original, hooks) => (...args) => {
+		const subscribers = hooks();
+		if (subscribers && !dispatching) {
+			dispatching = true;
+			try {
+				for (const listener of subscribers) listener(level, args);
+			} catch {} finally {
+				dispatching = false;
+			}
+		}
+		original.apply(console, args);
+	};
+}
+/**
+* Capture `console.*` calls as session events, then forward to the original so
+* the host app's console behaves normally. Never throws into the call site.
+* Teardown leaves a wrapper that something else wrapped in place, inert.
+*/
+function installConsoleCapture(emit, options = {}) {
+	const listener = (level, args) => {
+		safeEmit(emit, {
+			type: "console",
+			level,
+			...options.maskText ? void 0 : { message: formatArgs(args) }
+		});
+	};
+	if (listeners.size === 0) unpatch = LEVELS.map((level) => patchMethod(console, level, listeners, wrapLevel(level)));
+	listeners.add(listener);
+	let removed = false;
+	return () => {
+		if (removed) return;
+		removed = true;
+		listeners.delete(listener);
+		if (listeners.size > 0) return;
+		for (const off of unpatch) off();
+		unpatch = [];
+	};
+}
+/** One console line as text, at most `MAX_MESSAGE` characters. Never throws. */
+function formatArgs(args) {
+	let text = "";
+	for (const arg of args) {
+		if (text.length > MAX_MESSAGE) break;
+		const room = MAX_MESSAGE - text.length + 1;
+		text += (text ? " " : "") + formatArg(arg, room);
+	}
+	return truncateText(text, MAX_MESSAGE, "…");
+}
+function formatArg(arg, budget) {
+	if (typeof arg === "string") return truncateText(arg, budget);
+	try {
+		if (arg instanceof Error) return truncateText(`${arg.name}: ${arg.message}`, budget);
+		return boundedStringify(arg, budget);
+	} catch {
+		return "[Unserializable]";
+	}
+}
+/**
+* JSON-like text of `value`, stopping once roughly `budget` characters are
+* written. Reads own data properties only, never getters or `toJSON`, and caps
+* keys, elements and depth, so logging a store object costs bounded time and
+* runs none of the page's code. A hostile object (a throwing Proxy) ends the
+* walk with what was written so far.
+*/
+function boundedStringify(value, budget) {
+	let out = "";
+	const ancestors = [];
+	const full = () => out.length > budget;
+	const room = () => Math.max(0, budget - out.length) + 2;
+	/** A quoted string cut to the room left: escaping can grow it sixfold. */
+	const quote = (text) => truncateText(JSON.stringify(truncateText(text, room())), room());
+	const visit = (node, depth) => {
+		if (full()) return;
+		switch (typeof node) {
+			case "string":
+				out += quote(node);
+				return;
+			case "number":
+			case "boolean":
+			case "bigint":
+			case "symbol":
+			case "undefined":
+				out += truncateText(String(node), room());
+				return;
+			case "function":
+				out += "[Function]";
+				return;
+		}
+		if (typeof node !== "object" || node === null) {
+			out += "null";
+			return;
+		}
+		if (ancestors.includes(node)) {
+			out += "\"[Circular]\"";
+			return;
+		}
+		if (node instanceof Date) {
+			out += Number.isNaN(node.getTime()) ? "null" : JSON.stringify(node.toISOString());
+			return;
+		}
+		if (depth >= MAX_DEPTH) {
+			out += Array.isArray(node) ? "[…]" : "{…}";
+			return;
+		}
+		ancestors.push(node);
+		try {
+			if (Array.isArray(node)) visitArray(node, depth);
+			else if (isJsonObject(node)) visitObject(node, depth);
+		} catch {} finally {
+			ancestors.pop();
+		}
+	};
+	const visitArray = (node, depth) => {
+		out += "[";
+		try {
+			const count = Math.min(node.length, MAX_ARRAY_ELEMENTS);
+			for (let index = 0; index < count && !full(); index++) {
+				if (index > 0) out += ",";
+				visitProperty(node, String(index), depth + 1);
+			}
+			if (node.length > count && !full()) out += ",…";
+		} finally {
+			out += "]";
+		}
+	};
+	/** An own property's value, without running a getter: one could have side effects. */
+	const visitProperty = (node, key, depth) => {
+		const descriptor = Object.getOwnPropertyDescriptor(node, key);
+		if (!descriptor) out += "undefined";
+		else visit("value" in descriptor ? descriptor.value : "[Getter]", depth);
+	};
+	const visitObject = (node, depth) => {
+		out += "{";
+		try {
+			let written = 0;
+			for (const key in node) {
+				if (full()) break;
+				if (!Object.prototype.hasOwnProperty.call(node, key)) continue;
+				if (written === MAX_OBJECT_KEYS) {
+					out += ",…";
+					break;
+				}
+				out += `${written > 0 ? "," : ""}${quote(key)}:`;
+				visitProperty(node, key, depth + 1);
+				written++;
+			}
+		} finally {
+			out += "}";
+		}
+	};
+	try {
+		visit(value, 0);
+	} catch {}
+	return out;
+}
+//#endregion
+export { installConsoleCapture as t };

package/dist/{deferred-BDKAWiKZ.mjs → deferred-Dr2AmxSU.mjs}

@@ -1,6 +1,6 @@
-import { A as selectorOf, G as scrubUrl, K as mayUseStorage, L as consentAllowedSince, O as sdkHint, R as consentRevokedAt, S as ingestHeaders, V as onConsentChange, l as onSessionEvent, z as hasConsent } from "./sink-DbEuphC-.mjs";
-import { _ as severityOf, a as detachLogSink, c as resourceAttributes, d as OtlpExporter, f as newestFirstOnExit, g as Severity, h as onErrorRecorded, i as attachLogSink, l as SDK_NAME, m as claimPageSignal, n as navigationSpanAt, o as emitLog, p as attachSpanStash, r as onDocumentPageload, s as liveMapleTracer, u as SDK_VERSION } from "./src-DfU4Cnb1.mjs";
-import { t as installConsoleCapture } from "./console-Bkd3hBGp.mjs";
+import { E as ingestHeaders, H as consentAllowedSince, K as onConsentChange, M as sdkHint, P as selectorOf, U as consentRevokedAt, W as hasConsent, X as scrubUrl, Z as mayUseStorage, l as onSessionEvent } from "./sink-Ji0J42ul.mjs";
+import { _ as Severity, a as attachLogSink, c as liveMapleTracer, d as SDK_VERSION, f as OtlpExporter, g as onErrorRecorded, h as claimPageSignal, i as onDocumentPageload, l as resourceAttributes, m as attachSpanStash, o as detachLogSink, p as newestFirstOnExit, r as navigationSpanAt, s as emitLog, u as SDK_NAME, v as severityOf } from "./src-JUynR8Jc.mjs";
+import { t as installConsoleCapture } from "./console-iNhlufZV.mjs";
 import { ROOT_CONTEXT, TraceFlags, context, trace } from "@opentelemetry/api";
 import { JsonLogsSerializer, JsonTraceSerializer } from "@opentelemetry/otlp-transformer";
 import { resourceFromAttributes } from "@opentelemetry/resources";
@@ -505,6 +505,19 @@ function startReports(emitLog, options) {
 //#endregion
 //#region ../sdk-core/src/browser/web-vitals.ts
 let registered = false;
+/**
+* The path of the page view the metrics measure. web-vitals reports CLS, INP and
+* LCP for the whole document (often when it is hidden, long after an SPA moved
+* on), so the path is the document's, and a bfcache restore starts a new one.
+*/
+let pagePath = "";
+function documentPath() {
+	const [entry] = performance.getEntriesByType?.("navigation") ?? [];
+	try {
+		if (entry?.name) return new URL(entry.name).pathname;
+	} catch {}
+	return location.pathname;
+}
 let emit;
 let pageload;
 function report(metric) {
@@ -519,7 +532,7 @@ function report(metric) {
 			"browser.web_vital.id": metric.id,
 			"browser.web_vital.rating": metric.rating,
 			"browser.web_vital.navigation_type": metric.navigationType,
-			"url.path": scrubUrl(location.pathname)
+			"url.path": pagePath
 		},
 		link: pageload?.()
 	});
@@ -530,6 +543,10 @@ function startWebVitals(sink, getPageload) {
 	pageload = getPageload;
 	if (!registered) {
 		registered = true;
+		pagePath = scrubUrl(documentPath());
+		window.addEventListener("pageshow", (event) => {
+			if (event.persisted) pagePath = scrubUrl(location.pathname);
+		});
 		for (const on of [
 			onCLS,
 			onFCP,
@@ -595,7 +612,16 @@ function startLogs(config, stashOffline) {
 		ingestKey: config.ingestKey,
 		sdk: sdkHint(SDK_NAME, SDK_VERSION)
 	}), JsonLogsSerializer);
-	const exporter = new ConsentLogExporter(newestFirstOnExit(stashOffline ? new OfflineLogExporter(otlp, stashOffline) : otlp, JsonLogsSerializer));
+	let leaving = false;
+	const exporter = new ConsentLogExporter(newestFirstOnExit(stashOffline ? new OfflineLogExporter(otlp, stashOffline) : otlp, JsonLogsSerializer, 0, () => leaving));
+	const onPageHide = () => {
+		leaving = true;
+		provider.forceFlush().catch(() => {}).finally(() => {
+			leaving = false;
+		});
+	};
+	const canListen = typeof window !== "undefined" && typeof window.addEventListener === "function";
+	if (canListen) window.addEventListener("pagehide", onPageHide);
 	const provider = new LoggerProvider({
 		resource: resourceFromAttributes(resourceAttributes(config)),
 		processors: [new BatchLogRecordProcessor({
@@ -614,6 +640,7 @@ function startLogs(config, stashOffline) {
 		context: record.link ? trace.setSpanContext(ROOT_CONTEXT, record.link) : ROOT_CONTEXT
 	}));
 	return async () => {
+		if (canListen) window.removeEventListener("pagehide", onPageHide);
 		detachLogSink();
 		await provider.shutdown();
 	};

package/dist/index.d.mts

@@ -283,9 +283,15 @@ interface CaptureExceptionOptions {
 //#endregion
 //#region src/init.d.ts
 interface MapleBrowserHandle {
-  /** Empty until consent is granted when `requireConsent` is enabled. */
+  /**
+   * Empty until consent is granted when `requireConsent` is enabled, and while
+   * a previous `shutdown()` is still flushing.
+   */
   readonly sessionId: string;
-  /** Tear down tracing + session capture, flushing the final buffers. */
+  /**
+   * Tear down tracing + session capture, flushing the final buffers. The SDK
+   * is released at once: an `init()` right after it gets a new, live handle.
+   */
   readonly shutdown: () => Promise<void>;
 }
 //#endregion
@@ -321,10 +327,11 @@ export interface MapleBrowserApi {
    */
   track: (name: string, props?: TrackProps) => void;
   /**
-   * Report an error your app already caught — the case the global handlers
+   * Report an error your app already caught: the case the global handlers
    * cannot see, because catching it is what stops it reaching them. A
    * framework error boundary is the canonical caller. The same error object
-   * is recorded once, even if it is rethrown afterwards.
+   * is recorded once, even if it is rethrown afterwards. Safe before `init`:
+   * calls are held (capped) and recorded when it runs.
    *
    * BOUNDARY: a thrown value is unparsed by definition — JavaScript can throw
    * anything. `captureException` narrows it before it reaches a span.
@@ -340,7 +347,7 @@ export interface MapleBrowserApi {
    * Run data loading, like a route loader, in a span under the current navigation.
    * Errors are recorded once and rethrown. Only requests started before `fn`'s first `await` nest under the span.
    */
-  traced: <T>(name: string, fn: () => Promise<T>, options?: TracedOptions) => Promise<T>;
+  traced: <T>(name: string, fn: () => T | Promise<T>, options?: TracedOptions) => Promise<T>;
   /**
    * Structured logs, exported as OpenTelemetry log records linked to the active
    * span and the session. Safe before `init`: records queue until it runs.

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { t as MapleBrowser } from "./src-DfU4Cnb1.mjs";
+import { t as MapleBrowser } from "./src-JUynR8Jc.mjs";
 export { MapleBrowser };

package/dist/react.d.mts

@@ -24,14 +24,17 @@ export declare class MapleErrorBoundary extends Component<MapleErrorBoundaryProp
   private readonly reset;
   render(): ReactNode;
 }
+type ReactRootErrorHandler = (error: unknown, info: {
+  readonly componentStack?: string | null | undefined;
+}) => void;
 /**
  * For React 19's `createRoot(el, { onCaughtError, onUncaughtError, onRecoverableError })`:
  * reports what React caught, with its component stack. Errors already reported
- * (by a `MapleErrorBoundary`, say) are not reported twice.
+ * (by a `MapleErrorBoundary`, say) are not reported twice. Passing a handler
+ * replaces React's own console logging, so the error is then handed to `next`,
+ * which defaults to `console.error`.
  */
-export declare function mapleReactErrorHandler(source?: string): (error: unknown, info: {
-  readonly componentStack?: string | null | undefined;
-}) => void;
+export declare function mapleReactErrorHandler(source?: string, next?: ReactRootErrorHandler): ReactRootErrorHandler;
 /** A React Router data router (`createBrowserRouter` and friends), as far as Maple reads it. */
 export interface ReactRouterLike {
   readonly state: ReactRouterState;

package/dist/react.mjs

@@ -1,4 +1,4 @@
-import { t as MapleBrowser } from "./src-DfU4Cnb1.mjs";
+import { n as interruptNavigation, t as MapleBrowser } from "./src-JUynR8Jc.mjs";
 import { Component } from "react";
 //#region src/react.ts
 /** Component stacks can run to hundreds of lines; the top of it names the failing tree. */
@@ -46,10 +46,35 @@ var MapleErrorBoundary = class extends Component {
 /**
 * For React 19's `createRoot(el, { onCaughtError, onUncaughtError, onRecoverableError })`:
 * reports what React caught, with its component stack. Errors already reported
-* (by a `MapleErrorBoundary`, say) are not reported twice.
+* (by a `MapleErrorBoundary`, say) are not reported twice. Passing a handler
+* replaces React's own console logging, so the error is then handed to `next`,
+* which defaults to `console.error`.
 */
-function mapleReactErrorHandler(source = "react.root") {
-	return (error, info) => reportReactError(error, info.componentStack, source);
+function mapleReactErrorHandler(source = "react.root", next = (error) => console.error(error)) {
+	return (error, info) => {
+		reportReactError(error, info.componentStack, source);
+		next(error, info);
+	};
+}
+const attachedRouters = /* @__PURE__ */ new WeakMap();
+function attachOnce(router, attach) {
+	const entry = attachedRouters.get(router) ?? {
+		count: 0,
+		stop: attach()
+	};
+	entry.count += 1;
+	attachedRouters.set(router, entry);
+	let released = false;
+	return () => {
+		if (released) return;
+		released = true;
+		entry.count -= 1;
+		queueMicrotask(() => {
+			if (entry.count > 0 || attachedRouters.get(router) !== entry) return;
+			attachedRouters.delete(router);
+			entry.stop();
+		});
+	};
 }
 /** `/projects/:id/settings`, from the matched routes' own path segments. */
 function reactRouterTemplate(state) {
@@ -67,6 +92,9 @@ function reactRouterTemplate(state) {
 * page load. Returns an unsubscribe.
 */
 function instrumentReactRouter(router) {
+	return attachOnce(router, () => attachReactRouter(router));
+}
+function attachReactRouter(router) {
 	let open = false;
 	let pathname = router.state.location.pathname;
 	const start = (path) => {
@@ -80,7 +108,7 @@ function instrumentReactRouter(router) {
 	};
 	start(pathname);
 	if (router.state.initialized && router.state.navigation.state === "idle") end(router.state);
-	return router.subscribe((state) => {
+	const unsubscribe = router.subscribe((state) => {
 		const target = state.navigation.location?.pathname;
 		if (state.navigation.state !== "idle" && target !== void 0) {
 			if (target !== pathname) start(target);
@@ -92,6 +120,11 @@ function instrumentReactRouter(router) {
 		pathname = state.location.pathname;
 		end(state);
 	});
+	return () => {
+		unsubscribe();
+		if (open) interruptNavigation();
+		open = false;
+	};
 }
 /**
 * Span each TanStack Router navigation from `onBeforeNavigate` to `onResolved`,
@@ -99,6 +132,9 @@ function instrumentReactRouter(router) {
 * changes are not navigations. The first is the page load. Returns an unsubscribe.
 */
 function instrumentTanStackRouter(router) {
+	return attachOnce(router, () => attachTanStackRouter(router));
+}
+function attachTanStackRouter(router) {
 	/** The path of the navigation in flight, if any. */
 	let open;
 	const template = () => {
@@ -124,6 +160,8 @@ function instrumentTanStackRouter(router) {
 	return () => {
 		stopBefore();
 		stopResolved();
+		if (open !== void 0) interruptNavigation();
+		open = void 0;
 	};
 }
 //#endregion