@scalebun/react-native 1.0.4 → 1.2.0

package/src/core/constants/protocol.ts

@@ -0,0 +1,24 @@
+/**
+ * ScaleBun SDK — Debug-protocol constants needed OUTSIDE the debug lane.
+ *
+ * `PROTOCOL_VERSION` is stamped onto journey/session envelopes by production code
+ * (journeyManager, DesktopSessionTransport). Importing it from `vendor/protocol` — its canonical
+ * home — drags the whole vendored schema module into every production bundle, because that module
+ * builds all desktop wire-message schemas at module scope and Metro performs no tree shaking.
+ * Measured: 4,240 bytes of minified schema code shipped for the sake of two numeric constants.
+ *
+ * So the two constants are declared here, dependency-free, and production code imports THIS file.
+ * The vendored module keeps re-exporting its own copies for the debug lane, which is the only
+ * place the schemas themselves are used.
+ *
+ * The vendored file itself is deliberately untouched — `vendor/protocol` is a byte-identical copy
+ * of `@scalebun/protocol` enforced by parity gates, so the values are duplicated here rather than
+ * re-exported. `core/constants/__tests__/protocolConstants.test.ts` asserts both copies stay
+ * equal; if the canonical protocol bumps a value, that test fails until this file follows.
+ */
+
+/** Wire-protocol version stamped on every desktop-debug and journey envelope. */
+export const PROTOCOL_VERSION = 1;
+
+/** Heartbeat interval sent in ACK; the SDK uses this for its ping timer. */
+export const DEFAULT_HEARTBEAT_INTERVAL_MS = 5000;

package/src/core/constants/timings.ts

@@ -5,7 +5,9 @@
  * Import from here instead of using inline literals.
  */
 
-export { DEFAULT_HEARTBEAT_INTERVAL_MS } from '../../vendor/protocol';
+// From the SDK-owned constants copy, NOT vendor/protocol — importing the vendored module here
+// would ship every desktop wire-message schema in every production bundle. See ./protocol.ts.
+export { DEFAULT_HEARTBEAT_INTERVAL_MS } from './protocol';
 
 /** Default WebSocket port when no port is specified in DebugConfig */
 export const DEFAULT_WS_PORT = 9333;

package/src/core/lifecycle/appLifecycle.ts

@@ -12,7 +12,7 @@ class AppLifecycle {
     }
 
     private handleStateChange = (nextState: AppStateStatus) => {
-        logger.debug(`App state changed: ${this.currentState} -> ${nextState}`);
+        __DEV__ && logger.debug(`App state changed: ${this.currentState} -> ${nextState}`);
         this.currentState = nextState;
         this.listeners.forEach((l) => l(nextState));
     };

package/src/debug/bootstrap.ts

@@ -85,6 +85,22 @@ let _autoScreenDetector: AutoScreenDetector | null = null;
 
 // ─── Public API ─────────────────────────────────────────────────────────────
 
+/**
+ * Is the desktop-debugger tooling present in this bundle?
+ *
+ * When `features: { devTools: false }` is set in metro.config.js these modules resolve to an empty
+ * stub, so their exports are `undefined`. Checked as values rather than via a build-time flag
+ * because the answer is a property of how the bundle was resolved, which no runtime flag can know.
+ */
+function isDevToolsBundled(): boolean {
+    return (
+        typeof DebugTransport === 'function' &&
+        typeof DebugEventStream === 'function' &&
+        typeof CommandRegistry === 'function' &&
+        typeof resolveDebugHost === 'function'
+    );
+}
+
 /**
  * Enable the debug subsystem. Connects to the desktop app over WebSocket
  * and starts streaming SDK events.
@@ -94,13 +110,29 @@ let _autoScreenDetector: AutoScreenDetector | null = null;
 export function enableDebug(config: DebugConfig): void {
     try {
         if (_enabled) {
-            logger.debug('Debug already enabled, skipping');
+            __DEV__ && logger.debug('Debug already enabled, skipping');
+            return;
+        }
+
+        // The desktop-debugger tooling can be excluded from a build via
+        // `withScaleBun(config, { features: { devTools: false } })`, which resolves these modules
+        // to an empty stub. Detect that explicitly: without this check the first `new
+        // DebugTransport(...)` throws "not a constructor", the catch below reports it as a failure
+        // to enable debug, and the real cause — a deliberate build-time opt-out — is three layers
+        // from the message the developer reads.
+        if (!isDevToolsBundled()) {
+            logger.warn(
+                '[ScaleBun] debugConnection was configured, but the desktop-debugger tooling is not ' +
+                    'in this bundle. It is excluded by default (the ScaleBun desktop app is not yet ' +
+                    'released); opt in with `withScaleBun(config, { features: { devTools: true } })` ' +
+                    'in metro.config.js. All other SDK behaviour is unaffected.',
+            );
             return;
         }
 
         const host = resolveDebugHost(config.host);
         const port = config.port ?? DEFAULT_WS_PORT;
-        logger.debug(`Enabling debug transport → ws://${host}:${port}`);
+        __DEV__ && logger.debug(`Enabling debug transport → ws://${host}:${port}`);
 
         // Store journey config
         _journeyConfig = {
@@ -202,7 +234,7 @@ export function enableDebug(config: DebugConfig): void {
 
         // Transport events
         _transport.onStateChange((state) => {
-            logger.debug(`[Debug Transport] State → ${state}`);
+            __DEV__ && logger.debug(`[Debug Transport] State → ${state}`);
         });
 
         // Connect and install
@@ -215,7 +247,7 @@ export function enableDebug(config: DebugConfig): void {
 
         _enabled = true;
         _debugReady = true;
-        logger.info(`Debug enabled → ws://${host}:${port}`);
+        __DEV__ && logger.info(`Debug enabled → ws://${host}:${port}`);
 
         // Auto native capture wiring
         wireNativeCaptureDeferred(() => _sessionManager);
@@ -232,7 +264,7 @@ export function enableDebug(config: DebugConfig): void {
                     navMode: _autoScreenDetector ? 'auto' : 'beacon',
                     sdkVersion: '1.0.0',
                 });
-                logger.debug('Emitted journey:debug_ready event to desktop');
+                __DEV__ && logger.debug('Emitted journey:debug_ready event to desktop');
             } catch { /* no-throw */ }
         }, DEBUG_READY_EMIT_DELAY_MS);
     } catch (e) {
@@ -312,7 +344,6 @@ export function _isJourneyEnabled(): boolean { return _journeyConfig.enabled; }
 /** @internal */
 export function _setDebugReady(ready: boolean): void { _debugReady = ready; }
 /** @internal */
-export function _isDebugReady(): boolean { return _debugReady; }
 /** @internal */
 export function _getSessionManager(): SessionManagerType | null { return _sessionManager; }
 /** @internal */
@@ -329,7 +360,9 @@ export { setTrackedScreen, getTrackedScreen } from './screenTracking';
 export function _emitJourneyEvent(name: string, data: Record<string, unknown>): void {
     if (!_transport || !_enabled) return;
     try {
-        const { PROTOCOL_VERSION } = require('./protocol');
+        // From the SDK-owned constants module — requiring './protocol' here would statically drag
+        // the vendored schema module into every bundle, even ones that exclude the debug tooling.
+        const { PROTOCOL_VERSION } = require('../core/constants/protocol');
         const msg = {
             type: 'event' as const,
             protocolVersion: PROTOCOL_VERSION,

package/src/debug/exportBridge.ts

@@ -83,7 +83,9 @@ export function requestExport(
             _pendingExports.set(requestId, { requestId, resolve, reject, timer });
 
             // Send export request event to desktop
-            const { PROTOCOL_VERSION } = require('./protocol');
+            // From the SDK-owned constants module — requiring './protocol' here would statically
+            // drag the vendored schema module into every bundle, even devtools-excluded ones.
+            const { PROTOCOL_VERSION } = require('../core/constants/protocol');
             transport.send({
                 type: 'event' as const,
                 protocolVersion: PROTOCOL_VERSION,
@@ -99,7 +101,7 @@ export function requestExport(
                 },
             } as any);
 
-            logger.info(`[ExportBridge] Export request sent: ${requestId}`);
+            __DEV__ && logger.info(`[ExportBridge] Export request sent: ${requestId}`);
 
         } catch (err: any) {
             resolve({
@@ -135,7 +137,7 @@ export function handleExportResult(args: Record<string, unknown>): void {
             cancelled: args.cancelled as boolean | undefined,
         });
 
-        logger.info(`[ExportBridge] Export result received: ${requestId} success=${args.success}`);
+        __DEV__ && logger.info(`[ExportBridge] Export result received: ${requestId} success=${args.success}`);
     } catch { /* no-throw */ }
 }
 

package/src/debug/hostResolver.ts

@@ -15,7 +15,7 @@ import { logger } from '../core/logger/internalLogger';
  */
 export function resolveDebugHost(explicit?: string): string {
     if (explicit) {
-        logger.debug(`Debug host: explicit → ${explicit}`);
+        __DEV__ && logger.debug(`Debug host: explicit → ${explicit}`);
         return explicit;
     }
     // Android emulator needs 10.0.2.2 to reach host machine's loopback.
@@ -29,6 +29,6 @@ export function resolveDebugHost(explicit?: string): string {
     } catch {
         // Fallback to localhost if Platform is unavailable
     }
-    logger.debug(`Debug host: auto → ${host}`);
+    __DEV__ && logger.debug(`Debug host: auto → ${host}`);
     return host;
 }

package/src/debug/perfWiring.ts

@@ -33,7 +33,7 @@ export function initPerformance(
     },
 ): { performanceFeature: PerformanceFeature | null; perfMonitor: PerfMonitor | null } {
     if (config.performanceDisabled) {
-        logger.debug('Performance feature disabled — skipping PerformanceFeature init');
+        __DEV__ && logger.debug('Performance feature disabled — skipping PerformanceFeature init');
         return { performanceFeature: null, perfMonitor: null };
     }
 
@@ -69,7 +69,7 @@ export function initPerformance(
         });
 
         initPromise.then(() => {
-            logger.info('PerformanceFeature initialized successfully');
+            __DEV__ && logger.info('PerformanceFeature initialized successfully');
         }).catch((perfErr: any) => {
             logger.warn('PerformanceFeature async init failed:', perfErr?.message);
         });
@@ -96,7 +96,7 @@ export function initProfiler(
     enableProfiler?: boolean,
 ): ProfilerFeature | null {
     if (enableProfiler === false) {
-        logger.debug('Profiler feature disabled — skipping ProfilerFeature init');
+        __DEV__ && logger.debug('Profiler feature disabled — skipping ProfilerFeature init');
         return null;
     }
 
@@ -106,7 +106,7 @@ export function initProfiler(
         profilerFeature.setSessionId(transport.sessionId);
 
         profilerFeature.initialize().then(() => {
-            logger.info('ProfilerFeature initialized successfully (idle state)');
+            __DEV__ && logger.info('ProfilerFeature initialized successfully (idle state)');
         }).catch((initErr: any) => {
             logger.warn('ProfilerFeature init failed (non-fatal, native module may not be present):', initErr?.message);
         });

package/src/debug/replayWiring.ts

@@ -28,13 +28,13 @@ export function initReplaySdk(
     transport: DebugTransport,
 ): void {
     if (replayConfig === undefined) {
-        logger.debug('Replay feature disabled — skipping replay-sdk init');
+        __DEV__ && logger.debug('Replay feature disabled — skipping replay-sdk init');
         return;
     }
     try {
         ReplaySdk.init(replayConfig, { debugTransport: transport }).then(() => {
             _replaySdkInitialized = true;
-            logger.info('Replay SDK initialized with desktop transport');
+            __DEV__ && logger.info('Replay SDK initialized with desktop transport');
         }).catch((err: any) => {
             logger.warn('Replay SDK init failed (non-fatal):', err?.message);
         });
@@ -53,7 +53,7 @@ export function wireNativeCaptureDeferred(
     getSessionManager: () => SessionManagerType | null,
 ): void {
     if (_nativeCaptureWired) {
-        logger.debug('[AutoCapture] Already wired — skipping');
+        __DEV__ && logger.debug('[AutoCapture] Already wired — skipping');
         return;
     }
 
@@ -101,7 +101,7 @@ export function wireNativeCaptureDeferred(
                     if (typeof (sessionManager as any).setNativeCapture === 'function') {
                         (sessionManager as any).setNativeCapture(nativeBridgeCapture);
                         _nativeCaptureWired = true;
-                        logger.info('[AutoCapture] ✅ Native bridge capture wired (bridgeAdapter)');
+                        __DEV__ && logger.info('[AutoCapture] ✅ Native bridge capture wired (bridgeAdapter)');
                         return;
                     }
                 }
@@ -111,7 +111,7 @@ export function wireNativeCaptureDeferred(
 
             // Fallback: SessionManager was already created with nativeCapture
             _nativeCaptureWired = true;
-            logger.info('[AutoCapture] ✅ Native capture available via SessionManager bootstrap');
+            __DEV__ && logger.info('[AutoCapture] ✅ Native capture available via SessionManager bootstrap');
 
         } catch (err: any) {
             logger.warn('[AutoCapture] Wiring failed:', err?.message);

package/src/debug/screenTracking.ts

@@ -41,12 +41,12 @@ export function startAutoScreenDetection(): AutoScreenDetector | null {
         detector.onScreenChange((screenName, source) => {
             // Update cross-cutting screen tracker
             setTrackedScreen(screenName);
-            logger.debug(`[AutoScreenDebug] Screen mirrored → '${screenName}' (source: ${source})`);
+            __DEV__ && logger.debug(`[AutoScreenDebug] Screen mirrored → '${screenName}' (source: ${source})`);
         });
 
         // Ensure it's started in case debug connects before SDKBootstrapper finishes
         detector.start();
-        logger.info('[AutoScreen] Auto screen detection debug-mirror started');
+        __DEV__ && logger.info('[AutoScreen] Auto screen detection debug-mirror started');
         return detector;
     } catch (err: any) {
         logger.warn('[AutoScreen] Failed to start debug-mirror:', err?.message);

package/src/debug/sessionWiring.ts

@@ -24,7 +24,7 @@ export function createSessionManager(
     sessionDisabled?: boolean,
 ): SessionManagerType | null {
     if (sessionDisabled) {
-        logger.debug('Session feature disabled — skipping SessionManager');
+        __DEV__ && logger.debug('Session feature disabled — skipping SessionManager');
         return null;
     }
 
@@ -47,7 +47,7 @@ export function createSessionManager(
         // Attach desktop transport
         sessionManager.setDesktopTransport(transport);
         commands.setSessionManager(sessionManager);
-        logger.info('Session manager wired for debug (desktop transport attached)');
+        __DEV__ && logger.info('Session manager wired for debug (desktop transport attached)');
 
         return sessionManager;
 

package/src/features/crash/NativeCrashFeature.ts

@@ -25,7 +25,7 @@ export class NativeCrashFeature implements IFeature {
         drainNativeCrash()
             .then((found) => {
                 if (found) {
-                    logger.info('[NativeCrashFeature] Previous native crash queued for upload');
+                    __DEV__ && logger.info('[NativeCrashFeature] Previous native crash queued for upload');
                 }
             })
             .catch(() => {});

package/src/features/crash/globalHandler.ts

@@ -17,14 +17,14 @@ export function installGlobalHandler(onCrash: (error: Error, isFatal: boolean) =
     noThrow(() => {
         const errorUtils = (globalThis as any).ErrorUtils;
         if (!errorUtils || typeof errorUtils.getGlobalHandler !== 'function') {
-            logger.debug('[Crash] ErrorUtils unavailable — global JS error handler not installed');
+            __DEV__ && logger.debug('[Crash] ErrorUtils unavailable — global JS error handler not installed');
             return;
         }
 
         const originalHandler = errorUtils.getGlobalHandler();
 
         errorUtils.setGlobalHandler((error: any, isFatal?: boolean) => {
-            logger.debug('Caught global error:', error?.message);
+            __DEV__ && logger.debug('Caught global error:', error?.message);
 
             onCrash(error, !!isFatal);
 
@@ -34,6 +34,6 @@ export function installGlobalHandler(onCrash: (error: Error, isFatal: boolean) =
             }
         });
 
-        logger.debug('Global error handler installed');
+        __DEV__ && logger.debug('Global error handler installed');
     });
 }

package/src/features/crash/nativeCrashBridge.ts

@@ -23,7 +23,7 @@ function getCrashModule(): any {
         // eslint-disable-next-line @typescript-eslint/no-var-requires
         const turbo = require('../../specs/NativeScaleBunCrash').default;
         if (turbo) {
-            logger.debug(`[NativeCrash] resolved via ${nativeModuleVia()}`);
+            __DEV__ && logger.debug(`[NativeCrash] resolved via ${nativeModuleVia()}`);
             _crashModule = { mod: turbo };
             return turbo;
         }
@@ -58,7 +58,7 @@ export async function setNativeActiveSession(sessionId: string): Promise<void> {
         const mod = getCrashModule();
         if (!mod?.setActiveSessionId || !sessionId) return;
         await mod.setActiveSessionId(sessionId);
-        logger.debug(`[NativeCrash] Active session → ${sessionId}`);
+        __DEV__ && logger.debug(`[NativeCrash] Active session → ${sessionId}`);
     } catch {
         // No-throw
     }
@@ -68,11 +68,11 @@ export async function installNativeCrashHandler(): Promise<void> {
     try {
         const mod = getCrashModule();
         if (!mod?.install) {
-            logger.debug('[NativeCrash] Native module not available — skipping install');
+            __DEV__ && logger.debug('[NativeCrash] Native module not available — skipping install');
             return;
         }
         await mod.install();
-        logger.debug('[NativeCrash] Handler installed');
+        __DEV__ && logger.debug('[NativeCrash] Handler installed');
     } catch {
         // No-throw
     }
@@ -199,17 +199,17 @@ async function drainOne(seen: Set<string>): Promise<'none' | 'cleared' | 'kept'>
         const crashId = seenKey;
         if (!crashId) {
             await mod.clearPendingCrash?.('');
-            logger.info('[NativeCrash] Legacy crash (no id) drained and cleared');
+            __DEV__ && 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`);
+            __DEV__ && logger.info(`[NativeCrash] Crash ${crashId} delivered → cleared`);
             return 'cleared';
         }
-        logger.info(`[NativeCrash] Crash ${crashId} not yet delivered → kept for retry`);
+        __DEV__ && 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.

package/src/features/crash/rejectionHandler.ts

@@ -69,7 +69,7 @@ export function installRejectionHandler(
         noThrow(() => {
             const tracker = (deps?.resolveTracker ?? defaultResolveTracker)();
             if (!tracker || typeof tracker.enable !== 'function') {
-                logger.debug(
+                __DEV__ && logger.debug(
                     '[Crash] promise rejection tracking unavailable — unhandled rejections not captured',
                 );
                 return false;
@@ -107,7 +107,7 @@ export function installRejectionHandler(
                 },
             });
 
-            logger.debug('Unhandled promise rejection handler installed');
+            __DEV__ && logger.debug('Unhandled promise rejection handler installed');
             return true;
         }) ?? false
     );

package/src/features/engage/EngageArchetypeRenderers.tsx

@@ -3703,14 +3703,3 @@ export const ARCHETYPE_RENDERERS: Record<string, ArchetypeRenderer> = {
   celebration_confetti_full_screen: CelebrationInApp,
 };
 
-/** Resolve archetype renderer if spec.archetype is a known mechanic key. */
-export function resolveArchetypeRenderer(
-  archetype?: string,
-): ArchetypeRenderer | null {
-  if (!archetype) return null;
-  const familyRenderer = resolveArchetypeContent(archetype);
-  if (familyRenderer) return familyRenderer;
-  return Object.prototype.hasOwnProperty.call(ARCHETYPE_RENDERERS, archetype)
-    ? (ARCHETYPE_RENDERERS[archetype] ?? null)
-    : null;
-}

package/src/features/engage/EngageInAppView.tsx

@@ -2062,7 +2062,7 @@ export function EngageInAppView({
     const Branch = resolveInAppPresentationRenderer(presentation, mountModelOverride);
     const theme = resolveTheme(effectiveSpec);
     if (__DEV__) {
-        logger.debug(
+        __DEV__ && logger.debug(
             `[Engage] in-app ${message.id} rendering variant="${presentation.variantKey ?? 'legacy'}" archetype="${presentation.archetype}" mount="${effectiveMountModel}" layout="${presentation.legacyLayout}" fallback="${presentation.fallback?.reason ?? 'none'}"${message.isTest ? ` (test ${message.testRunId ?? message.previewId ?? message.id})` : ''}`,
         );
     }

package/src/features/engage/EngagePromptProvider.tsx

@@ -467,7 +467,7 @@ export function EngagePromptProvider({
                     deviceId: getDeviceId(),
                 });
             } catch (err) {
-                logger.debug('[Engage] trackEvent failed:', (err as Error)?.message);
+                __DEV__ && logger.debug('[Engage] trackEvent failed:', (err as Error)?.message);
             }
         },
         [engage],
@@ -487,7 +487,7 @@ export function EngagePromptProvider({
                     screen: activeScreenRef.current,
                 });
             } catch (err) {
-                logger.debug('[Engage] survey impression failed:', (err as Error)?.message);
+                __DEV__ && logger.debug('[Engage] survey impression failed:', (err as Error)?.message);
             }
         },
         [engage],
@@ -517,7 +517,7 @@ export function EngagePromptProvider({
                     dims: currentRatingDims(),
                 });
             } catch (err) {
-                logger.debug('[Engage] emitRatingEvent failed:', (err as Error)?.message);
+                __DEV__ && logger.debug('[Engage] emitRatingEvent failed:', (err as Error)?.message);
             }
         },
         [engage],
@@ -718,7 +718,7 @@ export function EngagePromptProvider({
                 if (!campaign) {
                     // Name the inputs so a silent mismatch (wrong trigger name, throttle
                     // suppression, type filter) is diagnosable from device logs alone.
-                    logger.debug(
+                    __DEV__ && logger.debug(
                         `[Engage] no eligible campaign to render (trigger=${options?.trigger ?? '—'} ` +
                             `candidates=${config.campaigns.length} ` +
                             `[${config.campaigns.map((c) => `${c.type}:${c.trigger ?? '—'}`).join(', ')}])`,
@@ -804,7 +804,7 @@ export function EngagePromptProvider({
                     ...(Object.keys(meta).length > 0 ? { meta } : {}),
                 });
             } catch (err) {
-                logger.debug('[Engage] in-app trackEvent failed:', (err as Error)?.message);
+                __DEV__ && logger.debug('[Engage] in-app trackEvent failed:', (err as Error)?.message);
             }
         },
         [engage],
@@ -827,7 +827,7 @@ export function EngagePromptProvider({
                 // Eager-flush so the backend consumes the one-shot preview row NOW — a fast
                 // close→kill→reopen must not re-serve a still-`delivered` test.
                 engage.flushEvents?.();
-                logger.debug(`[Engage] test ${runId} render displayed — ACK sent (impression), flushed`);
+                __DEV__ && logger.debug(`[Engage] test ${runId} render displayed — ACK sent (impression), flushed`);
             }
         },
         [trackInApp, engage],
@@ -838,19 +838,19 @@ export function EngagePromptProvider({
             if (current) {
                 const isTest = current.preview === true || current.isTest === true;
                 const runId = current.testRunId ?? current.previewId ?? current.id;
-                logger.debug(`[Engage] in-app ${eventType}${isTest ? ` (test ${runId})` : ''}`);
+                __DEV__ && logger.debug(`[Engage] in-app ${eventType}${isTest ? ` (test ${runId})` : ''}`);
                 trackInApp(current, eventType);
                 if (isTest) {
                     consumedPreviewIds.current.add(current.previewId ?? current.id);
                     seenTestsRef.current?.markSeen(runId);
                     engage.flushEvents?.();
-                    logger.debug(`[Engage] test ${runId} ${eventType} persisted + ACK flushed`);
+                    __DEV__ && logger.debug(`[Engage] test ${runId} ${eventType} persisted + ACK flushed`);
                 } else {
                     // Stamp the SERVED revision: without it the completion can never be invalidated,
                     // and an edited campaign would never return to a device that closed the old one.
                     storeRef.current?.markCompleted(current.id, Date.now(), current.revision);
                     engage.flushEvents?.();
-                    logger.debug(`[Engage] in-app ${current.id} ${eventType} — marked done on device`);
+                    __DEV__ && logger.debug(`[Engage] in-app ${current.id} ${eventType} — marked done on device`);
                 }
             }
             return null;
@@ -899,12 +899,12 @@ export function EngagePromptProvider({
                 consumedPreviewIds.current.add(message.previewId ?? message.id);
                 seenTestsRef.current?.markSeen(runId);
                 engage.flushEvents?.();
-                logger.debug(`[Engage] test ${runId} CTA — persisted locally + ACK flushed`);
+                __DEV__ && logger.debug(`[Engage] test ${runId} CTA — persisted locally + ACK flushed`);
             } else {
                 // Production message: a CTA tap is as final as a close — don't re-show it.
                 storeRef.current?.markCompleted(message.id, Date.now(), message.revision);
                 engage.flushEvents?.();
-                logger.debug(`[Engage] in-app ${message.id} CTA tapped — marked done on device`);
+                __DEV__ && logger.debug(`[Engage] in-app ${message.id} CTA tapped — marked done on device`);
             }
             setActiveInApp(null);
             // Any enabled click event above already read the arm; clear it now.
@@ -938,7 +938,7 @@ export function EngagePromptProvider({
             // PRECEDENCE: a campaign prompt owns the screen — defer (the backend re-serves
             // the preview on every poll until TTL, so the next foreground retries).
             if (active !== null) {
-                logger.debug('[Engage] campaign prompt active — preview deferred');
+                __DEV__ && logger.debug('[Engage] campaign prompt active — preview deferred');
                 return false;
             }
             if (activeInApp?.id === preview.id) return true;
@@ -950,12 +950,12 @@ export function EngagePromptProvider({
             // [T1] One-shot: already DISPLAYED on this device (persisted across restarts) —
             // never re-show, even if the backend briefly re-serves a not-yet-ACKed row.
             if (seenTestsRef.current?.has(runId)) {
-                logger.debug(`[Engage] test ${runId} already displayed on device — skip`);
+                __DEV__ && logger.debug(`[Engage] test ${runId} already displayed on device — skip`);
                 return false;
             }
             activeInAppVariantRef.current = null;
             setActiveInApp(preview);
-            logger.debug(`[Engage] test ${runId} render started`);
+            __DEV__ && logger.debug(`[Engage] test ${runId} render started`);
             return true;
         },
         [active, activeInApp],
@@ -968,7 +968,7 @@ export function EngagePromptProvider({
             // PRECEDENCE: a campaign prompt on screen wins — never stack an in-app
             // message over an open survey/NPS/rating prompt.
             if (active !== null) {
-                logger.debug('[Engage] campaign prompt active — in-app message deferred');
+                __DEV__ && logger.debug('[Engage] campaign prompt active — in-app message deferred');
                 return false;
             }
             try {
@@ -993,7 +993,7 @@ export function EngagePromptProvider({
                     action: options?.action,
                 });
                 if (!message) {
-                    logger.debug('[Engage] no eligible in-app message to render');
+                    __DEV__ && logger.debug('[Engage] no eligible in-app message to render');
                     return false;
                 }
 
@@ -1055,7 +1055,7 @@ export function EngagePromptProvider({
     // apps to see it. Only runs when the host opts in via `previewPollMs` (unset in prod).
     useEffect(() => {
         if (!previewPollMs || previewPollMs <= 0) return;
-        logger.debug(`[Engage] test-preview warm poll every ${previewPollMs}ms (dev)`);
+        __DEV__ && logger.debug(`[Engage] test-preview warm poll every ${previewPollMs}ms (dev)`);
         const interval = setInterval(() => {
             void checkForPreview();
         }, previewPollMs);

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;
@@ -478,7 +478,7 @@ export class EngageTransport {
                 schemaVersion: ENGAGE_SCHEMA_VERSION,
                 responses: batch,
             });
-            logger.debug(`[Engage] flushed ${batch.length} response(s)`);
+            __DEV__ && logger.debug(`[Engage] flushed ${batch.length} response(s)`);
         } catch (err) {
             if (EngageTransport._shouldRequeue(err)) this.pendingResponses.unshift(...batch);
             else logger.warn(`[Engage] dropped ${batch.length} response(s) — rejected by server`);
@@ -504,7 +504,7 @@ export class EngageTransport {
                 schemaVersion: ENGAGE_SCHEMA_VERSION,
                 events: batch,
             });
-            logger.debug(`[Engage] flushed ${batch.length} event(s)`);
+            __DEV__ && logger.debug(`[Engage] flushed ${batch.length} event(s)`);
         } catch (err) {
             if (EngageTransport._shouldRequeue(err)) this.pendingEvents.unshift(...batch);
             else logger.warn(`[Engage] dropped ${batch.length} in-app event(s) — rejected by server`);
@@ -519,7 +519,7 @@ export class EngageTransport {
                 schemaVersion: ENGAGE_SCHEMA_VERSION,
                 events: batch,
             });
-            logger.debug(`[Engage] flushed ${batch.length} rating-event(s)`);
+            __DEV__ && logger.debug(`[Engage] flushed ${batch.length} rating-event(s)`);
         } catch (err) {
             if (EngageTransport._shouldRequeue(err)) this.pendingRatingEvents.unshift(...batch);
             else logger.warn(`[Engage] dropped ${batch.length} rating-event(s) — rejected by server`);
@@ -534,7 +534,7 @@ export class EngageTransport {
                 schemaVersion: ENGAGE_SCHEMA_VERSION,
                 impressions: batch,
             });
-            logger.debug(`[Engage] flushed ${batch.length} survey impression(s)`);
+            __DEV__ && logger.debug(`[Engage] flushed ${batch.length} survey impression(s)`);
         } catch (err) {
             if (EngageTransport._shouldRequeue(err)) this.pendingSurveyImpressions.unshift(...batch);
             else logger.warn(`[Engage] dropped ${batch.length} survey impression(s) — rejected by server`);
@@ -549,7 +549,7 @@ export class EngageTransport {
         if (!registration) return;
         try {
             await this._post(ENDPOINTS.ENGAGE_DEVICE_TOKEN, registration);
-            logger.debug(`[Engage] registered device token (${registration.platform})`);
+            __DEV__ && logger.debug(`[Engage] registered device token (${registration.platform})`);
         } catch (err) {
             if (EngageTransport._shouldRequeue(err)) this.pendingTokens.unshift(registration);
             else logger.warn('[Engage] dropped a device-token registration — rejected by server');