@scalebun/react-native 1.0.2 → 1.0.4

package/src/features/profiler/ProfilerFeature.ts

@@ -1,661 +1,661 @@
-/**
- * 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,
-    ProfilerSample,
-    ProfilerIncident,
-    ProfilerScreenSummary,
-    JsProfileSample,
-} from './models';
-import { PROFILER_SCHEMA_VERSION } from './models';
-import type {
-    IProfilerNativeModule,
-    IProfilerFeature,
-    ProfilerState,
-    ProfilerTransportSink,
-} from './contracts';
-import { PROFILER_NATIVE_EVENTS } from './contracts';
-import { ProfilerConfig, mergeProfilerConfig, serializeProfilerConfig } from './config';
-import { ProfilerTransport } from './transport/ProfilerTransport';
-import { nativeModuleVia } from '../../core/architecture';
-
-// ─── JS Thread Stall Detector ──────────────────────────────────────────────
-
-/**
- * Lightweight JS event loop stall detector.
- *
- * HOW IT WORKS:
- * Posts a single setTimeout callback at a fixed interval.
- * If the callback fires significantly later than expected,
- * the JS thread was blocked during that window.
- *
- * This is the MINIMUM viable JS-side instrumentation:
- * - Single timer per interval (not a polling loop)
- * - ~0% overhead when event loop is healthy
- * - No complex buffer management
- * - Stall data is emitted as part of the native profiler batch
- *
- * OPT-IN: Enabled only when config.jsInstrumentationEnabled = true
- */
-class JsStallDetector {
-    private timerId: ReturnType<typeof setTimeout> | null = null;
-    private intervalMs: number;
-    private stallThresholdMs: number;
-    private lastTickMs: number = 0;
-    private stallCount: number = 0;
-    private totalStallMs: number = 0;
-    private currentStallDurationMs: number = 0;
-    private isStalled: boolean = false;
-    private running: boolean = false;
-
-    constructor(intervalMs: number = 200, stallThresholdMs: number = 100) {
-        this.intervalMs = intervalMs;
-        this.stallThresholdMs = stallThresholdMs;
-    }
-
-    start(): void {
-        if (this.running) return;
-        this.running = true;
-        this.lastTickMs = Date.now();
-        this.scheduleTick();
-    }
-
-    stop(): void {
-        this.running = false;
-        if (this.timerId !== null) {
-            clearTimeout(this.timerId);
-            this.timerId = null;
-        }
-    }
-
-    /**
-     * Collect current JS stall metrics and reset counters.
-     * Called by the profiler when building a composite sample.
-     */
-    collect(): JsProfileSample {
-        const result: JsProfileSample = {
-            isStalled: this.isStalled,
-            stallDurationMs: this.currentStallDurationMs > 0 ? this.currentStallDurationMs : undefined,
-            availability: this.running ? 'available' : 'unavailable',
-        };
-
-        // Reset per-window counters
-        this.stallCount = 0;
-        this.totalStallMs = 0;
-        this.currentStallDurationMs = 0;
-        this.isStalled = false;
-
-        return result;
-    }
-
-    private scheduleTick(): void {
-        if (!this.running) return;
-        this.timerId = setTimeout(() => this.onTick(), this.intervalMs);
-    }
-
-    private onTick(): void {
-        if (!this.running) return;
-
-        const now = Date.now();
-        const elapsed = now - this.lastTickMs;
-        const expectedMs = this.intervalMs;
-        const jitter = elapsed - expectedMs;
-
-        if (jitter > this.stallThresholdMs) {
-            // JS thread was blocked
-            this.isStalled = true;
-            this.stallCount++;
-            this.currentStallDurationMs = jitter;
-            this.totalStallMs += jitter;
-        } else {
-            this.isStalled = false;
-            this.currentStallDurationMs = 0;
-        }
-
-        this.lastTickMs = now;
-        this.scheduleTick();
-    }
-}
-
-// ─── Feature Implementation ────────────────────────────────────────────────
-
-export class ProfilerFeature implements IProfilerFeature {
-    readonly name = 'profiler' as const;
-
-    private state: ProfilerState = 'idle';
-    private config: ProfilerConfig;
-    private transport: ProfilerTransport;
-    private nativeModule: IProfilerNativeModule | null = null;
-    private eventListeners: Array<(event: AnyProfilerEvent) => void> = [];
-    private nativeSubscriptions: Array<{ remove(): void }> = [];
-    private capabilities: ProfilerCapabilities | null = null;
-    private sessionId: string = '';
-    private currentScreen: string = '';
-    private spanCounter: number = 0;
-
-    // Connection-aware backpressure
-    private transportConnected: boolean = false;
-    private transportStateUnsub: (() => void) | null = null;
-    private droppedEventCount: number = 0;
-
-    // JS instrumentation (opt-in)
-    private jsStallDetector: JsStallDetector | null = null;
-
-    // Runtime validation counter
-    private _samplesSent: number = 0;
-
-    constructor(config?: Partial<ProfilerConfig>) {
-        this.config = mergeProfilerConfig(config);
-        this.transport = new ProfilerTransport(this.config.maxBufferSize);
-    }
-
-    // ─── Lifecycle ──────────────────────────────────────────────────────
-
-    /**
-     * Initialize the profiler by resolving the native module.
-     * Does NOT start profiling — call start() for that.
-     */
-    async initialize(): Promise<void> {
-        try {
-            // Lazily require RN native modules to avoid module-scope crashes
-            const { NativeModules, NativeEventEmitter } = require('react-native');
-
-            // ─── Runtime Validation: Module Presence ──────────────────
-            // Prefer the codegen TurboModule (New Arch); fall back to NativeModules
-            // (Old Arch, iOS RCTEventEmitter interop, or no native build).
-            let mod: any = null;
-            let via = 'none';
-            try {
-                const turbo = require('../../specs/NativeScaleBunProfiler').default;
-                if (turbo) { mod = turbo; via = nativeModuleVia(); }
-            } catch {
-                // TurboModuleRegistry unavailable (web/SSR)
-            }
-            if (!mod) {
-                mod = NativeModules.ScaleBunProfiler ?? null;
-                if (mod) via = nativeModuleVia();
-            }
-            console.log(`[ScaleBun Profiler] ▶ Runtime check: ScaleBunProfiler = ${mod ? `FOUND ✅ via ${via}` : 'MISSING ❌'}`);
-            if (!mod) {
-                // List available native modules for debugging
-                const availableModules = Object.keys(NativeModules).filter(k => k.toLowerCase().includes('scalebun') || k.toLowerCase().includes('profiler') || k.toLowerCase().includes('scalebun'));
-                console.warn(`[ScaleBun Profiler] ❌ ScaleBunProfiler not found. Related modules: [${availableModules.join(', ') || 'none'}]`);
-                console.warn('[ScaleBun Profiler] ❌ Native module not found. It is autolinked via ScaleBunPackage — rebuild the app (npx react-native run-android) so autolinking registers it. Do NOT add packages to MainApplication.kt manually.');
-                this.state = 'error';
-                return;
-            }
-
-            this.nativeModule = mod as IProfilerNativeModule;
-            console.log('[ScaleBun Profiler] ✅ Native module resolved — wiring event listeners');
-
-            // Subscribe to batched native events — ONE subscription per event type.
-            // Native emits pre-batched payloads; JS only normalizes and forwards.
-            const emitter = new NativeEventEmitter(mod);
-
-            this.nativeSubscriptions = [
-                emitter.addListener(
-                    PROFILER_NATIVE_EVENTS.SAMPLE_BATCH,
-                    (batch: any) => this._handleNativeSampleBatch(batch),
-                ),
-                emitter.addListener(
-                    PROFILER_NATIVE_EVENTS.INCIDENT,
-                    (incident: any) => this._handleNativeIncident(incident),
-                ),
-                emitter.addListener(
-                    PROFILER_NATIVE_EVENTS.SCREEN_SUMMARY,
-                    (summary: any) => this._handleNativeScreenSummary(summary),
-                ),
-                emitter.addListener(
-                    PROFILER_NATIVE_EVENTS.THREAD_SNAPSHOT,
-                    (snapshot: any) => this._handleNativeThreadSnapshot(snapshot),
-                ),
-                emitter.addListener(
-                    PROFILER_NATIVE_EVENTS.CAPABILITIES,
-                    (caps: any) => this._handleNativeCapabilities(caps),
-                ),
-                emitter.addListener(
-                    PROFILER_NATIVE_EVENTS.STATE_CHANGED,
-                    (stateEvt: any) => this._handleNativeStateChanged(stateEvt),
-                ),
-            ];
-
-            console.log('[ScaleBun Profiler] ✅ Native module initialized, 6 event listeners wired');
-        } catch (e) {
-            console.warn('[ScaleBun Profiler] ❌ Failed to initialize native module:', e);
-            this.state = 'error';
-        }
-    }
-
-    /** Teardown and release all resources */
-    teardown(): void {
-        this.stop().catch(() => { });
-        // Remove all native subscriptions
-        for (const sub of this.nativeSubscriptions) {
-            try { sub.remove(); } catch { /* no-throw */ }
-        }
-        this.nativeSubscriptions = [];
-        this.eventListeners = [];
-        this.transport.reset();
-        this.nativeModule = null;
-        this.state = 'idle';
-        // Clean up transport state listener
-        if (this.transportStateUnsub) {
-            try { this.transportStateUnsub(); } catch { /* no-throw */ }
-            this.transportStateUnsub = null;
-        }
-        // Stop JS stall detector
-        this.jsStallDetector?.stop();
-        this.jsStallDetector = null;
-    }
-
-    // ─── Public API ─────────────────────────────────────────────────────
-
-    async start(): Promise<void> {
-        if (!this.nativeModule || !this.config.enabled) return;
-        // Desktop-only enforcement: the profiler must NEVER reach the backend.
-        // Its only valid sink is the desktop WebSocket debug transport, set via
-        // setTransportSink() during enableDebug(). If no desktop sink is connected
-        // there is no valid destination, so refuse to start — never fall back to
-        // any HTTP/backend path.
-        if (!this.transport.getSink()) {
-            console.warn('[ScaleBun Profiler] No desktop transport sink — refusing to start (profiler is desktop-only).');
-            return;
-        }
-        if (this.state === 'running') return;
-
-        try {
-            const serializedConfig = serializeProfilerConfig(this.config);
-            await this.nativeModule.startProfiler(serializedConfig);
-            this.state = 'running';
-
-            // Set session/screen context on native side
-            if (this.sessionId) {
-                this.nativeModule.setSessionId(this.sessionId).catch(() => { });
-            }
-            if (this.currentScreen) {
-                this.nativeModule.setCurrentScreen(this.currentScreen).catch(() => { });
-            }
-
-            // Start opt-in JS stall detector
-            if (this.config.jsInstrumentationEnabled) {
-                this.jsStallDetector = new JsStallDetector(200, 100);
-                this.jsStallDetector.start();
-            }
-
-            console.log('[ScaleBun Profiler] Started with preset:', this.config.samplingPreset);
-        } catch (e) {
-            console.warn('[ScaleBun Profiler] Failed to start:', e);
-            this.state = 'error';
-        }
-    }
-
-    async stop(): Promise<void> {
-        if (!this.nativeModule || this.state === 'idle') return;
-
-        try {
-            await this.nativeModule.stopProfiler();
-            this.state = 'idle';
-            // Stop JS stall detector
-            this.jsStallDetector?.stop();
-            this.jsStallDetector = null;
-            console.log('[ScaleBun Profiler] Stopped');
-        } catch (e) {
-            console.warn('[ScaleBun Profiler] Failed to stop:', e);
-        }
-    }
-
-    async pauseStream(): Promise<void> {
-        if (!this.nativeModule || this.state !== 'running') return;
-        try {
-            await this.nativeModule.pauseProfilerStream();
-            this.state = 'paused';
-        } catch (e) {
-            console.warn('[ScaleBun Profiler] Failed to pause:', e);
-        }
-    }
-
-    async resumeStream(): Promise<void> {
-        if (!this.nativeModule || this.state !== 'paused') return;
-        try {
-            await this.nativeModule.resumeProfilerStream();
-            this.state = 'running';
-        } catch (e) {
-            console.warn('[ScaleBun Profiler] Failed to resume:', e);
-        }
-    }
-
-    async captureSnapshot(): Promise<Record<string, unknown>> {
-        if (!this.nativeModule) return {};
-        try {
-            return await this.nativeModule.captureProfilerSnapshot();
-        } catch (e) {
-            console.warn('[ScaleBun Profiler] Snapshot failed:', e);
-            return {};
-        }
-    }
-
-    async getCapabilities(): Promise<ProfilerCapabilities | null> {
-        if (this.capabilities) return this.capabilities;
-        if (!this.nativeModule) return null;
-        try {
-            const raw = await this.nativeModule.getProfilerCapabilities();
-            this.capabilities = raw as unknown as ProfilerCapabilities;
-            return this.capabilities;
-        } catch (e) {
-            console.warn('[ScaleBun Profiler] Capabilities query failed:', e);
-            return null;
-        }
-    }
-
-    markSpan(name: string, metadata?: Record<string, unknown>): string {
-        const spanId = `span-${++this.spanCounter}-${Date.now()}`;
-        if (this.nativeModule && this.state === 'running') {
-            this.nativeModule.markProfilerSpan(name, spanId, metadata).catch(() => { });
-        }
-        return spanId;
-    }
-
-    endSpan(spanId: string): void {
-        if (this.nativeModule && this.state === 'running') {
-            this.nativeModule.endProfilerSpan(spanId).catch(() => { });
-        }
-    }
-
-    markInteraction(name: string): void {
-        const id = `interaction-${Date.now()}`;
-        if (this.nativeModule && this.state === 'running') {
-            this.nativeModule.markProfilerInteraction(id, name).catch(() => { });
-        }
-    }
-
-    async exportBundle(): Promise<Record<string, unknown>> {
-        if (!this.nativeModule) return {};
-        try {
-            return await this.nativeModule.flushProfilerExport();
-        } catch (e) {
-            console.warn('[ScaleBun Profiler] Export failed:', e);
-            return {};
-        }
-    }
-
-    getState(): ProfilerState {
-        return this.state;
-    }
-
-    isActive(): boolean {
-        return this.state === 'running' || this.state === 'paused';
-    }
-
-    onEvent(callback: (event: AnyProfilerEvent) => void): () => void {
-        this.eventListeners.push(callback);
-        return () => {
-            this.eventListeners = this.eventListeners.filter(l => l !== callback);
-        };
-    }
-
-    // ─── Transport Wiring ───────────────────────────────────────────────
-
-    /** Connect the debug transport for sending events to desktop */
-    setTransportSink(sink: ProfilerTransportSink | null): void {
-        this.transport.setSink(sink);
-        this._wireTransportBackpressure(sink);
-    }
-
-    /** Update session ID on native side */
-    setSessionId(sessionId: string): void {
-        this.sessionId = sessionId;
-        if (this.nativeModule && this.state !== 'idle') {
-            this.nativeModule.setSessionId(sessionId).catch(() => { });
-        }
-    }
-
-    /** Update current screen on native side for correlation */
-    setCurrentScreen(screenName: string): void {
-        this.currentScreen = screenName;
-        if (this.nativeModule && this.state !== 'idle') {
-            this.nativeModule.setCurrentScreen(screenName).catch(() => { });
-        }
-    }
-
-    // ─── Connection-Aware Backpressure ──────────────────────────────────
-
-    /**
-     * 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(sink: ProfilerTransportSink | null): void {
-        // Clean up previous listener
-        if (this.transportStateUnsub) {
-            try { this.transportStateUnsub(); } catch { /* no-throw */ }
-            this.transportStateUnsub = null;
-        }
-
-        if (!sink) {
-            this.transportConnected = false;
-            return;
-        }
-
-        // Check if the transport has onStateChange method
-        const transport = sink as any;
-        if (typeof transport.onStateChange === 'function') {
-            this.transportStateUnsub = transport.onStateChange((state: string) => {
-                const wasConnected = this.transportConnected;
-                this.transportConnected = state === 'connected';
-
-                if (!this.transportConnected && wasConnected && this.state === 'running') {
-                    // Desktop disconnected — pause native emission to save bridge bandwidth
-                    this.nativeModule?.pauseProfilerStream().catch(() => { });
-                    console.log('[ScaleBun Profiler] Transport disconnected — paused native stream');
-                } else if (this.transportConnected && !wasConnected && this.state === 'running') {
-                    // Desktop reconnected — resume native emission
-                    this.nativeModule?.resumeProfilerStream().catch(() => { });
-                    console.log('[ScaleBun Profiler] Transport reconnected — resumed native stream');
-                }
-            });
-        } else {
-            // If transport doesn't support state observation, assume connected
-            this.transportConnected = true;
-        }
-    }
-
-    // ─── Native Event Handlers ──────────────────────────────────────────
-    // These handle pre-batched, pre-aggregated data from native.
-    // JS only normalizes IDs, enriches with JS stall data, and forwards.
-
-    private _handleNativeSampleBatch(batch: any): void {
-        try {
-            const samples = Array.isArray(batch) ? batch : [batch];
-            for (const raw of samples) {
-                // Enrich with JS stall data if instrumentation is active
-                let jsData: JsProfileSample | undefined = raw.js;
-                if (this.jsStallDetector && this.config.jsInstrumentationEnabled) {
-                    jsData = this.jsStallDetector.collect();
-                }
-
-                const event: ProfilerSample = {
-                    id: raw.id || `sample-${Date.now()}-${Math.random().toString(36).substring(2, 6)}`,
-                    family: 'profiler.metric.sample',
-                    schemaVersion: PROFILER_SCHEMA_VERSION,
-                    context: {
-                        sessionId: this.sessionId,
-                        screenKey: raw.screenKey || this.currentScreen,
-                        timestamp: raw.timestamp || Date.now(),
-                        uptimeMs: raw.uptimeMs,
-                    },
-                    sampleIntervalMs: raw.sampleIntervalMs || this.config.cpuSampleIntervalMs,
-                    cpu: raw.cpu,
-                    memory: raw.memory,
-                    threads: raw.threads,
-                    render: raw.render,
-                    network: raw.network,
-                    js: jsData,
-                    thermal: raw.thermal,
-                };
-                this._emitEvent(event);
-
-                // ─── Runtime Validation: First sample emitted ────────
-                this._samplesSent = (this._samplesSent || 0) + 1;
-                if (this._samplesSent === 1) {
-                    console.log(`[ScaleBun Profiler] ✅ First profiler sample emitted to transport (id: ${event.id})`);
-                } else if (this._samplesSent % 50 === 0) {
-                    console.log(`[ScaleBun Profiler] 📊 ${this._samplesSent} profiler samples emitted so far`);
-                }
-            }
-        } catch (e) {
-            // No-throw
-        }
-    }
-
-    private _handleNativeIncident(raw: any): void {
-        try {
-            const event: ProfilerIncident = {
-                id: raw.id || `incident-${Date.now()}`,
-                family: 'profiler.incident',
-                schemaVersion: PROFILER_SCHEMA_VERSION,
-                context: {
-                    sessionId: this.sessionId,
-                    screenKey: raw.screenKey || this.currentScreen,
-                    timestamp: raw.timestamp || Date.now(),
-                },
-                incidentType: raw.incidentType,
-                title: raw.title,
-                severity: raw.severity || 'warning',
-                confidence: raw.confidence || 'medium',
-                startTimestamp: raw.startTimestamp || Date.now(),
-                endTimestamp: raw.endTimestamp,
-                affectedScreens: raw.affectedScreens || [this.currentScreen].filter(Boolean),
-                relatedRequests: raw.relatedRequests,
-                relatedLogs: raw.relatedLogs,
-                relatedThreads: raw.relatedThreads,
-                likelyCause: raw.likelyCause || 'unknown',
-                description: raw.description || '',
-            };
-            this._emitEvent(event);
-        } catch (e) {
-            // No-throw
-        }
-    }
-
-    private _handleNativeScreenSummary(raw: any): void {
-        try {
-            const event: ProfilerScreenSummary = {
-                id: raw.id || `screen-summary-${Date.now()}`,
-                family: 'profiler.screen.summary',
-                schemaVersion: PROFILER_SCHEMA_VERSION,
-                context: {
-                    sessionId: this.sessionId,
-                    screenKey: raw.screenName,
-                    timestamp: raw.timestamp || Date.now(),
-                },
-                screenName: raw.screenName,
-                durationMs: raw.durationMs || 0,
-                avgCpuPercent: raw.avgCpuPercent,
-                maxCpuPercent: raw.maxCpuPercent,
-                avgMemoryBytes: raw.avgMemoryBytes,
-                peakMemoryBytes: raw.peakMemoryBytes,
-                avgFps: raw.avgFps,
-                totalSlowFrames: raw.totalSlowFrames,
-                totalFrozenFrames: raw.totalFrozenFrames,
-                requestCount: raw.requestCount,
-                totalBytesTransferred: raw.totalBytesTransferred,
-                jsStallCount: raw.jsStallCount,
-                totalJsStallMs: raw.totalJsStallMs,
-                incidentCount: raw.incidentCount,
-            };
-            this._emitEvent(event);
-        } catch (e) {
-            // No-throw
-        }
-    }
-
-    private _handleNativeThreadSnapshot(raw: any): void {
-        try {
-            const event: AnyProfilerEvent = {
-                id: raw.id || `thread-snap-${Date.now()}`,
-                family: 'profiler.thread.snapshot',
-                schemaVersion: PROFILER_SCHEMA_VERSION,
-                context: {
-                    sessionId: this.sessionId,
-                    screenKey: this.currentScreen,
-                    timestamp: raw.timestamp || Date.now(),
-                },
-                ...raw,
-            };
-            this._emitEvent(event);
-        } catch (e) {
-            // No-throw
-        }
-    }
-
-    private _handleNativeCapabilities(raw: any): void {
-        try {
-            this.capabilities = raw as ProfilerCapabilities;
-            console.log(`[ScaleBun Profiler] ✅ Capabilities received: platform=${raw?.platform || 'unknown'}`);
-            const event: AnyProfilerEvent = {
-                id: `caps-${Date.now()}`,
-                family: 'profiler.capabilities',
-                schemaVersion: PROFILER_SCHEMA_VERSION,
-                context: {
-                    sessionId: this.sessionId,
-                    timestamp: Date.now(),
-                },
-                ...raw,
-            };
-            this._emitEvent(event);
-        } catch (e) {
-            // No-throw
-        }
-    }
-
-    private _handleNativeStateChanged(stateEvt: any): void {
-        try {
-            const nativeState = stateEvt?.state;
-            if (nativeState === 'running') this.state = 'running';
-            else if (nativeState === 'paused') this.state = 'paused';
-            else if (nativeState === 'idle') this.state = 'idle';
-        } catch {
-            // No-throw
-        }
-    }
-
-    /** Emit event to transport + listeners */
-    private _emitEvent(event: AnyProfilerEvent): void {
-        // Forward to transport (→ desktop)
-        this.transport.sendEvent(event);
-
-        // Notify listeners
-        for (const listener of this.eventListeners) {
-            try { listener(event); } catch { /* no-throw */ }
-        }
-    }
-}
+/**
+ * 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,
+    ProfilerSample,
+    ProfilerIncident,
+    ProfilerScreenSummary,
+    JsProfileSample,
+} from './models';
+import { PROFILER_SCHEMA_VERSION } from './models';
+import type {
+    IProfilerNativeModule,
+    IProfilerFeature,
+    ProfilerState,
+    ProfilerTransportSink,
+} from './contracts';
+import { PROFILER_NATIVE_EVENTS } from './contracts';
+import { ProfilerConfig, mergeProfilerConfig, serializeProfilerConfig } from './config';
+import { ProfilerTransport } from './transport/ProfilerTransport';
+import { nativeModuleVia } from '../../core/architecture';
+
+// ─── JS Thread Stall Detector ──────────────────────────────────────────────
+
+/**
+ * Lightweight JS event loop stall detector.
+ *
+ * HOW IT WORKS:
+ * Posts a single setTimeout callback at a fixed interval.
+ * If the callback fires significantly later than expected,
+ * the JS thread was blocked during that window.
+ *
+ * This is the MINIMUM viable JS-side instrumentation:
+ * - Single timer per interval (not a polling loop)
+ * - ~0% overhead when event loop is healthy
+ * - No complex buffer management
+ * - Stall data is emitted as part of the native profiler batch
+ *
+ * OPT-IN: Enabled only when config.jsInstrumentationEnabled = true
+ */
+class JsStallDetector {
+    private timerId: ReturnType<typeof setTimeout> | null = null;
+    private intervalMs: number;
+    private stallThresholdMs: number;
+    private lastTickMs: number = 0;
+    private stallCount: number = 0;
+    private totalStallMs: number = 0;
+    private currentStallDurationMs: number = 0;
+    private isStalled: boolean = false;
+    private running: boolean = false;
+
+    constructor(intervalMs: number = 200, stallThresholdMs: number = 100) {
+        this.intervalMs = intervalMs;
+        this.stallThresholdMs = stallThresholdMs;
+    }
+
+    start(): void {
+        if (this.running) return;
+        this.running = true;
+        this.lastTickMs = Date.now();
+        this.scheduleTick();
+    }
+
+    stop(): void {
+        this.running = false;
+        if (this.timerId !== null) {
+            clearTimeout(this.timerId);
+            this.timerId = null;
+        }
+    }
+
+    /**
+     * Collect current JS stall metrics and reset counters.
+     * Called by the profiler when building a composite sample.
+     */
+    collect(): JsProfileSample {
+        const result: JsProfileSample = {
+            isStalled: this.isStalled,
+            stallDurationMs: this.currentStallDurationMs > 0 ? this.currentStallDurationMs : undefined,
+            availability: this.running ? 'available' : 'unavailable',
+        };
+
+        // Reset per-window counters
+        this.stallCount = 0;
+        this.totalStallMs = 0;
+        this.currentStallDurationMs = 0;
+        this.isStalled = false;
+
+        return result;
+    }
+
+    private scheduleTick(): void {
+        if (!this.running) return;
+        this.timerId = setTimeout(() => this.onTick(), this.intervalMs);
+    }
+
+    private onTick(): void {
+        if (!this.running) return;
+
+        const now = Date.now();
+        const elapsed = now - this.lastTickMs;
+        const expectedMs = this.intervalMs;
+        const jitter = elapsed - expectedMs;
+
+        if (jitter > this.stallThresholdMs) {
+            // JS thread was blocked
+            this.isStalled = true;
+            this.stallCount++;
+            this.currentStallDurationMs = jitter;
+            this.totalStallMs += jitter;
+        } else {
+            this.isStalled = false;
+            this.currentStallDurationMs = 0;
+        }
+
+        this.lastTickMs = now;
+        this.scheduleTick();
+    }
+}
+
+// ─── Feature Implementation ────────────────────────────────────────────────
+
+export class ProfilerFeature implements IProfilerFeature {
+    readonly name = 'profiler' as const;
+
+    private state: ProfilerState = 'idle';
+    private config: ProfilerConfig;
+    private transport: ProfilerTransport;
+    private nativeModule: IProfilerNativeModule | null = null;
+    private eventListeners: Array<(event: AnyProfilerEvent) => void> = [];
+    private nativeSubscriptions: Array<{ remove(): void }> = [];
+    private capabilities: ProfilerCapabilities | null = null;
+    private sessionId: string = '';
+    private currentScreen: string = '';
+    private spanCounter: number = 0;
+
+    // Connection-aware backpressure
+    private transportConnected: boolean = false;
+    private transportStateUnsub: (() => void) | null = null;
+    private droppedEventCount: number = 0;
+
+    // JS instrumentation (opt-in)
+    private jsStallDetector: JsStallDetector | null = null;
+
+    // Runtime validation counter
+    private _samplesSent: number = 0;
+
+    constructor(config?: Partial<ProfilerConfig>) {
+        this.config = mergeProfilerConfig(config);
+        this.transport = new ProfilerTransport(this.config.maxBufferSize);
+    }
+
+    // ─── Lifecycle ──────────────────────────────────────────────────────
+
+    /**
+     * Initialize the profiler by resolving the native module.
+     * Does NOT start profiling — call start() for that.
+     */
+    async initialize(): Promise<void> {
+        try {
+            // Lazily require RN native modules to avoid module-scope crashes
+            const { NativeModules, NativeEventEmitter } = require('react-native');
+
+            // ─── Runtime Validation: Module Presence ──────────────────
+            // Prefer the codegen TurboModule (New Arch); fall back to NativeModules
+            // (Old Arch, iOS RCTEventEmitter interop, or no native build).
+            let mod: any = null;
+            let via = 'none';
+            try {
+                const turbo = require('../../specs/NativeScaleBunProfiler').default;
+                if (turbo) { mod = turbo; via = nativeModuleVia(); }
+            } catch {
+                // TurboModuleRegistry unavailable (web/SSR)
+            }
+            if (!mod) {
+                mod = NativeModules.ScaleBunProfiler ?? null;
+                if (mod) via = nativeModuleVia();
+            }
+            console.log(`[ScaleBun Profiler] ▶ Runtime check: ScaleBunProfiler = ${mod ? `FOUND ✅ via ${via}` : 'MISSING ❌'}`);
+            if (!mod) {
+                // List available native modules for debugging
+                const availableModules = Object.keys(NativeModules).filter(k => k.toLowerCase().includes('scalebun') || k.toLowerCase().includes('profiler') || k.toLowerCase().includes('scalebun'));
+                console.warn(`[ScaleBun Profiler] ❌ ScaleBunProfiler not found. Related modules: [${availableModules.join(', ') || 'none'}]`);
+                console.warn('[ScaleBun Profiler] ❌ Native module not found. It is autolinked via ScaleBunPackage — rebuild the app (npx react-native run-android) so autolinking registers it. Do NOT add packages to MainApplication.kt manually.');
+                this.state = 'error';
+                return;
+            }
+
+            this.nativeModule = mod as IProfilerNativeModule;
+            console.log('[ScaleBun Profiler] ✅ Native module resolved — wiring event listeners');
+
+            // Subscribe to batched native events — ONE subscription per event type.
+            // Native emits pre-batched payloads; JS only normalizes and forwards.
+            const emitter = new NativeEventEmitter(mod);
+
+            this.nativeSubscriptions = [
+                emitter.addListener(
+                    PROFILER_NATIVE_EVENTS.SAMPLE_BATCH,
+                    (batch: any) => this._handleNativeSampleBatch(batch),
+                ),
+                emitter.addListener(
+                    PROFILER_NATIVE_EVENTS.INCIDENT,
+                    (incident: any) => this._handleNativeIncident(incident),
+                ),
+                emitter.addListener(
+                    PROFILER_NATIVE_EVENTS.SCREEN_SUMMARY,
+                    (summary: any) => this._handleNativeScreenSummary(summary),
+                ),
+                emitter.addListener(
+                    PROFILER_NATIVE_EVENTS.THREAD_SNAPSHOT,
+                    (snapshot: any) => this._handleNativeThreadSnapshot(snapshot),
+                ),
+                emitter.addListener(
+                    PROFILER_NATIVE_EVENTS.CAPABILITIES,
+                    (caps: any) => this._handleNativeCapabilities(caps),
+                ),
+                emitter.addListener(
+                    PROFILER_NATIVE_EVENTS.STATE_CHANGED,
+                    (stateEvt: any) => this._handleNativeStateChanged(stateEvt),
+                ),
+            ];
+
+            console.log('[ScaleBun Profiler] ✅ Native module initialized, 6 event listeners wired');
+        } catch (e) {
+            console.warn('[ScaleBun Profiler] ❌ Failed to initialize native module:', e);
+            this.state = 'error';
+        }
+    }
+
+    /** Teardown and release all resources */
+    teardown(): void {
+        this.stop().catch(() => { });
+        // Remove all native subscriptions
+        for (const sub of this.nativeSubscriptions) {
+            try { sub.remove(); } catch { /* no-throw */ }
+        }
+        this.nativeSubscriptions = [];
+        this.eventListeners = [];
+        this.transport.reset();
+        this.nativeModule = null;
+        this.state = 'idle';
+        // Clean up transport state listener
+        if (this.transportStateUnsub) {
+            try { this.transportStateUnsub(); } catch { /* no-throw */ }
+            this.transportStateUnsub = null;
+        }
+        // Stop JS stall detector
+        this.jsStallDetector?.stop();
+        this.jsStallDetector = null;
+    }
+
+    // ─── Public API ─────────────────────────────────────────────────────
+
+    async start(): Promise<void> {
+        if (!this.nativeModule || !this.config.enabled) return;
+        // Desktop-only enforcement: the profiler must NEVER reach the backend.
+        // Its only valid sink is the desktop WebSocket debug transport, set via
+        // setTransportSink() during enableDebug(). If no desktop sink is connected
+        // there is no valid destination, so refuse to start — never fall back to
+        // any HTTP/backend path.
+        if (!this.transport.getSink()) {
+            console.warn('[ScaleBun Profiler] No desktop transport sink — refusing to start (profiler is desktop-only).');
+            return;
+        }
+        if (this.state === 'running') return;
+
+        try {
+            const serializedConfig = serializeProfilerConfig(this.config);
+            await this.nativeModule.startProfiler(serializedConfig);
+            this.state = 'running';
+
+            // Set session/screen context on native side
+            if (this.sessionId) {
+                this.nativeModule.setSessionId(this.sessionId).catch(() => { });
+            }
+            if (this.currentScreen) {
+                this.nativeModule.setCurrentScreen(this.currentScreen).catch(() => { });
+            }
+
+            // Start opt-in JS stall detector
+            if (this.config.jsInstrumentationEnabled) {
+                this.jsStallDetector = new JsStallDetector(200, 100);
+                this.jsStallDetector.start();
+            }
+
+            console.log('[ScaleBun Profiler] Started with preset:', this.config.samplingPreset);
+        } catch (e) {
+            console.warn('[ScaleBun Profiler] Failed to start:', e);
+            this.state = 'error';
+        }
+    }
+
+    async stop(): Promise<void> {
+        if (!this.nativeModule || this.state === 'idle') return;
+
+        try {
+            await this.nativeModule.stopProfiler();
+            this.state = 'idle';
+            // Stop JS stall detector
+            this.jsStallDetector?.stop();
+            this.jsStallDetector = null;
+            console.log('[ScaleBun Profiler] Stopped');
+        } catch (e) {
+            console.warn('[ScaleBun Profiler] Failed to stop:', e);
+        }
+    }
+
+    async pauseStream(): Promise<void> {
+        if (!this.nativeModule || this.state !== 'running') return;
+        try {
+            await this.nativeModule.pauseProfilerStream();
+            this.state = 'paused';
+        } catch (e) {
+            console.warn('[ScaleBun Profiler] Failed to pause:', e);
+        }
+    }
+
+    async resumeStream(): Promise<void> {
+        if (!this.nativeModule || this.state !== 'paused') return;
+        try {
+            await this.nativeModule.resumeProfilerStream();
+            this.state = 'running';
+        } catch (e) {
+            console.warn('[ScaleBun Profiler] Failed to resume:', e);
+        }
+    }
+
+    async captureSnapshot(): Promise<Record<string, unknown>> {
+        if (!this.nativeModule) return {};
+        try {
+            return await this.nativeModule.captureProfilerSnapshot();
+        } catch (e) {
+            console.warn('[ScaleBun Profiler] Snapshot failed:', e);
+            return {};
+        }
+    }
+
+    async getCapabilities(): Promise<ProfilerCapabilities | null> {
+        if (this.capabilities) return this.capabilities;
+        if (!this.nativeModule) return null;
+        try {
+            const raw = await this.nativeModule.getProfilerCapabilities();
+            this.capabilities = raw as unknown as ProfilerCapabilities;
+            return this.capabilities;
+        } catch (e) {
+            console.warn('[ScaleBun Profiler] Capabilities query failed:', e);
+            return null;
+        }
+    }
+
+    markSpan(name: string, metadata?: Record<string, unknown>): string {
+        const spanId = `span-${++this.spanCounter}-${Date.now()}`;
+        if (this.nativeModule && this.state === 'running') {
+            this.nativeModule.markProfilerSpan(name, spanId, metadata).catch(() => { });
+        }
+        return spanId;
+    }
+
+    endSpan(spanId: string): void {
+        if (this.nativeModule && this.state === 'running') {
+            this.nativeModule.endProfilerSpan(spanId).catch(() => { });
+        }
+    }
+
+    markInteraction(name: string): void {
+        const id = `interaction-${Date.now()}`;
+        if (this.nativeModule && this.state === 'running') {
+            this.nativeModule.markProfilerInteraction(id, name).catch(() => { });
+        }
+    }
+
+    async exportBundle(): Promise<Record<string, unknown>> {
+        if (!this.nativeModule) return {};
+        try {
+            return await this.nativeModule.flushProfilerExport();
+        } catch (e) {
+            console.warn('[ScaleBun Profiler] Export failed:', e);
+            return {};
+        }
+    }
+
+    getState(): ProfilerState {
+        return this.state;
+    }
+
+    isActive(): boolean {
+        return this.state === 'running' || this.state === 'paused';
+    }
+
+    onEvent(callback: (event: AnyProfilerEvent) => void): () => void {
+        this.eventListeners.push(callback);
+        return () => {
+            this.eventListeners = this.eventListeners.filter(l => l !== callback);
+        };
+    }
+
+    // ─── Transport Wiring ───────────────────────────────────────────────
+
+    /** Connect the debug transport for sending events to desktop */
+    setTransportSink(sink: ProfilerTransportSink | null): void {
+        this.transport.setSink(sink);
+        this._wireTransportBackpressure(sink);
+    }
+
+    /** Update session ID on native side */
+    setSessionId(sessionId: string): void {
+        this.sessionId = sessionId;
+        if (this.nativeModule && this.state !== 'idle') {
+            this.nativeModule.setSessionId(sessionId).catch(() => { });
+        }
+    }
+
+    /** Update current screen on native side for correlation */
+    setCurrentScreen(screenName: string): void {
+        this.currentScreen = screenName;
+        if (this.nativeModule && this.state !== 'idle') {
+            this.nativeModule.setCurrentScreen(screenName).catch(() => { });
+        }
+    }
+
+    // ─── Connection-Aware Backpressure ──────────────────────────────────
+
+    /**
+     * 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(sink: ProfilerTransportSink | null): void {
+        // Clean up previous listener
+        if (this.transportStateUnsub) {
+            try { this.transportStateUnsub(); } catch { /* no-throw */ }
+            this.transportStateUnsub = null;
+        }
+
+        if (!sink) {
+            this.transportConnected = false;
+            return;
+        }
+
+        // Check if the transport has onStateChange method
+        const transport = sink as any;
+        if (typeof transport.onStateChange === 'function') {
+            this.transportStateUnsub = transport.onStateChange((state: string) => {
+                const wasConnected = this.transportConnected;
+                this.transportConnected = state === 'connected';
+
+                if (!this.transportConnected && wasConnected && this.state === 'running') {
+                    // Desktop disconnected — pause native emission to save bridge bandwidth
+                    this.nativeModule?.pauseProfilerStream().catch(() => { });
+                    console.log('[ScaleBun Profiler] Transport disconnected — paused native stream');
+                } else if (this.transportConnected && !wasConnected && this.state === 'running') {
+                    // Desktop reconnected — resume native emission
+                    this.nativeModule?.resumeProfilerStream().catch(() => { });
+                    console.log('[ScaleBun Profiler] Transport reconnected — resumed native stream');
+                }
+            });
+        } else {
+            // If transport doesn't support state observation, assume connected
+            this.transportConnected = true;
+        }
+    }
+
+    // ─── Native Event Handlers ──────────────────────────────────────────
+    // These handle pre-batched, pre-aggregated data from native.
+    // JS only normalizes IDs, enriches with JS stall data, and forwards.
+
+    private _handleNativeSampleBatch(batch: any): void {
+        try {
+            const samples = Array.isArray(batch) ? batch : [batch];
+            for (const raw of samples) {
+                // Enrich with JS stall data if instrumentation is active
+                let jsData: JsProfileSample | undefined = raw.js;
+                if (this.jsStallDetector && this.config.jsInstrumentationEnabled) {
+                    jsData = this.jsStallDetector.collect();
+                }
+
+                const event: ProfilerSample = {
+                    id: raw.id || `sample-${Date.now()}-${Math.random().toString(36).substring(2, 6)}`,
+                    family: 'profiler.metric.sample',
+                    schemaVersion: PROFILER_SCHEMA_VERSION,
+                    context: {
+                        sessionId: this.sessionId,
+                        screenKey: raw.screenKey || this.currentScreen,
+                        timestamp: raw.timestamp || Date.now(),
+                        uptimeMs: raw.uptimeMs,
+                    },
+                    sampleIntervalMs: raw.sampleIntervalMs || this.config.cpuSampleIntervalMs,
+                    cpu: raw.cpu,
+                    memory: raw.memory,
+                    threads: raw.threads,
+                    render: raw.render,
+                    network: raw.network,
+                    js: jsData,
+                    thermal: raw.thermal,
+                };
+                this._emitEvent(event);
+
+                // ─── Runtime Validation: First sample emitted ────────
+                this._samplesSent = (this._samplesSent || 0) + 1;
+                if (this._samplesSent === 1) {
+                    console.log(`[ScaleBun Profiler] ✅ First profiler sample emitted to transport (id: ${event.id})`);
+                } else if (this._samplesSent % 50 === 0) {
+                    console.log(`[ScaleBun Profiler] 📊 ${this._samplesSent} profiler samples emitted so far`);
+                }
+            }
+        } catch (e) {
+            // No-throw
+        }
+    }
+
+    private _handleNativeIncident(raw: any): void {
+        try {
+            const event: ProfilerIncident = {
+                id: raw.id || `incident-${Date.now()}`,
+                family: 'profiler.incident',
+                schemaVersion: PROFILER_SCHEMA_VERSION,
+                context: {
+                    sessionId: this.sessionId,
+                    screenKey: raw.screenKey || this.currentScreen,
+                    timestamp: raw.timestamp || Date.now(),
+                },
+                incidentType: raw.incidentType,
+                title: raw.title,
+                severity: raw.severity || 'warning',
+                confidence: raw.confidence || 'medium',
+                startTimestamp: raw.startTimestamp || Date.now(),
+                endTimestamp: raw.endTimestamp,
+                affectedScreens: raw.affectedScreens || [this.currentScreen].filter(Boolean),
+                relatedRequests: raw.relatedRequests,
+                relatedLogs: raw.relatedLogs,
+                relatedThreads: raw.relatedThreads,
+                likelyCause: raw.likelyCause || 'unknown',
+                description: raw.description || '',
+            };
+            this._emitEvent(event);
+        } catch (e) {
+            // No-throw
+        }
+    }
+
+    private _handleNativeScreenSummary(raw: any): void {
+        try {
+            const event: ProfilerScreenSummary = {
+                id: raw.id || `screen-summary-${Date.now()}`,
+                family: 'profiler.screen.summary',
+                schemaVersion: PROFILER_SCHEMA_VERSION,
+                context: {
+                    sessionId: this.sessionId,
+                    screenKey: raw.screenName,
+                    timestamp: raw.timestamp || Date.now(),
+                },
+                screenName: raw.screenName,
+                durationMs: raw.durationMs || 0,
+                avgCpuPercent: raw.avgCpuPercent,
+                maxCpuPercent: raw.maxCpuPercent,
+                avgMemoryBytes: raw.avgMemoryBytes,
+                peakMemoryBytes: raw.peakMemoryBytes,
+                avgFps: raw.avgFps,
+                totalSlowFrames: raw.totalSlowFrames,
+                totalFrozenFrames: raw.totalFrozenFrames,
+                requestCount: raw.requestCount,
+                totalBytesTransferred: raw.totalBytesTransferred,
+                jsStallCount: raw.jsStallCount,
+                totalJsStallMs: raw.totalJsStallMs,
+                incidentCount: raw.incidentCount,
+            };
+            this._emitEvent(event);
+        } catch (e) {
+            // No-throw
+        }
+    }
+
+    private _handleNativeThreadSnapshot(raw: any): void {
+        try {
+            const event: AnyProfilerEvent = {
+                id: raw.id || `thread-snap-${Date.now()}`,
+                family: 'profiler.thread.snapshot',
+                schemaVersion: PROFILER_SCHEMA_VERSION,
+                context: {
+                    sessionId: this.sessionId,
+                    screenKey: this.currentScreen,
+                    timestamp: raw.timestamp || Date.now(),
+                },
+                ...raw,
+            };
+            this._emitEvent(event);
+        } catch (e) {
+            // No-throw
+        }
+    }
+
+    private _handleNativeCapabilities(raw: any): void {
+        try {
+            this.capabilities = raw as ProfilerCapabilities;
+            console.log(`[ScaleBun Profiler] ✅ Capabilities received: platform=${raw?.platform || 'unknown'}`);
+            const event: AnyProfilerEvent = {
+                id: `caps-${Date.now()}`,
+                family: 'profiler.capabilities',
+                schemaVersion: PROFILER_SCHEMA_VERSION,
+                context: {
+                    sessionId: this.sessionId,
+                    timestamp: Date.now(),
+                },
+                ...raw,
+            };
+            this._emitEvent(event);
+        } catch (e) {
+            // No-throw
+        }
+    }
+
+    private _handleNativeStateChanged(stateEvt: any): void {
+        try {
+            const nativeState = stateEvt?.state;
+            if (nativeState === 'running') this.state = 'running';
+            else if (nativeState === 'paused') this.state = 'paused';
+            else if (nativeState === 'idle') this.state = 'idle';
+        } catch {
+            // No-throw
+        }
+    }
+
+    /** Emit event to transport + listeners */
+    private _emitEvent(event: AnyProfilerEvent): void {
+        // Forward to transport (→ desktop)
+        this.transport.sendEvent(event);
+
+        // Notify listeners
+        for (const listener of this.eventListeners) {
+            try { listener(event); } catch { /* no-throw */ }
+        }
+    }
+}