@scalebun/react-native 1.0.3 → 1.1.0

package/src/features/bugreport/buildPayload.ts

@@ -0,0 +1,116 @@
+/**
+ * Builds the body for POST /ingestion/sessions/:sessionId/bug-reports.
+ *
+ * Kept as a PURE function with no transport, no bridge and no clock of its own, because the wire
+ * shape is a cross-repo contract and the only way to keep it honest is to be able to assert it
+ * directly. Every bound below is copied from the server DTO
+ * (wzb-dashboard-backend/src/features/bug-reports/dto/submit-bug-report.dto.ts) rather than guessed:
+ *
+ *   clientReportId?   string            idempotency key -> BugReport.clientReportId (@unique)
+ *   title?            string   <= 300
+ *   message           string   <= 20000  -> BugReport.description  (REQUIRED)
+ *   email?            string   <= 320
+ *   url?              string   <= 2000
+ *   console?          unknown[]          recent breadcrumbs
+ *   screenshotKey?    string   <= 512, [A-Za-z0-9._/-] and no ".."
+ *   timestamp?        number             2000-01-01 .. 2100-01-01 in epoch MILLIS
+ *   replaySeq?        int      0 .. 2147483647
+ *   replaySegmentId?  string   <= 256
+ *
+ * Truncating here rather than letting the server 400 is deliberate: a 20,001-character description
+ * is a real report from a real annoyed user, and losing it to a validation error helps nobody. The
+ * ceiling is theirs, so we respect it at the edge. Nothing is silently REWRITTEN — only cut, and
+ * only at bounds the server would otherwise reject outright.
+ */
+
+/** Mirrors SubmitBugReportDto. Optional keys are omitted entirely rather than sent as undefined. */
+export interface BugReportPayload {
+  clientReportId?: string;
+  title?: string;
+  message: string;
+  email?: string;
+  url?: string;
+  console?: unknown[];
+  screenshotKey?: string;
+  timestamp?: number;
+  replaySeq?: number;
+  replaySegmentId?: string;
+}
+
+export interface ReplayCoord {
+  seq?: number | null;
+  segmentId?: string | null;
+}
+
+const MAX_TITLE = 300;
+const MAX_MESSAGE = 20_000;
+const MAX_EMAIL = 320;
+const MAX_SEGMENT_ID = 256;
+/** The server rejects outside these; a drifted device clock must not cost us the whole report. */
+const TS_MIN = 946684800000; // 2000-01-01
+const TS_MAX = 4102444800000; // 2100-01-01
+const MAX_BREADCRUMBS = 50;
+
+function clip(v: string | undefined | null, max: number): string | undefined {
+  if (typeof v !== 'string') return undefined;
+  const t = v.trim();
+  return t.length === 0 ? undefined : t.slice(0, max);
+}
+
+export function buildBugReportPayload(
+  input: { message: string; title?: string; email?: string; clientReportId?: string },
+  breadcrumbs: readonly unknown[] = [],
+  ctx: { replayCoord?: ReplayCoord | null; timestamp?: number } = {},
+): BugReportPayload {
+  const message = (input.message ?? '').trim().slice(0, MAX_MESSAGE);
+
+  const payload: BugReportPayload = { message };
+
+  const title = clip(input.title, MAX_TITLE);
+  if (title) payload.title = title;
+
+  const email = clip(input.email, MAX_EMAIL);
+  if (email) payload.email = email;
+
+  const clientReportId = clip(input.clientReportId, 200);
+  if (clientReportId) payload.clientReportId = clientReportId;
+
+  if (breadcrumbs.length > 0) payload.console = breadcrumbs.slice(-MAX_BREADCRUMBS);
+
+  /**
+   * An out-of-range clock is DROPPED, not clamped.
+   *
+   * Clamping would invent a `reportedAt` the device never observed, and the server keeps that column
+   * separate from `createdAt` precisely so the two can be compared. A missing client time is honest;
+   * a fabricated one silently corrupts that comparison.
+   */
+  const ts = ctx.timestamp;
+  if (typeof ts === 'number' && Number.isFinite(ts) && ts >= TS_MIN && ts <= TS_MAX) {
+    payload.timestamp = ts;
+  }
+
+  /**
+   * The replay anchor is included ONLY when a frame actually existed at submit time.
+   *
+   * Defaulting `replaySeq` to 0 would point every anchor-less report at the start of the session,
+   * which reads in the dashboard exactly like a real anchor and is wrong. Replay may be disabled,
+   * paused, or yet to produce a frame; absent must stay absent.
+   */
+  const seq = ctx.replayCoord?.seq;
+  if (typeof seq === 'number' && Number.isInteger(seq) && seq >= 0 && seq <= 2147483647) {
+    payload.replaySeq = seq;
+    const segmentId = clip(ctx.replayCoord?.segmentId ?? undefined, MAX_SEGMENT_ID);
+    if (segmentId) payload.replaySegmentId = segmentId;
+  }
+
+  /**
+   * `url` is intentionally NEVER set on React Native.
+   *
+   * The field means a page URL. The nearest mobile concept is the current screen name, and putting
+   * a screen name in a column called `url` is exactly the field-misuse that makes a dashboard show
+   * one thing and mean another. Screen context already reaches the report through the session it is
+   * attached to. If mobile needs its own field, that is a schema change, not a reused column.
+   */
+
+  return payload;
+}

package/src/features/crash/CrashReporter.ts

@@ -18,7 +18,7 @@ import { noThrow } from '../../core/lifecycle/crashSafe';
 import { SessionManager } from '../session/SessionManager';
 
 /** Where the crash originated. */
-export type CrashSource = 'js' | 'handled' | 'native';
+export type CrashSource = 'js' | 'handled' | 'native' | 'manual';
 
 /** Normalized, transport-agnostic crash report. */
 export interface CrashReport {
@@ -40,6 +40,25 @@ export interface CrashReport {
     timestamp?: string;
     /** Free-form extra context (thread name, signal, cause, ...). */
     metadata?: Record<string, unknown>;
+    /**
+     * The session this crash BELONGS to, when that is not the current one.
+     *
+     * Set only by a recovered native crash: it happened in a process that is already gone, so the
+     * session it belongs to is not the session running now. Without it the report is routed through
+     * whichever SessionManager exists at drain time and lands on the NEW session — marking a healthy
+     * session crashed and the crashed one clean.
+     *
+     * Absent means "the current session", which is correct for every live report.
+     */
+    sessionId?: string;
+    /**
+     * Stable id for a recovered native crash — the idempotency key.
+     *
+     * Generated ONCE when the crash was first written to disk, never per attempt, so any number of
+     * retries collapse to one backend record. An id minted at upload time would defeat dedupe
+     * entirely and turn every retry into a fresh duplicate crash.
+     */
+    crashId?: string;
 }
 
 /**
@@ -111,11 +130,31 @@ export class BackendErrorsSink implements CrashSink {
     deliver(report: CrashReport): void {
         const transport = SessionManager.getExistingInstance()?.getBackendTransport();
         if (!transport) return;
+        // D12: this used to forward four fields and drop the rest — so a native
+        // crash's signal/thread/exception-type were captured on device and
+        // discarded one call before the wire, every RN error row had a NULL
+        // platform (making Issue.primaryPlatform mean "web-only"), and fatality
+        // was indistinguishable from a handled error. The receiver has always
+        // accepted all of these.
         transport.queueError({
             type: report.type,
             message: report.message,
             stack: report.stack,
             screenName: report.screenName,
+            platform: report.platform,
+            isFatal: report.isFatal,
+            metadata: report.metadata,
+            /**
+             * Carried through so the transport can address the ORIGINAL session.
+             *
+             * Set only on a recovered native crash, whose session died with its process. Omitted
+             * for every live report, where the current session is the right answer — so this
+             * changes nothing about normal error delivery.
+             */
+            ...(report.sessionId ? { sessionId: report.sessionId } : {}),
+            // Becomes SessionError.clientId, which is @unique — that constraint is what turns a
+            // retried crash into one record instead of a duplicate.
+            ...(report.crashId ? { clientId: report.crashId } : {}),
         });
         // Best-effort immediate delivery so the crash surfaces quickly.
         transport.flushErrors().catch(() => {});

package/src/features/crash/capture.ts

@@ -1,21 +1,48 @@
-import { createEnvelope } from '../../pipeline/envelope/envelope';
-import { memoryQueue } from '../../pipeline/queue/memoryQueue';
 import { noThrow } from '../../core/lifecycle/crashSafe';
+import { getCrashReporter } from './CrashReporter';
 
-export function captureException(error: Error, extra?: any) {
+/**
+ * Manual error/message capture — the `Sentry.captureException` equivalent.
+ *
+ * D3: these used to write envelopes into `memoryQueue`, a queue whose only
+ * drain (`Dispatcher.flush`) was registered in the DI container and never
+ * resolved by anything — every capture was accumulated and discarded. They
+ * were also never exported, so the two entry points were reachable by nobody
+ * and delivered to nowhere.
+ *
+ * Now they ride the SAME pipeline as automatic crash capture (CrashReporter →
+ * BackendErrorsSink → `/ingestion/sessions/:id/errors`) — the one path in this
+ * SDK that is proven to land rows.
+ */
+export function captureException(
+    error: Error,
+    extra?: { screenName?: string; metadata?: Record<string, unknown> },
+): void {
     noThrow(() => {
-        const envelope = createEnvelope('crash', {
+        getCrashReporter().report({
+            type: 'handled',
             message: error.message,
             stack: error.stack,
-            ...extra,
+            isFatal: false,
+            source: 'manual',
+            screenName: extra?.screenName,
+            metadata: extra?.metadata,
         });
-        memoryQueue.add(envelope);
     });
 }
 
-export function captureMessage(message: string) {
+export function captureMessage(
+    message: string,
+    extra?: { screenName?: string; metadata?: Record<string, unknown> },
+): void {
     noThrow(() => {
-        const envelope = createEnvelope('log', { message, level: 'info' });
-        memoryQueue.add(envelope);
+        getCrashReporter().report({
+            type: 'handled',
+            message,
+            isFatal: false,
+            source: 'manual',
+            screenName: extra?.screenName,
+            metadata: extra?.metadata,
+        });
     });
 }

package/src/features/crash/nativeCrashBridge.ts

@@ -1,7 +1,5 @@
 import { NativeModules } from 'react-native';
 import { nativeModuleVia } from '../../core/architecture';
-import { createEnvelope } from '../../pipeline/envelope/envelope';
-import { memoryQueue } from '../../pipeline/queue/memoryQueue';
 import { logger } from '../../core/logger/internalLogger';
 import { getCrashReporter } from './CrashReporter';
 
@@ -45,6 +43,27 @@ function getCrashModule(): any {
  * NSSetUncaughtExceptionHandler + signal handlers on iOS).
  * Safe to call multiple times — native side is idempotent.
  */
+/**
+ * Tell native which session is live, so a crash that happens next can name it.
+ *
+ * Called once per session — never per event. Native writes it to crash-safe storage immediately,
+ * because a fatal handler cannot call back into JS to ask, and by the time it runs the JS thread may
+ * already be gone.
+ *
+ * Fire-and-forget and no-throw: losing this degrades a recovered crash to unattributed, which is the
+ * old behaviour. It must never be able to fail a session start.
+ */
+export async function setNativeActiveSession(sessionId: string): Promise<void> {
+    try {
+        const mod = getCrashModule();
+        if (!mod?.setActiveSessionId || !sessionId) return;
+        await mod.setActiveSessionId(sessionId);
+        logger.debug(`[NativeCrash] Active session → ${sessionId}`);
+    } catch {
+        // No-throw
+    }
+}
+
 export async function installNativeCrashHandler(): Promise<void> {
     try {
         const mod = getCrashModule();
@@ -60,34 +79,68 @@ export async function installNativeCrashHandler(): Promise<void> {
 }
 
 /**
- * Drain a crash record left from the previous process run.
- * If found, enqueues a crash.native envelope and returns true.
- * Returns false when no pending crash is found.
+ * How many pending crashes one launch will deliver.
+ *
+ * The native spool holds three (a device that crashes, restarts offline, and crashes again), but
+ * `drainPendingCrash` hands back the OLDEST ONE ONLY. Draining once per launch therefore needed three
+ * launches to clear three crashes — and a fourth crash evicts the oldest, so on a device crashing in a
+ * loop the spool loses faster than a one-per-launch drain empties it.
+ *
+ * Bounded, not `while (true)`: this loop is driven by native state and stops the moment delivery
+ * fails, but the bound is what makes it impossible for a native bug — a clear that silently does
+ * nothing — to spin the drain forever at startup.
+ */
+const MAX_DRAIN_PER_LAUNCH = 4;
+
+/**
+ * Drain the crash records left from previous process runs.
+ * Returns true if at least one pending crash was found.
+ *
+ * Stops early the first time delivery fails: if the network is down for one crash it is down for the
+ * next, and every extra attempt is a request that cannot succeed made during app startup.
  */
 export async function drainNativeCrash(): Promise<boolean> {
+    let found = false;
+    const seen = new Set<string>();
+    for (let i = 0; i < MAX_DRAIN_PER_LAUNCH; i++) {
+        const outcome = await drainOne(seen);
+        if (outcome === 'none') break;
+        found = true;
+        // 'kept' means the backend did not take it. The rest of the spool is behind the same
+        // network, so stop rather than fail three more times.
+        if (outcome === 'kept') break;
+    }
+    return found;
+}
+
+/** One record: read → report → clear if the backend took it. */
+async function drainOne(seen: Set<string>): Promise<'none' | 'cleared' | 'kept'> {
     try {
         const mod = getCrashModule();
-        if (!mod?.drainPendingCrash) return false;
+        if (!mod?.drainPendingCrash) return 'none';
 
         const crash = await mod.drainPendingCrash();
-        if (!crash) return false;
+        if (!crash) return 'none';
+
+        /*
+         * The same record twice means the previous clear did not take effect — a native failure we
+         * cannot fix from here. Reporting it again would deliver a duplicate on every iteration, so
+         * treat it as the end of the spool.
+         */
+        const seenKey = typeof crash.crashId === 'string' ? crash.crashId : '';
+        // `''` is a deliberate sentinel for the single legacy record, which has no id. Tracking it
+        // too means a legacy clear that silently fails stops the loop instead of redelivering the
+        // same crash on every one of the remaining iterations.
+        if (seen.has(seenKey)) return 'none';
+        seen.add(seenKey);
 
         const stackArr: string[] = Array.isArray(crash.stackTrace) ? crash.stackTrace : [];
 
         // 1) Desktop debug stream — keep the rich native-crash envelope.
-        const envelope = createEnvelope('crash', {
-            name: crash.name ?? 'crash.native',
-            exceptionType: crash.exceptionType,
-            message: crash.message,
-            stackTrace: stackArr,
-            threadName: crash.threadName,
-            timestamp: crash.timestamp,
-            platform: crash.platform,
-            ...(crash.signal !== undefined ? { signal: crash.signal } : {}),
-            ...(crash.cause !== undefined ? { cause: crash.cause } : {}),
-            ...(crash.userInfo !== undefined ? { userInfo: crash.userInfo } : {}),
-        });
-        memoryQueue.add(envelope);
+        // D2: a rich envelope used to be written here into memoryQueue — a queue
+        // whose drain was never wired, so the native crash's forensic detail was
+        // captured and then discarded. The flattened report below now carries the
+        // same fields in `metadata` (D12), through the pipeline that actually lands.
 
         // 2) SaaS backend errors endpoint (dashboard Crashes view) — route the
         // same normalized report through the central reporter. This is what
@@ -99,6 +152,26 @@ export async function drainNativeCrash(): Promise<boolean> {
             message: crash.message ?? crash.exceptionType ?? 'Native crash',
             stack: stackArr.length ? stackArr.join('\n') : undefined,
             platform: crash.platform,
+            /**
+             * THE ORIGINAL SESSION — the entire point of the recovery path.
+             *
+             * This crash happened in a process that no longer exists, so it does NOT belong to the
+             * session running now. Passing it explicitly is what stops the reporter routing it
+             * through the current SessionManager and attributing it to the session created after
+             * the restart.
+             *
+             * Undefined on records written before this shipped, and on a crash that beat the first
+             * session. The sink then keeps the legacy behaviour rather than guessing an owner.
+             */
+            ...(crash.sessionId ? { sessionId: String(crash.sessionId) } : {}),
+            /**
+             * The stable id, carried through so it becomes the backend's dedupe key.
+             *
+             * Written once when the crash was first persisted — never regenerated here. If this were
+             * minted per attempt, every retry would arrive as a brand-new crash and at-least-once
+             * delivery would turn into duplicate-every-time.
+             */
+            ...(crash.crashId ? { crashId: String(crash.crashId) } : {}),
             metadata: {
                 exceptionType: crash.exceptionType,
                 threadName: crash.threadName,
@@ -106,8 +179,69 @@ export async function drainNativeCrash(): Promise<boolean> {
             },
         });
 
-        logger.info('[NativeCrash] Previous crash drained → desktop + backend');
-        return true;
+        /**
+         * DELETE ONLY AFTER THE BACKEND HAS IT.
+         *
+         * The read above is non-destructive, so the crash is still on disk right now. It is removed
+         * only once delivery has actually succeeded — previously the record was destroyed at read
+         * time, so a failed upload lost the crash permanently: the app had proof of a crash, deleted
+         * it, and then failed to send it.
+         *
+         * On failure we simply do NOT clear. The crash stays pending and is retried on the next
+         * launch, which is what makes this at-least-once. Duplicate delivery is safe because the
+         * crash carries a stable `crashId` that the backend dedupes on — a retry produces no second
+         * record.
+         *
+         * A record with no `crashId` is legacy: it predates stable ids, so it cannot be safely
+         * retried (a redelivery WOULD duplicate) and is cleared immediately, preserving exactly the
+         * old at-most-once behaviour for old data rather than silently changing it.
+         */
+        const crashId = seenKey;
+        if (!crashId) {
+            await mod.clearPendingCrash?.('');
+            logger.info('[NativeCrash] Legacy crash (no id) drained and cleared');
+            return 'cleared';
+        }
+
+        const delivered = await confirmDelivery();
+        if (delivered) {
+            await mod.clearPendingCrash?.(crashId);
+            logger.info(`[NativeCrash] Crash ${crashId} delivered → cleared`);
+            return 'cleared';
+        }
+        logger.info(`[NativeCrash] Crash ${crashId} not yet delivered → kept for retry`);
+        return 'kept';
+    } catch {
+        // Unknown state — stop the loop rather than risk spinning on a failure we cannot diagnose.
+        return 'none';
+    }
+}
+
+/**
+ * Has the crash actually reached the backend?
+ *
+ * The reporter's sinks are fire-and-forget by design (a crash report must never block or throw), so
+ * "delivered" is asked of the transport rather than inferred from `report()` returning. If the
+ * transport is not up yet — the drain can win the race against SessionManager — the answer is NO and
+ * the crash stays on disk for the next launch. That is strictly better than the old behaviour, where
+ * exactly that race deleted the record and dropped the crash silently.
+ */
+async function confirmDelivery(): Promise<boolean> {
+    try {
+        const { SessionManager } = await import('../session/SessionManager');
+        const transport = SessionManager.getExistingInstance()?.getBackendTransport();
+        // No transport yet — the drain can win the startup race. That is a delivery FAILURE, not a
+        // reason to give up: the record stays on disk and the next launch retries it. This exact
+        // path used to delete the crash and send nothing.
+        if (!transport) return false;
+        /**
+         * The BOOLEAN, not merely "it resolved".
+         *
+         * flushErrors used to return void and swallow its own errors, so awaiting it proved only
+         * that the call finished. Deleting a crash on that basis would have thrown away crashes
+         * that never reached the backend — the failure this whole change exists to prevent.
+         */
+        return (await transport.flushErrors()) === true;
     } catch {
         return false;
     }

package/src/features/engage/EngagePromptProvider.tsx

@@ -609,7 +609,47 @@ export function EngagePromptProvider({
                       };
 
                 const drafts = result.attachments ?? [];
-                if (engage.submitResponseConfirmed) {
+
+                /**
+                 * Bug-report lane — opt in per campaign via `fileAsBugReport`.
+                 *
+                 * A FEEDBACK campaign fired by `shake_device` is almost always "something is
+                 * broken", not "how do you feel", and those are different products: a bug report
+                 * gets a status, a priority and an assignee on /diagnose/bug-reports, while a survey
+                 * response is counted in aggregate and cannot be triaged.
+                 *
+                 * Routed INSTEAD of submitResponse rather than in addition — a dual write would
+                 * create two rows for one submission and double-count the campaign on the Engage
+                 * side.
+                 *
+                 * `responseId` doubles as the idempotency key so a retried submit cannot file the
+                 * same report twice (BugReport.clientReportId is @unique).
+                 *
+                 * Falls through to the normal lane when the host facade predates `reportBugDetailed`
+                 * — an older app bundling a newer config degrades to existing behaviour instead of
+                 * dropping the user's report on the floor.
+                 */
+                const bugLane =
+                    campaign.fileAsBugReport && typeof (engage as any).reportBugDetailed === 'function'
+                        ? ((engage as any).reportBugDetailed as (i: {
+                              message: string;
+                              title?: string;
+                              clientReportId?: string;
+                          }) => Promise<unknown>)
+                        : null;
+
+                if (bugLane) {
+                    const outcome = await bugLane({
+                        message: result.reason ?? '',
+                        title: campaign.name,
+                        clientReportId: responseId,
+                    });
+                    // Surface a refusal as a throw so the existing retry/error UI handles it; a
+                    // silent success here would tell the user their report was filed when it wasn't.
+                    if (outcome && typeof outcome === 'object' && 'e' in (outcome as object)) {
+                        throw new Error(`bug report failed: ${(outcome as { e: string }).e}`);
+                    }
+                } else if (engage.submitResponseConfirmed) {
                     // Confirmed lane: awaits real persistence (presign+PUT bytes → response
                     // POST), reports stages, idempotent on responseId, throws on failure.
                     await engage.submitResponseConfirmed(input, drafts, {
@@ -676,7 +716,13 @@ export function EngagePromptProvider({
                     action: options?.action,
                 });
                 if (!campaign) {
-                    logger.debug('[Engage] no eligible campaign to render');
+                    // Name the inputs so a silent mismatch (wrong trigger name, throttle
+                    // suppression, type filter) is diagnosable from device logs alone.
+                    logger.debug(
+                        `[Engage] no eligible campaign to render (trigger=${options?.trigger ?? '—'} ` +
+                            `candidates=${config.campaigns.length} ` +
+                            `[${config.campaigns.map((c) => `${c.type}:${c.trigger ?? '—'}`).join(', ')}])`,
+                    );
                     return false;
                 }
 

package/src/features/engage/EngagePromptView.tsx

@@ -241,7 +241,21 @@ function RatingPrompt({ campaign, onSubmit, onDismiss, onStart, rating }: Prompt
 
 // ─── FEEDBACK render branch (free text + optional category/tags) ─────────────
 
-function FeedbackPrompt({ campaign, onSubmit, onDismiss, onStart }: PromptBranchProps): ReactElement {
+function FeedbackPrompt(props: PromptBranchProps): ReactElement {
+    // A FEEDBACK campaign authored with structured questions (voice, scale, emoji,
+    // screenshot, multiple prompts) IS a survey — this branch only knows how to draw
+    // one text box plus category chips, and used to silently render a voice question
+    // as text (found live: "it was supposed to be a voice input but showed text").
+    // Anything beyond chips delegates to the full survey renderer, which owns the
+    // record → transcribe → approve voice flow.
+    const structured = (props.campaign.questions ?? []).some(
+        (q) => q.kind !== 'choice' && q.kind !== 'single' && q.kind !== 'multi',
+    );
+    if (structured) return <SurveyPrompt {...props} />;
+    return <FeedbackTextPrompt {...props} />;
+}
+
+function FeedbackTextPrompt({ campaign, onSubmit, onDismiss, onStart }: PromptBranchProps): ReactElement {
     const [text, setText] = useState('');
     const [selectedTags, setSelectedTags] = useState<string[]>([]);
 
@@ -500,7 +514,14 @@ function SurveyPrompt({ campaign, onSubmit, onDismiss, onStart }: PromptBranchPr
                 return result;
             }, []);
 
+    // A survey where every question is optional could be submitted with nothing
+    // answered and nothing attached — an empty response row polluting analytics
+    // (found live: voice question, Submit tapped without ever recording). Content
+    // is what gates the final Submit; "Not now" remains the way out.
+    const hasAnyContent = (): boolean => questions.some((q) => isAnswered(q));
+
     const submit = (): void => {
+        if (!hasAnyContent()) return;
         const drafts = Object.values(attachments);
         onSubmit({
             answers: assemble(),
@@ -739,17 +760,25 @@ function SurveyPrompt({ campaign, onSubmit, onDismiss, onStart }: PromptBranchPr
                     <Pressable accessibilityRole="button" accessibilityLabel="Start survey" onPress={() => { onStart?.(); setStep(0); }} style={styles.submitBtn}>
                         <Text style={styles.submitText}>Start</Text>
                     </Pressable>
-                ) : current ? (
-                    <Pressable
-                        accessibilityRole="button"
-                        accessibilityLabel={step === questions.length - 1 || current.skipTo === 'end' ? 'Submit survey' : 'Continue survey'}
-                        disabled={current.required === true && !isAnswered(current)}
-                        onPress={advance}
-                        style={[styles.submitBtn, current.required === true && !isAnswered(current) ? styles.submitBtnDisabled : null]}
-                    >
-                        <Text style={styles.submitText}>{step === questions.length - 1 || current.skipTo === 'end' ? 'Submit' : 'Continue'}</Text>
-                    </Pressable>
-                ) : null}
+                ) : current ? (() => {
+                    const isSubmitStep = step === questions.length - 1 || current.skipTo === 'end';
+                    // A required question blocks its own step; the submit step
+                    // additionally requires the survey to carry ANY content at all.
+                    const blocked =
+                        (current.required === true && !isAnswered(current)) ||
+                        (isSubmitStep && !hasAnyContent());
+                    return (
+                        <Pressable
+                            accessibilityRole="button"
+                            accessibilityLabel={isSubmitStep ? 'Submit survey' : 'Continue survey'}
+                            disabled={blocked}
+                            onPress={advance}
+                            style={[styles.submitBtn, blocked ? styles.submitBtnDisabled : null]}
+                        >
+                            <Text style={styles.submitText}>{isSubmitStep ? 'Submit' : 'Continue'}</Text>
+                        </Pressable>
+                    );
+                })() : null}
             </View>
         </View>
     );
@@ -845,12 +874,19 @@ function VoiceQuestion({
                 🎙 Voice note recorded · {formatElapsed(draft.durationMs ?? 0)}
             </Text>
             <Text style={styles.voiceHint}>
-                Review the transcript below — edit it, then approve to send. Nothing is
-                sent until you approve.
+                {(draft.transcript ?? '').trim().length > 0
+                    ? 'Review the transcript below — edit it, then approve to send. Nothing is sent until you approve.'
+                    : // An empty prefill is a device limitation (on many phones the recorder
+                      // holds the microphone, so the on-device engine hears silence) — the
+                      // recording itself was captured fine. Say so, or the blank field reads
+                      // as a bug and the typed-transcript path goes undiscovered.
+                      'Your recording was captured, but automatic transcription wasn’t available on this device. Type what you said (optional), then approve to send.'}
             </Text>
             <TextInput
                 style={styles.reasonInput}
-                placeholder="Transcript (edit before approving)"
+                placeholder={(draft.transcript ?? '').trim().length > 0
+                    ? 'Transcript (edit before approving)'
+                    : 'Type what you said (optional)'}
                 placeholderTextColor="#9097A3"
                 value={draft.transcript ?? ''}
                 onChangeText={onEditTranscript}

package/src/features/engage/EngageTransport.ts

@@ -56,7 +56,7 @@ function uuidV4(): string {
 }
 
 export interface EngageTransportConfig {
-    /** Backend API base URL (e.g. https://api.scalebun.com). */
+    /** Backend API base URL (e.g. https://api.scalebun.com/api/v1). */
     endpoint: string;
     /** SaaS multi-tenant client key — gates upload lanes + x-scalebun-client-key header. */
     clientKey?: string;

package/src/features/engage/engageTriggerEngine.ts

@@ -106,6 +106,21 @@ export function installEngageTriggerEngine(deps: EngageTriggerEngineDeps): () =>
 
     const fire = (options: ShowEngagePromptOptions): void => {
         try {
+            // A fire while the app is not foregrounded renders behind the lock
+            // screen (or into a backgrounded activity), records the impression,
+            // and permanently consumes a showOnce campaign that no human saw.
+            // Found live: a cold start with the screen off burned both a survey
+            // and an in-app message before the phone was ever unlocked.
+            if (appLifecycle.getCurrentState() !== 'active') {
+                logger.debug(
+                    `[Engage] trigger suppressed (app ${appLifecycle.getCurrentState()}): ${options.trigger ?? 'manual'}`,
+                );
+                return;
+            }
+            logger.debug(
+                `[Engage] trigger fire: ${options.trigger ?? 'manual'}` +
+                    (options.screen ? ` screen=${options.screen}` : ''),
+            );
             deps.fire(options);
         } catch (err) {
             logger.debug('[Engage] trigger fire failed:', (err as Error)?.message);