@interfere/react 9.0.1 → 10.0.0

package/dist/internal/console-patch.d.mts

@@ -0,0 +1,19 @@
+//#region src/internal/console-patch.d.ts
+/**
+ * Single point of `console.{debug,log,info,warn,error}` patching. The
+ * errors plugin and the logs plugin both want to observe console calls;
+ * before this consolidation, each patched independently and the
+ * resulting wrap-order coupling made teardown leaky.
+ *
+ * Now: a single set of patched methods is installed on first
+ * subscription, fans out to every subscriber, and is uninstalled on the
+ * last unsubscription. Handlers never wrap each other; they observe.
+ */
+declare const CONSOLE_LEVELS: readonly ["debug", "log", "info", "warn", "error"];
+type ConsoleLevel = (typeof CONSOLE_LEVELS)[number];
+type ConsoleHandler = (level: ConsoleLevel, args: unknown[]) => void;
+declare function onConsoleCall(handler: ConsoleHandler): () => void;
+/** Test hook — drops every handler and restores originals. */
+declare function _resetConsolePatchForTests(): void;
+//#endregion
+export { CONSOLE_LEVELS, ConsoleHandler, ConsoleLevel, _resetConsolePatchForTests, onConsoleCall };

package/dist/internal/console-patch.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"console-patch.d.mts","names":[],"sources":["../../src/internal/console-patch.ts"],"mappings":";;AAUA;;;;;AAQA;;;;cARa,cAAA;AAAA,KAQD,YAAA,WAAuB,cAAA;AAAA,KAEvB,cAAA,IAAkB,KAAA,EAAO,YAAA,EAAc,IAAA;AAAA,iBAiDnC,aAAA,CAAc,OAAA,EAAS,cAAA;;iBAYvB,0BAAA,CAAA"}

package/dist/internal/console-patch.mjs

@@ -0,0 +1,62 @@
+//#region src/internal/console-patch.ts
+/**
+* Single point of `console.{debug,log,info,warn,error}` patching. The
+* errors plugin and the logs plugin both want to observe console calls;
+* before this consolidation, each patched independently and the
+* resulting wrap-order coupling made teardown leaky.
+*
+* Now: a single set of patched methods is installed on first
+* subscription, fans out to every subscriber, and is uninstalled on the
+* last unsubscription. Handlers never wrap each other; they observe.
+*/
+const CONSOLE_LEVELS = [
+	"debug",
+	"log",
+	"info",
+	"warn",
+	"error"
+];
+const handlers = /* @__PURE__ */ new Set();
+const originals = {};
+let installed = false;
+function install() {
+	if (installed) return;
+	installed = true;
+	const target = globalThis.console;
+	for (const level of CONSOLE_LEVELS) {
+		const orig = target[level];
+		if (typeof orig !== "function") continue;
+		originals[level] = orig;
+		target[level] = (...args) => {
+			orig.apply(globalThis.console, args);
+			for (const handler of handlers) handler(level, args);
+		};
+	}
+}
+function uninstall() {
+	if (!installed) return;
+	installed = false;
+	const target = globalThis.console;
+	for (const level of CONSOLE_LEVELS) {
+		const orig = originals[level];
+		if (orig) {
+			target[level] = orig;
+			delete originals[level];
+		}
+	}
+}
+function onConsoleCall(handler) {
+	install();
+	handlers.add(handler);
+	return () => {
+		handlers.delete(handler);
+		if (handlers.size === 0) uninstall();
+	};
+}
+/** Test hook — drops every handler and restores originals. */
+function _resetConsolePatchForTests() {
+	handlers.clear();
+	uninstall();
+}
+//#endregion
+export { CONSOLE_LEVELS, _resetConsolePatchForTests, onConsoleCall };

package/dist/internal/console-patch.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"console-patch.mjs","names":[],"sources":["../../src/internal/console-patch.ts"],"sourcesContent":["/**\n * Single point of `console.{debug,log,info,warn,error}` patching. The\n * errors plugin and the logs plugin both want to observe console calls;\n * before this consolidation, each patched independently and the\n * resulting wrap-order coupling made teardown leaky.\n *\n * Now: a single set of patched methods is installed on first\n * subscription, fans out to every subscriber, and is uninstalled on the\n * last unsubscription. Handlers never wrap each other; they observe.\n */\nexport const CONSOLE_LEVELS = [\n  \"debug\",\n  \"log\",\n  \"info\",\n  \"warn\",\n  \"error\",\n] as const;\n\nexport type ConsoleLevel = (typeof CONSOLE_LEVELS)[number];\n\nexport type ConsoleHandler = (level: ConsoleLevel, args: unknown[]) => void;\n\nconst handlers = new Set<ConsoleHandler>();\nconst originals: Partial<Record<ConsoleLevel, (...args: unknown[]) => void>> =\n  {};\nlet installed = false;\n\nfunction install(): void {\n  if (installed) {\n    return;\n  }\n  installed = true;\n  const target = globalThis.console as unknown as Record<\n    ConsoleLevel,\n    (...args: unknown[]) => void\n  >;\n  for (const level of CONSOLE_LEVELS) {\n    const orig = target[level];\n    if (typeof orig !== \"function\") {\n      continue;\n    }\n    originals[level] = orig;\n    target[level] = (...args: unknown[]) => {\n      orig.apply(globalThis.console, args);\n      for (const handler of handlers) {\n        handler(level, args);\n      }\n    };\n  }\n}\n\nfunction uninstall(): void {\n  if (!installed) {\n    return;\n  }\n  installed = false;\n  const target = globalThis.console as unknown as Record<\n    ConsoleLevel,\n    (...args: unknown[]) => void\n  >;\n  for (const level of CONSOLE_LEVELS) {\n    const orig = originals[level];\n    if (orig) {\n      target[level] = orig;\n      delete originals[level];\n    }\n  }\n}\n\nexport function onConsoleCall(handler: ConsoleHandler): () => void {\n  install();\n  handlers.add(handler);\n  return () => {\n    handlers.delete(handler);\n    if (handlers.size === 0) {\n      uninstall();\n    }\n  };\n}\n\n/** Test hook — drops every handler and restores originals. */\nexport function _resetConsolePatchForTests(): void {\n  handlers.clear();\n  uninstall();\n}\n"],"mappings":";;;;;;;;;;;AAUA,MAAa,iBAAiB;CAC5B;CACA;CACA;CACA;CACA;CACD;AAMD,MAAM,2BAAW,IAAI,KAAqB;AAC1C,MAAM,YACJ,EAAE;AACJ,IAAI,YAAY;AAEhB,SAAS,UAAgB;CACvB,IAAI,WACF;CAEF,YAAY;CACZ,MAAM,SAAS,WAAW;CAI1B,KAAK,MAAM,SAAS,gBAAgB;EAClC,MAAM,OAAO,OAAO;EACpB,IAAI,OAAO,SAAS,YAClB;EAEF,UAAU,SAAS;EACnB,OAAO,UAAU,GAAG,SAAoB;GACtC,KAAK,MAAM,WAAW,SAAS,KAAK;GACpC,KAAK,MAAM,WAAW,UACpB,QAAQ,OAAO,KAAK;;;;AAM5B,SAAS,YAAkB;CACzB,IAAI,CAAC,WACH;CAEF,YAAY;CACZ,MAAM,SAAS,WAAW;CAI1B,KAAK,MAAM,SAAS,gBAAgB;EAClC,MAAM,OAAO,UAAU;EACvB,IAAI,MAAM;GACR,OAAO,SAAS;GAChB,OAAO,UAAU;;;;AAKvB,SAAgB,cAAc,SAAqC;CACjE,SAAS;CACT,SAAS,IAAI,QAAQ;CACrB,aAAa;EACX,SAAS,OAAO,QAAQ;EACxB,IAAI,SAAS,SAAS,GACpB,WAAW;;;;AAMjB,SAAgB,6BAAmC;CACjD,SAAS,OAAO;CAChB,WAAW"}

package/dist/internal/dom/actionable.d.mts

@@ -0,0 +1,27 @@
+//#region src/internal/dom/actionable.d.ts
+/**
+ * Single source of truth for "what counts as a clickable element" across
+ * the SDK. Used by both the `pages` plugin (which captures `ui_event`
+ * envelopes) and the OTel `UserInteractionInstrumentation` enrichment
+ * hook (which gates span creation + stamps target attrs). Before this
+ * was extracted, the two sites diverged and produced inconsistent
+ * notions of "actionable."
+ *
+ * `data-track-click` is the customer escape hatch — any element opted
+ * in via that attribute is treated as actionable regardless of tag/role.
+ */
+declare function isActionable(el: Element): boolean;
+declare function closestActionable(target: EventTarget | null): Element | null;
+interface ActionableDescriptor {
+  ariaLabel?: string | undefined;
+  href?: string | undefined;
+  id?: string | undefined;
+  name?: string | undefined;
+  role?: string | undefined;
+  tag: string;
+  text?: string | undefined;
+  [key: string]: unknown;
+}
+declare function describeActionable(el: Element): ActionableDescriptor;
+//#endregion
+export { ActionableDescriptor, closestActionable, describeActionable, isActionable };

package/dist/internal/dom/actionable.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actionable.d.mts","names":[],"sources":["../../../src/internal/dom/actionable.ts"],"mappings":";;AAkCA;;;;;AAWA;;;;;iBAXgB,YAAA,CAAa,EAAA,EAAI,OAAA;AAAA,iBAWjB,iBAAA,CAAkB,MAAA,EAAQ,WAAA,UAAqB,OAAA;AAAA,UAc9C,oBAAA;EACf,SAAA;EACA,IAAA;EACA,EAAA;EACA,IAAA;EACA,IAAA;EACA,GAAA;EACA,IAAA;EAAA,CACC,GAAA;AAAA;AAAA,iBAGa,kBAAA,CAAmB,EAAA,EAAI,OAAA,GAAU,oBAAA"}

package/dist/internal/dom/actionable.mjs

@@ -0,0 +1,62 @@
+//#region src/internal/dom/actionable.ts
+/**
+* Single source of truth for "what counts as a clickable element" across
+* the SDK. Used by both the `pages` plugin (which captures `ui_event`
+* envelopes) and the OTel `UserInteractionInstrumentation` enrichment
+* hook (which gates span creation + stamps target attrs). Before this
+* was extracted, the two sites diverged and produced inconsistent
+* notions of "actionable."
+*
+* `data-track-click` is the customer escape hatch — any element opted
+* in via that attribute is treated as actionable regardless of tag/role.
+*/
+const ACTIONABLE_TAGS = new Set([
+	"a",
+	"button",
+	"input",
+	"select",
+	"textarea",
+	"summary",
+	"label"
+]);
+const ACTIONABLE_ROLES = new Set([
+	"button",
+	"link",
+	"menuitem",
+	"tab",
+	"checkbox",
+	"radio",
+	"switch"
+]);
+const TEXT_TRUNCATE = 120;
+function isActionable(el) {
+	if (ACTIONABLE_TAGS.has(el.tagName.toLowerCase())) return true;
+	const role = el.getAttribute("role");
+	if (role && ACTIONABLE_ROLES.has(role)) return true;
+	return el.hasAttribute("data-track-click");
+}
+function closestActionable(target) {
+	if (!(target instanceof Element)) return null;
+	let el = target;
+	while (el) {
+		if (isActionable(el)) return el;
+		el = el.parentElement;
+	}
+	return null;
+}
+function describeActionable(el) {
+	const desc = { tag: el.tagName.toLowerCase() };
+	if (el.id) desc.id = el.id;
+	const role = el.getAttribute("role");
+	if (role) desc.role = role;
+	const name = el.getAttribute("name");
+	if (name) desc.name = name;
+	const ariaLabel = el.getAttribute("aria-label");
+	if (ariaLabel) desc.ariaLabel = ariaLabel;
+	if (el instanceof HTMLAnchorElement) desc.href = el.href;
+	const text = el.textContent?.trim().slice(0, TEXT_TRUNCATE);
+	if (text) desc.text = text;
+	return desc;
+}
+//#endregion
+export { closestActionable, describeActionable, isActionable };

package/dist/internal/dom/actionable.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"actionable.mjs","names":[],"sources":["../../../src/internal/dom/actionable.ts"],"sourcesContent":["/**\n * Single source of truth for \"what counts as a clickable element\" across\n * the SDK. Used by both the `pages` plugin (which captures `ui_event`\n * envelopes) and the OTel `UserInteractionInstrumentation` enrichment\n * hook (which gates span creation + stamps target attrs). Before this\n * was extracted, the two sites diverged and produced inconsistent\n * notions of \"actionable.\"\n *\n * `data-track-click` is the customer escape hatch — any element opted\n * in via that attribute is treated as actionable regardless of tag/role.\n */\n\nconst ACTIONABLE_TAGS = new Set([\n  \"a\",\n  \"button\",\n  \"input\",\n  \"select\",\n  \"textarea\",\n  \"summary\",\n  \"label\",\n]);\n\nconst ACTIONABLE_ROLES = new Set([\n  \"button\",\n  \"link\",\n  \"menuitem\",\n  \"tab\",\n  \"checkbox\",\n  \"radio\",\n  \"switch\",\n]);\n\nconst TEXT_TRUNCATE = 120;\n\nexport function isActionable(el: Element): boolean {\n  if (ACTIONABLE_TAGS.has(el.tagName.toLowerCase())) {\n    return true;\n  }\n  const role = el.getAttribute(\"role\");\n  if (role && ACTIONABLE_ROLES.has(role)) {\n    return true;\n  }\n  return el.hasAttribute(\"data-track-click\");\n}\n\nexport function closestActionable(target: EventTarget | null): Element | null {\n  if (!(target instanceof Element)) {\n    return null;\n  }\n  let el: Element | null = target;\n  while (el) {\n    if (isActionable(el)) {\n      return el;\n    }\n    el = el.parentElement;\n  }\n  return null;\n}\n\nexport interface ActionableDescriptor {\n  ariaLabel?: string | undefined;\n  href?: string | undefined;\n  id?: string | undefined;\n  name?: string | undefined;\n  role?: string | undefined;\n  tag: string;\n  text?: string | undefined;\n  [key: string]: unknown;\n}\n\nexport function describeActionable(el: Element): ActionableDescriptor {\n  const desc: ActionableDescriptor = {\n    tag: el.tagName.toLowerCase(),\n  };\n  if (el.id) {\n    desc.id = el.id;\n  }\n  const role = el.getAttribute(\"role\");\n  if (role) {\n    desc.role = role;\n  }\n  const name = el.getAttribute(\"name\");\n  if (name) {\n    desc.name = name;\n  }\n  const ariaLabel = el.getAttribute(\"aria-label\");\n  if (ariaLabel) {\n    desc.ariaLabel = ariaLabel;\n  }\n  if (el instanceof HTMLAnchorElement) {\n    desc.href = el.href;\n  }\n  const text = el.textContent?.trim().slice(0, TEXT_TRUNCATE);\n  if (text) {\n    desc.text = text;\n  }\n  return desc;\n}\n"],"mappings":";;;;;;;;;;;;AAYA,MAAM,kBAAkB,IAAI,IAAI;CAC9B;CACA;CACA;CACA;CACA;CACA;CACA;CACD,CAAC;AAEF,MAAM,mBAAmB,IAAI,IAAI;CAC/B;CACA;CACA;CACA;CACA;CACA;CACA;CACD,CAAC;AAEF,MAAM,gBAAgB;AAEtB,SAAgB,aAAa,IAAsB;CACjD,IAAI,gBAAgB,IAAI,GAAG,QAAQ,aAAa,CAAC,EAC/C,OAAO;CAET,MAAM,OAAO,GAAG,aAAa,OAAO;CACpC,IAAI,QAAQ,iBAAiB,IAAI,KAAK,EACpC,OAAO;CAET,OAAO,GAAG,aAAa,mBAAmB;;AAG5C,SAAgB,kBAAkB,QAA4C;CAC5E,IAAI,EAAE,kBAAkB,UACtB,OAAO;CAET,IAAI,KAAqB;CACzB,OAAO,IAAI;EACT,IAAI,aAAa,GAAG,EAClB,OAAO;EAET,KAAK,GAAG;;CAEV,OAAO;;AAcT,SAAgB,mBAAmB,IAAmC;CACpE,MAAM,OAA6B,EACjC,KAAK,GAAG,QAAQ,aAAa,EAC9B;CACD,IAAI,GAAG,IACL,KAAK,KAAK,GAAG;CAEf,MAAM,OAAO,GAAG,aAAa,OAAO;CACpC,IAAI,MACF,KAAK,OAAO;CAEd,MAAM,OAAO,GAAG,aAAa,OAAO;CACpC,IAAI,MACF,KAAK,OAAO;CAEd,MAAM,YAAY,GAAG,aAAa,aAAa;CAC/C,IAAI,WACF,KAAK,YAAY;CAEnB,IAAI,cAAc,mBAChB,KAAK,OAAO,GAAG;CAEjB,MAAM,OAAO,GAAG,aAAa,MAAM,CAAC,MAAM,GAAG,cAAc;CAC3D,IAAI,MACF,KAAK,OAAO;CAEd,OAAO"}

package/dist/internal/kernel-registry.d.mts

@@ -0,0 +1,8 @@
+import { Kernel } from "./kernel.mjs";
+
+//#region src/internal/kernel-registry.d.ts
+declare function registerKernel(kernel: Kernel): void;
+declare function unregisterKernel(kernel: Kernel): void;
+declare function activeKernel(): Kernel | null;
+//#endregion
+export { activeKernel, registerKernel, unregisterKernel };

package/dist/internal/kernel-registry.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kernel-registry.d.mts","names":[],"sources":["../../src/internal/kernel-registry.ts"],"mappings":";;;iBAsBgB,cAAA,CAAe,MAAA,EAAQ,MAAA;AAAA,iBASvB,gBAAA,CAAiB,MAAA,EAAQ,MAAA;AAAA,iBAMzB,YAAA,CAAA,GAAgB,MAAA"}

package/dist/internal/kernel-registry.mjs

@@ -0,0 +1,31 @@
+import { createLogger } from "../util/log.mjs";
+//#region src/internal/kernel-registry.ts
+const log = createLogger("kernel-registry");
+/**
+* Module-scoped active kernel reference. The framework wrapper
+* (`@interfere/next`, `@interfere/vite`) registers its kernel here on
+* `init()` so the public `api.ts` helpers can find it without each customer
+* call site threading the kernel through.
+*
+* Single-kernel by design: each app bundle has its own module instance, so
+* the common case (one app, one init) gets a clean global. The warn on
+* overwrite catches HMR / accidental double-init / module-federated MFEs
+* that share `@interfere/react` across surfaces — those setups need to
+* reach for `kernel.recordException()` directly rather than the registry.
+*
+* @internal Wrappers only. Importing this from app code will silently
+* de-fang the public api helpers.
+*/
+let active = null;
+function registerKernel(kernel) {
+	if (active && active !== kernel) log.warn("init() called twice with different kernels; later one wins. The public capture()/span() helpers route only to the latest kernel — multi-surface apps should call kernel.recordException() directly.");
+	active = kernel;
+}
+function unregisterKernel(kernel) {
+	if (active === kernel) active = null;
+}
+function activeKernel() {
+	return active;
+}
+//#endregion
+export { activeKernel, registerKernel, unregisterKernel };

package/dist/internal/kernel-registry.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"kernel-registry.mjs","names":[],"sources":["../../src/internal/kernel-registry.ts"],"sourcesContent":["import { createLogger } from \"../util/log.js\";\nimport type { Kernel } from \"./kernel.js\";\n\nconst log = createLogger(\"kernel-registry\");\n\n/**\n * Module-scoped active kernel reference. The framework wrapper\n * (`@interfere/next`, `@interfere/vite`) registers its kernel here on\n * `init()` so the public `api.ts` helpers can find it without each customer\n * call site threading the kernel through.\n *\n * Single-kernel by design: each app bundle has its own module instance, so\n * the common case (one app, one init) gets a clean global. The warn on\n * overwrite catches HMR / accidental double-init / module-federated MFEs\n * that share `@interfere/react` across surfaces — those setups need to\n * reach for `kernel.recordException()` directly rather than the registry.\n *\n * @internal Wrappers only. Importing this from app code will silently\n * de-fang the public api helpers.\n */\nlet active: Kernel | null = null;\n\nexport function registerKernel(kernel: Kernel): void {\n  if (active && active !== kernel) {\n    log.warn(\n      \"init() called twice with different kernels; later one wins. The public capture()/span() helpers route only to the latest kernel — multi-surface apps should call kernel.recordException() directly.\"\n    );\n  }\n  active = kernel;\n}\n\nexport function unregisterKernel(kernel: Kernel): void {\n  if (active === kernel) {\n    active = null;\n  }\n}\n\nexport function activeKernel(): Kernel | null {\n  return active;\n}\n"],"mappings":";;AAGA,MAAM,MAAM,aAAa,kBAAkB;;;;;;;;;;;;;;;;AAiB3C,IAAI,SAAwB;AAE5B,SAAgB,eAAe,QAAsB;CACnD,IAAI,UAAU,WAAW,QACvB,IAAI,KACF,sMACD;CAEH,SAAS;;AAGX,SAAgB,iBAAiB,QAAsB;CACrD,IAAI,WAAW,QACb,SAAS;;AAIb,SAAgB,eAA8B;CAC5C,OAAO"}

package/dist/internal/kernel.d.mts

@@ -0,0 +1,267 @@
+import { PluginContext } from "../plugins/lib/types.mjs";
+import { PluginOverrides } from "../plugins/lib/loader.mjs";
+import { SessionTracker } from "../tracking/api.mjs";
+import { OtelProviderHandle } from "./otel/provider.mjs";
+import { PluginRuntime } from "./plugin-runtime.mjs";
+import { NonErrorException } from "@interfere/types/sdk/errors";
+import { ConsentState } from "@interfere/types/sdk/plugins/manifest";
+import { ReleaseSlug } from "@interfere/types/releases/slug";
+import { MetricReader } from "@opentelemetry/sdk-metrics";
+import { LogRecordProcessor } from "@opentelemetry/sdk-logs";
+import { SpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { IngestedFrame } from "@interfere/types/data/frame";
+import { SessionId } from "@interfere/types/data/session";
+import { IdentifyParams } from "@interfere/types/sdk/identify";
+import { ErrorMechanism } from "@interfere/types/sdk/plugins/payload/errors";
+
+//#region src/internal/kernel.d.ts
+declare function buildSdkStack(wrapperVersions?: string[]): string[];
+interface KernelOptions {
+  consent?: ConsentState;
+  /**
+   * Override the automatic dev-mode guard. When `undefined`, the SDK
+   * auto-detects: it disables itself if `process.env["NODE_ENV"]` is not
+   * `"production"` (Node / webpack / Next.js). In environments where
+   * `process` does not exist (Vite, CRA, plain browser) the SDK
+   * defaults to **enabled** — pass `false` to disable explicitly.
+   */
+  enabled?: boolean;
+  /** Override `globalThis.fetch` for tests / non-browser hosts. */
+  fetch?: typeof globalThis.fetch;
+  plugins?: PluginOverrides;
+  /**
+   * Override the OTel `service.name` resource attribute. Defaults to
+   * `"interfere-sdk"`. Customers running multiple frontends in one
+   * monitoring backend (e.g. `"@interfere/homepage"` vs
+   * `"@interfere/dashboard"`) set this so spans/metrics/logs slice
+   * cleanly by surface.
+   */
+  serviceName?: string;
+  /**
+   * `false` skips the OTel module entirely — the bundler code-splits
+   * `internal/otel/*` out of this path so the error-only bundle never
+   * imports the OTel SDK. `true` (default) loads it with default
+   * instrumentation config. An object loads it with the supplied
+   * config.
+   */
+  tracing?: boolean | TracingOptions;
+}
+/**
+ * Per-instrumentation tuning. Every field is optional; defaults match
+ * what `interfere/homepage` and `interfere/dashboard` use today via
+ * the internal `observability/browser/rum.ts`. New customers don't
+ * need to touch any of these — sensible defaults ship out of the box.
+ */
+interface TracingOptions {
+  /**
+   * Additional URL patterns to skip when creating fetch / XHR spans.
+   * The SDK's own collector endpoint is always ignored; customer-side
+   * third-party SDKs (Clerk, Sentry, GTM, etc.) are also skipped by
+   * default — supplement with anything specific to your app.
+   */
+  ignoreUrls?: (string | RegExp)[];
+  /**
+   * URL patterns that should receive W3C `traceparent` + `baggage`
+   * headers on outgoing fetch / XHR. Same-origin requests always
+   * propagate; this allowlist enables cross-origin propagation
+   * (separate API origin, internal service mesh, etc.).
+   */
+  propagateContextUrls?: (string | RegExp)[];
+  /**
+   * Resolve a URL pathname to a low-cardinality route template
+   * (e.g. `/blog/[slug]`). Without this, dynamic routes produce one
+   * unique span / metric label per visited slug — a cardinality
+   * hazard. Used by fetch, document-load resource enrichment,
+   * user-interaction, long-task, and web-vitals.
+   */
+  resolveRoute?: (pathname: string) => string | undefined;
+  /**
+   * `false` disables Core Web Vitals capture (LCP/FCP/TTFB/INP/CLS).
+   * Defaults to enabled; customers who run their own vitals reporting
+   * can opt out.
+   */
+  webVitals?: boolean;
+}
+/**
+ * @internal
+ * Framework wrappers (`@interfere/next`, `@interfere/vite`) pass extra
+ * fields through `createKernel` that customers never set themselves.
+ * Kept off the customer-facing `KernelOptions` to make the public surface
+ * clean.
+ */
+interface KernelInternalOptions extends KernelOptions {
+  /**
+   * Extra log-record processors fanned into the LoggerProvider's
+   * processor list. Used by `@interfere/observability` for internal-only
+   * dual-write to BetterStack from `interfere/homepage` +
+   * `interfere/dashboard`. **Not part of the customer surface** — the
+   * SDK doesn't expose a way to fan-out to other observability vendors.
+   */
+  _internalAdditionalLogRecordProcessors?: LogRecordProcessor[];
+  /**
+   * Extra metric readers fanned into the MeterProvider's reader list.
+   * See `_internalAdditionalLogRecordProcessors`. Used to keep web
+   * vitals histograms landing on the BetterStack-fronting OTel
+   * collector after the rum.ts → SDK migration moved the primary path
+   * to `/v2/sink` (Tinybird-only).
+   */
+  _internalAdditionalMetricReaders?: MetricReader[];
+  /**
+   * Extra span processors fanned into the WebTracerProvider's processor
+   * list. See `_internalAdditionalLogRecordProcessors`.
+   */
+  _internalAdditionalSpanProcessors?: SpanProcessor[];
+  /** Wrapper SDK versions (e.g. `@interfere/next@10.0.0`). */
+  _wrapperVersions?: string[];
+}
+interface KernelConsent {
+  get(): ConsentState | null;
+  set(value?: ConsentState): void;
+}
+interface KernelIdentity {
+  get(): IdentifyParams | null;
+  set(params: IdentifyParams): Promise<void>;
+}
+interface KernelDevice {
+  getDeviceId(): string | null;
+  getFpHash(): string | null;
+}
+interface KernelSession {
+  getId(): SessionId | null;
+  getWindowId(): string | null;
+}
+interface RecordExceptionOpts {
+  /**
+   * Frames always appended to the first exception's stack. Used by
+   * `<ErrorBoundary>` to inject React's component-stack frames as
+   * supplementary context — these add on top of the real JS frames, they
+   * don't replace them.
+   */
+  readonly appendFrames?: readonly IngestedFrame[];
+  /**
+   * `error.digest` from React when an RSC server-side throw is
+   * sanitised and rebuilt as a synthetic Error on the client. The only
+   * identifier that pairs the redacted client capture with the
+   * unredacted server capture — enrichment mixes this into the
+   * fingerprint so both events group as one problem.
+   */
+  readonly errorDigest?: string;
+  /**
+   * Frames adopted only when the first exception's parsed stack is empty.
+   * Used by the `window.onerror` handler when the browser hands us
+   * source/line/col but the `Error` itself has a degenerate stack — never
+   * glued on top of a real stack.
+   */
+  readonly fallbackFrames?: readonly IngestedFrame[];
+  readonly mechanism: ErrorMechanism;
+}
+/**
+ * The replacement for the old `Client` god-object. Pure construction graph
+ * via `createKernel`; no module-level mutable state, no global lookups.
+ * Framework wrappers (`@interfere/next`, `@interfere/vite`) own the
+ * singleton lifecycle.
+ *
+ * Implements `PluginContext` directly: plugins are wired with the kernel
+ * itself rather than a closure adapter. The kernel⇄runtime cycle is
+ * resolved by constructing the kernel first and binding the runtime via
+ * `attachRuntime` immediately after.
+ */
+declare class Kernel implements PluginContext {
+  readonly consent: KernelConsent;
+  readonly identity: KernelIdentity;
+  readonly device: KernelDevice;
+  readonly session: KernelSession;
+  private readonly tracker;
+  private readonly seen;
+  private runtime;
+  private otel;
+  private otelDispose;
+  private unsubscribePageHidden;
+  constructor(tracker: SessionTracker);
+  /** @internal Bound by `createKernel` immediately after construction. */
+  attachRuntime(runtime: PluginRuntime): void;
+  private requireRuntime;
+  /** PluginContext shim: plugins expect a non-null string. */
+  getSessionId(): string;
+  /**
+   * Records an exception event on the active OTel span. No envelope
+   * path — the SDK is OTel-only. Single dedup boundary: drops repeats
+   * of the same `Error` instance, plus browser-extension noise and
+   * unresolvable stacks. Upstream callers (the errors plugin's
+   * `window.onerror` / `console.error` / `unhandledrejection`, the
+   * React error boundary) just call this — they don't pre-filter.
+   *
+   * Does NOT mark the active span as failed. A console.error inside a
+   * customer-owned `span()` block would otherwise taint the customer's
+   * span even when the customer caught the error explicitly. The
+   * customer's `span()` helper sets status itself when it observes a
+   * throw.
+   *
+   * `appendFrames` are always appended (component-stack supplements);
+   * `fallbackFrames` are only adopted when the parsed stack is empty
+   * (`window.onerror` source/line/col when the Error has no usable
+   * stack). Both ride on the serialised `interfere.exception.chain`
+   * attribute when the chain is non-trivial.
+   */
+  recordException(value: Error | NonErrorException, opts: RecordExceptionOpts): void;
+  /**
+   * Emits an OTel `LogRecord` via the kernel's logger provider. Used by
+   * `plugins/logs.ts` to capture string-only `console.*` calls (the
+   * errors plugin still owns Error-bearing console calls — class
+   * boundary). No-ops when OTel is not wired (`tracing: false`) since
+   * there's no logger provider to emit through.
+   */
+  recordLog(input: {
+    severityText: string;
+    severityNumber: number;
+    body: string;
+    attributes?: Record<string, string>;
+  }): void;
+  /**
+   * Force-flushes the OTel exporters. Returns once they've settled
+   * (success or failure) so callers driving unload — page-lifecycle
+   * handlers, integration test teardown — can actually await
+   * completion. The OTel SDK swallows export errors internally; we
+   * surface the resolution either way.
+   */
+  flush(): Promise<void>;
+  /**
+   * @internal Wired by `createKernel` after the OTel module has been
+   * lazy-loaded. Held on the kernel so `flush()` and `dispose()` can fan
+   * out to the providers. The tracer/meter providers stay private —
+   * customers don't get raw OTel access; the public surface is the
+   * `span()` / `capture()` helpers in `api.ts`.
+   */
+  attachOtel(handle: OtelProviderHandle, dispose: () => void): void;
+  /**
+   * Provider-driven consent sync. Pass `undefined` to clear consent (treats
+   * the prop as "unmanaged"); pass a state to apply it.
+   */
+  syncConsent(value: ConsentState | undefined): void;
+  dispose(): Promise<void>;
+}
+interface CreateKernelInput {
+  opts?: KernelInternalOptions;
+}
+/**
+ * Pure construction graph. Awaits the remote-config fetch before resolving,
+ * so the runtime sees a fully-applied config before any capture is attempted
+ * by the caller. Removes the capture-before-config race the old `Client`
+ * had.
+ */
+declare function createKernel(input?: CreateKernelInput): Promise<Kernel>;
+declare function isEnabledByEnvironment(): boolean;
+/**
+ * Build-time-derived release slug. The build step
+ * (`@interfere/next/withInterfere`, `@interfere/vite/plugin`) takes the
+ * leading 16 hex chars of the commit SHA (`rel_<16hex>`) and stamps it into
+ * the bundle as `__INTERFERE_RELEASE_SLUG__`. The collector derives the same
+ * value from the create-release request, so the bundle's runtime slug is
+ * guaranteed to match the row without a round-trip.
+ *
+ * Returns `null` when no slug was injected (dev builds, customers who
+ * haven't wired up the plugin).
+ */
+declare function readReleaseSlugFromGlobals(): ReleaseSlug | null;
+//#endregion
+export { Kernel, KernelConsent, KernelDevice, KernelIdentity, KernelInternalOptions, KernelOptions, KernelSession, RecordExceptionOpts, TracingOptions, buildSdkStack, createKernel, isEnabledByEnvironment, readReleaseSlugFromGlobals };

package/dist/internal/kernel.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kernel.d.mts","names":[],"sources":["../../src/internal/kernel.ts"],"mappings":";;;;;;;;;;;;;;;;;iBAyCgB,aAAA,CAAc,eAAA;AAAA,UAyDb,aAAA;EACf,OAAA,GAAU,YAAA;EA1DI;;;;;AAyDhB;;EASE,OAAA;EARU;EAUV,KAAA,UAAe,UAAA,CAAW,KAAA;EAC1B,OAAA,GAAU,eAAA;EAgBU;;;;;;;EARpB,WAAA;EAT0B;;;;;;;EAiB1B,OAAA,aAAoB,cAAA;AAAA;;;;;;;UASL,cAAA;EAsBf;;;;;AAgBF;EA/BE,UAAA,aAAuB,MAAA;;;;;;;EAOvB,oBAAA,aAAiC,MAAA;EAwBY;;;;;;;EAhB7C,YAAA,IAAgB,QAAA;EAuCA;;AAGlB;;;EApCE,SAAA;AAAA;;;;;;;AAyCF;UA/BiB,qBAAA,SAA8B,aAAA;;;;;;;;EAQ7C,sCAAA,GAAyC,kBAAA;EAyBzC;;;;;;AAGF;EApBE,gCAAA,GAAmC,YAAA;;;;AAyBrC;EApBE,iCAAA,GAAoC,aAAA;;EAEpC,gBAAA;AAAA;AAAA,UAGe,aAAA;EACf,GAAA,IAAO,YAAA;EACP,GAAA,CAAI,KAAA,GAAQ,YAAA;AAAA;AAAA,UAGG,cAAA;EACf,GAAA,IAAO,cAAA;EACP,GAAA,CAAI,MAAA,EAAQ,cAAA,GAAiB,OAAA;AAAA;AAAA,UAGd,YAAA;EACf,WAAA;EACA,SAAA;AAAA;AAAA,UAGe,aAAA;EACf,KAAA,IAAS,SAAA;EACT,WAAA;AAAA;AAAA,UAGe,mBAAA;EAuBN;;;;AAcX;;EAdW,SAhBA,YAAA,YAAwB,aAAA;EA+Bf;;;;;;;EAAA,SAvBT,WAAA;EA0HD;;;;;;EAAA,SAnHC,cAAA,YAA0B,aAAA;EAAA,SAC1B,SAAA,EAAW,cAAA;AAAA;;;;;;;;;;;;cAcT,MAAA,YAAkB,aAAA;EAAA,SACpB,OAAA,EAAS,aAAA;EAAA,SACT,QAAA,EAAU,cAAA;EAAA,SACV,MAAA,EAAQ,YAAA;EAAA,SACR,OAAA,EAAS,aAAA;EAAA,iBAED,OAAA;EAAA,iBAGA,IAAA;EAAA,QAKT,OAAA;EAAA,QACA,IAAA;EAAA,QACA,WAAA;EAAA,QACA,qBAAA;cAEI,OAAA,EAAS,cAAA;EA+ErB;EAtCA,aAAA,CAAc,OAAA,EAAS,aAAA;EAAA,QAIf,cAAA;EAmCN;EAzBF,YAAA,CAAA;EA0BE;;;;;;;;;;;;;;;;;;;;EAFF,eAAA,CACE,KAAA,EAAO,KAAA,GAAQ,iBAAA,EACf,IAAA,EAAM,mBAAA;EA6HA;;;;;AAUV;;EAlFE,SAAA,CAAU,KAAA;IACR,YAAA;IACA,cAAA;IACA,IAAA;IACA,UAAA,GAAa,MAAA;EAAA;EA+ER;;;;;;AA6PT;EAxTQ,KAAA,CAAA,GAAS,OAAA;;;;AAiVjB;;;;EApUE,UAAA,CAAW,MAAA,EAAQ,kBAAA,EAAoB,OAAA;;;;;EASvC,WAAA,CAAY,KAAA,EAAO,YAAA;EASb,OAAA,CAAA,GAAW,OAAA;AAAA;AAAA,UAiBT,iBAAA;EACR,IAAA,GAAO,qBAAA;AAAA;;;;;;;iBASa,YAAA,CACpB,KAAA,GAAO,iBAAA,GACN,OAAA,CAAQ,MAAA;AAAA,iBA4PK,sBAAA,CAAA;;;;;;;;;;;;iBAyBA,0BAAA,CAAA,GAA8B,WAAA"}