@scalebun/react-native 1.0.3 → 1.1.0

package/src/analytics/EventTracker.ts

@@ -21,6 +21,7 @@
 import { createStorageBackend, StorageBackend } from '../storage/StorageBackend';
 import { getDeviceId } from '../core/id/deviceId';
 import { logger } from '../core/logger/internalLogger';
+import { setNativeActiveSession } from '../features/crash/nativeCrashBridge';
 import { hmacSha256Hex } from '../crypto/hmacSha256';
 import { MAX_BATCH_EVENTS, clampBatchSize, batchIdempotencyKey } from './batching';
 import { subscribeAutomaticEvents } from './automaticEvents';
@@ -29,7 +30,14 @@ import { subscribeAutomaticEvents } from './automaticEvents';
 // treats an unsigned/invalid batch from a signing-capable SDK as a fraud signal.
 const SDK_SIGNING_VERSION = '1';
 
-const K_INSTALLATION_ID = 'scalebun_installation_id';
+/**
+ * Exported because this is THE canonical per-install identity key for the whole
+ * SDK. The OTA lane used to demand a caller-supplied installationId instead of
+ * reading this one, which put OTA telemetry in its own id namespace — every
+ * join from OTA to CDP (blast radius, MRR-at-risk, churn) matched by luck.
+ * One install, one id, every lane.
+ */
+export const K_INSTALLATION_ID = 'scalebun_installation_id';
 const K_ANONYMOUS_ID = 'scalebun_anonymous_id';
 const K_FIRST_OPEN = 'scalebun_first_open_done';
 /** Last app version seen on this device — the baseline app_update compares against. */
@@ -143,6 +151,9 @@ export class EventTracker {
         this.installationId = this.loadOrCreate(K_INSTALLATION_ID);
         this.anonymousId = this.loadOrCreate(K_ANONYMOUS_ID);
         this.sessionId = `sess-${uuid()}`;
+        // Published immediately, before anything else runs — a crash can happen on the very next
+        // line, and native must already know which session owns it.
+        this.publishSessionToNative();
         this.loadQueue();
         this.loadClickId();
     }
@@ -210,9 +221,25 @@ export class EventTracker {
     /** Start a fresh session (e.g. after the app returns from a long background). */
     newSession(): void {
         this.sessionId = `sess-${uuid()}`;
+        this.publishSessionToNative();
         this.track('session_start');
     }
 
+    /**
+     * Hand the live session id to the native crash layer.
+     *
+     * Called at EVERY point the id changes — construction and rollover — because a crash-safe copy
+     * that is one session stale is worse than none: it would confidently attribute a crash to a
+     * session that had already ended.
+     *
+     * Fire-and-forget. Native persists it synchronously on its own side; a failure here degrades a
+     * recovered crash to unattributed, which is exactly the behaviour before this existed, and must
+     * never be able to fail a session start.
+     */
+    private publishSessionToNative(): void {
+        void setNativeActiveSession(this.sessionId);
+    }
+
     // ─── identity ────────────────────────────────────────────────────────────
 
     identify(userId: string, traits?: Record<string, any>): void {

package/src/bootstrap/SDKBootstrapper.ts

@@ -17,6 +17,7 @@
 
 import { Linking, Platform } from 'react-native';
 import { ConfigSchema, type ScaleBunConfig } from '../core/config/schema';
+import { DEFAULT_API_BASE_URL } from '../core/constants/endpoints';
 import { logger, LogLevel } from '../core/logger/internalLogger';
 import { coreContainer } from '../core/di/container';
 import { HttpClient } from '../transport/http/httpClient';
@@ -85,6 +86,10 @@ export class SDKBootstrapper {
         }
 
         this.config = result.data;
+        // apiBaseUrl is LOCKED: whatever an integrator passed (or the schema default) is
+        // discarded here so the SDK can never be repointed away from the ScaleBun cloud.
+        // Change DEFAULT_API_BASE_URL at build time to target a different backend.
+        this.config.apiBaseUrl = DEFAULT_API_BASE_URL;
         // Explicit logLevel wins; otherwise debug:true implies verbose 'debug'.
         if (this.config.logLevel) {
             logger.setLevelByName(this.config.logLevel);
@@ -121,20 +126,16 @@ export class SDKBootstrapper {
             new HttpClient(this.config.apiBaseUrl),
         );
 
-        const clientKey = this.config.clientKey;
-        coreContainer.register(
-            'Dispatcher',
-            new Dispatcher(async (batch) => {
-                const headers: Record<string, string> = {};
-                if (clientKey) {
-                    headers['x-scalebun-client-key'] = clientKey;
-                }
-                await httpClient.post(ENDPOINTS.EVENTS, {
-                    deviceId: getDeviceId(),
-                    events: batch,
-                }, headers);
-            }),
-        );
+        // D1: a `Dispatcher` used to be registered here, draining `memoryQueue`
+        // to ENDPOINTS.EVENTS ('/sdk/events'). Removed on two grounds, both
+        // verified: nothing anywhere resolved 'Dispatcher' from the container
+        // (so its flush never ran and the queue was a black hole), and no
+        // backend controller has ever served '/sdk/events' — even a wired
+        // dispatcher would have 404'd forever. Every producer that wrote into
+        // that pipeline now rides a live lane instead (captureException →
+        // CrashReporter, native-crash detail → report metadata, metrics →
+        // queuePerformanceMetric). A decoy pipeline is worse than none: it
+        // makes the real path look redundant.
 
         const scheduler = coreContainer.register(
             'FlushScheduler',
@@ -394,15 +395,18 @@ export class SDKBootstrapper {
                         const analyticsStarted = backendAdapter
                             .startAnalyticsSession(this._buildAnalyticsSession());
 
-                        // Cold-launch frame recording. The AppState listener only
-                        // starts a recording session on a foreground TRANSITION, which
-                        // never fires on the initial launch — so without this the first
-                        // session uploads events but zero frames ("No screen recordings").
-                        // Start it once the analytics session id exists so startSession
-                        // adopts it (one-row merge) instead of minting an orphan row.
-                        // Gated by the same finalizeOnBackground flag as the per-foreground
-                        // recording path above.
-                        if (this.config.finalizeOnBackground) {
+                        // Cold-launch frame recording. The AppState listener only starts a
+                        // recording session on a foreground TRANSITION, which never fires on the
+                        // initial launch — so without this the first session uploads events but zero
+                        // frames ("No screen recordings"). Auto-start recording by DEFAULT in SaaS mode
+                        // so replays appear out of the box; hosts opt out with `replay: { record: false }`
+                        // for events-only sessions (they can still record on demand via startSession()).
+                        // Deliberately NOT gated by finalizeOnBackground (that flag only governs
+                        // per-foreground session boundaries, not whether replay records at all).
+                        // Started once the analytics session id exists so startSession adopts it
+                        // (one-row merge) instead of minting an orphan row.
+                        const shouldAutoRecord = this.config.replay?.record !== false;
+                        if (shouldAutoRecord) {
                             analyticsStarted
                                 .then(() => {
                                     if (!sessionManager.isActive) {

package/src/compat/codepush.ts

@@ -1,4 +1,5 @@
 import { otaOrchestrator } from '../features/ota/OtaOrchestrator';
+import { logger } from '../core/logger/internalLogger';
 
 export enum CodePushInstallMode {
   IMMEDIATE = 0,
@@ -38,12 +39,57 @@ export interface CodePushPackage {
 }
 
 /**
- * Microsoft CodePush Drop-in Compatibility Shim — Sprint 10 (S10-CLI-1).
+ * Microsoft CodePush compatibility shim.
  *
- * Allows developers to migrate from CodePush to Scalebun OTA by simply changing:
- *   - import codePush from 'react-native-code-push'
- *   + import codePush from '@scalebun/react-native/compat/codepush'
+ * Maps the CodePush surface (`sync`, `checkForUpdate`, the HOC) onto the
+ * ScaleBun orchestrator so a migrating app keeps compiling while its call sites
+ * are ported.
+ *
+ * CONFIGURE IT FIRST. This shim used to carry hardcoded defaults —
+ * `http://localhost:3001/api/v1` with a dev client key — so a migrated
+ * production app silently checked localhost forever and reported UP_TO_DATE on
+ * every sync. There is no correct default for someone else's backend, so there
+ * is now none: call `configureCodePushShim()` (or `ScaleBun.init({ ota })`,
+ * which the facade wires for you) before the first sync, and an unconfigured
+ * shim says so loudly instead of pretending to be up to date.
+ *
+ *   import codePush, { configureCodePushShim } from '@scalebun/react-native/compat/codepush';
+ *   configureCodePushShim({ apiUrl, clientKey, appVersion, installationId });
+ */
+
+export interface CodePushShimConfig {
+    /** Backend base URL, e.g. https://api.yourbackend.com/api/v1 */
+    apiUrl: string;
+    /** SDK client key for this app/environment. */
+    clientKey: string;
+    /** Native app version this binary reports (e.g. '1.4.0'). */
+    appVersion: string;
+    /** Stable per-install id. Defaults to the SDK's canonical installation id. */
+    installationId?: string;
+}
+
+let shimConfig: CodePushShimConfig | null = null;
+
+/** Point the shim at a real backend. Required before sync/checkForUpdate. */
+export function configureCodePushShim(config: CodePushShimConfig): void {
+    shimConfig = config;
+}
+
+/**
+ * Resolve the sync params, or null when unconfigured. Returning null (rather
+ * than substituting a localhost default) is what turns a silent no-update into
+ * a visible, fixable error.
  */
+function shimParams(): CodePushShimConfig | null {
+    if (!shimConfig) {
+        logger.warn(
+            '[ScaleBun] CodePush shim is not configured — no update check was performed. ' +
+                'Call configureCodePushShim({ apiUrl, clientKey, appVersion }) during startup.',
+        );
+        return null;
+    }
+    return shimConfig;
+}
 const codePushShim = function <P>(rootComponent: React.ComponentType<P>) {
   return rootComponent;
 };
@@ -53,14 +99,21 @@ codePushShim.sync = async (
   syncStatusCallback?: (status: CodePushSyncStatus) => void,
   downloadProgressCallback?: (progress: { receivedBytes: number; totalBytes: number }) => void,
 ): Promise<CodePushSyncStatus> => {
+  const params = shimParams();
+  if (!params) {
+    // Unconfigured is an ERROR, not "up to date": reporting UP_TO_DATE here is
+    // exactly how a broken migration stays invisible for months.
+    syncStatusCallback?.(CodePushSyncStatus.UNKNOWN_ERROR);
+    return CodePushSyncStatus.UNKNOWN_ERROR;
+  }
   try {
     syncStatusCallback?.(CodePushSyncStatus.CHECKING_FOR_UPDATE);
     const result = await otaOrchestrator.sync({
-      apiUrl: 'http://localhost:3001/api/v1',
-      clientKey: 'scalebun_ck_dev_default_0000000000000000000000',
-      appVersion: '1.0.0',
-      installationId: 'codepush_shim',
-    });
+      ...params,
+      // Omitted → the orchestrator falls back to the SDK's canonical
+      // installation id, which is the right identity anyway.
+      ...(params.installationId ? { installationId: params.installationId } : {}),
+    } as any);
 
     if (result.status === 'UP_TO_DATE') {
       syncStatusCallback?.(CodePushSyncStatus.UP_TO_DATE);
@@ -81,16 +134,16 @@ codePushShim.sync = async (
 };
 
 codePushShim.checkForUpdate = async (): Promise<CodePushPackage | null> => {
+  const params = shimParams();
+  if (!params) return null;
   const check = await otaOrchestrator.checkForUpdate({
-    apiUrl: 'http://localhost:3001/api/v1',
-    clientKey: 'scalebun_ck_dev_default_0000000000000000000000',
-    appVersion: '1.0.0',
-    installationId: 'codepush_shim',
-  });
+    ...params,
+    ...(params.installationId ? { installationId: params.installationId } : {}),
+  } as any);
   if (check.action === 'NONE' || !check.bundle) return null;
 
   return {
-    appVersion: '1.0.0',
+    appVersion: params.appVersion,
     deploymentKey: 'scalebun_ota',
     description: check.bundle.releaseNote ?? '',
     failedInstall: false,
@@ -111,8 +164,26 @@ codePushShim.allowRestart = () => {
   // Scalebun handles restart safety automatically via boot guard
 };
 
+/**
+ * Metadata for the bundle currently RUNNING. CodePush apps use this to show a
+ * version or decide whether a pending update landed; returning a flat null
+ * (as this did) makes every such check read as "no OTA bundle installed".
+ */
 codePushShim.getUpdateMetadata = async (): Promise<CodePushPackage | null> => {
-  return null;
+  const current = otaOrchestrator.getCurrentBundle();
+  if (!current) return null;
+  return {
+    appVersion: shimConfig?.appVersion ?? '',
+    deploymentKey: 'scalebun_ota',
+    description: current.releaseNote ?? '',
+    failedInstall: false,
+    isFirstRun: false,
+    isMandatory: current.isMandatory ?? false,
+    isPending: false,
+    label: `v${current.version}`,
+    packageHash: current.sha256,
+    packageSize: current.size,
+  };
 };
 
 export default codePushShim;

package/src/core/config/schema.ts

@@ -6,11 +6,18 @@ export const ConfigSchema = z.object({
     projectId: z.string().min(1).optional(),
     publishableKey: z.string().min(1).optional(),
     /**
-     * Backend API base URL. Optional — defaults to the ScaleBun cloud
-     * ({@link DEFAULT_API_BASE_URL}). Override only for staging or a
-     * self-hosted backend. Still validated as a URL when supplied.
-     */
-    apiBaseUrl: z.string().url('apiBaseUrl must be a valid URL').default(DEFAULT_API_BASE_URL),
+     * Backend API base URL. LOCKED to {@link DEFAULT_API_BASE_URL} — the ScaleBun
+     * cloud endpoint is fixed and cannot be overridden by integrators. Any value
+     * supplied here is accepted (no validation error, for backward compatibility)
+     * but ignored: the bootstrapper force-overwrites it with DEFAULT_API_BASE_URL
+     * immediately after parse. To point the SDK at a different backend, change the
+     * constant at build time.
+     */
+    // NB: `.default()` on the vendored `z` types its arg as `Partial<T> | (() => T)`, so a bare
+    // string arg fails `tsc` (.d.ts generation via bob) with TS2345. The factory form satisfies the
+    // `(() => any)` overload. Behaviour is identical — omitted apiBaseUrl resolves to the default,
+    // which the bootstrapper overwrites anyway (the endpoint is locked).
+    apiBaseUrl: z.any().default(() => DEFAULT_API_BASE_URL),
     debug: z.boolean().default(false),
     /**
      * SDK internal log verbosity. Recoverable transport failures are logged at
@@ -161,6 +168,11 @@ export const ConfigSchema = z.object({
      * Plumbed into SessionManager via SDKBootstrapper.
      */
     replay: z.object({
+        // Auto-start frame recording in SaaS mode (clientKey set) at cold launch, so replay
+        // sessions carry frames out of the box. Default: true (undefined ⇒ record). Set false for
+        // events-only sessions — the host can still record on demand via ScaleBun.startSession().
+        // Decoupled from finalizeOnBackground (which only governs per-foreground session boundaries).
+        record: z.boolean().optional(),
         captureMode: z.enum(['navigation', 'interactions', 'frequency']).optional(),
         intervalMs: z.number().min(500).optional(),
         quality: z.enum(['high', 'normal', 'low', 'grayscale']).optional(),
@@ -206,6 +218,15 @@ export const ConfigSchema = z.object({
         channelOverride: z.string().optional(),
         /** Ed25519 public key for bundle signature verification (base64). */
         publicSigningKey: z.string().optional(),
+        /**
+         * Ed25519 verifier supplied by the host — the SDK ships no crypto
+         * implementation. Required whenever `publicSigningKey` is set: pinning a
+         * key without a verifier is fail-closed, so updates stop installing.
+         * `(message, signature, publicKey) => boolean | Promise<boolean>`.
+         */
+        verifySignature: z.any().optional(),
+        /** Override how long a new bundle has to prove healthy (ms). */
+        healthyTimeoutMs: z.number().optional(),
         /** Block UI interaction while a mandatory update is pending. Default: false. */
         mandatoryBlocksUi: z.boolean().default(false),
     }).optional(),

package/src/core/constants/endpoints.ts

@@ -1,9 +1,12 @@
 /**
- * ScaleBun cloud API base URL.
+ * ScaleBun cloud API base URL — the single, LOCKED endpoint for the SDK.
  *
- * Used as the default for `apiBaseUrl` when an integrator does not supply one,
- * so the common "just give me a project key" integration works without knowing
- * the server address. Override `apiBaseUrl` in init config to point at a
- * staging environment or a self-hosted backend.
+ * `SDKBootstrapper` ignores any `apiBaseUrl` passed in init config and always
+ * uses this value, so an integrator cannot repoint the SDK at another backend.
+ * Includes the `/api/v1` path segment because every SDK route is built relative
+ * to this base (e.g. `${apiBaseUrl}/batch`, `${apiBaseUrl}/ingestion/sessions`,
+ * `${apiBaseUrl}/config`). Without `/api/v1` the ingestion routes return 404 and
+ * events are silently lost. To target a staging or self-hosted backend, change
+ * this value at build time.
  */
-export const DEFAULT_API_BASE_URL = 'https://api.scalebun.com';
+export const DEFAULT_API_BASE_URL = 'https://api.scalebun.com/api/v1';

package/src/core/context/device.ts

@@ -0,0 +1,146 @@
+/**
+ * The ONE place that answers "what device is this?".
+ *
+ * It was previously answered three incompatible ways at once:
+ *
+ *   1. The replay lane asked the native bridge and got the truth.
+ *   2. The analytics lane took `ScaleBun.init({ context })` verbatim and shipped whatever the
+ *      integrator typed. Production carries `device_model: "android"`, `manufacturer: "android"`
+ *      and `sdk_version: "qa-app-1.0"` because an app hand-wrote them — none of those are a model,
+ *      a manufacturer, or an SDK version.
+ *   3. Seven call sites wrote `Platform.OS === 'ios' ? 'ios' : 'android'`, which reports every
+ *      non-iOS platform — windows, macos, web — as Android.
+ *
+ * Detection belongs to the SDK. An integrator cannot be expected to know the device better than the
+ * process running on it, and asking them to means the field is wrong whenever they guess.
+ *
+ * Every value here is measured or absent. Nothing is defaulted to a plausible-looking constant: a
+ * fabricated device model is indistinguishable from a real one to whoever reads the dashboard, which
+ * is strictly worse than an empty field.
+ */
+import { SDK_VERSION } from '../constants/version';
+
+/**
+ * The real `Platform.OS`, never narrowed.
+ *
+ * React Native's own union is `'ios' | 'android' | 'windows' | 'macos' | 'web'`, and the protocol's
+ * platform field is an open enum precisely so new ones travel without a release. Collapsing that to
+ * a two-way ternary is what made every macOS and Windows session read as Android.
+ */
+export type PlatformOS = 'ios' | 'android' | 'windows' | 'macos' | 'web' | 'unknown';
+
+interface RNPlatform {
+    OS?: string;
+    Version?: string | number;
+    constants?: {
+        Manufacturer?: string;
+        Model?: string;
+        Brand?: string;
+        Release?: string;
+        osVersion?: string;
+        systemName?: string;
+    };
+}
+
+function rnPlatform(): RNPlatform | null {
+    try {
+        return (require('react-native') as { Platform?: RNPlatform }).Platform ?? null;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * `Platform.OS`, verbatim.
+ *
+ * `'unknown'` when React Native itself cannot be loaded — the previous `catch { return 'android' }`
+ * turned "we could not tell" into a confident, wrong answer.
+ */
+export function resolvePlatformOS(): PlatformOS {
+    const os = rnPlatform()?.OS;
+    switch (os) {
+        case 'ios':
+        case 'android':
+        case 'windows':
+        case 'macos':
+        case 'web':
+            return os;
+        default:
+            // A platform React Native gained after this build. Pass it through rather than guess —
+            // the wire's platform field is an open enum for exactly this case.
+            return (os as PlatformOS) ?? 'unknown';
+    }
+}
+
+/**
+ * `'ios' | 'android'` for the few call sites whose payload genuinely only has those two, keeping the
+ * narrowing HONEST: `null` where it used to silently say Android.
+ */
+export function resolveMobileOS(): 'ios' | 'android' | null {
+    const os = resolvePlatformOS();
+    return os === 'ios' || os === 'android' ? os : null;
+}
+
+/** The keys this module owns. An integrator-supplied value for any of them is overridden. */
+export const DETECTED_CONTEXT_KEYS = [
+    'sdk_version',
+    'platform_os',
+    'os_version',
+    'device_model',
+    'manufacturer',
+] as const;
+
+/**
+ * Everything derivable WITHOUT the native bridge, so the very first event already carries it.
+ *
+ * The bridge is async and may not be installed at all (Expo Go, an older native binary); waiting on
+ * it would leave the opening events of every session unattributed. `Platform.constants` is populated
+ * synchronously at startup and covers Android fully — iOS exposes no model there, which is why
+ * `device_model` stays absent on iOS until {@link nativeDeviceContext} fills it in.
+ */
+export function staticDeviceContext(): Record<string, string> {
+    const platform = rnPlatform();
+    const out: Record<string, string> = {
+        sdk_version: SDK_VERSION,
+        platform_os: resolvePlatformOS(),
+    };
+    if (!platform) return out;
+
+    const c = platform.constants ?? {};
+    // Android: Release is the marketing version ("14"); Version is the API level (34).
+    // iOS: osVersion is the real thing; Platform.Version mirrors it.
+    const osVersion = c.Release ?? c.osVersion ?? (platform.Version != null ? String(platform.Version) : undefined);
+    if (osVersion) out.os_version = String(osVersion);
+    if (c.Model) out.device_model = String(c.Model);
+    if (c.Manufacturer) out.manufacturer = String(c.Manufacturer);
+    else if (c.Brand) out.manufacturer = String(c.Brand);
+    return out;
+}
+
+/** Bridge values, once the native module answers. Absent keys stay absent. */
+export function nativeDeviceContext(info: {
+    platform?: string;
+    osVersion?: string;
+    deviceModel?: string;
+} | null): Record<string, string> {
+    const out: Record<string, string> = {};
+    if (!info) return out;
+    if (info.osVersion) out.os_version = info.osVersion;
+    if (info.deviceModel) out.device_model = info.deviceModel;
+    return out;
+}
+
+/**
+ * Merge the integrator's context with what we detected — DETECTED WINS on the keys above.
+ *
+ * The inversion is deliberate. Config normally wins over defaults, but these are not defaults: they
+ * are measurements, and a measurement must not be overridable by a guess. Everything outside
+ * {@link DETECTED_CONTEXT_KEYS} — `language`, `timezone`, `network_type`, anything app-specific —
+ * is still the integrator's to set, untouched.
+ */
+export function mergeDeviceContext(
+    configured: Record<string, unknown> | undefined,
+    detected: Record<string, string> = staticDeviceContext(),
+): Record<string, unknown> {
+    return { ...(configured ?? {}), ...detected };
+}

package/src/debug/replayWiring.ts

@@ -10,6 +10,7 @@ import type { ReplayConfig } from '../features/replay/public/types';
 import type { DebugTransport } from './transport';
 import type { SessionManager as SessionManagerType } from '../features/session/SessionManager';
 import { logger } from '../core/logger/internalLogger';
+import { resolvePlatformOS } from '../core/context/device';
 
 // ─── State ──────────────────────────────────────────────────────────────────
 
@@ -90,7 +91,7 @@ export function wireNativeCaptureDeferred(
                                 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/bugreport/BugReportFeature.ts

@@ -0,0 +1,128 @@
+/**
+ * F-BUG (React Native) — bug-report feature.
+ *
+ * Ported from the web SDK's `features/bugreport/BugReportFeature.ts`, deliberately keeping its
+ * split: this class is THIN. It raises the capture signal and holds a `submitFn` injected by the
+ * facade, which owns session + transport and therefore owns the HTTP. Duplicating the submit here
+ * would give the two SDKs two contracts to drift apart.
+ *
+ * WHAT DOES NOT PORT
+ * The web feature lazy-imports a DOM launcher widget (`widget.ts`, 185 lines of document/CSS). RN
+ * has no DOM: the form is rendered by `EngagePromptView`, which already exists, already handles the
+ * native modal/keyboard behaviour, and is already what `shake_device` puts on screen. Building a
+ * second prompt system for this would be the same mistake in a different repo.
+ *
+ * TRIGGERING
+ * `shake_device` is already wired end to end — native CoreMotion/SensorManager →
+ * `engageShakeBridge` → `gestureTriggerDetector.reportShake()` → the `$gesture` signal lane → the
+ * engage trigger engine. This feature is a submit target for that flow, not a second detector.
+ */
+import { logger } from '../../core/logger/internalLogger';
+import type { EngageAttachmentDraft } from '../engage/engageTypes';
+
+/** Why a submit did not produce a report id. Mirrors the web SDK's discriminated failure union. */
+export type BugFailure = 'init' | 'consent' | 'send' | 'empty';
+
+/** Resolves to the report id, or to `{ e }` naming WHICH branch failed. */
+export type BugSubmitResult = string | { e: BugFailure };
+
+export interface BugReportInput {
+  /** The issue text. Required — a report with no description is not a report. */
+  message: string;
+  title?: string;
+  /**
+   * Reporter's email. Optional on purpose: the session usually already resolves to an end user, so
+   * the form should PREFILL this rather than demand it from someone who just shook their phone in
+   * frustration. `BugReport.reporterEmail` is nullable server-side.
+   */
+  email?: string;
+  /**
+   * An approved voice note, produced by `features/engage/captureVoiceAttachment`.
+   *
+   * That module returns a transcript as a PREFILL and only marks `transcriptApproved` once the user
+   * has explicitly accepted the wording. This feature must never submit an unapproved draft — a
+   * machine transcription of someone's voice, sent without them confirming it, is a different
+   * product decision than the one that pipeline was built for.
+   */
+  voice?: EngageAttachmentDraft;
+}
+
+type SubmitFn = (input: BugReportInput) => Promise<BugSubmitResult>;
+
+export class BugReportFeature {
+  readonly name = 'bugReport';
+
+  private active = false;
+  private submitFn: SubmitFn | null = null;
+  /** Raises the 'report' capture signal so replay flushes its buffer into the current session. */
+  private signalFn: (() => void) | null = null;
+
+  get isActive(): boolean {
+    return this.active;
+  }
+
+  setup(hooks: { signal?: () => void } = {}): void {
+    this.signalFn = hooks.signal ?? null;
+    this.active = true;
+  }
+
+  /**
+   * Flush replay into the session so the report has its visual context.
+   *
+   * Fail-soft: replay may be disabled, paused, or unsupported on this build. A report without a
+   * replay anchor is still a useful report, so this must never block a submit.
+   */
+  signalReport(): void {
+    try {
+      this.signalFn?.();
+    } catch {
+      /* never let a capture-signal failure break a bug report */
+    }
+  }
+
+  /** Wired by the facade after init — the full submit path (transport + session + context). */
+  setSubmit(fn: SubmitFn): void {
+    this.submitFn = fn;
+  }
+
+  /**
+   * Submit a report.
+   *
+   * Returns rather than throws, always. This is called from a UI the host app renders, often from a
+   * user gesture; an exception escaping into a React Native render tree is a redbox for the
+   * customer's user, over a bug report they were trying to send us.
+   */
+  async submit(input: BugReportInput): Promise<BugSubmitResult> {
+    if (!input || !input.message || input.message.trim().length === 0) {
+      logger.warn('[scalebun] reportBug: a message is required');
+      return { e: 'empty' };
+    }
+    // No submitFn means the facade never finished wiring. That is 'init', not a send failure —
+    // the distinction is what tells an integrator to check their setup rather than their network.
+    if (!this.submitFn) return { e: 'init' };
+
+    if (input.voice && !input.voice.transcriptApproved) {
+      // Refused rather than silently stripped: dropping the attachment would send a report the user
+      // believes contains their voice note, and they would never learn it did not.
+      logger.warn('[scalebun] reportBug: voice note has no approved transcript — not sending');
+      return { e: 'empty' };
+    }
+
+    try {
+      // Order matters and mirrors the web path: signal BEFORE submit so the replay bytes are already
+      // in flight, and so the report's replay coordinate refers to a frame that exists. A flush
+      // cannot retroactively manufacture a frame, so a missing anchor must stay missing rather than
+      // become a misleading "start of session" link in the dashboard.
+      this.signalReport();
+      return await this.submitFn(input);
+    } catch {
+      return { e: 'send' };
+    }
+  }
+
+  teardown(): void {
+    this.submitFn = null;
+    this.signalFn = null;
+    this.active = false;
+  }
+}