@maple-dev/browser 0.1.0 → 0.3.0

package/README.md

@@ -17,11 +17,11 @@ npm install @maple-dev/browser
 import { MapleBrowser } from "@maple-dev/browser"
 
 MapleBrowser.init({
-  ingestKey: "maple_pk_...",     // public ingest key
-  serviceName: "acme-web",
-  environment: "production",
-  replay: { enabled: true, sampleRate: 1.0 },
-  privacy: { maskAllInputs: true },
+	ingestKey: "maple_pk_...", // public ingest key
+	serviceName: "acme-web",
+	environment: "production",
+	replay: { enabled: true, sampleRate: 1.0 },
+	privacy: { maskAllInputs: true },
 })
 ```
 
@@ -35,6 +35,19 @@ That single call:
 - writes session metadata at start (`active`) and on page hide (`ended`),
   including the trace ids observed during the session.
 
+## 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.
+
+```ts
+MapleBrowser.identify(user.id)
+
+// after sign-out
+MapleBrowser.identify(null)
+```
+
 ## Privacy
 
 `maskAllInputs` (default **on**) masks every `<input>` value. Use rrweb's

package/dist/index.d.mts

@@ -7,12 +7,17 @@ interface MapleBrowserConfig {
   readonly serviceName: string;
   /** Maple ingest base URL. Defaults to `https://ingest.maple.dev`. */
   readonly endpoint?: string;
+  /**
+   * Logical group this service belongs to, emitted as the OTel
+   * `service.namespace` resource attribute on traces. Optional.
+   */
+  readonly serviceNamespace?: string;
   /** Service version / commit SHA. */
   readonly serviceVersion?: string;
   /** Deployment environment, e.g. "production". */
   readonly environment?: string;
-  /** Optional user id attached to the replay session. */
-  readonly userId?: string;
+  /** Optional user id attached to replay sessions and future browser spans. */
+  readonly userId?: string | null | undefined;
   readonly tracing?: {
     /** Default true. */readonly enabled?: boolean;
     /**
@@ -60,8 +65,8 @@ interface MapleBrowserHandle {
  * ```
  */
 declare const MapleBrowser: {
-  init: (config: MapleBrowserConfig) => MapleBrowserHandle; /** Attach (or replace) the user id on the active session. Safe to call repeatedly. */
-  identify: (userId: string) => void;
+  init: (config: MapleBrowserConfig) => MapleBrowserHandle; /** Attach, replace, or clear the user id on the active session. Safe to call repeatedly. */
+  identify: (userId?: string | null) => void;
 };
 //#endregion
 export { MapleBrowser, type MapleBrowserConfig, type MapleBrowserHandle };

package/dist/index.mjs

@@ -1,3 +1,5 @@
+import { trace } from "@opentelemetry/api";
+import { record } from "rrweb";
 import { WebTracerProvider } from "@opentelemetry/sdk-trace-web";
 import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
 import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
@@ -5,33 +7,7 @@ import { resourceFromAttributes } from "@opentelemetry/resources";
 import { registerInstrumentations } from "@opentelemetry/instrumentation";
 import { FetchInstrumentation } from "@opentelemetry/instrumentation-fetch";
 import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from "@opentelemetry/semantic-conventions";
-import { record } from "rrweb";
-import { trace } from "@opentelemetry/api";
-//#region src/config.ts
-const DEFAULT_ENDPOINT = "https://ingest.maple.dev";
-function resolveConfig(config) {
-	return {
-		ingestKey: config.ingestKey,
-		serviceName: config.serviceName,
-		endpoint: (config.endpoint ?? DEFAULT_ENDPOINT).replace(/\/$/, ""),
-		serviceVersion: config.serviceVersion,
-		environment: config.environment,
-		userId: config.userId,
-		tracingEnabled: config.tracing?.enabled ?? true,
-		tracingInstrumentFetch: config.tracing?.instrumentFetch ?? true,
-		replayEnabled: config.replay?.enabled ?? true,
-		replaySampleRate: config.replay?.sampleRate ?? 1,
-		maskAllInputs: config.privacy?.maskAllInputs ?? true,
-		maskAllText: config.privacy?.maskAllText ?? false
-	};
-}
-/** ClickHouse-style `YYYY-MM-DD HH:MM:SS.mmm` in UTC (matches the ingest gateway). */
-function formatCHDateTime(date) {
-	const pad = (n, width = 2) => String(n).padStart(width, "0");
-	return `${date.getUTCFullYear()}-${pad(date.getUTCMonth() + 1)}-${pad(date.getUTCDate())} ${pad(date.getUTCHours())}:${pad(date.getUTCMinutes())}:${pad(date.getUTCSeconds())}.${pad(date.getUTCMilliseconds(), 3)}`;
-}
-//#endregion
-//#region src/session.ts
+//#region ../browser-session/src/session.ts
 const STORAGE_KEY = "maple.session";
 /** Rotate the session after this much inactivity (PostHog's default). */
 const IDLE_TIMEOUT_MS = 30 * 6e4;
@@ -44,7 +20,8 @@ function freshRecord(now) {
 		id: crypto.randomUUID(),
 		startedAt: now,
 		lastActivityAt: now,
-		chunkSeq: 0
+		chunkSeq: 0,
+		metaVersion: 0
 	};
 }
 function readRecord() {
@@ -106,16 +83,26 @@ function nextChunkSeq() {
 	});
 	return seq;
 }
-/** Best-effort UA parse — enough to populate filterable session facets. */
-function parseUserAgent(ua) {
-	return {
-		browserName: /edg/i.test(ua) ? "Edge" : /opr|opera/i.test(ua) ? "Opera" : /chrome|crios/i.test(ua) ? "Chrome" : /firefox|fxios/i.test(ua) ? "Firefox" : /safari/i.test(ua) ? "Safari" : "Unknown",
-		osName: /windows/i.test(ua) ? "Windows" : /mac os|macintosh/i.test(ua) ? "macOS" : /android/i.test(ua) ? "Android" : /iphone|ipad|ios/i.test(ua) ? "iOS" : /linux/i.test(ua) ? "Linux" : "Unknown",
-		deviceType: /mobile|iphone|android.*mobile/i.test(ua) ? "mobile" : /ipad|tablet/i.test(ua) ? "tablet" : "desktop"
-	};
+/**
+* Take the next session-metadata row version for the current session.
+* Monotonic per session across reloads, hide/resume cycles, and writers (both
+* SDKs share the persisted counter), so `argMax(field, Version)` on the
+* backend always resolves to the most recently posted row. Records written by
+* older SDKs (no `metaVersion`) already posted versions 1 and 2, so the
+* counter resumes at 3 for them; a fresh session starts at 1.
+*/
+function nextMetaVersion() {
+	const record = readRecord() ?? freshRecord(Date.now());
+	const version = (record.metaVersion ?? 2) + 1;
+	writeRecord({
+		...record,
+		metaVersion: version
+	});
+	return version;
 }
 //#endregion
-//#region src/session-sink.ts
+//#region ../browser-session/src/sink.ts
+const SESSION_SINK_KEY = "__MAPLE_BROWSER_SESSION__";
 const observedTraceIds = /* @__PURE__ */ new Set();
 /** Record a trace id seen during the session. Idempotent per id. */
 function recordTraceId(traceId) {
@@ -124,12 +111,11 @@ function recordTraceId(traceId) {
 function getObservedTraceIds() {
 	return Array.from(observedTraceIds);
 }
-const SESSION_SINK_KEY = "__MAPLE_BROWSER_SESSION__";
 /**
-* Publish the session sink on `globalThis` so other tracers in the page (e.g. the
-* Effect client SDK) can attach their trace ids to this replay session without a
-* direct dependency on `@maple-dev/browser`. Reads are lazy/per-span on the consumer
-* side, so init ordering between the SDKs does not matter.
+* Publish the session sink on `globalThis` so other tracers in the page can
+* attach their trace ids to the active replay session without a direct
+* dependency on the publishing SDK. Reads are lazy/per-span on the consumer
+* side, so init ordering between SDKs does not matter.
 */
 function publishSessionSink(sessionId) {
 	globalThis[SESSION_SINK_KEY] = {
@@ -138,62 +124,63 @@ function publishSessionSink(sessionId) {
 	};
 }
 //#endregion
-//#region src/tracing.ts
-/**
-* Captures every span's trace id into the session sink. Lightweight — runs
-* alongside the BatchSpanProcessor, does no export of its own.
-*/
-var TraceIdCollector = class {
-	onStart(span) {
-		recordTraceId(span.spanContext().traceId);
-	}
-	onEnd(_span) {}
-	forceFlush() {
-		return Promise.resolve();
-	}
-	shutdown() {
-		return Promise.resolve();
-	}
-};
+//#region ../browser-session/src/user-agent.ts
+/** Best-effort UA parse — enough to populate filterable session facets. */
+function parseUserAgent(ua) {
+	return {
+		browserName: /edg/i.test(ua) ? "Edge" : /opr|opera/i.test(ua) ? "Opera" : /chrome|crios/i.test(ua) ? "Chrome" : /firefox|fxios/i.test(ua) ? "Firefox" : /safari/i.test(ua) ? "Safari" : "Unknown",
+		osName: /windows/i.test(ua) ? "Windows" : /iphone|ipad|ios/i.test(ua) ? "iOS" : /mac os|macintosh/i.test(ua) ? "macOS" : /android/i.test(ua) ? "Android" : /linux/i.test(ua) ? "Linux" : "Unknown",
+		deviceType: /mobile|iphone|android.*mobile/i.test(ua) ? "mobile" : /ipad|tablet/i.test(ua) ? "tablet" : "desktop"
+	};
+}
+//#endregion
+//#region ../browser-session/src/meta-row.ts
+/** ClickHouse-style `YYYY-MM-DD HH:MM:SS.mmm` in UTC (matches the ingest gateway). */
+function formatCHDateTime(date) {
+	const pad = (n, width = 2) => String(n).padStart(width, "0");
+	return `${date.getUTCFullYear()}-${pad(date.getUTCMonth() + 1)}-${pad(date.getUTCDate())} ${pad(date.getUTCHours())}:${pad(date.getUTCMinutes())}:${pad(date.getUTCSeconds())}.${pad(date.getUTCMilliseconds(), 3)}`;
+}
 /**
-* Set up browser OTel tracing exporting to Maple's ingest, tagging the resource
-* with the shared `session.id`. When `tracingInstrumentFetch` is true, fetch()
-* calls are auto-instrumented and their trace ids feed the session. Disable it
-* when an external tracer (e.g. the Effect client SDK) already instruments
-* requests — that tracer feeds the session via the published sink instead, and
-* this avoids redundant duplicate network spans. Returns a shutdown function.
+* Build one `/v1/sessionReplays/meta` NDJSON row. Shared by `@maple-dev/browser`
+* and the Effect client SDK so a session looks identical no matter which SDK
+* posted it. UA/URL facets come from the live browser globals; absent (tests,
+* exotic embedders) they fall back to empty strings.
 */
-function setupTracing(config, sessionId) {
-	const attributes = {
-		[ATTR_SERVICE_NAME]: config.serviceName,
-		"maple.sdk.type": "browser",
-		"session.id": sessionId
+function buildSessionMetaRow(input) {
+	const g = globalThis;
+	const userAgent = g["navigator"]?.userAgent ?? "";
+	const ua = parseUserAgent(userAgent);
+	const now = /* @__PURE__ */ new Date();
+	const row = {
+		session_id: input.sessionId,
+		start_time: formatCHDateTime(input.startedAt),
+		status: input.status,
+		version: input.version,
+		user_id: input.userId ?? "",
+		url_initial: g["window"]?.location?.href ?? "",
+		user_agent: userAgent,
+		browser_name: ua.browserName,
+		os_name: ua.osName,
+		device_type: ua.deviceType,
+		service_name: input.serviceName,
+		resource_attributes: {
+			...input.environment ? {
+				"deployment.environment": input.environment,
+				"deployment.environment.name": input.environment
+			} : {},
+			...input.serviceVersion ? { "deployment.commit_sha": input.serviceVersion } : {}
+		}
 	};
-	if (config.serviceVersion) {
-		attributes[ATTR_SERVICE_VERSION] = config.serviceVersion;
-		attributes["deployment.commit_sha"] = config.serviceVersion;
-	}
-	if (config.environment) {
-		attributes["deployment.environment"] = config.environment;
-		attributes["deployment.environment.name"] = config.environment;
+	if (input.status === "ended") {
+		row.end_time = formatCHDateTime(now);
+		row.duration_ms = Math.max(0, now.getTime() - input.startedAt.getTime());
+		row.click_count = input.clickCount ?? 0;
+		row.trace_ids = input.traceIds ? Array.from(input.traceIds) : [];
 	}
-	const exporter = new OTLPTraceExporter({
-		url: `${config.endpoint}/v1/traces`,
-		headers: { Authorization: `Bearer ${config.ingestKey}` }
-	});
-	const provider = new WebTracerProvider({
-		resource: resourceFromAttributes(attributes),
-		spanProcessors: [new TraceIdCollector(), new BatchSpanProcessor(exporter)]
-	});
-	provider.register();
-	if (config.tracingInstrumentFetch) registerInstrumentations({ instrumentations: [new FetchInstrumentation({ ignoreUrls: [new RegExp(`${escapeRegExp(config.endpoint)}/v1/`)] })] });
-	return () => provider.shutdown();
-}
-function escapeRegExp(value) {
-	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	return row;
 }
 //#endregion
-//#region src/replay/transport.ts
+//#region ../browser-session/src/replay/transport.ts
 let lastWarnAt = 0;
 function warnDropped(what, error) {
 	const now = Date.now();
@@ -261,75 +248,7 @@ async function postSessionBlob(config, meta, gzipped, keepalive = false) {
 	});
 }
 //#endregion
-//#region src/replay/util.ts
-/** Approximate byte size of an event for flush-threshold accounting. Falls back
-*  to a fixed estimate for values that can't be serialized (e.g. cycles). */
-function approximateSize(value) {
-	try {
-		return JSON.stringify(value).length;
-	} catch {
-		return 256;
-	}
-}
-//#endregion
-//#region src/replay/record.ts
-const FULL_SNAPSHOT = 2;
-const INCREMENTAL = 3;
-const SOURCE_MOUSE_INTERACTION = 2;
-const MOUSE_CLICK = 2;
-const FLUSH_INTERVAL_MS$1 = 5e3;
-const FLUSH_BYTES$1 = 100 * 1024;
-const CHECKOUT_EVERY_MS = 3e4;
-function startRecording(config, sessionId) {
-	let buffer = [];
-	let bufferBytes = 0;
-	let bufferHasCheckpoint = false;
-	let clickCount = 0;
-	const flush = async (keepalive = false) => {
-		if (buffer.length === 0) return;
-		markActivity();
-		const events = buffer;
-		const isCheckpoint = bufferHasCheckpoint;
-		const seq = nextChunkSeq();
-		const first = events[0].timestamp;
-		const last = events[events.length - 1].timestamp;
-		buffer = [];
-		bufferBytes = 0;
-		bufferHasCheckpoint = false;
-		const gzipped = await gzip(new TextEncoder().encode(JSON.stringify(events)));
-		await postSessionBlob(config, {
-			sessionId,
-			chunkSeq: seq,
-			isCheckpoint,
-			eventCount: events.length,
-			durationMs: Math.max(0, last - first)
-		}, gzipped, keepalive);
-	};
-	const stop = record({
-		emit: (event, isCheckpoint) => {
-			const e = event;
-			if (isCheckpoint === true || e.type === FULL_SNAPSHOT) bufferHasCheckpoint = true;
-			if (e.type === INCREMENTAL && e.data?.source === SOURCE_MOUSE_INTERACTION && e.data.type === MOUSE_CLICK) clickCount++;
-			buffer.push(e);
-			bufferBytes += approximateSize(e);
-			if (bufferBytes >= FLUSH_BYTES$1) flush();
-		},
-		maskAllInputs: config.maskAllInputs,
-		...config.maskAllText ? { maskTextSelector: "*" } : {},
-		checkoutEveryNms: CHECKOUT_EVERY_MS
-	});
-	const flushTimer = setInterval(() => void flush(), FLUSH_INTERVAL_MS$1);
-	return {
-		stop: () => {
-			clearInterval(flushTimer);
-			stop?.();
-		},
-		flush,
-		getClickCount: () => clickCount
-	};
-}
-//#endregion
-//#region src/replay/capture/shared.ts
+//#region ../browser-session/src/replay/capture/shared.ts
 /** Emit best-effort: capture must never throw into the host app's call site. */
 function safeEmit(emit, ev) {
 	try {
@@ -337,7 +256,7 @@ function safeEmit(emit, ev) {
 	} catch {}
 }
 //#endregion
-//#region src/replay/capture/console.ts
+//#region ../browser-session/src/replay/capture/console.ts
 const LEVELS = [
 	"log",
 	"info",
@@ -385,7 +304,7 @@ function formatArgs(args) {
 	return text.length > MAX_MESSAGE ? `${text.slice(0, MAX_MESSAGE)}…` : text;
 }
 //#endregion
-//#region src/replay/capture/network.ts
+//#region ../browser-session/src/replay/capture/network.ts
 /**
 * Capture fetch + XHR requests as session events, tagged with the active trace
 * id so each request links to its backend trace. `ignoreUrl` skips Maple's own
@@ -459,7 +378,7 @@ function requestMethod(input, init) {
 	return (init?.method ?? (typeof input === "object" && "method" in input ? input.method : void 0) ?? "GET").toUpperCase();
 }
 //#endregion
-//#region src/replay/capture/errors.ts
+//#region ../browser-session/src/replay/capture/errors.ts
 const MAX_STACK = 4e3;
 /** Capture uncaught errors + unhandled promise rejections as session events. */
 function installErrorCapture(emit) {
@@ -494,7 +413,7 @@ function truncate(stack) {
 	return stack.length > MAX_STACK ? `${stack.slice(0, MAX_STACK)}…` : stack;
 }
 //#endregion
-//#region src/replay/capture/navigation.ts
+//#region ../browser-session/src/replay/capture/navigation.ts
 /**
 * Capture page views as session events: the initial load plus every SPA
 * navigation (history pushState/replaceState, popstate, hashchange).
@@ -533,7 +452,7 @@ function installNavigationCapture(emit) {
 	};
 }
 //#endregion
-//#region src/replay/capture/interactions.ts
+//#region ../browser-session/src/replay/capture/interactions.ts
 const MAX_TEXT = 120;
 /**
 * Capture clicks and input events as session events. Listens in the capture
@@ -576,13 +495,29 @@ function textOf(el) {
 	return text.length > MAX_TEXT ? `${text.slice(0, MAX_TEXT)}…` : text;
 }
 //#endregion
-//#region src/replay/events.ts
-const FLUSH_INTERVAL_MS = 5e3;
-const FLUSH_BYTES = 64 * 1024;
+//#region ../browser-session/src/replay/util.ts
+/** Approximate byte size of an event for flush-threshold accounting. Falls back
+*  to a fixed estimate for values that can't be serialized (e.g. cycles). */
+function approximateSize(value) {
+	try {
+		return JSON.stringify(value).length;
+	} catch {
+		return 256;
+	}
+}
+//#endregion
+//#region ../browser-session/src/replay/events.ts
+const FLUSH_INTERVAL_MS$1 = 5e3;
+const FLUSH_BYTES$1 = 64 * 1024;
 const ZERO_TRACE_ID = "00000000000000000000000000000000";
-/** The OTel trace id of the active span, or undefined when none is active. */
+let traceIdProvider = () => void 0;
+/** Wire the host SDK's active-trace-id lookup into event capture. */
+function setActiveTraceIdProvider(provider) {
+	traceIdProvider = provider;
+}
+/** The trace id of the active span, or undefined when none is active. */
 function activeTraceId() {
-	const id = trace.getActiveSpan()?.spanContext().traceId;
+	const id = traceIdProvider();
 	return id && id !== ZERO_TRACE_ID ? id : void 0;
 }
 /**
@@ -600,7 +535,7 @@ function startEventCapture(config, sessionId) {
 			seq: seq++
 		});
 		bufferBytes += approximateSize(ev);
-		if (bufferBytes >= FLUSH_BYTES) flush();
+		if (bufferBytes >= FLUSH_BYTES$1) flush();
 	};
 	const flush = async (keepalive = false) => {
 		if (buffer.length === 0) return;
@@ -618,7 +553,7 @@ function startEventCapture(config, sessionId) {
 		installNetworkCapture(emit, ignoreUrl),
 		installErrorCapture(emit)
 	];
-	const flushTimer = setInterval(() => void flush(), FLUSH_INTERVAL_MS);
+	const flushTimer = setInterval(() => void flush(), FLUSH_INTERVAL_MS$1);
 	return {
 		stop: () => {
 			clearInterval(flushTimer);
@@ -649,6 +584,234 @@ function toRow(sessionId, ev, seq) {
 	};
 }
 //#endregion
+//#region ../browser-session/src/replay/record.ts
+const FULL_SNAPSHOT = 2;
+const INCREMENTAL = 3;
+const SOURCE_MOUSE_INTERACTION = 2;
+const MOUSE_CLICK = 2;
+const FLUSH_INTERVAL_MS = 5e3;
+const FLUSH_BYTES = 100 * 1024;
+const CHECKOUT_EVERY_MS = 3e4;
+function startRecording(config, sessionId) {
+	let buffer = [];
+	let bufferBytes = 0;
+	let bufferHasCheckpoint = false;
+	let clickCount = 0;
+	const flush = async (keepalive = false) => {
+		if (buffer.length === 0) return;
+		markActivity();
+		const events = buffer;
+		const isCheckpoint = bufferHasCheckpoint;
+		const seq = nextChunkSeq();
+		const first = events[0].timestamp;
+		const last = events[events.length - 1].timestamp;
+		buffer = [];
+		bufferBytes = 0;
+		bufferHasCheckpoint = false;
+		const gzipped = await gzip(new TextEncoder().encode(JSON.stringify(events)));
+		await postSessionBlob(config, {
+			sessionId,
+			chunkSeq: seq,
+			isCheckpoint,
+			eventCount: events.length,
+			durationMs: Math.max(0, last - first)
+		}, gzipped, keepalive);
+	};
+	const stop = record({
+		emit: (event, isCheckpoint) => {
+			const e = event;
+			if (isCheckpoint === true || e.type === FULL_SNAPSHOT) bufferHasCheckpoint = true;
+			if (e.type === INCREMENTAL && e.data?.source === SOURCE_MOUSE_INTERACTION && e.data.type === MOUSE_CLICK) clickCount++;
+			buffer.push(e);
+			bufferBytes += approximateSize(e);
+			if (bufferBytes >= FLUSH_BYTES) flush();
+		},
+		maskAllInputs: config.maskAllInputs,
+		...config.maskAllText ? { maskTextSelector: "*" } : {},
+		checkoutEveryNms: CHECKOUT_EVERY_MS
+	});
+	const flushTimer = setInterval(() => void flush(), FLUSH_INTERVAL_MS);
+	return {
+		stop: () => {
+			clearInterval(flushTimer);
+			stop?.();
+		},
+		flush,
+		getClickCount: () => clickCount
+	};
+}
+//#endregion
+//#region ../browser-session/src/replay-session.ts
+/**
+* Start recording the current browser session. Publishes the session sink,
+* posts an `active` metadata row, and installs visibility handlers:
+* hidden → flush + `ended` row (with observed trace ids) + stop capture;
+* visible → re-resolve the session (rotating if idle-expired), republish the
+* sink, restart capture, post a fresh `active` row. Metadata versions are
+* monotonic per session, so the latest row always wins on the backend.
+*
+* Returns undefined outside a browser. Sampling is the caller's decision.
+*/
+function startReplaySession(options) {
+	if (typeof window === "undefined") return void 0;
+	const engineConfig = {
+		endpoint: options.endpoint.replace(/\/$/, ""),
+		ingestKey: options.ingestKey,
+		maskAllInputs: options.maskAllInputs,
+		maskAllText: options.maskAllText
+	};
+	const session = getSession();
+	let currentSessionId = session.id;
+	let currentStartedAt = new Date(session.startedAt);
+	publishSessionSink(currentSessionId);
+	let recorder;
+	let events;
+	let stopped = false;
+	const postMeta = (status, clickCount, keepalive = false) => postSessionMeta(engineConfig, buildSessionMetaRow({
+		sessionId: currentSessionId,
+		startedAt: currentStartedAt,
+		version: nextMetaVersion(),
+		status,
+		serviceName: options.serviceName,
+		userId: options.getUserId?.(),
+		environment: options.environment,
+		serviceVersion: options.serviceVersion,
+		clickCount: clickCount ?? 0,
+		traceIds: status === "ended" ? getObservedTraceIds() : void 0
+	}), keepalive);
+	const start = () => {
+		recorder = startRecording(engineConfig, currentSessionId);
+		events = startEventCapture(engineConfig, currentSessionId);
+		postMeta("active", null);
+	};
+	const suspend = () => {
+		if (!recorder || !events) return;
+		recorder.flush(true);
+		events.flush(true);
+		postMeta("ended", recorder.getClickCount(), true);
+		recorder.stop();
+		events.stop();
+		recorder = void 0;
+		events = void 0;
+	};
+	const resume = () => {
+		if (stopped || recorder) return;
+		const next = getSession();
+		if (next.id !== currentSessionId) {
+			currentSessionId = next.id;
+			currentStartedAt = new Date(next.startedAt);
+			publishSessionSink(currentSessionId);
+		}
+		start();
+	};
+	const onVisibilityChange = () => {
+		if (document.visibilityState === "hidden") suspend();
+		else resume();
+	};
+	const onPageHide = () => suspend();
+	start();
+	document.addEventListener("visibilitychange", onVisibilityChange);
+	window.addEventListener("pagehide", onPageHide);
+	return {
+		sessionId: currentSessionId,
+		shutdown: async () => {
+			stopped = true;
+			document.removeEventListener("visibilitychange", onVisibilityChange);
+			window.removeEventListener("pagehide", onPageHide);
+			if (recorder) await recorder.flush(true);
+			if (events) await events.flush(true);
+			recorder?.stop();
+			events?.stop();
+			recorder = void 0;
+			events = void 0;
+		}
+	};
+}
+//#endregion
+//#region src/config.ts
+const DEFAULT_ENDPOINT = "https://ingest.maple.dev";
+function normalizeUserId(userId) {
+	return userId ? userId : void 0;
+}
+function resolveConfig(config) {
+	return {
+		ingestKey: config.ingestKey,
+		serviceName: config.serviceName,
+		endpoint: (config.endpoint ?? DEFAULT_ENDPOINT).replace(/\/$/, ""),
+		serviceNamespace: config.serviceNamespace,
+		serviceVersion: config.serviceVersion,
+		environment: config.environment,
+		userId: normalizeUserId(config.userId),
+		tracingEnabled: config.tracing?.enabled ?? true,
+		tracingInstrumentFetch: config.tracing?.instrumentFetch ?? true,
+		replayEnabled: config.replay?.enabled ?? true,
+		replaySampleRate: config.replay?.sampleRate ?? 1,
+		maskAllInputs: config.privacy?.maskAllInputs ?? true,
+		maskAllText: config.privacy?.maskAllText ?? false
+	};
+}
+//#endregion
+//#region src/tracing.ts
+/**
+* Captures every span's trace id into the session sink. Lightweight — runs
+* alongside the BatchSpanProcessor, does no export of its own.
+*/
+var TraceIdCollector = class {
+	constructor(getUserId = () => void 0) {
+		this.getUserId = getUserId;
+	}
+	onStart(span) {
+		recordTraceId(span.spanContext().traceId);
+		const userId = this.getUserId();
+		if (userId !== void 0) span.setAttribute("user.id", userId);
+	}
+	onEnd(_span) {}
+	forceFlush() {
+		return Promise.resolve();
+	}
+	shutdown() {
+		return Promise.resolve();
+	}
+};
+/**
+* Set up browser OTel tracing exporting to Maple's ingest, tagging the resource
+* with the shared `session.id`. When `tracingInstrumentFetch` is true, fetch()
+* calls are auto-instrumented and their trace ids feed the session. Disable it
+* when an external tracer (e.g. the Effect client SDK) already instruments
+* requests — that tracer feeds the session via the published sink instead, and
+* this avoids redundant duplicate network spans. Returns a shutdown function.
+*/
+function setupTracing(config, sessionId) {
+	const attributes = {
+		[ATTR_SERVICE_NAME]: config.serviceName,
+		"maple.sdk.type": "browser",
+		"session.id": sessionId
+	};
+	if (config.serviceNamespace) attributes["service.namespace"] = config.serviceNamespace;
+	if (config.serviceVersion) {
+		attributes[ATTR_SERVICE_VERSION] = config.serviceVersion;
+		attributes["deployment.commit_sha"] = config.serviceVersion;
+	}
+	if (config.environment) {
+		attributes["deployment.environment"] = config.environment;
+		attributes["deployment.environment.name"] = config.environment;
+	}
+	const exporter = new OTLPTraceExporter({
+		url: `${config.endpoint}/v1/traces`,
+		headers: { Authorization: `Bearer ${config.ingestKey}` }
+	});
+	const provider = new WebTracerProvider({
+		resource: resourceFromAttributes(attributes),
+		spanProcessors: [new TraceIdCollector(() => config.userId), new BatchSpanProcessor(exporter)]
+	});
+	provider.register();
+	if (config.tracingInstrumentFetch) registerInstrumentations({ instrumentations: [new FetchInstrumentation({ ignoreUrls: [new RegExp(`${escapeRegExp(config.endpoint)}/v1/`)] })] });
+	return () => provider.shutdown();
+}
+function escapeRegExp(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+//#endregion
 //#region src/init.ts
 let active;
 let activeConfig;
@@ -656,6 +819,10 @@ let activeConfig;
 * Initialize Maple browser telemetry: OTel tracing + (sampled) rrweb session
 * replay, both tagged with one shared session id so a trace can link to its
 * replay and vice versa. Idempotent — repeated calls return the live handle.
+*
+* The replay lifecycle (suspend on tab-hidden, resume on visible, session
+* metadata rows) lives in `@maple/browser-session` and is shared with the
+* Effect client SDK's `replay` option.
 */
 function init(rawConfig) {
 	if (active) return active;
@@ -666,26 +833,26 @@ function init(rawConfig) {
 	const config = resolveConfig(rawConfig);
 	activeConfig = config;
 	const session = getSession();
-	const sessionId = session.id;
-	const startedAt = new Date(session.startedAt);
-	publishSessionSink(sessionId);
-	const shutdownTracing = config.tracingEnabled ? setupTracing(config, sessionId) : void 0;
+	publishSessionSink(session.id);
+	setActiveTraceIdProvider(() => trace.getActiveSpan()?.spanContext().traceId);
+	const shutdownTracing = config.tracingEnabled ? setupTracing(config, session.id) : void 0;
 	const recordReplay = config.replayEnabled && Math.random() < config.replaySampleRate;
-	let recorder;
-	let events;
-	if (recordReplay) {
-		recorder = startRecording(config, sessionId);
-		events = startEventCapture(config, sessionId);
-		postSessionMeta(config, sessionMetaRow(config, sessionId, startedAt, 1, "active", null));
-		installLifecycleHandlers(config, sessionId, startedAt, recorder, events);
-	}
+	let replay;
+	if (recordReplay) replay = startReplaySession({
+		endpoint: config.endpoint,
+		ingestKey: config.ingestKey,
+		serviceName: config.serviceName,
+		environment: config.environment,
+		serviceVersion: config.serviceVersion,
+		maskAllInputs: config.maskAllInputs,
+		maskAllText: config.maskAllText,
+		getUserId: () => activeConfig?.userId
+	});
 	const handle = {
-		sessionId,
+		sessionId: session.id,
 		shutdown: async () => {
-			if (recorder) await recorder.flush(true);
-			if (events) await events.flush(true);
-			recorder?.stop();
-			events?.stop();
+			await replay?.shutdown();
+			replay = void 0;
 			await shutdownTracing?.();
 			active = void 0;
 			activeConfig = void 0;
@@ -695,64 +862,14 @@ function init(rawConfig) {
 	return handle;
 }
 /**
-* Attach (or replace) the user id on the active session. Idempotent and safe to
-* call on every render. The session's authoritative row is the `Version=2`
-* "ended" row posted on unload, which reads `config.userId` at that moment — so
-* an id set here before the session ends is what the session is tagged with.
-* We deliberately do not re-post the active row (the SDK already writes a fresh
-* `Version=1` row on every reload; a second write here would collide under
-* `argMax(field, Version)`).
+* Attach, replace, or clear the user id on the active session. Idempotent and
+* safe to call on every render. Future browser-created spans read this value
+* when they start, and future session metadata rows read it when they post.
 */
 function identify(userId) {
 	if (typeof window === "undefined") return;
 	if (!activeConfig) return;
-	if (!userId) return;
-	if (activeConfig.userId === userId) return;
-	activeConfig.userId = userId;
-}
-function installLifecycleHandlers(config, sessionId, startedAt, recorder, events) {
-	let finalized = false;
-	const finalize = () => {
-		if (finalized) return;
-		finalized = true;
-		recorder.flush(true);
-		events.flush(true);
-		postSessionMeta(config, sessionMetaRow(config, sessionId, startedAt, 2, "ended", recorder.getClickCount()), true);
-		recorder.stop();
-		events.stop();
-	};
-	document.addEventListener("visibilitychange", () => {
-		if (document.visibilityState === "hidden") finalize();
-	});
-	window.addEventListener("pagehide", finalize);
-}
-function sessionMetaRow(config, sessionId, startedAt, version, status, clickCount) {
-	const ua = parseUserAgent(navigator.userAgent);
-	const now = /* @__PURE__ */ new Date();
-	const row = {
-		session_id: sessionId,
-		start_time: formatCHDateTime(startedAt),
-		status,
-		version,
-		user_id: config.userId ?? "",
-		url_initial: window.location.href,
-		user_agent: navigator.userAgent,
-		browser_name: ua.browserName,
-		os_name: ua.osName,
-		device_type: ua.deviceType,
-		service_name: config.serviceName,
-		resource_attributes: config.environment ? {
-			"deployment.environment": config.environment,
-			"deployment.environment.name": config.environment
-		} : {}
-	};
-	if (status === "ended") {
-		row.end_time = formatCHDateTime(now);
-		row.duration_ms = Math.max(0, now.getTime() - startedAt.getTime());
-		row.click_count = clickCount ?? 0;
-		row.trace_ids = getObservedTraceIds();
-	}
-	return row;
+	activeConfig.userId = normalizeUserId(userId);
 }
 //#endregion
 //#region src/index.ts

package/package.json

@@ -1,13 +1,21 @@
 {
 	"name": "@maple-dev/browser",
-	"version": "0.1.0",
+	"version": "0.3.0",
 	"description": "Maple browser SDK — OpenTelemetry tracing and rrweb session replay in one package. Every span and replay event shares a session id for trace↔replay correlation.",
+	"keywords": [
+		"maple",
+		"observability",
+		"opentelemetry",
+		"rrweb",
+		"rum",
+		"session-replay"
+	],
 	"license": "MIT",
-	"type": "module",
 	"files": [
 		"dist",
 		"README.md"
 	],
+	"type": "module",
 	"exports": {
 		".": {
 			"types": "./dist/index.d.mts",
@@ -31,16 +39,9 @@
 		"rrweb": "^2.0.0-alpha.18"
 	},
 	"devDependencies": {
+		"@maple/browser-session": "0.1.0",
 		"tsdown": "^0.21.7",
 		"typescript": "^6.0.2",
-		"vitest": "^4.1.2"
-	},
-	"keywords": [
-		"maple",
-		"opentelemetry",
-		"session-replay",
-		"rrweb",
-		"observability",
-		"rum"
-	]
+		"vitest": "^4.1.9"
+	}
 }