react-native-nitro-tracing 0.6.0

package/lib/typescript/src/plugins/performance.d.ts

@@ -0,0 +1,13 @@
+import type { TracingEntry } from '../client/TracingSink';
+import type performance from 'react-native-performance';
+import type { PerformanceObserver } from 'react-native-performance';
+import type { TracePlugin } from './TracePlugin';
+/** Default measurement-source dependencies; supports the installed RN performance API. */
+export interface PerformancePluginOptions {
+    /** Same clock used by the supplied observer's entries. */
+    performance: typeof performance;
+    /** PerformanceObserver from react-native-performance. */
+    PerformanceObserver: typeof PerformanceObserver;
+}
+/** Observe user timing without patching globals, clearing shared buffers or timing network bodies. */
+export declare function createPerformancePlugin(api: PerformancePluginOptions, onEntry?: (entry: TracingEntry) => void): TracePlugin;

package/lib/typescript/src/plugins/releaseProfiler.d.ts

@@ -0,0 +1,25 @@
+import type { TracePlugin } from './TracePlugin';
+/** Injected optional react-native-release-profiler module; never imported by core. */
+export interface ReleaseProfilerApi {
+    /** Start the process-wide Hermes sampler; false means unavailable. */
+    startProfiling(): boolean | void;
+    /** Stop and save a local profile artifact. */
+    stopProfiling(saveToDownloads?: boolean): Promise<string>;
+}
+/** Manually controlled profiler integration. Sampling never starts on plugin setup. */
+export interface ReleaseProfilerPlugin extends TracePlugin {
+    /** Start one session owned by this plugin. */
+    startProfiling(): void;
+    /** Finish profiling and return the artifact's local path. */
+    stopProfiling(): Promise<string>;
+    /** Whether this plugin owns an active or stopping profile. */
+    isProfiling(): boolean;
+    /** Last successful artifact; not sent to remote exporters. */
+    getProfilePath(): string | undefined;
+}
+export interface ReleaseProfilerOptions {
+    /** Runs after every stop. Defaults to Tracing.disableHermesSampling(). */
+    stopSampler?: () => void;
+}
+/** Attach manual Hermes profile controls to a recording. */
+export declare function createReleaseProfilerPlugin(api: ReleaseProfilerApi, options?: ReleaseProfilerOptions): ReleaseProfilerPlugin;

package/lib/typescript/src/plugins/runtimeMetrics.d.ts

@@ -0,0 +1,17 @@
+import type { TracePlugin } from './TracePlugin';
+export interface RuntimeMetricsOptions {
+    /** Reporting interval in ms, minimum 250; default 1000. */
+    intervalMs?: number;
+    /** Observe JS requestAnimationFrame callbacks (not native UI frames). Default true. */
+    frames?: boolean;
+}
+/** Injectable clock/lifecycle surface for deterministic tests and alternate hosts. */
+export interface RuntimeMetricsHost {
+    now(): number;
+    isActive(): boolean;
+    subscribe(listener: (active: boolean) => void): () => void;
+    requestFrame(callback: () => void): number;
+    cancelFrame(id: number): void;
+}
+/** Low-volume foreground JS health samples. No per-frame native calls or UI FPS claims. */
+export declare function createRuntimeMetricsPlugin(options?: RuntimeMetricsOptions, host?: RuntimeMetricsHost): TracePlugin;

package/lib/typescript/src/plugins/sentry.d.ts

@@ -0,0 +1,15 @@
+import type * as Sentry from '@sentry/react-native';
+import type { TracePlugin } from './TracePlugin';
+/** Optional Sentry capabilities; SDK initialization and consent remain app-owned. */
+export interface SentryPluginOptions {
+    /** Inject an installed SDK. This module has no runtime SDK dependency. */
+    sentry: Pick<typeof Sentry, 'getClient' | 'spanToJSON' | 'startInactiveSpan'>;
+    /** Capture observable SDK spans locally. Defaults to false; sampling applies. */
+    captureSpans?: boolean;
+    /** Explicitly opt into sending retained span names/timing/status to Sentry on stop. Defaults to false. */
+    exportSpans?: boolean;
+    /** Only these sanitized custom attribute keys may leave the device. Defaults to none. */
+    exportedAttributeKeys?: readonly string[];
+}
+/** Optional SDK measurements and opt-in export; neither direction is enabled implicitly. */
+export declare function createSentryPlugin(options: SentryPluginOptions): TracePlugin;

package/lib/typescript/src/plugins/startPlugins.d.ts

@@ -0,0 +1,4 @@
+import type { Recording } from '../specs/Recording.nitro';
+import type { PluginHandle, TracePlugin } from './TracePlugin';
+/** Start optional integrations. Failures are isolated; stop waits for all cleanup. */
+export declare function startPlugins(recording: Recording, plugins: readonly TracePlugin[], onError: (error: unknown) => void): PluginHandle;

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

@@ -0,0 +1,11 @@
+import React from 'react';
+import type { Metric, Viewer } from './useTraceViewer';
+import type { InspectorTranslator } from './labels';
+export declare function MetricDetail({ series, t, }: {
+    series: Metric;
+    t: InspectorTranslator;
+}): React.JSX.Element;
+export declare function DetailView({ v, t }: {
+    v: Viewer;
+    t: InspectorTranslator;
+}): React.JSX.Element;

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

@@ -0,0 +1,9 @@
+import React from 'react';
+import type { Viewer } from './useTraceViewer';
+import type { InspectorTranslator } from './labels';
+/** Draft filters: Apply commits them, Cancel discards them. Sorting lives in its own menu. */
+export declare function ExplorerFilters({ v, t, close, }: {
+    v: Viewer;
+    t: InspectorTranslator;
+    close: () => void;
+}): React.JSX.Element;

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

@@ -0,0 +1,9 @@
+import React from 'react';
+import type { InspectorTranslator } from './labels';
+import type { Viewer } from './useTraceViewer';
+import { type Sort } from './explorerModel';
+export declare const sortsFor: (mode: Viewer["mode"]) => Sort[];
+export declare function ExplorerView({ v, t }: {
+    v: Viewer;
+    t: InspectorTranslator;
+}): React.JSX.Element;

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

@@ -0,0 +1,229 @@
+import React from 'react';
+export declare const palette: {
+    bg: string;
+    panel: string;
+    line: string;
+    text: string;
+    muted: string;
+    accent: string;
+    selected: string;
+    error: string;
+    scrim: string;
+};
+export declare const ui: {
+    bottomNav: {
+        borderTopWidth: number;
+        borderColor: string;
+        paddingHorizontal: number;
+        paddingVertical: number;
+        alignItems: "center";
+    };
+    root: {
+        flex: number;
+        backgroundColor: string;
+    };
+    header: {
+        padding: number;
+        gap: number;
+        borderBottomWidth: number;
+        borderColor: string;
+    };
+    row: {
+        flexDirection: "row";
+        alignItems: "center";
+        gap: number;
+        flexWrap: "wrap";
+    };
+    spread: {
+        flexDirection: "row";
+        alignItems: "center";
+        justifyContent: "space-between";
+        gap: number;
+    };
+    content: {
+        padding: number;
+        gap: number;
+    };
+    title: {
+        fontSize: number;
+        fontWeight: "700";
+        color: string;
+        flexShrink: number;
+    };
+    heading: {
+        fontSize: number;
+        fontWeight: "600";
+        color: string;
+    };
+    text: {
+        fontSize: number;
+        color: string;
+    };
+    muted: {
+        fontSize: number;
+        lineHeight: number;
+        color: string;
+    };
+    error: {
+        color: string;
+        fontSize: number;
+    };
+    card: {
+        padding: number;
+        borderRadius: number;
+        backgroundColor: string;
+        gap: number;
+    };
+    item: {
+        padding: number;
+        borderBottomWidth: number;
+        borderColor: string;
+        gap: number;
+    };
+    input: {
+        borderWidth: number;
+        borderColor: string;
+        borderRadius: number;
+        paddingHorizontal: number;
+        paddingVertical: number;
+        color: string;
+        fontSize: number;
+    };
+    button: {
+        paddingHorizontal: number;
+        paddingVertical: number;
+        borderRadius: number;
+        backgroundColor: string;
+        borderWidth: number;
+        borderColor: string;
+    };
+    selected: {
+        backgroundColor: string;
+        borderColor: string;
+    };
+    buttonText: {
+        color: string;
+        fontSize: number;
+        fontWeight: "500";
+    };
+    selectedText: {
+        color: string;
+    };
+    link: {
+        color: string;
+        fontSize: number;
+    };
+    chart: {
+        height: number;
+        flexDirection: "row";
+        gap: number;
+        alignItems: "flex-end";
+    };
+    bar: {
+        flex: number;
+        backgroundColor: string;
+        minHeight: number;
+    };
+    track: {
+        height: number;
+        backgroundColor: string;
+        borderRadius: number;
+        overflow: "hidden";
+    };
+};
+export declare function Button({ label, onPress, selected, disabled, testID, }: {
+    label: string;
+    onPress: () => void;
+    selected?: boolean;
+    disabled?: boolean;
+    testID?: string;
+}): React.JSX.Element;
+export declare function Field({ label, value, onChange, numeric, }: {
+    label: string;
+    value: string;
+    onChange: (value: string) => void;
+    numeric?: boolean;
+}): React.JSX.Element;
+export declare const apple: {
+    grouped: string;
+    card: string;
+    separator: string;
+    secondary: string;
+    fill: string;
+};
+export declare function NavBar({ left, title, right, }: {
+    left?: React.ReactNode;
+    title: string;
+    right?: React.ReactNode;
+}): React.JSX.Element;
+/** Blue text or glyph button, as in iOS navigation bars and toolbars. */
+export declare function TextButton({ label, icon, onPress, disabled, bold, accessibilityLabel, }: {
+    label?: string;
+    icon?: string;
+    onPress: () => void;
+    disabled?: boolean;
+    bold?: boolean;
+    accessibilityLabel?: string;
+}): React.JSX.Element;
+export declare function Section({ header, footer, children, }: {
+    header?: string;
+    footer?: string;
+    children: React.ReactNode;
+}): React.JSX.Element;
+export interface RowProps {
+    title: string;
+    subtitle?: string;
+    value?: string;
+    icon?: string;
+    iconColor?: string;
+    /** Tints title and value, e.g. errors. */
+    tint?: string;
+    onPress?: () => void;
+    /** Hide the separator on the last row of a section. */
+    last?: boolean;
+    /** Toggle row: shows a checkmark instead of a disclosure chevron. */
+    checked?: boolean;
+}
+/** Memoized: unchanged rows skip re-rendering when live data ticks. */
+export declare const Row: React.MemoExoticComponent<({ title, subtitle, value, icon, iconColor, tint, onPress, last, checked, }: RowProps) => React.JSX.Element>;
+export declare function SearchField({ value, onChange, placeholder, }: {
+    value: string;
+    onChange: (value: string) => void;
+    placeholder: string;
+}): React.JSX.Element;
+export declare function Segmented<T extends string>({ options, value, onChange, }: {
+    options: readonly {
+        value: T;
+        label: string;
+    }[];
+    value: T;
+    onChange: (value: T) => void;
+}): React.JSX.Element;
+export declare function TabBar<T extends string>({ items, value, onChange, }: {
+    items: readonly {
+        value: T;
+        label: string;
+        icon: string;
+        iconSize?: number;
+    }[];
+    value: T;
+    onChange: (value: T) => void;
+}): React.JSX.Element;
+export declare function Banner({ label, onPress, }: {
+    label: string;
+    onPress: () => void;
+}): React.JSX.Element;
+export interface SheetOption {
+    label: string;
+    onPress: () => void;
+    selected?: boolean;
+    destructive?: boolean;
+    disabled?: boolean;
+}
+/** iOS-style action sheet fallback (Android, or without @expo/ui). Mount only while open. */
+export declare function ActionSheet({ title, options, cancelLabel, close, }: {
+    title?: string;
+    options: SheetOption[];
+    cancelLabel: string;
+    close: () => void;
+}): React.JSX.Element;

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

@@ -0,0 +1,8 @@
+import React from 'react';
+import type { Viewer } from './useTraceViewer';
+import type { InspectorTranslator } from './labels';
+/** Navigation bar, status line and live-update banner. Only this subscribes to the 1 s telemetry tick. */
+export declare function InspectorHeader({ v: viewer, t, }: {
+    v: Viewer;
+    t: InspectorTranslator;
+}): React.JSX.Element;

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

@@ -0,0 +1,16 @@
+import React, { type ReactNode } from 'react';
+/**
+ * iOS page sheet: nav bar with Cancel and an optional primary action, grouped body.
+ * Mount only while open; a pre-mounted Modal inside the inspector's Modal presents unreliably.
+ */
+export declare function InspectorSheet({ title, close, closeLabel, primary, children, }: {
+    title: string;
+    close: () => void;
+    closeLabel: string;
+    primary?: {
+        label: string;
+        onPress: () => void;
+        disabled?: boolean;
+    };
+    children: ReactNode;
+}): React.JSX.Element;

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

@@ -0,0 +1,7 @@
+import React from 'react';
+import type { Viewer } from './useTraceViewer';
+import type { InspectorTranslator } from './labels';
+export declare function MetricsView({ v, t }: {
+    v: Viewer;
+    t: InspectorTranslator;
+}): React.JSX.Element;

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

@@ -0,0 +1,11 @@
+import React from 'react';
+import type { InspectorTranslator } from './labels';
+import type { Viewer } from './useTraceViewer';
+import { type AnyEvent } from './topics';
+/** Opens the matching detail; metric samples open their series. */
+export declare const openEvent: (v: Viewer, event: AnyEvent) => void;
+export declare function SummaryView({ v, t, budgetMs, }: {
+    v: Viewer;
+    t: InspectorTranslator;
+    budgetMs?: number;
+}): React.JSX.Element;

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

@@ -0,0 +1,8 @@
+import React from 'react';
+import type { InspectorTranslator } from './labels';
+import type { Viewer } from './useTraceViewer';
+/** Newest screen visit first; section headers are the screens the events happened on. */
+export declare function TimelineView({ v, t }: {
+    v: Viewer;
+    t: InspectorTranslator;
+}): React.JSX.Element;

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

@@ -0,0 +1,11 @@
+import React from 'react';
+import type { TraceClient } from '../client/createTraceClient';
+import { type Budgets } from './topics';
+import { type InspectorLabels, type InspectorTranslator } from './labels';
+export declare function TraceInspector({ client, labels, translate, budgets, }: {
+    client: TraceClient;
+    labels?: Partial<InspectorLabels>;
+    translate?: InspectorTranslator;
+    /** Local issue thresholds for the Summary and Timeline. */
+    budgets?: Partial<Budgets>;
+}): React.JSX.Element;

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

@@ -0,0 +1,17 @@
+import React from 'react';
+import type { TraceClient } from '../client/createTraceClient';
+import { type InspectorLabels, type InspectorTranslator } from './labels';
+import { type Budgets } from './topics';
+/**
+ * Floating entry point and live, non-modal sheet for the current screen. The app stays
+ * usable above the sheet; mount it last at the app root. It sits below the app's own
+ * native modals. Rendering it is the app's decision (e.g. internal or UAT builds only).
+ */
+export declare function TraceOverlay({ client, labels, translate, budgets, bottomOffset, }: {
+    client: TraceClient;
+    labels?: Partial<InspectorLabels>;
+    translate?: InspectorTranslator;
+    budgets?: Partial<Budgets>;
+    /** Dock the sheet this far above the bottom edge, e.g. the app's tab bar height, so it stays usable. */
+    bottomOffset?: number;
+}): React.JSX.Element;

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

@@ -0,0 +1,38 @@
+import type { MarkEvent, SpanEvent, TracePage } from '../types';
+export type ExplorerMode = 'traces' | 'spans' | 'marks';
+export type Sort = 'newest' | 'oldest' | 'longest' | 'shortest' | 'errors' | 'count' | 'name';
+export interface Query {
+    search: string;
+    outcomes: string[];
+    sources: string[];
+    minDuration: string;
+    from: string;
+    to: string;
+    correlation: string;
+    sort: Sort;
+}
+export declare const defaultQuery: () => Query;
+export type Event = SpanEvent | MarkEvent;
+export interface Trace {
+    id: string;
+    name: string;
+    start: number;
+    duration: number;
+    errors: number;
+    spans: SpanEvent[];
+    marks: MarkEvent[];
+    sources: string[];
+}
+export declare const sourceOf: (event: Event) => string;
+export declare const matchesSearch: (event: Event, search: string) => boolean;
+export declare const buildTraces: (page: TracePage) => Trace[];
+export declare const queryEvents: (events: Event[], query: Query) => Event[];
+export declare const queryTraces: (traces: Trace[], query: Query) => Trace[];
+export declare const hierarchyRows: (spans: SpanEvent[], collapsed: Set<string>) => {
+    span: SpanEvent;
+    depth: number;
+    children: number;
+    offset: number;
+    width: number;
+}[];
+export declare const traceForSpan: (traces: Trace[], span: SpanEvent) => Trace | undefined;