@maple-dev/browser 0.3.0 → 0.8.0

package/dist/index.mjs

@@ -1,737 +1,304 @@
+import { C as setActiveTraceIdProvider, T as setVisitorTracking, a as recordTraceId, b as sdkHint, c as getActiveSink, d as getSession, g as SDK_HINT_HEADER, h as postSessionMetaRow, i as readSessionSink, l as queuePending, m as rotateSession, n as getObservedTraceIds, o as startSessionLifecycle, r as publishSessionSink, s as clearPendingEvents, t as clearSessionSink, u as startEventSink, w as configureVisitorCookie } from "./sink-D9w1kg0Q.mjs";
 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";
-import { resourceFromAttributes } from "@opentelemetry/resources";
 import { registerInstrumentations } from "@opentelemetry/instrumentation";
 import { FetchInstrumentation } from "@opentelemetry/instrumentation-fetch";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { WebTracerProvider } from "@opentelemetry/sdk-trace-web";
 import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from "@opentelemetry/semantic-conventions";
-//#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;
-/** Hard cap on a single session's lifetime regardless of activity. */
-const MAX_SESSION_MS = 1440 * 6e4;
-/** In-memory fallback when sessionStorage is unavailable (private mode). */
-let ephemeral;
-function freshRecord(now) {
-	return {
-		id: crypto.randomUUID(),
-		startedAt: now,
-		lastActivityAt: now,
-		chunkSeq: 0,
-		metaVersion: 0
-	};
-}
-function readRecord() {
-	try {
-		const raw = window.sessionStorage.getItem(STORAGE_KEY);
-		if (!raw) return void 0;
-		const parsed = JSON.parse(raw);
-		if (typeof parsed.id === "string" && typeof parsed.startedAt === "number" && typeof parsed.lastActivityAt === "number" && typeof parsed.chunkSeq === "number") return parsed;
-		return;
-	} catch {
-		return ephemeral;
-	}
-}
-function writeRecord(record) {
-	ephemeral = record;
-	try {
-		window.sessionStorage.setItem(STORAGE_KEY, JSON.stringify(record));
-	} catch {}
-}
-function isExpired(record, now) {
-	return now - record.lastActivityAt > IDLE_TIMEOUT_MS || now - record.startedAt > MAX_SESSION_MS;
-}
+//#region ../browser-session/src/identity/consent.ts
 /**
-* Resolve the active session, rotating to a fresh one if the previous session
-* has gone idle (or hit the lifetime cap). Touches `lastActivityAt` so calling
-* it on page load keeps a live session alive. The id is the correlation key
-* shared by OTel traces and replay events.
+* Consent gating for session capture.
+*
+* The posture, deliberately:
+*
+* - `requireConsent` defaults to **false**. Flipping that default would
+*   silently stop telemetry for every existing install — an availability
+*   incident dressed up as a privacy win. Apps that need a consent gate opt in.
+* - Global Privacy Control **is** honored by default, but only against the
+*   persistent visitor id, not the session itself. GPC is a legally recognized
+*   signal in several US states and it maps exactly onto the one cross-session
+*   identifier this SDK stores; the session-scoped capture that powers replay
+*   and error triage is unaffected.
+* - `doNotTrack` is **not** honored by default. It is deprecated, removed from
+*   Safari, and ignored across the industry, so respecting it would mostly mean
+*   dropping data from users who never intended to opt out. Apps can turn it on.
 */
-function getSession() {
-	const now = Date.now();
-	const existing = readRecord();
-	const record = existing && !isExpired(existing, now) ? {
-		...existing,
-		lastActivityAt: now
-	} : freshRecord(now);
-	writeRecord(record);
-	return record;
-}
-/** Mark the session as active right now (called as replay chunks flush). */
-function markActivity() {
-	const record = readRecord();
-	if (!record) return;
-	writeRecord({
-		...record,
-		lastActivityAt: Date.now()
-	});
-}
 /**
-* Take the next replay chunk sequence number for the current session. Monotonic
-* across reloads (persisted on the session record), so a refresh continues the
-* sequence instead of restarting at 0 and overwriting the previous load's blobs.
+* Consent lives on `globalThis`, for the same reason the event sink does
+* (`events/events-sink.ts`): an app that bundles both `@maple-dev/browser` and the
+* Effect SDK gets **two copies** of this module, and per-copy state would mean
+* `setConsent(true)` on one never releases the other copy's exporters — or, the
+* other way round, one copy capturing while the other believes consent is
+* required. There is one user and one decision, so there is one state.
 */
-function nextChunkSeq() {
-	const record = readRecord() ?? freshRecord(Date.now());
-	const seq = record.chunkSeq;
-	writeRecord({
-		...record,
-		chunkSeq: seq + 1
-	});
-	return seq;
+const CONSENT_KEY = "__MAPLE_BROWSER_CONSENT__";
+function consentState() {
+	const owner = globalThis;
+	const existing = owner[CONSENT_KEY];
+	if (existing) return existing;
+	const fresh = {
+		allowedSince: 0,
+		granted: false,
+		listeners: /* @__PURE__ */ new Set(),
+		requireConsent: false,
+		respectDoNotTrack: false
+	};
+	owner[CONSENT_KEY] = fresh;
+	return fresh;
+}
+function updateEffectiveConsent(previous) {
+	const state = consentState();
+	const allowed = hasConsent();
+	if (allowed === previous) return;
+	state.allowedSince = allowed ? Date.now() : Number.POSITIVE_INFINITY;
+	for (const listener of state.listeners) try {
+		listener(allowed);
+	} catch {}
 }
 /**
-* 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.
+* Apply the host app's privacy config. Call before anything captures.
+*
+* Both SDKs call this at startup, and an app can init one of them without a
+* `privacy` block — so the gates only ever **tighten**. Letting the second
+* caller's absent option reset `requireConsent` back to false would silently
+* disable a gate the first caller asked for, and the resulting
+* denied→allowed transition would start capture on a user who never consented.
+* To genuinely relax a gate, reload without it.
 */
-function nextMetaVersion() {
-	const record = readRecord() ?? freshRecord(Date.now());
-	const version = (record.metaVersion ?? 2) + 1;
-	writeRecord({
-		...record,
-		metaVersion: version
+function configurePrivacy(options) {
+	const state = consentState();
+	const previous = hasConsent();
+	state.requireConsent = state.requireConsent || (options?.requireConsent ?? false);
+	state.respectDoNotTrack = state.respectDoNotTrack || (options?.respectDoNotTrack ?? false);
+	configureVisitorCookie({
+		crossSubdomainCookie: options?.crossSubdomainCookie,
+		cookieDomain: options?.cookieDomain
 	});
-	return version;
+	updateEffectiveConsent(previous);
 }
-//#endregion
-//#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) {
-	observedTraceIds.add(traceId);
+/** Record the user's consent decision. No-op unless `requireConsent` is set. */
+function setConsent(nextGranted) {
+	const previous = hasConsent();
+	consentState().granted = nextGranted;
+	updateEffectiveConsent(previous);
 }
-function getObservedTraceIds() {
-	return Array.from(observedTraceIds);
+/** Whether capture may proceed at all. */
+function hasConsent() {
+	const state = consentState();
+	return !state.requireConsent || state.granted;
 }
 /**
-* 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.
+* Subscribe to effective capture permission changes. The listener is invoked
+* only when capture actually transitions between allowed and denied; changing
+* the stored decision while `requireConsent` is off is deliberately silent.
 */
-function publishSessionSink(sessionId) {
-	globalThis[SESSION_SINK_KEY] = {
-		sessionId,
-		recordTraceId
-	};
-}
-//#endregion
-//#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)}`;
+function onConsentChange(listener) {
+	const { listeners } = consentState();
+	listeners.add(listener);
+	return () => listeners.delete(listener);
 }
 /**
-* 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.
+* Earliest epoch-ms timestamp telemetry may export for the current grant.
+* `Infinity` means capture is denied. Exporters use this to discard anything
+* buffered before a late grant or across a revoke/re-grant cycle.
 */
-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 (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) : [];
-	}
-	return row;
-}
-//#endregion
-//#region ../browser-session/src/replay/transport.ts
-let lastWarnAt = 0;
-function warnDropped(what, error) {
-	const now = Date.now();
-	if (now - lastWarnAt < 3e4) return;
-	lastWarnAt = now;
-	console.warn(`[maple] session replay ${what} failed (dropping; will retry on next chunk):`, error);
-}
-/** gzip a byte buffer using the native CompressionStream (no library). */
-async function gzip(bytes) {
-	const stream = new CompressionStream("gzip");
-	const writer = stream.writable.getWriter();
-	writer.write(bytes);
-	writer.close();
-	const buffer = await new Response(stream.readable).arrayBuffer();
-	return new Uint8Array(buffer);
-}
-/** POST session metadata (NDJSON, single row). `keepalive` for the final unload write. */
-async function postSessionMeta(config, row, keepalive = false) {
-	const body = `${JSON.stringify(row)}\n`;
-	await fetch(`${config.endpoint}/v1/sessionReplays/meta`, {
-		method: "POST",
-		headers: {
-			Authorization: `Bearer ${config.ingestKey}`,
-			"content-type": "application/x-ndjson"
-		},
-		body,
-		keepalive
-	}).catch((error) => {
-		warnDropped("metadata POST", error);
-	});
-}
-/** POST distilled session events (NDJSON, one row per event). Best-effort. */
-async function postSessionEvents(config, rows, keepalive = false) {
-	if (rows.length === 0) return;
-	const body = `${rows.map((row) => JSON.stringify(row)).join("\n")}\n`;
-	await fetch(`${config.endpoint}/v1/sessionEvents`, {
-		method: "POST",
-		headers: {
-			Authorization: `Bearer ${config.ingestKey}`,
-			"content-type": "application/x-ndjson"
-		},
-		body,
-		keepalive
-	}).catch((error) => {
-		warnDropped("events POST", error);
-	});
+function consentAllowedSince() {
+	return hasConsent() ? consentState().allowedSince : Number.POSITIVE_INFINITY;
 }
-/** PUT a gzipped rrweb event chunk. */
-async function postSessionBlob(config, meta, gzipped, keepalive = false) {
-	await fetch(`${config.endpoint}/v1/sessionReplays/blob`, {
-		method: "POST",
-		headers: {
-			Authorization: `Bearer ${config.ingestKey}`,
-			"content-type": "application/octet-stream",
-			"x-maple-session-id": meta.sessionId,
-			"x-maple-chunk-seq": String(meta.chunkSeq),
-			"x-maple-is-checkpoint": meta.isCheckpoint ? "1" : "0",
-			"x-maple-event-count": String(meta.eventCount),
-			"x-maple-duration-ms": String(meta.durationMs)
-		},
-		body: gzipped,
-		keepalive
-	}).catch((error) => {
-		warnDropped("blob PUT", error);
-	});
-}
-//#endregion
-//#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 {
-		emit(ev);
-	} catch {}
-}
-//#endregion
-//#region ../browser-session/src/replay/capture/console.ts
-const LEVELS = [
-	"log",
-	"info",
-	"warn",
-	"error",
-	"debug"
-];
-const MAX_MESSAGE = 2e3;
 /**
-* Capture `console.*` calls as session events. Wraps each method, emits a
-* distilled record, then forwards to the original so the host app's console
-* behaves normally. Never throws into the call site.
+* Whether a *persistent* identifier may be stored. Separate from `hasConsent`
+* because GPC/DNT suppress the cross-session id without suppressing capture.
 */
-function installConsoleCapture(emit) {
-	const original = {};
-	for (const level of LEVELS) {
-		const orig = console[level];
-		original[level] = orig;
-		console[level] = (...args) => {
-			safeEmit(emit, {
-				type: "console",
-				level,
-				message: formatArgs(args)
-			});
-			orig.apply(console, args);
-		};
-	}
-	return () => {
-		for (const level of LEVELS) {
-			const orig = original[level];
-			if (orig) console[level] = orig;
-		}
-	};
-}
-function formatArgs(args) {
-	const text = args.map((a) => {
-		if (typeof a === "string") return a;
-		if (a instanceof Error) return `${a.name}: ${a.message}`;
-		try {
-			return JSON.stringify(a);
-		} catch {
-			return String(a);
-		}
-	}).join(" ");
-	return text.length > MAX_MESSAGE ? `${text.slice(0, MAX_MESSAGE)}…` : text;
+function mayPersistIdentifier() {
+	if (!hasConsent()) return false;
+	if (typeof navigator === "undefined") return true;
+	const nav = navigator;
+	if (nav.globalPrivacyControl === true) return false;
+	if (consentState().respectDoNotTrack && nav.doNotTrack === "1") return false;
+	return true;
 }
 //#endregion
-//#region ../browser-session/src/replay/capture/network.ts
+//#region ../browser-session/src/identity/identity.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
-* ingest endpoints (otherwise capturing the session-events POST would loop).
+* Trait caps. The warehouse column is `Map(String, String)` — plain keys
+* precisely because they are arbitrary — so the cost of a unique key per user
+* is row size and query-time map width rather than a churned dictionary. The
+* cap bounds one row's damage; `warnOnIdLikeTraitKey` surfaces the pattern to
+* whoever wrote it, since an id in a trait key is nearly always a mistake.
 */
-function installNetworkCapture(emit, ignoreUrl) {
-	const origFetch = typeof window !== "undefined" ? window.fetch : void 0;
-	if (origFetch) window.fetch = async (input, init) => {
-		const url = requestUrl(input);
-		const method = requestMethod(input, init);
-		const traceId = activeTraceId();
-		const start = performance.now();
-		try {
-			const res = await origFetch(input, init);
-			record(url, method, res.status, start, traceId);
-			return res;
-		} catch (error) {
-			record(url, method, 0, start, traceId, String(error));
-			throw error;
+const MAX_TRAITS = 24;
+const MAX_TRAIT_KEY_LENGTH = 64;
+const MAX_TRAIT_VALUE_LENGTH = 256;
+let warnedAboutTraitKeys = false;
+/** Heuristic: a trait *key* that looks like an id is almost always a mistake. */
+function looksLikeId(key) {
+	return /^[0-9a-f]{8,}$/i.test(key) || /^(usr|user|org|cus|acct)_/i.test(key);
+}
+function coerceTraitValue(value) {
+	if (value === null || value === void 0) return void 0;
+	return (typeof value === "string" ? value : String(value)).slice(0, MAX_TRAIT_VALUE_LENGTH);
+}
+function normalizeTraits(traits) {
+	if (!traits) return {};
+	const out = {};
+	for (const [rawKey, rawValue] of Object.entries(traits)) {
+		if (Object.keys(out).length >= MAX_TRAITS) break;
+		const value = coerceTraitValue(rawValue);
+		if (value === void 0) continue;
+		const key = rawKey.slice(0, MAX_TRAIT_KEY_LENGTH);
+		if (!key) continue;
+		if (!warnedAboutTraitKeys && looksLikeId(key)) {
+			warnedAboutTraitKeys = true;
+			console.warn(`[maple] identity trait key "${key}" looks like an id. Trait keys share a ClickHouse dictionary — put ids in the value, or in id/groupId, not the key.`);
 		}
-	};
-	const record = (url, method, status, start, traceId, error) => {
-		if (ignoreUrl(url)) return;
-		safeEmit(emit, {
-			type: "network",
-			net: {
-				method,
-				url,
-				status,
-				durationMs: Math.round(performance.now() - start)
-			},
-			traceId,
-			...error ? { attrs: { error } } : {}
-		});
-	};
-	const XHR = typeof window !== "undefined" ? window.XMLHttpRequest : void 0;
-	const origOpen = XHR?.prototype.open;
-	const origSend = XHR?.prototype.send;
-	if (XHR && origOpen && origSend) {
-		XHR.prototype.open = function(method, url, ...rest) {
-			this.__mapleMethod = String(method).toUpperCase();
-			this.__mapleUrl = typeof url === "string" ? url : url.href;
-			return origOpen.apply(this, [
-				method,
-				url,
-				...rest
-			]);
-		};
-		XHR.prototype.send = function(...args) {
-			const meta = this;
-			const start = performance.now();
-			const traceId = activeTraceId();
-			this.addEventListener("loadend", () => {
-				record(meta.__mapleUrl ?? "", meta.__mapleMethod ?? "GET", this.status, start, traceId);
-			});
-			return origSend.apply(this, args);
-		};
+		out[key] = value;
 	}
-	return () => {
-		if (origFetch) window.fetch = origFetch;
-		if (XHR && origOpen) XHR.prototype.open = origOpen;
-		if (XHR && origSend) XHR.prototype.send = origSend;
-	};
-}
-function requestUrl(input) {
-	if (typeof input === "string") return input;
-	if (input instanceof URL) return input.href;
-	return input.url;
+	return out;
 }
-function requestMethod(input, init) {
-	return (init?.method ?? (typeof input === "object" && "method" in input ? input.method : void 0) ?? "GET").toUpperCase();
+function trimmed(value) {
+	const text = value?.trim();
+	return text ? text : void 0;
 }
-//#endregion
-//#region ../browser-session/src/replay/capture/errors.ts
-const MAX_STACK = 4e3;
-/** Capture uncaught errors + unhandled promise rejections as session events. */
-function installErrorCapture(emit) {
-	const onError = (event) => {
-		safeEmit(emit, {
-			type: "error",
-			level: "error",
-			message: event.message || String(event.error ?? "Error"),
-			errorStack: truncate(event.error?.stack),
-			traceId: activeTraceId()
-		});
-	};
-	const onRejection = (event) => {
-		const reason = event.reason;
-		safeEmit(emit, {
-			type: "error",
-			level: "error",
-			message: typeof reason === "string" ? reason : reason?.message ?? "Unhandled promise rejection",
-			errorStack: truncate(typeof reason === "object" ? reason?.stack : void 0),
-			traceId: activeTraceId()
-		});
-	};
-	window.addEventListener("error", onError);
-	window.addEventListener("unhandledrejection", onRejection);
-	return () => {
-		window.removeEventListener("error", onError);
-		window.removeEventListener("unhandledrejection", onRejection);
-	};
-}
-function truncate(stack) {
-	if (!stack) return void 0;
-	return stack.length > MAX_STACK ? `${stack.slice(0, MAX_STACK)}…` : stack;
-}
-//#endregion
-//#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).
+* Normalize whatever a host app passed into the shape the metadata row wants.
+*
+* Each call *replaces* the identity rather than merging into the previous one.
+* Merging would leak a signed-out user's email into the next person to use a
+* shared device, and replacement is what the existing string-only `identify`
+* already did.
 */
-function installNavigationCapture(emit) {
-	let lastUrl = "";
-	const emitNav = () => {
-		const url = location.href;
-		if (url === lastUrl) return;
-		lastUrl = url;
-		safeEmit(emit, {
-			type: "navigation",
-			url
-		});
-	};
-	emitNav();
-	const origPush = history.pushState;
-	const origReplace = history.replaceState;
-	history.pushState = function(...args) {
-		const result = origPush.apply(this, args);
-		emitNav();
-		return result;
-	};
-	history.replaceState = function(...args) {
-		const result = origReplace.apply(this, args);
-		emitNav();
-		return result;
-	};
-	window.addEventListener("popstate", emitNav);
-	window.addEventListener("hashchange", emitNav);
-	return () => {
-		history.pushState = origPush;
-		history.replaceState = origReplace;
-		window.removeEventListener("popstate", emitNav);
-		window.removeEventListener("hashchange", emitNav);
+function normalizeIdentity(input) {
+	if (input === null || input === void 0) return void 0;
+	if (typeof input === "string") {
+		const id = trimmed(input);
+		return id ? {
+			id,
+			traits: {}
+		} : void 0;
+	}
+	const resolved = {
+		id: trimmed(input.id),
+		email: trimmed(input.email),
+		username: trimmed(input.username),
+		groupId: trimmed(input.groupId),
+		groupName: trimmed(input.groupName),
+		traits: normalizeTraits(input.traits)
 	};
+	return resolved.id || resolved.email || resolved.username || resolved.groupId || resolved.groupName || Object.keys(resolved.traits).length > 0 ? resolved : void 0;
 }
 //#endregion
-//#region ../browser-session/src/replay/capture/interactions.ts
-const MAX_TEXT = 120;
+//#region ../browser-session/src/session/metadata-session.ts
 /**
-* Capture clicks and input events as session events. Listens in the capture
-* phase so it sees interactions even when the host app calls
-* `stopPropagation()`. Input *values* are never recorded; only the target
-* element. Click target text is omitted when `maskAllText` is set.
+* Metadata-only session lifecycle used whenever rrweb is disabled or unsampled.
+* It is the shared lifecycle driver with no capture of its own: the distilled
+* event sink runs on every page load regardless, so this owner only has to post
+* rows and flush that sink on the way out.
 */
-function installInteractionCapture(emit, maskAllText) {
-	const onClick = (event) => {
-		const target = event.target;
-		if (!(target instanceof Element)) return;
-		safeEmit(emit, {
-			type: "click",
-			targetSelector: selectorOf(target),
-			targetText: maskAllText ? void 0 : textOf(target)
-		});
-	};
-	const onInput = (event) => {
-		const target = event.target;
-		if (!(target instanceof Element)) return;
-		safeEmit(emit, {
-			type: "input",
-			targetSelector: selectorOf(target)
-		});
-	};
-	document.addEventListener("click", onClick, true);
-	document.addEventListener("input", onInput, true);
-	return () => {
-		document.removeEventListener("click", onClick, true);
-		document.removeEventListener("input", onInput, true);
-	};
-}
-/** A short, human-readable selector: tag + #id + .first-class. */
-function selectorOf(el) {
-	return `${el.tagName.toLowerCase()}${el.id ? `#${el.id}` : ""}${typeof el.className === "string" && el.className.trim() ? `.${el.className.trim().split(/\s+/)[0]}` : ""}`;
-}
-function textOf(el) {
-	const text = (el.textContent ?? "").trim().replace(/\s+/g, " ");
-	if (!text) return void 0;
-	return text.length > MAX_TEXT ? `${text.slice(0, MAX_TEXT)}…` : text;
+function startMetadataSession(options) {
+	return startSessionLifecycle(options, {
+		recorded: false,
+		post: (row, keepalive) => {
+			postSessionMetaRow(options, row, keepalive);
+		},
+		onSuspend: ({ flush, keepalive }) => {
+			if (flush && keepalive) getActiveSink()?.flush(true);
+		},
+		onSessionChange: options.onSessionChange
+	});
 }
 //#endregion
-//#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) {
+//#region ../browser-session/src/events/track.ts
+/**
+* Caps mirroring what the ingest gateway enforces. Applying them here too means
+* an over-sized event is trimmed before it costs bandwidth, and the developer
+* sees the same shape locally that the warehouse will store.
+*/
+const MAX_NAME_LENGTH = 128;
+const MAX_PROPS = 32;
+const MAX_PROP_KEY_LENGTH = 64;
+const MAX_PROP_VALUE_LENGTH = 1024;
+const MAX_TOTAL_PROP_BYTES = 8192;
+let warnedAboutName = false;
+/**
+* Coerce one property value to the string the warehouse column holds.
+*
+* `null`/`undefined`/functions/symbols are dropped rather than stringified —
+* `"undefined"` as a stored value is worse than an absent key.
+*/
+function coerce(value) {
+	if (value === null || value === void 0) return void 0;
+	switch (typeof value) {
+		case "string": return value.slice(0, MAX_PROP_VALUE_LENGTH);
+		case "number":
+		case "boolean":
+		case "bigint": return String(value);
+		case "function":
+		case "symbol": return;
+	}
 	try {
-		return JSON.stringify(value).length;
+		if (value instanceof Date) return value.toISOString();
+		return JSON.stringify(value)?.slice(0, MAX_PROP_VALUE_LENGTH);
 	} catch {
-		return 256;
+		return;
 	}
 }
-//#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";
-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 = traceIdProvider();
-	return id && id !== ZERO_TRACE_ID ? id : void 0;
-}
-/**
-* Capture distilled session events (console, network, errors, navigation,
-* interactions) and ship them to the ingest gateway as NDJSON rows. Best-effort
-* and decoupled from the rrweb recorder — runs on its own flush loop.
-*/
-function startEventCapture(config, sessionId) {
-	let buffer = [];
-	let bufferBytes = 0;
-	let seq = 0;
-	const emit = (ev) => {
-		buffer.push({
-			ev,
-			seq: seq++
-		});
-		bufferBytes += approximateSize(ev);
-		if (bufferBytes >= FLUSH_BYTES$1) flush();
-	};
-	const flush = async (keepalive = false) => {
-		if (buffer.length === 0) return;
-		markActivity();
-		const batch = buffer;
-		buffer = [];
-		bufferBytes = 0;
-		await postSessionEvents(config, batch.map(({ ev, seq }) => toRow(sessionId, ev, seq)), keepalive);
-	};
-	const ignoreUrl = (url) => url.startsWith(`${config.endpoint}/v1/`);
-	const uninstall = [
-		installNavigationCapture(emit),
-		installInteractionCapture(emit, config.maskAllText),
-		installConsoleCapture(emit),
-		installNetworkCapture(emit, ignoreUrl),
-		installErrorCapture(emit)
-	];
-	const flushTimer = setInterval(() => void flush(), FLUSH_INTERVAL_MS$1);
-	return {
-		stop: () => {
-			clearInterval(flushTimer);
-			for (const off of uninstall) off();
-		},
-		flush
-	};
-}
-/** Map an internal event to the snake_case ingest row (org_id is added server-side). */
-function toRow(sessionId, ev, seq) {
-	return {
-		session_id: sessionId,
-		timestamp: formatCHDateTime(new Date(ev.timestamp ?? Date.now())),
-		seq,
-		type: ev.type,
-		url: ev.url ?? (typeof location !== "undefined" ? location.href : ""),
-		trace_id: ev.traceId ?? activeTraceId() ?? "",
-		level: ev.level ?? "",
-		message: ev.message ?? "",
-		target_selector: ev.targetSelector ?? "",
-		target_text: ev.targetText ?? "",
-		net_method: ev.net?.method ?? "",
-		net_url: ev.net?.url ?? "",
-		net_status: ev.net?.status ?? 0,
-		net_duration_ms: ev.net?.durationMs ?? 0,
-		error_stack: ev.errorStack ?? "",
-		attributes: ev.attrs ?? {}
-	};
-}
-//#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
-	};
+function coerceProps(props) {
+	if (!props) return {};
+	const out = {};
+	let bytes = 0;
+	for (const [rawKey, rawValue] of Object.entries(props)) {
+		if (Object.keys(out).length >= MAX_PROPS) break;
+		const value = coerce(rawValue);
+		if (value === void 0) continue;
+		const key = rawKey.slice(0, MAX_PROP_KEY_LENGTH);
+		if (!key) continue;
+		bytes += key.length + value.length;
+		if (bytes > MAX_TOTAL_PROP_BYTES) break;
+		out[key] = value;
+	}
+	return out;
 }
-//#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.
+* Record a custom product event against the current session.
 *
-* Returns undefined outside a browser. Sampling is the caller's decision.
+* Stored as a `session_events` row with `Type='custom'`, so it shows up inline
+* in the session transcript alongside the clicks and network calls that
+* surround it — not in a separate analytics silo.
+*
+* Safe to call before the SDK finishes initializing: events are queued (capped)
+* and drained once the sink starts. Never throws.
 */
-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;
+function track(name, props) {
+	if (!hasConsent()) return;
+	if (typeof name !== "string" || name.trim().length === 0) {
+		if (!warnedAboutName) {
+			warnedAboutName = true;
+			console.warn("[maple] track() needs a non-empty event name; the call was ignored.");
 		}
+		return;
+	}
+	const ev = {
+		type: "custom",
+		message: name.trim().slice(0, MAX_NAME_LENGTH),
+		attrs: coerceProps(props),
+		timestamp: Date.now(),
+		url: typeof location !== "undefined" ? location.href : void 0
 	};
+	const sink = getActiveSink();
+	if (sink) sink.emit(ev);
+	else queuePending(ev);
 }
 //#endregion
 //#region src/config.ts
 const DEFAULT_ENDPOINT = "https://ingest.maple.dev";
-function normalizeUserId(userId) {
-	return userId ? userId : void 0;
+/**
+* Resolve the identity from either the new `user` object or the legacy
+* `userId` string. `user` wins when both are set.
+*/
+function resolveIdentity(config) {
+	return normalizeIdentity(config.user ?? config.userId);
 }
 function resolveConfig(config) {
 	return {
@@ -741,27 +308,42 @@ function resolveConfig(config) {
 		serviceNamespace: config.serviceNamespace,
 		serviceVersion: config.serviceVersion,
 		environment: config.environment,
-		userId: normalizeUserId(config.userId),
+		identity: resolveIdentity(config),
 		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
+		maskAllText: config.privacy?.maskAllText ?? false,
+		persistVisitorId: config.privacy?.persistVisitorId ?? true,
+		crossSubdomainCookie: config.privacy?.crossSubdomainCookie ?? true,
+		cookieDomain: config.privacy?.cookieDomain,
+		requireConsent: config.privacy?.requireConsent ?? false,
+		captureUserEmail: config.privacy?.captureUserEmail ?? true,
+		respectDoNotTrack: config.privacy?.respectDoNotTrack ?? false
 	};
 }
 //#endregion
+//#region src/version.ts
+const SDK_VERSION = "0.8.0";
+/** The `x-maple-sdk` value this build sends. */
+const SDK_NAME = "maple-browser";
+//#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 {
+	getUserId;
 	constructor(getUserId = () => void 0) {
 		this.getUserId = getUserId;
 	}
 	onStart(span) {
+		if (!hasConsent()) return;
 		recordTraceId(span.spanContext().traceId);
+		const sessionId = readSessionSink()?.sessionId;
+		if (sessionId !== void 0) span.setAttribute("session.id", sessionId);
 		const userId = this.getUserId();
 		if (userId !== void 0) span.setAttribute("user.id", userId);
 	}
@@ -774,18 +356,62 @@ var TraceIdCollector = class {
 	}
 };
 /**
-* 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.
+* Drops buffered spans captured while consent was absent. Checking start time,
+* rather than only permission at flush time, also prevents a late grant from
+* releasing spans that began before that grant.
 */
-function setupTracing(config, sessionId) {
+var ConsentSpanExporter = class {
+	inner;
+	constructor(inner) {
+		this.inner = inner;
+	}
+	export(spans, callback) {
+		const since = consentAllowedSince();
+		if (!hasConsent() || !Number.isFinite(since)) {
+			callback({ code: 0 });
+			return;
+		}
+		const eligible = spans.filter((span) => span.startTime[0] * 1e3 + span.startTime[1] / 1e6 >= since);
+		if (eligible.length === 0) {
+			callback({ code: 0 });
+			return;
+		}
+		this.inner.export(eligible, callback);
+	}
+	forceFlush() {
+		return this.inner.forceFlush?.() ?? Promise.resolve();
+	}
+	shutdown() {
+		return this.inner.shutdown();
+	}
+};
+/**
+* How long a span may sit in the batch queue before export.
+*
+* Shorter than OTel's 5s default: in a browser the queue is only as durable as
+* the tab, and the unload flush below is a best-effort catch rather than a
+* guarantee (a crashed or killed tab fires neither event). 2s trades a few more
+* requests for a materially smaller loss window.
+*/
+const EXPORT_INTERVAL_MS = 2e3;
+/**
+* Set up browser OTel tracing exporting to Maple's ingest. 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.
+*
+* `session.id` is deliberately **not** a resource attribute: the resource is
+* fixed for the provider's lifetime, but sessions rotate under it (idle
+* rotation, consent revoke→re-grant), so a resource-level id would attribute
+* every post-rotation span to the ended session. `TraceIdCollector` stamps the
+* live id per span instead.
+*/
+function setupTracing(config) {
 	const attributes = {
 		[ATTR_SERVICE_NAME]: config.serviceName,
-		"maple.sdk.type": "browser",
-		"session.id": sessionId
+		"maple.sdk.type": "browser"
 	};
 	if (config.serviceNamespace) attributes["service.namespace"] = config.serviceNamespace;
 	if (config.serviceVersion) {
@@ -796,33 +422,52 @@ function setupTracing(config, sessionId) {
 		attributes["deployment.environment"] = config.environment;
 		attributes["deployment.environment.name"] = config.environment;
 	}
-	const exporter = new OTLPTraceExporter({
+	const exporter = new ConsentSpanExporter(new OTLPTraceExporter({
 		url: `${config.endpoint}/v1/traces`,
-		headers: { Authorization: `Bearer ${config.ingestKey}` }
-	});
+		headers: {
+			Authorization: `Bearer ${config.ingestKey}`,
+			[SDK_HINT_HEADER]: sdkHint(SDK_NAME, SDK_VERSION)
+		}
+	}));
 	const provider = new WebTracerProvider({
 		resource: resourceFromAttributes(attributes),
-		spanProcessors: [new TraceIdCollector(() => config.userId), new BatchSpanProcessor(exporter)]
+		spanProcessors: [new TraceIdCollector(() => config.identity?.id), new BatchSpanProcessor(exporter, { scheduledDelayMillis: EXPORT_INTERVAL_MS })]
 	});
 	provider.register();
-	if (config.tracingInstrumentFetch) registerInstrumentations({ instrumentations: [new FetchInstrumentation({ ignoreUrls: [new RegExp(`${escapeRegExp(config.endpoint)}/v1/`)] })] });
-	return () => provider.shutdown();
+	const onExit = () => {
+		provider.forceFlush().catch(() => {});
+	};
+	const onVisibilityChange = () => {
+		if (document.visibilityState === "hidden") onExit();
+	};
+	const canListen = typeof document !== "undefined" && typeof document.addEventListener === "function";
+	if (canListen) {
+		document.addEventListener("visibilitychange", onVisibilityChange);
+		window.addEventListener("pagehide", onExit);
+	}
+	const unregisterInstrumentations = config.tracingInstrumentFetch ? registerInstrumentations({ instrumentations: [new FetchInstrumentation({ ignoreUrls: [new RegExp(`${escapeRegExp(config.endpoint)}/v1/`)] })] }) : void 0;
+	return async () => {
+		if (canListen) {
+			document.removeEventListener("visibilitychange", onVisibilityChange);
+			window.removeEventListener("pagehide", onExit);
+		}
+		unregisterInstrumentations?.();
+		await provider.shutdown();
+	};
 }
 function escapeRegExp(value) {
 	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 //#endregion
 //#region src/init.ts
+/** `x-maple-sdk` value for every request this build makes to ingest. */
+const SDK_HINT = sdkHint(SDK_NAME, SDK_VERSION);
 let active;
 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.
+* Initialize Maple browser telemetry. With consent gating enabled the returned
+* handle remains live while denied: granting starts capture, revoking detaches
+* it without flushing, and a later grant starts cleanly again.
 */
 function init(rawConfig) {
 	if (active) return active;
@@ -832,28 +477,114 @@ function init(rawConfig) {
 	};
 	const config = resolveConfig(rawConfig);
 	activeConfig = config;
-	const session = getSession();
-	publishSessionSink(session.id);
+	configurePrivacy(config);
+	if (!hasConsent()) clearPendingEvents();
 	setActiveTraceIdProvider(() => trace.getActiveSpan()?.spanContext().traceId);
-	const shutdownTracing = config.tracingEnabled ? setupTracing(config, session.id) : void 0;
 	const recordReplay = config.replayEnabled && Math.random() < config.replaySampleRate;
-	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
-	});
+	let runtime;
+	let stopped = false;
+	let rotateOnNextStart = false;
+	let shutdownTracing;
+	let generation = 0;
+	const startRuntime = () => {
+		if (stopped || runtime || !hasConsent()) return;
+		setVisitorTracking(config.persistVisitorId && mayPersistIdentifier());
+		const session = (rotateOnNextStart ? rotateSession() : void 0) ?? getSession();
+		rotateOnNextStart = false;
+		publishSessionSink(session.id);
+		const sink = startEventSink({
+			endpoint: config.endpoint,
+			ingestKey: config.ingestKey,
+			sdk: SDK_HINT,
+			maskAllInputs: config.maskAllInputs,
+			maskAllText: config.maskAllText
+		}, session.id);
+		if (config.tracingEnabled && !shutdownTracing) shutdownTracing = setupTracing(config);
+		const shared = {
+			endpoint: config.endpoint,
+			ingestKey: config.ingestKey,
+			sdk: SDK_HINT,
+			serviceName: config.serviceName,
+			environment: config.environment,
+			serviceVersion: config.serviceVersion,
+			getIdentity: () => activeConfig?.identity,
+			captureUserEmail: config.captureUserEmail
+		};
+		const startMetadata = () => startMetadataSession({
+			...shared,
+			getTraceIds: getObservedTraceIds,
+			onSessionChange: publishSessionSink
+		});
+		if (!recordReplay) {
+			runtime = {
+				initialSessionId: session.id,
+				sink,
+				metadata: startMetadata()
+			};
+			return;
+		}
+		const next = {
+			initialSessionId: session.id,
+			sink
+		};
+		runtime = next;
+		const ownGeneration = ++generation;
+		const stale = () => stopped || !hasConsent() || generation !== ownGeneration || runtime !== next;
+		next.replayPending = import("./replay-session-BYZfi3iZ.mjs").then(({ startReplaySession }) => {
+			if (stale()) return;
+			next.replay = startReplaySession({
+				...shared,
+				maskAllInputs: config.maskAllInputs,
+				maskAllText: config.maskAllText
+			});
+		}).catch(() => {
+			if (stale()) return;
+			next.metadata = startMetadata();
+		});
+	};
+	const stopRuntime = async (flush) => {
+		generation++;
+		const previous = runtime;
+		runtime = void 0;
+		if (!previous) return;
+		const replayShutdown = previous.replay?.shutdown({ flush });
+		const metadataShutdown = previous.metadata?.shutdown({ flush });
+		const currentSessionId = previous.replay?.sessionId ?? previous.metadata?.sessionId;
+		const liveSink = getActiveSink();
+		const sink = liveSink && currentSessionId && liveSink.sessionId === currentSessionId ? liveSink : previous.sink;
+		if (flush) await sink.flush(true);
+		sink.stop();
+		if (sink !== previous.sink) previous.sink.stop();
+		clearSessionSink(currentSessionId ?? previous.initialSessionId);
+		await Promise.all([
+			replayShutdown,
+			metadataShutdown,
+			previous.replayPending
+		]);
+	};
+	startRuntime();
+	const stopConsentListener = config.requireConsent ? onConsentChange((allowed) => {
+		if (allowed) {
+			startRuntime();
+			return;
+		}
+		rotateOnNextStart = runtime !== void 0;
+		clearPendingEvents();
+		setVisitorTracking(false);
+		stopRuntime(false);
+	}) : () => {};
 	const handle = {
-		sessionId: session.id,
+		get sessionId() {
+			return runtime?.replay?.sessionId ?? runtime?.metadata?.sessionId ?? runtime?.initialSessionId ?? "";
+		},
 		shutdown: async () => {
-			await replay?.shutdown();
-			replay = void 0;
+			if (stopped) return;
+			stopped = true;
+			stopConsentListener();
+			await stopRuntime(true);
 			await shutdownTracing?.();
+			shutdownTracing = void 0;
+			setActiveTraceIdProvider(() => void 0);
 			active = void 0;
 			activeConfig = void 0;
 		}
@@ -862,14 +593,24 @@ function init(rawConfig) {
 	return handle;
 }
 /**
-* 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.
+* Attach, replace, or clear the end-user identity on the active session.
+* Idempotent and safe to call on every render. Future browser-created spans
+* read the id when they start, and future session metadata rows read the whole
+* identity when they post.
+*
+* Accepts a bare user id or the full object:
+*
+* ```ts
+* MapleBrowser.identify("user_123")
+* MapleBrowser.identify({ id: "user_123", email: "a@b.com", groupId: "org_1", groupName: "Acme" })
+* ```
+*
+* Each call replaces the identity rather than merging — merging would leak a
+* signed-out user's email into whoever signs in next on a shared device.
 */
-function identify(userId) {
-	if (typeof window === "undefined") return;
-	if (!activeConfig) return;
-	activeConfig.userId = normalizeUserId(userId);
+function identify(input) {
+	if (typeof window === "undefined" || !activeConfig) return;
+	activeConfig.identity = normalizeIdentity(input);
 }
 //#endregion
 //#region src/index.ts
@@ -885,11 +626,16 @@ function identify(userId) {
 *   ingestKey: "maple_pk_...",
 *   serviceName: "acme-web",
 * })
+*
+* MapleBrowser.identify({ id: user.id, email: user.email, groupId: org.id, groupName: org.name })
+* MapleBrowser.track("checkout_completed", { plan: "pro", seats: 5 })
 * ```
 */
 const MapleBrowser = {
 	init,
-	identify
+	identify,
+	track,
+	setConsent
 };
 //#endregion
 export { MapleBrowser };