@scalebun-release/react-native 2.5.0

package/lib/typescript/features/performance/config.d.ts

@@ -0,0 +1,73 @@
+/**
+ * ScaleBun SDK — Performance Config
+ *
+ * Performance-specific configuration with sensible defaults.
+ * All thresholds are tuned for development debugging first,
+ * with hooks for production configuration later.
+ */
+export interface PerformanceConfig {
+    /** Enable/disable performance monitoring entirely. Default: true */
+    enabled: boolean;
+    /** Enable JS event-loop stall detection. Default: true */
+    jsStalls: boolean;
+    /** Stall threshold in ms (drift above this = stall). Default: 32 (2 frames) */
+    stallThresholdMs: number;
+    /** Stall sampling interval in ms. Default: 16 (~60fps frame budget) */
+    stallIntervalMs: number;
+    /** Enable native frame metrics collection. Default: true */
+    frameMetrics: boolean;
+    /** Slow frame threshold in ms. Default: 16.67 (below 60fps) */
+    slowFrameThresholdMs: number;
+    /** Frozen frame threshold in ms. Default: 700 */
+    frozenFrameThresholdMs: number;
+    /** Enable app launch timing. Default: true */
+    appLaunch: boolean;
+    /** Enable screen load timing. Default: true */
+    screenLoad: boolean;
+    /**
+     * Enable native UI hang / ANR watchdog. Tier-1, emits only on a real hang.
+     * Default: true — additive (fires only on a real hang); forward-only since it
+     * needs the native module, so stale prebuilt binaries no-op until rebuilt.
+     * Disable via config (`performance.tier1.uiHang`) — no SDK release required.
+     */
+    uiHangs: boolean;
+    /** UI hang threshold in ms. Default: 2000 */
+    hangThresholdMs: number;
+    /**
+     * Master enable for the Tier-2 (heavy, continuous) collectors.
+     * Even when true, a session only runs them if it passes tier2SampleRate.
+     * Default: true (gated by sampleRate below).
+     */
+    tier2Enabled: boolean;
+    /**
+     * Per-session sampling fraction (0..1) for Tier-2 collectors.
+     * Decision is deterministic per sessionId (same session never flips).
+     * Default: DEFAULT_TIER2_SAMPLE_RATE (10%) — conservative sample that keeps
+     * ingest ~1/10th of full-rate. Set 0 to disable via `performance.tier2.sampleRate`.
+     */
+    tier2SampleRate: number;
+    /** Enable network performance tracking. Default: true */
+    networkPerf: boolean;
+    /** Slow request threshold in ms. Default: 3000 */
+    slowRequestThresholdMs: number;
+    /** Enable custom trace API. Default: true */
+    customTraces: boolean;
+    /** Maximum concurrent custom traces. Default: 20 */
+    maxConcurrentTraces: number;
+    /** How often to report aggregate metrics in ms. Default: 5000 */
+    reportIntervalMs: number;
+    /** Maximum buffered events before flush. Default: 200 */
+    maxBufferSize: number;
+    /** Sample rate (0.0 to 1.0). Default: 1.0 (collect everything in dev) */
+    sampleRate: number;
+}
+/**
+ * Safe non-zero default for Tier-2 (frame_metrics + js_stall) per-session
+ * sampling. 0.1 = 10% of sessions run the heavy collectors — enough to surface
+ * FPS/jank/stall trends while keeping ingest volume ~1/10th of full-rate.
+ * Host-overridable via `performance.tier2.sampleRate` (set 0 to disable).
+ */
+export declare const DEFAULT_TIER2_SAMPLE_RATE = 0.1;
+export declare const DEFAULT_PERF_CONFIG: PerformanceConfig;
+export declare function mergePerformanceConfig(partial?: Partial<PerformanceConfig>): PerformanceConfig;
+//# sourceMappingURL=config.d.ts.map

package/lib/typescript/features/performance/getNativePerformanceModule.d.ts

@@ -0,0 +1,2 @@
+export declare function getNativePerformanceModule(): any;
+//# sourceMappingURL=getNativePerformanceModule.d.ts.map

package/lib/typescript/features/performance/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * ScaleBun SDK — Performance Feature Public Exports
+ */
+export { PerformanceFeature } from './PerformanceFeature';
+export type { PerformanceConfig } from './config';
+export { mergePerformanceConfig, DEFAULT_PERF_CONFIG } from './config';
+export type { PerformanceEvent, AnyPerfEvent, AppLaunchEvent, ScreenLoadEvent, FrameMetricsEvent, JsStallEvent, UiHangEvent, NetworkPerfEvent, CustomTraceEvent, PerformanceSummary, PerfContext, PerfDeviceMeta, PerfSpan, PerfMeasurement, PerfEventType, LaunchType, Severity, } from './models';
+export { PERF_SCHEMA_VERSION } from './models';
+export { MetricKeys, computeStats, percentile, MetricWindow } from './metrics/MetricsEngine';
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/features/performance/metrics/MetricsEngine.d.ts

@@ -0,0 +1,69 @@
+/**
+ * ScaleBun SDK — Metrics Engine
+ *
+ * Aggregation, percentile calculation (p50/p95/p99),
+ * and summary generation for performance metrics.
+ */
+export declare const MetricKeys: {
+    readonly APP_LAUNCH_COLD: "perf.app_launch.cold";
+    readonly APP_LAUNCH_WARM: "perf.app_launch.warm";
+    readonly FPS_ESTIMATED: "perf.fps.estimated";
+    readonly FRAMES_TOTAL: "perf.frames.total";
+    readonly FRAMES_DROPPED: "perf.frames.dropped";
+    readonly FRAMES_SLOW: "perf.frames.slow";
+    readonly FRAMES_FROZEN: "perf.frames.frozen";
+    readonly FRAME_DROP_RATE: "perf.frames.drop_rate";
+    readonly JS_ESTIMATED_FPS: "perf.js.estimated_fps";
+    readonly JS_FRAMES_DROPPED: "perf.js.frames_dropped";
+    readonly JS_STALL_COUNT: "perf.js.stall_count";
+    readonly JS_STALL_MAX: "perf.js.stall_max";
+    readonly JS_STALL_TOTAL: "perf.js.stall_total";
+    readonly JS_STALL_AVG: "perf.js.stall_avg";
+    readonly UI_HANG_COUNT: "perf.ui.hang_count";
+    readonly UI_HANG_MAX: "perf.ui.hang_max";
+    readonly SCREEN_LOAD: "perf.screen.load";
+    readonly NETWORK_SLOW_COUNT: "perf.network.slow_count";
+    readonly NETWORK_FAIL_COUNT: "perf.network.fail_count";
+    readonly CUSTOM_TRACE: "perf.trace";
+};
+/**
+ * Calculate a percentile value from a sorted array of numbers.
+ * Uses nearest-rank method.
+ */
+export declare function percentile(sorted: number[], p: number): number;
+/**
+ * Calculate p50, p95, p99, avg, min, max from an array of values.
+ */
+export declare function computeStats(values: number[]): MetricStats;
+export interface MetricStats {
+    count: number;
+    avg: number;
+    min: number;
+    max: number;
+    p50: number;
+    p95: number;
+    p99: number;
+    sum: number;
+}
+/**
+ * Bounded rolling window for metric values.
+ * Supports time-based and count-based bounding.
+ */
+export declare class MetricWindow {
+    private values;
+    private maxSize;
+    constructor(maxSize?: number);
+    add(value: number, timestamp?: number): void;
+    /** Get all values */
+    getAll(): number[];
+    /** Get values within a time range */
+    getSince(sinceMs: number): number[];
+    /** Get stats for all values */
+    stats(): MetricStats;
+    /** Get stats for a time range */
+    statsSince(sinceMs: number): MetricStats;
+    /** Number of values stored */
+    get size(): number;
+    clear(): void;
+}
+//# sourceMappingURL=MetricsEngine.d.ts.map

package/lib/typescript/features/performance/models.d.ts

@@ -0,0 +1,169 @@
+/**
+ * ScaleBun SDK — Performance Models
+ *
+ * Strong-typed domain models for all performance signals.
+ * Every model includes session/trace/screen/device context
+ * for cross-feature correlation.
+ *
+ * Schema version: 1
+ */
+export declare const PERF_SCHEMA_VERSION = 1;
+export type PerfEventType = 'app_launch' | 'screen_load' | 'frame_metrics' | 'js_stall' | 'ui_hang' | 'network_perf' | 'custom_trace' | 'perf_summary';
+export type LaunchType = 'cold' | 'warm' | 'hot';
+export type Severity = 'info' | 'warning' | 'critical';
+export type FrameQuality = 'normal' | 'slow' | 'frozen';
+/** Context attached to every performance event for cross-feature correlation */
+export interface PerfContext {
+    sessionId: string;
+    traceId?: string;
+    screenKey?: string;
+    interactionId?: string;
+    /** Device/app/os metadata snapshot */
+    device?: PerfDeviceMeta;
+}
+export interface PerfDeviceMeta {
+    platform?: 'android' | 'ios';
+    osVersion?: string;
+    deviceModel?: string;
+    appVersion?: string;
+    buildType?: 'debug' | 'release';
+    bundleId?: string;
+    sdkVersion?: string;
+}
+export interface PerformanceEvent {
+    id: string;
+    type: PerfEventType;
+    timestamp: number;
+    /** Monotonic clock timestamp for drift-free duration measurement */
+    monotonicMs?: number;
+    schemaVersion: number;
+    context: PerfContext;
+}
+export interface AppLaunchEvent extends PerformanceEvent {
+    type: 'app_launch';
+    launchType: LaunchType;
+    durationMs: number;
+    /** Breakdown of launch phases (optional — depends on native granularity) */
+    breakdown?: {
+        processStartMs?: number;
+        nativeInitMs?: number;
+        contentProviderMs?: number;
+        activityCreateMs?: number;
+        firstFrameMs?: number;
+        jsReadyMs?: number;
+        firstScreenMs?: number;
+    };
+    /**
+     * Labels each breakdown phase as 'measured' or 'inferred'.
+     * Only phases present in `breakdown` should have entries.
+     */
+    phaseLabels?: Record<string, 'measured' | 'inferred'>;
+}
+export interface ScreenLoadEvent extends PerformanceEvent {
+    type: 'screen_load';
+    screenName: string;
+    durationMs: number;
+    /** Previous screen (for transition measurement) */
+    previousScreen?: string;
+    /** Whether this load was captured automatically vs manual markers */
+    automatic?: boolean;
+}
+export interface FrameMetricsEvent extends PerformanceEvent {
+    type: 'frame_metrics';
+    /** Window duration these metrics cover */
+    windowMs: number;
+    totalFrames: number;
+    droppedFrames: number;
+    slowFrames: number;
+    frozenFrames: number;
+    estimatedFps: number;
+    /** Worst single frame render time in this window */
+    maxFrameTimeMs: number;
+}
+export interface JsStallEvent extends PerformanceEvent {
+    type: 'js_stall';
+    /** Duration of this individual stall */
+    durationMs: number;
+    severity: Severity;
+}
+/** Aggregated JS stall summary for a reporting period */
+export interface JsStallSummary {
+    stallCount: number;
+    maxStallMs: number;
+    totalStallMs: number;
+    avgStallMs: number;
+}
+export interface UiHangEvent extends PerformanceEvent {
+    type: 'ui_hang';
+    durationMs: number;
+    severity: Severity;
+}
+export interface NetworkPerfEvent extends PerformanceEvent {
+    type: 'network_perf';
+    url: string;
+    method: string;
+    statusCode?: number;
+    durationMs: number;
+    /** Whether request is considered failed */
+    failed: boolean;
+    /** Byte size of response if available */
+    responseSize?: number;
+}
+export interface CustomTraceEvent extends PerformanceEvent {
+    type: 'custom_trace';
+    name: string;
+    durationMs: number;
+    spans?: PerfSpan[];
+    measurements?: Record<string, PerfMeasurement>;
+}
+export interface PerfSpan {
+    spanId: string;
+    name: string;
+    startMs: number;
+    endMs?: number;
+    durationMs?: number;
+    status?: 'ok' | 'error' | 'cancelled';
+    data?: Record<string, unknown>;
+}
+export interface PerfMeasurement {
+    value: number;
+    unit: string;
+}
+export interface PerformanceSummary {
+    sessionId: string;
+    timestamp: number;
+    schemaVersion: number;
+    /** App launch timing */
+    launch?: {
+        type: LaunchType;
+        durationMs: number;
+    };
+    /** Frame quality summary */
+    frames?: {
+        avgFps: number;
+        totalFrames: number;
+        droppedFrames: number;
+        slowFrames: number;
+        frozenFrames: number;
+        dropRate: number;
+    };
+    /** JS stall summary */
+    jsStalls?: JsStallSummary;
+    /** UI hang summary */
+    uiHangs?: {
+        hangCount: number;
+        maxHangMs: number;
+        totalHangMs: number;
+    };
+    /** Screen load summary */
+    screenLoads?: Array<{
+        screenName: string;
+        avgMs: number;
+        p95Ms: number;
+        count: number;
+    }>;
+    /** Slow network requests */
+    slowNetworkRequests?: number;
+}
+export type AnyPerfEvent = AppLaunchEvent | ScreenLoadEvent | FrameMetricsEvent | JsStallEvent | UiHangEvent | NetworkPerfEvent | CustomTraceEvent;
+//# sourceMappingURL=models.d.ts.map

package/lib/typescript/features/performance/transport/PerformanceTransport.d.ts

@@ -0,0 +1,40 @@
+/**
+ * ScaleBun SDK — Performance Transport
+ *
+ * Serializes performance events into the debug protocol format
+ * and sends them via the debug transport. Handles batching and
+ * bounded buffer.
+ */
+import type { AnyPerfEvent, PerformanceSummary, JsStallSummary } from '../models';
+import type { PerformanceConfig } from '../config';
+/** Minimal transport interface — decoupled from DebugTransport implementation */
+export interface PerfTransportSink {
+    readonly deviceId: string;
+    readonly sessionId: string;
+    nextSequence(): number;
+    send(msg: unknown): void;
+}
+export declare class PerformanceTransport {
+    private sink;
+    private config;
+    private buffer;
+    constructor(config: PerformanceConfig);
+    /** Set the transport sink (debug transport) */
+    setSink(sink: PerfTransportSink | null): void;
+    /** Get the transport sink (for direct frame sending) */
+    getSink(): PerfTransportSink | null;
+    /** Send a performance event as a protocol event message */
+    sendEvent(event: AnyPerfEvent): void;
+    /** Send a metric value (for backward compat with existing metric handler) */
+    sendMetric(name: string, value: number, unit?: string, tags?: Record<string, string>): void;
+    /** Send JS stall summary as individual metric messages */
+    sendStallSummary(summary: JsStallSummary & {
+        timestamp: number;
+    }): void;
+    /** Send performance summary */
+    sendSummary(summary: PerformanceSummary): void;
+    private _send;
+    /** Clear buffer */
+    reset(): void;
+}
+//# sourceMappingURL=PerformanceTransport.d.ts.map

package/lib/typescript/features/profiler/ProfilerFeature.d.ts

@@ -0,0 +1,92 @@
+/**
+ * ScaleBun SDK — ProfilerFeature (Phase 3)
+ *
+ * Thin JS orchestrator for the native-first profiler.
+ *
+ * NATIVE-FIRST DESIGN:
+ * This file is intentionally minimal. All heavy lifting
+ * (sampling, aggregation, batching, incident detection) happens
+ * in native code (Android/iOS). This orchestrator only:
+ *   1. Manages lifecycle (start/stop/pause/resume)
+ *   2. Passes config to native modules
+ *   3. Subscribes to batched native events
+ *   4. Forwards normalized events to transport (→ desktop)
+ *   5. Provides a typed public API facade
+ *   6. Implements connection-aware backpressure
+ *   7. Provides opt-in JS thread stall detection
+ *
+ * NO sampling loops, NO timers, NO aggregation logic in JS.
+ * The ONLY JS-side instrumentation is the opt-in JsStallDetector
+ * which uses a single lightweight heartbeat to detect event loop stalls.
+ */
+import type { AnyProfilerEvent, ProfilerCapabilities } from './models';
+import type { IProfilerFeature, ProfilerState, ProfilerTransportSink } from './contracts';
+import { ProfilerConfig } from './config';
+export declare class ProfilerFeature implements IProfilerFeature {
+    readonly name: "profiler";
+    private state;
+    private config;
+    private transport;
+    private nativeModule;
+    private eventListeners;
+    private nativeSubscriptions;
+    private capabilities;
+    private sessionId;
+    private currentScreen;
+    private spanCounter;
+    private transportConnected;
+    private transportStateUnsub;
+    private droppedEventCount;
+    private jsStallDetector;
+    private _samplesSent;
+    constructor(config?: Partial<ProfilerConfig>);
+    /**
+     * Initialize the profiler by resolving the native module.
+     * Does NOT start profiling — call start() for that.
+     */
+    initialize(): Promise<void>;
+    /** Teardown and release all resources */
+    teardown(): void;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    pauseStream(): Promise<void>;
+    resumeStream(): Promise<void>;
+    captureSnapshot(): Promise<Record<string, unknown>>;
+    getCapabilities(): Promise<ProfilerCapabilities | null>;
+    markSpan(name: string, metadata?: Record<string, unknown>): string;
+    endSpan(spanId: string): void;
+    markInteraction(name: string): void;
+    exportBundle(): Promise<Record<string, unknown>>;
+    getState(): ProfilerState;
+    isActive(): boolean;
+    onEvent(callback: (event: AnyProfilerEvent) => void): () => void;
+    /** Connect the debug transport for sending events to desktop */
+    setTransportSink(sink: ProfilerTransportSink | null): void;
+    /** Update session ID on native side */
+    setSessionId(sessionId: string): void;
+    /** Update current screen on native side for correlation */
+    setCurrentScreen(screenName: string): void;
+    /**
+     * Wire transport state observation for connection-aware streaming.
+     *
+     * When desktop disconnects:
+     *   - Pause native event emission to JS (save bridge bandwidth)
+     *   - Buffer is bounded (drops oldest when full)
+     *
+     * When desktop reconnects:
+     *   - Resume native event emission
+     *   - Flush bounded buffer
+     *
+     * This prevents unbounded queue growth during disconnects.
+     */
+    private _wireTransportBackpressure;
+    private _handleNativeSampleBatch;
+    private _handleNativeIncident;
+    private _handleNativeScreenSummary;
+    private _handleNativeThreadSnapshot;
+    private _handleNativeCapabilities;
+    private _handleNativeStateChanged;
+    /** Emit event to transport + listeners */
+    private _emitEvent;
+}
+//# sourceMappingURL=ProfilerFeature.d.ts.map

package/lib/typescript/features/profiler/config.d.ts

@@ -0,0 +1,85 @@
+/**
+ * ScaleBun SDK — Profiler Config
+ *
+ * Configuration model for the profiler feature.
+ * Sensible defaults tuned for low-overhead production use.
+ *
+ * NATIVE-FIRST: These configs are serialized and sent to
+ * native modules on start. Native code owns the sampling
+ * loops, scheduling, and aggregation.
+ */
+import type { SamplingPreset } from './models';
+export interface ProfilerConfig {
+    /** Master enable/disable. Default: true */
+    enabled: boolean;
+    /** Enable live streaming to desktop. Default: true */
+    liveStreamingEnabled: boolean;
+    /**
+     * Sampling preset. Controls the balance between fidelity and overhead.
+     * 'off'        — profiler disabled
+     * 'low'        — minimal sampling, very low overhead
+     * 'balanced'   — default, good fidelity with moderate overhead
+     * 'high'       — high fidelity, higher overhead (dev/debug)
+     * 'diagnostic' — maximum fidelity, significant overhead (short bursts only)
+     */
+    samplingPreset: SamplingPreset;
+    /** CPU sampling interval. Default: 1000ms */
+    cpuSampleIntervalMs: number;
+    /** Memory sampling interval. Default: 2000ms */
+    memorySampleIntervalMs: number;
+    /** Thread snapshot interval. Default: 3000ms */
+    threadSampleIntervalMs: number;
+    /** Enable render/frame collection. Default: true */
+    renderCollectionEnabled: boolean;
+    /** Enable network profiling correlation. Default: true */
+    networkCorrelationEnabled: boolean;
+    /** Enable JS thread instrumentation. Default: false (opt-in) */
+    jsInstrumentationEnabled: boolean;
+    /** Enable diagnostics/incident detection. Default: true */
+    diagnosticsEnabled: boolean;
+    /** Enable trace capture. Default: false (opt-in) */
+    traceCaptureEnabled: boolean;
+    /** Enable export functionality. Default: true */
+    exportEnabled: boolean;
+    /** Max sample buffer size (native side). Default: 500 */
+    maxBufferSize: number;
+    /** Max profiling session duration in ms. Default: 3600000 (1 hour) */
+    maxSessionDurationMs: number;
+    incidentThresholds: ProfilerIncidentThresholds;
+    /** Enable screen-level correlation. Default: true */
+    screenCorrelationEnabled: boolean;
+    /** Enable battery-aware throttling. Default: true */
+    batteryAwareMode: boolean;
+    /** Enable Android StrictMode hooks (debug builds only). Default: false */
+    debugStrictModeHooksEnabled: boolean;
+    /** Custom metadata tags attached to all profiler events */
+    customTags?: Record<string, string>;
+}
+export interface ProfilerIncidentThresholds {
+    /** CPU % above which a spike is detected. Default: 80 */
+    cpuSpikePercent: number;
+    /** Memory growth rate (bytes/sec) for surge detection. Default: 10MB/s */
+    memorySurgeBytesPerSec: number;
+    /** Consecutive slow frames to trigger jank burst. Default: 5 */
+    jankBurstFrameCount: number;
+    /** Main thread stall threshold in ms. Default: 500 */
+    mainThreadStallMs: number;
+    /** JS stall threshold in ms. Default: 300 */
+    jsStallMs: number;
+    /** Thread count spike threshold. Default: 50 */
+    excessiveThreadCount: number;
+    /** Frozen frame threshold in ms. Default: 700 */
+    frozenFrameMs: number;
+}
+export declare const DEFAULT_PROFILER_CONFIG: ProfilerConfig;
+/**
+ * Merge user-provided config with defaults.
+ * Applies preset overrides first, then user overrides on top.
+ */
+export declare function mergeProfilerConfig(partial?: Partial<ProfilerConfig>): ProfilerConfig;
+/**
+ * Serialize config to a plain object suitable for passing across the RN bridge.
+ * Native modules consume this to configure their sampling loops.
+ */
+export declare function serializeProfilerConfig(config: ProfilerConfig): Record<string, unknown>;
+//# sourceMappingURL=config.d.ts.map

package/lib/typescript/features/profiler/contracts.d.ts

@@ -0,0 +1,142 @@
+/**
+ * ScaleBun SDK — Profiler Contracts
+ *
+ * Public interfaces and bridge contracts for the profiler feature.
+ *
+ * NATIVE-FIRST: The native modules implement these commands.
+ * JS only orchestrates lifecycle and forwards config.
+ */
+import type { ProfilerCapabilities, AnyProfilerEvent } from './models';
+/**
+ * Interface for the native profiler module.
+ * Both Android (ScaleBunProfiler) and iOS (ScaleBunProfiler) implement this.
+ *
+ * All heavy work (sampling, aggregation, batching, incident detection)
+ * happens natively. JS receives pre-processed batched payloads.
+ */
+export interface IProfilerNativeModule {
+    /**
+     * Start the profiler with the given serialized config.
+     * Native module begins its own sampling loops.
+     */
+    startProfiler(config: Record<string, unknown>): Promise<boolean>;
+    /**
+     * Stop the profiler and clean up all native resources.
+     */
+    stopProfiler(): Promise<boolean>;
+    /**
+     * Pause live streaming (data still collected, just not emitted to JS).
+     */
+    pauseProfilerStream(): Promise<boolean>;
+    /**
+     * Resume live streaming.
+     */
+    resumeProfilerStream(): Promise<boolean>;
+    /**
+     * Capture an immediate snapshot of all profiler metrics.
+     * Returns a single composite sample.
+     */
+    captureProfilerSnapshot(): Promise<Record<string, unknown>>;
+    /**
+     * Update profiler config while running.
+     */
+    setProfilerConfig(config: Record<string, unknown>): Promise<boolean>;
+    /**
+     * Mark a named span start (for custom profiling spans).
+     */
+    markProfilerSpan(spanName: string, spanId: string, metadata?: Record<string, unknown>): Promise<boolean>;
+    /**
+     * End a named span.
+     */
+    endProfilerSpan(spanId: string): Promise<boolean>;
+    /**
+     * Mark an interaction event for correlation.
+     */
+    markProfilerInteraction(interactionId: string, interactionName: string): Promise<boolean>;
+    /**
+     * Flush buffered data and prepare an export bundle.
+     */
+    flushProfilerExport(): Promise<Record<string, unknown>>;
+    /**
+     * Get platform capabilities.
+     * Returns which metrics are supported on this device/OS version.
+     */
+    getProfilerCapabilities(): Promise<Record<string, unknown>>;
+    /**
+     * Set the current screen name for correlation.
+     * Called by the SDK when screen changes are detected.
+     */
+    setCurrentScreen(screenName: string): Promise<boolean>;
+    /**
+     * Set the current session ID for correlation.
+     */
+    setSessionId(sessionId: string): Promise<boolean>;
+    /** Required for RN NativeEventEmitter */
+    addListener(eventName: string): void;
+    /** Required for RN NativeEventEmitter */
+    removeListeners(count: number): void;
+}
+/**
+ * Events emitted from native → JS via RCTDeviceEventEmitter.
+ * These are batched and compact — never per-frame.
+ */
+export declare const PROFILER_NATIVE_EVENTS: {
+    /** Batched metric samples */
+    readonly SAMPLE_BATCH: "ScaleBunProfiler_SampleBatch";
+    /** Incident detected natively */
+    readonly INCIDENT: "ScaleBunProfiler_Incident";
+    /** Screen summary emitted on screen change */
+    readonly SCREEN_SUMMARY: "ScaleBunProfiler_ScreenSummary";
+    /** Thread snapshot */
+    readonly THREAD_SNAPSHOT: "ScaleBunProfiler_ThreadSnapshot";
+    /** Capabilities report */
+    readonly CAPABILITIES: "ScaleBunProfiler_Capabilities";
+    /** Profiler state changed */
+    readonly STATE_CHANGED: "ScaleBunProfiler_StateChanged";
+};
+export type ProfilerNativeEventName = typeof PROFILER_NATIVE_EVENTS[keyof typeof PROFILER_NATIVE_EVENTS];
+export type ProfilerState = 'idle' | 'running' | 'paused' | 'error';
+/**
+ * Public API surface for the profiler feature.
+ * Kept minimal — JS is an orchestration layer, not the profiling engine.
+ */
+export interface IProfilerFeature {
+    readonly name: 'profiler';
+    /** Start the profiler */
+    start(): Promise<void>;
+    /** Stop the profiler */
+    stop(): Promise<void>;
+    /** Pause live streaming */
+    pauseStream(): Promise<void>;
+    /** Resume live streaming */
+    resumeStream(): Promise<void>;
+    /** Capture an immediate snapshot */
+    captureSnapshot(): Promise<Record<string, unknown>>;
+    /** Get platform capabilities */
+    getCapabilities(): Promise<ProfilerCapabilities | null>;
+    /** Mark a custom span */
+    markSpan(name: string, metadata?: Record<string, unknown>): string;
+    /** End a custom span */
+    endSpan(spanId: string): void;
+    /** Mark an interaction */
+    markInteraction(name: string): void;
+    /** Export profiler data */
+    exportBundle(): Promise<Record<string, unknown>>;
+    /** Current profiler state */
+    getState(): ProfilerState;
+    /** Whether the profiler is currently active */
+    isActive(): boolean;
+    /** Listen for profiler events (for transport forwarding) */
+    onEvent(callback: (event: AnyProfilerEvent) => void): () => void;
+}
+/**
+ * Minimal transport interface for sending profiler data to desktop.
+ * Mirrors the PerfTransportSink pattern from the performance feature.
+ */
+export interface ProfilerTransportSink {
+    readonly deviceId: string;
+    readonly sessionId: string;
+    nextSequence(): number;
+    send(msg: unknown): void;
+}
+//# sourceMappingURL=contracts.d.ts.map