react-native-nitro-tracing 0.6.0

package/lib/typescript/src/react/labels.d.ts

@@ -0,0 +1,203 @@
+export declare const defaultLabels: {
+    readonly applyFilters: "Apply";
+    readonly title: "Performance";
+    readonly searchMatch: "Search match";
+    readonly explore: "Explore";
+    readonly profiles: "Profiles";
+    readonly spans: "Spans";
+    readonly events: "events";
+    readonly actions: "Actions";
+    readonly tools: "Tools";
+    readonly back: "Back";
+    readonly done: "Done";
+    readonly details: "Details";
+    readonly cancel: "Cancel";
+    readonly filters: "Filters";
+    readonly sort: "Sort";
+    readonly reset: "Reset";
+    readonly exploreSearch: "Search";
+    readonly metricSearch: "Search metrics";
+    readonly newest: "Newest";
+    readonly oldest: "Oldest";
+    readonly longest: "Longest";
+    readonly shortest: "Shortest";
+    readonly errors: "Most errors";
+    readonly count: "Most samples";
+    readonly name: "Name";
+    readonly p95: "Highest p95";
+    readonly source: "Source";
+    readonly outcome: "Outcome";
+    readonly success: "Success";
+    readonly error: "Error";
+    readonly cancelled: "Cancelled";
+    readonly interrupted: "Interrupted";
+    readonly noErrors: "No recorded errors";
+    readonly minDuration: "Minimum duration (ms)";
+    readonly from: "From (ms since recording)";
+    readonly to: "To (ms since recording)";
+    readonly correlation: "Exact correlation ID";
+    readonly invalidRange: "Enter nonnegative numbers, with From no later than To.";
+    readonly resultCount: "{{matching}} / {{loaded}} matching";
+    readonly traceRow: "{{spans}} spans · {{errors}} errors · {{source}}";
+    readonly noResults: "No matching events. Change filters or reset to see the retained recording.";
+    readonly uncorrelated: "Uncorrelated";
+    readonly uncorrelatedHint: "{{count}} uncorrelated events are also available in Spans and Marks.";
+    readonly pauseUpdates: "Freeze view";
+    readonly resumeUpdates: "Resume live view";
+    readonly newEvents: "{{count}} new events";
+    readonly detailFrozen: "Detail is held steady while capture continues. Return to load newer events.";
+    readonly expandAll: "Expand all";
+    readonly collapseAll: "Collapse all";
+    readonly missingParent: "Parent is outside retained history.";
+    readonly wholeTrace: "Show entire trace";
+    readonly similar: "Find similar spans";
+    readonly parent: "Parent";
+    readonly children: "Children";
+    readonly attributes: "Search attributes";
+    readonly evicted: "This event is outside retained history. Showing the last inspected snapshot.";
+    readonly all: "All";
+    readonly runtime: "Runtime";
+    readonly custom: "Custom";
+    readonly metricBrief: "p95 {{p95}} · n={{count}}";
+    readonly metricSortNotice: "All retained traces. Numeric sorting compares raw values; check units when comparing series.";
+    readonly exportAll: "Recording JSON (stops recording)";
+    readonly sharePerfetto: "Perfetto trace";
+    readonly replaceTitle: "Replace current recording?";
+    readonly replaceDescription: "Start a new recording and discard the currently retained history. Export first to keep a copy.";
+    readonly retainedScope: "Counts and statistics cover retained history. Pause updates freezes this view, not recording or profiling.";
+    readonly lostHistory: "Lost {{what}}; this history is incomplete.";
+    readonly lostSpans: "{{count}} spans";
+    readonly lostMarks: "{{count}} marks";
+    readonly lostMetrics: "{{count}} metric samples";
+    readonly slowest: "Slowest spans";
+    readonly errorsOnly: "Errors";
+    readonly profileSeparate: "CPU profiles are separate from trace JSON. Stop sampling to save and share the latest artifact.";
+    readonly noProfiler: "No CPU profiler is configured for this client.";
+    readonly eyebrow: "DEVELOPER TOOLS";
+    readonly close: "Close";
+    readonly recording: "Recording live";
+    readonly stopped: "Recording stopped";
+    readonly counters: "{{events}} events · {{active}} active · {{dropped}} dropped · {{bytes}} bytes";
+    readonly start: "Start recording";
+    readonly stop: "Stop recording";
+    readonly clear: "Clear";
+    readonly export: "Stop & export";
+    readonly retention: "Bounded native history · refreshes while open";
+    readonly traces: "Traces";
+    readonly search: "Search operation or correlation ID";
+    readonly traceSummary: "{{duration}} ms · {{events}} events · {{errors}} errors";
+    readonly empty: "No traces yet. Use the app to capture activity.";
+    readonly waterfall: "Span waterfall";
+    readonly noSpans: "No completed spans in this trace.";
+    readonly spanDetails: "Span {{id}} · parent {{parent}} · {{outcome}}";
+    readonly metrics: "Metrics";
+    readonly operations: "Operation outcomes";
+    readonly operationsShort: "Operations";
+    readonly operationStats: "{{count}} spans · {{errors}} errors · {{errorRate}} error rate · {{cancelled}} cancelled · {{interrupted}} interrupted";
+    readonly metricsScope: "All traces · app.ready.after_tracer_init measures tracer setup to app readiness, not TTI. duration: series are derived from completed spans. Statistics cover retained samples, not the whole session.";
+    readonly emptyMetrics: "No samples yet. Use the app or run the playground. App-ready timing appears after a fresh launch; TTI requires an explicit readiness definition.";
+    readonly metricStats: "Latest {{latest}} · median {{median}} · min {{min}} · max {{max}} · p95 {{p95}} · {{count}} samples";
+    readonly marks: "Marks";
+    readonly playground: "Instrumentation playground";
+    readonly playgroundDescription: "Check nested spans, concurrent operations with the same name, cancellation, repeated completion, errors and metrics.";
+    readonly run: "Run sample trace";
+    readonly profiling: "CPU profile";
+    readonly profilingDescription: "Capture a native profiler artifact alongside this recording.";
+    readonly startProfile: "Start CPU profile";
+    readonly stopProfile: "Stop CPU profile";
+    readonly shareProfile: "CPU profile";
+    readonly shareArtifact: "Share performance recording";
+    readonly sharingUnavailable: "File sharing is unavailable on this device.";
+    readonly cacheUnavailable: "The application cache is unavailable.";
+    readonly truncated: "Showing up to 100 traces, spans and marks, and 40 metric series. Search to narrow traces; export includes all retained events.";
+    readonly overview: "Summary";
+    readonly tabs: "Inspector views";
+    readonly recordingSummary: "Recording summary";
+    readonly summary: "{{traces}} traces · {{spans}} spans · {{marks}} marks · {{metrics}} metric samples loaded";
+    readonly session: "Session {{id}} · elapsed {{elapsed}} ms";
+    readonly metricWindow: "Showing {{displayed}} / {{retained}} loaded samples · {{start}}–{{end}} ms since recording start";
+    readonly passed: "PASS";
+    readonly failed: "FAIL";
+    readonly scenarioResults: "Scenario results";
+    readonly scenarioNotice: "Checks inspect retained native events; dropped or expired samples can fail a check.";
+    readonly scenarioNested: "Explicit parent hierarchy";
+    readonly scenarioConcurrency: "Overlapping spans with the same name";
+    readonly scenarioCancelled: "Cancelled outcome";
+    readonly scenarioIdempotent: "Repeated completion records once";
+    readonly scenarioError: "Error outcome";
+    readonly scenarioMetrics: "Native metric values";
+    readonly openScenario: "Open scenario trace";
+    readonly timeline: "Timeline";
+    readonly issues: "Issues: {{count}}";
+    readonly noIssues: "Nothing over budget in retained history.";
+    readonly summaryScope: "Issues compare retained events with local budgets, not production percentiles. Tap a topic to explore it.";
+    readonly moreIssues: "{{count}} more in Explore";
+    readonly issueValue: "{{value}} ms · budget {{budget}} ms";
+    readonly notTracked: "Not tracked";
+    readonly quiet: "No events yet";
+    readonly topicStartup: "Startup";
+    readonly topicScreens: "Screens";
+    readonly topicNetwork: "Network";
+    readonly topicResponsiveness: "Responsiveness";
+    readonly topicErrors: "Errors";
+    readonly topicCustom: "Custom spans";
+    readonly headlineStartup: "App ready {{value}} after tracer init";
+    readonly headlineScreens: "{{count}} visits · p95 transition {{value}}";
+    readonly headlineNetwork: "{{count}} requests · p95 {{value}}";
+    readonly headlineResponsiveness: "{{count}} stalls over {{budget}} ms";
+    readonly headlineErrors: "{{count}} errors";
+    readonly headlineCustom: "{{count}} spans";
+    readonly hintStartup: "Call useAppReadyMetric(client, ready) from /react.";
+    readonly hintScreens: "Add createNavigationPlugin(navigationRef) from /plugins.";
+    readonly hintNetwork: "Add createNetworkPlugin() from /plugins.";
+    readonly hintResponsiveness: "Add createNativeMetricsPlugin(), Sentry frames, or runtimeMetrics: true.";
+    readonly hintErrors: "Add createErrorsPlugin() from /plugins.";
+    readonly hintCustom: "Use client.trace or native spans.";
+    readonly issueSlowStartup: "Slow startup";
+    readonly issueSlowScreen: "Slow screen";
+    readonly issueSlowRequest: "Slow request";
+    readonly issueFailedRequest: "Failed request";
+    readonly issueStall: "JS stall";
+    readonly issueError: "Error";
+    readonly beforeNavigation: "Before first screen";
+    readonly liveAllActivity: "All activity";
+    readonly liveInspector: "Inspector";
+    readonly liveRequests: "requests";
+    readonly liveStalls: "stalls";
+    readonly liveErrors: "errors";
+    readonly liveEmpty: "No activity on this screen yet. Use the app; events stream in here.";
+    readonly topicResources: "Resources";
+    readonly headlineResources: "CPU {{cpu}}% · {{memory}} MB";
+    readonly hintResources: "Add createNativeMetricsPlugin() from /plugins.";
+    readonly issueUiStall: "UI stall";
+    readonly issueFrozenFrames: "Frozen frames";
+    readonly liveFlag: "Flag";
+    readonly liveShare: "Share trace";
+    readonly liveFlagged: "Flagged";
+    readonly share: "Share";
+    readonly more: "More";
+    readonly shareTitle: "Share recording";
+    readonly startNew: "Start new recording";
+    readonly frozen: "Frozen";
+    readonly topics: "Topics";
+    readonly sortBy: "Sort: {{sort}}";
+    readonly filter: "Filter";
+    readonly range: "Range";
+    readonly stat_latest: "Latest";
+    readonly stat_median: "Median";
+    readonly stat_p95: "p95";
+    readonly stat_min: "Min";
+    readonly stat_max: "Max";
+    readonly samples: "Samples";
+    readonly duration: "Duration";
+    readonly time: "Time";
+    readonly spanId: "Span ID";
+    readonly correlationId: "Correlation ID";
+    readonly attributeSearch: "Search attributes";
+};
+export type InspectorLabels = {
+    [K in keyof typeof defaultLabels]: string;
+};
+export type InspectorLabelKey = keyof InspectorLabels;
+export type InspectorTranslator = (key: InspectorLabelKey, values?: Record<string, unknown>) => string;
+export declare const createTranslator: (labels?: Partial<InspectorLabels>) => InspectorTranslator;

package/lib/typescript/src/react/native.d.ts

@@ -0,0 +1,42 @@
+import React, { type ReactNode } from 'react';
+import { type ColorValue, type StyleProp, type ViewStyle } from 'react-native';
+import { type SheetOption } from './InspectorControls';
+export interface MenuConfig {
+    title?: string;
+    options: SheetOption[];
+    cancelLabel: string;
+}
+/**
+ * `open(config)` shows a native action sheet on iOS (UIAlertController, Liquid Glass on
+ * iOS 26) and the RN sheet elsewhere; render `element` once in the calling component.
+ */
+export declare function useMenu(): {
+    open: (next: MenuConfig) => void;
+    element: React.JSX.Element | null;
+};
+export interface NativeTab<K extends string> {
+    key: K;
+    title: string;
+    /** SF Symbol name for the native iOS tab bar. */
+    sfSymbol: string;
+    badge?: string;
+    render: () => ReactNode;
+}
+/**
+ * Native tab bar (UITabBarController / Material) when react-native-bottom-tabs is
+ * installed; inactive screens are lazy and frozen so live ticks only render the visible tab.
+ */
+export declare function NativeTabs<K extends string>({ tabs, value, onChange, tint, fallback, }: {
+    tabs: NativeTab<K>[];
+    value: K;
+    onChange: (key: K) => void;
+    tint: ColorValue;
+    fallback: (content: ReactNode) => ReactNode;
+}): React.JSX.Element;
+/** Liquid Glass surface on iOS 26 (expo-glass-effect); a solid fallback elsewhere. */
+export declare function Glass({ style, fallbackColor, children, interactive, }: {
+    style?: StyleProp<ViewStyle>;
+    fallbackColor: ColorValue;
+    children?: ReactNode;
+    interactive?: boolean;
+}): React.JSX.Element;

package/lib/typescript/src/react/readSnapshot.d.ts

@@ -0,0 +1,4 @@
+import type { Recording } from '../specs/Recording.nitro';
+import type { TracePage } from '../types';
+/** Bound work to retained history at read start, not an arbitrary UI result limit. */
+export declare function readSnapshot(recording: Recording, previous?: TracePage): Promise<TracePage>;

package/lib/typescript/src/react/store.d.ts

@@ -0,0 +1,9 @@
+/** Minimal external store so only subscribed components rerender on telemetry ticks. */
+export interface Store<T> {
+    get(): T;
+    set(patch: Partial<T>): void;
+    subscribe(listener: () => void): () => void;
+}
+export declare function createStore<T extends object>(initial: T): Store<T>;
+/** Selectors must return primitives or existing references. */
+export declare const useStore: <T, S>(store: Store<T>, select: (value: T) => S) => S;

package/lib/typescript/src/react/topics.d.ts

@@ -0,0 +1,80 @@
+import type { MarkEvent, MetricEvent, SpanEvent, TracePage } from '../types';
+export type TopicId = 'startup' | 'screens' | 'network' | 'responsiveness' | 'resources' | 'errors' | 'custom';
+export declare const topicIds: TopicId[];
+/** Text-presentation glyphs (no color emoji) and system tints per topic. */
+export declare const topicGlyph: Record<TopicId, {
+    icon: string;
+    color: string;
+}>;
+/** Local triage thresholds, not production SLOs. */
+export interface Budgets {
+    appReadyMs: number;
+    screenMs: number;
+    requestMs: number;
+    stallMs: number;
+}
+export declare const defaultBudgets: Budgets;
+export type AnyEvent = SpanEvent | MarkEvent | MetricEvent;
+export type IssueKind = 'slowStartup' | 'slowScreen' | 'slowRequest' | 'failedRequest' | 'stall' | 'uiStall' | 'frozenFrames' | 'error';
+export interface Issue {
+    kind: IssueKind;
+    topic: TopicId;
+    title: string;
+    valueMs?: number;
+    budgetMs?: number;
+    event: AnyEvent;
+    /** Errors outrank budget overruns; overruns rank by value / budget. */
+    severity: number;
+}
+export interface TopicSummary {
+    id: TopicId;
+    /** A collector is configured or the topic has events. */
+    tracked: boolean;
+    count: number;
+    /** Nearest-rank p95 (screens: transition, network: duration) or latest app-ready. */
+    value?: number;
+    /** Extra headline values, e.g. resources: latest cpu and memory. */
+    values?: Record<string, string>;
+    issues: Issue[];
+}
+export declare const attribute: (event: AnyEvent, key: string) => string | undefined;
+export declare const topicOf: (event: AnyEvent) => TopicId;
+export declare const summarizeTopics: (page: TracePage, collectors: readonly string[], budgets?: Budgets) => {
+    topics: TopicSummary[];
+    issues: Issue[];
+};
+export type TimelineItem = {
+    kind: 'screen';
+    key: string;
+    name: string;
+    timestampMs: number;
+} | {
+    kind: 'event';
+    key: string;
+    event: AnyEvent;
+    topic: TopicId;
+    issue: boolean;
+};
+/**
+ * Newest screen visit first, each followed by its events newest first. Visits come from
+ * `navigation.enter` marks, so the active screen appears before its visit span completes.
+ * Metrics are listed only when they are issues; periodic samples belong in Metrics.
+ */
+export declare const buildTimeline: (page: TracePage, issues: readonly Issue[], limit?: number) => TimelineItem[];
+export declare const currentScreen: (page: TracePage) => string | undefined;
+export interface VisitSummary {
+    /** Undefined when no navigation collector has recorded a screen yet. */
+    screen?: string;
+    sinceMs?: number;
+    events: Extract<TimelineItem, {
+        kind: 'event';
+    }>[];
+    requests: number;
+    stalls: number;
+    errors: number;
+    issues: number;
+}
+/** The newest screen visit in a timeline: what happened on the screen the user is looking at. */
+export declare const currentVisit: (items: readonly TimelineItem[]) => VisitSummary;
+/** Latest sample of a metric by name; undefined when not collected. */
+export declare const latestMetric: (page: TracePage, name: string) => number | undefined;

package/lib/typescript/src/react/useAppReadyMetric.d.ts

@@ -0,0 +1,3 @@
+import type { TraceClient } from '../client/createTraceClient';
+/** Report the consumer's ready signal after a frame opportunity. Not native launch time or guaranteed TTI. */
+export declare function useAppReadyMetric(client: TraceClient, ready: boolean): void;

package/lib/typescript/src/react/useLiveRecording.d.ts

@@ -0,0 +1,4 @@
+import type { TraceClient } from '../client/createTraceClient';
+import type { TracePage } from '../types';
+/** Incremental polling of the active recording; unchanged snapshots keep their identity. */
+export declare function useLiveRecording(client: TraceClient, active: boolean, intervalMs?: number): TracePage | undefined;

package/lib/typescript/src/react/useTraceViewer.d.ts

@@ -0,0 +1,140 @@
+import type { TraceClient } from '../client/createTraceClient';
+import type { RecordingStats, TracePage, SpanEvent, MarkEvent } from '../types';
+import { type ExplorerMode, type Query, type Trace } from './explorerModel';
+import { recordingMetrics } from './viewerModel';
+import { type Budgets } from './topics';
+export type Metric = ReturnType<typeof recordingMetrics>[number];
+export type Detail = {
+    kind: 'trace';
+    value: Trace;
+} | {
+    kind: 'span';
+    value: SpanEvent;
+} | {
+    kind: 'mark';
+    value: MarkEvent;
+} | {
+    kind: 'metric';
+    value: Metric;
+};
+export type Tab = 'overview' | 'timeline' | 'explore' | 'metrics' | 'tools';
+export interface Telemetry {
+    stats?: RecordingStats;
+    error?: string;
+    pending?: Pick<TracePage, 'nextSequence' | 'earliestSequence'>;
+}
+export declare const useTraceViewer: (client: TraceClient, budgets?: Partial<Budgets>) => {
+    client: {
+        reportAppReady(): void;
+        trace: {
+            mark(name: string, attributes?: import("../client/createTraceClient").ClientAttributes): void;
+            metric(name: string, value: number | string, attributes?: import("../client/createTraceClient").ClientAttributes): void;
+            measure<T>(name: string, fn: () => Promise<T>, attributes?: import("../client/createTraceClient").ClientAttributes): Promise<T>;
+            measureSince(name: string, startName: string, id: string, attributes?: import("../client/createTraceClient").ClientAttributes): void;
+            clear(id: string): void;
+        };
+        start: () => Promise<void>;
+        stop: () => Promise<void>;
+        clear: () => Promise<void>;
+        getRecording: () => import("..").Recording | undefined;
+        getError: () => string | undefined;
+        getSnapshot: () => import("../client/createTraceClient").TraceClientSnapshot;
+        subscribe(listener: () => void): () => void;
+        open(): void;
+        close(): void;
+        reportError: (error: unknown) => void;
+        canShare: boolean;
+        canProfile: boolean;
+        canShareProfile: boolean;
+        export: () => Promise<void>;
+        shareTrace: (format?: import("../client/createTraceClient").TraceFormat) => Promise<void>;
+        flag: (note?: string) => void;
+        toggleProfile: () => Promise<void>;
+        shareProfile: () => Promise<void>;
+        playground: () => Promise<void>;
+        dispose(): Promise<void>;
+    };
+    tab: Tab;
+    setTab: (next: Tab) => void;
+    mode: ExplorerMode;
+    setMode: import("react").Dispatch<import("react").SetStateAction<ExplorerMode>>;
+    page: TracePage;
+    telemetry: import("./store").Store<Telemetry>;
+    traces: Trace[];
+    topics: import("./topics").TopicSummary[];
+    issues: import("./topics").Issue[];
+    timeline: import("./topics").TimelineItem[];
+    screen: string | undefined;
+    results: import("./explorerModel").Event[] | Trace[];
+    query: Query;
+    updateQuery: (patch: Partial<Query>) => void;
+    resetQuery: () => void;
+    loaded: number;
+    uncorrelated: number;
+    detail: Detail;
+    detailState: import("react").RefObject<Record<string, {
+        collapsed: string[];
+        layout: "waterfall" | "list";
+        attributes: string;
+        offset: number;
+    }>>;
+    details: Detail[];
+    open: (next: Detail) => void;
+    back: () => void;
+    traceFor: (span: SpanEvent) => Trace | undefined;
+    showSpans: (patch: Partial<Query>) => void;
+    showMarks: (patch: Partial<Query>) => void;
+    paused: boolean;
+    holding: boolean;
+    setHolding: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    apply: () => void;
+    togglePause: () => void;
+    offsets: import("react").RefObject<Record<string, number>>;
+    metrics: {
+        latest: number;
+        median: number;
+        min: number;
+        peak: number;
+        p95: number;
+        name: string;
+        metric: string;
+        unit: string;
+        samples: import("..").MetricEvent[];
+        retainedCount: number;
+        startMs: number;
+        endMs: number;
+        max: number;
+    }[];
+    operations: {
+        name: string;
+        count: number;
+        errors: number;
+        errorRate: number | undefined;
+        cancelled: number;
+        interrupted: number;
+    }[];
+    metricQuery: string;
+    setMetricQuery: import("react").Dispatch<import("react").SetStateAction<string>>;
+    metricCategory: string;
+    setMetricCategory: import("react").Dispatch<import("react").SetStateAction<string>>;
+    metricSort: string;
+    setMetricSort: import("react").Dispatch<import("react").SetStateAction<string>>;
+    start: () => void;
+    stop: () => void;
+    export: () => void;
+    sharePerfetto: () => void;
+    toggleProfile: () => void;
+    shareProfile: () => void;
+    playground: () => void;
+    playgroundResult: import("../client/playground").PlaygroundReport | undefined;
+    openPlayground: () => void;
+    visible: boolean;
+    recording: boolean;
+    busy: boolean;
+    disposed: boolean;
+    error?: string;
+    profiling: boolean;
+    profilePath?: string;
+    collectors?: string[];
+};
+export type Viewer = ReturnType<typeof useTraceViewer>;

package/lib/typescript/src/react/viewerModel.d.ts

@@ -0,0 +1,59 @@
+import type { MetricEvent, SpanEvent, TracePage } from '../types';
+export interface TraceGroup {
+    id: string;
+    name: string;
+    start: number;
+    duration: number;
+    errors: number;
+    events: number;
+}
+export declare const groupTraces: (page: TracePage, query: string) => TraceGroup[];
+export declare const waterfall: (spans: SpanEvent[]) => {
+    span: SpanEvent;
+    depth: number;
+    offset: number;
+    width: number;
+}[];
+/** Human value with unit: 3653 ms → "3.65 s", 1240 MB → "1.21 GB". */
+export declare const formatMetric: (value: number, unit: string) => string;
+export declare const metricSeries: (metrics: MetricEvent[]) => {
+    latest: number;
+    median: number;
+    min: number;
+    peak: number;
+    p95: number;
+    name: string;
+    /** Metric name without the unit suffix used for grouping. */
+    metric: string;
+    unit: string;
+    samples: MetricEvent[];
+    retainedCount: number;
+    startMs: number;
+    endMs: number;
+    max: number;
+}[];
+/** Durations are derived from retained completed spans, not additional native samples. */
+export declare const recordingMetrics: (page: TracePage) => {
+    latest: number;
+    median: number;
+    min: number;
+    peak: number;
+    p95: number;
+    name: string;
+    /** Metric name without the unit suffix used for grouping. */
+    metric: string;
+    unit: string;
+    samples: MetricEvent[];
+    retainedCount: number;
+    startMs: number;
+    endMs: number;
+    max: number;
+}[];
+export declare const operationMetrics: (spans: SpanEvent[]) => {
+    name: string;
+    count: number;
+    errors: number;
+    errorRate: number | undefined;
+    cancelled: number;
+    interrupted: number;
+}[];

package/lib/typescript/src/specs/Recording.nitro.d.ts

@@ -0,0 +1,31 @@
+import type { HybridObject } from 'react-native-nitro-modules';
+import type { TraceSpan } from './TraceSpan.nitro';
+import type { CompletedSpanOptions, SpanOptions, MarkOptions, MetricOptions, ReadOptions, TracePage, RecordingStats, NativeSamplingOptions } from '../types';
+/** Owns bounded native history. Stop before export; dispose when all readers are done. */
+export interface Recording extends HybridObject<{
+    ios: 'c++';
+    android: 'c++';
+}> {
+    /** Start a span, optionally linked to an explicit parent. */
+    startSpan(options: SpanOptions): TraceSpan;
+    /** Import a completed measurement; returns its native span identity. */
+    recordSpan(options: CompletedSpanOptions): string;
+    /** Append a point event. */
+    mark(options: MarkOptions): void;
+    /** Append a finite numeric sample with units. */
+    recordMetric(options: MetricOptions): void;
+    /** Read at most 1000 completed events without per-event callbacks. */
+    readEvents(options: ReadOptions): Promise<TracePage>;
+    /** Read cheap recording counters and clock anchor. */
+    getStats(): RecordingStats;
+    /** Freeze history and close active spans as interrupted. Idempotent. */
+    stop(): void;
+    /** Serialize a snapshot off the JS thread; includes schema version and clock anchor. */
+    exportJson(): Promise<string>;
+    /** Chrome Trace Event JSON for ui.perfetto.dev; serialized off the JS thread. */
+    exportTraceEvents(): Promise<string>;
+    /** Start a native thread writing process.cpu, process.memory and ui.* frame metrics. Replaces a running sampler. */
+    startNativeSampling(options: NativeSamplingOptions): void;
+    /** Stop native sampling. Idempotent; stop() and dispose() also stop it. */
+    stopNativeSampling(): void;
+}

package/lib/typescript/src/specs/TraceSpan.nitro.d.ts

@@ -0,0 +1,14 @@
+import type { HybridObject } from 'react-native-nitro-modules';
+import type { SpanOutcome } from '../types';
+/** A native span handle returned by Recording.startSpan. */
+export interface TraceSpan extends HybridObject<{
+    ios: 'c++';
+    android: 'c++';
+}> {
+    /** Empty when rejected by capacity limits. */
+    readonly spanId: string;
+    /** Whether capacity allowed this span to be recorded. */
+    readonly recorded: boolean;
+    /** Complete once. Repeated completion and completion after stop are no-ops. */
+    end(outcome: SpanOutcome): void;
+}

package/lib/typescript/src/specs/Tracing.nitro.d.ts

@@ -0,0 +1,17 @@
+import type { HybridObject } from 'react-native-nitro-modules';
+import type { Recording } from './Recording.nitro';
+import type { RecordingOptions } from '../types';
+/** Factory for independent native recordings. Exported as Tracing. */
+export interface Tracing extends HybridObject<{
+    ios: 'c++';
+    android: 'c++';
+}> {
+    /** Create an active recording with explicit validated retention limits. */
+    startRecording(options: RecordingOptions): Recording;
+    /**
+     * Stop Hermes' process-wide sampling profiler. The release-profiler plugin calls this
+     * after saving a profile: on React Native 0.85 Android the profiler's own stop restarts
+     * sampling. Returns false where Hermes is not linked (iOS stops correctly itself).
+     */
+    disableHermesSampling(): boolean;
+}

package/lib/typescript/src/types/CompletedSpanOptions.d.ts

@@ -0,0 +1,15 @@
+import type { SpanOutcome } from './SpanOutcome';
+import type { SpanOptions } from './SpanOptions';
+/** Completed external measurement in Recording's native clock domain. */
+export interface CompletedSpanOptions extends SpanOptions {
+    /** Optional source-qualified identity, for example sentry:traceId:spanId. */
+    sourceSpanId?: string;
+    /** Source-qualified parent identity; resolves even when parent ends later. */
+    sourceParentSpanId?: string;
+    /** Start in milliseconds relative to recording creation. */
+    timestampMs: number;
+    /** Finite nonnegative duration. */
+    durationMs: number;
+    /** Terminal result from the measurement source. */
+    outcome: SpanOutcome;
+}

package/lib/typescript/src/types/EventContext.d.ts

@@ -0,0 +1,8 @@
+import type { TraceContext } from './TraceContext';
+/** Immutable native event identity and timing shared by recorded variants. */
+export interface EventContext extends TraceContext {
+    /** Increasing session-local completion sequence. */
+    sequence: number;
+    /** Milliseconds since recording creation on its native monotonic clock. */
+    timestampMs: number;
+}

package/lib/typescript/src/types/MarkEvent.d.ts

@@ -0,0 +1,4 @@
+import type { EventContext } from './EventContext';
+/** Point-in-time event from Recording.readEvents. */
+export interface MarkEvent extends EventContext {
+}

package/lib/typescript/src/types/MarkOptions.d.ts

@@ -0,0 +1,6 @@
+import type { TraceContext } from './TraceContext';
+/** Native mark, optionally imported with a translated source timestamp. */
+export interface MarkOptions extends TraceContext {
+    /** Milliseconds in the recording clock; omit to record now. */
+    timestampMs?: number;
+}