@scalebun-release/react-native 2.5.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

@@ -0,0 +1,336 @@
+/**
+ * ScaleBun SDK — Metro configuration helper.
+ *
+ * PURPOSE
+ * The SDK integrates OPTIONALLY with a few third-party packages (screenshots,
+ * Notifee, Expo Router). Each is loaded through a guarded lazy `require()` at
+ * runtime, but Metro statically resolves every literal `require('<name>')` at
+ * BUNDLE time — before the runtime `try/catch` runs — so a host that does not
+ * install one of these packages fails to bundle with:
+ *
+ *     Unable to resolve module <name>
+ *
+ * `withScaleBun` wraps a host's Metro config so that, ONLY for ScaleBun's own
+ * optional integration packages, a failed resolution falls back to an empty
+ * stub module shipped inside the SDK. Everything else resolves exactly as before
+ * and unrelated missing modules still fail normally.
+ *
+ * This entry point is deliberately Node-only: it imports no React Native, no
+ * native modules, and no SDK runtime code, so it is safe to `require()` from a
+ * CommonJS `metro.config.js`.
+ *
+ * Resolution order for every request:
+ *   host's custom resolveRequest (if any) → Metro's default resolver →
+ *   on failure, if the name is a known ScaleBun optional module → empty stub;
+ *   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
+// even in hosts that don't expose them, while staying accurate for Metro >=0.64.
+
+export interface MetroSourceFileResolution {
+    type: 'sourceFile';
+    filePath: string;
+}
+
+export type MetroResolution =
+    | MetroSourceFileResolution
+    | { type: 'empty' }
+    | { type: 'assetFiles'; filePaths: readonly string[] };
+
+export interface MetroResolutionContext {
+    /**
+     * Metro's DEFAULT resolver. Metro guarantees this is present inside a custom
+     * `resolveRequest` and that it is NOT the custom resolver itself, so calling
+     * it cannot recurse back into `withScaleBun`.
+     */
+    resolveRequest: MetroResolver;
+    [key: string]: unknown;
+}
+
+export type MetroResolver = (
+    context: MetroResolutionContext,
+    moduleName: string,
+    platform: string | null,
+) => MetroResolution;
+
+export interface MetroResolverConfig {
+    resolveRequest?: MetroResolver;
+    [key: string]: unknown;
+}
+
+export interface MetroConfigLike {
+    resolver?: MetroResolverConfig;
+    [key: string]: unknown;
+}
+
+export interface WithScaleBunOptions {
+    /**
+     * Extra optional module names to stub when absent, merged with the built-in
+     * ScaleBun list. Use only for ScaleBun integrations you knowingly opt out of
+     * 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>>;
+}
+
+/**
+ * Absolute path to the shipped empty stub. Resolved once at load. `require.resolve`
+ * is portable across the compiled package (`optionalDependencyStub.js` sibling)
+ * and the ts-jest test runtime (`.ts` sibling). If it throws, the package is
+ * packed incorrectly and we surface a clear, actionable error immediately.
+ */
+function resolveStubPath(): string {
+    try {
+        return require.resolve('./optionalDependencyStub');
+    } catch (cause) {
+        throw new Error(
+            '[scalebun/metro] Could not locate the optional-dependency stub ' +
+                '(optionalDependencyStub). The @scalebun/react-native package may be ' +
+                'installed incorrectly or incomplete — try reinstalling it.',
+            { cause },
+        );
+    }
+}
+
+/**
+ * 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.
+ *
+ * @param config  A Metro config (typically the result of `mergeConfig(...)`).
+ * @param options Optional extra module names to treat as ScaleBun-optional.
+ * @returns A NEW config object; the input and its `resolver` are not mutated.
+ */
+export function withScaleBun<T extends MetroConfigLike>(
+    config: T,
+    options: WithScaleBunOptions = {},
+): T & { resolver: MetroResolverConfig } {
+    if (config == null || typeof config !== 'object') {
+        throw new Error(
+            '[scalebun/metro] withScaleBun(config) expects a Metro config object. ' +
+                'Pass it the result of mergeConfig(getDefaultConfig(__dirname), {}).',
+        );
+    }
+
+    const stubPath = resolveStubPath();
+    const optionalModules = new Set<string>([
+        ...SCALEBUN_OPTIONAL_MODULES,
+        ...(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;
+
+    const resolveRequest: MetroResolver = (context, moduleName, platform) => {
+        // Prefer the host resolver; otherwise Metro's default (always on context).
+        const baseResolve = hostResolveRequest ?? context.resolveRequest;
+
+        if (typeof baseResolve !== 'function') {
+            throw new Error(
+                '[scalebun/metro] This Metro version does not expose a resolver ' +
+                    "callback on the resolution context. withScaleBun requires Metro's " +
+                    'custom `resolver.resolveRequest` API (Metro >= 0.64, React Native ' +
+                    '>= 0.64). Upgrade Metro/React Native or remove withScaleBun.',
+            );
+        }
+
+        // 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 {
+            resolution = baseResolve(context, moduleName, platform);
+        } catch (error) {
+            if (optionalModules.has(moduleName)) {
+                // Known ScaleBun optional integration, not installed → empty stub.
+                return { type: 'sourceFile', filePath: stubPath };
+            }
+            // 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 } : {}),
+    };
+}
+
+export { SCALEBUN_OPTIONAL_MODULES } from './optionalModules';
+export type { ScaleBunOptionalModule } from './optionalModules';
+
+export default withScaleBun;

package/src/metro/optionalDependencyStub.ts

@@ -0,0 +1,13 @@
+/**
+ * ScaleBun SDK — Empty stand-in for an ABSENT optional integration package.
+ *
+ * When `withScaleBun` detects that one of the SDK's optional integration
+ * packages (see ./optionalModules) is not installed, it points Metro at this
+ * file so bundling succeeds. The module intentionally exports nothing: every
+ * optional loader validates the real API shape it needs (e.g. `captureRef`,
+ * `createChannel`, `usePathname`), so an empty object reads as "integration
+ * unavailable" rather than a false positive.
+ *
+ * Do NOT add exports here. It must never look like a real installed package.
+ */
+export {};

package/src/metro/optionalModules.ts

@@ -0,0 +1,27 @@
+/**
+ * ScaleBun SDK — Optional integration module registry.
+ *
+ * Single source of truth for the third-party packages the SDK integrates with
+ * OPTIONALLY. Each is loaded through a guarded, lazy `require()` at runtime, so a
+ * host that does not use the integration never needs the package at runtime.
+ *
+ * Metro, however, statically resolves every literal `require('<name>')` string at
+ * bundle time — BEFORE the runtime `try/catch` can execute — so an uninstalled
+ * package fails the bundle with "Unable to resolve module <name>". `withScaleBun`
+ * (see ./index) stubs exactly these names when they are absent so bundling
+ * succeeds while the integration stays disabled. See FIX_PUSH_UNKNOWN_MODULE.md.
+ *
+ * IMPORTANT: keep this list narrow. Only ScaleBun's own optional integrations
+ * belong here. Never add a package the SDK does not knowingly `require()`, so an
+ * unrelated missing module still fails resolution normally.
+ */
+export const SCALEBUN_OPTIONAL_MODULES = [
+    // Screenshot capture for the journey/replay screenshot helper.
+    'react-native-view-shot',
+    // Notifee notification-channel integration in the FCM push adapter.
+    '@notifee/react-native',
+    // Expo Router navigation-mode detection.
+    'expo-router',
+] as const;
+
+export type ScaleBunOptionalModule = (typeof SCALEBUN_OPTIONAL_MODULES)[number];