@scalebun/react-native 1.0.3 → 1.1.0

package/src/features/engage/engageTypes.ts

@@ -110,6 +110,21 @@ export interface EngageCampaignConfig {
     storeUrl?: string;
     highRatingThreshold?: number;
     routeLowToFeedback?: boolean;
+    /**
+     * Route this campaign's submission to BUG REPORTS instead of Engage responses.
+     *
+     * Engage responses and bug reports are different products: a survey response measures sentiment
+     * in aggregate, while a bug report is a single item that gets a status, a priority and an
+     * assignee on /diagnose/bug-reports. A FEEDBACK campaign triggered by `shake_device` is almost
+     * always the second kind — someone shook the phone because something is broken.
+     *
+     * Opt-IN per campaign rather than rerouting every FEEDBACK campaign, because rerouting would
+     * silently break existing sentiment surveys, and because the destination should be visible to
+     * whoever configures the campaign rather than inferred from its trigger.
+     *
+     * Absent/false keeps the existing behaviour exactly.
+     */
+    fileAsBugReport?: boolean;
     enabled: boolean;
 }
 

package/src/features/journey/ScaleBunDebugRoot.tsx

@@ -30,6 +30,7 @@ import React, {
 import { View, NativeEventEmitter, NativeModules } from 'react-native';
 import { emitAutomaticEvent } from '../../analytics/automaticEvents';
 import { resolveTouchTarget, describeTouchTarget } from './touchTarget';
+import { resolvePlatformOS } from '../../core/context/device';
 
 // ─── Lazy imports to avoid native module cascade at load time ────────────────
 // We only import TYPE references at the top level; actual modules are require()'d
@@ -159,7 +160,7 @@ export function ScaleBunDebugRoot({
                                         byteSize: result.sizeBytes || Math.round(result.base64.length * 0.75),
                                         format: (result.format ?? 'jpeg') as string,
                                         frameHash: (result as any).frameHash as string | undefined,
-                                        platform: (Platform.OS === 'ios' ? 'ios' : 'android') as 'android' | 'ios',
+                                        platform: resolvePlatformOS() as 'android' | 'ios',
                                     };
                                 } catch {
                                     return null;

package/src/features/ota/OtaOrchestrator.ts

@@ -11,10 +11,14 @@ import { noThrow } from '../../core/lifecycle/crashSafe';
 import NativeScaleBunOta from '../../specs/NativeScaleBunOta';
 import type { OtaCheckRequest, OtaCheckResponse, OtaBundlePayload } from './OtaTypes';
 import { otaEventEmitter } from './OtaEventEmitter';
+import { getDeviceCountry, prefetchDeviceCountry } from './geoCountry';
+import { deviceTargetingAttributes } from './deviceAttributes';
+import { K_INSTALLATION_ID } from '../../analytics/EventTracker';
 import { verifyBundleSignature, type SignatureConfig } from './signature';
 import { detectOtaEnvironment, type OtaEnvironment } from './environment';
 import { retryWithBackoff, isRetryableNetworkError, HttpStatusError } from './retry';
 import { createStorageBackend, type StorageBackend } from '../../storage/StorageBackend';
+import { resolveMobileOS } from '../../core/context/device';
 
 /**
  * Identity marker injected into the bundle by `scalebun ota publish` before
@@ -67,6 +71,36 @@ function subscribeNativeProgress(
 /** POST at most once per this interval; first and terminal ticks always go. */
 const PROGRESS_POST_INTERVAL_MS = 1_000;
 
+/**
+ * P8 — the SDK's canonical per-install id, shared with the analytics lane.
+ *
+ * OTA used to REQUIRE a caller-supplied `installationId`, and the documented
+ * example passed `deviceId` — so OTA telemetry lived in its own identity
+ * namespace, disconnected from the id every other lane reports. Every join
+ * from OTA data to CDP data (blast radius, MRR-at-risk, churn bands) was a
+ * cross-namespace join that matched by luck.
+ *
+ * Reads (or mints, for OTA-only apps that never initialize analytics) the same
+ * persisted value `EventTracker` uses, via the same storage backend and the
+ * same exported key — one install, one id, every lane.
+ */
+function resolveInstallationId(): string {
+  try {
+    const storage = createStorageBackend();
+    const existing = storage.get(K_INSTALLATION_ID);
+    if (existing) return existing;
+    const id = `inst-${Math.random().toString(36).slice(2, 10)}${Math.random()
+      .toString(36)
+      .slice(2, 10)}`;
+    storage.set(K_INSTALLATION_ID, id);
+    return id;
+  } catch {
+    // Storage unavailable (tests, exotic hosts): a per-process id keeps sync
+    // functional; it will stabilize on the first run where storage works.
+    return `inst-ephemeral-${Math.random().toString(36).slice(2, 10)}`;
+  }
+}
+
 /**
  * Deliver queued OTA lifecycle events to the backend's batch endpoint.
  *
@@ -93,13 +127,18 @@ async function deliverOtaEvents(params: {
 }): Promise<void> {
   const events = otaEventEmitter.flush();
   if (!events.length) return;
+  // A platform OTA cannot serve is not reported as Android — it is not reported at all.
+  const mobileOS = resolveMobileOS();
+  if (!mobileOS) return;
 
   const items = events.map((e) => ({
     kind: 'ota_event' as const,
     type: e.type,
     bundleId: e.bundleId,
     installationId: params.installationId,
-    platform: Platform.OS === 'ios' ? 'ios' : 'android',
+    // OTA bundles are compiled per platform, so this genuinely is ios|android. Narrowed via
+    // resolveMobileOS so a non-mobile RN target is skipped rather than served an Android bundle.
+    platform: mobileOS,
     appVersion: params.appVersion,
     durationMs: e.durationMs,
     errorCode: e.error ?? e.reason,
@@ -160,6 +199,15 @@ const DEFAULT_MAX_REVERT_ATTEMPTS = 2;
 export class OtaOrchestrator {
   private enabled = false;
   private currentBundle: OtaBundlePayload | null = null;
+
+  /**
+   * The bundle this process is running, once hydrated from the native slots.
+   * Read-only view for integrations (e.g. the CodePush shim's
+   * getUpdateMetadata) that need to report the running version.
+   */
+  public getCurrentBundle(): OtaBundlePayload | null {
+    return this.currentBundle;
+  }
   private isRestartRequiredState = false;
   private healthyTimer: ReturnType<typeof setTimeout> | null = null;
   private bootGuardConfig: BootGuardConfig = {};
@@ -244,6 +292,11 @@ export class OtaOrchestrator {
       // no way to know what the device was actually on.
       this.hydrateCurrentBundleFromSlots();
 
+      // Warm the device-country cache (edge Worker lookup) so checks can carry
+      // a country when the API itself sits behind no geo-stamping CDN.
+      // Fire-and-forget and failure-soft — a check without a country is valid.
+      void prefetchDeviceCountry();
+
       // Prove the bundle we installed is the bundle that loaded.
       this.verifyRunningBundleIdentity();
 
@@ -472,15 +525,24 @@ export class OtaOrchestrator {
       // never carried it — so every device resolved to `default` no matter what
       // the host app asked for. Undefined fields are omitted by JSON.stringify,
       // so an app that supplies nothing behaves exactly as before.
+      // OTA has no bundle for a non-mobile target; claiming Android there would install the wrong one.
+      const mobileOS = resolveMobileOS();
+      if (!mobileOS) throw new Error('OTA is not supported on this platform');
       const payload: OtaCheckRequest = {
         appVersion: requestParams.appVersion,
-        platform: Platform.OS === 'ios' ? 'ios' : 'android',
+        platform: mobileOS,
         installationId: requestParams.installationId,
         currentBundleId: this.currentBundle?.id,
         currentBundleHash: this.currentBundle?.sha256,
         channelName: requestParams.channelName,
-        country: requestParams.country,
-        attributes: requestParams.attributes,
+        // Host-supplied country wins; otherwise the cached edge-Worker lookup
+        // fills in (see geoCountry.ts). Undefined when neither knows — the
+        // server renders unknown as unknown rather than guessing.
+        country: requestParams.country ?? getDeviceCountry() ?? undefined,
+        // Hardware/OS context under the host's own attributes (host wins on
+        // collision) — this is what lets ATTRIBUTE rules target device classes
+        // (deviceModel / manufacturer / brand / osVersion / formFactor).
+        attributes: { ...deviceTargetingAttributes(), ...requestParams.attributes },
         segmentIds: requestParams.segmentIds,
         lifecycleStage: requestParams.lifecycleStage,
         // Runtime compatibility context. Without these the backend cannot tell
@@ -529,13 +591,29 @@ export class OtaOrchestrator {
    * Downloads, stage, and apply an update in one step.
    * Sprint 5: emits lifecycle events + starts boot-guard heartbeat.
    */
-  async sync(params: {
+  async sync(rawParams: {
     apiUrl: string;
     clientKey: string;
     appVersion: string;
-    installationId: string;
+    /** Omit to use the SDK's canonical per-install id (recommended — P8). */
+    installationId?: string;
+    // P1: these five existed on checkForUpdate and on the wire contract, but
+    // sync() — the only caller that matters — never accepted them, so they
+    // were structurally undefined on every real device: every install pinned
+    // to the `default` channel and the whole targeting engine matched nothing.
+    // The C1 comment in OtaTypes.ts claimed this was fixed; the plumbing had
+    // stopped exactly one function short of true.
+    channelName?: string;
+    country?: string;
+    attributes?: Record<string, string | number>;
+    segmentIds?: string[];
+    lifecycleStage?: string;
     autoRestart?: boolean;
   }): Promise<SyncResult> {
+    const params = {
+      ...rawParams,
+      installationId: rawParams.installationId ?? resolveInstallationId(),
+    };
     try {
       if (!this.enabled || !NativeScaleBunOta) {
         return { status: 'ERROR', error: 'OTA native module disabled or missing' };

package/src/features/ota/deviceAttributes.ts

@@ -0,0 +1,46 @@
+import { Dimensions, Platform } from 'react-native';
+
+/**
+ * Hardware/OS context auto-attached to OTA check payloads so ATTRIBUTE targeting
+ * rules can address device classes without any host-app wiring:
+ *
+ *   deviceModel  — 'SM-A155F', '23129RAA4G'… (Android; iOS does not expose it in JS)
+ *   manufacturer — 'samsung', 'xiaomi'… (lowercased: rules shouldn't fail on casing)
+ *   brand        — 'redmi' vs manufacturer 'xiaomi' — sub-brands are real segments
+ *   osVersion    — Android Release ('14') / iOS version ('17.5')
+ *   formFactor   — 'phone' | 'tablet' | 'tv' (Android tablets via the 600dp
+ *                  smallest-width convention — the same line AndroidX draws)
+ *
+ * Host-supplied attributes always win on key collision: an app that knows better
+ * (e.g. its own device tiering) must not be overridden by generic detection.
+ * Everything here is best-effort — a missing constant yields a missing key,
+ * never a guessed value.
+ */
+export function deviceTargetingAttributes(): Record<string, string> {
+    const out: Record<string, string> = {};
+    try {
+        const c = (Platform.constants ?? {}) as Record<string, unknown>;
+        if (Platform.OS === 'android') {
+            if (typeof c.Model === 'string' && c.Model) out.deviceModel = c.Model;
+            if (typeof c.Manufacturer === 'string' && c.Manufacturer) {
+                out.manufacturer = c.Manufacturer.toLowerCase();
+            }
+            if (typeof c.Brand === 'string' && c.Brand) out.brand = c.Brand.toLowerCase();
+            if (typeof c.Release === 'string' && c.Release) out.osVersion = c.Release;
+            const screen = Dimensions.get('screen');
+            const smallestDp = Math.min(screen.width, screen.height);
+            out.formFactor = Platform.isTV ? 'tv' : smallestDp >= 600 ? 'tablet' : 'phone';
+        } else {
+            const osVersion = typeof c.osVersion === 'string' ? c.osVersion : String(Platform.Version ?? '');
+            if (osVersion) out.osVersion = osVersion;
+            out.formFactor = Platform.isTV
+                ? 'tv'
+                : (c as { interfaceIdiom?: string }).interfaceIdiom === 'pad'
+                  ? 'tablet'
+                  : 'phone';
+        }
+    } catch {
+        // Targeting enrichment must never break a check. Missing keys are honest.
+    }
+    return out;
+}

package/src/features/ota/geoCountry.ts

@@ -0,0 +1,85 @@
+import { createStorageBackend } from '../../storage/StorageBackend';
+import { logger } from '../../core/logger/internalLogger';
+
+/**
+ * Device country via an edge Worker — the workaround for an API that is not
+ * behind a geo-stamping CDN.
+ *
+ * The clean architecture is the API itself resolving `cf-ipcountry` at its own
+ * edge (see backend `resolveCountry`) — the device can't forge it and every
+ * request carries it. When the API record isn't proxied, that header never
+ * exists, so this module asks a Cloudflare Worker (which DOES see the device's
+ * edge geo) and attaches the answer to the OTA check payload. Host-supplied
+ * country always wins; the server treats a client country as locale-grade, not
+ * proof of location.
+ *
+ * Failure-soft by design: a dead Worker, a timeout, or a bad payload leaves the
+ * country unset — an unknown country must render as unknown, never be guessed.
+ */
+
+/** Default lookup endpoint. Overridable via {@link setGeoEndpoint}. */
+const DEFAULT_GEO_ENDPOINT = 'https://get-location.imohamadfahmy.workers.dev/';
+
+const K_COUNTRY = 'scalebun.ota.geoCountry';
+const K_FETCHED_AT = 'scalebun.ota.geoCountryAt';
+const TTL_MS = 24 * 60 * 60 * 1000; // countries change when people travel — daily is plenty
+const TIMEOUT_MS = 2500;
+
+/** Cloudflare's non-countries: Tor exits and internal probes. Unknown, not a place. */
+const NON_COUNTRIES = new Set(['XX', 'T1', 'ZZ']);
+
+let endpoint = DEFAULT_GEO_ENDPOINT;
+let memory: string | null = null;
+let inFlight: Promise<void> | null = null;
+const storage = createStorageBackend();
+
+/** Override the lookup endpoint (e.g. a self-hosted Worker). */
+export function setGeoEndpoint(url: string): void {
+    endpoint = url;
+}
+
+/**
+ * Synchronous read of the cached country (uppercase ISO 3166-1 alpha-2), or
+ * null when no fresh lookup has ever succeeded. Never triggers network.
+ */
+export function getDeviceCountry(): string | null {
+    if (memory) return memory;
+    const stored = storage.get(K_COUNTRY);
+    const at = parseInt(storage.get(K_FETCHED_AT) ?? '0', 10) || 0;
+    if (stored && Date.now() - at < TTL_MS) {
+        memory = stored;
+        return stored;
+    }
+    return null;
+}
+
+/**
+ * Refresh the cache from the Worker if stale. Fire-and-forget: call it at
+ * orchestrator init; the first check of a cold install may go out without a
+ * country (the server stores the country per device on later checks anyway).
+ */
+export function prefetchDeviceCountry(): Promise<void> {
+    if (getDeviceCountry()) return Promise.resolve(); // fresh — nothing to do
+    if (inFlight) return inFlight;
+    inFlight = (async () => {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+        try {
+            const res = await fetch(endpoint, { signal: controller.signal });
+            if (!res.ok) return;
+            const body = (await res.json()) as { country?: unknown };
+            const raw = typeof body?.country === 'string' ? body.country.trim().toUpperCase() : '';
+            if (!/^[A-Z]{2}$/.test(raw) || NON_COUNTRIES.has(raw)) return;
+            memory = raw;
+            storage.set(K_COUNTRY, raw);
+            storage.set(K_FETCHED_AT, String(Date.now()));
+            logger.debug(`[OTA] Device country resolved: ${raw}`);
+        } catch (err: any) {
+            logger.debug(`[OTA] Geo lookup skipped: ${err?.message ?? err}`);
+        } finally {
+            clearTimeout(timer);
+            inFlight = null;
+        }
+    })();
+    return inFlight;
+}

package/src/features/ota/useOtaUpdate.ts

@@ -7,7 +7,22 @@ export interface UseOtaUpdateOptions {
   apiUrl: string;
   clientKey: string;
   appVersion: string;
-  installationId: string;
+  /**
+   * Omit to use the SDK's canonical per-install id (recommended). Supplying a
+   * different id here — the old docs suggested `deviceId` — put OTA telemetry
+   * in its own identity namespace, disconnected from every other SDK lane.
+   */
+  installationId?: string;
+  /** OTA channel to pull from. Omitted means `default`. */
+  channelName?: string;
+  /** ISO 3166-1 alpha-2. The server resolves this from the edge when absent. */
+  country?: string;
+  /** Free-form device attributes evaluated by ATTRIBUTE targeting rules. */
+  attributes?: Record<string, string | number>;
+  /** CDP segment ids this installation belongs to. */
+  segmentIds?: string[];
+  /** Lifecycle stage evaluated by LIFECYCLE_STAGE targeting rules. */
+  lifecycleStage?: string;
   autoRestart?: boolean;
   /**
    * When true and the server says `isMandatory`, the hook sets
@@ -49,7 +64,10 @@ export interface UseOtaUpdateReturn {
  *   apiUrl: 'https://api.scalebun.com/api/v1',
  *   clientKey: 'scalebun_ck_…',
  *   appVersion: '1.0.0',
- *   installationId: deviceId,
+ *   // installationId is resolved from the SDK's own persisted install id —
+ *   // do NOT pass deviceId here (the old example did; it split OTA telemetry
+ *   // into a separate identity namespace from every other lane).
+ *   channelName: 'production',
  *   mandatoryBlocksUi: true,
  * });
  * ```

package/src/features/performance/PerformanceFeature.ts

@@ -71,7 +71,6 @@ export class PerformanceFeature implements IFeature {
     private static readonly CAPTURE_DELAYS = [300, 600, 1200];
 
     // Track event function from SDK pipeline
-    private trackFn: ((name: string, payload?: Record<string, unknown>) => void) | null = null;
 
     constructor(config?: Partial<PerformanceConfig>) {
         this.config = mergePerformanceConfig(config);
@@ -208,7 +207,6 @@ export class PerformanceFeature implements IFeature {
     async initialize(context: FeatureContext): Promise<void> {
         if (this.active || !this.config.enabled) return;
 
-        this.trackFn = context.trackEvent;
         this.active = true;
 
         // Activate native performance collectors (Android AppStart/Frame/ANR,
@@ -549,13 +547,28 @@ export class PerformanceFeature implements IFeature {
         // Send to debug transport
         this.transport.sendEvent(event);
 
-        // Also track through SDK pipeline (for backend ingestion)
-        if (this.trackFn) {
-            this.trackFn('$perf_event', {
-                perfType: event.type,
-                ...event,
-            });
-        }
+        /**
+         * REMOVED: a duplicate `$perf_event` through the analytics/event pipeline.
+         *
+         * This claimed to be "for backend ingestion", but the `queuePerformanceMetric` call below is
+         * the backend ingestion path — it writes the dedicated `performance_metrics` table, and that
+         * is what EVERY consumer reads: `perf-aggregate.ch.ts` (FPS, frameMetricsSessions), the
+         * Monitor low-FPS KPI, the page-load RenderingPanel and the Replay Inspector's FPS readout.
+         * Nothing in the backend or the dashboard reads `$perf_event` — verified by search.
+         *
+         * So this line wrote every perf sample a SECOND time, into the event lane, where it landed as
+         * `USER_ACTION` and was counted as a user interaction. Measured in production:
+         *
+         *     performance_metrics.frame_metrics   75,278   ← read by everything
+         *     replay_events (as USER_ACTION)      47,019   ← read by nothing
+         *
+         * `USER_ACTION` was 99% of all mobile events (62,026 of ~62,600), and only 980 of those
+         * carried real gesture data. One session showed 4,735 events against SIX real gestures. That
+         * made session event counts meaningless and polluted anything counting user interactions.
+         *
+         * Dropping it loses no data and no feature — the perf lane's copy is the more complete one —
+         * and it costs a duplicate serialize + upload per sample on every session.
+         */
 
         // Queue to SaaS backend dedicated performance endpoint
         const backendTransport = SessionManager.getExistingInstance()?.getBackendTransport();

package/src/features/performance/collectors/FrameMetricsCollector.ts

@@ -11,7 +11,7 @@
  * - Emits FrameMetricsEvent for transport
  */
 
-import { NativeEventEmitter } from 'react-native';
+import { AppState, NativeEventEmitter, type NativeEventSubscription } from 'react-native';
 import { getNativePerformanceModule } from '../getNativePerformanceModule';
 import type { FrameMetricsEvent, PerfContext } from '../models';
 import { PERF_SCHEMA_VERSION } from '../models';
@@ -25,6 +25,10 @@ export class FrameMetricsCollector {
     private contextProvider: () => PerfContext;
     private eventSubscription: any = null;
     private running = false;
+    /** AppState subscription — see `_installAppStateGate`. */
+    private appStateSubscription: NativeEventSubscription | null = null;
+    /** True while the native sampler is actually running (i.e. armed AND foregrounded). */
+    private sampling = false;
 
     constructor(
         config: PerformanceConfig,
@@ -56,22 +60,64 @@ export class FrameMetricsCollector {
                 },
             );
 
-            // Tell native module to start collecting frame metrics
-            if (typeof perfModule.startFrameMetrics === 'function') {
-                perfModule.startFrameMetrics(this.config.reportIntervalMs);
-            }
+            this._startNativeSampler();
+            this._installAppStateGate();
         } catch {
             // Native module not available — graceful degradation
         }
     }
 
-    stop(): void {
-        this.running = false;
-        if (this.eventSubscription) {
-            this.eventSubscription.remove();
-            this.eventSubscription = null;
+    /**
+     * Pause sampling while the app is backgrounded.
+     *
+     * THE BUG THIS FIXES. `startFrameMetrics` hands off to a native loop that runs until something
+     * calls `stopFrameMetrics`. Nothing did. The collector had no AppState awareness at all — unlike
+     * `AutoScreenLoadCollector`, which has subscribed to it since it was written — so once a session
+     * was sampled in, it kept sampling for as long as the PROCESS lived, not as long as the app was
+     * being used.
+     *
+     * Measured in production: sessions with `durationMs` of 86,400,000 (exactly 24h) and 70,797,000
+     * (~19.7h) carrying 39,766 and 3,709 frame samples against 0 and 6 real gestures respectively.
+     * `frame_metrics` was 75% of ALL mobile events for this reason.
+     *
+     * The `tier2SampleRate` knob does not help here: it gates WHICH sessions collect, not how long
+     * they collect for. A sampled-in session that gets backgrounded still samples for hours, which is
+     * why lowering it would have hidden the symptom while leaving the cause.
+     *
+     * It is also a DATA-QUALITY fix, not only a volume one. Frame timings from a backgrounded app
+     * describe a screen nobody is looking at, and they were feeding the low-FPS KPI and jank
+     * detection — so the noise was not merely stored, it was being reported as UI performance.
+     *
+     * NOTE: on iOS the OS already stops delivering CADisplayLink callbacks on background, so the
+     * practical effect is largest on Android. Gating in JS keeps the two platforms behaving the same
+     * either way, rather than relying on an OS side effect that is not part of any contract.
+     */
+    private _installAppStateGate(): void {
+        if (this.appStateSubscription) return;
+        this.appStateSubscription = AppState.addEventListener('change', (next) => {
+            if (!this.running) return; // stop() already tore us down
+            if (next === 'active') this._startNativeSampler();
+            else this._stopNativeSampler(); // 'background' and 'inactive' (iOS call/app-switcher)
+        });
+    }
+
+    /** Idempotent — AppState can fire 'active' more than once without an intervening background. */
+    private _startNativeSampler(): void {
+        if (this.sampling) return;
+        try {
+            const perfModule = getNativePerformanceModule();
+            if (typeof perfModule?.startFrameMetrics === 'function') {
+                perfModule.startFrameMetrics(this.config.reportIntervalMs);
+                this.sampling = true;
+            }
+        } catch {
+            // No-throw: a perf collector must never break the host app.
         }
+    }
 
+    private _stopNativeSampler(): void {
+        if (!this.sampling) return;
+        this.sampling = false;
         try {
             const perfModule = getNativePerformanceModule();
             if (typeof perfModule?.stopFrameMetrics === 'function') {
@@ -82,6 +128,22 @@ export class FrameMetricsCollector {
         }
     }
 
+    stop(): void {
+        this.running = false;
+        if (this.eventSubscription) {
+            this.eventSubscription.remove();
+            this.eventSubscription = null;
+        }
+        // Remove the AppState listener BEFORE stopping the sampler: a 'change' arriving mid-teardown
+        // would otherwise restart the native loop on a collector that is being shut down, which is the
+        // same leak this gate exists to close.
+        if (this.appStateSubscription) {
+            this.appStateSubscription.remove();
+            this.appStateSubscription = null;
+        }
+        this._stopNativeSampler();
+    }
+
     private _handleNativeFrameMetrics(data: any): void {
         if (!data || typeof data.totalFrames !== 'number') return;
 

package/src/features/performance/transport/PerformanceTransport.ts

@@ -68,6 +68,24 @@ export class PerformanceTransport {
 
     /** Send a metric value (for backward compat with existing metric handler) */
     sendMetric(name: string, value: number, unit?: string, tags?: Record<string, string>): void {
+        // D4: the desktop sink is only wired under enableDebug(), so in a
+        // production build everything through here — JS stall stats, launch
+        // timings, and the PUBLIC ScaleBun.sendMetric() API — was buffered into
+        // a bounded array and discarded. Mirror every metric onto the backend
+        // ingestion lane (the one that provably lands rows); the desktop sink
+        // remains the dev-tooling fan-out below.
+        try {
+            // Lazy import avoids a static cycle: session → performance → session.
+            const { SessionManager } = require('../../session/SessionManager');
+            const backend = SessionManager.getExistingInstance()?.getBackendTransport();
+            backend?.queuePerformanceMetric({
+                type: name,
+                value,
+                metadata: { ...(unit ? { unit } : {}), ...(tags ?? {}) },
+            });
+        } catch {
+            // Backend lane unavailable (no session yet) — dev sink may still get it.
+        }
         const msg = {
             type: 'metric' as const,
             protocolVersion: PROTOCOL_VERSION,