@scalebun/react-native 1.0.2 → 1.0.3

package/src/features/profiler/models.ts

@@ -1,430 +1,430 @@
-/**
- * ScaleBun SDK — Profiler Models
- *
- * Strong-typed domain models for all profiler signals.
- * These models define the data contracts between:
- *   - Native collectors (Android/iOS) → JS bridge
- *   - JS bridge → Desktop transport
- *   - Desktop ingestion → visualization
- *
- * NATIVE-FIRST: All data is produced natively and arrives
- * pre-batched/pre-aggregated. These models describe the
- * normalized shape JS receives, NOT raw native structs.
- *
- * Schema version: 1
- */
-
-// ─── Schema ─────────────────────────────────────────────────────────────────
-
-export const PROFILER_SCHEMA_VERSION = 1;
-
-// ─── Enums ──────────────────────────────────────────────────────────────────
-
-/** Profiler event families — used for protocol routing */
-export type ProfilerEventFamily =
-    | 'profiler.metric.sample'
-    | 'profiler.span.begin'
-    | 'profiler.span.end'
-    | 'profiler.incident'
-    | 'profiler.screen.summary'
-    | 'profiler.thread.snapshot'
-    | 'profiler.network.summary'
-    | 'profiler.render.frame'
-    | 'profiler.js.longtask'
-    | 'profiler.diagnostic'
-    | 'profiler.capabilities';
-
-/** Sampling preset names */
-export type SamplingPreset = 'off' | 'low' | 'balanced' | 'high' | 'diagnostic';
-
-/** Incident severity levels */
-export type IncidentSeverity = 'info' | 'warning' | 'critical';
-
-/** Incident confidence levels */
-export type IncidentConfidence = 'low' | 'medium' | 'high';
-
-/** Metric availability status */
-export type MetricAvailability = 'available' | 'unavailable' | 'restricted' | 'degraded';
-
-/** Thread role classification */
-export type ThreadRole =
-    | 'main'
-    | 'js'
-    | 'render'
-    | 'network'
-    | 'worker'
-    | 'db'
-    | 'sdk_internal'
-    | 'unknown';
-
-/** Thread state */
-export type ThreadState = 'running' | 'waiting' | 'sleeping' | 'blocked' | 'unknown';
-
-/** Incident type identifiers */
-export type IncidentType =
-    | 'cpu_spike'
-    | 'memory_surge'
-    | 'memory_leak_suspicion'
-    | 'jank_burst'
-    | 'frozen_frame'
-    | 'main_thread_stall'
-    | 'js_stall'
-    | 'slow_start'
-    | 'request_induced_slowdown'
-    | 'low_memory_pressure'
-    | 'excessive_thread_growth'
-    | 'hang_precursor'
-    | 'thermal_throttle';
-
-// ─── Context ────────────────────────────────────────────────────────────────
-
-/** Context attached to every profiler event for cross-feature correlation */
-export interface ProfilerContext {
-    sessionId: string;
-    screenKey?: string;
-    interactionId?: string;
-    navigationId?: string;
-    timestamp: number;
-    /** Monotonic uptime in ms — for drift-free intervals */
-    uptimeMs?: number;
-}
-
-// ─── Base Event ─────────────────────────────────────────────────────────────
-
-export interface ProfilerEvent {
-    id: string;
-    family: ProfilerEventFamily;
-    schemaVersion: number;
-    context: ProfilerContext;
-}
-
-// ─── CPU Metrics ────────────────────────────────────────────────────────────
-
-/**
- * FROZEN CONTRACT — cpuPercent semantics (Phase 4)
- *
- * `appCpuPercent` is ALWAYS normalized to 0–100% of TOTAL device CPU capacity.
- *   - Android: (process utime+stime delta / total CPU ticks) * numCores * 100,
- *     then divided by numCores for 0–100 scale.
- *   - iOS: thread-sum (task_threads + thread_info.cpu_usage / TH_USAGE_SCALE * 100),
- *     then divided by activeProcessorCount for 0–100 scale.
- *
- * 50% means the app is using half of the total CPU capacity.
- * 100% means the app is saturating all available cores.
- *
- * `rawMultiCoreCpuPercent` (iOS only) is the un-normalized sum that can
- * exceed 100% on multi-core devices (e.g. 400% = 4 cores fully busy).
- * This is informational only and NOT used for incident thresholds.
- */
-export interface CpuSample {
-    /**
-     * App process CPU usage: 0–100% of total device CPU capacity.
-     * FROZEN SEMANTICS: normalized on both Android and iOS.
-     * 50 = half of all CPU capacity, 100 = all cores saturated.
-     */
-    appCpuPercent: number;
-    /** Process CPU time in ms since last sample */
-    processCpuTimeMs?: number;
-    /** Main thread CPU usage estimate 0–100 (Android only) */
-    mainThreadCpuPercent?: number;
-    /** Per-core CPU usage (if available, Android only) */
-    perCoreCpu?: number[];
-    /** Un-normalized multi-core CPU% (iOS only, informational) */
-    rawMultiCoreCpuPercent?: number;
-    /** Availability status */
-    availability: MetricAvailability;
-}
-
-// ─── Memory Metrics ─────────────────────────────────────────────────────────
-
-export interface MemorySample {
-    /** Resident / physical footprint in bytes */
-    residentBytes?: number;
-    /** Java/Dalvik heap used in bytes (Android) */
-    javaHeapUsedBytes?: number;
-    /** Java/Dalvik heap total in bytes (Android) */
-    javaHeapTotalBytes?: number;
-    /** Native heap used in bytes (Android) */
-    nativeHeapBytes?: number;
-    /** Graphics memory in bytes (if available) */
-    graphicsBytes?: number;
-    /** Total heap bytes */
-    totalHeapBytes?: number;
-    /** Used heap bytes */
-    usedHeapBytes?: number;
-    /** Free heap bytes */
-    freeHeapBytes?: number;
-    /** Peak memory recorded this session */
-    peakMemoryBytes?: number;
-    /** Available memory on device */
-    availableMemoryBytes?: number;
-    /** Whether device is in low-memory state */
-    lowMemory: boolean;
-    /** Memory pressure level (0 = none, 1 = moderate, 2 = critical) */
-    pressureLevel: number;
-    /** Availability status */
-    availability: MetricAvailability;
-}
-
-// ─── Thread Snapshot ────────────────────────────────────────────────────────
-
-export interface ThreadInfo {
-    /** Thread ID */
-    id: number;
-    /** Thread name */
-    name: string;
-    /** Classified role */
-    role: ThreadRole;
-    /** Current state */
-    state: ThreadState;
-    /** CPU usage of this thread (0–100) if available */
-    cpuPercent?: number;
-}
-
-export interface ThreadSnapshot {
-    /** All app-owned threads */
-    threads: ThreadInfo[];
-    /** Total thread count */
-    threadCount: number;
-    /** Peak thread count this session */
-    peakThreadCount: number;
-    /** Availability status */
-    availability: MetricAvailability;
-}
-
-// ─── Render / Frame Metrics ─────────────────────────────────────────────────
-
-export interface RenderSample {
-    /** FPS / frame rate */
-    fps: number;
-    /** Total frames in this sampling window */
-    totalFrames: number;
-    /** Slow frames (> 16.67ms) */
-    slowFrames: number;
-    /** Frozen frames (> 700ms) */
-    frozenFrames: number;
-    /** Dropped frames */
-    droppedFrames: number;
-    /** Maximum frame time in ms */
-    maxFrameTimeMs: number;
-    /** Frame time histogram buckets (ms ranges → counts) */
-    histogram?: Record<string, number>;
-    /** Availability status */
-    availability: MetricAvailability;
-}
-
-// ─── Network Summary ────────────────────────────────────────────────────────
-
-export interface NetworkProfileSample {
-    /** Active request count */
-    activeRequestCount: number;
-    /** Bytes sent since last sample */
-    bytesSent: number;
-    /** Bytes received since last sample */
-    bytesReceived: number;
-    /** Slowest active request duration in ms */
-    slowestRequestMs?: number;
-    /** Availability status */
-    availability: MetricAvailability;
-}
-
-/**
- * JS event loop stall detection sample.
- *
- * CAVEAT: This is an APPROXIMATE measurement, NOT exact.
- * Uses setTimeout jitter as a proxy for event loop blocking.
- * Can detect stalls ≥ 300ms wall-clock (200ms heartbeat + 100ms threshold).
- * Sub-100ms micro-stalls will NOT be caught.
- * Timer coalescing and OS scheduling can affect accuracy.
- *
- * This is NOT the sole source of truth for JS performance.
- * It should be correlated with native CPU/render data for a complete picture.
- */
-export interface JsProfileSample {
-    /** Whether JS thread is currently stalled */
-    isStalled: boolean;
-    /** Duration of current/last stall in ms (approximate) */
-    stallDurationMs?: number;
-    /** Estimated JS thread busy percentage */
-    jsBusyPercent?: number;
-    /** Bridge call count since last sample */
-    bridgeCallCount?: number;
-    /** Average bridge call latency in ms */
-    avgBridgeLatencyMs?: number;
-    /** Availability status */
-    availability: MetricAvailability;
-}
-
-// ─── Thermal / Energy ───────────────────────────────────────────────────────
-
-export interface ThermalSample {
-    /** Thermal state: 0 = nominal, 1 = fair, 2 = serious, 3 = critical */
-    thermalState: number;
-    /** Whether battery saver / low-power mode is active */
-    lowPowerMode?: boolean;
-    /** Availability status */
-    availability: MetricAvailability;
-}
-
-// ─── Composite Profiler Sample ──────────────────────────────────────────────
-
-/**
- * A single batched profiler sample emitted from native.
- * Contains all metric families collected in a single sampling window.
- * Arrives pre-aggregated from native — JS does NOT compute these.
- */
-export interface ProfilerSample extends ProfilerEvent {
-    family: 'profiler.metric.sample';
-    cpu?: CpuSample;
-    memory?: MemorySample;
-    threads?: ThreadSnapshot;
-    render?: RenderSample;
-    network?: NetworkProfileSample;
-    js?: JsProfileSample;
-    thermal?: ThermalSample;
-    /** Sample interval in ms (how often this sample fires) */
-    sampleIntervalMs: number;
-}
-
-// ─── Profiler Span ──────────────────────────────────────────────────────────
-
-export interface ProfilerSpan extends ProfilerEvent {
-    family: 'profiler.span.begin' | 'profiler.span.end';
-    /** Span name (e.g. 'screen_transition', 'network_request', 'user_interaction') */
-    spanName: string;
-    /** Unique span ID for begin/end matching */
-    spanId: string;
-    /** Duration in ms (only on span.end) */
-    durationMs?: number;
-    /** Associated metadata */
-    metadata?: Record<string, unknown>;
-}
-
-// ─── Profiler Incident ──────────────────────────────────────────────────────
-
-export interface ProfilerIncident extends ProfilerEvent {
-    family: 'profiler.incident';
-    /** Incident type identifier */
-    incidentType: IncidentType;
-    /** Human-readable title */
-    title: string;
-    /** Severity level */
-    severity: IncidentSeverity;
-    /** Confidence score */
-    confidence: IncidentConfidence;
-    /** Start timestamp */
-    startTimestamp: number;
-    /** End timestamp (if resolved) */
-    endTimestamp?: number;
-    /** Affected screen(s) — screen keys from visit windows */
-    affectedScreens: string[];
-    /** Screen visit IDs correlated with this incident */
-    affectedScreenVisitIds?: string[];
-    /** Related request IDs (from network interceptor) */
-    relatedRequests?: string[];
-    /** Related log entry IDs */
-    relatedLogs?: string[];
-    /** Related thread IDs */
-    relatedThreads?: number[];
-    /** Related span IDs */
-    relatedSpanIds?: string[];
-    /** Related replay/timeline markers */
-    relatedTimelineMarkers?: string[];
-    /** Suggested likely cause category */
-    likelyCause: string;
-    /** Descriptive text */
-    description: string;
-}
-
-// ─── Screen Summary ─────────────────────────────────────────────────────────
-
-export interface ProfilerScreenSummary extends ProfilerEvent {
-    family: 'profiler.screen.summary';
-    screenName: string;
-    /** Unique screen visit ID for correlating with samples/incidents */
-    screenVisitId?: string;
-    /** Absolute start timestamp of this screen visit */
-    visitStartTimestamp?: number;
-    /** Absolute end timestamp (set when screen exits) */
-    visitEndTimestamp?: number;
-    /** Duration this screen was active in ms */
-    durationMs: number;
-    /** Aggregated CPU stats for this screen */
-    avgCpuPercent?: number;
-    maxCpuPercent?: number;
-    /** Aggregated memory stats */
-    avgMemoryBytes?: number;
-    peakMemoryBytes?: number;
-    /** Frame stats */
-    avgFps?: number;
-    totalSlowFrames?: number;
-    totalFrozenFrames?: number;
-    /** Network stats */
-    requestCount?: number;
-    totalBytesTransferred?: number;
-    expensiveRequestCount?: number;
-    /** JS stats */
-    jsStallCount?: number;
-    totalJsStallMs?: number;
-    /** Incident count */
-    incidentCount?: number;
-    /** Thread peak count during screen visit */
-    peakThreadCount?: number;
-}
-
-// ─── Profiler Diagnostic ────────────────────────────────────────────────────
-
-export interface ProfilerDiagnostic extends ProfilerEvent {
-    family: 'profiler.diagnostic';
-    /** Diagnostic category */
-    category: string;
-    /** Human-readable message */
-    message: string;
-    /** Associated data */
-    data?: Record<string, unknown>;
-}
-
-// ─── Capabilities ───────────────────────────────────────────────────────────
-
-export interface ProfilerCapabilityEntry {
-    /** Whether this metric is available */
-    available: boolean;
-    /** Minimum API level / iOS version required */
-    minVersion?: string;
-    /** Current device API level / iOS version */
-    currentVersion?: string;
-    /** Whether live reporting is supported (vs deferred only) */
-    liveSupported: boolean;
-    /** Reason if unavailable */
-    reason?: string;
-}
-
-export interface ProfilerCapabilities extends ProfilerEvent {
-    family: 'profiler.capabilities';
-    platform: 'android' | 'ios';
-    /** Capabilities per metric group */
-    cpu: ProfilerCapabilityEntry;
-    memory: ProfilerCapabilityEntry;
-    threads: ProfilerCapabilityEntry;
-    render: ProfilerCapabilityEntry;
-    network: ProfilerCapabilityEntry;
-    js: ProfilerCapabilityEntry;
-    thermal: ProfilerCapabilityEntry;
-    diskIo: ProfilerCapabilityEntry;
-    /** Device model */
-    deviceModel: string;
-    /** OS version string */
-    osVersion: string;
-    /** App build type */
-    buildType: 'debug' | 'release';
-}
-
-// ─── Union ──────────────────────────────────────────────────────────────────
-
-export type AnyProfilerEvent =
-    | ProfilerSample
-    | ProfilerSpan
-    | ProfilerIncident
-    | ProfilerScreenSummary
-    | ProfilerDiagnostic
-    | ProfilerCapabilities;
+/**
+ * ScaleBun SDK — Profiler Models
+ *
+ * Strong-typed domain models for all profiler signals.
+ * These models define the data contracts between:
+ *   - Native collectors (Android/iOS) → JS bridge
+ *   - JS bridge → Desktop transport
+ *   - Desktop ingestion → visualization
+ *
+ * NATIVE-FIRST: All data is produced natively and arrives
+ * pre-batched/pre-aggregated. These models describe the
+ * normalized shape JS receives, NOT raw native structs.
+ *
+ * Schema version: 1
+ */
+
+// ─── Schema ─────────────────────────────────────────────────────────────────
+
+export const PROFILER_SCHEMA_VERSION = 1;
+
+// ─── Enums ──────────────────────────────────────────────────────────────────
+
+/** Profiler event families — used for protocol routing */
+export type ProfilerEventFamily =
+    | 'profiler.metric.sample'
+    | 'profiler.span.begin'
+    | 'profiler.span.end'
+    | 'profiler.incident'
+    | 'profiler.screen.summary'
+    | 'profiler.thread.snapshot'
+    | 'profiler.network.summary'
+    | 'profiler.render.frame'
+    | 'profiler.js.longtask'
+    | 'profiler.diagnostic'
+    | 'profiler.capabilities';
+
+/** Sampling preset names */
+export type SamplingPreset = 'off' | 'low' | 'balanced' | 'high' | 'diagnostic';
+
+/** Incident severity levels */
+export type IncidentSeverity = 'info' | 'warning' | 'critical';
+
+/** Incident confidence levels */
+export type IncidentConfidence = 'low' | 'medium' | 'high';
+
+/** Metric availability status */
+export type MetricAvailability = 'available' | 'unavailable' | 'restricted' | 'degraded';
+
+/** Thread role classification */
+export type ThreadRole =
+    | 'main'
+    | 'js'
+    | 'render'
+    | 'network'
+    | 'worker'
+    | 'db'
+    | 'sdk_internal'
+    | 'unknown';
+
+/** Thread state */
+export type ThreadState = 'running' | 'waiting' | 'sleeping' | 'blocked' | 'unknown';
+
+/** Incident type identifiers */
+export type IncidentType =
+    | 'cpu_spike'
+    | 'memory_surge'
+    | 'memory_leak_suspicion'
+    | 'jank_burst'
+    | 'frozen_frame'
+    | 'main_thread_stall'
+    | 'js_stall'
+    | 'slow_start'
+    | 'request_induced_slowdown'
+    | 'low_memory_pressure'
+    | 'excessive_thread_growth'
+    | 'hang_precursor'
+    | 'thermal_throttle';
+
+// ─── Context ────────────────────────────────────────────────────────────────
+
+/** Context attached to every profiler event for cross-feature correlation */
+export interface ProfilerContext {
+    sessionId: string;
+    screenKey?: string;
+    interactionId?: string;
+    navigationId?: string;
+    timestamp: number;
+    /** Monotonic uptime in ms — for drift-free intervals */
+    uptimeMs?: number;
+}
+
+// ─── Base Event ─────────────────────────────────────────────────────────────
+
+export interface ProfilerEvent {
+    id: string;
+    family: ProfilerEventFamily;
+    schemaVersion: number;
+    context: ProfilerContext;
+}
+
+// ─── CPU Metrics ────────────────────────────────────────────────────────────
+
+/**
+ * FROZEN CONTRACT — cpuPercent semantics (Phase 4)
+ *
+ * `appCpuPercent` is ALWAYS normalized to 0–100% of TOTAL device CPU capacity.
+ *   - Android: (process utime+stime delta / total CPU ticks) * numCores * 100,
+ *     then divided by numCores for 0–100 scale.
+ *   - iOS: thread-sum (task_threads + thread_info.cpu_usage / TH_USAGE_SCALE * 100),
+ *     then divided by activeProcessorCount for 0–100 scale.
+ *
+ * 50% means the app is using half of the total CPU capacity.
+ * 100% means the app is saturating all available cores.
+ *
+ * `rawMultiCoreCpuPercent` (iOS only) is the un-normalized sum that can
+ * exceed 100% on multi-core devices (e.g. 400% = 4 cores fully busy).
+ * This is informational only and NOT used for incident thresholds.
+ */
+export interface CpuSample {
+    /**
+     * App process CPU usage: 0–100% of total device CPU capacity.
+     * FROZEN SEMANTICS: normalized on both Android and iOS.
+     * 50 = half of all CPU capacity, 100 = all cores saturated.
+     */
+    appCpuPercent: number;
+    /** Process CPU time in ms since last sample */
+    processCpuTimeMs?: number;
+    /** Main thread CPU usage estimate 0–100 (Android only) */
+    mainThreadCpuPercent?: number;
+    /** Per-core CPU usage (if available, Android only) */
+    perCoreCpu?: number[];
+    /** Un-normalized multi-core CPU% (iOS only, informational) */
+    rawMultiCoreCpuPercent?: number;
+    /** Availability status */
+    availability: MetricAvailability;
+}
+
+// ─── Memory Metrics ─────────────────────────────────────────────────────────
+
+export interface MemorySample {
+    /** Resident / physical footprint in bytes */
+    residentBytes?: number;
+    /** Java/Dalvik heap used in bytes (Android) */
+    javaHeapUsedBytes?: number;
+    /** Java/Dalvik heap total in bytes (Android) */
+    javaHeapTotalBytes?: number;
+    /** Native heap used in bytes (Android) */
+    nativeHeapBytes?: number;
+    /** Graphics memory in bytes (if available) */
+    graphicsBytes?: number;
+    /** Total heap bytes */
+    totalHeapBytes?: number;
+    /** Used heap bytes */
+    usedHeapBytes?: number;
+    /** Free heap bytes */
+    freeHeapBytes?: number;
+    /** Peak memory recorded this session */
+    peakMemoryBytes?: number;
+    /** Available memory on device */
+    availableMemoryBytes?: number;
+    /** Whether device is in low-memory state */
+    lowMemory: boolean;
+    /** Memory pressure level (0 = none, 1 = moderate, 2 = critical) */
+    pressureLevel: number;
+    /** Availability status */
+    availability: MetricAvailability;
+}
+
+// ─── Thread Snapshot ────────────────────────────────────────────────────────
+
+export interface ThreadInfo {
+    /** Thread ID */
+    id: number;
+    /** Thread name */
+    name: string;
+    /** Classified role */
+    role: ThreadRole;
+    /** Current state */
+    state: ThreadState;
+    /** CPU usage of this thread (0–100) if available */
+    cpuPercent?: number;
+}
+
+export interface ThreadSnapshot {
+    /** All app-owned threads */
+    threads: ThreadInfo[];
+    /** Total thread count */
+    threadCount: number;
+    /** Peak thread count this session */
+    peakThreadCount: number;
+    /** Availability status */
+    availability: MetricAvailability;
+}
+
+// ─── Render / Frame Metrics ─────────────────────────────────────────────────
+
+export interface RenderSample {
+    /** FPS / frame rate */
+    fps: number;
+    /** Total frames in this sampling window */
+    totalFrames: number;
+    /** Slow frames (> 16.67ms) */
+    slowFrames: number;
+    /** Frozen frames (> 700ms) */
+    frozenFrames: number;
+    /** Dropped frames */
+    droppedFrames: number;
+    /** Maximum frame time in ms */
+    maxFrameTimeMs: number;
+    /** Frame time histogram buckets (ms ranges → counts) */
+    histogram?: Record<string, number>;
+    /** Availability status */
+    availability: MetricAvailability;
+}
+
+// ─── Network Summary ────────────────────────────────────────────────────────
+
+export interface NetworkProfileSample {
+    /** Active request count */
+    activeRequestCount: number;
+    /** Bytes sent since last sample */
+    bytesSent: number;
+    /** Bytes received since last sample */
+    bytesReceived: number;
+    /** Slowest active request duration in ms */
+    slowestRequestMs?: number;
+    /** Availability status */
+    availability: MetricAvailability;
+}
+
+/**
+ * JS event loop stall detection sample.
+ *
+ * CAVEAT: This is an APPROXIMATE measurement, NOT exact.
+ * Uses setTimeout jitter as a proxy for event loop blocking.
+ * Can detect stalls ≥ 300ms wall-clock (200ms heartbeat + 100ms threshold).
+ * Sub-100ms micro-stalls will NOT be caught.
+ * Timer coalescing and OS scheduling can affect accuracy.
+ *
+ * This is NOT the sole source of truth for JS performance.
+ * It should be correlated with native CPU/render data for a complete picture.
+ */
+export interface JsProfileSample {
+    /** Whether JS thread is currently stalled */
+    isStalled: boolean;
+    /** Duration of current/last stall in ms (approximate) */
+    stallDurationMs?: number;
+    /** Estimated JS thread busy percentage */
+    jsBusyPercent?: number;
+    /** Bridge call count since last sample */
+    bridgeCallCount?: number;
+    /** Average bridge call latency in ms */
+    avgBridgeLatencyMs?: number;
+    /** Availability status */
+    availability: MetricAvailability;
+}
+
+// ─── Thermal / Energy ───────────────────────────────────────────────────────
+
+export interface ThermalSample {
+    /** Thermal state: 0 = nominal, 1 = fair, 2 = serious, 3 = critical */
+    thermalState: number;
+    /** Whether battery saver / low-power mode is active */
+    lowPowerMode?: boolean;
+    /** Availability status */
+    availability: MetricAvailability;
+}
+
+// ─── Composite Profiler Sample ──────────────────────────────────────────────
+
+/**
+ * A single batched profiler sample emitted from native.
+ * Contains all metric families collected in a single sampling window.
+ * Arrives pre-aggregated from native — JS does NOT compute these.
+ */
+export interface ProfilerSample extends ProfilerEvent {
+    family: 'profiler.metric.sample';
+    cpu?: CpuSample;
+    memory?: MemorySample;
+    threads?: ThreadSnapshot;
+    render?: RenderSample;
+    network?: NetworkProfileSample;
+    js?: JsProfileSample;
+    thermal?: ThermalSample;
+    /** Sample interval in ms (how often this sample fires) */
+    sampleIntervalMs: number;
+}
+
+// ─── Profiler Span ──────────────────────────────────────────────────────────
+
+export interface ProfilerSpan extends ProfilerEvent {
+    family: 'profiler.span.begin' | 'profiler.span.end';
+    /** Span name (e.g. 'screen_transition', 'network_request', 'user_interaction') */
+    spanName: string;
+    /** Unique span ID for begin/end matching */
+    spanId: string;
+    /** Duration in ms (only on span.end) */
+    durationMs?: number;
+    /** Associated metadata */
+    metadata?: Record<string, unknown>;
+}
+
+// ─── Profiler Incident ──────────────────────────────────────────────────────
+
+export interface ProfilerIncident extends ProfilerEvent {
+    family: 'profiler.incident';
+    /** Incident type identifier */
+    incidentType: IncidentType;
+    /** Human-readable title */
+    title: string;
+    /** Severity level */
+    severity: IncidentSeverity;
+    /** Confidence score */
+    confidence: IncidentConfidence;
+    /** Start timestamp */
+    startTimestamp: number;
+    /** End timestamp (if resolved) */
+    endTimestamp?: number;
+    /** Affected screen(s) — screen keys from visit windows */
+    affectedScreens: string[];
+    /** Screen visit IDs correlated with this incident */
+    affectedScreenVisitIds?: string[];
+    /** Related request IDs (from network interceptor) */
+    relatedRequests?: string[];
+    /** Related log entry IDs */
+    relatedLogs?: string[];
+    /** Related thread IDs */
+    relatedThreads?: number[];
+    /** Related span IDs */
+    relatedSpanIds?: string[];
+    /** Related replay/timeline markers */
+    relatedTimelineMarkers?: string[];
+    /** Suggested likely cause category */
+    likelyCause: string;
+    /** Descriptive text */
+    description: string;
+}
+
+// ─── Screen Summary ─────────────────────────────────────────────────────────
+
+export interface ProfilerScreenSummary extends ProfilerEvent {
+    family: 'profiler.screen.summary';
+    screenName: string;
+    /** Unique screen visit ID for correlating with samples/incidents */
+    screenVisitId?: string;
+    /** Absolute start timestamp of this screen visit */
+    visitStartTimestamp?: number;
+    /** Absolute end timestamp (set when screen exits) */
+    visitEndTimestamp?: number;
+    /** Duration this screen was active in ms */
+    durationMs: number;
+    /** Aggregated CPU stats for this screen */
+    avgCpuPercent?: number;
+    maxCpuPercent?: number;
+    /** Aggregated memory stats */
+    avgMemoryBytes?: number;
+    peakMemoryBytes?: number;
+    /** Frame stats */
+    avgFps?: number;
+    totalSlowFrames?: number;
+    totalFrozenFrames?: number;
+    /** Network stats */
+    requestCount?: number;
+    totalBytesTransferred?: number;
+    expensiveRequestCount?: number;
+    /** JS stats */
+    jsStallCount?: number;
+    totalJsStallMs?: number;
+    /** Incident count */
+    incidentCount?: number;
+    /** Thread peak count during screen visit */
+    peakThreadCount?: number;
+}
+
+// ─── Profiler Diagnostic ────────────────────────────────────────────────────
+
+export interface ProfilerDiagnostic extends ProfilerEvent {
+    family: 'profiler.diagnostic';
+    /** Diagnostic category */
+    category: string;
+    /** Human-readable message */
+    message: string;
+    /** Associated data */
+    data?: Record<string, unknown>;
+}
+
+// ─── Capabilities ───────────────────────────────────────────────────────────
+
+export interface ProfilerCapabilityEntry {
+    /** Whether this metric is available */
+    available: boolean;
+    /** Minimum API level / iOS version required */
+    minVersion?: string;
+    /** Current device API level / iOS version */
+    currentVersion?: string;
+    /** Whether live reporting is supported (vs deferred only) */
+    liveSupported: boolean;
+    /** Reason if unavailable */
+    reason?: string;
+}
+
+export interface ProfilerCapabilities extends ProfilerEvent {
+    family: 'profiler.capabilities';
+    platform: 'android' | 'ios';
+    /** Capabilities per metric group */
+    cpu: ProfilerCapabilityEntry;
+    memory: ProfilerCapabilityEntry;
+    threads: ProfilerCapabilityEntry;
+    render: ProfilerCapabilityEntry;
+    network: ProfilerCapabilityEntry;
+    js: ProfilerCapabilityEntry;
+    thermal: ProfilerCapabilityEntry;
+    diskIo: ProfilerCapabilityEntry;
+    /** Device model */
+    deviceModel: string;
+    /** OS version string */
+    osVersion: string;
+    /** App build type */
+    buildType: 'debug' | 'release';
+}
+
+// ─── Union ──────────────────────────────────────────────────────────────────
+
+export type AnyProfilerEvent =
+    | ProfilerSample
+    | ProfilerSpan
+    | ProfilerIncident
+    | ProfilerScreenSummary
+    | ProfilerDiagnostic
+    | ProfilerCapabilities;