@scalebun/react-native 1.1.0 → 1.2.0

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 } : {}),
     };
 }
 

package/src/metro/serializerCompose.ts

@@ -0,0 +1,157 @@
+/**
+ * ScaleBun SDK — Metro serializer wrapper that emits a COMPOSED source map.
+ *
+ * Attached by `withScaleBun`. Reproduces Metro's default serialization (the exact calls
+ * Server.js makes when no custom serializer is configured), then rewrites every mapping that
+ * lands in a ScaleBun pre-bundled artifact through that artifact's stage-2 map, so the .map the
+ * build writes resolves SDK frames to original TypeScript — by default, for every consumer.
+ *
+ * Cooperation with a host-configured serializer: the host runs first and its code output is
+ * respected verbatim. If it returned its own map, that map is composed; if it returned only a
+ * string, the map is built from the graph exactly as Metro itself would have, then composed —
+ * either way the host loses nothing and gains correct SDK frames.
+ *
+ * Metro's serialization internals are reached through the "./private/*" exports alias
+ * (Metro >= 0.80.6) with a fallback to the bare "./src/*" paths older versions expose. If
+ * neither resolves, the wrapper is NOT attached and one warning explains what degrades —
+ * bundling must never fail because symbolication couldn't be improved.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+
+import { composeSourceMap, type ArtifactMapping } from './composeSourceMap';
+
+// ─── Minimal structural types for the slice of Metro's serializer API we touch ─────────────────
+
+type MetroModule = { path: string };
+
+export interface MetroSerializerOptions {
+    createModuleId: (filePath: string) => number;
+    excludeSource?: boolean;
+    processModuleFilter?: (module: MetroModule) => boolean;
+    shouldAddToIgnoreList?: (module: MetroModule) => boolean;
+    getSourceUrl?: (module: MetroModule) => string;
+    [key: string]: unknown;
+}
+
+export type MetroSerializerResult = string | { code: string; map: string };
+
+export type MetroSerializer = (
+    entryPoint: string,
+    preModules: readonly MetroModule[],
+    graph: { dependencies: Map<string, MetroModule> },
+    options: MetroSerializerOptions,
+) => MetroSerializerResult | Promise<MetroSerializerResult>;
+
+interface MetroInternals {
+    baseJSBundle: (
+        entryPoint: string,
+        preModules: readonly MetroModule[],
+        graph: { dependencies: Map<string, MetroModule> },
+        options: MetroSerializerOptions,
+    ) => unknown;
+    bundleToString: (bundle: unknown) => { code: string };
+    sourceMapObject: (modules: readonly MetroModule[], options: object) => object;
+}
+
+/**
+ * Resolve Metro's serialization helpers from the HOST's Metro install. Returns null when they
+ * cannot be found (exotic Metro version/layout) — callers must degrade gracefully.
+ *
+ * Resolution is anchored at the APP (project root / cwd), never at this package's own location:
+ * `metro` is not a dependency of the SDK, so under pnpm's strict layout a bare require from here
+ * finds nothing — and even where it would resolve, the app's Metro is the one whose serializer
+ * contract must be matched, not whichever copy happens to sit near the SDK.
+ */
+export function resolveMetroInternals(searchPaths: readonly string[]): MetroInternals | null {
+    const paths = [...searchPaths.filter(Boolean)];
+    const req = (spec: string): unknown => require(require.resolve(spec, { paths }));
+    for (const prefix of ['metro/private', 'metro/src']) {
+        try {
+            const base = req(`${prefix}/DeltaBundler/Serializers/baseJSBundle`) as {
+                default?: unknown;
+            };
+            const bts = req(`${prefix}/lib/bundleToString`) as { default?: unknown };
+            const smo = req(`${prefix}/DeltaBundler/Serializers/sourceMapObject`) as {
+                sourceMapObject?: unknown;
+                default?: unknown;
+            };
+            const baseJSBundle = base.default ?? base;
+            const bundleToString = bts.default ?? bts;
+            const sourceMapObject = smo.sourceMapObject ?? smo.default ?? smo;
+            if (
+                typeof baseJSBundle === 'function' &&
+                typeof bundleToString === 'function' &&
+                typeof sourceMapObject === 'function'
+            ) {
+                return { baseJSBundle, bundleToString, sourceMapObject } as MetroInternals;
+            }
+        } catch {
+            // try the next prefix
+        }
+    }
+    return null;
+}
+
+/** The artifacts a package root can contain, with existence checked once at config time. */
+export function discoverArtifacts(packageRoot: string): ArtifactMapping[] {
+    const out: ArtifactMapping[] = [];
+    for (const name of ['scalebun.slim.js', 'scalebun.full.js']) {
+        const artifactPath = path.join(packageRoot, 'dist', name);
+        const mapPath = artifactPath + '.map';
+        if (fs.existsSync(artifactPath) && fs.existsSync(mapPath)) {
+            out.push({ artifactPath, mapPath });
+        }
+    }
+    return out;
+}
+
+/**
+ * Build the composing serializer. `hostSerializer` is the app's own customSerializer, if any.
+ */
+export function createComposingSerializer(
+    artifacts: readonly ArtifactMapping[],
+    internals: MetroInternals,
+    hostSerializer: MetroSerializer | undefined,
+): MetroSerializer {
+    return async (entryPoint, preModules, graph, options) => {
+        let code: string;
+        let mapObj: object | null = null;
+
+        if (hostSerializer) {
+            const hostResult = await hostSerializer(entryPoint, preModules, graph, options);
+            if (typeof hostResult === 'string') {
+                code = hostResult;
+            } else {
+                code = hostResult.code;
+                try {
+                    mapObj = JSON.parse(hostResult.map);
+                } catch {
+                    // Host emitted an unparsable map; fall through and rebuild from the graph so
+                    // the build still succeeds with a correct map rather than failing here.
+                    mapObj = null;
+                }
+            }
+        } else {
+            code = internals.bundleToString(
+                internals.baseJSBundle(entryPoint, preModules, graph, options),
+            ).code;
+        }
+
+        if (mapObj == null) {
+            // Metro's own fallback, replicated: modules sorted by module id, same options.
+            const modules = [...graph.dependencies.values()].sort(
+                (a, b) => options.createModuleId(a.path) - options.createModuleId(b.path),
+            );
+            mapObj = internals.sourceMapObject([...preModules, ...modules], {
+                excludeSource: options.excludeSource,
+                processModuleFilter: options.processModuleFilter,
+                shouldAddToIgnoreList: options.shouldAddToIgnoreList,
+                getSourceUrl: options.getSourceUrl,
+            });
+        }
+
+        const { map } = composeSourceMap(mapObj as never, artifacts);
+        return { code, map: JSON.stringify(map) };
+    };
+}

package/src/pipeline/dispatcher/dispatcher.ts

@@ -11,7 +11,7 @@ export class Dispatcher {
 
         try {
             await this.transport(batch);
-            logger.info(`Successfully dispatched batch of ${batch.length} events`);
+            __DEV__ && logger.info(`Successfully dispatched batch of ${batch.length} events`);
         } catch (err) {
             logger.error('Failed to dispatch batch, returning to queue', err);
             // Re-queue items on failure

package/src/pipeline/queue/flushQueue.ts

@@ -34,7 +34,7 @@ export async function flushQueue(
     headers?: Record<string, string>,
 ): Promise<FlushResult> {
     if (inFlight.has(queue)) {
-        logger.debug('[Flush] Skipped — a flush is already in progress');
+        __DEV__ && logger.debug('[Flush] Skipped — a flush is already in progress');
         return { status: 'skipped', batchSize: 0 };
     }
 
@@ -77,7 +77,7 @@ export async function flushQueue(
         }
 
         failureStreak.delete(queue);
-        logger.info(`Successfully flushed ${batch.length} events`);
+        __DEV__ && logger.info(`Successfully flushed ${batch.length} events`);
         return { status: 'flushed', batchSize: batch.length };
     } catch (err) {
         if (isRecoverableFlushError(err)) {