@maple-dev/browser 0.1.0

package/README.md

@@ -0,0 +1,49 @@
+# @maple-dev/browser
+
+Browser SDK for [Maple](https://maple.dev) — OpenTelemetry tracing **and** rrweb
+session replay in a single package. Every span and every replay event is tagged
+with the same `session.id`, so a trace can link straight to the replay that
+produced it (and vice versa) with no clock-skew guessing.
+
+## Install
+
+```bash
+npm install @maple-dev/browser
+```
+
+## Usage
+
+```ts
+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 },
+})
+```
+
+That single call:
+
+- starts OTel browser tracing, auto-instrumenting `fetch`, 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`;
+- writes session metadata at start (`active`) and on page hide (`ended`),
+  including the trace ids observed during the session.
+
+## Privacy
+
+`maskAllInputs` (default **on**) masks every `<input>` value. Use rrweb's
+attribute hooks (`data-rr-block`, `.rr-block`, `.rr-ignore`) to block elements
+or subtrees from capture.
+
+## Notes
+
+- Replay event blobs live in object storage; only small, queryable metadata is
+  indexed — playback streams blobs directly via signed URLs.
+- The SDK is best-effort: network failures in telemetry never throw into your
+  app.

package/dist/index.d.mts

@@ -0,0 +1,67 @@
+//#region src/config.d.ts
+/** Public configuration for `MapleBrowser.init`. */
+interface MapleBrowserConfig {
+  /** Public ingest key (`maple_pk_...`). */
+  readonly ingestKey: string;
+  /** Service name reported on traces and stored on replay sessions. */
+  readonly serviceName: string;
+  /** Maple ingest base URL. Defaults to `https://ingest.maple.dev`. */
+  readonly endpoint?: 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;
+  readonly tracing?: {
+    /** Default true. */readonly enabled?: boolean;
+    /**
+     * Auto-instrument `fetch()` to create network spans. Default true. Set
+     * false when another tracer (e.g. the Effect client SDK) already
+     * instruments requests — those spans feed the session via the published
+     * sink, and disabling this avoids redundant duplicate network spans.
+     */
+    readonly instrumentFetch?: boolean;
+  };
+  readonly replay?: {
+    /** Default true. */readonly enabled?: boolean; /** Fraction of sessions to record, 0–1. Default 1. */
+    readonly sampleRate?: number;
+  };
+  readonly privacy?: {
+    /** Mask all `<input>` values. Default true. */readonly maskAllInputs?: boolean;
+    /**
+     * Mask all text in the rrweb recording and omit captured click target
+     * text from session events. Default false.
+     */
+    readonly maskAllText?: boolean;
+  };
+}
+//#endregion
+//#region src/init.d.ts
+interface MapleBrowserHandle {
+  readonly sessionId: string;
+  /** Tear down tracing + replay (flushing the final chunk). */
+  readonly shutdown: () => Promise<void>;
+}
+//#endregion
+//#region src/index.d.ts
+/**
+ * Maple browser SDK. One call wires up OpenTelemetry tracing and rrweb session
+ * replay, both tagged with a shared session id.
+ *
+ * @example
+ * ```ts
+ * import { MapleBrowser } from "@maple-dev/browser"
+ *
+ * MapleBrowser.init({
+ *   ingestKey: "maple_pk_...",
+ *   serviceName: "acme-web",
+ * })
+ * ```
+ */
+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;
+};
+//#endregion
+export { MapleBrowser, type MapleBrowserConfig, type MapleBrowserHandle };

package/dist/index.mjs

@@ -0,0 +1,778 @@
+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 { 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
+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
+	};
+}
+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;
+}
+/**
+* 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.
+*/
+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.
+*/
+function nextChunkSeq() {
+	const record = readRecord() ?? freshRecord(Date.now());
+	const seq = record.chunkSeq;
+	writeRecord({
+		...record,
+		chunkSeq: seq + 1
+	});
+	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"
+	};
+}
+//#endregion
+//#region src/session-sink.ts
+const observedTraceIds = /* @__PURE__ */ new Set();
+/** Record a trace id seen during the session. Idempotent per id. */
+function recordTraceId(traceId) {
+	observedTraceIds.add(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.
+*/
+function publishSessionSink(sessionId) {
+	globalThis[SESSION_SINK_KEY] = {
+		sessionId,
+		recordTraceId
+	};
+}
+//#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();
+	}
+};
+/**
+* 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.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(), 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/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);
+	});
+}
+/** 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 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
+/** Emit best-effort: capture must never throw into the host app's call site. */
+function safeEmit(emit, ev) {
+	try {
+		emit(ev);
+	} catch {}
+}
+//#endregion
+//#region 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.
+*/
+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;
+}
+//#endregion
+//#region 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
+* ingest endpoints (otherwise capturing the session-events POST would loop).
+*/
+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 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);
+		};
+	}
+	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;
+}
+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
+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 src/replay/capture/navigation.ts
+/**
+* Capture page views as session events: the initial load plus every SPA
+* navigation (history pushState/replaceState, popstate, hashchange).
+*/
+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);
+	};
+}
+//#endregion
+//#region src/replay/capture/interactions.ts
+const MAX_TEXT = 120;
+/**
+* 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.
+*/
+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;
+}
+//#endregion
+//#region src/replay/events.ts
+const FLUSH_INTERVAL_MS = 5e3;
+const FLUSH_BYTES = 64 * 1024;
+const ZERO_TRACE_ID = "00000000000000000000000000000000";
+/** The OTel trace id of the active span, or undefined when none is active. */
+function activeTraceId() {
+	const id = trace.getActiveSpan()?.spanContext().traceId;
+	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) 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);
+	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 src/init.ts
+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.
+*/
+function init(rawConfig) {
+	if (active) return active;
+	if (typeof window === "undefined") return {
+		sessionId: "",
+		shutdown: () => Promise.resolve()
+	};
+	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;
+	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);
+	}
+	const handle = {
+		sessionId,
+		shutdown: async () => {
+			if (recorder) await recorder.flush(true);
+			if (events) await events.flush(true);
+			recorder?.stop();
+			events?.stop();
+			await shutdownTracing?.();
+			active = void 0;
+			activeConfig = void 0;
+		}
+	};
+	active = handle;
+	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)`).
+*/
+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;
+}
+//#endregion
+//#region src/index.ts
+/**
+* Maple browser SDK. One call wires up OpenTelemetry tracing and rrweb session
+* replay, both tagged with a shared session id.
+*
+* @example
+* ```ts
+* import { MapleBrowser } from "@maple-dev/browser"
+*
+* MapleBrowser.init({
+*   ingestKey: "maple_pk_...",
+*   serviceName: "acme-web",
+* })
+* ```
+*/
+const MapleBrowser = {
+	init,
+	identify
+};
+//#endregion
+export { MapleBrowser };

package/package.json

@@ -0,0 +1,46 @@
+{
+	"name": "@maple-dev/browser",
+	"version": "0.1.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.",
+	"license": "MIT",
+	"type": "module",
+	"files": [
+		"dist",
+		"README.md"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/index.d.mts",
+			"import": "./dist/index.mjs"
+		}
+	},
+	"scripts": {
+		"build": "tsdown",
+		"typecheck": "tsc --noEmit",
+		"test": "vitest run"
+	},
+	"dependencies": {
+		"@opentelemetry/api": "^1.9.0",
+		"@opentelemetry/exporter-trace-otlp-http": "^0.205.0",
+		"@opentelemetry/instrumentation": "^0.205.0",
+		"@opentelemetry/instrumentation-fetch": "^0.205.0",
+		"@opentelemetry/resources": "^2.0.0",
+		"@opentelemetry/sdk-trace-base": "^2.0.0",
+		"@opentelemetry/sdk-trace-web": "^2.0.0",
+		"@opentelemetry/semantic-conventions": "^1.36.0",
+		"rrweb": "^2.0.0-alpha.18"
+	},
+	"devDependencies": {
+		"tsdown": "^0.21.7",
+		"typescript": "^6.0.2",
+		"vitest": "^4.1.2"
+	},
+	"keywords": [
+		"maple",
+		"opentelemetry",
+		"session-replay",
+		"rrweb",
+		"observability",
+		"rum"
+	]
+}