@nathanclaire/edge-telemetry-sdk 3.0.0 → 4.0.0

package/dist/src/adapters/loadingTime.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The quiet window, and **the same constant as §4.6's dead-click window** — one constant, not
+ * two. `ui.dead` (web only, not built yet) must import this rather than declare a second 1000.
+ */
+export declare const QUIET_WINDOW_MS = 1000;
+/** Hard cap (§4.5.2). A capped view emits **null, not the cap**: at 30 s, 30 s and 90 s are the same row. */
+export declare const LOADING_TIME_CAP_MS = 30000;
+/** §4.5's `view.loading_time_outcome` domain — never null, exactly four values. */
+export type LoadingTimeOutcome = "settled" | "no_activity" | "capped" | "abandoned";
+export type LoadingTimeResult = {
+    /** Milliseconds, or null — and null has three causes, which is why the outcome ships beside it. */
+    loadingTime: number | null;
+    outcome: LoadingTimeOutcome;
+};
+export type NetworkSettleOpts = {
+    /**
+     * `initial_load` only: the view starts **busy** until the platform's own runtime-ready
+     * marker (`loadEventEnd` on web, `performance.rnStartupTiming` on native), then settles.
+     * Every other `load_type` runs the same column with no seed.
+     */
+    awaitRuntimeReady?: boolean;
+};
+/**
+ * One view's settle state. Constructed per view and handed the requests that **started** in
+ * it — a request in flight across a view boundary belongs to the old view and does not hold
+ * the new one open (§4.5.2), which is why the completion callback is bound to this instance
+ * rather than looked up on whatever view is live when the response lands.
+ */
+export declare class NetworkSettle {
+    private readonly viewStart;
+    private started;
+    private inFlight;
+    private lastEnd?;
+    /** Frozen the first time quiet is *observed*, so a later request cannot un-settle the view. */
+    private settledAt?;
+    private awaitingRuntimeReady;
+    private runtimeReadyAt?;
+    constructor(viewStart: number, opts?: NetworkSettleOpts);
+    /** `view.request_count` — requests **started** in this view, failures included (§4.5). */
+    get requestCount(): number;
+    /**
+     * The platform's runtime-ready marker, or `undefined` where the platform has none —
+     * Old Architecture, or a runtime that omits it (§4.3). Either way this releases the gate:
+     * a marker that never arrives must not make every launch report `abandoned`.
+     */
+    seedRuntimeReady(at?: number): void;
+    /**
+     * A request started in this view. Returns its completion callback — idempotent, because an
+     * XHR `loadend` can fire more than once for a reused instance and an unbalanced in-flight
+     * count would hold the view open forever.
+     */
+    requestStarted(now?: number): (endedAt?: number) => void;
+    /**
+     * The view's verdict at exit. Idempotent, not pure: it may freeze the settle timestamp as
+     * a side effect, which is deliberate — once quiet has been *observed* it cannot be undone
+     * by a later call, and calling this twice must not produce two different answers.
+     */
+    resolve(now?: number): LoadingTimeResult;
+    /**
+     * Settle is the *completion* timestamp, not the moment we noticed it — the quiet window is
+     * detection delay and is subtracted back out. That is free precisely because the `view`
+     * event emits at view exit rather than at settle, so nothing waits on the window.
+     */
+    private freezeIfQuiet;
+    /** When the network last went quiet, or undefined while the view is still busy. */
+    private quietSince;
+}

package/dist/src/adapters/native/interceptHttpNative.native.d.ts

@@ -0,0 +1,18 @@
+import { Telemetry } from '../../core/telemetry';
+/**
+ * Captures all JS-originated HTTP on React Native by patching `XMLHttpRequest` — and nothing
+ * else. RN's `global.fetch` is `XMLHttpRequest` underneath (contract §4.4), so patching both
+ * would emit **two** `http.request` events per `fetch()` call; the one chokepoint catches
+ * `fetch` *and* axios, which is why an axios app's HTTP dashboard was empty before #95.
+ *
+ * Outside the boundary and uncountable: rn-fetch-blob, RN Firebase, native Apollo links,
+ * expo-file-system, `Image` loading and `WebSocket` — none of them touch JS HTTP.
+ */
+export declare class NetworkTrackerNative {
+    private telemetry;
+    private unpatch?;
+    constructor(telemetry: Telemetry);
+    start(): Promise<void>;
+    /** Restores the original XHR prototype, removing the interception. */
+    stop(): void;
+}

package/dist/src/adapters/native/memoryNative.native.d.ts

@@ -1,25 +1,29 @@
 import { Telemetry } from '../../core/telemetry';
 /**
- * Logs JavaScript memory usage and pressure level at regular intervals
- * in a React Native environment.
+ * §5.2 / #105 — `memory_usage`: RSS, **native only**, sampled every 30 s. The rationale for
+ * every part of that sentence lives in CLAUDE.md's `memory_usage` section; this file is the
+ * mechanism.
  */
 export declare class TelemetryMemoryUsageNative {
     private telemetry;
     private intervalId;
     constructor(telemetry: Telemetry);
     /**
-     * Records a memory_usage metric (value = used heap MB) per sample, on the v3 metric path.
-     */
-    recordMemoryUsage(): void;
-    /**
-     * Starts periodic memory usage logging at the given interval.
-     * Returns a resolved Promise for async startup flows.
+     * One sample: `value` = resident MB, with the device total alongside so headroom is
+     * readable without a second join. An unusable read emits nothing — a fabricated 0 would
+     * drag every percentile down and read as a memory *win*.
      *
-     * @param intervalMs Sampling interval in milliseconds (default: 30s)
+     * The two reads are guarded separately on purpose: `value` is what §5.2 makes primary,
+     * so a device-info build whose `getTotalMemory()` throws must still ship the resident
+     * figure with `memory.total_mb` simply absent.
      */
-    start(intervalMs?: number): Promise<void>;
+    recordMemoryUsage(): Promise<void>;
     /**
-     * Stops the periodic memory logging if it was started.
+     * Starts the periodic sampler. v3 never called this — `trackMemoryUsage()` fired the
+     * one-shot read and applied `.catch` to its `void` return — so the metric was
+     * single-shot at best.
      */
+    start(): Promise<void>;
+    /** Stops the periodic sampler. Called by `Telemetry.shutdown()`. */
     stop(): void;
 }

package/dist/src/adapters/native/runtimeReady.native.d.ts

@@ -0,0 +1 @@
+export declare function runtimeReadyAt(): Promise<number | undefined>;

package/dist/src/adapters/native/store.native.d.ts

@@ -0,0 +1,10 @@
+import { AsyncStore } from '../../core/store';
+/**
+ * AsyncStorage-backed Store for the native build (#89). Reads settle later, so a
+ * caller cannot assume a write has landed before the process dies — the crash-loss
+ * window narrows here, it does not close. The port keeps that visible.
+ *
+ * A rejected AsyncStorage call — no native module linked, SQLite/disk full — is
+ * `unavailable`, distinct from a key that simply isn't there.
+ */
+export declare function nativeStore(): AsyncStore;

package/dist/src/adapters/nativeSender.d.ts

@@ -1,3 +1,3 @@
 import { Sender } from '../core/telemetry';
-export declare function nativeSender(endpoint?: string, apiKey?: string): Sender;
-export declare function replayFailedNative(endpoint?: string, apiKey?: string): Promise<void>;
+import { Store } from '../core/store';
+export declare function nativeSender(endpoint?: string, apiKey?: string, store?: Store): Sender;

package/dist/src/adapters/navigationRef.d.ts

@@ -0,0 +1,21 @@
+import { Telemetry } from '../core/telemetry';
+/**
+ * React Navigation route tracking, **shared by both builds** (§4.5.1, #96).
+ *
+ * `getCurrentRoute()` is a navigation-tree API, not a native one — it works identically on
+ * RN-Web — and `route.name` is rung 2 of the name ladder. Wiring it once means one
+ * `GROUP BY view.name` spans web and native, instead of web reverse-engineering a template
+ * out of a URL the app is already holding in memory.
+ *
+ * Everything platform-specific stays in `Telemetry.recordRouteChange`, which gates the two
+ * deprecated native feeds (§4.11) on an entry-supplied flag.
+ *
+ * Usage: pass your navigationContainerRef.
+ */
+export declare class NavigationRefTracker {
+    private telemetry;
+    private currentRoute?;
+    constructor(telemetry: Telemetry);
+    attach(navigationRef: any): void;
+    private getActiveRouteName;
+}

package/dist/src/adapters/navigationTracker.d.ts

@@ -2,5 +2,5 @@ import { Telemetry } from '../core/telemetry';
 export declare class NavigationTracker {
     private telemetry;
     constructor(telemetry: Telemetry);
-    recordRouteChange(from: string, to: string): void;
+    recordRouteChange(from: string, to: string): Promise<void>;
 }

package/dist/src/adapters/screenTiming.d.ts

@@ -4,6 +4,12 @@ export declare class ScreenTimingTracker {
     private startTimes;
     private lastScreen?;
     constructor(telemetry: Telemetry);
-    startScreen(screen: string): void;
-    endScreen(screen: string): void;
+    startScreen(screen: string): Promise<void>;
+    /**
+     * Arm the dwell clock without emitting `navigation`. The route-change path (§4.11) has
+     * already emitted its own `navigation` with `method: "push"`, and emitting a second one
+     * with `method: "screen_start"` for the same transition would double the table.
+     */
+    markStart(screen: string): void;
+    endScreen(screen: string): Promise<void>;
 }

package/dist/src/adapters/seedRuntimeReady.d.ts

@@ -0,0 +1,8 @@
+import { ViewManager } from './viewManager';
+export type RuntimeReadyReader = () => Promise<number | undefined>;
+/**
+ * Fire-and-forget on purpose: on web the marker arrives with the load event, and blocking init
+ * on it would put every host call behind the page's own images. The caller awaits the *module*
+ * import instead, so the seed is armed before the instance is visible.
+ */
+export declare function seedRuntimeReady(views: ViewManager, read: RuntimeReadyReader, build: string): void;

package/dist/src/adapters/traceHeader.d.ts

@@ -0,0 +1,33 @@
+/** Lowercase on purpose: header names are compared case-insensitively (§6.4). */
+export declare const TRACEPARENT = "traceparent";
+/** §6.5's ladder. Precedence is declaration order; **absent means not traced**. */
+export type TraceOutcome = "skipped_off_allowlist" | "skipped_no_cors" | "skipped_consumer_set" | "adopted" | "injected_attributed" | "injected_expired" | "injected_unattributed";
+/**
+ * Constructor-only, exact match, empty by default — v4 is **dark on upgrade**, so nobody's
+ * CORS breaks until they opt in. Listing a host is the consumer's assertion that that host
+ * allows the header; that is why regexes and predicates were rejected rather than deferred.
+ */
+export declare function normalizeAllowlist(entries: unknown): ReadonlySet<string>;
+/** Matching is on `hostname` — **ports ignored**, exact-only, no wildcards, no same-origin exemption. */
+export declare function allowsHost(allowlist: ReadonlySet<string>, url: string): boolean;
+/**
+ * W3C `traceparent`, version `00`. Used for exactly one decision: is the consumer's own
+ * header valid (`adopted`) or not (`skipped_consumer_set`)? An all-zero trace-id or span-id
+ * is invalid by the spec. ⚠ Its price, said out loud: Android *repairs* a malformed consumer
+ * header; §6.4's never-strip forbids that here, so it goes out broken and is unattributed on
+ * both ends — visible in the outcome distribution rather than silently fixed.
+ */
+export declare function parseTraceparent(value: string | null | undefined): {
+    traceId: string;
+    spanId: string;
+} | undefined;
+/** Flags are always `01`: an unsampled session injects no header at all, not a `flags=00` id. */
+export declare function formatTraceparent(traceId: string, spanId: string): string;
+/** Presence check only — the one purpose §6.4's read-scope invariant permits. */
+export declare function readHeader(headers: unknown, name: string): string | undefined;
+/**
+ * A **copy** with our header appended. The consumer's `Headers`/`Request`/object is never
+ * mutated, which is how never-strip is satisfied by construction rather than by discipline.
+ * An array of pairs is a valid `HeadersInit` everywhere, so no `Headers` global is required.
+ */
+export declare function withHeader(headers: unknown, name: string, value: string): [string, string][];

package/dist/src/adapters/traceManager.d.ts

@@ -0,0 +1,131 @@
+/** §6.1's four root types. */
+export type TraceRootType = "launch" | "interaction" | "navigation" | "request";
+/** A flat bag of wire keys. An absent key means the SDK had nothing (§6.1). */
+export type TraceAttributes = Record<string, string | number>;
+/** What the interceptor observed at `send()`, and nothing it had to interpret. */
+export type RequestTraceCtx = {
+    url: string;
+    /** An unsampled session injects no header at all (§6.5). Sampling stays session-level. */
+    sampled: boolean;
+    /**
+     * The consumer's own `traceparent`, captured by the interceptor **at their write time**.
+     * Absent (not empty-string) means they set none — never sniffed back off the request.
+     */
+    consumerTraceparent?: string | null;
+    /** fetch-only. `mode` is a fetch concept XHR cannot express, so native never sets it. */
+    noCors?: boolean;
+};
+export type RequestTrace = {
+    /** The one header value to write, or nothing at all. Never a `flags=00` placeholder. */
+    header?: string;
+    finish: (endedAt: number) => TraceAttributes;
+};
+export declare class TraceManager {
+    private root?;
+    /** Bare hosts, punycode-normalized, ports ignored. Empty by default: v4 is dark on upgrade. */
+    private readonly allowlist;
+    /** Kept whether or not it is still the carrier: `app.start` reports it at any age. */
+    private launch;
+    /**
+     * @param launchStartMs what `app.start` reports as `span.start_time` — and **neither
+     * value is a fork time** (§6.2). Web passes `performance.timeOrigin` (true navigation
+     * start); native leaves it defaulted to `initialize()`, because everything before the
+     * JS bundle loads is invisible and JS cannot see process fork. Do not compare the two
+     * platforms' launch envelopes as if they measured the same interval.
+     */
+    constructor(launchStartMs?: number, traceHostAllowlist?: string[]);
+    /**
+     * §4.1's `sdk.trace_allowlist_size` — **count only, never the hosts**, so an operator can
+     * tell "nobody opted in" apart from "the header is being stripped" without the SDK
+     * shipping a customer's internal hostnames to the collector.
+     */
+    allowlistSize(): number;
+    /**
+     * `app.start`'s own row — a root, so `span.id === rum.action.id` and there is no
+     * `parent.span.id`. No `span.duration_ms` either: roots derive theirs server-side.
+     */
+    launchRootAttributes(): TraceAttributes;
+    /**
+     * Tier 1 for a `view`, captured at view **entry** — the action that opened the screen,
+     * not the one that closed it (§6.3). A **point span**: `span.start_time` and never
+     * `span.duration_ms`, because view dwell is not span duration and a width here would
+     * stretch every tap-that-navigates envelope across the whole time the user sat there.
+     */
+    viewSpan(entryAt: number): TraceAttributes;
+    /**
+     * Tier 1 for a `ui.interaction`, captured at the click's **mint** (§4.6/§6.2). The one
+     * unconditional mint in the table: a tap is a new user action by definition, so it
+     * *replaces* whatever root was live rather than joining it — which is what makes the
+     * request a tap fires a child of the tap and not of the route change before it.
+     *
+     * A root, so `span.id === rum.action.id`, no `parent.span.id`, and no `span.duration_ms`
+     * (§6.1 — a root's width is derived server-side).
+     */
+    interactionSpan(mintedAt: number): TraceAttributes;
+    /**
+     * Tier 1 for an `http.request`, captured at **send** — the root live then is the parent,
+     * and `span.start_time` is the send — plus §6.5's outcome ladder and the one header the
+     * SDK ever writes. Returns the finisher, so duration is stamped from the same pair of
+     * timestamps the row's `http.duration_ms` uses.
+     *
+     * ponytail: a `send()` that throws synchronously never calls the finisher, so a root it
+     * minted lives on for up to 2 s with no row describing it. Rare enough to leave; give
+     * the finisher a `discard()` sibling if the orphan ratio ever shows up.
+     */
+    requestTrace(startedAt: number, ctx: RequestTraceCtx): RequestTrace;
+    /**
+     * §6.5's ladder above the `injected_*` split, in table order — the precedence *is* the
+     * order of these returns. `undefined` means the attribute is omitted entirely: absent
+     * means not traced, which is the honest report for a consumer who never opted in and for
+     * a sampled-out session (which injects no header at all, not a `flags=00` id).
+     */
+    private decide;
+    /**
+     * Tier 2 — annotation-only (§6.3): join the trace without occupying a span. No
+     * `span.id`, no parent, no duration, and **no minting** — §6.2 lists the four events
+     * that mint and these are not among them, so an untraced crash carries no trace keys
+     * rather than inventing a root nothing else will ever join.
+     */
+    annotate(now?: number): TraceAttributes;
+    /**
+     * Drop the carrier. Background clears it on both builds, so a resumed app's first fetch
+     * mints its own root rather than joining an action from before the user left (§6.2);
+     * session rotation clears it because `trace.id` never spans a `session.id` (§6.6).
+     */
+    clear(): void;
+    /**
+     * Retire the launch root and mint a replacement, keeping the *reported* launch time —
+     * the process really did start then. For a session rotation that lands **before**
+     * `app.start`, which is the expired-record cold launch and therefore §4.3's most common
+     * path of all.
+     *
+     * Clearing alone would not do: `app.start` reports the launch root at any age, so its
+     * root row would ship under the **new** session while the initial `view` it fathered
+     * shipped under the **old** one. `trace.id` would span a `session.id` (§6.6, invariant 2)
+     * and `GROUP BY rum.action.id` would never reassemble the launch envelope. Re-minting
+     * keeps the retired trace wholly inside the retired session.
+     *
+     * ⚠ The retired trace then has children and no root row — the initial `view` row is a
+     * rootless child. That is the same condition process death already produces by design
+     * (a killed view emits nothing), and it is the cheaper of the two wrongs.
+     */
+    restartLaunchRoot(): void;
+    /**
+     * Join the live root, or mint one of `mintAs`. A span's *start* extends the root.
+     *
+     * `attribution` is read **before** `liveRoot()` drops an expired carrier, which is the
+     * only place the two unattributed causes are still distinguishable: a carrier that just
+     * aged out is `injected_expired` (context lost), no carrier at all is
+     * `injected_unattributed` (no action) — the split §6.5 asks the backend to keep.
+     */
+    private attach;
+    private mint;
+    /**
+     * The carrier if it is still live, dropping it otherwise. Both boundaries are strict —
+     * a root sitting exactly on one has not crossed it — matching the session boundaries.
+     *
+     * A **negative** delta is clamped to expired (§6.7): `Date.now()` can move backwards on
+     * an NTP correction, and reading that as "fresh" would hold one root open indefinitely.
+     */
+    private liveRoot;
+}

package/dist/src/adapters/uiInteraction.d.ts

@@ -0,0 +1,111 @@
+/** Rungs 2-5 are capped at 64 (§4.6). Rung 1 is not — see `resolveUiName`. */
+export declare const UI_NAME_MAX = 64;
+/**
+ * §4.6's three unnamed values, two of which live here. `unnamed` is an **instrumentation
+ * gap someone should close**; `surface` is whitespace with nothing to fix. Collapsing them
+ * into one recreates the original disease in miniature — `40% unnamed` with no way to tell
+ * a missing `data-edge-action-name` from people tapping padding.
+ */
+export declare const UI_UNNAMED = "unnamed";
+export declare const UI_SURFACE = "surface";
+/** Six values on web, two (`edge_action | none`) on native (§4.6). */
+export type UiNameSource = "edge_action" | "test_id" | "aria_label" | "title" | "text" | "none";
+/** The bare minimum of an element this module reads. */
+export type UiElement = {
+    tagName?: string;
+    getAttribute?(name: string): string | null;
+    textContent?: string | null;
+};
+export declare function isActionable(el: UiElement | undefined | null): boolean;
+/**
+ * Text entry and downloads are excluded from dead-click judgement (§4.6): typing mutates
+ * nothing the observer can see, and a download or a `_blank` anchor does its work outside
+ * this document entirely. Both would be false accusations.
+ */
+export declare function isDeadClickExempt(el: UiElement | undefined | null): boolean;
+/**
+ * Rungs 2-5's normalization (§4.6): trim, lowercase, non-alphanumeric → `_`, collapse runs,
+ * cap 64. Edge underscores are dropped too, so `"Add to cart!"` is `add_to_cart` and not
+ * `add_to_cart_` — a cap or a trailing `!` must not change the name a consumer sees.
+ * Returns `""` when nothing survived, which the ladder reads as "this rung had nothing".
+ */
+export declare function normalizeUiName(raw: string | null | undefined): string;
+/** What one click resolved to, before the trace and view snapshot are attached. */
+export type UiNameResolution = {
+    /** `ui.target` — a derived name, or `unnamed` / `surface` (§4.6). */
+    target: string;
+    nameSource: UiNameSource;
+    /** `ui.tag` — the *resolved* element's tag, lowercased; the click target when none resolved. */
+    tag: string;
+    /**
+     * The node rage identity is keyed on — the resolved element, or the raw target when
+     * nothing resolved. **Never the derived name** (§4.6): three clicks on three different
+     * `unnamed` divs are indistinguishable on the wire, which is the whole reason rage runs
+     * client-side.
+     */
+    node: unknown;
+    /** Whether the click landed on something role-actionable — the `ui.dead` gate. */
+    actionable: boolean;
+};
+/**
+ * §4.6's five-rung ladder, gated on element role.
+ *
+ * Rung 1 (`data-edge-action-name`) is scanned over the **whole** path, works on role-less
+ * elements, always wins, and passes through **unnormalized and uncapped** — it is explicit
+ * author intent and a consumer must be able to predict the value they just set. Rungs 2-5
+ * are read off the nearest role-actionable ancestor *only*, and normalized.
+ *
+ * @param path `composedPath()`, innermost first.
+ * @param pointerCursor whether the click target's computed cursor is `pointer` — the one
+ * signal that separates `unnamed` (a real control nobody instrumented) from `surface`.
+ */
+export declare function resolveUiName(path: readonly UiElement[], opts?: {
+    pointerCursor?: boolean;
+}): UiNameResolution;
+/**
+ * §4.6's key block, shared so a web click and a native tap cannot drift on a key name.
+ * Everything platform-specific is decided by the caller: web resolves the ladder against the
+ * DOM, native is handed the name outright.
+ *
+ * `ui.x`/`ui.y` default to `0` — the key is never-null in §4.6 and a keyboard activation
+ * (web) or a `trackTap(name)` (native) genuinely has no viewport coordinate. `ui.rage` is
+ * **omitted when false**, deliberately asymmetric with `ui.dead`, which the web caller adds
+ * later or not at all.
+ */
+export declare function uiAttributes(a: {
+    type: "click" | "tap";
+    target: string;
+    nameSource: UiNameSource;
+    tag: string;
+    x?: number;
+    y?: number;
+    rage?: boolean;
+}): Record<string, any>;
+/** §4.6's threshold: **≥3** clicks inside the window. */
+export declare const RAGE_CLICK_THRESHOLD = 3;
+/**
+ * §4.6 states the same 1000 ms as the dead-click window, but the two are **not the same
+ * constant** and must not be bound: the dead-click window is §4.5.2's `QUIET_WINDOW_MS`
+ * because the contract says so, and retuning network settle must not silently retune what
+ * counts as user frustration.
+ */
+export declare const RAGE_WINDOW_MS = 1000;
+/**
+ * ≥3 clicks within a sliding window **on the same live element node**, flagged **once per
+ * burst** on the crossing click — so `rage bursts = count of flagged rows` and a fourth and
+ * fifth angry click do not each mint their own burst.
+ *
+ * ⚠ Identity is the node reference the caller hands in, never `ui.target`. The tracker is
+ * per-`Telemetry`, so the node references it holds die with the page; it keeps at most
+ * `RAGE_CLICK_THRESHOLD` timestamps for one node at a time and drops the node the moment a
+ * click lands elsewhere, which is why there is no eviction policy to get wrong.
+ */
+export declare class RageTracker {
+    private readonly windowMs;
+    private node;
+    private hits;
+    private flagged;
+    constructor(windowMs: number);
+    /** @returns `true` on the click that crosses the threshold, and only that one. */
+    record(node: unknown, now: number): boolean;
+}

package/dist/src/adapters/viewManager.d.ts

@@ -0,0 +1,161 @@
+import { TraceAttributes } from './traceManager';
+/** §4.5.1's ladder. `none` is the literal `"unknown"` name, not an absent one. */
+export type ViewNameSource = "explicit" | "route" | "url" | "none";
+/** §4.5's four `view.load_type` values — one per lifetime boundary that mints a successor. */
+export type ViewLoadType = "initial_load" | "route_change" | "resume" | "session_rotation";
+/** `view.name` before anything has named the view. A literal, never null (§4.5.1). */
+export declare const UNKNOWN_VIEW_NAME = "unknown";
+/**
+ * How many retired views `nameOf()` can still name (§3.1). Bounded because an unbounded
+ * map is a leak on a long session; 16 because a span outliving that many boundaries is a
+ * request §4.5.2's 30 s settle cap has already given up on.
+ */
+export declare const MAX_RETIRED_VIEW_NAMES = 16;
+/**
+ * All ViewManager needs of core. Structural, so the manager stays unit-testable alone.
+ * `trace` is optional for that reason and for that reason only — every real `Telemetry`
+ * has one, and a view with no trace source simply carries no §6 keys.
+ */
+type Emitter = {
+    log(name: string, data?: Record<string, any>): unknown;
+    trace?: {
+        viewSpan(entryAt: number): TraceAttributes;
+    };
+};
+export declare class ViewManager {
+    private telemetry;
+    private view;
+    /** Origin only, and only where there is one — omitted on native (§4.5). */
+    private readonly host?;
+    /** §4.6's aliveness subscribers. Empty on native and on a web build with no DOM. */
+    private readonly activityListeners;
+    /** §5.1's boundary subscribers — the frame window, awaited before the successor mints. */
+    private readonly boundaryListeners;
+    /** Retired `view.id` → final `view.name`, for `nameOf()`. Bounded; oldest evicted. */
+    private readonly retiredNames;
+    constructor(telemetry: Emitter);
+    /** The two keys the Context block carries on every row. Name resolves at log time. */
+    get id(): string;
+    get name(): string;
+    /**
+     * §3.1 — `view.name` for a **frozen** `view.id`. A span-carrying row pins itself to the
+     * view live at span start, and its name is still resolved at log time, so an
+     * `http.request` that outlives a route change reports the departing view's *current*
+     * best name rather than a stale copy taken at send.
+     *
+     * ponytail: a bounded ring of retired names, not a full history. A span outliving
+     * `MAX_RETIRED_VIEW_NAMES` boundaries is a request the settle cap (30 s) already gave up
+     * on; it degrades to `"unknown"`, which is what a never-named view reports anyway.
+     */
+    nameOf(id: string): string;
+    /**
+     * The name ladder (§4.5.1), and the only path that mints a view from a *name*.
+     *
+     * - a **higher** rung re-stamps the name and never changes `view.id` — that is what
+     *   "rank beats order" means, and it is why a route name arriving after a URL-derived
+     *   one upgrades the view in place instead of splitting it in two;
+     * - a **lower** rung is ignored outright, whenever it arrives — ⚠ *including its
+     *   boundary*. A host that mixes rung 1 with `attachNavigation` therefore pins the view
+     *   to the `screenStart` name until the next `screenStart`: route changes stop minting
+     *   successors, and dwell keeps accruing under the explicit name. That is what §4.5.1's
+     *   "a lower rung arriving later does not overwrite a higher one" costs, and the two
+     *   rungs describing one navigation (the upgrade window) is the case it exists for.
+     *   It needs a contract ruling, not a local invention — see CLAUDE.md's known gaps;
+     * - the **same** rung naming a different screen is a genuine navigation, so it ends the
+     *   view and mints a successor.
+     *
+     * Rungs 1 and 2 are handed through unnormalized: a host naming a screen "Step 2 of 3"
+     * must not receive "Step {id} of {id}". The caller normalizes rung 3, not this method.
+     */
+    navigate(name: string, source: ViewNameSource): Promise<void>;
+    /** `view.error_count` — `app.crash` rows sharing this `view.id`. A closed enumeration. */
+    countError(): void;
+    /** `view.action_count` — interaction rows sharing this `view.id`. */
+    countAction(): void;
+    /**
+     * An HTTP request started (§4.5.2). Returns its completion callback, **bound to the view
+     * that was live at start** — a request that finishes after a route change belongs to the
+     * view it started in and does not hold the arriving one open. The collector's own POST
+     * never reaches here; the interceptors filter it before calling.
+     */
+    requestStarted(now?: number): (endedAt?: number) => void;
+    /**
+     * §4.6's dead-click gate, in the two places this manager already sees: a request started
+     * and a view minted (a route change, a resume, a session rotation). The web tracker adds
+     * DOM mutation on top, which it can observe on its own; these two it cannot.
+     *
+     * Deliberately fires for the background and rotation boundaries too. Those are not
+     * navigations the click caused, so counting them as aliveness **under-reports** dead
+     * clicks — which is the direction §4.6 requires: `ui.dead` must never falsely accuse.
+     *
+     * @returns an unsubscribe, so a tracker that is torn down does not keep the manager alive.
+     */
+    onActivity(fn: () => void): () => void;
+    private notifyActivity;
+    /**
+     * §5.1's view-boundary reset. A subscriber is **awaited inside `beginView`, before the
+     * successor replaces the current view**, so anything it emits is stamped with the
+     * departing `view.id`. That ordering is the whole feature: a fixed 10 s frame window
+     * straddling a route change otherwise charges the departing screen's dropped frames to
+     * the arriving one — backwards for the one query the metric exists to serve.
+     *
+     * ⚠ **It does not fire on the `session_rotation` boundary**, and that is deliberate.
+     * `newSession()` installs the new `session.id` *before* minting the successor view, so a
+     * row emitted there would carry the new `session.id` with the departing `view.id` — the
+     * one thing §4.5's "`view.id` never spans a `session.id`" forbids. Emitting *before* the
+     * rotation instead is worse: `logMetric` re-checks session expiry, `lastActivity` is
+     * still stale at that point, and the emit would rotate the session a second time. The
+     * accepted residue is a frame window that carries across a rotation — at most one
+     * unflushed window, of a session that ended by idleness.
+     *
+     * The successor's load type is handed to the subscriber so it can tell the two firing
+     * boundaries apart: `frame_render_time` wants both, while §5.3's running CLS/INP values
+     * want **`"resume"` — the background boundary — only**. Emitting a page-load-scoped vital
+     * at a soft navigation would ship a second row for the same page load and stamp it with
+     * a `view.id` that is not the initial view's.
+     *
+     * @returns an unsubscribe, so a torn-down subscriber does not keep the manager alive.
+     */
+    onBoundary(fn: (successorLoadType: ViewLoadType) => unknown): () => void;
+    /**
+     * The platform's runtime-ready marker — `loadEventEnd` on web,
+     * `performance.rnStartupTiming` on native — or `undefined` where the platform has none.
+     *
+     * Forwarded to whatever view is current, which is safe because a view that was never gated
+     * *ignores* the seed — enforced in `NetworkSettle`, not assumed here. On web the `load`
+     * event routinely arrives after the first route change, and flooring that view's settle at
+     * the page's load time would charge the launch's cost to a route change.
+     */
+    seedRuntimeReady(at?: number): void;
+    /**
+     * Emit the `view` event for the current view. Its `view.name` is authoritative and its
+     * `view.name_source` reports the *final* rung; the Context-block copy on rows emitted
+     * early in the view may still carry a lower rung's name (§4.5.1).
+     *
+     * `view.loading_time` is **omitted when null**, following this contract's general
+     * absent-means-the-SDK-had-nothing discipline (§4.11 names `navigation.from_screen` as the
+     * only explicit wire null). `view.loading_time_outcome` always ships: it is what tells the
+     * three null causes apart, and reading p75-of-settled beside %-capped is the whole point.
+     */
+    endView(): Promise<void>;
+    /**
+     * Mint the successor. Called directly by session rotation, which has to mint *after*
+     * the new `session.id` is in place — `view.id` never spans a `session.id` (§4.5).
+     * An unnamed successor carries the departing view's name: backgrounding and a session
+     * rotation do not move the user off the screen they were on.
+     */
+    beginView(successorLoadType: ViewLoadType, name?: string, source?: ViewNameSource): Promise<void>;
+    /** A boundary that stays inside one session: emit, then mint the successor. */
+    exit(successorLoadType: ViewLoadType, name?: string, source?: ViewNameSource): Promise<void>;
+    /**
+     * The background boundary. The successor is minted immediately — `view.id` must never
+     * be absent — but its clock starts paused, so a night spent backgrounded does not land
+     * as dwell on whatever screen the user left open.
+     */
+    background(): Promise<void>;
+    /** The matching foreground edge: re-arm the paused clock. */
+    foreground(): void;
+    private sinceResume;
+    private timeSpent;
+}
+export {};