@interfere/react 9.0.1 → 10.0.0

package/dist/internal/otel/exporter.mjs

@@ -0,0 +1,212 @@
+import { PRODUCER_VERSION } from "../version.mjs";
+import { diag } from "@opentelemetry/api";
+import { ExportResultCode } from "@opentelemetry/core";
+import { JsonLogsSerializer } from "@opentelemetry/otlp-transformer/build/esm/logs/json/logs.js";
+import { JsonMetricsSerializer } from "@opentelemetry/otlp-transformer/build/esm/metrics/json/metrics.js";
+import { JsonTraceSerializer } from "@opentelemetry/otlp-transformer/build/esm/trace/json/trace.js";
+import { AggregationTemporality } from "@opentelemetry/sdk-metrics";
+//#region src/internal/otel/exporter.ts
+/**
+* Opaque collector ingest path. Single endpoint for every OTLP signal —
+* server-side dispatches by which `resource*` block the request carries.
+*
+* Semantically nondescript so common adblock filter lists (EasyPrivacy,
+* uBlock) don't fingerprint it the way they do `traces` / `metrics` /
+* `logs` / `telemetry`. Customer-domain proxy mode is still the
+* recommended path for browser SDKs; this is the second line of defence
+* for direct-ingestion (`pub-token`) clients.
+*/
+const COLLECTOR_SINK_PATH = "/v2/sink";
+/**
+* Identity gate values the collector accepts via URL query when their
+* matching headers can't be set.
+*
+* `navigator.sendBeacon` (the only browser transport that survives
+* `visibilitychange→hidden`) only attaches `Content-Type` via the
+* `Blob` — no other request headers. We rely on that exclusively for
+* the browser SDK's primary path, so the identity gates the collector
+* enforces (`x-interfere-producer-version`, `x-interfere-pub-token`)
+* have to ride the URL instead. Mirrors `PRODUCER_VERSION_QUERY` /
+* `PUB_TOKEN_QUERY` on
+* `services/collector/src/{modules/v2/middleware,auth/surface}.ts`.
+*
+* Pub-token query exposure note: pub-tokens are public by design (they
+* ship in browser bundles, visible in DevTools), so URL exposure is no
+* worse than the existing header path. API keys deliberately have **no**
+* query fallback — see `surfaceAuth` for the matching server-side
+* rationale.
+*/
+const PRODUCER_VERSION_QUERY = "_pv";
+const PUB_TOKEN_QUERY = "_pt";
+const PUB_TOKEN_HEADER = "x-interfere-pub-token";
+const JSON_CONTENT_TYPE = "application/json";
+/** Exported for direct unit testing. */
+function buildSinkUrl(collectorUrl) {
+	return `${collectorUrl.endsWith("/") ? collectorUrl.slice(0, -1) : collectorUrl}${COLLECTOR_SINK_PATH}`;
+}
+/**
+* Beacon-flavoured sink URL — encodes the producer-version (always)
+* and pub-token (when present in `authHeaders`) as query parameters
+* so `navigator.sendBeacon` can authenticate without setting custom
+* request headers.
+*
+* Exported for direct unit testing.
+*/
+function buildBeaconUrl(input) {
+	const params = new URLSearchParams({ [PRODUCER_VERSION_QUERY]: PRODUCER_VERSION });
+	const pubToken = input.authHeaders.get(PUB_TOKEN_HEADER);
+	if (pubToken) params.set(PUB_TOKEN_QUERY, pubToken);
+	return `${buildSinkUrl(input.collectorUrl)}?${params.toString()}`;
+}
+/**
+* Returns true iff the runtime can dispatch a `navigator.sendBeacon`
+* call. Browser-only; server contexts (SSR, prerender, Vitest's `node`
+* environment) trip the typeof guards.
+*/
+function canSendBeacon() {
+	return typeof navigator !== "undefined" && typeof navigator.sendBeacon === "function";
+}
+/**
+* Dispatches an OTLP payload via `navigator.sendBeacon` and always
+* reports `SUCCESS` to the BSP. `sendBeacon` is fire-and-forget by
+* spec — a `true` return only means "the user agent accepted the
+* payload into its delivery queue", not "the server received it".
+*
+* Why never report `FAILED`:
+*   - `BatchSpanProcessor._flushOneBatch` rejects its promise on
+*     `code !== SUCCESS`, and that rejection propagates up through
+*     `forceFlush()` / `shutdown()`. In production, that surfaces
+*     during Vercel function teardown (and other awaited unload
+*     paths) as an unhandled rejection. In tests, it surfaces as
+*     `provider.test.tsx > passes through useSession` — vitest's
+*     `afterEach(close)` awaits `kernel.dispose() → BSP.shutdown
+*     → _flushAll`, the rejection bubbles, and the test fails.
+*   - `sendBeacon`'s `false` return signals a *local* drop (per-call
+*     ~64KiB ceiling, per-page queue full, disallowed scheme). No
+*     network request was attempted, so the service-worker backstop
+*     in `internal/sw.ts` can't intercept it either. Retrying inside
+*     the exporter would just hit the same browser limit again.
+*
+* The data is gone, but the export *completed* in the only sense
+* that matters to the BSP. A `diag.debug` keeps visibility for any
+* OTel diag listener wired into the kernel.
+*/
+function reportBeacon(url, payload, signal, resultCallback) {
+	if (!payload || payload.byteLength === 0) {
+		diag.debug(`[interfere/beacon] ${signal} serializer returned no bytes`);
+		resultCallback({ code: ExportResultCode.SUCCESS });
+		return;
+	}
+	if (!canSendBeacon()) {
+		diag.debug(`[interfere/beacon] navigator.sendBeacon unavailable; dropping ${signal} batch (${payload.byteLength}B)`);
+		resultCallback({ code: ExportResultCode.SUCCESS });
+		return;
+	}
+	const blob = new Blob([payload], { type: JSON_CONTENT_TYPE });
+	if (!navigator.sendBeacon(url, blob)) diag.debug(`[interfere/beacon] navigator.sendBeacon refused ${signal} payload (oversized or queue full); dropping ${payload.byteLength}B`);
+	resultCallback({ code: ExportResultCode.SUCCESS });
+}
+/**
+* Browser-side OTLP trace exporter.
+*
+* Dispatches every export via `navigator.sendBeacon` — which is the
+* only browser transport that reliably commits a request the page is
+* also tearing down (`visibilitychange→hidden`, hard navigation). The
+* `keepalive: true` fetch path the OTLP HTTP exporter ships with
+* works for small payloads but falls back to ordinary fetch (which
+* the renderer aborts on unload) once the cumulative 64KiB / 9-
+* concurrent budget is exhausted. Production data on 2026-05-11
+* attributed ~15% browser-fetch span loss to that fallback; the
+* beacon path closes that hole by design.
+*
+* Identity (`x-interfere-producer-version`, `x-interfere-pub-token`)
+* rides the URL because beacons can't carry custom headers. The
+* collector accepts both query and header paths — see
+* `services/collector/src/{modules/v2/middleware,auth/surface}.ts`.
+*
+* No retry on failure. The service worker backstop captures 5xx /
+* network failures separately by intercepting the same beacon POST
+* and queueing into IndexedDB for replay (`internal/sw.ts`).
+*/
+var BeaconTraceExporter = class {
+	url;
+	constructor(url) {
+		this.url = url;
+	}
+	export(spans, resultCallback) {
+		if (spans.length === 0) {
+			resultCallback({ code: ExportResultCode.SUCCESS });
+			return;
+		}
+		reportBeacon(this.url, JsonTraceSerializer.serializeRequest(spans), "trace", resultCallback);
+	}
+	shutdown() {
+		return Promise.resolve();
+	}
+	forceFlush() {
+		return Promise.resolve();
+	}
+};
+/**
+* Browser-side OTLP log exporter — same beacon transport, log
+* payload. See `BeaconTraceExporter` for the design rationale.
+*/
+var BeaconLogExporter = class {
+	url;
+	constructor(url) {
+		this.url = url;
+	}
+	export(logs, resultCallback) {
+		if (logs.length === 0) {
+			resultCallback({ code: ExportResultCode.SUCCESS });
+			return;
+		}
+		reportBeacon(this.url, JsonLogsSerializer.serializeRequest(logs), "log", resultCallback);
+	}
+	shutdown() {
+		return Promise.resolve();
+	}
+	forceFlush() {
+		return Promise.resolve();
+	}
+};
+/**
+* Browser-side OTLP metric exporter — beacon transport, metric
+* payload, `DELTA` temporality.
+*
+* `DELTA` matches what the OTLP HTTP exporter the kit's previous
+* `OTLPMetricExporter` was configured with (see the
+* `temporalityPreference: AggregationTemporalityPreference.DELTA`
+* arg `provider.ts` used to pass). Returning the same temporality
+* for every instrument type keeps the wire shape downstream
+* consumers receive unchanged across the migration.
+*/
+var BeaconMetricExporter = class {
+	url;
+	constructor(url) {
+		this.url = url;
+	}
+	export(metrics, resultCallback) {
+		reportBeacon(this.url, JsonMetricsSerializer.serializeRequest(metrics), "metric", resultCallback);
+	}
+	selectAggregationTemporality() {
+		return AggregationTemporality.DELTA;
+	}
+	forceFlush() {
+		return Promise.resolve();
+	}
+	shutdown() {
+		return Promise.resolve();
+	}
+};
+function createBeaconTraceExporter(input) {
+	return new BeaconTraceExporter(buildBeaconUrl(input));
+}
+function createBeaconMetricExporter(input) {
+	return new BeaconMetricExporter(buildBeaconUrl(input));
+}
+function createBeaconLogExporter(input) {
+	return new BeaconLogExporter(buildBeaconUrl(input));
+}
+//#endregion
+export { buildBeaconUrl, buildSinkUrl, createBeaconLogExporter, createBeaconMetricExporter, createBeaconTraceExporter };

package/dist/internal/otel/exporter.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"exporter.mjs","names":[],"sources":["../../../src/internal/otel/exporter.ts"],"sourcesContent":["import { diag } from \"@opentelemetry/api\";\nimport type { ExportResult } from \"@opentelemetry/core\";\nimport { ExportResultCode } from \"@opentelemetry/core\";\n// Deep imports against the package build output — the barrel\n// (`@opentelemetry/otlp-transformer`) re-exports the JSON *and*\n// Protobuf serializers, and the protobuf side reaches `protobufjs`\n// which transitively hits `worker_threads.MessageChannel` (via\n// `import-in-the-middle`). Vite externalizes `worker_threads` for\n// the browser test environment with a runtime-throwing stub; the\n// kernel's `await import(\"./otel/index.js\")` chunk inherits any file\n// reachable from the package root through Vite's dep optimizer, so\n// importing from the barrel breaks `provider.test.tsx` with\n// \"Failed to fetch dynamically imported module\" on the chunk URL.\n//\n// The `*/json/trace.js` (etc.) modules import only `@opentelemetry/\n// api` and the package's own JSON-only utility files — no protobuf\n// in the transitive graph. We also pin the file extension (`.js`)\n// instead of letting the directory's `index.js` resolution kick in\n// because resolvers (bun on Linux vs macOS, vite vs raw esbuild)\n// disagree about whether a missing extension on a directory-shaped\n// specifier should resolve to `<dir>/index.js` or fail. The explicit\n// `.js` is the only spelling all of them agree on.\n//\n// `@opentelemetry/otlp-transformer` doesn't ship an `\"exports\"` field\n// in its `package.json`, so these deep paths are the supported escape\n// hatch (the OTel HTTP exporters take the same approach internally —\n// see `@opentelemetry/exporter-trace-otlp-http/build/esm/platform/\n// browser/OTLPTraceExporter.js`). Pinned via the workspace catalog so\n// a minor version bump can't quietly relocate the build directory.\nimport { JsonLogsSerializer } from \"@opentelemetry/otlp-transformer/build/esm/logs/json/logs.js\";\nimport { JsonMetricsSerializer } from \"@opentelemetry/otlp-transformer/build/esm/metrics/json/metrics.js\";\nimport { JsonTraceSerializer } from \"@opentelemetry/otlp-transformer/build/esm/trace/json/trace.js\";\nimport type { ReadableLogRecord } from \"@opentelemetry/sdk-logs\";\nimport type {\n  PushMetricExporter,\n  ResourceMetrics,\n} from \"@opentelemetry/sdk-metrics\";\nimport { AggregationTemporality } from \"@opentelemetry/sdk-metrics\";\nimport type { ReadableSpan, SpanExporter } from \"@opentelemetry/sdk-trace-base\";\n\nimport { PRODUCER_VERSION } from \"../version.js\";\n\n/**\n * Opaque collector ingest path. Single endpoint for every OTLP signal —\n * server-side dispatches by which `resource*` block the request carries.\n *\n * Semantically nondescript so common adblock filter lists (EasyPrivacy,\n * uBlock) don't fingerprint it the way they do `traces` / `metrics` /\n * `logs` / `telemetry`. Customer-domain proxy mode is still the\n * recommended path for browser SDKs; this is the second line of defence\n * for direct-ingestion (`pub-token`) clients.\n */\nconst COLLECTOR_SINK_PATH = \"/v2/sink\";\n\n/**\n * Identity gate values the collector accepts via URL query when their\n * matching headers can't be set.\n *\n * `navigator.sendBeacon` (the only browser transport that survives\n * `visibilitychange→hidden`) only attaches `Content-Type` via the\n * `Blob` — no other request headers. We rely on that exclusively for\n * the browser SDK's primary path, so the identity gates the collector\n * enforces (`x-interfere-producer-version`, `x-interfere-pub-token`)\n * have to ride the URL instead. Mirrors `PRODUCER_VERSION_QUERY` /\n * `PUB_TOKEN_QUERY` on\n * `services/collector/src/{modules/v2/middleware,auth/surface}.ts`.\n *\n * Pub-token query exposure note: pub-tokens are public by design (they\n * ship in browser bundles, visible in DevTools), so URL exposure is no\n * worse than the existing header path. API keys deliberately have **no**\n * query fallback — see `surfaceAuth` for the matching server-side\n * rationale.\n */\nconst PRODUCER_VERSION_QUERY = \"_pv\";\nconst PUB_TOKEN_QUERY = \"_pt\";\nconst PUB_TOKEN_HEADER = \"x-interfere-pub-token\";\n\nconst JSON_CONTENT_TYPE = \"application/json\";\n\ninterface ExporterCommon {\n  /**\n   * Auth identity from the kernel's resolved ingest target — currently\n   * `x-interfere-pub-token` only (proxy mode sets nothing because the\n   * proxy server stamps `x-api-key` upstream). Encoded into the beacon\n   * URL via `buildBeaconUrl` rather than into request headers because\n   * `sendBeacon` doesn't carry custom headers.\n   */\n  authHeaders: Headers;\n  /** Base collector URL — the opaque sink path is appended. */\n  collectorUrl: string;\n}\n\n/** Exported for direct unit testing. */\nexport function buildSinkUrl(collectorUrl: string): string {\n  const stripped = collectorUrl.endsWith(\"/\")\n    ? collectorUrl.slice(0, -1)\n    : collectorUrl;\n  return `${stripped}${COLLECTOR_SINK_PATH}`;\n}\n\n/**\n * Beacon-flavoured sink URL — encodes the producer-version (always)\n * and pub-token (when present in `authHeaders`) as query parameters\n * so `navigator.sendBeacon` can authenticate without setting custom\n * request headers.\n *\n * Exported for direct unit testing.\n */\nexport function buildBeaconUrl(input: ExporterCommon): string {\n  const params = new URLSearchParams({\n    [PRODUCER_VERSION_QUERY]: PRODUCER_VERSION,\n  });\n  const pubToken = input.authHeaders.get(PUB_TOKEN_HEADER);\n  if (pubToken) {\n    params.set(PUB_TOKEN_QUERY, pubToken);\n  }\n  return `${buildSinkUrl(input.collectorUrl)}?${params.toString()}`;\n}\n\n/**\n * Returns true iff the runtime can dispatch a `navigator.sendBeacon`\n * call. Browser-only; server contexts (SSR, prerender, Vitest's `node`\n * environment) trip the typeof guards.\n */\nfunction canSendBeacon(): boolean {\n  return (\n    typeof navigator !== \"undefined\" &&\n    typeof navigator.sendBeacon === \"function\"\n  );\n}\n\n/**\n * Dispatches an OTLP payload via `navigator.sendBeacon` and always\n * reports `SUCCESS` to the BSP. `sendBeacon` is fire-and-forget by\n * spec — a `true` return only means \"the user agent accepted the\n * payload into its delivery queue\", not \"the server received it\".\n *\n * Why never report `FAILED`:\n *   - `BatchSpanProcessor._flushOneBatch` rejects its promise on\n *     `code !== SUCCESS`, and that rejection propagates up through\n *     `forceFlush()` / `shutdown()`. In production, that surfaces\n *     during Vercel function teardown (and other awaited unload\n *     paths) as an unhandled rejection. In tests, it surfaces as\n *     `provider.test.tsx > passes through useSession` — vitest's\n *     `afterEach(close)` awaits `kernel.dispose() → BSP.shutdown\n *     → _flushAll`, the rejection bubbles, and the test fails.\n *   - `sendBeacon`'s `false` return signals a *local* drop (per-call\n *     ~64KiB ceiling, per-page queue full, disallowed scheme). No\n *     network request was attempted, so the service-worker backstop\n *     in `internal/sw.ts` can't intercept it either. Retrying inside\n *     the exporter would just hit the same browser limit again.\n *\n * The data is gone, but the export *completed* in the only sense\n * that matters to the BSP. A `diag.debug` keeps visibility for any\n * OTel diag listener wired into the kernel.\n */\nfunction reportBeacon(\n  url: string,\n  payload: Uint8Array | undefined,\n  signal: \"trace\" | \"log\" | \"metric\",\n  resultCallback: (result: ExportResult) => void\n): void {\n  if (!payload || payload.byteLength === 0) {\n    diag.debug(`[interfere/beacon] ${signal} serializer returned no bytes`);\n    resultCallback({ code: ExportResultCode.SUCCESS });\n    return;\n  }\n  if (!canSendBeacon()) {\n    diag.debug(\n      `[interfere/beacon] navigator.sendBeacon unavailable; dropping ${signal} batch (${payload.byteLength}B)`\n    );\n    resultCallback({ code: ExportResultCode.SUCCESS });\n    return;\n  }\n  // `Blob` is the only sendBeacon argument shape that lets us pin\n  // `Content-Type: application/json` on the request — using the raw\n  // `Uint8Array` would default to `application/octet-stream`, which\n  // the collector's content-type allowlist rejects with 415.\n  //\n  // The cast is necessary because `JsonTraceSerializer.serializeRequest`\n  // returns `Uint8Array<ArrayBufferLike>`, but `Blob`'s constructor\n  // narrows `BlobPart` to `Uint8Array<ArrayBuffer>` (excluding\n  // `SharedArrayBuffer`). The serializer never returns shared-buffer-\n  // backed bytes (it allocates a fresh `Uint8Array(byteLength)`\n  // internally) so the runtime check the type system is asking for is\n  // already true; a structural cast preserves that without forcing an\n  // unnecessary buffer copy.\n  const blob = new Blob([payload as Uint8Array<ArrayBuffer>], {\n    type: JSON_CONTENT_TYPE,\n  });\n  if (!navigator.sendBeacon(url, blob)) {\n    diag.debug(\n      `[interfere/beacon] navigator.sendBeacon refused ${signal} payload (oversized or queue full); dropping ${payload.byteLength}B`\n    );\n  }\n  resultCallback({ code: ExportResultCode.SUCCESS });\n}\n\n/**\n * Browser-side OTLP trace exporter.\n *\n * Dispatches every export via `navigator.sendBeacon` — which is the\n * only browser transport that reliably commits a request the page is\n * also tearing down (`visibilitychange→hidden`, hard navigation). The\n * `keepalive: true` fetch path the OTLP HTTP exporter ships with\n * works for small payloads but falls back to ordinary fetch (which\n * the renderer aborts on unload) once the cumulative 64KiB / 9-\n * concurrent budget is exhausted. Production data on 2026-05-11\n * attributed ~15% browser-fetch span loss to that fallback; the\n * beacon path closes that hole by design.\n *\n * Identity (`x-interfere-producer-version`, `x-interfere-pub-token`)\n * rides the URL because beacons can't carry custom headers. The\n * collector accepts both query and header paths — see\n * `services/collector/src/{modules/v2/middleware,auth/surface}.ts`.\n *\n * No retry on failure. The service worker backstop captures 5xx /\n * network failures separately by intercepting the same beacon POST\n * and queueing into IndexedDB for replay (`internal/sw.ts`).\n */\nclass BeaconTraceExporter implements SpanExporter {\n  private readonly url: string;\n\n  constructor(url: string) {\n    this.url = url;\n  }\n\n  export(\n    spans: ReadableSpan[],\n    resultCallback: (result: ExportResult) => void\n  ): void {\n    if (spans.length === 0) {\n      resultCallback({ code: ExportResultCode.SUCCESS });\n      return;\n    }\n    reportBeacon(\n      this.url,\n      JsonTraceSerializer.serializeRequest(spans),\n      \"trace\",\n      resultCallback\n    );\n  }\n\n  shutdown(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  forceFlush(): Promise<void> {\n    return Promise.resolve();\n  }\n}\n\n/**\n * Browser-side OTLP log exporter — same beacon transport, log\n * payload. See `BeaconTraceExporter` for the design rationale.\n */\nclass BeaconLogExporter {\n  private readonly url: string;\n\n  constructor(url: string) {\n    this.url = url;\n  }\n\n  export(\n    logs: ReadableLogRecord[],\n    resultCallback: (result: ExportResult) => void\n  ): void {\n    if (logs.length === 0) {\n      resultCallback({ code: ExportResultCode.SUCCESS });\n      return;\n    }\n    reportBeacon(\n      this.url,\n      JsonLogsSerializer.serializeRequest(logs),\n      \"log\",\n      resultCallback\n    );\n  }\n\n  shutdown(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  forceFlush(): Promise<void> {\n    return Promise.resolve();\n  }\n}\n\n/**\n * Browser-side OTLP metric exporter — beacon transport, metric\n * payload, `DELTA` temporality.\n *\n * `DELTA` matches what the OTLP HTTP exporter the kit's previous\n * `OTLPMetricExporter` was configured with (see the\n * `temporalityPreference: AggregationTemporalityPreference.DELTA`\n * arg `provider.ts` used to pass). Returning the same temporality\n * for every instrument type keeps the wire shape downstream\n * consumers receive unchanged across the migration.\n */\nclass BeaconMetricExporter implements PushMetricExporter {\n  private readonly url: string;\n\n  constructor(url: string) {\n    this.url = url;\n  }\n\n  export(\n    metrics: ResourceMetrics,\n    resultCallback: (result: ExportResult) => void\n  ): void {\n    reportBeacon(\n      this.url,\n      JsonMetricsSerializer.serializeRequest(metrics),\n      \"metric\",\n      resultCallback\n    );\n  }\n\n  selectAggregationTemporality(): AggregationTemporality {\n    return AggregationTemporality.DELTA;\n  }\n\n  forceFlush(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  shutdown(): Promise<void> {\n    return Promise.resolve();\n  }\n}\n\nexport function createBeaconTraceExporter(\n  input: ExporterCommon\n): BeaconTraceExporter {\n  return new BeaconTraceExporter(buildBeaconUrl(input));\n}\n\nexport function createBeaconMetricExporter(\n  input: ExporterCommon\n): BeaconMetricExporter {\n  return new BeaconMetricExporter(buildBeaconUrl(input));\n}\n\nexport function createBeaconLogExporter(\n  input: ExporterCommon\n): BeaconLogExporter {\n  return new BeaconLogExporter(buildBeaconUrl(input));\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAoDA,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;AAqB5B,MAAM,yBAAyB;AAC/B,MAAM,kBAAkB;AACxB,MAAM,mBAAmB;AAEzB,MAAM,oBAAoB;;AAgB1B,SAAgB,aAAa,cAA8B;CAIzD,OAAO,GAHU,aAAa,SAAS,IAAI,GACvC,aAAa,MAAM,GAAG,GAAG,GACzB,eACiB;;;;;;;;;;AAWvB,SAAgB,eAAe,OAA+B;CAC5D,MAAM,SAAS,IAAI,gBAAgB,GAChC,yBAAyB,kBAC3B,CAAC;CACF,MAAM,WAAW,MAAM,YAAY,IAAI,iBAAiB;CACxD,IAAI,UACF,OAAO,IAAI,iBAAiB,SAAS;CAEvC,OAAO,GAAG,aAAa,MAAM,aAAa,CAAC,GAAG,OAAO,UAAU;;;;;;;AAQjE,SAAS,gBAAyB;CAChC,OACE,OAAO,cAAc,eACrB,OAAO,UAAU,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BpC,SAAS,aACP,KACA,SACA,QACA,gBACM;CACN,IAAI,CAAC,WAAW,QAAQ,eAAe,GAAG;EACxC,KAAK,MAAM,sBAAsB,OAAO,+BAA+B;EACvE,eAAe,EAAE,MAAM,iBAAiB,SAAS,CAAC;EAClD;;CAEF,IAAI,CAAC,eAAe,EAAE;EACpB,KAAK,MACH,iEAAiE,OAAO,UAAU,QAAQ,WAAW,IACtG;EACD,eAAe,EAAE,MAAM,iBAAiB,SAAS,CAAC;EAClD;;CAeF,MAAM,OAAO,IAAI,KAAK,CAAC,QAAmC,EAAE,EAC1D,MAAM,mBACP,CAAC;CACF,IAAI,CAAC,UAAU,WAAW,KAAK,KAAK,EAClC,KAAK,MACH,mDAAmD,OAAO,+CAA+C,QAAQ,WAAW,GAC7H;CAEH,eAAe,EAAE,MAAM,iBAAiB,SAAS,CAAC;;;;;;;;;;;;;;;;;;;;;;;;AAyBpD,IAAM,sBAAN,MAAkD;CAChD;CAEA,YAAY,KAAa;EACvB,KAAK,MAAM;;CAGb,OACE,OACA,gBACM;EACN,IAAI,MAAM,WAAW,GAAG;GACtB,eAAe,EAAE,MAAM,iBAAiB,SAAS,CAAC;GAClD;;EAEF,aACE,KAAK,KACL,oBAAoB,iBAAiB,MAAM,EAC3C,SACA,eACD;;CAGH,WAA0B;EACxB,OAAO,QAAQ,SAAS;;CAG1B,aAA4B;EAC1B,OAAO,QAAQ,SAAS;;;;;;;AAQ5B,IAAM,oBAAN,MAAwB;CACtB;CAEA,YAAY,KAAa;EACvB,KAAK,MAAM;;CAGb,OACE,MACA,gBACM;EACN,IAAI,KAAK,WAAW,GAAG;GACrB,eAAe,EAAE,MAAM,iBAAiB,SAAS,CAAC;GAClD;;EAEF,aACE,KAAK,KACL,mBAAmB,iBAAiB,KAAK,EACzC,OACA,eACD;;CAGH,WAA0B;EACxB,OAAO,QAAQ,SAAS;;CAG1B,aAA4B;EAC1B,OAAO,QAAQ,SAAS;;;;;;;;;;;;;;AAe5B,IAAM,uBAAN,MAAyD;CACvD;CAEA,YAAY,KAAa;EACvB,KAAK,MAAM;;CAGb,OACE,SACA,gBACM;EACN,aACE,KAAK,KACL,sBAAsB,iBAAiB,QAAQ,EAC/C,UACA,eACD;;CAGH,+BAAuD;EACrD,OAAO,uBAAuB;;CAGhC,aAA4B;EAC1B,OAAO,QAAQ,SAAS;;CAG1B,WAA0B;EACxB,OAAO,QAAQ,SAAS;;;AAI5B,SAAgB,0BACd,OACqB;CACrB,OAAO,IAAI,oBAAoB,eAAe,MAAM,CAAC;;AAGvD,SAAgB,2BACd,OACsB;CACtB,OAAO,IAAI,qBAAqB,eAAe,MAAM,CAAC;;AAGxD,SAAgB,wBACd,OACmB;CACnB,OAAO,IAAI,kBAAkB,eAAe,MAAM,CAAC"}

package/dist/internal/otel/index.d.mts

@@ -0,0 +1,6 @@
+import { createBeaconMetricExporter, createBeaconTraceExporter } from "./exporter.mjs";
+import { InstrumentationsInput, registerBundledInstrumentations } from "./instrumentations.mjs";
+import { readPropagationFromDocument } from "./propagation.mjs";
+import { OtelProviderHandle, OtelProviderInput, buildOtelProvider } from "./provider.mjs";
+import { captureWebVitals } from "./web-vitals.mjs";
+export { type InstrumentationsInput, type OtelProviderHandle, type OtelProviderInput, buildOtelProvider, captureWebVitals, createBeaconMetricExporter, createBeaconTraceExporter, readPropagationFromDocument, registerBundledInstrumentations };

package/dist/internal/otel/index.mjs

@@ -0,0 +1,6 @@
+import { createBeaconMetricExporter, createBeaconTraceExporter } from "./exporter.mjs";
+import { registerBundledInstrumentations } from "./instrumentations.mjs";
+import { readPropagationFromDocument } from "./propagation.mjs";
+import { buildOtelProvider } from "./provider.mjs";
+import { captureWebVitals } from "./web-vitals.mjs";
+export { buildOtelProvider, captureWebVitals, createBeaconMetricExporter, createBeaconTraceExporter, readPropagationFromDocument, registerBundledInstrumentations };

package/dist/internal/otel/instrumentations.d.mts

@@ -0,0 +1,42 @@
+import { WebTracerProvider } from "@opentelemetry/sdk-trace-web";
+
+//#region src/internal/otel/instrumentations.d.ts
+interface InstrumentationsInput {
+  /**
+   * URLs the SDK exempts from `fetch` and `XHR` instrumentation —
+   * typically our own ingest/OTLP endpoints, so the SDK doesn't trace
+   * its own export requests in an infinite loop. Combined with the
+   * `THIRD_PARTY_IGNORE` defaults and the customer's `ignoreUrls`.
+   */
+  ignoreUrls: (string | RegExp)[];
+  /**
+   * Customer-supplied URL patterns the fetch + XHR instrumentations
+   * inject `traceparent` + `baggage` headers on. Same-origin requests
+   * always propagate.
+   */
+  propagateContextUrls?: (string | RegExp)[];
+  /**
+   * Pathname → low-cardinality route template (e.g. `/blog/[slug]`).
+   * Drives span renaming + `url.path` / `http.route` attrs across
+   * fetch, document-load, user-interaction, and long-task.
+   */
+  resolveRoute?: (pathname: string) => string | undefined;
+  /**
+   * The kernel's private provider — instrumentations register against
+   * it, not the global one, so customer OTel setups stay untouched.
+   */
+  tracerProvider: WebTracerProvider;
+}
+/**
+ * Registers every browser auto-instrumentation against the kernel's
+ * private provider. Every instrumentation is enriched with the same
+ * route-template-aware URL attributes so dashboards can slice fetch /
+ * interaction / long-task / resource-load by `http.route` without
+ * cardinality blow-up from raw pathnames.
+ *
+ * Returns a disposer that unregisters everything; called by
+ * `kernel.dispose()`.
+ */
+declare function registerBundledInstrumentations(input: InstrumentationsInput): () => void;
+//#endregion
+export { InstrumentationsInput, registerBundledInstrumentations };

package/dist/internal/otel/instrumentations.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrumentations.d.mts","names":[],"sources":["../../../src/internal/otel/instrumentations.ts"],"mappings":";;;UAgHiB,qBAAA;;AAAjB;;;;;EAOE,UAAA,YAAsB,MAAA;EAiBW;;;;;EAXjC,oBAAA,aAAiC,MAAA;EAMjC;;;;;EAAA,YAAA,IAAgB,QAAA;EAkBF;;;;EAbd,cAAA,EAAgB,iBAAA;AAAA;;;;;;;;;;;iBAaF,+BAAA,CACd,KAAA,EAAO,qBAAA"}

package/dist/internal/otel/instrumentations.mjs

@@ -0,0 +1,150 @@
+import { describeActionable, isActionable } from "../dom/actionable.mjs";
+import { registerInstrumentations } from "@opentelemetry/instrumentation";
+import { BrowserNavigationInstrumentation, defaultSanitizeUrl } from "@opentelemetry/instrumentation-browser-navigation";
+import { DocumentLoadInstrumentation } from "@opentelemetry/instrumentation-document-load";
+import { FetchInstrumentation } from "@opentelemetry/instrumentation-fetch";
+import { LongTaskInstrumentation } from "@opentelemetry/instrumentation-long-task";
+import { UserInteractionInstrumentation } from "@opentelemetry/instrumentation-user-interaction";
+import { XMLHttpRequestInstrumentation } from "@opentelemetry/instrumentation-xml-http-request";
+//#region src/internal/otel/instrumentations.ts
+const ATTR_HTTP_ROUTE = "http.route";
+const ATTR_URL_FULL = "url.full";
+const ATTR_URL_PATH = "url.path";
+/**
+* Mirrors the `semconvStabilityOptIn` constant from the internal
+* `observability/browser/rum.ts`. Pins the HTTP attribute set to the
+* stable-namespace conventions (`url.path`, `server.address`, …) so
+* dashboards that filter on those keys aren't broken by minor
+* upgrades of the instrumentation packages.
+*/
+const SEMCONV_STABILITY_OPT_IN = "http,database,messaging,gen_ai_latest_experimental";
+/**
+* Hosts/paths whose CLIENT fetch spans we never want to emit: they
+* always become 1-span orphan traces (no traceparent propagation to
+* 3rd-party origins) and clutter live tail. Conservative, customer-
+* generic list — common analytics / ads / auth / replay vendors that
+* many apps use. Customer-specific noise (Statsig CDNs, our own
+* BetterStack, etc.) belongs in the customer's own `ignoreUrls` config,
+* not hardcoded into a public SDK.
+*/
+const THIRD_PARTY_IGNORE = [
+	/(?:^|\/\/)clerk\./,
+	/\.clerk\./,
+	/\.sentry\./,
+	/\.intercom\./,
+	/\.posthog\./,
+	/\.googletagmanager\.com/,
+	/\.google-analytics\.com/,
+	/\.googleapis\.com/,
+	/\.doubleclick\.net/,
+	/\.facebook\.com/,
+	/\.fbcdn\.net/,
+	/\.analytics\.google\.com/,
+	/px\.ads\.linkedin\.com/,
+	/[?&]_rsc=/
+];
+const NEVER_MATCH = /^$/;
+const ESCAPE_RE = /[.*+?^${}()|[\]\\]/g;
+function sameOriginPattern() {
+	if (typeof window === "undefined") return NEVER_MATCH;
+	const { protocol, host } = window.location;
+	return new RegExp(`^${protocol}//${host.replace(ESCAPE_RE, "\\$&")}`);
+}
+function stampInteractionAttrs(eventType, element, span) {
+	const desc = describeActionable(element);
+	span.setAttribute("ui.event_type", eventType);
+	span.setAttribute("ui.target.tag", desc.tag);
+	if (desc.id) span.setAttribute("ui.target.id", desc.id);
+	if (desc.name) span.setAttribute("ui.target.name", desc.name);
+	if (desc.role) span.setAttribute("ui.target.role", desc.role);
+	if (desc.ariaLabel) span.setAttribute("ui.target.aria_label", desc.ariaLabel);
+	if (desc.text) span.setAttribute("ui.target.text", desc.text);
+}
+function stampUrlAttrs(span, resolveRoute) {
+	if (typeof window === "undefined") return;
+	const pathname = window.location.pathname;
+	const route = resolveRoute?.(pathname);
+	span.setAttribute(ATTR_URL_PATH, route ?? pathname);
+	span.setAttribute(ATTR_URL_FULL, window.location.href);
+	if (route) span.setAttribute(ATTR_HTTP_ROUTE, route);
+}
+/**
+* Registers every browser auto-instrumentation against the kernel's
+* private provider. Every instrumentation is enriched with the same
+* route-template-aware URL attributes so dashboards can slice fetch /
+* interaction / long-task / resource-load by `http.route` without
+* cardinality blow-up from raw pathnames.
+*
+* Returns a disposer that unregisters everything; called by
+* `kernel.dispose()`.
+*/
+function registerBundledInstrumentations(input) {
+	const { tracerProvider, ignoreUrls, propagateContextUrls = [] } = input;
+	const resolveRoute = input.resolveRoute;
+	const origin = sameOriginPattern();
+	const fetchIgnore = [...ignoreUrls, ...THIRD_PARTY_IGNORE];
+	return registerInstrumentations({
+		tracerProvider,
+		instrumentations: [
+			new FetchInstrumentation({
+				propagateTraceHeaderCorsUrls: [origin, ...propagateContextUrls],
+				ignoreUrls: fetchIgnore,
+				semconvStabilityOptIn: SEMCONV_STABILITY_OPT_IN,
+				measureRequestSize: true,
+				applyCustomAttributesOnSpan: (span, request) => {
+					const url = request instanceof Request ? request.url : request?.toString();
+					if (typeof url !== "string") return;
+					try {
+						const parsed = new URL(url);
+						span.setAttribute(ATTR_URL_PATH, parsed.pathname);
+						if (origin.test(url) || propagateContextUrls.some((re) => re instanceof RegExp ? re.test(url) : url.includes(re))) {
+							const method = (request instanceof Request ? request.method : void 0) ?? "GET";
+							const route = resolveRoute?.(parsed.pathname);
+							if (route) span.setAttribute(ATTR_HTTP_ROUTE, route);
+							span.updateName(`${method} ${route ?? parsed.pathname}`);
+						}
+					} catch {
+						return;
+					}
+				}
+			}),
+			new XMLHttpRequestInstrumentation({
+				propagateTraceHeaderCorsUrls: [origin, ...propagateContextUrls],
+				ignoreUrls: fetchIgnore,
+				semconvStabilityOptIn: SEMCONV_STABILITY_OPT_IN
+			}),
+			new DocumentLoadInstrumentation({
+				semconvStabilityOptIn: SEMCONV_STABILITY_OPT_IN,
+				applyCustomAttributesOnSpan: { resourceFetch: (span, entry) => {
+					const name = entry?.name;
+					if (typeof name !== "string") return;
+					try {
+						const url = new URL(name);
+						const isCrossOrigin = typeof window !== "undefined" && url.origin !== window.location.origin;
+						span.updateName(isCrossOrigin ? `resource: ${url.host}${url.pathname}` : `resource: ${url.pathname}`);
+						span.setAttribute(ATTR_URL_FULL, name);
+						span.setAttribute(ATTR_URL_PATH, url.pathname);
+						span.setAttribute("server.address", url.host);
+					} catch {}
+				} }
+			}),
+			new BrowserNavigationInstrumentation({ sanitizeUrl: defaultSanitizeUrl }),
+			new UserInteractionInstrumentation({
+				eventNames: ["click", "submit"],
+				shouldPreventSpanCreation: (eventType, element, span) => {
+					if (eventType === "click" && !isActionable(element)) return true;
+					stampInteractionAttrs(eventType, element, span);
+					stampUrlAttrs(span, resolveRoute);
+					return false;
+				}
+			}),
+			new LongTaskInstrumentation({ observerCallback: (span, info) => {
+				stampUrlAttrs(span, resolveRoute);
+				const containerType = info.longtaskEntry.attribution[0]?.containerType;
+				if (containerType) span.setAttribute("longtask.container_type", containerType);
+			} })
+		]
+	});
+}
+//#endregion
+export { registerBundledInstrumentations };

package/dist/internal/otel/instrumentations.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrumentations.mjs","names":[],"sources":["../../../src/internal/otel/instrumentations.ts"],"sourcesContent":["import type { Span } from \"@opentelemetry/api\";\nimport { registerInstrumentations } from \"@opentelemetry/instrumentation\";\nimport {\n  BrowserNavigationInstrumentation,\n  defaultSanitizeUrl,\n} from \"@opentelemetry/instrumentation-browser-navigation\";\nimport { DocumentLoadInstrumentation } from \"@opentelemetry/instrumentation-document-load\";\nimport { FetchInstrumentation } from \"@opentelemetry/instrumentation-fetch\";\nimport {\n  LongTaskInstrumentation,\n  type ObserverCallbackInformation,\n} from \"@opentelemetry/instrumentation-long-task\";\nimport { UserInteractionInstrumentation } from \"@opentelemetry/instrumentation-user-interaction\";\nimport { XMLHttpRequestInstrumentation } from \"@opentelemetry/instrumentation-xml-http-request\";\nimport type { WebTracerProvider } from \"@opentelemetry/sdk-trace-web\";\n\nimport { describeActionable, isActionable } from \"../dom/actionable.js\";\n\nconst ATTR_HTTP_ROUTE = \"http.route\" as const;\nconst ATTR_URL_FULL = \"url.full\" as const;\nconst ATTR_URL_PATH = \"url.path\" as const;\n\n/**\n * Mirrors the `semconvStabilityOptIn` constant from the internal\n * `observability/browser/rum.ts`. Pins the HTTP attribute set to the\n * stable-namespace conventions (`url.path`, `server.address`, …) so\n * dashboards that filter on those keys aren't broken by minor\n * upgrades of the instrumentation packages.\n */\nconst SEMCONV_STABILITY_OPT_IN =\n  \"http,database,messaging,gen_ai_latest_experimental\";\n\n/**\n * Hosts/paths whose CLIENT fetch spans we never want to emit: they\n * always become 1-span orphan traces (no traceparent propagation to\n * 3rd-party origins) and clutter live tail. Conservative, customer-\n * generic list — common analytics / ads / auth / replay vendors that\n * many apps use. Customer-specific noise (Statsig CDNs, our own\n * BetterStack, etc.) belongs in the customer's own `ignoreUrls` config,\n * not hardcoded into a public SDK.\n */\nconst THIRD_PARTY_IGNORE: RegExp[] = [\n  /(?:^|\\/\\/)clerk\\./,\n  /\\.clerk\\./,\n  /\\.sentry\\./,\n  /\\.intercom\\./,\n  /\\.posthog\\./,\n  /\\.googletagmanager\\.com/,\n  /\\.google-analytics\\.com/,\n  /\\.googleapis\\.com/,\n  /\\.doubleclick\\.net/,\n  /\\.facebook\\.com/,\n  /\\.fbcdn\\.net/,\n  /\\.analytics\\.google\\.com/,\n  /px\\.ads\\.linkedin\\.com/,\n  /[?&]_rsc=/,\n];\n\nconst NEVER_MATCH = /^$/;\nconst ESCAPE_RE = /[.*+?^${}()|[\\]\\\\]/g;\n\nfunction sameOriginPattern(): RegExp {\n  if (typeof window === \"undefined\") {\n    return NEVER_MATCH;\n  }\n  const { protocol, host } = window.location;\n  return new RegExp(`^${protocol}//${host.replace(ESCAPE_RE, \"\\\\$&\")}`);\n}\n\nfunction stampInteractionAttrs(\n  eventType: string,\n  element: HTMLElement,\n  span: Span\n): void {\n  const desc = describeActionable(element);\n  span.setAttribute(\"ui.event_type\", eventType);\n  span.setAttribute(\"ui.target.tag\", desc.tag);\n  if (desc.id) {\n    span.setAttribute(\"ui.target.id\", desc.id);\n  }\n  if (desc.name) {\n    span.setAttribute(\"ui.target.name\", desc.name);\n  }\n  if (desc.role) {\n    span.setAttribute(\"ui.target.role\", desc.role);\n  }\n  if (desc.ariaLabel) {\n    span.setAttribute(\"ui.target.aria_label\", desc.ariaLabel);\n  }\n  // Truncated visible label — useful for triage without exfiltrating\n  // full DOM contents. Only meaningful on the direct target.\n  if (desc.text) {\n    span.setAttribute(\"ui.target.text\", desc.text);\n  }\n}\n\nfunction stampUrlAttrs(\n  span: Span,\n  resolveRoute: ((pathname: string) => string | undefined) | undefined\n): void {\n  if (typeof window === \"undefined\") {\n    return;\n  }\n  const pathname = window.location.pathname;\n  const route = resolveRoute?.(pathname);\n  span.setAttribute(ATTR_URL_PATH, route ?? pathname);\n  span.setAttribute(ATTR_URL_FULL, window.location.href);\n  if (route) {\n    span.setAttribute(ATTR_HTTP_ROUTE, route);\n  }\n}\n\nexport interface InstrumentationsInput {\n  /**\n   * URLs the SDK exempts from `fetch` and `XHR` instrumentation —\n   * typically our own ingest/OTLP endpoints, so the SDK doesn't trace\n   * its own export requests in an infinite loop. Combined with the\n   * `THIRD_PARTY_IGNORE` defaults and the customer's `ignoreUrls`.\n   */\n  ignoreUrls: (string | RegExp)[];\n  /**\n   * Customer-supplied URL patterns the fetch + XHR instrumentations\n   * inject `traceparent` + `baggage` headers on. Same-origin requests\n   * always propagate.\n   */\n  propagateContextUrls?: (string | RegExp)[];\n  /**\n   * Pathname → low-cardinality route template (e.g. `/blog/[slug]`).\n   * Drives span renaming + `url.path` / `http.route` attrs across\n   * fetch, document-load, user-interaction, and long-task.\n   */\n  resolveRoute?: (pathname: string) => string | undefined;\n  /**\n   * The kernel's private provider — instrumentations register against\n   * it, not the global one, so customer OTel setups stay untouched.\n   */\n  tracerProvider: WebTracerProvider;\n}\n\n/**\n * Registers every browser auto-instrumentation against the kernel's\n * private provider. Every instrumentation is enriched with the same\n * route-template-aware URL attributes so dashboards can slice fetch /\n * interaction / long-task / resource-load by `http.route` without\n * cardinality blow-up from raw pathnames.\n *\n * Returns a disposer that unregisters everything; called by\n * `kernel.dispose()`.\n */\nexport function registerBundledInstrumentations(\n  input: InstrumentationsInput\n): () => void {\n  const { tracerProvider, ignoreUrls, propagateContextUrls = [] } = input;\n  const resolveRoute = input.resolveRoute;\n  const origin = sameOriginPattern();\n  const fetchIgnore = [...ignoreUrls, ...THIRD_PARTY_IGNORE];\n\n  return registerInstrumentations({\n    tracerProvider,\n    instrumentations: [\n      new FetchInstrumentation({\n        propagateTraceHeaderCorsUrls: [origin, ...propagateContextUrls],\n        ignoreUrls: fetchIgnore,\n        semconvStabilityOptIn: SEMCONV_STABILITY_OPT_IN,\n        measureRequestSize: true,\n        applyCustomAttributesOnSpan: (\n          span: Span,\n          request: Request | RequestInit\n        ) => {\n          const url =\n            request instanceof Request ? request.url : request?.toString();\n          if (typeof url !== \"string\") {\n            return;\n          }\n          try {\n            const parsed = new URL(url);\n            span.setAttribute(ATTR_URL_PATH, parsed.pathname);\n            const isTracked =\n              origin.test(url) ||\n              propagateContextUrls.some((re) =>\n                re instanceof RegExp ? re.test(url) : url.includes(re)\n              );\n            if (isTracked) {\n              const method =\n                (request instanceof Request ? request.method : undefined) ??\n                \"GET\";\n              const route = resolveRoute?.(parsed.pathname);\n              if (route) {\n                span.setAttribute(ATTR_HTTP_ROUTE, route);\n              }\n              span.updateName(`${method} ${route ?? parsed.pathname}`);\n            }\n          } catch {\n            return;\n          }\n        },\n      }),\n      new XMLHttpRequestInstrumentation({\n        propagateTraceHeaderCorsUrls: [origin, ...propagateContextUrls],\n        ignoreUrls: fetchIgnore,\n        semconvStabilityOptIn: SEMCONV_STABILITY_OPT_IN,\n      }),\n      new DocumentLoadInstrumentation({\n        semconvStabilityOptIn: SEMCONV_STABILITY_OPT_IN,\n        // Default `resourceFetch` span name is the literal string\n        // `\"resourceFetch\"` for every entry — useless when a single\n        // page load emits 30 of them. Replace with the pathname (or\n        // origin+path for cross-origin) so the waterfall is scannable.\n        applyCustomAttributesOnSpan: {\n          resourceFetch: (span, entry) => {\n            const name = entry?.name;\n            if (typeof name !== \"string\") {\n              return;\n            }\n            try {\n              const url = new URL(name);\n              const isCrossOrigin =\n                typeof window !== \"undefined\" &&\n                url.origin !== window.location.origin;\n              span.updateName(\n                isCrossOrigin\n                  ? `resource: ${url.host}${url.pathname}`\n                  : `resource: ${url.pathname}`\n              );\n              span.setAttribute(ATTR_URL_FULL, name);\n              span.setAttribute(ATTR_URL_PATH, url.pathname);\n              span.setAttribute(\"server.address\", url.host);\n            } catch {\n              // Malformed/relative URL — leave the default name and\n              // let the entry's own attributes carry whatever info\n              // the SDK already stamped.\n            }\n          },\n        },\n      }),\n      // `BrowserNavigationInstrumentation` emits a `browser.navigation`\n      // log record per hard navigation (page load) and soft navigation\n      // (history.pushState, hash change, back/forward). The default\n      // sanitizer redacts credentials in the URL and common sensitive\n      // query params (`token`, `api_key`, `secret`, …) before emit.\n      new BrowserNavigationInstrumentation({\n        sanitizeUrl: defaultSanitizeUrl,\n      }),\n      new UserInteractionInstrumentation({\n        eventNames: [\"click\", \"submit\"],\n        // Despite the name, `shouldPreventSpanCreation` is also the\n        // hook for *enriching* spans (return falsy → create the span;\n        // the callback may set attributes on the way through). We use\n        // it as both: stamp a stable target descriptor for\n        // dashboarding, then suppress spans on elements that aren't\n        // actionable (scroll containers, body clicks, etc.).\n        shouldPreventSpanCreation: (eventType, element, span) => {\n          if (eventType === \"click\" && !isActionable(element)) {\n            return true;\n          }\n          stampInteractionAttrs(eventType, element, span);\n          stampUrlAttrs(span, resolveRoute);\n          return false;\n        },\n      }),\n      // Long-task spans default to a generic `longtask` name with\n      // attribution embedded as attributes — but no page context.\n      // Empty `url.path` makes it impossible to triage which routes\n      // are jank-heavy. Stamp it in the observer callback so\n      // dashboards can slice by route.\n      new LongTaskInstrumentation({\n        observerCallback: (span, info: ObserverCallbackInformation) => {\n          stampUrlAttrs(span, resolveRoute);\n          // PerformanceLongTaskTiming attribution[0].containerType is\n          // the surface that hosted the offending task. Most are\n          // `\"window\"` (main frame); the few that aren't (`\"iframe\"`,\n          // `\"embed\"`, `\"object\"`) are the actionable ones — surface\n          // them as a top-level attr instead of leaving them buried\n          // in `longtask.attribution.container_type`.\n          const containerType =\n            info.longtaskEntry.attribution[0]?.containerType;\n          if (containerType) {\n            span.setAttribute(\"longtask.container_type\", containerType);\n          }\n        },\n      }),\n    ],\n  });\n}\n"],"mappings":"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"}

package/dist/internal/otel/page-scope-context-manager.d.mts

@@ -0,0 +1,32 @@
+import { Context } from "@opentelemetry/api";
+import { ZoneContextManager } from "@opentelemetry/context-zone";
+
+//#region src/internal/otel/page-scope-context-manager.d.ts
+/**
+ * `ZoneContextManager` returns `ROOT_CONTEXT` whenever `context.active()` is
+ * called outside a zone the manager itself created — which in practice is
+ * most of the time:
+ *
+ *   - app code calling `fetch(...)` from a `useEffect`
+ *   - `PerformanceObserver` callbacks (long-task, paint timing, …)
+ *   - top-level await / module init code
+ *   - listeners attached before the SDK booted
+ *
+ * Spans created from those code paths default to "no parent" → root, which
+ * is why a single page load produces N disjoint traces (one per
+ * instrumentation) instead of one waterfall.
+ *
+ * This subclass adds a single fallback: if the underlying zone lookup yields
+ * `ROOT_CONTEXT`, return the page-scope context instead. The page-scope
+ * context is built once at SDK init from the `<meta name="traceparent">`
+ * tag emitted by the SSR layout. If the meta tag is absent the page scope
+ * stays at `ROOT_CONTEXT` and the manager behaves like a stock
+ * `ZoneContextManager`.
+ */
+declare class PageScopeContextManager extends ZoneContextManager {
+  private pageScope;
+  setPageScope(ctx: Context): void;
+  active(): Context;
+}
+//#endregion
+export { PageScopeContextManager };

package/dist/internal/otel/page-scope-context-manager.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-scope-context-manager.d.mts","names":[],"sources":["../../../src/internal/otel/page-scope-context-manager.ts"],"mappings":";;;;;;AAyBA;;;;;;;;;;;;;;;;;;;cAAa,uBAAA,SAAgC,kBAAA;EAAA,QACnC,SAAA;EAER,YAAA,CAAa,GAAA,EAAK,OAAA;EAIT,MAAA,CAAA,GAAU,OAAA;AAAA"}

package/dist/internal/otel/page-scope-context-manager.mjs

@@ -0,0 +1,36 @@
+import { ROOT_CONTEXT } from "@opentelemetry/api";
+import { ZoneContextManager } from "@opentelemetry/context-zone";
+//#region src/internal/otel/page-scope-context-manager.ts
+/**
+* `ZoneContextManager` returns `ROOT_CONTEXT` whenever `context.active()` is
+* called outside a zone the manager itself created — which in practice is
+* most of the time:
+*
+*   - app code calling `fetch(...)` from a `useEffect`
+*   - `PerformanceObserver` callbacks (long-task, paint timing, …)
+*   - top-level await / module init code
+*   - listeners attached before the SDK booted
+*
+* Spans created from those code paths default to "no parent" → root, which
+* is why a single page load produces N disjoint traces (one per
+* instrumentation) instead of one waterfall.
+*
+* This subclass adds a single fallback: if the underlying zone lookup yields
+* `ROOT_CONTEXT`, return the page-scope context instead. The page-scope
+* context is built once at SDK init from the `<meta name="traceparent">`
+* tag emitted by the SSR layout. If the meta tag is absent the page scope
+* stays at `ROOT_CONTEXT` and the manager behaves like a stock
+* `ZoneContextManager`.
+*/
+var PageScopeContextManager = class extends ZoneContextManager {
+	pageScope = ROOT_CONTEXT;
+	setPageScope(ctx) {
+		this.pageScope = ctx;
+	}
+	active() {
+		const ctx = super.active();
+		return ctx === ROOT_CONTEXT ? this.pageScope : ctx;
+	}
+};
+//#endregion
+export { PageScopeContextManager };

package/dist/internal/otel/page-scope-context-manager.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-scope-context-manager.mjs","names":[],"sources":["../../../src/internal/otel/page-scope-context-manager.ts"],"sourcesContent":["import type { Context } from \"@opentelemetry/api\";\nimport { ROOT_CONTEXT } from \"@opentelemetry/api\";\nimport { ZoneContextManager } from \"@opentelemetry/context-zone\";\n\n/**\n * `ZoneContextManager` returns `ROOT_CONTEXT` whenever `context.active()` is\n * called outside a zone the manager itself created — which in practice is\n * most of the time:\n *\n *   - app code calling `fetch(...)` from a `useEffect`\n *   - `PerformanceObserver` callbacks (long-task, paint timing, …)\n *   - top-level await / module init code\n *   - listeners attached before the SDK booted\n *\n * Spans created from those code paths default to \"no parent\" → root, which\n * is why a single page load produces N disjoint traces (one per\n * instrumentation) instead of one waterfall.\n *\n * This subclass adds a single fallback: if the underlying zone lookup yields\n * `ROOT_CONTEXT`, return the page-scope context instead. The page-scope\n * context is built once at SDK init from the `<meta name=\"traceparent\">`\n * tag emitted by the SSR layout. If the meta tag is absent the page scope\n * stays at `ROOT_CONTEXT` and the manager behaves like a stock\n * `ZoneContextManager`.\n */\nexport class PageScopeContextManager extends ZoneContextManager {\n  private pageScope: Context = ROOT_CONTEXT;\n\n  setPageScope(ctx: Context): void {\n    this.pageScope = ctx;\n  }\n\n  override active(): Context {\n    const ctx = super.active();\n    return ctx === ROOT_CONTEXT ? this.pageScope : ctx;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAyBA,IAAa,0BAAb,cAA6C,mBAAmB;CAC9D,YAA6B;CAE7B,aAAa,KAAoB;EAC/B,KAAK,YAAY;;CAGnB,SAA2B;EACzB,MAAM,MAAM,MAAM,QAAQ;EAC1B,OAAO,QAAQ,eAAe,KAAK,YAAY"}

package/dist/internal/otel/propagation.d.mts

@@ -0,0 +1,21 @@
+import { Context } from "@opentelemetry/api";
+
+//#region src/internal/otel/propagation.d.ts
+/**
+ * Reads the W3C `traceparent` (and optional `tracestate`) meta tag from the
+ * document head and extracts an OTel `Context`. SSR renderers (Next, Vite,
+ * …) inject the server-side request span's context so the client SDK can
+ * stitch its spans onto the same trace.
+ *
+ * Returns `null` when:
+ *  - called server-side (no `document`)
+ *  - no `traceparent` meta tag is present
+ *  - the extracted context has an invalid trace id
+ *  - the `sampled` flag is unset — the browser doesn't honor the bit when
+ *    creating child spans, so an unsampled parent would orphan every
+ *    browser span under a trace with no recorded server segments. Drop
+ *    instead so spans fall back to a fresh root.
+ */
+declare function readPropagationFromDocument(): Context | null;
+//#endregion
+export { readPropagationFromDocument };

package/dist/internal/otel/propagation.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"propagation.d.mts","names":[],"sources":["../../../src/internal/otel/propagation.ts"],"mappings":";;;;;AAuCA;;;;;;;;;;;;;iBAAgB,2BAAA,CAAA,GAA+B,OAAA"}

package/dist/internal/otel/propagation.mjs

@@ -0,0 +1,40 @@
+import { ROOT_CONTEXT, defaultTextMapGetter, trace } from "@opentelemetry/api";
+import { W3CTraceContextPropagator } from "@opentelemetry/core";
+//#region src/internal/otel/propagation.ts
+const TRACEPARENT_META = "traceparent";
+const TRACESTATE_META = "tracestate";
+const INVALID_TRACE_ID = "00000000000000000000000000000000";
+const TRACE_FLAGS_SAMPLED = 1;
+const W3C_PROPAGATOR = new W3CTraceContextPropagator();
+function readMeta(name) {
+	if (typeof document === "undefined") return null;
+	return document.querySelector(`meta[name="${name}"]`)?.getAttribute("content") ?? null;
+}
+/**
+* Reads the W3C `traceparent` (and optional `tracestate`) meta tag from the
+* document head and extracts an OTel `Context`. SSR renderers (Next, Vite,
+* …) inject the server-side request span's context so the client SDK can
+* stitch its spans onto the same trace.
+*
+* Returns `null` when:
+*  - called server-side (no `document`)
+*  - no `traceparent` meta tag is present
+*  - the extracted context has an invalid trace id
+*  - the `sampled` flag is unset — the browser doesn't honor the bit when
+*    creating child spans, so an unsampled parent would orphan every
+*    browser span under a trace with no recorded server segments. Drop
+*    instead so spans fall back to a fresh root.
+*/
+function readPropagationFromDocument() {
+	const traceparent = readMeta(TRACEPARENT_META);
+	if (!traceparent) return null;
+	const carrier = { traceparent };
+	const tracestate = readMeta(TRACESTATE_META);
+	if (tracestate) carrier[TRACESTATE_META] = tracestate;
+	const extracted = W3C_PROPAGATOR.extract(ROOT_CONTEXT, carrier, defaultTextMapGetter);
+	const spanCtx = trace.getSpanContext(extracted);
+	if (!spanCtx || spanCtx.traceId === INVALID_TRACE_ID || (spanCtx.traceFlags & TRACE_FLAGS_SAMPLED) === 0) return null;
+	return extracted;
+}
+//#endregion
+export { readPropagationFromDocument };