@flareapp/core 2.7.0 → 2.8.0

package/dist/index.d.cts

@@ -1,222 +1,20 @@
-//#region src/types.d.ts
-type MessageLevel = 'debug' | 'info' | 'notice' | 'warning' | 'error' | 'critical' | 'alert' | 'emergency';
-type AttributeValue = string | number | boolean | null | AttributeValue[] | {
-  [key: string]: AttributeValue;
-};
-type Attributes = Record<string, AttributeValue>;
-/**
- * An identified user passed to `Flare.setUser`. The four known fields project to the
- * report keys the Flare backend reads: `id`→`user.id`, `email`→`user.email`,
- * `fullName`→`user.full_name`, `ipAddress`→`client.address`. Any OTHER key is bundled
- * into `user.attributes`.
- *
- * Caveat: the open index signature means a misspelled known field (e.g. `fullname` or
- * `full_name` instead of `fullName`) does NOT raise a type error — it silently lands in
- * `user.attributes` rather than the identity key. Spell the four known fields exactly.
- */
-type User = {
-  id?: string | number;
-  email?: string;
-  fullName?: string;
-  ipAddress?: string;
-  [key: string]: AttributeValue | undefined;
-};
-type Config = {
-  key: string | null;
-  version: string;
-  sourcemapVersionId: string;
-  stage: string;
-  maxGlowsPerReport: number;
-  reportBrowserExtensionErrors: boolean;
-  ingestUrl: string;
-  debug: boolean;
-  urlDenylist: RegExp;
-  replaceDefaultUrlDenylist: boolean;
-  sampleRate: number;
-  enableLogs: boolean;
-  logsIngestUrl: string;
-  minimumLogLevel?: MessageLevel;
-  serviceName?: string;
-  maxLogBufferSize: number;
-  logFlushIntervalMs: number;
-  logFlushMaxBytes: number;
-  keepaliveMaxBytes: number;
-  beforeEvaluate: (error: Error) => Error | false | null | Promise<Error | false | null>;
-  beforeSubmit: (report: Report) => Report | false | null | Promise<Report | false | null>;
-};
-type StackFrame = {
-  file: string;
-  lineNumber: number;
-  columnNumber?: number;
-  method?: string;
-  class?: string;
-  codeSnippet?: {
-    [line: number]: string;
-  };
-  isApplicationFrame?: boolean;
-  arguments?: unknown[];
-};
-type SpanEvent = {
-  type: string;
-  startTimeUnixNano: number;
-  endTimeUnixNano: number | null;
-  attributes: Attributes;
-};
-type OverriddenGrouping = 'exception_class' | 'exception_message' | 'exception_message_and_class' | 'full_stacktrace_and_exception_class_and_code';
-type Report = {
-  exceptionClass?: string | null;
-  message?: string | null;
-  code?: string;
-  seenAtUnixNano: number;
-  isLog?: boolean;
-  level?: MessageLevel;
-  sourcemapVersionId?: string;
-  trackingUuid?: string;
-  handled?: boolean;
-  openFrameIndex?: number;
-  applicationPath?: string;
-  overriddenGrouping?: OverriddenGrouping | null;
-  stacktrace: StackFrame[];
-  events: SpanEvent[];
-  attributes: Attributes;
-};
-type Glow = {
-  time: number;
-  microtime: number;
-  name: string;
-  messageLevel: MessageLevel;
-  metaData: Record<string, unknown> | Record<string, unknown>[];
-};
-type EntryPointHandler = {
-  identifier?: string;
-  name?: string;
-  type?: string;
-};
-type SdkInfo = {
-  name: string;
-  version: string;
-};
-type Framework = {
-  name: string;
-  version?: string;
-};
-type AnyValue = {
-  stringValue: string;
-} | {
-  boolValue: boolean;
-} | {
-  intValue: number;
-} | {
-  doubleValue: number;
-} | {
-  arrayValue: {
-    values: AnyValue[];
-  };
-} | {
-  kvlistValue: {
-    values: KeyValue[];
-  };
-};
-type KeyValue = {
-  key: string;
-  value: AnyValue;
-};
-type OtelResource = {
-  attributes: KeyValue[];
-  droppedAttributesCount: number;
-};
-type OtelScope = {
-  name: string;
-  version: string;
-  attributes: KeyValue[];
-  droppedAttributesCount: number;
-};
-type OtelLogRecord = {
-  timeUnixNano: string;
-  observedTimeUnixNano: string;
-  severityNumber: number;
-  severityText: string;
-  body: AnyValue;
-  attributes: KeyValue[];
-  flags: number;
-  droppedAttributesCount: number;
-};
-type LogsEnvelope = {
-  resourceLogs: Array<{
-    resource: OtelResource;
-    scopeLogs: Array<{
-      scope: OtelScope;
-      logRecords: OtelLogRecord[];
-    }>;
-  }>;
-};
-type BufferedLog = {
-  timeUnixNano: string;
-  severityNumber: number;
-  severityText: string;
-  message: string;
-  recordAttributes: KeyValue[];
-  resourceAttributes: Attributes;
-};
-//#endregion
-//#region src/util/assert.d.ts
-declare function assert(value: unknown, message: string, debug: boolean): boolean;
-//#endregion
-//#region src/util/assertKey.d.ts
-declare function assertKey(key: unknown, debug: boolean): boolean;
-//#endregion
-//#region src/util/convertToError.d.ts
-declare function convertToError(error: unknown): Error;
-//#endregion
-//#region src/util/extractCode.d.ts
-declare function extractCode(error: Error): string | undefined;
-//#endregion
-//#region src/util/flatJsonStringify.d.ts
-declare function flatJsonStringify(json: object): string;
-//#endregion
-//#region src/util/glowsToEvents.d.ts
-declare function glowsToEvents(glows: Glow[]): SpanEvent[];
-//#endregion
-//#region src/util/now.d.ts
-declare function now(): number;
-//#endregion
-//#region src/util/redactUrl.d.ts
-declare const DEFAULT_URL_DENYLIST: RegExp;
-declare function resolveDenylist(custom?: RegExp, replaceDefault?: boolean, defaultDenylist?: RegExp): RegExp;
-declare function redactUrlQuery(fullPath: string, denylist?: RegExp): string;
-//#endregion
-//#region src/util/rejection.d.ts
-/**
- * Shared unhandled-rejection routing. A rejection "reason" can be anything a
- * promise was rejected with: an Error, an Error-like object carrying a `.stack`,
- * a string, or a plain object. The browser `unhandledrejection` listener
- * (`@flareapp/js`) and the React Native engine rejection tracker
- * (`@flareapp/react-native`) need the SAME routing so a report looks identical
- * across SDKs, so it lives here instead of being copy-pasted (and drifting) per
- * client.
- */
-type RejectionReporter = {
-  reportSilently: (error: Error) => void;
-  reportUnhandledRejection: (message: string) => unknown;
-};
-/** Best-effort human-readable description of an arbitrary rejection reason. */
-declare function describeRejectionReason(reason: unknown): string;
-/**
- * Route a rejection reason to the reporter: an Error (or any stack-bearing
- * object) goes to `reportSilently` so the STACK survives; only a stackless
- * reason falls back to `reportUnhandledRejection` (string message, empty-stack
- * `UnhandledRejection` class). Any rejection from `reportUnhandledRejection`'s
- * returned promise is swallowed so a transport failure cannot itself surface as
- * an unhandled rejection. `reportSilently` is assumed not to throw synchronously
- * (core's does its work asynchronously); it is intentionally not wrapped, so a
- * synchronous throw there would propagate.
- */
-declare function routeRejection(reporter: RejectionReporter, reason: unknown): void;
-//#endregion
+import { $ as User, A as BufferedSpan, B as OtelSpan, D as AttributeValue, E as AnyValue, F as Glow, G as Span, H as Report, I as KeyValue, J as SpanStatus, K as SpanEvent, L as LogsEnvelope, M as EntryPointHandler, N as EntryPointType, O as Attributes, P as Framework, Q as TracesSampler, R as MessageLevel, T as assert, U as SamplingContext, V as OverriddenGrouping, W as SdkInfo, X as StackFrame, Y as SpanStatusCode, Z as TracesEnvelope, _ as flatJsonStringify, a as SafeCloneOptions, b as createIdentityTagger, c as describeRejectionReason, d as redactObjectValues, et as BrowserSpanType, f as redactUrlQuery, g as glowsToEvents, h as now, j as Config, k as BufferedLog, l as routeRejection, m as safeDecode, n as urlAttributes, nt as FrameworkName, o as safeClone, p as resolveDenylist, q as SpanOptions, r as toCustomContext, s as RejectionReporter, tt as SpanTypeName, u as DEFAULT_URL_DENYLIST, v as extractCode, w as assertKey, x as convertToError, y as SdkTaggable, z as OtelLogRecord } from "./urlAttributes-CvOw6tU3.cjs";
+
 //#region src/api/Api.d.ts
 declare class Api {
+  private pendingKeepaliveBytes;
+  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.
+   */
+  keepaliveBudgetRemaining(): number;
   report(report: Report, url: string, key: string | null, reportBrowserExtensionErrors: boolean, debug?: boolean): Promise<void>;
   logs(envelope: LogsEnvelope, url: string, key: string | null, debug?: boolean, keepalive?: boolean): Promise<void>;
+  traces(envelope: TracesEnvelope, url: string, key: string | null, debug?: boolean, keepalive?: boolean): Promise<void>;
+  private ingestHeaders;
+  private send;
 }
 //#endregion
 //#region src/logging/FlushScheduler.d.ts
@@ -250,10 +48,8 @@ type LoggerDeps = {
 };
 declare class Logger {
   private deps;
-  private buffer;
+  private inner;
   private resourceAttributes;
-  private timer;
-  private timerActive;
   constructor(deps: LoggerDeps);
   debug(message: string, context?: Attributes, attributes?: Attributes): void;
   info(message: string, context?: Attributes, attributes?: Attributes): void;
@@ -264,108 +60,46 @@ declare class Logger {
   alert(message: string, context?: Attributes, attributes?: Attributes): void;
   emergency(message: string, context?: Attributes, attributes?: Attributes): void;
   bufferLength(): number;
-  private record;
-  private evaluateTriggers;
-  private armTimer;
-  private trim;
   flush(opts?: {
     keepalive?: boolean;
   }): void;
   clear(): void;
-  private packForKeepalive;
-  private buildEnvelope;
+  private record;
   private resourceForFlush;
-  private clearTimer;
   private estimateBytes;
-  private bufferBytes;
 }
 //#endregion
 //#region src/Scope.d.ts
-/**
- * The report attribute keys that `Flare.setUser` owns: the four projected identity
- * fields plus the `user.attributes` bag for extras. Single source of truth so the
- * clear pass and the set pass in `setUser` cannot drift, and so consumers that must
- * stamp identity outside core's report pipeline (Electron's forwarded-renderer path)
- * pick up the exact same set instead of re-hardcoding it.
- */
+/** Every key `Flare.setUser` owns. Consumers stamping identity outside core's report pipeline (Electron's
+ *  forwarded-renderer path) reuse this exact set. */
 declare const USER_IDENTITY_KEYS: readonly [...("user.id" | "user.email" | "user.full_name" | "client.address")[], "user.attributes"];
-/**
- * Pick the user-identity attributes currently set on a scope. Used where identity must
- * be copied onto a report that does not flow through `Flare.report()` (which would
- * otherwise spread `pendingAttributes` automatically).
- */
+/** For reports that do not flow through `Flare.report()`, which would spread `pendingAttributes` itself. */
 declare function userIdentityAttributes(scope: Scope): Attributes;
 /**
- * Holds the per-call mutable state that used to live on the `Flare` instance:
- * breadcrumbs (`glows`), custom attributes (`pendingAttributes`), and the
- * current entry-point handler.
- *
- * Why this exists as its own class: in the browser there is one `Flare` per
- * page and one user at a time, so a single shared bag of state is fine. In
- * Node, a single `Flare` instance serves many concurrent requests, and each
- * request wants its own breadcrumbs and its own custom context that do NOT
- * leak into other requests. Splitting this state out of `Flare` lets the
- * consumer choose: one global `Scope` (browser) or one `Scope` per request
- * via AsyncLocalStorage (Node).
- *
- * `Flare` reads and writes this through `scopeProvider.active()` instead of
- * holding the state directly, so the per-request behavior comes from the
- * provider, not from the class itself.
- *
- * `NodeScope` (in `@flareapp/node`) extends this with a `request` bucket
- * (HTTP method, path, headers). User identity is written to `pendingAttributes`
- * by `Flare.setUser`, so it needs no dedicated field. Browser does not need `request`.
+ * Per-call mutable state, split out of `Flare` so the consumer can choose one global `Scope` (browser, one
+ * user at a time) or one per request via AsyncLocalStorage (Node, where concurrent requests must not leak
+ * into each other). `@flareapp/node`'s `NodeScope` extends this with a `request` bucket.
  */
 declare class Scope {
   glows: Glow[];
   pendingAttributes: Attributes;
   entryPoint: EntryPointHandler | null;
-  /**
-   * Append a breadcrumb. Caps the list at `maxGlowsPerReport` by dropping the
-   * OLDEST entries when the limit is exceeded; this keeps reports below a
-   * payload-size threshold while preserving the most recent events leading
-   * up to an error.
-   *
-   * `slice(length - max)` returns the trailing `max` items, which is the
-   * shortest way to drop from the front and keep insertion order.
-   */
+  /** Caps at `maxGlowsPerReport` by dropping the oldest, so the payload stays bounded. */
   addGlow(glow: Glow, maxGlowsPerReport: number): void;
   clearGlows(): void;
-  /**
-   * Set a single attribute on this scope. Called from `Flare.addContext` and
-   * `Flare.addContextGroup`. Last write wins.
-   */
   setAttribute(key: string, value: AttributeValue): void;
-  /**
-   * Shallow-merge a bag of attributes into this scope. Used by Node's
-   * AsyncLocalStorage provider when patching the live request context via
-   * `flare.mergeContext({ ... })`. Last write wins per key; nested objects
-   * are NOT deep-merged.
-   */
+  /** Shallow: last write wins per key, nested objects are not deep-merged. */
   mergeAttributes(partial: Attributes): void;
 }
 /**
- * The seam through which `Flare` reaches its current `Scope`. Implementations
- * decide what "current" means.
- *
- * - `GlobalScopeProvider` always returns the same `Scope` instance (browser).
- * - `AsyncLocalStorageScopeProvider` in `@flareapp/node` returns the per-request
- *   `NodeScope` stored in `node:async_hooks` for the in-flight async chain,
- *   falling back to a single shared scope when called outside any
- *   `runWithContext(...)` callback.
- *
- * Any consumer of `@flareapp/core` can supply its own provider to plug in
- * different "current scope" semantics.
+ * The seam through which `Flare` reaches its current `Scope`; implementations decide what "current" means.
+ * `@flareapp/node`'s returns the per-request `NodeScope` from `node:async_hooks`, falling back to a shared
+ * scope outside any `runWithContext(...)`.
  */
 interface ScopeProvider {
   active(): Scope;
 }
-/**
- * The simplest provider: one `Scope` for the lifetime of the provider, shared
- * by every caller. This is the right default for environments with a single
- * logical context (browser tab, CLI script, etc.) and is the default that
- * `Flare`'s constructor falls back to when no provider is supplied.
- */
+/** One `Scope` for the provider's lifetime. The right default for a browser tab or a CLI script. */
 declare class GlobalScopeProvider implements ScopeProvider {
   private scope;
   active(): Scope;
@@ -385,6 +119,102 @@ type ReaderResponse = {
 declare function getCodeSnippet(fileReader: FileReader, url?: string, lineNumber?: number, columnNumber?: number): Promise<ReaderResponse>;
 declare function readLinesFromFile(fileText: string, lineNumber: number, columnNumber?: number, maxSnippetLineLength?: number, maxSnippetLines?: number): ReaderResponse;
 //#endregion
+//#region src/tracing/context.d.ts
+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.
+   */
+  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.
+   */
+  setActiveRoot?(span: Span | undefined): void;
+}
+declare class InMemoryActiveSpanHolder implements ActiveSpanHolder {
+  private active;
+  private root;
+  getActive(): Span | undefined;
+  withActive<T>(span: Span, fn: () => T): T;
+  setActiveRoot(span: Span | undefined): void;
+}
+//#endregion
+//#region src/tracing/Tracer.d.ts
+declare function defaultNowNano(): number;
+type SpanPhase = 'start' | 'end';
+type SpanLifecycleEvent = {
+  phase: SpanPhase;
+  span: Span;
+};
+type SpanLifecycleListener = (event: SpanLifecycleEvent) => void;
+/** Bounded backstop for the live TraceState map: an app that never ends spans must not grow it forever. */
+declare const DEFAULT_MAX_LIVE_TRACES = 1000;
+type TracerDeps = {
+  api: Api;
+  getConfig: () => Config;
+  getSdkInfo: () => SdkInfo;
+  getFramework: () => Framework | null;
+  getScopeAttributes: () => Attributes;
+  getResourceAttributes: () => Attributes;
+  track: <T>(p: Promise<T>) => Promise<T>;
+  scheduler: FlushScheduler;
+  activeSpanHolder?: ActiveSpanHolder;
+  now?: () => number;
+  rng?: () => number;
+  maxLiveTraces?: number;
+};
+declare class Tracer {
+  private deps;
+  private buffer;
+  private holder;
+  private traceStates;
+  private closedTraces;
+  private stateGeneration;
+  private now;
+  private rng;
+  private maxLiveTraces;
+  private epoch;
+  private pendingContinuation;
+  private spanListeners;
+  constructor(deps: TracerDeps);
+  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 })`.
+   */
+  claimSpanSlot(traceId: string): boolean;
+  addSpanListener(fn: SpanLifecycleListener): () => void;
+  private emitSpanEvent;
+  flush(opts?: {
+    keepalive?: boolean;
+  }): void;
+  clear(): void;
+  continueFromTraceparent(header: string): void;
+  /**
+   * Runs `fn` with the span active, so spans started inside auto-parent to it, then ends it.
+   * 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. */
+  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;
+}
+//#endregion
 //#region src/Flare.d.ts
 type ContextCollector = (config: Readonly<Config>) => Attributes;
 declare class Flare {
@@ -394,157 +224,54 @@ declare class Flare {
   private scopeProvider;
   private inflight;
   private _logger;
+  private _tracer;
   private _config;
   private sdkInfo;
   private framework;
   /**
-   * @param api              sends the report over HTTP.
-   * @param contextCollector returns per-report attributes (browser DOM info, Node
-   *                         process info, etc). Default is a no-op.
-   * @param fileReader       reads source files for stack-trace snippets. Default
-   *                         returns null (no snippets); `@flareapp/js` injects a
-   *                         fetch-based reader, `@flareapp/node` injects a disk reader.
-   * @param scopeProvider    returns the current `Scope` (per-call mutable state:
-   *                         glows, pendingAttributes, entryPoint). Browser uses a
-   *                         single global scope; Node uses an AsyncLocalStorage-
-   *                         backed provider so each request gets its own.
+   * @param api              fetch transport for reports, logs and traces. Stateless: ingest url and
+   *                         key are passed per call, so tests swap in a fake.
+   * @param contextCollector per-report attributes (browser DOM, Node process). No-op by default.
+   * @param fileReader       source files for stack-trace snippets. Defaults to no snippets;
+   *                         `@flareapp/js` injects a fetch reader, `@flareapp/node` a disk reader.
+   * @param scopeProvider    the current `Scope`. Browser uses one global scope; Node an
+   *                         AsyncLocalStorage-backed provider so each request gets its own.
+   * @param scheduler        drains the log and span buffers when the host's lifecycle ends (browser
+   *                         unload, process exit). No-op by default, leaving only size/timer flushes.
+   * @param activeSpanHolder tracks the active span so new spans auto-parent to it. In-memory by
+   *                         default; a platform can back it with AsyncLocalStorage instead.
    */
-  constructor(api?: Api, contextCollector?: ContextCollector, fileReader?: FileReader, scopeProvider?: ScopeProvider, scheduler?: FlushScheduler);
+  constructor(api?: Api, contextCollector?: ContextCollector, fileReader?: FileReader, scopeProvider?: ScopeProvider, scheduler?: FlushScheduler, activeSpanHolder?: ActiveSpanHolder);
   /**
-   * Register an in-flight report so `flush()` can wait for it. Called by
-   * every public report entry point (`report`, `reportSilently`,
-   * `reportMessage`, `reportUnhandledRejection`, `test`); each wraps its
-   * full async pipeline (beforeEvaluate -> stack trace + source snippets ->
-   * beforeSubmit -> `api.report()`) so the entire roundtrip is what's
-   * tracked, not just the HTTP send at the end.
-   *
-   * Two problems this method solves at once.
-   *
-   * Problem 1: hold a reference to the work without leaking rejections.
-   *
-   *   `p` is the real report pipeline; it can reject (network failure,
-   *   `beforeSubmit` throws, etc). If we stored `p` directly in `inflight`
-   *   and no caller attached a `.catch` (the global error listeners use
-   *   `reportSilently` which DOES catch, but the path is still subtle), an
-   *   eventual rejection would surface as an unhandled-rejection warning
-   *   on Node and a console error in the browser. Bad citizen.
+   * 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.
    *
-   *   So we build a SHADOW promise that mirrors `p`'s timing but cannot
-   *   reject:
-   *
-   *     p.then(
-   *         () => undefined,   // on fulfilment, value is undefined
-   *         () => undefined,   // on rejection, ALSO resolve with undefined
-   *     )
-   *
-   *   Providing the second argument means we have "handled" any rejection
-   *   from `p`. The shadow always resolves with `undefined`, and `p`'s
-   *   rejection is consumed at the boundary. From the runtime's point of
-   *   view, the shadow is well-behaved.
-   *
-   * Problem 2: self-cleaning entry.
-   *
-   *   `tracked.finally(() => this.inflight.delete(tracked))`. `finally`
-   *   fires whether the shadow resolves or rejects, but the shadow can no
-   *   longer reject (problem 1 normalized it), so this is effectively
-   *   "when the underlying report has settled, remove me from the Set."
-   *   No GC magic, no external cleanup, no race window.
-   *
-   *   Note that `.finally` itself returns a new promise that we drop on
-   *   the floor. If the cleanup callback ever throws, that would surface
-   *   as an unhandled rejection on the dropped promise; `delete` does not
-   *   throw so we are safe today, but anything more elaborate added here
-   *   should be wrapped in try/catch.
-   *
-   * The return value is the ORIGINAL `p`. The caller awaits real success
-   * or failure; the tracking is completely invisible to them. This is why
-   * `await flare.report(err)` inside a fatal handler observes network
-   * errors the same as before tracking was added.
+   * 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 until `timeoutMs`
-   * elapses, whichever comes first. Always resolves; never rejects.
-   *
-   * The main consumer is `@flareapp/node`'s fatal handler:
-   *
-   *     process.on('uncaughtException', async (err) => {
-   *         process.exitCode = 1;
-   *         try { await flare.report(err); } catch {}
-   *         await flare.flush(shutdownTimeoutMs);
-   *         process.exit(1);
-   *     });
-   *
-   * The fatal `report` is awaited explicitly; `flush` then drains any
-   * OTHER reports that were already in flight (a request handler that
-   * fired `flare.report(...)` concurrently with the crash). The timeout
-   * caps the wait so a hung HTTP request cannot indefinitely block
-   * shutdown.
-   *
-   * Walking the implementation:
-   *
-   *   const pending = [...this.inflight];
-   *
-   *     Spread takes a SNAPSHOT of the Set at this instant. Reports that
-   *     start AFTER this line are not included in `pending`, so they are
-   *     not awaited by THIS flush call. This is intentional: it bounds
-   *     the wait. Without the snapshot, a handler that kept emitting
-   *     reports during shutdown could keep flush alive forever and block
-   *     the process from exiting.
-   *
-   *   if (pending.length === 0) return Promise.resolve();
-   *
-   *     Fast path. No timer scheduled, no promise constructor needed.
-   *     Resolves on the microtask queue. Cheap.
+   * 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`.
    *
-   *   return new Promise<void>((resolve) => {
-   *       const timer = setTimeout(resolve, timeoutMs);
-   *       Promise.allSettled(pending).then(() => {
-   *           clearTimeout(timer);
-   *           resolve();
-   *       });
-   *   });
-   *
-   *     The race between two outcomes, both calling the same `resolve`:
-   *
-   *     1. `setTimeout(resolve, timeoutMs)` schedules a "give up" call.
-   *        After `timeoutMs` it fires, calling `resolve()` from the
-   *        timer-queue side. The outer promise resolves immediately,
-   *        even if reports are still pending. Those reports are abandoned
-   *        (they continue running but the process is about to die).
-   *
-   *     2. `Promise.allSettled(pending)` returns a promise that resolves
-   *        when every promise in `pending` has either fulfilled or
-   *        rejected. It NEVER rejects on its own. We use `allSettled`
-   *        rather than `Promise.all` because `all` short-circuits on the
-   *        first rejection -- we want to wait for everyone regardless of
-   *        whether their HTTP calls succeed or fail. (Our shadows cannot
-   *        reject anyway because `track` normalized them, but using
-   *        `allSettled` documents the intent and survives future changes
-   *        to shadow construction.) When it resolves, we call
-   *        `clearTimeout(timer)` to cancel the pending timer (so it does
-   *        not fire later and call `resolve` a second time -- a no-op,
-   *        but wasted work) and then `resolve()` ourselves.
-   *
-   *   Resolve can only meaningfully fire once. Subsequent calls to the
-   *   same `resolve` are silently ignored by the Promise spec, so the
-   *   race is safe even if for some reason both branches fired together.
-   *
-   * Things flush() deliberately does NOT do:
-   *
-   *   - It does not reject. Even if every report failed, allSettled
-   *     resolves. Callers do not need a `.catch`.
-   *   - It does not retry. One pipeline attempt per report, then move on.
-   *   - It does not stop new reports from starting. The Flare instance
-   *     is still usable after flush resolves. flush is "wait for what is
-   *     in flight," not "freeze the SDK."
-   *   - It does not drain reports started after the snapshot. Call flush
-   *     again if you need to wait for those too.
+   * 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.
    */
   flush(timeoutMs?: number): Promise<void>;
   get config(): Readonly<Config>;
   get glows(): readonly Glow[];
   get logger(): Logger;
+  get tracer(): Tracer;
+  /** 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;
+  /**
+   * Runs `fn` with the span active, so spans started inside auto-parent to it, then ends it.
+   * Records an error status first if `fn` throws or its returned promise rejects.
+   */
+  withSpan<T>(name: string, fn: (span: Span) => T, opts?: SpanOptions): T;
   light(key?: string, debug?: boolean): this;
   configure(config: Partial<Config>): this;
   test(): Promise<void>;
@@ -554,11 +281,8 @@ declare class Flare {
   addContext(name: string, value: AttributeValue): this;
   addContextGroup(groupName: string, value: Record<string, AttributeValue>): this;
   /**
-   * Attach an identified user to the active scope. Fields are projected to the
-   * keys the Flare backend reads: `user.id`, `user.email`, `user.full_name`,
-   * and `client.address`. Any extra keys are bundled into `user.attributes`.
-   * Pass `null` to clear the user. Scope-aware: in Node this targets the
-   * per-request scope via the scope provider.
+   * Maps the known fields onto the keys the Flare backend reads (see `USER_FIELD_KEYS`) and bundles
+   * anything else into `user.attributes`. Pass `null` to clear. In Node this targets the per-request scope.
    */
   setUser(user: User | null): this;
   setEntryPoint(handler: EntryPointHandler): this;
@@ -575,31 +299,42 @@ 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;
   sendReport(report: Report): Promise<void>;
 }
 //#endregion
+//#region src/tracing/envelope.d.ts
+declare function buildTracesEnvelope(spans: BufferedSpan[], resourceAttributes: Attributes, scopeName: string, scopeVersion: string): TracesEnvelope;
+//#endregion
+//#region src/tracing/traceparent.d.ts
+declare function buildTraceparent(traceId: string, spanId: string, sampled: boolean): string;
+declare function parseTraceparent(header: string): {
+  traceId: string;
+  parentSpanId: string;
+  sampled: boolean;
+} | null;
+//#endregion
+//#region src/tracing/ids.d.ts
+declare function spanId(): string;
+//#endregion
 //#region src/stacktrace/NullFileReader.d.ts
 /**
- * No-op `FileReader` that returns `null` for every URL it is asked to read.
- *
- * Used as the default for `Flare`'s `fileReader` constructor parameter so the
- * class is usable without picking a side: instantiated bare (`new Flare()`),
- * reports still build, but stack frames omit source-code snippets — which is
- * the correct, safe behavior in an environment we know nothing about.
- *
- * The two real implementations live in the consumer packages and take their
- * place once the right environment is established:
- *
- * - `@flareapp/js` injects `FetchFileReader`, which `fetch()`s source maps
- *   and original files over HTTP for browser stack frames.
- * - `@flareapp/node` injects `DiskFileReader`, which reads files from disk
- *   via `node:fs/promises` for server stack frames.
- *
- * The interface (`read(url) -> Promise<string | null>`) lets the stack-trace
- * builder treat all three the same way: ask for a URL, render the snippet
- * when text comes back, gracefully skip it when `null` does. No environment
- * checks anywhere in core.
+ * 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.
  */
 declare class NullFileReader implements FileReader {
   read(_url: string): Promise<string | null>;
@@ -608,4 +343,4 @@ declare class NullFileReader implements FileReader {
 //#region src/stacktrace/createStackTrace.d.ts
 declare function createStackTrace(error: Error, debug: boolean, fileReader: FileReader): Promise<Array<StackFrame>>;
 //#endregion
-export { type AnyValue, Api, type AttributeValue, type Attributes, type BufferedLog, type Config, type ContextCollector, DEFAULT_URL_DENYLIST, type EntryPointHandler, type FileReader, Flare, type FlushFn, type FlushScheduler, type Framework, GlobalScopeProvider, type Glow, type KeyValue, Logger, type LoggerDeps, type LogsEnvelope, type MessageLevel, NoopFlushScheduler, NullFileReader, type OtelLogRecord, type OverriddenGrouping, type RejectionReporter, type Report, Scope, type ScopeProvider, type SdkInfo, type SpanEvent, type StackFrame, USER_IDENTITY_KEYS, type User, assert, assertKey, convertToError, createStackTrace, describeRejectionReason, extractCode, flatJsonStringify, getCodeSnippet, glowsToEvents, now, readLinesFromFile, redactUrlQuery, resolveDenylist, routeRejection, userIdentityAttributes };
+export { type ActiveSpanHolder, type AnyValue, Api, type AttributeValue, type Attributes, 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, 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, buildTraceparent, buildTracesEnvelope, convertToError, createIdentityTagger, createStackTrace, defaultNowNano, describeRejectionReason, extractCode, flatJsonStringify, getCodeSnippet, glowsToEvents, now, parseTraceparent, readLinesFromFile, redactObjectValues, redactUrlQuery, resolveDenylist, routeRejection, safeClone, safeDecode, spanId, toCustomContext, urlAttributes, userIdentityAttributes };