@scalebun/react-native 1.1.0 → 1.2.1

package/src/features/session/SessionManager.ts

@@ -205,7 +205,7 @@ export class SessionManager {
      */
     setBackendTransport(transport: BackendSessionAdapter): void {
         this._backendTransport = transport;
-        logger.info('[SessionManager] Backend transport attached (replay → backend upload enabled)');
+        __DEV__ && logger.info('[SessionManager] Backend transport attached (replay → backend upload enabled)');
     }
 
     /** Expose the backend transport so features can queue network/errors/performance. */
@@ -235,7 +235,7 @@ export class SessionManager {
      */
     setDesktopTransport(debugTransport: DebugTransport): void {
         this.desktopTransport = new DesktopSessionTransport(debugTransport);
-        logger.info('[SessionManager] Desktop transport attached');
+        __DEV__ && logger.info('[SessionManager] Desktop transport attached');
     }
 
     // ─── Session Lifecycle ──────────────────────────────────────────────
@@ -278,7 +278,7 @@ export class SessionManager {
         // Hot-swap into active capture manager if session is running
         if (this.active && this.captureManager) {
             (this.captureManager as any).nativeCapture = captureFn;
-            logger.info('[SessionManager] Capture function updated (hot-swap)');
+            __DEV__ && logger.info('[SessionManager] Capture function updated (hot-swap)');
         }
     }
 
@@ -288,7 +288,7 @@ export class SessionManager {
     startSession(metadata?: Partial<SessionMetadata>): void {
         try {
             if (this.active) {
-                logger.debug('[SessionManager] Session already active, skipping start');
+                __DEV__ && logger.debug('[SessionManager] Session already active, skipping start');
                 return;
             }
 
@@ -461,12 +461,12 @@ export class SessionManager {
             // Set timeout
             if (this.config.maxDurationMs > 0) {
                 this.timeoutTimer = setTimeout(() => {
-                    logger.debug('[SessionManager] Session timeout reached');
+                    __DEV__ && logger.debug('[SessionManager] Session timeout reached');
                     this.endSession('timeout');
                 }, this.config.maxDurationMs);
             }
 
-            logger.info(`[SessionManager] Session started: ${sessionId}`);
+            __DEV__ && logger.info(`[SessionManager] Session started: ${sessionId}`);
 
             // ── Replay initial screen ──────────────────────────────────────
             // If the user was already on a screen before pressing Record
@@ -566,7 +566,7 @@ export class SessionManager {
             this.captureManager.clear();
             // (this.active already set to false above)
 
-            logger.info(
+            __DEV__ && logger.info(
                 `[SessionManager] Session ended: ${this.session.sessionId} ` +
                 `(${reason}, sync=${decision.shouldSync}, priority=${decision.priority})`,
             );
@@ -805,7 +805,7 @@ export class SessionManager {
 
                 const alreadyNormalized = this._normalizeInteractionPayload(p);
 
-                logger.debug(
+                __DEV__ && logger.debug(
                     `[TapAccuracy] sink platform=${p.platform ?? '?'} space=${p.coordinateSpace ?? '?'} ` +
                     `source=${alreadyNormalized ? (p.confidence === 'high' ? 'native-high' : 'js-precomputed') : 'js-estimated'} ` +
                     `norm=(${p.normalizedX},${p.normalizedY}) base=(${p.viewportWidth}x${p.viewportHeight})`,
@@ -963,7 +963,7 @@ export class SessionManager {
 
             this.crashAnchors.push(anchor);
 
-            logger.debug(
+            __DEV__ && logger.debug(
                 `[SessionManager] Crash anchored: ${crashEventId}, ` +
                 `protected ${anchor.nearbyEventIds.length} events, ` +
                 `${anchor.nearbyFrameIds.length} frames`,

package/src/features/session/SyncDecisionEngine.ts

@@ -71,7 +71,7 @@ export class SyncDecisionEngine {
 
             const decision = this._policy(enrichedCandidate);
 
-            logger.debug(
+            __DEV__ && logger.debug(
                 `[SyncDecisionEngine] Session ${candidate.sessionId}: ` +
                 `shouldSync=${decision.shouldSync}, priority=${decision.priority}, ` +
                 `reason="${decision.reason}"`,

package/src/features/skan/skanBridge.ts

@@ -35,27 +35,19 @@ export async function updateSkanConversionValue(
     try {
         const mod = getSkanModule();
         if (!mod?.updateConversionValue) {
-            logger.debug('[SKAN] Native module unavailable — conversion value not sent');
+            __DEV__ && logger.debug('[SKAN] Native module unavailable — conversion value not sent');
             return false;
         }
         const fine = Math.max(0, Math.min(63, Math.round(value)));
         await mod.updateConversionValue(fine, coarseValue ?? null, !!lockWindow);
-        logger.debug(`[SKAN] updateConversionValue(${fine}, ${coarseValue ?? '-'}, lock=${lockWindow})`);
+        __DEV__ && logger.debug(`[SKAN] updateConversionValue(${fine}, ${coarseValue ?? '-'}, lock=${lockWindow})`);
         return true;
     } catch (err) {
-        logger.debug(`[SKAN] updateConversionValue failed: ${(err as Error)?.message}`);
+        __DEV__ && logger.debug(`[SKAN] updateConversionValue failed: ${(err as Error)?.message}`);
         return false;
     }
 }
 
-/** Register the app's SKAdNetwork attribution at first launch (iOS 11.3+). No-op elsewhere. */
-export async function registerSkanAttribution(): Promise<void> {
-    try {
-        const mod = getSkanModule();
-        if (!mod?.registerAppForAttribution) return;
-        await mod.registerAppForAttribution();
-        logger.debug('[SKAN] registered app for attribution');
-    } catch {
-        // No-throw.
-    }
-}
+// (registerSkanAttribution was removed: nothing in the SDK or any consumer ever called it, so SKAN
+// attribution registration never actually happened. If the feature is wanted, wire it from the
+// facade's init path rather than restoring an orphaned export — see git history for the body.)

package/src/features/skan/skanConversionManager.ts

@@ -106,7 +106,7 @@ export class SkanConversionManager {
                 headers: { 'x-scalebun-client-key': this.clientKey },
             });
             if (!res.ok) {
-                logger.debug(`[SKAN] schema fetch HTTP ${res.status}`);
+                __DEV__ && logger.debug(`[SKAN] schema fetch HTTP ${res.status}`);
                 return;
             }
             const json: any = await res.json();
@@ -118,12 +118,12 @@ export class SkanConversionManager {
                 } catch {
                     /* no-throw */
                 }
-                logger.debug(
+                __DEV__ && logger.debug(
                     `[SKAN] schema loaded (enabled=${this.enabled}, ${this.schema.length} rules)`,
                 );
             }
         } catch (err) {
-            logger.debug(`[SKAN] schema fetch failed: ${(err as Error)?.message}`);
+            __DEV__ && logger.debug(`[SKAN] schema fetch failed: ${(err as Error)?.message}`);
         }
     }
 
@@ -142,12 +142,12 @@ export class SkanConversionManager {
             this.persist();
 
             void this.applyCv(rule.value, rule.coarse, rule.lockWindow ?? false);
-            logger.debug(
+            __DEV__ && logger.debug(
                 `[SKAN] event '${eventName}' → CV ${rule.value}` +
                     `${rule.coarse ? `/${rule.coarse}` : ''}${rule.lockWindow ? ' (locked)' : ''}`,
             );
         } catch (err) {
-            logger.debug(`[SKAN] onEvent('${eventName}') failed: ${(err as Error)?.message}`);
+            __DEV__ && logger.debug(`[SKAN] onEvent('${eventName}') failed: ${(err as Error)?.message}`);
         }
     }
 

package/src/integrations/fetch/fetchInterceptor.ts

@@ -177,6 +177,6 @@ export function installFetchInterceptor(
             }
         };
 
-        logger.debug('Fetch Interceptor installed');
+        __DEV__ && logger.debug('Fetch Interceptor installed');
     });
 }

package/src/integrations/xhr/xhrInterceptor.ts

@@ -226,6 +226,6 @@ export function installXHRInterceptor(
             return originalSend.apply(this, arguments as any);
         };
 
-        logger.debug('XHR Interceptor installed');
+        __DEV__ && logger.debug('XHR Interceptor installed');
     });
 }

package/src/metro/composeSourceMap.ts

@@ -0,0 +1,104 @@
+/**
+ * ScaleBun SDK — source-map composition for the pre-bundled artifact.
+ *
+ * The SDK ships as one scope-hoisted file (dist/scalebun.*.js). Metro's map therefore resolves
+ * every SDK frame to that single generated file, and Metro cannot chain the artifact's own map
+ * (no inputSourceMap support anywhere in metro-transform-worker). Left like that, a production
+ * crash inside the SDK symbolicates to one opaque file:line — for a crash-reporting SDK that is
+ * self-sabotage.
+ *
+ * This module performs the missing chain step: every mapping in the app's final map that lands in
+ * a ScaleBun artifact is re-resolved through the artifact's stage-2 map (which itself chains via
+ * bob's per-file maps back to the original TypeScript). It runs inside `withScaleBun`'s
+ * serializer wrapper, so the .map Metro writes to disk is already correct — for ScaleBun's own
+ * backend and for any third-party tool the host uploads maps to, with zero consumer action.
+ *
+ * Node-only (metro.config.js context). Never part of the app bundle.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+
+import { TraceMap, originalPositionFor } from '@jridgewell/trace-mapping';
+import { decode, encode } from '@jridgewell/sourcemap-codec';
+
+export interface ArtifactMapping {
+    /** Absolute path of the pre-bundled artifact as Metro resolved it. */
+    artifactPath: string;
+    /** Absolute path of the artifact's stage-2 source map. */
+    mapPath: string;
+}
+
+interface MutableSourceMap {
+    version: number;
+    sources: (string | null)[];
+    sourcesContent?: (string | null)[];
+    names: string[];
+    mappings: string;
+    [key: string]: unknown;
+}
+
+const normalize = (p: string): string => p.replace(/\\/g, '/');
+
+/**
+ * Rewrite `metroMap` so mappings pointing into any of `artifacts` resolve through that artifact's
+ * stage-2 map. Returns the number of rewritten segments (0 = nothing matched, map returned as-is).
+ *
+ * The input object is mutated and returned — serialization happens exactly once, in the caller.
+ */
+export function composeSourceMap(
+    metroMap: MutableSourceMap,
+    artifacts: readonly ArtifactMapping[],
+): { map: MutableSourceMap; rewritten: number } {
+    // Index of each artifact in the outer map's source list, if present at all.
+    const byIndex = new Map<number, { trace: TraceMap; mapDir: string }>();
+    for (const { artifactPath, mapPath } of artifacts) {
+        const wanted = normalize(artifactPath);
+        const idx = metroMap.sources.findIndex(s => s != null && normalize(s) === wanted);
+        if (idx < 0) continue;
+        const trace = new TraceMap(JSON.parse(fs.readFileSync(mapPath, 'utf8')));
+        byIndex.set(idx, { trace, mapDir: path.dirname(mapPath) });
+    }
+    if (byIndex.size === 0) return { map: metroMap, rewritten: 0 };
+
+    const sourcesContent = (metroMap.sourcesContent ??= []);
+    while (sourcesContent.length < metroMap.sources.length) sourcesContent.push(null);
+
+    /** stage-2 source (resolved against its map's directory) → index in the outer source list. */
+    const appended = new Map<string, number>();
+    const indexFor = (mapDir: string, source: string, content: string | null): number => {
+        // build-dist rewrites stage-2 sources to package-relative "src/…", and the maps live in
+        // <packageRoot>/dist — so resolve against the map directory's PARENT to yield
+        // "<packageRoot>/src/…" like every other absolute path in the outer map.
+        const abs = normalize(path.resolve(path.dirname(mapDir), source));
+        const hit = appended.get(abs);
+        if (hit !== undefined) return hit;
+        metroMap.sources.push(abs);
+        sourcesContent.push(content);
+        const idx = metroMap.sources.length - 1;
+        appended.set(abs, idx);
+        return idx;
+    };
+
+    const decoded = decode(metroMap.mappings);
+    let rewritten = 0;
+    for (const line of decoded) {
+        for (const seg of line) {
+            if (seg.length < 4) continue;
+            const hit = byIndex.get(seg[1]!);
+            if (!hit) continue;
+            const pos = originalPositionFor(hit.trace, { line: seg[2]! + 1, column: seg[3]! });
+            if (pos.source == null || pos.line == null) continue;
+            const srcIdx = hit.trace.resolvedSources.indexOf(pos.source);
+            const content = srcIdx >= 0 ? (hit.trace.sourcesContent?.[srcIdx] ?? null) : null;
+            seg[1] = indexFor(hit.mapDir, pos.source, content);
+            seg[2] = pos.line - 1;
+            seg[3] = pos.column;
+            // Drop the name index: it refers to the outer map's name table, which is meaningless
+            // for a position that now lives in the stage-2 map's coordinate space.
+            if (seg.length === 5) (seg as unknown as number[]).length = 4;
+            rewritten++;
+        }
+    }
+    metroMap.mappings = encode(decoded);
+    return { map: metroMap, rewritten };
+}

package/src/metro/featureModules.ts

@@ -0,0 +1,143 @@
+/**
+ * ScaleBun SDK — Build-time excludable feature registry.
+ *
+ * Metro has NO tree shaking: every module reachable from the entry point is bundled regardless of
+ * whether it is ever imported by name or ever executed. Measured on this SDK, importing a single
+ * tiny function instead of the whole facade changed the bundle by 115 bytes. So the only way a
+ * consumer can stop paying for a subsystem they do not use is to make it unreachable at RESOLUTION
+ * time, which is what `withScaleBun`'s `features` option does.
+ *
+ * Each entry lists module paths RELATIVE TO THE PACKAGE ROOT, without extension and without the
+ * `lib/module` / `lib/commonjs` / `src` prefix, so one list covers every build output.
+ *
+ * IMPORTANT: a module belongs here only if it is genuinely unreachable when the feature is off.
+ * `debug/` is the cautionary case — it also contains PRODUCTION code:
+ *   - `debug/redaction`      → redactBody / redactNetworkEvent, used by SessionManager,
+ *                              persistentQueue and both network interceptors. Removing it would
+ *                              silently disable payload redaction. It is NOT listed here.
+ *   - `debug/protocol`       → PROTOCOL_VERSION, imported as a VALUE by journeyManager and
+ *                              DesktopSessionTransport. NOT listed here.
+ *   - `debug/screenTracking` → getTrackedScreen, used by NetworkFeature. NOT listed here.
+ *   - `debug/bootstrap`      → re-exported from the package entry point. NOT listed here; it is
+ *                              instead guarded at runtime (see enableDebug).
+ */
+
+/**
+ * The desktop-debugger tooling: a WebSocket bridge to the ScaleBun desktop app, the command
+ * registry it drives, the event stream it consumes, and the profiler that only it initialises.
+ *
+ * `debug/transport` is included because every importer outside `debug/bootstrap` uses
+ * `import type`, which is erased at compile time — bootstrap is its only value consumer, and
+ * bootstrap degrades gracefully when the tooling is absent.
+ *
+ * `features/profiler/` is included because nothing outside `debug/` references ProfilerFeature.
+ */
+const DEV_TOOLS_MODULES = [
+    // Reached only from inside enableDebug(), which returns early when the tooling is absent, or
+    // through accessors that read a module-level variable left at null (`_getStream`,
+    // `_getCommands`, `_getTransport`) or optional-chain it (`_setFlushFn`, `addBreadcrumb`,
+    // `ping`, `_perf?.stop()`). None of them call into these modules directly.
+    'debug/commands',
+    'debug/stream',
+    'debug/transport',
+    'debug/perf',
+    'debug/hostResolver',
+    'debug/perfWiring',
+    'debug/sessionWiring',
+
+    // Profiler is unreachable once perfWiring is gone — nothing outside debug/ imports it.
+    'features/profiler/ProfilerFeature',
+    'features/profiler/ProfilerTransport',
+    'features/profiler/index',
+    'features/profiler/config',
+    'features/profiler/contracts',
+    'features/profiler/models',
+
+    // DELIBERATELY ABSENT, each verified by reading its callers:
+    //   debug/replayWiring  — `_getReplaySdk()` / `_isReplaySdkInitialized()` call into it
+    //                         unconditionally, outside any enable/disable guard.
+    //   debug/exportBridge  — `requestExport()` / `_handleExportResult()` likewise.
+    //   debug/configBuilder — ScaleBunFacade calls applyFeatureGatesToDebugConfig() BEFORE
+    //                         bootstrap's guard can run.
+    //   debug/metrics       — `ScaleBun.debug.sendMetric()` is public API and is NOT wrapped in
+    //                         noThrow, so a stub would throw straight into caller code.
+] as const;
+
+/**
+ * Feature name → the modules that become unreachable when it is disabled.
+ *
+ * Keep this narrow and evidence-backed. Every addition must be justified by checking who actually
+ * imports the module, distinguishing `import type` (erased) from a value import (not erased).
+ */
+export const SCALEBUN_FEATURE_MODULES: Readonly<Record<string, readonly string[]>> = {
+    /**
+     * Desktop-debugger tooling. Disabling it means `ScaleBun.init({ debugConnection })` no longer
+     * connects in that build; the SDK logs one clear warning and continues. All analytics, session,
+     * replay, crash, network and redaction behaviour is unaffected.
+     *
+     * Measured saving: 52,138 bytes of minified JavaScript in a production Android bundle.
+     */
+    devTools: DEV_TOOLS_MODULES,
+};
+
+export type ScaleBunFeatureName = keyof typeof SCALEBUN_FEATURE_MODULES;
+
+/**
+ * Per-feature default when the host's config does not mention it.
+ *
+ * `devTools` defaults to OFF: the desktop debugger it talks to is a future product — no
+ * counterpart exists yet anywhere, so today the tooling can only ever dial a socket nobody is
+ * listening on, retry, and give up. Shipping 53 KB of that in every app by default was pure waste.
+ * When the desktop app ships, hosts opt in with `features: { devTools: true }` (and the default
+ * here may flip back).
+ */
+const FEATURE_DEFAULTS: Readonly<Record<ScaleBunFeatureName, boolean>> = {
+    devTools: false,
+};
+
+/**
+ * Build the set of module suffixes to exclude for a given feature configuration.
+ *
+ * Every known feature is resolved: an explicit `true`/`false` in `features` wins, otherwise the
+ * feature's default applies. Unknown names throw — a typo here would silently ship (or silently
+ * keep) code the caller believed they had configured, so it is an error rather than a warning.
+ */
+export function resolveExcludedModules(
+    features: Readonly<Record<string, boolean | undefined>> | undefined,
+): ReadonlySet<string> {
+    for (const name of Object.keys(features ?? {})) {
+        if (!SCALEBUN_FEATURE_MODULES[name]) {
+            throw new Error(
+                `[scalebun/metro] Unknown feature "${name}". Known features: ` +
+                    `${Object.keys(SCALEBUN_FEATURE_MODULES).join(', ')}.`,
+            );
+        }
+    }
+
+    const excluded = new Set<string>();
+    for (const [name, modules] of Object.entries(SCALEBUN_FEATURE_MODULES)) {
+        const enabled = features?.[name] ?? FEATURE_DEFAULTS[name as ScaleBunFeatureName] ?? true;
+        if (enabled) continue;
+        for (const m of modules) excluded.add(m);
+    }
+    return excluded;
+}
+
+/**
+ * Does `filePath` correspond to one of the excluded module paths?
+ *
+ * Matches against the tail of the path so a single registry entry covers `lib/module/…​.js`,
+ * `lib/commonjs/…​.js` and `src/…​.ts`. Callers MUST have already confirmed the file lives inside
+ * the ScaleBun package — matching on the tail alone would also match a host application's own
+ * `debug/commands.js`, which must never be stubbed.
+ */
+export function isExcludedModule(filePath: string, excluded: ReadonlySet<string>): boolean {
+    if (excluded.size === 0) return false;
+    const normalized = filePath.replace(/\\/g, '/');
+    // Drop the extension so 'debug/commands' matches commands.js, commands.ts and commands.tsx.
+    const withoutExt = normalized.replace(/\.[cm]?[jt]sx?$/, '');
+    for (const suffix of excluded) {
+        if (withoutExt.endsWith('/' + suffix)) return true;
+    }
+    return false;
+}

package/src/metro/index.ts

@@ -25,7 +25,17 @@
  *   otherwise the original resolution error is rethrown.
  */
 
+import * as nodePath from 'path';
+import * as nodeFs from 'fs';
+
 import { SCALEBUN_OPTIONAL_MODULES } from './optionalModules';
+import { isExcludedModule, resolveExcludedModules } from './featureModules';
+import {
+    createComposingSerializer,
+    discoverArtifacts,
+    resolveMetroInternals,
+    type MetroSerializer,
+} from './serializerCompose';
 
 // Minimal structural types for the slice of Metro's resolver API we touch. We
 // avoid a hard dependency on `metro`/`metro-resolver` types so the helper builds
@@ -74,6 +84,29 @@ export interface WithScaleBunOptions {
      * installing — never to silence unrelated missing modules.
      */
     optionalModules?: readonly string[];
+
+    /**
+     * Per-subsystem bundling switches. Metro performs no tree shaking, so a subsystem you never
+     * call is still bundled in full; resolution-time exclusion is the only mechanism that removes
+     * it. See ./featureModules for the module list behind each name and, importantly, for what
+     * deliberately stays (redaction, protocol constants and screen tracking live under `debug/`
+     * but are production code).
+     *
+     * | feature    | contents                              | default | measured cost |
+     * |------------|---------------------------------------|---------|---------------|
+     * | `devTools` | desktop-debugger bridge + profiler    | OFF     | ~53 KB        |
+     *
+     * `devTools` is OFF by default because the ScaleBun desktop debugger is a future product —
+     * no counterpart exists yet, so the tooling can only dial a socket nobody is listening on.
+     * When the desktop app ships, opt in with:
+     *
+     *     withScaleBun(config, { features: { devTools: true } })
+     *
+     * In a devTools-excluded bundle, `ScaleBun.init({ debugConnection })` logs one clear warning
+     * and continues; every production feature (analytics, sessions, replay, crash, network
+     * capture, redaction, Engage, OTA, push) is unaffected — verified by differential test.
+     */
+    features?: Readonly<Record<string, boolean | undefined>>;
 }
 
 /**
@@ -95,6 +128,56 @@ function resolveStubPath(): string {
     }
 }
 
+/**
+ * Absolute path to this package's root, found by walking up from this file until a package.json
+ * naming this package appears.
+ *
+ * Computed by search rather than a fixed number of `..` segments because this module is emitted to
+ * different depths (`lib/commonjs/metro/` when published, `src/metro/` under ts-jest), and a
+ * hard-coded depth would silently resolve to the wrong directory in one of them.
+ *
+ * Returns null if the root cannot be identified, in which case feature exclusion is skipped
+ * entirely — stubbing on a tail match alone could hit a host application's own files.
+ */
+function findPackageRoot(): string | null {
+    let dir = __dirname;
+    for (let i = 0; i < 10; i++) {
+        try {
+            const manifest = nodePath.join(dir, 'package.json');
+            if (nodeFs.existsSync(manifest)) {
+                const name = JSON.parse(nodeFs.readFileSync(manifest, 'utf8'))?.name;
+                if (name === '@scalebun/react-native') return nodeFs.realpathSync(dir);
+            }
+        } catch {
+            // Unreadable/malformed manifest — keep walking rather than failing the whole build.
+        }
+        const parent = nodePath.dirname(dir);
+        if (parent === dir) break;
+        dir = parent;
+    }
+    return null;
+}
+
+/**
+ * Is `filePath` inside this package?
+ *
+ * Both sides are realpath'd because pnpm and npm workspaces symlink the package into
+ * `node_modules`, so Metro can hand back a path through the symlink while the package root was
+ * discovered through the store — a plain prefix comparison would then miss and quietly disable
+ * exclusion. Falls back to the raw path when realpath fails (file may not exist yet).
+ */
+function isInsidePackage(filePath: string, packageRoot: string): boolean {
+    let real = filePath;
+    try {
+        real = nodeFs.realpathSync(filePath);
+    } catch {
+        // Keep the original path; the relative check below still gives a correct answer for
+        // anything that genuinely lives under the package root.
+    }
+    const rel = nodePath.relative(packageRoot, real);
+    return rel !== '' && !rel.startsWith('..') && !nodePath.isAbsolute(rel);
+}
+
 /**
  * Wrap a Metro configuration so the SDK's optional integration packages resolve
  * to an empty stub when they are not installed.
@@ -120,6 +203,36 @@ export function withScaleBun<T extends MetroConfigLike>(
         ...(options.optionalModules ?? []),
     ]);
 
+    // Throws on an unknown feature name, at config load, rather than silently shipping code the
+    // caller believed they had excluded.
+    const excludedModules = resolveExcludedModules(options.features);
+    const packageRoot = findPackageRoot();
+
+    if (excludedModules.size > 0 && packageRoot == null) {
+        throw new Error(
+            '[scalebun/metro] features were requested but the @scalebun/react-native package root ' +
+                'could not be located from ' +
+                __dirname +
+                '. Refusing to exclude modules by path suffix alone, because that could stub files ' +
+                "belonging to your own app. Reinstall the package, or drop the `features` option.",
+        );
+    }
+
+    // The pre-bundled artifacts. Package exports resolve "@scalebun/react-native" to the slim one;
+    // `features: { devTools: true }` redirects to the full one below. When the package was built
+    // without dist/ (working from raw source), both lists are empty and every dist-dependent
+    // behaviour degrades to the per-file lib/ path.
+    const artifacts = packageRoot ? discoverArtifacts(packageRoot) : [];
+    const fullArtifact = artifacts.find(a => a.artifactPath.endsWith('scalebun.full.js'));
+    const wantsDevTools = options.features?.devTools === true;
+
+    if (wantsDevTools && artifacts.length > 0 && !fullArtifact) {
+        throw new Error(
+            '[scalebun/metro] features.devTools is true but dist/scalebun.full.js is missing from ' +
+                'the installed package. Reinstall @scalebun/react-native.',
+        );
+    }
+
     // Preserve a host-provided resolver so aliases, monorepo/PnP, SVG, NativeWind,
     // Storybook, Expo, etc. keep working. We call it first and only add a fallback.
     const hostResolveRequest = config.resolver?.resolveRequest;
@@ -137,8 +250,16 @@ export function withScaleBun<T extends MetroConfigLike>(
             );
         }
 
+        // devTools opt-in: the package's exports point at the slim artifact, so the full one is
+        // reachable only through this redirect. Matching the bare specifier is safe here — it is
+        // the package's own name, which nothing else can legitimately claim.
+        if (wantsDevTools && fullArtifact && moduleName === '@scalebun/react-native') {
+            return { type: 'sourceFile', filePath: fullArtifact.artifactPath };
+        }
+
+        let resolution: MetroResolution;
         try {
-            return baseResolve(context, moduleName, platform);
+            resolution = baseResolve(context, moduleName, platform);
         } catch (error) {
             if (optionalModules.has(moduleName)) {
                 // Known ScaleBun optional integration, not installed → empty stub.
@@ -147,14 +268,65 @@ export function withScaleBun<T extends MetroConfigLike>(
             // Unrelated module: preserve Metro's original failure exactly.
             throw error;
         }
+
+        // Feature exclusion is decided on the RESOLVED path, never on the request string: one
+        // module is reached through many different relative specifiers, and only a resolved path
+        // can be confirmed to live inside this package. That containment check is the safety
+        // property — a tail match alone would also stub a host app's own `debug/commands.js`.
+        if (
+            packageRoot != null &&
+            resolution != null &&
+            resolution.type === 'sourceFile' &&
+            typeof resolution.filePath === 'string' &&
+            isInsidePackage(resolution.filePath, packageRoot) &&
+            isExcludedModule(resolution.filePath, excludedModules)
+        ) {
+            return { type: 'sourceFile', filePath: stubPath };
+        }
+
+        return resolution;
     };
 
+    // ── Source-map composition (symbolication correct by default) ───────────────────────────
+    // The pre-bundled artifact collapses SDK frames to one generated file in Metro's map, and
+    // Metro cannot chain input maps. Wrapping the serializer here means the .map every consumer
+    // build writes already resolves SDK frames to original TypeScript — wherever it is uploaded.
+    let serializerConfig = (config as { serializer?: { customSerializer?: unknown } }).serializer;
+    if (artifacts.length > 0) {
+        // Anchor metro resolution at the app: its projectRoot when the config carries one, else
+        // the bundling process's cwd (react-native CLI runs from the app root).
+        const projectRoot = (config as { projectRoot?: unknown }).projectRoot;
+        const internals = resolveMetroInternals([
+            ...(typeof projectRoot === 'string' ? [projectRoot] : []),
+            process.cwd(),
+        ]);
+        if (internals == null) {
+            // eslint-disable-next-line no-console
+            console.warn(
+                '[scalebun/metro] Could not load Metro serialization internals from this Metro ' +
+                    "version, so ScaleBun's source-map composition is disabled. Builds work, but " +
+                    'SDK stack frames will symbolicate to the bundled artifact instead of original ' +
+                    'sources. Please report your Metro version to ScaleBun.',
+            );
+        } else {
+            serializerConfig = {
+                ...serializerConfig,
+                customSerializer: createComposingSerializer(
+                    artifacts,
+                    internals,
+                    serializerConfig?.customSerializer as MetroSerializer | undefined,
+                ),
+            };
+        }
+    }
+
     return {
         ...config,
         resolver: {
             ...config.resolver,
             resolveRequest,
         },
+        ...(serializerConfig !== undefined ? { serializer: serializerConfig } : {}),
     };
 }