sootsim 0.1.83 → 0.1.84

package/src/vite-plugin.ts

@@ -0,0 +1,1381 @@
+// sootsim vite plugin — use in any vite project to get react-native resolution,
+// native dep stubbing, and external app support.
+//
+// usage:
+//   import { sootsim } from 'sootsim/vite'
+//   export default defineConfig({ plugins: [sootsim()] })
+//
+//   // with external app:
+//   export default defineConfig({ plugins: [sootsim({ app: '~/my-rn-app' })] })
+
+import fs from 'fs'
+import { createRequire } from 'module'
+import path from 'path'
+import { fileURLToPath } from 'url'
+import { type Plugin, transformWithOxc } from 'vite'
+import {
+  SOOTSIM_COMPAT_WRAPPER_REAL_PACKAGES,
+  SOOTSIM_HAPTIC_FEEDBACK_TOUCHABLE_SOURCE,
+  SOOTSIM_HAPTIC_FEEDBACK_TOUCHABLE_SPECIFIER,
+  compatStubsForBuildResolver,
+  reactNativeDeepStubsForBuildResolver,
+} from '../../compat/src/stub-manifest.ts'
+import { DEFAULT_SOOTSIM_BRIDGE_PORT } from './bridge-constants.ts'
+import { shouldApplyWorkletsPlugin, transformWorkletsCode } from './worklets-babel.ts'
+
+const sootsimPluginRequire = createRequire(import.meta.url)
+
+export interface SootOptions {
+  // directory of an external RN app to load
+  app?: string
+  // additional source directories to treat as app sources (metro transforms apply)
+  sources?: string[]
+  // additional packages that must resolve from the host project, not the external app
+  ownedPackages?: string[]
+}
+
+// derive sootsim's root from this file's location (src/vite-plugin.ts → ..)
+const sootsimRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const workspaceRoot = path.resolve(sootsimRoot, '..', '..')
+const workspaceNodeModules = path.resolve(workspaceRoot, 'node_modules')
+const workspaceTamaguiDir = path.resolve(workspaceNodeModules, '@tamagui')
+// stubs and the mutable React bridge live in @soot/compat.
+const compatRoot = path.resolve(sootsimRoot, '..', 'compat')
+
+// the rendering engine and its shims live in the private sootsim-engine
+// workspace package. resolve via workspace root rather than relative hops so
+// renames of either package don't break things.
+const engineRoot = path.resolve(workspaceRoot, 'packages/sootsim-engine')
+const rnShimPath = path.resolve(engineRoot, 'src/react-native/index.ts')
+const reactBridgePath = path.resolve(compatRoot, 'src/react-bridge.ts')
+const sootsimBrowserSourceAliases = [
+  {
+    find: 'sootsim/backend-origin',
+    replacement: path.resolve(sootsimRoot, 'src/backend-origin.ts'),
+  },
+  {
+    find: 'sootsim/bridge-constants',
+    replacement: path.resolve(sootsimRoot, 'src/bridge-constants.ts'),
+  },
+  {
+    find: 'sootsim/dev-bundle-resolution',
+    replacement: path.resolve(sootsimRoot, 'src/dev-bundle-resolution.ts'),
+  },
+]
+
+const compatStubsDir = path.resolve(compatRoot, 'src/stubs')
+const nativeAutoStubPath = path.resolve(compatStubsDir, 'native-auto-stub.ts')
+const rnDeepStubDefault = path.resolve(compatStubsDir, 'react-native-internals.ts')
+
+function getInternalTamaguiPackages(): string[] {
+  try {
+    const scoped = fs
+      .readdirSync(workspaceTamaguiDir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => `@tamagui/${entry.name}`)
+
+    return ['tamagui', ...scoped].sort()
+  } catch {
+    return ['tamagui']
+  }
+}
+
+const internalTamaguiPackages = getInternalTamaguiPackages()
+
+const vitePackageStubs = compatStubsForBuildResolver('vite')
+const viteReactNativeDeepStubs = reactNativeDeepStubsForBuildResolver('vite')
+const builtinStubs = Object.fromEntries(
+  vitePackageStubs.map((entry) => [entry.specifier, entry.stubFile]),
+)
+const rnLibraryStubs = Object.fromEntries(
+  viteReactNativeDeepStubs.map((entry) => [
+    entry.specifier,
+    path.resolve(compatStubsDir, entry.stubFile),
+  ]),
+)
+
+// resolve the real @react-navigation/native location at config time so the
+// wrapper at compat/src/stubs/react-navigation-native.tsx can import it
+// without bouncing back through the alias above. the wrapper imports from
+// the synthetic specifier `@sootsim-internal/react-navigation-native-real`
+// which is aliased to this absolute path; rolldown follows the path
+// terminally so its `export *` static analysis sees the real export
+// surface.
+const reactNavigationNativeRealPath = (() => {
+  try {
+    return sootsimPluginRequire.resolve('@react-navigation/native')
+  } catch {
+    return null
+  }
+})()
+
+const reactNativeHapticFeedbackTouchablePath = (() => {
+  try {
+    return path.join(
+      path.dirname(
+        sootsimPluginRequire.resolve('react-native-haptic-feedback/package.json'),
+      ),
+      SOOTSIM_HAPTIC_FEEDBACK_TOUCHABLE_SOURCE,
+    )
+  } catch {
+    return null
+  }
+})()
+
+const compatWrapperRealPackageAliases: Array<{
+  find: string
+  replacement: string
+}> = []
+for (const { specifier, packageName } of Object.values(
+  SOOTSIM_COMPAT_WRAPPER_REAL_PACKAGES,
+)) {
+  try {
+    compatWrapperRealPackageAliases.push({
+      find: specifier,
+      replacement: sootsimPluginRequire.resolve(packageName),
+    })
+  } catch {}
+}
+
+// packages that must always resolve from sootsim to ensure single instances
+// across the renderer/runtime itself. keep this list minimal for external apps.
+const coreOwnedPackages = [
+  'react',
+  'react-dom',
+  'react-reconciler',
+  'react/jsx-runtime',
+  'react/jsx-dev-runtime',
+  'canvaskit-wasm',
+  'canvaskit-wasm/full',
+  'yoga-layout',
+]
+
+const nativePackagePatterns = [
+  /^expo-/,
+  /^react-native-/,
+  /^@react-native\//,
+  /^@react-native-community\//,
+  /^@expo\//,
+  /^expo$/,
+]
+
+function getPackageName(source: string): string {
+  return source.startsWith('@')
+    ? source.split('/').slice(0, 2).join('/')
+    : source.split('/')[0]
+}
+
+function isNativePackage(source: string): boolean {
+  return nativePackagePatterns.some((p) => p.test(source))
+}
+
+function moduleExistsIn(pkgName: string, dir: string): boolean {
+  try {
+    return fs.existsSync(path.join(dir, 'node_modules', pkgName))
+  } catch {
+    return false
+  }
+}
+
+export function sootsim(options: SootOptions = {}): Plugin[] {
+  const appDir = options.app ? path.resolve(options.app) : ''
+  const extraSources = (options.sources || []).map((s) => path.resolve(s))
+  const ownedPackages = new Set([...coreOwnedPackages, ...(options.ownedPackages || [])])
+
+  function isAppSource(filePath: string): boolean {
+    // exclude node_modules — only actual app source files
+    if (filePath.includes('/node_modules/')) return false
+    if (appDir && filePath.startsWith(appDir)) return true
+    return extraSources.some((s) => filePath.startsWith(s))
+  }
+
+  return [
+    wsBridgePlugin(),
+    reactBridgePlugin(),
+    sootsimConfigPlugin(appDir, extraSources),
+    fixJsxRuntimeExports(),
+    flowStripTransform(),
+    nodeModulesJsxTransform(),
+    // must run before metroNativeResolve — that plugin resolves relative
+    // imports like `./bindings` to absolute file paths via the platform-
+    // extension lookup, and once it returns a resolved id, downstream
+    // resolveId hooks don't see the source string anymore.
+    keyboardControllerBindingsRedirect(),
+    reanimatedNativeSeamRedirect(),
+    manifestNativeSeamRedirect(),
+    workletsBabelTransform(isAppSource),
+    metroNativeResolve(isAppSource),
+    reactNativeRequirePlugin(isAppSource),
+    externalAppResolvePlugin(appDir, isAppSource, ownedPackages),
+    externalAppTransformPlugin(isAppSource),
+    stubMissingNativeDeps(appDir),
+    stubMissingImages(isAppSource),
+  ]
+}
+
+// shared worker plugin chain for the engine's shell-host build (used by
+// both `vite.config.ts` for dev/watch and `vite.build.config.ts` for prod).
+// keep these here — duplicating the list inline drifts (which is exactly how
+// the prod shell worker shipped without `reanimatedNativeSeamRedirect` and
+// threw "Native part of Reanimated doesn't seem to be initialized" until
+// 2e6a8450).
+//
+// shell-host.ts spawns shell-worker.ts via Vite's declarative
+// `new Worker(new URL(...))` pattern, so shell-worker is a worker chunk of
+// the engine build. apply react-bridge / jsx-runtime fixes plus the
+// reanimated/keyboard-controller native-seam redirects so upstream's
+// reanimated wires up our turbomodule + globals inside the worker too.
+// without these, worker bundles see upstream's original
+// `NativeReanimatedModule.ts`, `TurboModuleRegistry.get('ReanimatedModule')`
+// returns null on web/sootsim, `__reanimatedModuleProxy` never gets set,
+// and the NativeReanimated constructor throws on shell-worker mount.
+//
+// workletsBabelTransform populates `__closure` on user-code worklets so
+// useAnimatedStyle/useDerivedValue/etc. subscribe correctly inside the
+// worker. matching is content-driven today, so the predicate is `() => true`.
+export function engineShellWorkerPlugins(): Plugin[] {
+  return [
+    workerReactBridgePlugin(),
+    fixJsxRuntimeExports(),
+    reanimatedNativeSeamRedirect(),
+    manifestNativeSeamRedirect(),
+    keyboardControllerBindingsRedirect(),
+    workletsBabelTransform(() => true),
+  ]
+}
+
+// react-native-keyboard-controller is pure-JS for everything except its
+// native-event seam (`bindings.ts` / `bindings.native.ts`) and RN platform
+// `findNodeHandle` resolution. let upstream's components, hooks, animated
+// module, and KeyboardAvoidingView resolve from node_modules unchanged, and
+// redirect only those native/platform seams.
+//
+// the redirect runs `enforce: 'pre'` so it sees `./bindings` / `../bindings`
+// / `../../bindings` strings before vite's native resolver collapses them to
+// absolute paths. matches by importer path (must be inside upstream's
+// node_modules root) and source basename.
+export function keyboardControllerBindingsRedirect(): Plugin {
+  const target = path.resolve(compatStubsDir, 'react-native-keyboard-controller.ts')
+  const findNodeHandleTarget = '\0sootsim:rnkc-find-node-handle-native'
+  const nativePlatformBasenames = new Set(['findNodeHandle', 'reanimated'])
+  const nativeExts = [
+    '.ios.tsx',
+    '.ios.ts',
+    '.ios.jsx',
+    '.ios.js',
+    '.native.tsx',
+    '.native.ts',
+    '.native.jsx',
+    '.native.js',
+    '.native.mjs',
+  ]
+  const resolveNativePlatformFile = (source: string, importer: string): string | null => {
+    const base = path.resolve(path.dirname(importer), source)
+    for (const ext of nativeExts) {
+      const candidate = base + ext
+      try {
+        if (fs.existsSync(candidate)) return candidate
+      } catch {}
+    }
+    for (const ext of nativeExts) {
+      const candidate = path.join(base, 'index' + ext)
+      try {
+        if (fs.existsSync(candidate)) return candidate
+      } catch {}
+    }
+    return null
+  }
+  return {
+    name: 'sootsim-keyboard-controller-bindings-redirect',
+    enforce: 'pre',
+    resolveId(source, importer) {
+      if (!importer) return null
+      if (!importer.includes('/react-native-keyboard-controller/')) return null
+      // keep bindings imports — strip optional .native and any leading
+      // `./`, `../`, `../../` so the depth doesn't matter.
+      const basename = source.split('/').pop() ?? ''
+      if (nativePlatformBasenames.has(basename)) {
+        return (
+          resolveNativePlatformFile(source, importer) ??
+          (basename === 'findNodeHandle' ? findNodeHandleTarget : null)
+        )
+      }
+      if (basename !== 'bindings' && basename !== 'bindings.native') return null
+      // don't redirect bindings imports that already resolved to our file
+      if (importer === target) return null
+      return target
+    },
+    load(id) {
+      if (id === findNodeHandleTarget) {
+        return `export { findNodeHandle } from ${JSON.stringify(rnShimPath)};`
+      }
+      return null
+    },
+  }
+}
+
+// react-native-reanimated is mostly pure-JS — useSharedValue, useAnimatedStyle,
+// useDerivedValue, withTiming/withSpring/etc., createAnimatedComponent, hooks,
+// layout animations, easing all sit on top of a thin native seam:
+//
+//   - src/specs/NativeReanimatedModule (turbomodule that installs __reanimatedModuleProxy)
+//   - src/platformFunctions/scrollTo
+//   - src/platformFunctions/measure
+//   - src/platformFunctions/setNativeProps
+//   - src/platformFunctions/dispatchCommand
+//   - src/platformFunctions/setGestureState
+//
+// per the project policy of not shimming pure-JS libs, we let upstream resolve
+// from node_modules and redirect ONLY the native seam to our compat stub
+// (one file at packages/compat/src/stubs/react-native-reanimated.ts that
+// exports the right shape — default = turbomodule, named = platform fns).
+//
+// upstream's `assertWorkletsVersion` (DEV-only) imports a build-time script
+// that does `require('react-native-worklets/package.json')`. our flat-file
+// stub for react-native-worklets has no such subpath, so this throws under
+// vite's worker build. redirect the validate script to a no-op stub.
+const reanimatedNativeSeamFiles = new Set([
+  'NativeReanimatedModule',
+  'scrollTo',
+  'measure',
+  'setNativeProps',
+  'dispatchCommand',
+  'setGestureState',
+])
+const reanimatedFabricUtilsRedirectPath = path.resolve(
+  compatStubsDir,
+  'react-native-reanimated-fabric-utils.ts',
+)
+const reanimatedValidateWorkletsVersionPath = path.resolve(
+  compatStubsDir,
+  'react-native-reanimated-validate-worklets-version.ts',
+)
+export function reanimatedNativeSeamRedirect(): Plugin {
+  const target = path.resolve(compatStubsDir, 'react-native-reanimated.ts')
+  return {
+    name: 'sootsim-reanimated-native-seam-redirect',
+    enforce: 'pre',
+    resolveId(source, importer) {
+      // upstream's `assertWorkletsVersion` (DEV-only) imports a build-time
+      // script that does `require('react-native-worklets/package.json')`.
+      // our flat-file stub for react-native-worklets has no such subpath,
+      // so this throws under vite's worker build. resolve the package.json
+      // import to a synthetic virtual id and load synthetic JSON below.
+      if (source === 'react-native-worklets/package.json') {
+        return '\0sootsim:react-native-worklets-package-json'
+      }
+      if (!importer) return null
+      // no-op the assertWorkletsVersion validator — same reason. matches both
+      // the bare import and the .js-suffixed resolved form some bundlers see.
+      if (
+        source === 'react-native-reanimated/scripts/validate-worklets-version' ||
+        source === 'react-native-reanimated/scripts/validate-worklets-version.js'
+      ) {
+        return reanimatedValidateWorkletsVersionPath
+      }
+      if (!importer.includes('/react-native-reanimated/')) return null
+      if (importer === target) return null
+      // strip optional `.web` / `.native` extension and leading `./`s — the
+      // redirect should match regardless of relative depth or platform suffix.
+      const basename = (source.split('/').pop() ?? '').replace(
+        /\.(native|web|ios|android)$/,
+        '',
+      )
+      // upstream's `fabricUtils.{ts,js}` `getShadowNodeWrapperFromRef` requires
+      // `ref.__internalInstanceHandle` (Fabric's react-shadow-tree handle) and
+      // throws otherwise. on sootsim refs come through as raw SootSimNodes
+      // without that handle. redirect to a sootsim-aware version that
+      // lazy-attaches the handle before reading it. see
+      // `react-native-reanimated-fabric-utils.ts`.
+      if (basename === 'fabricUtils' && importer !== reanimatedFabricUtilsRedirectPath) {
+        return reanimatedFabricUtilsRedirectPath
+      }
+      if (!reanimatedNativeSeamFiles.has(basename)) return null
+      if (process.env.SOOTSIM_REANIMATED_REDIRECT_DEBUG) {
+        console.log(
+          '[reanimatedRedirect]',
+          basename,
+          '<-',
+          source,
+          'from',
+          importer.slice(-80),
+        )
+      }
+      return target
+    },
+    load(id) {
+      // synthetic package.json for react-native-worklets — see resolveId
+      // above. just enough for upstream's version-validator to read `version`.
+      if (id === '\0sootsim:react-native-worklets-package-json') {
+        return `export default ${JSON.stringify({ version: '0.0.0-sootsim', name: 'react-native-worklets' })}`
+      }
+      return null
+    },
+  }
+}
+
+// generalised native-seam redirect driven by NATIVE_SEAM_MANIFEST. each entry
+// names an upstream package + a list of basenames to redirect to a single
+// stub. agents migrating from wholesale-rewrite stubs to the native-seam
+// pattern append entries here without touching the plugin code.
+//
+// the reanimated plugin above stays separate because it has package-specific
+// edge cases (fabricUtils, validate-worklets-version). new migrations should
+// use the manifest path unless they need similar special handling.
+import { NATIVE_SEAM_MANIFEST } from './native-seam-manifest'
+export function manifestNativeSeamRedirect(): Plugin {
+  // build a fast lookup: pkg → { basenames, target }
+  const byPkg = new Map<
+    string,
+    { basenames: Set<string>; target: string; notes?: string }
+  >()
+  for (const entry of NATIVE_SEAM_MANIFEST) {
+    const existing = byPkg.get(entry.pkg)
+    if (existing) {
+      for (const b of entry.seamBasenames) existing.basenames.add(b)
+    } else {
+      byPkg.set(entry.pkg, {
+        basenames: new Set(entry.seamBasenames),
+        target: entry.target,
+        notes: entry.notes,
+      })
+    }
+  }
+  return {
+    name: 'sootsim-manifest-native-seam-redirect',
+    enforce: 'pre',
+    resolveId(source, importer) {
+      if (!importer || byPkg.size === 0) return null
+      // find the package whose path appears in the importer. matches both
+      // `/<pkg>/` (unscoped) and `/@scope/<pkg>/` (scoped — the leading `@`
+      // is part of the pkg name in the manifest, e.g. `@notifee/react-native`).
+      let match: { basenames: Set<string>; target: string; notes?: string } | undefined
+      let matchedPkg: string | undefined
+      for (const [pkg, entry] of byPkg) {
+        if (importer.includes(`/${pkg}/`)) {
+          match = entry
+          matchedPkg = pkg
+          break
+        }
+      }
+      if (!match) return null
+      if (importer === match.target) return null
+      const basename = (source.split('/').pop() ?? '').replace(
+        /\.(native|web|ios|android)$/,
+        '',
+      )
+      if (!match.basenames.has(basename)) return null
+      if (process.env.SOOTSIM_NATIVE_SEAM_DEBUG) {
+        console.log(
+          '[nativeSeamRedirect]',
+          `${matchedPkg}:${basename}`,
+          '<-',
+          source,
+          'from',
+          importer.slice(-80),
+          match.notes ? `(${match.notes})` : '',
+        )
+      }
+      return match.target
+    },
+  }
+}
+
+// start WS bridge server for debug CLI connectivity. exported so shell
+// vite can install it standalone (engine builds via `vite build --watch`,
+// which doesn't fire configureServer — the bridge has to run on shell).
+export function wsBridgePlugin(): Plugin {
+  let bridgeHost: {
+    start?: (options?: { silent?: boolean }) => void | Promise<void>
+    close?: () => Promise<void> | void
+  } | null = null
+  return {
+    name: 'sootsim-ws-bridge',
+    configureServer(server) {
+      if (bridgeHost) return
+      // lazy import to avoid pulling ws into the main bundle.
+      // note: the .ts extension is required on vite 8 / node ESM — without
+      // it, import() throws "Cannot find module" and the bridge silently
+      // never starts.
+      void import('./host/bridge-host.ts')
+        .then(({ SootSimBridgeHost }) => {
+          bridgeHost = new SootSimBridgeHost({ port: DEFAULT_SOOTSIM_BRIDGE_PORT })
+          bridgeHost.start?.({ silent: true })
+        })
+        .catch((err: unknown) => {
+          // log but don't crash — some environments (e.g. production builds)
+          // don't have ws available. silently swallowing has caused debugging
+          // pain; print the message instead.
+          const message = err instanceof Error ? err.message : String(err)
+          console.warn('[sootsim] ws bridge failed to start:', message)
+        })
+
+      // cleanup on server close (HMR restart)
+      server.httpServer?.on('close', () => {
+        if (bridgeHost) {
+          void bridgeHost.close?.()
+          bridgeHost = null
+        }
+      })
+    },
+  }
+}
+
+// applies resolve, define, optimizeDeps config
+function sootsimConfigPlugin(appDir: string, extraSources: string[]): Plugin {
+  return {
+    name: 'sootsim-config',
+    config(_, { mode }) {
+      const fsAllow = ['.']
+      for (const src of extraSources) fsAllow.push(src)
+      if (appDir) {
+        fsAllow.push(appDir)
+        const appNodeModules = path.join(appDir, 'node_modules')
+        if (fs.existsSync(appNodeModules)) fsAllow.push(appNodeModules)
+      }
+
+      // build alias list from builtin stubs
+      const stubAliases = Object.entries(builtinStubs)
+        // sort longest keys first so subpath aliases (e.g. foo/Bar) match before
+        // their parent package (e.g. foo) — vite processes aliases in order
+        .sort((a, b) => b[0].length - a[0].length)
+        .map(([find, file]) => ({
+          find,
+          replacement: path.resolve(compatStubsDir, file),
+        }))
+
+      const dedupe = ['react', 'react-dom', 'react/jsx-runtime', 'react/jsx-dev-runtime']
+
+      // internal sootsim builds must keep the entire Tamagui package family on a
+      // single module graph. mixing raw @fs modules with prebundled .vite/deps
+      // versions breaks context identity (Adapt/Portal/ZIndex/etc).
+      if (!appDir) {
+        dedupe.push(...internalTamaguiPackages)
+      }
+
+      const optimizeDepsExclude = [
+        '@tamagui/config',
+        '@tamagui/demos',
+        'react-native',
+        // tamagui native variants reference RN internals that the metro transform
+        // handles — must go through sootsim plugin, not rolldown pre-bundling
+        ...(!appDir ? internalTamaguiPackages : []),
+        // ships .js with JSX that rolldown can't parse
+        'react-native-actions-sheet',
+        // these packages import `react-native-reanimated` and `react-native-gesture-handler`,
+        // both of which we alias to local stubs. pre-bundling would resolve those imports
+        // against the REAL packages (the alias only applies to main-plugin resolveId), so
+        // the resulting dep has a different reanimated instance than the app graph. keep
+        // them served live so our plugin aliases kick in.
+        '@gorhom/bottom-sheet',
+        '@gorhom/portal',
+      ]
+
+      return {
+        define: {
+          'process.env.NODE_ENV': JSON.stringify(mode),
+          'process.env.TEST_NATIVE_PLATFORM': JSON.stringify(''),
+          'process.env.TAMAGUI_TARGET': JSON.stringify('native'),
+          global: 'globalThis',
+        },
+        optimizeDeps: {
+          include: [
+            'react',
+            'react-dom',
+            'react-dom/client',
+            'react-reconciler',
+            'react-reconciler/constants',
+            'react/jsx-runtime',
+            'react/jsx-dev-runtime',
+            '@react-native/normalize-color',
+            // CJS deps transitively imported by @gorhom/bottom-sheet and
+            // @gorhom/portal (both excluded above). vite's CJS→ESM interop
+            // only kicks in via pre-bundle, so these must be pre-bundled even
+            // though their importers aren't.
+            'invariant',
+            'nanoid/non-secure',
+          ],
+          exclude: optimizeDepsExclude,
+          // vite 8: rolldown replaces esbuild for dep optimization
+          rolldownOptions: {
+            resolve: {
+              conditionNames: ['react-native', 'import', 'require'],
+              mainFields: ['react-native', 'module', 'jsnext:main', 'jsnext'],
+              extensions: [
+                '.ios.tsx',
+                '.ios.ts',
+                '.ios.jsx',
+                '.ios.js',
+                '.native.tsx',
+                '.native.ts',
+                '.native.jsx',
+                '.native.js',
+                '.native.mjs',
+                '.mjs',
+                '.js',
+                '.mts',
+                '.ts',
+                '.jsx',
+                '.tsx',
+                '.json',
+              ],
+            },
+            plugins: [
+              {
+                name: 'sootsim-stub-images',
+                resolveId(source: string, importer: string | undefined) {
+                  if (
+                    /\.(jpg|png|gif)$/.test(source) &&
+                    importer?.includes('node_modules')
+                  ) {
+                    return { id: '\0stub-image' }
+                  }
+                },
+                load(id: string) {
+                  if (id === '\0stub-image') return 'export default ""'
+                },
+              },
+            ],
+          },
+        },
+        build: { target: 'esnext' },
+        oxc: { target: 'esnext' },
+        server: {
+          fs: { allow: fsAllow },
+        },
+        resolve: {
+          dedupe,
+          conditions: ['react-native', 'import', 'require'],
+          mainFields: ['react-native', 'module', 'jsnext:main', 'jsnext'],
+          extensions: [
+            '.ios.tsx',
+            '.ios.ts',
+            '.ios.jsx',
+            '.ios.js',
+            '.native.tsx',
+            '.native.ts',
+            '.native.jsx',
+            '.native.js',
+            '.native.mjs',
+            '.mjs',
+            '.js',
+            '.mts',
+            '.ts',
+            '.jsx',
+            '.tsx',
+            '.json',
+          ],
+          alias: [
+            ...sootsimBrowserSourceAliases,
+            ...Object.entries(rnLibraryStubs).map(([find, replacement]) => ({
+              find,
+              replacement,
+            })),
+            { find: /^react-native\/Libraries\/.*/, replacement: rnDeepStubDefault },
+            { find: 'react-native', replacement: rnShimPath },
+            { find: 'react-native-web', replacement: rnShimPath },
+            // resolved-path alias for the synthetic specifier the
+            // @react-navigation/native compat wrapper imports from. terminates
+            // the wrapper's own real-package import without re-entering the
+            // alias above. omit the entry if the package isn't installed —
+            // the wrapper file simply won't be loaded in that case.
+            ...(reactNavigationNativeRealPath
+              ? [
+                  {
+                    find: '@sootsim-internal/react-navigation-native-real',
+                    replacement: reactNavigationNativeRealPath,
+                  },
+                ]
+              : []),
+            ...(reactNativeHapticFeedbackTouchablePath
+              ? [
+                  {
+                    find: SOOTSIM_HAPTIC_FEEDBACK_TOUCHABLE_SPECIFIER,
+                    replacement: reactNativeHapticFeedbackTouchablePath,
+                  },
+                ]
+              : []),
+            ...compatWrapperRealPackageAliases,
+            ...stubAliases,
+          ],
+        },
+      }
+    },
+  }
+}
+
+// redirect `import ... from 'react'` to react-bridge for sootsim, compat, and
+// react-reconciler code. this enables runtime React version switching for
+// external app bundles — bindReact(appReact) swaps which React all code uses.
+function reactBridgePlugin(): Plugin {
+  let isBuild = false
+  let redirectCount = 0
+  let skipCount = 0
+  return {
+    name: 'sootsim-react-bridge',
+    enforce: 'pre',
+    configResolved(config) {
+      isBuild = config.command === 'build'
+      console.log('[react-bridge-plugin] isBuild:', isBuild)
+    },
+    async resolveId(source, importer, options) {
+      if (source !== 'react' || !importer) return null
+
+      // log all react imports to see what's being processed
+      if (
+        importer.includes('/compat/') ||
+        importer.includes('/sootsim/src/') ||
+        importer.includes('/sootsim-engine/src/')
+      ) {
+        skipCount++
+        if (skipCount <= 5) {
+          const skip = (options as { scan?: boolean })?.scan || options?.ssr || isBuild
+          if (!skip) {
+            console.log(
+              '[react-bridge-plugin] react import from:',
+              importer.split('/').slice(-3).join('/'),
+              'skip:',
+              skip,
+            )
+          }
+        }
+      }
+
+      // skip during dep scanning / SSR — only active in browser serve mode
+      if ((options as { scan?: boolean })?.scan || options?.ssr || isBuild) return null
+
+      // only redirect imports from sootsim, sootsim-engine, compat, and react-reconciler
+      const shouldRedirect =
+        importer.includes('/sootsim/src/') ||
+        importer.includes('/sootsim-engine/src/') ||
+        importer.includes('/compat/src/') ||
+        importer.includes('react-reconciler')
+
+      if (!shouldRedirect) return null
+
+      // don't redirect react-bridge's own import of react (avoid infinite loop)
+      if (importer.includes('react-bridge')) return null
+
+      // stub-registry needs the real React (with __CLIENT_INTERNALS) for bundle stubs
+      if (importer.includes('stub-registry')) return null
+
+      redirectCount++
+      if (redirectCount <= 10) {
+        console.log(
+          '[react-bridge-plugin] REDIRECTING:',
+          importer.split('/').slice(-3).join('/'),
+        )
+      } else if (redirectCount === 11) {
+        console.log('[react-bridge-plugin] ... more redirects')
+      }
+      return { id: reactBridgePath, external: false }
+    },
+  }
+}
+
+// worker-compatible react-bridge redirect. unlike the main plugin, this one
+// also applies during builds since workers are built, not served. exported for
+// use in worker.plugins configuration.
+export function workerReactBridgePlugin(): Plugin {
+  return {
+    name: 'sootsim-worker-react-bridge',
+    enforce: 'pre',
+    async resolveId(source, importer, options) {
+      if (source !== 'react' || !importer) return null
+
+      // skip during dep scanning / SSR
+      if ((options as { scan?: boolean })?.scan || options?.ssr) return null
+
+      // don't redirect react-bridge's own import of react (avoid infinite loop)
+      if (importer.includes('react-bridge')) return null
+
+      // stub-registry needs the real React (with __CLIENT_INTERNALS) for bundle stubs
+      if (importer.includes('stub-registry')) return null
+
+      // redirect react imports from sootsim, sootsim-engine, compat, react-reconciler,
+      // and any pure-JS RN-ecosystem package the bundle pulls in. without this
+      // redirect, packages like react-native-drawer-layout / use-latest-callback
+      // call into a separate React instance than the renderer/bridge does, so
+      // their useRef/useEffect refs collide with the engine's hooks state and
+      // we hit "Maximum update depth exceeded" infinite-loop renders.
+      const shouldRedirect =
+        importer.includes('/sootsim/src/') ||
+        importer.includes('/sootsim-engine/src/') ||
+        importer.includes('/compat/src/') ||
+        importer.includes('react-reconciler') ||
+        importer.includes('/node_modules/')
+
+      if (!shouldRedirect) return null
+
+      return { id: reactBridgePath, external: false }
+    },
+  }
+}
+
+// react 19's jsx-runtime.development.js wraps exports.jsx inside a conditional
+// IIFE, so esbuild's static CJS analysis can't detect the named exports during
+// pre-bundling. this plugin wraps the real pre-bundled module with explicit exports.
+// exported for use in worker.plugins configuration.
+export function fixJsxRuntimeExports(): Plugin {
+  return {
+    name: 'sootsim-fix-jsx-runtime',
+    enforce: 'pre',
+    async resolveId(source, importer, options) {
+      if (source === 'react/jsx-runtime' || source === 'react/jsx-dev-runtime') {
+        const resolved = await this.resolve(source, importer, {
+          ...options,
+          skipSelf: true,
+        })
+        if (!resolved) return null
+        const prefix =
+          source === 'react/jsx-runtime'
+            ? '\0sootsim:jsx-runtime:'
+            : '\0sootsim:jsx-dev-runtime:'
+        return prefix + resolved.id
+      }
+      return null
+    },
+    load(id) {
+      if (id.startsWith('\0sootsim:jsx-runtime:')) {
+        const realId = id.slice('\0sootsim:jsx-runtime:'.length)
+        return [
+          `import * as _mod from ${JSON.stringify(realId)};`,
+          `const _m = _mod.default || _mod;`,
+          `export const jsx = _m.jsx || _mod.jsx;`,
+          `export const jsxs = _m.jsxs || _mod.jsxs;`,
+          `export const Fragment = _m.Fragment || _mod.Fragment;`,
+        ].join('\n')
+      }
+      if (id.startsWith('\0sootsim:jsx-dev-runtime:')) {
+        const realId = id.slice('\0sootsim:jsx-dev-runtime:'.length)
+        // react/jsx-runtime is already wrapped by this plugin (above) to expose
+        // { jsx, jsxs, Fragment } as named exports, so read them directly from
+        // the namespace — no `_runtime.default || _runtime` fallback needed.
+        // rolldown statically knows the wrapped module has no default export
+        // and would emit IMPORT_IS_UNDEFINED warnings on every build.
+        return [
+          `import * as _mod from ${JSON.stringify(realId)};`,
+          `import * as _runtime from "react/jsx-runtime";`,
+          `const _m = _mod.default || _mod;`,
+          // production React builds may not expose jsxDEV from react/jsx-dev-runtime.
+          // fall back to jsx so transformed modules still execute.
+          `export const jsxDEV = _m.jsxDEV || _mod.jsxDEV || _m.jsx || _mod.jsx || _runtime.jsx;`,
+          `export const Fragment = _m.Fragment || _mod.Fragment || _runtime.Fragment;`,
+        ].join('\n')
+      }
+      return null
+    },
+  }
+}
+
+// esbuild plugin for optimizeDeps pre-bundling
+function sootsimEsbuildPlugin(appDir: string) {
+  const platformExts = [
+    '.ios.tsx',
+    '.ios.ts',
+    '.ios.jsx',
+    '.ios.js',
+    '.native.tsx',
+    '.native.ts',
+    '.native.jsx',
+    '.native.js',
+    '.native.mjs',
+  ]
+
+  function isAppSourceEsbuild(filePath: string): boolean {
+    return !!(appDir && filePath.startsWith(appDir))
+  }
+
+  return {
+    name: 'sootsim-esbuild',
+    setup(build: any) {
+      // metro-style .ios > .native resolution
+      build.onResolve({ filter: /^\./ }, (args: any) => {
+        if (!args.importer.includes('node_modules') && !isAppSourceEsbuild(args.importer))
+          return null
+        const dir = path.dirname(args.importer)
+        const resolved = path.resolve(dir, args.path)
+        for (const ext of platformExts) {
+          const candidate = resolved + ext
+          try {
+            if (fs.existsSync(candidate)) return { path: candidate }
+          } catch {}
+        }
+        for (const ext of platformExts) {
+          const candidate = path.join(resolved, 'index' + ext)
+          try {
+            if (fs.existsSync(candidate)) return { path: candidate }
+          } catch {}
+        }
+        const allExts = [...platformExts, '.tsx', '.ts', '.jsx', '.js', '.mjs', '.cjs']
+        for (const ext of allExts) {
+          if (args.path.endsWith(ext)) {
+            const base = resolved.slice(0, -ext.length)
+            for (const pext of platformExts) {
+              const candidate = base + pext
+              try {
+                if (fs.existsSync(candidate)) return { path: candidate }
+              } catch {}
+            }
+            break
+          }
+        }
+        return null
+      })
+
+      // react-native deep path stubs
+      for (const [importPath, stubPath] of Object.entries(rnLibraryStubs)) {
+        build.onResolve(
+          { filter: new RegExp(`^${importPath.replace(/\//g, '\\/')}$`) },
+          () => ({
+            path: stubPath,
+          }),
+        )
+      }
+      build.onResolve({ filter: /^react-native\/Libraries\// }, (args: any) => {
+        return { path: rnLibraryStubs[args.path] || rnDeepStubDefault }
+      })
+
+      // resolve builtin stubs (react-native-safe-area-context, expo-*, etc.)
+      for (const [pkgName, stubFile] of Object.entries(builtinStubs)) {
+        const stubPath = path.resolve(compatStubsDir, stubFile)
+        const escaped = pkgName.replace(/[.*+?^${}()|[\]\\/@-]/g, '\\$&')
+        build.onResolve({ filter: new RegExp(`^${escaped}$`) }, () => ({
+          path: stubPath,
+        }))
+      }
+
+      // external app node_modules resolution — use esbuild's own resolve
+      // so exports conditions are respected (not CJS require.resolve which ignores them)
+      if (appDir) {
+        const owned = new Set(coreOwnedPackages)
+        build.onResolve({ filter: /^[^.]/ }, async (args: any) => {
+          if (args.pluginData?.fromAppResolve) return null
+          if (
+            !isAppSourceEsbuild(args.importer) &&
+            !args.importer.includes(path.join(appDir, 'node_modules'))
+          )
+            return null
+          const src = args.path
+          if (src.startsWith('\0')) return null
+          if (owned.has(src) || owned.has(getPackageName(src))) return null
+          if (src === 'react-native' || src.startsWith('react-native/')) return null
+          try {
+            const result = await build.resolve(src, {
+              resolveDir: appDir,
+              pluginData: { fromAppResolve: true },
+            })
+            if (result.errors.length) return null
+            return { path: result.path }
+          } catch {
+            return null
+          }
+        })
+      }
+
+      // auto-stub missing native packages
+      build.onResolve(
+        {
+          filter:
+            /^(expo-|react-native-|@react-native\/|@react-native-community\/|@expo\/|expo$)/,
+        },
+        (args: any) => {
+          const pkgName = getPackageName(args.path)
+          if (moduleExistsIn(pkgName, sootsimRoot)) return null
+          if (appDir && moduleExistsIn(pkgName, appDir)) return null
+          return { path: nativeAutoStubPath }
+        },
+      )
+
+      // stub missing image imports
+      build.onResolve({ filter: /\.(jpg|png|gif)$/ }, (args: any) => {
+        if (args.importer.includes('node_modules')) {
+          return { path: args.path, namespace: 'stub-image' }
+        }
+        return null
+      })
+      build.onLoad({ filter: /.*/, namespace: 'stub-image' }, () => ({
+        contents: 'export default ""',
+        loader: 'js',
+      }))
+    },
+  }
+}
+
+// handle .js files containing JSX from node_modules during production builds.
+// upstream `react-native-reanimated` and downstream consumers (
+// `react-native-keyboard-controller`, `react-native-gesture-handler`,
+// `react-native-screens`, sootsim's own fixtures + RN compat source) ship
+// raw source containing `'worklet'` directives and inline updaters to
+// auto-workletizable hooks. the `react-native-worklets/plugin` babel
+// transform lifts those into wrapper functions carrying `__closure`,
+// `__workletHash`, and `__initData`. without that transform,
+// `useAnimatedStyle`'s `let inputs = Object.values(updater.__closure ?? {})`
+// returns `[]` and the mapper never subscribes — animations don't run.
+//
+// metro builds (apps loaded inside sootsim — 3pc, bluesky, expensify,
+// eigen, …) run the plugin in their own pipeline, so the bundle that
+// reaches us already has `__closure` baked in. our transform only needs
+// to act on:
+//
+//   - sootsim's own src + test fixtures + external-app source, and
+//   - upstream library source loaded from node_modules where the redirect
+//     plugin let pure-JS resolve naturally.
+//
+// the keyword list + ignored-path list is ported from
+// `~/one/packages/compiler/src/transformBabel.ts` (which is itself ported
+// from reanimated 3.15.1's autoworkletization keywords). keep the two in
+// sync if upstream adds new auto-workletized hooks. detection is
+// content-driven, not path-driven, so we don't need a per-package
+// allow-list — anything that mentions a workletizable identifier and
+// isn't on the ignored-path list goes through.
+
+export function workletsBabelTransform(
+  // accepted for future per-target overrides; matching is content-driven
+  // today so we don't actually consult it. kept for plugin-list parity.
+  _isAppSource: (p: string) => boolean = () => false,
+): Plugin {
+  return {
+    name: 'sootsim-worklets-babel-transform',
+    enforce: 'pre',
+    async transform(code, id) {
+      if (!shouldApplyWorkletsPlugin(id, code)) return null
+      try {
+        if (process.env.SOOTSIM_WORKLETS_BABEL_DEBUG) {
+          console.log('[worklets-babel] transforming', id.slice(-80))
+        }
+        return await transformWorkletsCode(code, id, true)
+      } catch (err) {
+        // surface but don't kill the build — fall back to raw code so the
+        // rest of the pipeline can run. these failures are loud in the
+        // console and easy to chase.
+        const message = err instanceof Error ? err.message : String(err)
+        console.warn(`[sootsim-worklets-babel] transform failed for ${id}: ${message}`)
+        return null
+      }
+    },
+  }
+}
+
+// rolldown can't parse JSX in .js files — transform them first.
+// needed because some RN packages (e.g. react-native-actions-sheet) ship JSX in .js.
+// some upstream RN libraries (e.g. @react-native-segmented-control/segmented-control)
+// publish raw Flow source as their runtime entry. Metro strips Flow in its babel
+// pipeline; vite/rolldown/oxc do not. detect the `@flow` pragma in node_modules and
+// run @babel/plugin-transform-flow-strip-types so the wrapper-real seam can pull
+// in the real upstream JS without re-implementing it locally. mirrored in
+// scripts/build-bundler-deps.ts so esbuild-based dep prebundles stay in sync.
+let flowBabel: typeof import('@babel/core') | null = null
+let flowStripPlugin: import('@babel/core').PluginItem | null = null
+let jsxSyntaxPlugin: import('@babel/core').PluginItem | null = null
+function loadFlowBabel(): void {
+  if (flowBabel) return
+  flowBabel = sootsimPluginRequire('@babel/core')
+  flowStripPlugin = sootsimPluginRequire(
+    '@babel/plugin-transform-flow-strip-types',
+  ) as import('@babel/core').PluginItem
+  jsxSyntaxPlugin = sootsimPluginRequire(
+    '@babel/plugin-syntax-jsx',
+  ) as import('@babel/core').PluginItem
+}
+function flowStripTransform(): Plugin {
+  return {
+    name: 'sootsim-flow-strip',
+    enforce: 'pre',
+    transform(code, id) {
+      if (!id.includes('/node_modules/')) return null
+      if (!/\.[cm]?jsx?$/.test(id)) return null
+      if (!code.includes('@flow')) return null
+      loadFlowBabel()
+      const result = flowBabel!.transformSync(code, {
+        filename: id,
+        babelrc: false,
+        configFile: false,
+        plugins: [flowStripPlugin!, jsxSyntaxPlugin!],
+        sourceMaps: true,
+        compact: false,
+      })
+      if (!result?.code) return null
+      return { code: result.code, map: result.map ?? null }
+    },
+  }
+}
+
+function nodeModulesJsxTransform(): Plugin {
+  return {
+    name: 'sootsim-node-modules-jsx',
+    enforce: 'pre',
+    async transform(code, id) {
+      if (!id.includes('/node_modules/')) return null
+      if (!id.endsWith('.js')) return null
+      if (!code.includes('<')) return null
+      // quick check: does it look like JSX? (angle bracket followed by uppercase or known RN component)
+      if (!/[=(\s,]<[A-Z]/.test(code) && !/<\/[A-Z]/.test(code)) return null
+      const needsReact =
+        !code.includes('import React') && !code.includes('import * as React')
+      const withReact = needsReact ? `import React from 'react';\n${code}` : code
+      const transformed = await transformWithOxc(withReact, id, {
+        lang: 'jsx',
+        jsx: { runtime: 'classic' },
+      })
+      return { code: transformed.code, map: transformed.map }
+    },
+  }
+}
+
+// metro-style platform resolution: .ios > .native > base
+function metroNativeResolve(isAppSource: (p: string) => boolean): Plugin {
+  const platformExts = [
+    '.ios.tsx',
+    '.ios.ts',
+    '.ios.jsx',
+    '.ios.js',
+    '.native.tsx',
+    '.native.ts',
+    '.native.jsx',
+    '.native.js',
+    '.native.mjs',
+  ]
+  const allExts = [...platformExts, '.tsx', '.ts', '.jsx', '.js', '.mjs', '.cjs']
+
+  function tryResolve(base: string): string | null {
+    for (const ext of platformExts) {
+      const candidate = base + ext
+      try {
+        if (fs.existsSync(candidate)) return candidate
+      } catch {}
+    }
+    for (const ext of platformExts) {
+      const candidate = path.join(base, 'index' + ext)
+      try {
+        if (fs.existsSync(candidate)) return candidate
+      } catch {}
+    }
+    return null
+  }
+
+  return {
+    name: 'sootsim-metro-native-resolve',
+    enforce: 'pre',
+    resolveId(source, importer) {
+      if (!importer) return null
+      if (!importer.includes('node_modules') && !isAppSource(importer)) return null
+      if (!source.startsWith('.')) return null
+      if (platformExts.some((ext) => source.endsWith(ext))) return null
+
+      const hasBaseExt = allExts.some((ext) => source.endsWith(ext))
+      const dir = path.dirname(importer)
+
+      if (hasBaseExt) {
+        const resolved = path.resolve(dir, source)
+        for (const ext of allExts) {
+          if (source.endsWith(ext)) {
+            const found = tryResolve(resolved.slice(0, -ext.length))
+            if (found) return found
+            break
+          }
+        }
+      } else {
+        const found = tryResolve(path.resolve(dir, source))
+        if (found) return found
+      }
+      return null
+    },
+  }
+}
+
+// convert require("react-native") and deep library requires to ESM imports
+function reactNativeRequirePlugin(isAppSource: (p: string) => boolean): Plugin {
+  return {
+    name: 'sootsim-react-native-require',
+    enforce: 'pre',
+    transform(code, id) {
+      if (!id.includes('node_modules') && !isAppSource(id)) return null
+      if (!code.includes('react-native')) return null
+
+      let hasChanges = false
+      let imports = ''
+      let result = code
+      let importCounter = 0
+
+      if (
+        result.includes('require("react-native")') ||
+        result.includes("require('react-native')")
+      ) {
+        imports += `import * as __soot_rn_shim__ from ${JSON.stringify(rnShimPath)};\n`
+        result = result.replace(/require\(["']react-native["']\)/g, '__soot_rn_shim__')
+        hasChanges = true
+      }
+
+      const deepRequireRegex = /require\(["'](react-native\/Libraries\/[^"']+)["']\)/g
+      const replacements: Array<{ full: string; path: string; varName: string }> = []
+      const seenPaths = new Map<string, string>()
+      let match
+
+      deepRequireRegex.lastIndex = 0
+      while ((match = deepRequireRegex.exec(result)) !== null) {
+        const importPath = match[1]
+        if (!seenPaths.has(importPath)) {
+          const varName = `__soot_rn_lib_${importCounter++}__`
+          const stubPath = rnLibraryStubs[importPath] || rnDeepStubDefault
+          imports += `import * as ${varName} from ${JSON.stringify(stubPath)};\n`
+          seenPaths.set(importPath, varName)
+        }
+        replacements.push({
+          full: match[0],
+          path: importPath,
+          varName: seenPaths.get(importPath)!,
+        })
+      }
+
+      if (replacements.length > 0) {
+        for (const rep of replacements) {
+          result = result.replace(rep.full, rep.varName)
+        }
+        hasChanges = true
+      }
+
+      if (!hasChanges) return null
+      return { code: imports + result, map: null }
+    },
+  }
+}
+
+// resolve bare imports from external app's node_modules
+function externalAppResolvePlugin(
+  appDir: string,
+  isAppSource: (p: string) => boolean,
+  ownedPackages: Set<string>,
+): Plugin {
+  if (!appDir) return { name: 'sootsim-external-app-resolve' }
+
+  // synthetic importer inside the app dir so vite searches app's node_modules
+  // using its conditions-aware exports resolution (not CJS require.resolve)
+  const appVirtualImporter = path.join(appDir, '_virtual_.js')
+
+  return {
+    name: 'sootsim-external-app-resolve',
+    enforce: 'pre',
+    async resolveId(source, importer, options) {
+      if (!importer) return null
+      if (source.startsWith('.') || source.startsWith('/') || source.startsWith('\0'))
+        return null
+      if (ownedPackages.has(source) || ownedPackages.has(getPackageName(source)))
+        return null
+      if (!isAppSource(importer) && !importer.includes(path.join(appDir, 'node_modules')))
+        return null
+      if (source === 'react-native' || source.startsWith('react-native/')) return null
+
+      // re-resolve through vite's pipeline so exports conditions (react-native, import) are respected
+      const resolved = await this.resolve(source, appVirtualImporter, {
+        ...options,
+        skipSelf: true,
+      })
+      return resolved || null
+    },
+  }
+}
+
+// convert require() calls and handle JSX in .js files from external app sources
+function externalAppTransformPlugin(isAppSource: (p: string) => boolean): Plugin {
+  return {
+    name: 'sootsim-external-app-transform',
+    enforce: 'pre',
+    async transform(code, id) {
+      if (!isAppSource(id)) return null
+
+      let result = code
+      let imports = ''
+      let importCounter = 0
+      let hasChanges = false
+
+      if (code.includes('require(')) {
+        const requireRegex = /require\(["']([^"']+)["']\)/g
+        const replacements: Array<{ full: string; varName: string }> = []
+        const seenPaths = new Map<string, string>()
+        let match
+
+        requireRegex.lastIndex = 0
+        while ((match = requireRegex.exec(result)) !== null) {
+          const reqPath = match[1]
+          if (reqPath === 'react-native' || reqPath.startsWith('react-native/')) continue
+
+          if (!seenPaths.has(reqPath)) {
+            const varName = `__soot_cjs_${importCounter++}__`
+            imports += `import * as ${varName} from ${JSON.stringify(reqPath)};\n`
+            seenPaths.set(reqPath, varName)
+          }
+          replacements.push({ full: match[0], varName: seenPaths.get(reqPath)! })
+        }
+
+        if (replacements.length > 0) {
+          for (const rep of replacements) {
+            result = result.replace(rep.full, rep.varName)
+          }
+          hasChanges = true
+        }
+      }
+
+      if (imports) result = imports + result
+
+      if (id.endsWith('.js') && result.includes('<')) {
+        const needsReact =
+          !result.includes('import React') && !result.includes('import * as React')
+        const withReact = needsReact ? `import React from 'react';\n${result}` : result
+        const transformed = await transformWithOxc(withReact, id, {
+          lang: 'jsx',
+          jsx: { runtime: 'classic' },
+        })
+        return { code: transformed.code, map: transformed.map }
+      }
+
+      if (!hasChanges) return null
+      return { code: result, map: null }
+    },
+  }
+}
+
+// auto-stub native packages that don't exist in any node_modules
+function stubMissingNativeDeps(appDir: string): Plugin {
+  const checked = new Map<string, boolean>()
+
+  function packageExists(pkgName: string): boolean {
+    const cached = checked.get(pkgName)
+    if (cached !== undefined) return cached
+    let exists = moduleExistsIn(pkgName, sootsimRoot)
+    if (!exists && appDir) exists = moduleExistsIn(pkgName, appDir)
+    checked.set(pkgName, exists)
+    return exists
+  }
+
+  return {
+    name: 'sootsim-stub-missing-native-deps',
+    resolveId(source) {
+      if (!isNativePackage(source)) return null
+      const pkgName = getPackageName(source)
+      if (packageExists(pkgName)) return null
+      console.log(`[sootsim] auto-stubbing missing native dep: ${source}`)
+      return nativeAutoStubPath
+    },
+  }
+}
+
+// stub missing image imports from node_modules
+function stubMissingImages(isAppSource: (p: string) => boolean): Plugin {
+  return {
+    name: 'sootsim-stub-images',
+    enforce: 'pre',
+    resolveId(id, importer) {
+      if (id.endsWith('.jpg') || id.endsWith('.png') || id.endsWith('.gif')) {
+        if (importer?.includes('node_modules') || (importer && isAppSource(importer))) {
+          return '\0stub-image'
+        }
+      }
+      return null
+    },
+    load(id) {
+      if (id === '\0stub-image') return 'export default ""'
+      return null
+    },
+  }
+}