@flareapp/core 2.10.0 → 2.12.0

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { $ as TracesSampler, A as BufferedLog, B as OtelLogRecord, D as AnyValue, E as assert, F as Framework, G as SdkInfo, H as OverriddenGrouping, I as Glow, J as SpanOptions, K as Span, L as KeyValue, M as Config, N as EntryPointHandler, O as AttributeValue, P as EntryPointType, Q as TracesEnvelope, R as LogsEnvelope, S as convertToError, T as assertKey, U as Report, V as OtelSpan, W as SamplingContext, X as SpanStatusCode, Y as SpanStatus, Z as StackFrame, _ as glowsToEvents, a as SafeCloneOptions, b as SdkTaggable, c as describeRejectionReason, d as redactObjectValues, et as User, f as redactUrlQuery, h as now, it as FrameworkName, j as BufferedSpan, k as Attributes, l as routeRejection, m as safeDecode, n as urlAttributes, nt as BrowserSpanType, o as safeClone, p as resolveDenylist, q as SpanEvent, r as toCustomContext, rt as SpanTypeName, s as RejectionReporter, tt as BrowserSpanEventType, u as DEFAULT_URL_DENYLIST, v as flatJsonStringify, x as createIdentityTagger, y as extractCode, z as MessageLevel } from "./urlAttributes-CYsfTfi9.mjs";
+import { $ as StackFrame, A as AttributeValue, B as LogsEnvelope, C as createIdentityTagger, D as assertKey, F as EntryPointHandler, G as Report, H as OtelLogRecord, I as EntryPointType, J as Span, K as SamplingContext, L as Framework, M as BufferedLog, N as BufferedSpan, O as assert, P as Config, Q as SpanStatusCode, R as Glow, S as SdkTaggable, U as OtelSpan, V as MessageLevel, W as OverriddenGrouping, X as SpanOptions, Y as SpanEvent, Z as SpanStatus, at as SpanTypeName, b as extractCode, c as RejectionReporter, d as DEFAULT_URL_DENYLIST, et as TracesEnvelope, f as redactObjectValues, g as now, h as safeDecode, it as BrowserSpanType, j as Attributes, k as AnyValue, l as describeRejectionReason, m as resolveDenylist, n as urlAttributes, nt as User, o as SafeCloneOptions, ot as FrameworkName, p as redactUrlQuery, q as SdkInfo, r as toCustomContext, rt as BrowserSpanEventType, s as safeClone, tt as TracesSampler, u as routeRejection, v as glowsToEvents, w as convertToError, x as evictLruIfNew, y as flatJsonStringify, z as KeyValue } from "./urlAttributes-rWoVW31H.mjs";
 
 //#region src/api/Api.d.ts
 declare class Api {
@@ -6,8 +6,7 @@ declare class Api {
   private pendingKeepaliveRequests;
   /**
    * How many keepalive bytes are still available. Logs and traces share one browser allowance and both
-   * flush on page hide, so whichever goes second has to pack against what is left rather than assume the
-   * whole budget, or it exceeds the gate in send() and silently degrades to a cancellable fetch.
+   * flush on page hide, so whichever goes second must pack against what is left, not the whole budget.
    */
   keepaliveBudgetRemaining(): number;
   report(report: Report, url: string, key: string | null, reportBrowserExtensionErrors: boolean, debug?: boolean): Promise<void>;
@@ -127,14 +126,13 @@ declare function readLinesFromFile(fileText: string, lineNumber: number, columnN
 interface ActiveSpanHolder {
   getActive(): Span | undefined;
   /**
-   * Run `fn` with `span` active, restoring the prior active span afterward. A callback (not a bare setter) so a Node
-   * holder can back it with AsyncLocalStorage.run(...) to preserve async-scoped context.
+   * Runs `fn` with `span` active, then restores the previous active span. Takes a callback, not a
+   * setter, so a Node holder can implement it with `AsyncLocalStorage.run(...)`.
    */
   withActive<T>(span: Span, fn: () => T): T;
   /**
-   * Persistent "active root" that getActive() falls back to when no withActive scope is on the stack. Used by
-   * long-lived pageload/navigation roots so child spans (e.g. fetches) auto-parent to them. Optional; a holder that
-   * omits it simply has no active-root support.
+   * Fallback span that getActive() returns when no withActive scope is active. Long-lived
+   * pageload/navigation roots use it so child spans auto-parent to them. Optional.
    */
   setActiveRoot?(span: Span | undefined): void;
 }
@@ -187,10 +185,9 @@ declare class Tracer {
   getActiveSpan(): Span | undefined;
   setActiveRoot(span?: Span): void;
   /**
-   * Take one span against `traceId`'s cap up front, for a caller that publishes a span id before the
-   * span exists (the component profilers do; their descendants record first). False means the trace is
-   * full and the caller should stay transparent instead of handing out an id the cap will refuse.
-   * Consumed by the matching `startSpan({ claimed: true })`.
+   * Claims a span slot before the span exists, for a caller that publishes a span id early (the
+   * component profilers do; their descendants record first). Returns false when the trace is full.
+   * Paired with `startSpan({ claimed: true })`.
    */
   claimSpanSlot(traceId: string): boolean;
   addSpanListener(fn: SpanLifecycleListener): () => void;
@@ -201,20 +198,20 @@ declare class Tracer {
   clear(): void;
   continueFromTraceparent(header: string): void;
   /**
-   * Runs `fn` with the span active, so spans started inside auto-parent to it, then ends it.
+   * Runs `fn` with the span active, so spans started inside it auto-parent to it, then ends the span.
    * Records an error status first if `fn` throws or its returned promise rejects.
    */
   withSpan<T>(name: string, fn: (span: Span) => T, opts?: SpanOptions): T;
-  /** Starts a span the caller must end. Unlike `withSpan`, it does not become the active span,
-   *  so spans started after it do not auto-parent to it. */
+  /**
+   * Starts a span the caller must end. Unlike `withSpan`, it does not become the active span, so spans
+   * started after it do not auto-parent to it.
+   */
   startSpan(name: string, opts?: SpanOptions): Span;
-  /** A real Span handle that records nothing, so callers never have to branch on whether tracing is on. */
   private startInertSpan;
   private resolveTrace;
   private getOrSeedState;
   private createState;
   private makeSpan;
-  /** Bounded, LRU by insertion order, like traceStates. Holds primitives only, never a span. */
   private rememberClosed;
   private onSpanEnd;
 }
@@ -246,22 +243,13 @@ declare class Flare {
    *                         default; a platform can back it with AsyncLocalStorage instead.
    */
   constructor(api?: Api, contextCollector?: ContextCollector, fileReader?: FileReader, scopeProvider?: ScopeProvider, scheduler?: FlushScheduler, activeSpanHolder?: ActiveSpanHolder);
-  /**
-   * Register an in-flight report so `flush()` can wait for it. Every entry point wraps its whole async
-   * pipeline, from beforeEvaluate through api.report, so flush() waits on all of it.
-   *
-   * What goes in the Set is a shadow promise that mirrors `p`'s timing but cannot reject, so a failed
-   * report never surfaces as an unhandled rejection warning. `p` itself is returned untouched, so the
-   * caller still observes real success or failure.
-   */
   private track;
   /**
-   * Wait until every in-flight report settles or `timeoutMs` elapses. Always resolves, never rejects.
-   * Written for `@flareapp/node`'s fatal handler, which awaits the fatal report itself then flushes to
-   * drain any other concurrent reports before `process.exit`.
+   * Waits until every in-flight report settles, or `timeoutMs` elapses. Always resolves, never rejects.
+   * Used by `@flareapp/node`'s fatal handler to drain other reports before `process.exit`.
    *
-   * Snapshotting the Set bounds the wait: reports started after this line are not awaited, so a handler
-   * that keeps emitting during shutdown cannot block the process forever. Call flush again for those.
+   * Only reports already in flight are awaited, so a handler still emitting during shutdown cannot block
+   * forever. Call flush again to catch those.
    */
   flush(timeoutMs?: number): Promise<void>;
   get config(): Readonly<Config>;
@@ -298,10 +286,6 @@ declare class Flare {
   setEntryPoint(handler: EntryPointHandler): this;
   setSdkInfo(info: SdkInfo): this;
   setFramework(framework: Framework): this;
-  /**
-   * True when a report must not be captured: consent withdrawn, or dropped by sampling. Consent is
-   * checked first, so a blocked report never runs the sampler or assembles a report (no cookie read).
-   */
   private shouldSkipCapture;
   report(error: Error, attributes?: Attributes): Promise<void>;
   private reportInternal;
@@ -314,15 +298,6 @@ declare class Flare {
   private buildBaseAttributes;
   private assembleAttributes;
   private buildLogAttributes;
-  /**
-   * Local roots only, snapshotted by the Tracer at span START so a long-lived root does not drift into
-   * the next page's scope. Children get none, and no span ever runs the DOM collector.
-   *
-   * Everything assembled is inherited except user identity (excluding the opaque `user.id`): a root span
-   * goes out for every page view, so email, full name, IP and `user.attributes` would turn normal
-   * browsing into PII traffic. The rest — `context.custom`, `addContextGroup` bags — stays in, because
-   * the trace viewer renders any span attribute whose key does not start with `flare.`.
-   */
   private getScopeAttributes;
   private spanResourceAttributes;
   private buildReport;
@@ -350,17 +325,74 @@ declare function spanId(): string;
 //#endregion
 //#region src/stacktrace/NullFileReader.d.ts
 /**
- * No-op `FileReader` returning `null` for every URL. Default for `Flare`'s `fileReader` param so `new Flare()` builds
- * reports without picking an environment; stack frames just omit source snippets. Consumer packages inject the real
- * ones: `@flareapp/js` a fetch-based reader, `@flareapp/node` a disk reader. The `read(url) -> Promise<string | null>`
- * interface lets the stack-trace builder treat all three the same (render on text, skip on null), so core needs no
- * environment checks.
+ * No-op `FileReader` returning `null` for every URL. Default for `Flare`'s `fileReader` param, so
+ * `new Flare()` builds reports without picking an environment; stack frames just omit source snippets.
+ * `@flareapp/js` and `@flareapp/node` inject a real fetch- or disk-based reader instead.
  */
 declare class NullFileReader implements FileReader {
   read(_url: string): Promise<string | null>;
 }
 //#endregion
+//#region src/device/types.d.ts
+/** Effective connection quality. The API never reports 5g: a 5g device reports '4g'. */
+type EffectiveConnectionType = 'slow-2g' | '2g' | '3g' | '4g';
+/** Normalised device info. Every field optional: each provider fills what it reads, the mapper drops the rest. */
+type DeviceInfo = {
+  os?: {
+    name?: string;
+    version?: string;
+  };
+  runtime?: {
+    name?: string;
+    version?: string;
+  };
+  device?: {
+    type?: string;
+    model?: string;
+    memoryGb?: number;
+    cpuCores?: number;
+    screen?: {
+      width?: number;
+      height?: number;
+      scale?: number;
+    };
+  };
+  network?: {
+    effectiveType?: EffectiveConnectionType;
+    downlinkMbps?: number;
+    rttMs?: number;
+    online?: boolean;
+  };
+  app?: {
+    version?: string;
+    id?: string;
+  };
+  locale?: {
+    language?: string;
+    timezone?: string;
+  };
+};
+//#endregion
+//#region src/device/DeviceInfoProvider.d.ts
+/** The seam each platform implements to read device info. A `ContextCollector` maps it with `deviceInfoToAttributes`. */
+interface DeviceInfoProvider {
+  collect(): DeviceInfo;
+}
+/** Default for platforms with no device info. */
+declare class NullDeviceInfoProvider implements DeviceInfoProvider {
+  collect(): DeviceInfo;
+}
+//#endregion
+//#region src/device/deviceInfoToAttributes.d.ts
+/** Map `DeviceInfo` to wire attributes: flat keys plus a `context.device` card. Shared by every SDK, so keys never drift. */
+declare function deviceInfoToAttributes(info: DeviceInfo): Attributes;
+/**
+ * `context.device` card for the error UI. Rendered one level deep, so values stay scalar. Built only when
+ * a device or network signal exists (an os-only Node report gets none).
+ */
+declare function buildDeviceContextGroup(info: DeviceInfo): Record<string, AttributeValue>;
+//#endregion
 //#region src/stacktrace/createStackTrace.d.ts
 declare function createStackTrace(error: Error, debug: boolean, fileReader: FileReader): Promise<Array<StackFrame>>;
 //#endregion
-export { type ActiveSpanHolder, type AnyValue, Api, type AttributeValue, type Attributes, BrowserSpanEventType, BrowserSpanType, type BufferedLog, type BufferedSpan, type Config, type ContextCollector, DEFAULT_MAX_LIVE_TRACES, DEFAULT_URL_DENYLIST, type EntryPointHandler, type EntryPointType, type FileReader, Flare, type FlushFn, type FlushScheduler, type Framework, FrameworkName, GlobalScopeProvider, type Glow, InMemoryActiveSpanHolder, type KeyValue, Logger, type LoggerDeps, type LogsEnvelope, MAX_BREADCRUMB_URL_LENGTH, type MessageLevel, NoopFlushScheduler, NullFileReader, type OtelLogRecord, type OtelSpan, type OverriddenGrouping, type RejectionReporter, type Report, type SafeCloneOptions, type SamplingContext, Scope, type ScopeProvider, type SdkInfo, type SdkTaggable, type Span, type SpanEvent, type SpanLifecycleEvent, type SpanLifecycleListener, type SpanOptions, type SpanPhase, type SpanStatus, SpanStatusCode, type SpanTypeName, type StackFrame, Tracer, type TracerDeps, type TracesEnvelope, type TracesSampler, USER_IDENTITY_KEYS, type User, assert, assertKey, breadcrumbUrl, buildTraceparent, buildTracesEnvelope, convertToError, createIdentityTagger, createStackTrace, defaultNowNano, describeRejectionReason, extractCode, flatJsonStringify, getCodeSnippet, glowsToEvents, now, parseTraceparent, readLinesFromFile, recordBreadcrumb, redactObjectValues, redactUrlQuery, resolveDenylist, routeRejection, safeClone, safeDecode, spanId, toCustomContext, urlAttributes, userIdentityAttributes };
+export { type ActiveSpanHolder, type AnyValue, Api, type AttributeValue, type Attributes, BrowserSpanEventType, BrowserSpanType, type BufferedLog, type BufferedSpan, type Config, type ContextCollector, DEFAULT_MAX_LIVE_TRACES, DEFAULT_URL_DENYLIST, type DeviceInfo, type DeviceInfoProvider, type EffectiveConnectionType, type EntryPointHandler, type EntryPointType, type FileReader, Flare, type FlushFn, type FlushScheduler, type Framework, FrameworkName, GlobalScopeProvider, type Glow, InMemoryActiveSpanHolder, type KeyValue, Logger, type LoggerDeps, type LogsEnvelope, MAX_BREADCRUMB_URL_LENGTH, type MessageLevel, NoopFlushScheduler, NullDeviceInfoProvider, NullFileReader, type OtelLogRecord, type OtelSpan, type OverriddenGrouping, type RejectionReporter, type Report, type SafeCloneOptions, type SamplingContext, Scope, type ScopeProvider, type SdkInfo, type SdkTaggable, type Span, type SpanEvent, type SpanLifecycleEvent, type SpanLifecycleListener, type SpanOptions, type SpanPhase, type SpanStatus, SpanStatusCode, type SpanTypeName, type StackFrame, Tracer, type TracerDeps, type TracesEnvelope, type TracesSampler, USER_IDENTITY_KEYS, type User, assert, assertKey, breadcrumbUrl, buildDeviceContextGroup, buildTraceparent, buildTracesEnvelope, convertToError, createIdentityTagger, createStackTrace, defaultNowNano, describeRejectionReason, deviceInfoToAttributes, evictLruIfNew, extractCode, flatJsonStringify, getCodeSnippet, glowsToEvents, now, parseTraceparent, readLinesFromFile, recordBreadcrumb, redactObjectValues, redactUrlQuery, resolveDenylist, routeRejection, safeClone, safeDecode, spanId, toCustomContext, urlAttributes, userIdentityAttributes };

package/dist/index.mjs

@@ -1,13 +1,13 @@
-import { D as CLIENT_VERSION, E as assert, O as KEY, S as convertToError, T as assertKey, _ as TRUNCATED, a as routeRejection, b as extractCode, c as redactUrlQuery, d as now, f as timelineEvents, g as MAX_TRAVERSAL_DEPTH, h as safeClone, i as describeRejectionReason, k as SOURCEMAP_VERSION, l as resolveDenylist, m as flatJsonStringify, n as urlAttributes, o as DEFAULT_URL_DENYLIST, p as glowsToEvents, r as toCustomContext, s as redactObjectValues, u as safeDecode, v as createTraversalBudget, x as createIdentityTagger, y as spendNode } from "./urlAttributes-DeDN7qtu.mjs";
+import { A as KEY, C as createIdentityTagger, D as assertKey, O as assert, S as evictLruIfNew, _ as MAX_TRAVERSAL_DEPTH, a as describeRejectionReason, b as spendNode, c as redactObjectValues, d as safeDecode, f as now, g as safeClone, h as flatJsonStringify, i as setDefined, j as SOURCEMAP_VERSION, k as CLIENT_VERSION, l as redactUrlQuery, m as glowsToEvents, n as urlAttributes, o as routeRejection, p as timelineEvents, r as toCustomContext, s as DEFAULT_URL_DENYLIST, u as resolveDenylist, v as TRUNCATED, w as convertToError, x as extractCode, y as createTraversalBudget } from "./urlAttributes-ggdpIKSS.mjs";
 import ErrorStackParser from "error-stack-parser";
 
 //#region src/framework.ts
 /**
-* Framework names the Flare backend recognises. Wire format, so the values never change: they ship as
-* `flare.framework.name` and (lowercased) as `context.custom.framework`.
+* Framework names the Flare backend recognizes. Wire format: these values never change, since they
+* ship as `flare.framework.name` and (lowercased) as `context.custom.framework`.
 *
-* `Js` and `Node` are the base SDKs' fallback claim, overwritten when a framework package tags its
-* own name. `NodeElectron` is an Electron main process; its renderers report their own.
+* `Js` and `Node` are fallback claims from the base SDKs, overwritten when a framework package sets
+* its own name. `NodeElectron` is the Electron main process; renderers report their own name.
 */
 const FrameworkName = {
 	Js: "js",
@@ -23,7 +23,7 @@ const FrameworkName = {
 //#endregion
 //#region src/spanTypes.ts
 /**
-* Span types the Flare backend recognises. Wire format, so the values never change: they ship as the
+* Span types the Flare backend recognizes. Wire format, so the values never change: they ship as the
 * `flare.span_type` attribute and the backend groups performance data by them.
 *
 * These are the browser client's set. They live in core because core's `SpanOptions.spanType` needs
@@ -37,6 +37,10 @@ const BrowserSpanType = {
 	Component: "browser_component",
 	WebVital: "browser_web_vital"
 };
+/**
+* Span event types on an error report. Kept apart from `BrowserSpanType`: these are points in time,
+* not spans with a duration. That is also why a route change is not called `browser_navigation`.
+*/
 const BrowserSpanEventType = {
 	Click: "browser_click",
 	Input: "browser_input",
@@ -55,7 +59,6 @@ const SpanStatusCode = {
 //#endregion
 //#region src/util/utf8Bytes.ts
 const textEncoder = new TextEncoder();
-/** UTF-8 byte length of `value`. */
 function utf8Bytes(value) {
 	return textEncoder.encode(value).length;
 }
@@ -69,8 +72,7 @@ var Api = class {
 	pendingKeepaliveRequests = 0;
 	/**
 	* How many keepalive bytes are still available. Logs and traces share one browser allowance and both
-	* flush on page hide, so whichever goes second has to pack against what is left rather than assume the
-	* whole budget, or it exceeds the gate in send() and silently degrades to a cancellable fetch.
+	* flush on page hide, so whichever goes second must pack against what is left, not the whole budget.
 	*/
 	keepaliveBudgetRemaining() {
 		if (this.pendingKeepaliveRequests >= MAX_PENDING_KEEPALIVE_REQUESTS) return 0;
@@ -170,11 +172,6 @@ function recordBreadcrumb(scopeProvider, config, type, attributes, startTimeUnix
 
 //#endregion
 //#region src/telemetry/TelemetryBuffer.ts
-/**
-* The batching machine behind both telemetry signals: hold records, ship them when a size, weight or time
-* trigger fires, and shed the oldest when nothing can drain. One instance owns one signal; what that signal
-* is comes entirely from the policy.
-*/
 var TelemetryBuffer = class {
 	entries = [];
 	bufferedBytes = 0;
@@ -284,11 +281,6 @@ var TelemetryBuffer = class {
 			if (dropped) this.bufferedBytes -= dropped.bytes;
 		}
 	}
-	/**
-	* Newest-wins. An over-budget record is skipped, not a stop signal, so a smaller older record behind a fat
-	* one still ships. Runs on visibilitychange:hidden, which fires on plain backgrounding too, so the tail this
-	* leaves behind is retained and re-armed rather than dropped (see flush).
-	*/
 	packForKeepalive(config, resource) {
 		const fixedBytes = this.policy.emptyEnvelopeBytes(resource);
 		const budget = Math.min(config.keepaliveMaxBytes, this.policy.keepaliveBudget?.(config) ?? config.keepaliveMaxBytes);
@@ -317,11 +309,6 @@ var TelemetryBuffer = class {
 
 //#endregion
 //#region src/telemetry/resourceIdentity.ts
-/**
-* Builds the attributes that go on every logs or traces envelope: the caller's own attributes in `base`, with
-* our SDK, service and framework identity on top. Our keys win, so a user value cannot overwrite something
-* like `telemetry.sdk.name`.
-*/
 function buildResourceIdentity(base, config, sdk, framework) {
 	const identity = {
 		"telemetry.sdk.language": "javascript",
@@ -342,18 +329,6 @@ function buildResourceIdentity(base, config, sdk, framework) {
 
 //#endregion
 //#region src/logging/otel.ts
-/**
-* Converts one attribute value into the OpenTelemetry `AnyValue` shape. Strings, numbers and booleans become
-* leaves, arrays and objects are walked recursively. Anything OpenTelemetry cannot carry (null, undefined,
-* NaN, functions) returns null and the caller drops that key.
-*
-* A value that contains itself becomes the string `[Circular]`. `inPath` only holds the parents of the value
-* being converted right now, so the same object used twice side by side is converted twice instead of being
-* wrongly called circular.
-*
-* The walk also stops at a maximum depth and a maximum number of nodes, see traversalBudget.ts. Pass `budget`
-* to let several calls share one allowance, otherwise every call gets its own.
-*/
 function valueToOpenTelemetry(value, inPath = /* @__PURE__ */ new WeakSet(), budget = createTraversalBudget()) {
 	return convert(value, inPath, 0, budget);
 }
@@ -438,17 +413,9 @@ function buildLogsEnvelope(records, resourceAttributes, scopeName, scopeVersion)
 		}]
 	}] };
 }
-/**
-* How many UTF-8 bytes one record adds to an envelope. We measure the real toOtelLogRecord output instead of
-* reusing the cached BufferedLog estimate, because keepaliveMaxBytes is a hard browser limit and an estimate
-* is not good enough.
-*
-* Uses flatJsonStringify to match Api.logs, which sends the envelope through the same encoder.
-*/
 function otelLogRecordBytes(record) {
 	return utf8Bytes(flatJsonStringify(toOtelLogRecord(record)));
 }
-/** UTF-8 bytes of an empty envelope: the fixed overhead every batch has, before any records are added. */
 function emptyLogsEnvelopeBytes(resourceAttributes, scopeName, scopeVersion) {
 	return utf8Bytes(flatJsonStringify(buildLogsEnvelope([], resourceAttributes, scopeName, scopeVersion)));
 }
@@ -589,6 +556,8 @@ const RESOURCE_PREFIXES = [
 	"host.",
 	"os.",
 	"process.",
+	"device.",
+	"network.",
 	"flare.framework.",
 	"flare.language."
 ];
@@ -606,7 +575,6 @@ function partitionAttributes(attributes) {
 
 //#endregion
 //#region src/Scope.ts
-/** `USER_IDENTITY_KEYS` derives from this, so adding a field here can never leave the clear pass stale. */
 const USER_FIELD_KEYS = {
 	id: "user.id",
 	email: "user.email",
@@ -786,11 +754,9 @@ function isApplicationFrame(fileName) {
 //#endregion
 //#region src/stacktrace/NullFileReader.ts
 /**
-* No-op `FileReader` returning `null` for every URL. Default for `Flare`'s `fileReader` param so `new Flare()` builds
-* reports without picking an environment; stack frames just omit source snippets. Consumer packages inject the real
-* ones: `@flareapp/js` a fetch-based reader, `@flareapp/node` a disk reader. The `read(url) -> Promise<string | null>`
-* interface lets the stack-trace builder treat all three the same (render on text, skip on null), so core needs no
-* environment checks.
+* No-op `FileReader` returning `null` for every URL. Default for `Flare`'s `fileReader` param, so
+* `new Flare()` builds reports without picking an environment; stack frames just omit source snippets.
+* `@flareapp/js` and `@flareapp/node` inject a real fetch- or disk-based reader instead.
 */
 var NullFileReader = class {
 	read(_url) {
@@ -976,28 +942,15 @@ function buildTracesEnvelope(spans, resourceAttributes, scopeName, scopeVersion)
 		}]
 	}] };
 }
-/**
-* How many UTF-8 bytes one span adds to an envelope. We measure the real toOtelSpan output instead of reusing
-* the cached BufferedSpan estimate, because keepaliveMaxBytes is a hard browser limit and an estimate is not
-* good enough.
-*
-* We use flatJsonStringify instead of JSON.stringify because a span keeps values the caller still owns, like
-* status.message, and those can turn unserializable after the span ended. This runs from a visibilitychange
-* listener with no try/catch around it, so a throw here loses the flush. flatJsonStringify handles the usual
-* suspects (circular references, BigInt, a getter that throws on a plain object) but is not bulletproof: a
-* class instance with a throwing getter goes through untouched and can still throw.
-*/
 function otelSpanBytes(span) {
 	return utf8Bytes(flatJsonStringify(toOtelSpan(span)));
 }
-/** UTF-8 bytes of an empty envelope: the fixed overhead every batch has, before any spans are added. */
 function emptyTracesEnvelopeBytes(resourceAttributes, scopeName, scopeVersion) {
 	return utf8Bytes(JSON.stringify(buildTracesEnvelope([], resourceAttributes, scopeName, scopeVersion)));
 }
 
 //#endregion
 //#region src/tracing/SpanBuffer.ts
-/** The span half of the shared telemetry buffer: names the config keys, the envelope and the ingest call. */
 var SpanBuffer = class {
 	inner;
 	constructor(deps) {
@@ -1082,11 +1035,9 @@ function parseTraceparent(header) {
 function isPromiseLike(value) {
 	return (typeof value === "object" || typeof value === "function") && value !== null && typeof value.then === "function";
 }
-/** `SpanOptions.parent` is a structurally overlapping union; `isRecording` is what tells a real Span apart. */
 function isSpan(parent) {
 	return "isRecording" in parent;
 }
-/** A SpanImpl carries the epoch it was created under; a hand-stitched `{traceId, spanId}` parent does not. */
 function hasEpoch(parent) {
 	return "epoch" in parent && typeof parent.epoch === "number";
 }
@@ -1095,16 +1046,6 @@ function defaultNowNano() {
 	const ms = performanceApi && typeof performanceApi.now === "function" && typeof performanceApi.timeOrigin === "number" ? performanceApi.timeOrigin + performanceApi.now() : Date.now();
 	return Math.round(ms * 1e6);
 }
-/**
-* Both trace maps cap their size the same way: insertion order is LRU, so the first key is the one to drop.
-* Only evicts when `key` is not already in the map. A set() that overwrites an existing key does not grow the
-* map, so it must not evict an unrelated entry to make room for it.
-*/
-function evictLruIfNew(map, key, cap) {
-	if (map.has(key) || map.size < cap) return;
-	const lru = map.keys().next().value;
-	if (lru !== void 0) map.delete(lru);
-}
 const MAX_CLOSED_TRACES = 100;
 /** Bounded backstop for the live TraceState map: an app that never ends spans must not grow it forever. */
 const DEFAULT_MAX_LIVE_TRACES = 1e3;
@@ -1143,10 +1084,9 @@ var Tracer = class {
 		this.holder.setActiveRoot?.(span);
 	}
 	/**
-	* Take one span against `traceId`'s cap up front, for a caller that publishes a span id before the
-	* span exists (the component profilers do; their descendants record first). False means the trace is
-	* full and the caller should stay transparent instead of handing out an id the cap will refuse.
-	* Consumed by the matching `startSpan({ claimed: true })`.
+	* Claims a span slot before the span exists, for a caller that publishes a span id early (the
+	* component profilers do; their descendants record first). Returns false when the trace is full.
+	* Paired with `startSpan({ claimed: true })`.
 	*/
 	claimSpanSlot(traceId) {
 		const config = this.deps.getConfig();
@@ -1185,7 +1125,7 @@ var Tracer = class {
 		this.pendingContinuation = parseTraceparent(header);
 	}
 	/**
-	* Runs `fn` with the span active, so spans started inside auto-parent to it, then ends it.
+	* Runs `fn` with the span active, so spans started inside it auto-parent to it, then ends the span.
 	* Records an error status first if `fn` throws or its returned promise rejects.
 	*/
 	withSpan(name, fn, opts = {}) {
@@ -1215,8 +1155,10 @@ var Tracer = class {
 			}
 		});
 	}
-	/** Starts a span the caller must end. Unlike `withSpan`, it does not become the active span,
-	*  so spans started after it do not auto-parent to it. */
+	/**
+	* Starts a span the caller must end. Unlike `withSpan`, it does not become the active span, so spans
+	* started after it do not auto-parent to it.
+	*/
 	startSpan(name, opts = {}) {
 		const config = this.deps.getConfig();
 		const spanId$1 = opts.spanId ?? spanId();
@@ -1246,7 +1188,6 @@ var Tracer = class {
 		this.emitSpanEvent("start", span);
 		return span;
 	}
-	/** A real Span handle that records nothing, so callers never have to branch on whether tracing is on. */
 	startInertSpan(name, spanId, opts, config) {
 		const span = this.makeSpan({
 			traceId: traceId(),
@@ -1353,7 +1294,6 @@ var Tracer = class {
 		if (opts.attributes) for (const [key, value] of Object.entries(opts.attributes)) span.setAttribute(key, value);
 		return span;
 	}
-	/** Bounded, LRU by insertion order, like traceStates. Holds primitives only, never a span. */
 	rememberClosed(state) {
 		evictLruIfNew(this.closedTraces, state.traceId, MAX_CLOSED_TRACES);
 		this.closedTraces.set(state.traceId, {
@@ -1408,8 +1348,6 @@ var Tracer = class {
 
 //#endregion
 //#region src/Flare.ts
-/** Scope attributes a span never inherits. Derived from `USER_IDENTITY_KEYS` so a future user field is
-*  excluded automatically, without anyone needing to remember to list it here. See `getScopeAttributes`. */
 const SPAN_SCOPE_EXCLUDED_KEYS = USER_IDENTITY_KEYS.filter((key) => key !== USER_FIELD_KEYS.id);
 const DEFAULT_SDK_NAME = "@flareapp/core";
 var Flare = class {
@@ -1494,14 +1432,6 @@ var Flare = class {
 			activeSpanHolder
 		});
 	}
-	/**
-	* Register an in-flight report so `flush()` can wait for it. Every entry point wraps its whole async
-	* pipeline, from beforeEvaluate through api.report, so flush() waits on all of it.
-	*
-	* What goes in the Set is a shadow promise that mirrors `p`'s timing but cannot reject, so a failed
-	* report never surfaces as an unhandled rejection warning. `p` itself is returned untouched, so the
-	* caller still observes real success or failure.
-	*/
 	track(p) {
 		const tracked = p.then(() => void 0, () => void 0);
 		this.inflight.add(tracked);
@@ -1509,12 +1439,11 @@ var Flare = class {
 		return p;
 	}
 	/**
-	* Wait until every in-flight report settles or `timeoutMs` elapses. Always resolves, never rejects.
-	* Written for `@flareapp/node`'s fatal handler, which awaits the fatal report itself then flushes to
-	* drain any other concurrent reports before `process.exit`.
+	* Waits until every in-flight report settles, or `timeoutMs` elapses. Always resolves, never rejects.
+	* Used by `@flareapp/node`'s fatal handler to drain other reports before `process.exit`.
 	*
-	* Snapshotting the Set bounds the wait: reports started after this line are not awaited, so a handler
-	* that keeps emitting during shutdown cannot block the process forever. Call flush again for those.
+	* Only reports already in flight are awaited, so a handler still emitting during shutdown cannot block
+	* forever. Call flush again to catch those.
 	*/
 	flush(timeoutMs = 2e3) {
 		this._logger.flush();
@@ -1661,10 +1590,6 @@ var Flare = class {
 		this.framework = framework;
 		return this;
 	}
-	/**
-	* True when a report must not be captured: consent withdrawn, or dropped by sampling. Consent is
-	* checked first, so a blocked report never runs the sampler or assembles a report (no cookie read).
-	*/
 	shouldSkipCapture() {
 		if (this._config.hasConsent === false) return true;
 		return this._config.sampleRate < 1 && Math.random() >= this._config.sampleRate;
@@ -1789,15 +1714,6 @@ var Flare = class {
 			record: this.assembleAttributes(collectorRecord, userAttributes, false)
 		};
 	}
-	/**
-	* Local roots only, snapshotted by the Tracer at span START so a long-lived root does not drift into
-	* the next page's scope. Children get none, and no span ever runs the DOM collector.
-	*
-	* Everything assembled is inherited except user identity (excluding the opaque `user.id`): a root span
-	* goes out for every page view, so email, full name, IP and `user.attributes` would turn normal
-	* browsing into PII traffic. The rest — `context.custom`, `addContextGroup` bags — stays in, because
-	* the trace viewer renders any span attribute whose key does not start with `flare.`.
-	*/
 	getScopeAttributes() {
 		const scoped = { ...this.assembleAttributes({}, {}, false) };
 		for (const key of SPAN_SCOPE_EXCLUDED_KEYS) delete scoped[key];
@@ -1833,4 +1749,71 @@ var Flare = class {
 };
 
 //#endregion
-export { Api, BrowserSpanEventType, BrowserSpanType, DEFAULT_MAX_LIVE_TRACES, DEFAULT_URL_DENYLIST, Flare, FrameworkName, GlobalScopeProvider, InMemoryActiveSpanHolder, Logger, MAX_BREADCRUMB_URL_LENGTH, NoopFlushScheduler, NullFileReader, Scope, SpanStatusCode, Tracer, USER_IDENTITY_KEYS, assert, assertKey, breadcrumbUrl, buildTraceparent, buildTracesEnvelope, convertToError, createIdentityTagger, createStackTrace, defaultNowNano, describeRejectionReason, extractCode, flatJsonStringify, getCodeSnippet, glowsToEvents, now, parseTraceparent, readLinesFromFile, recordBreadcrumb, redactObjectValues, redactUrlQuery, resolveDenylist, routeRejection, safeClone, safeDecode, spanId, toCustomContext, urlAttributes, userIdentityAttributes };
+//#region src/device/DeviceInfoProvider.ts
+/** Default for platforms with no device info. */
+var NullDeviceInfoProvider = class {
+	collect() {
+		return {};
+	}
+};
+
+//#endregion
+//#region src/device/deviceInfoToAttributes.ts
+/** Map `DeviceInfo` to wire attributes: flat keys plus a `context.device` card. Shared by every SDK, so keys never drift. */
+function deviceInfoToAttributes(info) {
+	const attrs = {};
+	setDefined(attrs, "os.name", info.os?.name);
+	setDefined(attrs, "os.version", info.os?.version);
+	setDefined(attrs, "process.runtime.name", info.runtime?.name);
+	setDefined(attrs, "process.runtime.version", info.runtime?.version);
+	setDefined(attrs, "device.type", info.device?.type);
+	setDefined(attrs, "device.model.name", info.device?.model);
+	setDefined(attrs, "device.memory_gb", info.device?.memoryGb);
+	setDefined(attrs, "device.cpu_cores", info.device?.cpuCores);
+	setDefined(attrs, "device.screen.width", info.device?.screen?.width);
+	setDefined(attrs, "device.screen.height", info.device?.screen?.height);
+	setDefined(attrs, "device.screen.scale", info.device?.screen?.scale);
+	setDefined(attrs, "network.effective_type", info.network?.effectiveType);
+	setDefined(attrs, "network.downlink_mbps", info.network?.downlinkMbps);
+	setDefined(attrs, "network.rtt_ms", info.network?.rttMs);
+	setDefined(attrs, "network.online", info.network?.online);
+	setDefined(attrs, "app.version", info.app?.version);
+	setDefined(attrs, "app.id", info.app?.id);
+	const group = buildDeviceContextGroup(info);
+	if (Object.keys(group).length > 0) attrs["context.device"] = group;
+	return attrs;
+}
+/**
+* `context.device` card for the error UI. Rendered one level deep, so values stay scalar. Built only when
+* a device or network signal exists (an os-only Node report gets none).
+*/
+function buildDeviceContextGroup(info) {
+	if (!hasDeviceSignal(info.device) && !hasNetworkSignal(info.network)) return {};
+	const group = {};
+	const os = [info.os?.name, info.os?.version].filter((value) => value != null).join(" ");
+	if (os) group.OS = os;
+	setDefined(group, "Model", info.device?.model);
+	setDefined(group, "Type", info.device?.type);
+	const screen = info.device?.screen;
+	if (screen?.width != null && screen?.height != null) group.Screen = screen.scale != null ? `${screen.width} × ${screen.height} @ ${screen.scale}x` : `${screen.width} × ${screen.height}`;
+	if (info.device?.memoryGb != null) group.Memory = `${info.device.memoryGb} GB`;
+	setDefined(group, "CPU cores", info.device?.cpuCores);
+	setDefined(group, "Connection", info.network?.effectiveType);
+	if (info.network?.downlinkMbps != null) group.Downlink = `${info.network.downlinkMbps} Mbps`;
+	if (info.network?.rttMs != null) group.RTT = `${info.network.rttMs} ms`;
+	setDefined(group, "Online", info.network?.online);
+	setDefined(group, "App version", info.app?.version);
+	setDefined(group, "App ID", info.app?.id);
+	setDefined(group, "Language", info.locale?.language);
+	setDefined(group, "Timezone", info.locale?.timezone);
+	return group;
+}
+function hasDeviceSignal(device) {
+	return device != null && (device.type != null || device.model != null || device.memoryGb != null || device.cpuCores != null || device.screen?.width != null || device.screen?.height != null);
+}
+function hasNetworkSignal(network) {
+	return network != null && (network.effectiveType != null || network.downlinkMbps != null || network.rttMs != null || network.online != null);
+}
+
+//#endregion
+export { Api, BrowserSpanEventType, BrowserSpanType, DEFAULT_MAX_LIVE_TRACES, DEFAULT_URL_DENYLIST, Flare, FrameworkName, GlobalScopeProvider, InMemoryActiveSpanHolder, Logger, MAX_BREADCRUMB_URL_LENGTH, NoopFlushScheduler, NullDeviceInfoProvider, NullFileReader, Scope, SpanStatusCode, Tracer, USER_IDENTITY_KEYS, assert, assertKey, breadcrumbUrl, buildDeviceContextGroup, buildTraceparent, buildTracesEnvelope, convertToError, createIdentityTagger, createStackTrace, defaultNowNano, describeRejectionReason, deviceInfoToAttributes, evictLruIfNew, extractCode, flatJsonStringify, getCodeSnippet, glowsToEvents, now, parseTraceparent, readLinesFromFile, recordBreadcrumb, redactObjectValues, redactUrlQuery, resolveDenylist, routeRejection, safeClone, safeDecode, spanId, toCustomContext, urlAttributes, userIdentityAttributes };