rnxsim 0.0.0 → 0.1.312

package/src/vite-plugin.ts

@@ -0,0 +1,1750 @@
+// 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 { resolveExportsHiddenSubpath } from '../../compat/src/resolve-hidden-subpath.ts'
+import {
+  SOOTSIM_COMPAT_PUBLISHED_BROWSER_ENTRIES,
+  SOOTSIM_COMPAT_WRAPPER_REAL_PACKAGES,
+  SOOTSIM_HAPTIC_FEEDBACK_TOUCHABLE_SOURCE,
+  SOOTSIM_HAPTIC_FEEDBACK_TOUCHABLE_SPECIFIER,
+  compatStubsForBuildResolver,
+  reactNativeDeepStubsForBuildResolver,
+} from '../../compat/src/stub-manifest.ts'
+import { resolveSootsimBridgePort } from './bridge-constants.ts'
+import {
+  REANIMATED_WORKLETIZATION_REGEX,
+  shouldApplyWorkletsPlugin,
+  transformWorkletsCode,
+} from './worklets-babel.ts'
+
+const sootsimPluginRequire = createRequire(import.meta.url)
+const virtualIdPrefix = String.fromCharCode(0)
+
+export interface SootSimOptions {
+  // 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 @sootsim/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: 'rnxsim/backend-origin',
+    replacement: path.resolve(sootsimRoot, 'src/backend-origin.ts'),
+  },
+  {
+    find: 'rnxsim/bridge-constants',
+    replacement: path.resolve(sootsimRoot, 'src/bridge-constants.ts'),
+  },
+  {
+    find: 'rnxsim/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),
+  ]),
+)
+
+type PublishedBrowserPackage = {
+  specifier: string
+  packageDir: string
+  browserEntry: string
+}
+
+function resolvePublishedBrowserPackages(appDir: string): PublishedBrowserPackage[] {
+  const packageRequire = appDir
+    ? createRequire(path.join(appDir, 'package.json'))
+    : sootsimPluginRequire
+  return Object.values(SOOTSIM_COMPAT_PUBLISHED_BROWSER_ENTRIES).flatMap(
+    ({ specifier }) => {
+      try {
+        const packageJson = packageRequire.resolve(`${specifier}/package.json`)
+        const packageManifest = JSON.parse(fs.readFileSync(packageJson, 'utf8'))
+        const rootExport = Reflect.get(packageManifest.exports, '.')
+        const browserFile =
+          typeof rootExport === 'object' && rootExport !== null
+            ? Reflect.get(rootExport, 'browser')
+            : undefined
+        if (typeof browserFile !== 'string') return []
+        const packageDir = path.dirname(packageJson)
+        const browserEntry = path.resolve(packageDir, browserFile)
+        if (!fs.existsSync(browserEntry)) return []
+        return [{ specifier, packageDir, browserEntry }]
+      } catch {
+        return []
+      }
+    },
+  )
+}
+
+function resolvePublishedBrowserInternal(
+  source: string,
+  importer: string | undefined,
+  packages: PublishedBrowserPackage[],
+): string | null {
+  if (!importer || !source.startsWith('.')) return null
+  const cleanImporter = importer.split('?')[0]
+  const packageEntry = packages.find(({ packageDir }) => {
+    const relative = path.relative(packageDir, cleanImporter)
+    return relative.length > 0 && !relative.startsWith('..') && !path.isAbsolute(relative)
+  })
+  if (!packageEntry) return null
+
+  const cleanSource = source.split('?')[0]
+  const resolved = path.resolve(path.dirname(cleanImporter), cleanSource)
+  const sourceExtension = path.extname(cleanSource)
+  if (sourceExtension) {
+    const candidate = `${resolved.slice(0, -sourceExtension.length)}.web${sourceExtension}`
+    return fs.existsSync(candidate) ? candidate : null
+  }
+
+  for (const extension of ['.tsx', '.ts', '.jsx', '.js', '.mjs', '.cjs']) {
+    const fileCandidate = `${resolved}.web${extension}`
+    if (fs.existsSync(fileCandidate)) return fileCandidate
+    const indexCandidate = path.join(resolved, `index.web${extension}`)
+    if (fs.existsSync(indexCandidate)) return indexCandidate
+  }
+  return null
+}
+
+// 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
+  }
+})()
+
+// `@expo/ui/swift-ui/modifiers` is pure JS (every modifier just returns a
+// ModifierConfig via createModifier) and runs from the real bundle unchanged —
+// the runtime stub-registry intentionally does NOT intercept it. but the
+// `@expo/ui/swift-ui` stub alias is a vite PREFIX match, so without an explicit
+// longer alias it captures `.../modifiers` and rewrites it to
+// `<stubs>/expo-ui.ts/modifiers` ("Not a directory"). resolve the real subpath
+// here and alias it first (stubAliases are sorted longest-first, and this is
+// longer than `@expo/ui/swift-ui`, so it wins).
+const expoUiSwiftUiModifiersRealPath = (() => {
+  try {
+    return sootsimPluginRequire.resolve('@expo/ui/swift-ui/modifiers')
+  } catch {
+    return null
+  }
+})()
+
+// the same prefix-alias trap, for the whole Android half of the package.
+// `@expo/ui/jetpack-compose` and its `/modifiers` subpath are deliberately NOT
+// intercepted: every component is a thin `requireNativeView('ExpoUI', …)`
+// wrapper and the Android views come from the compat native seam, so the real
+// upstream JS has to load. Without these two longer aliases the `@expo/ui` stub
+// prefix rewrites them to `<stubs>/expo-ui.ts/jetpack-compose` ("Not a
+// directory") and every Android Expo UI screen fails to build.
+const expoUiJetpackComposeRealAliases = [
+  '@expo/ui/jetpack-compose/modifiers',
+  '@expo/ui/jetpack-compose',
+].flatMap((specifier) => {
+  try {
+    return [{ find: specifier, replacement: sootsimPluginRequire.resolve(specifier) }]
+  } catch {
+    return []
+  }
+})
+
+// `react-native-gesture-handler/ReanimatedSwipeable` and `.../DrawerLayout` are
+// upstream pure JS and should load from the installed package. The root RNGH
+// package still aliases to SootSim's native seam, so add exact subpath aliases
+// before the root stub can rewrite them to
+// `<stubs>/react-native-gesture-handler.ts/<subpath>`.
+function rnghSubpathRealPath(subpath: string): string | null {
+  try {
+    const packageJsonPath = sootsimPluginRequire.resolve(
+      `react-native-gesture-handler/${subpath}/package.json`,
+    )
+    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'))
+    const moduleEntry = packageJson?.module
+    if (typeof moduleEntry !== 'string' || moduleEntry.length === 0) return null
+    const modulePath = path.resolve(path.dirname(packageJsonPath), moduleEntry)
+    if (fs.existsSync(modulePath) && fs.statSync(modulePath).isFile()) return modulePath
+    const jsPath = `${modulePath}.js`
+    if (fs.existsSync(jsPath)) return jsPath
+    const indexPath = path.join(modulePath, 'index.js')
+    return fs.existsSync(indexPath) ? indexPath : null
+  } catch {
+    return null
+  }
+}
+
+const rnghReanimatedSwipeableRealPath = rnghSubpathRealPath('ReanimatedSwipeable')
+const rnghDrawerLayoutRealPath = rnghSubpathRealPath('DrawerLayout')
+
+const rnghGestureHandlerRootViewContextRealPath = (() => {
+  try {
+    return path.join(
+      path.dirname(
+        sootsimPluginRequire.resolve('react-native-gesture-handler/package.json'),
+      ),
+      'lib/module/GestureHandlerRootViewContext.js',
+    )
+  } catch {
+    return null
+  }
+})()
+const rnghGestureHandlerRootViewContextShimPath = path.resolve(
+  compatStubsDir,
+  'rngh-gesture-handler-root-view-context.ts',
+)
+const rnghRootStubPath = path.resolve(compatStubsDir, 'react-native-gesture-handler.ts')
+const rnghLibModuleRoot = rnghGestureHandlerRootViewContextRealPath
+  ? path.dirname(rnghGestureHandlerRootViewContextRealPath)
+  : null
+
+const compatWrapperRealPackageAliases: Array<{
+  find: string
+  replacement: string
+}> = []
+for (const { specifier, packageName } of Object.values(
+  SOOTSIM_COMPAT_WRAPPER_REAL_PACKAGES,
+)) {
+  let replacement = resolveExportsHiddenSubpath(packageName, (specifier) =>
+    sootsimPluginRequire.resolve(specifier),
+  )
+  if (!replacement) {
+    try {
+      replacement = sootsimPluginRequire.resolve(packageName)
+    } catch {}
+  }
+  if (!replacement) {
+    // a dropped alias only surfaces much later as an opaque
+    // "failed to resolve @sootsim-internal/…", so say it here instead.
+    console.warn(
+      `[sootsim] compat wrapper alias ${specifier} -> ${packageName} did not resolve`,
+    )
+    continue
+  }
+  compatWrapperRealPackageAliases.push({ find: specifier, replacement })
+}
+
+// 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: SootSimOptions = {}): 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 || [])])
+  const publishedBrowserPackages = resolvePublishedBrowserPackages(appDir)
+
+  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(),
+    {
+      name: 'sootsim-published-browser-internals',
+      enforce: 'pre',
+      resolveId: {
+        filter: { id: /^\./ },
+        handler(source, importer) {
+          return resolvePublishedBrowserInternal(
+            source,
+            importer,
+            publishedBrowserPackages,
+          )
+        },
+      },
+    },
+    sootsimConfigPlugin(appDir, extraSources, publishedBrowserPackages),
+    rnghUpstreamInternalResolvePlugin(),
+    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),
+    ...(appDir ? [externalAppResolvePlugin(appDir, isAppSource, ownedPackages)] : []),
+    ...(appDir || extraSources.length > 0
+      ? [externalAppTransformPlugin(isAppSource)]
+      : []),
+    stubMissingNativeDeps(appDir),
+    stubMissingImages(isAppSource),
+  ]
+}
+
+function stripViteQuery(id: string): string {
+  return id.split('?')[0]
+}
+
+function isPathInside(child: string, parent: string): boolean {
+  const rel = path.relative(parent, child)
+  return rel === '' || (!!rel && !rel.startsWith('..') && !path.isAbsolute(rel))
+}
+
+function rnghUpstreamInternalResolvePlugin(): Plugin {
+  return {
+    name: 'sootsim-rngh-upstream-internal-resolve',
+    enforce: 'pre',
+    resolveId: {
+      filter: {
+        id: /(?:^\.\.\/\.\.(?:\.(?:js|jsx|mjs|ts|tsx))?$|GestureDetector(?:\.(?:js|jsx|mjs|ts|tsx))?$|GestureHandlerRootViewContext(?:\.(?:js|jsx|mjs|ts|tsx))?$|(?:PanGestureHandler|TapGestureHandler|State)(?:\.(?:js|jsx|mjs|ts|tsx))?$)/,
+      },
+      handler(source, importer) {
+        if (!importer || !rnghLibModuleRoot) return null
+        const importerPath = stripViteQuery(importer)
+        if (!isPathInside(importerPath, rnghLibModuleRoot)) return null
+        const sourcePath = source.replace(/\.(js|jsx|mjs|ts|tsx)$/, '')
+        if (
+          sourcePath === '../..' ||
+          sourcePath.endsWith('/handlers/gestures/GestureDetector') ||
+          // upstream's DrawerLayout builds on the old-API handlers and the
+          // State enum; both come from our seam, not upstream's native modules.
+          sourcePath.endsWith('/handlers/PanGestureHandler') ||
+          sourcePath.endsWith('/handlers/TapGestureHandler') ||
+          sourcePath === '../State'
+        ) {
+          return rnghRootStubPath
+        }
+        if (sourcePath.endsWith('GestureHandlerRootViewContext')) {
+          return rnghGestureHandlerRootViewContextShimPath
+        }
+        return null
+      },
+    },
+  }
+}
+
+// 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(),
+    flowStripTransform(),
+    nodeModulesJsxTransform(),
+    reanimatedNativeSeamRedirect(),
+    manifestNativeSeamRedirect(),
+    keyboardControllerBindingsRedirect(),
+    rnghUpstreamInternalResolvePlugin(),
+    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: {
+      filter: {
+        id: /(?:^|\/)(?:bindings(?:\.native)?|findNodeHandle|reanimated)$/,
+      },
+      handler(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: {
+      filter: {
+        id: new RegExp(`^${virtualIdPrefix}sootsim:rnkc-find-node-handle-native$`),
+      },
+      handler() {
+        return `export { findNodeHandle } from ${JSON.stringify(rnShimPath)};`
+      },
+    },
+  }
+}
+
+// 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: {
+      filter: {
+        id: /(?:^react-native-worklets\/package\.json$|^react-native-reanimated\/scripts\/validate-worklets-version(?:\.js)?$|(?:^|\/)(?:fabricUtils|NativeReanimatedModule|scrollTo|measure|setNativeProps|dispatchCommand|setGestureState)(?:\.(?:native|web|ios|android))?$)/,
+      },
+      handler(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)$/,
+          '',
+        )
+        // keep fabricUtils on the SootSim Fabric public-instance contract. the
+        // redirected module reads the constructor-attached handle for native
+        // refs and uses ReactFabric's renderer lookup for composite refs.
+        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: {
+      filter: {
+        id: new RegExp(`^${virtualIdPrefix}sootsim:react-native-worklets-package-json$`),
+      },
+      handler() {
+        // synthetic package.json for react-native-worklets — see resolveId
+        // above. just enough for upstream's version-validator to read `version`.
+        return `export default ${JSON.stringify({ version: '0.0.0-sootsim', name: 'react-native-worklets' })}`
+      },
+    },
+  }
+}
+
+// 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.ts'
+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,
+      })
+    }
+  }
+  const sourceFilter = new RegExp(
+    `(?:^|/)(?:${[...byPkg.values()]
+      .flatMap(({ basenames }) => [...basenames])
+      .map((basename) => basename.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+      .join('|')})(?:\\.(?:native|web|ios|android))?$`,
+  )
+  return {
+    name: 'sootsim-manifest-native-seam-redirect',
+    enforce: 'pre',
+    resolveId: {
+      filter: { id: sourceFilter },
+      handler(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: {
+    startAsync?: (options?: { silent?: boolean }) => Promise<number>
+    close?: () => Promise<void> | void
+  } | null = null
+  // the port the bridge ACTUALLY bound, which is not necessarily the one it
+  // asked for: the host scans forward from its preferred port on EADDRINUSE.
+  // the page has to be told this value. when it derived its own guess from
+  // the shell's http port instead, any box where 7668 was already taken sent
+  // the page dialing a port nobody listens on, and the only symptom was a
+  // websocket console error during boot.
+  let boundPort: Promise<number | null> | null = null
+  return {
+    name: 'sootsim-ws-bridge',
+    apply: 'serve',
+    configureServer(server) {
+      if (boundPort) 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.
+      boundPort = import('./host/bridge-host.ts')
+        .then(({ SootSimBridgeHost }) => {
+          const host = new SootSimBridgeHost({
+            port: resolveSootsimBridgePort({
+              explicitPort: process.env.SOOTSIM_BRIDGE_PORT,
+              portOffset: process.env.PORT_OFFSET,
+            }),
+            writeDevLockfile: true,
+            // resolved on every lockfile heartbeat: the address is null until
+            // vite's http server is listening, then the real bound port. lets
+            // CLI commands resolve the shell base URL from the same lockfile
+            // that names the bridge port (one world, no split-brain).
+            getShellPort: () => {
+              const addr = server.httpServer?.address()
+              if (addr && typeof addr === 'object') return addr.port
+              return server.config.server.port || null
+            },
+          })
+          bridgeHost = host
+          // startAsync, not start: the whole point is to learn the bound port.
+          return host.startAsync({ 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('[rnx] ws bridge failed to start:', message)
+          return null
+        })
+
+      // cleanup on server close (HMR restart)
+      server.httpServer?.on('close', () => {
+        if (bridgeHost) {
+          void bridgeHost.close?.()
+          bridgeHost = null
+        }
+        boundPort = null
+      })
+    },
+    // publish the bound port to the page. head-prepend so it lands before the
+    // module script that reads it. `vite build` never runs configureServer, so
+    // boundPort stays null there and nothing is injected.
+    //
+    // `||` rather than a plain assignment, and do not "simplify" it away: the
+    // playwright driver and the electron preload inject the port of the daemon
+    // they actually own via addInitScript, which runs before any page script.
+    // that value is authoritative and must win, so this dev server only ever
+    // fills in a blank — it never overwrites a port someone else published.
+    async transformIndexHtml() {
+      const port = boundPort ? await boundPort : null
+      if (port == null) return
+      return [
+        {
+          tag: 'script',
+          injectTo: 'head-prepend' as const,
+          children: `window.__sootsimBridgePort=window.__sootsimBridgePort||${port};`,
+        },
+      ]
+    },
+  }
+}
+
+// applies resolve, define, optimizeDeps config
+function sootsimConfigPlugin(
+  appDir: string,
+  extraSources: string[],
+  publishedBrowserPackages: PublishedBrowserPackage[],
+): 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 publishedBrowserEntryAliases = publishedBrowserPackages.map(
+        ({ specifier, browserEntry }) => ({
+          find: new RegExp(`^${specifier.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}$`),
+          replacement: browserEntry,
+        }),
+      )
+
+      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',
+        // these reviewed packages publish a supported browser artifact. keep
+        // them on the live graph so the exact alias below wins over their
+        // `react-native` export during dependency optimization too.
+        ...Object.values(SOOTSIM_COMPAT_PUBLISHED_BROWSER_ENTRIES).map(
+          ({ specifier }) => specifier,
+        ),
+      ]
+
+      return {
+        define: {
+          'process.env.NODE_ENV': JSON.stringify(mode),
+          'process.env.TEST_NATIVE_PLATFORM': JSON.stringify(''),
+          'process.env.TAMAGUI_TARGET': JSON.stringify('native'),
+          // expo sdk 57's winter runtime (expo/src/winter/runtime.native.ts)
+          // replaces globalThis.fetch with a native implementation whose
+          // Response class extends ExpoFetchModule.NativeResponse. that native
+          // module does not exist in a browser, so constructing any response
+          // throws `this.addListener is not a function` and every request the
+          // app makes fails. upstream's own web build keeps the platform fetch
+          // (src/winter/fetch/fetch.web.ts is `globalThis.fetch`), and this is
+          // upstream's supported switch for that — it removes the native fetch
+          // install, leaving the browser's streaming fetch in place.
+          'process.env.EXPO_PUBLIC_USE_RN_FETCH': JSON.stringify('1'),
+          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'],
+              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-published-browser-internals',
+                resolveId(source: string, importer: string | undefined) {
+                  const replacement = resolvePublishedBrowserInternal(
+                    source,
+                    importer,
+                    publishedBrowserPackages,
+                  )
+                  return replacement ? { id: replacement } : null
+                },
+              },
+              {
+                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'],
+          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,
+            ...publishedBrowserEntryAliases,
+            ...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,
+            ...(expoUiSwiftUiModifiersRealPath
+              ? [
+                  {
+                    find: '@expo/ui/swift-ui/modifiers',
+                    replacement: expoUiSwiftUiModifiersRealPath,
+                  },
+                ]
+              : []),
+            ...expoUiJetpackComposeRealAliases,
+            ...(rnghReanimatedSwipeableRealPath
+              ? [
+                  {
+                    find: /^react-native-gesture-handler\/ReanimatedSwipeable$/,
+                    replacement: rnghReanimatedSwipeableRealPath,
+                  },
+                ]
+              : []),
+            ...(rnghDrawerLayoutRealPath
+              ? [
+                  {
+                    find: /^react-native-gesture-handler\/DrawerLayout$/,
+                    replacement: rnghDrawerLayoutRealPath,
+                  },
+                ]
+              : []),
+            ...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 redirectCount = 0
+  return {
+    name: 'sootsim-react-bridge',
+    apply: 'serve',
+    enforce: 'pre',
+    resolveId: {
+      filter: { id: /^react$/ },
+      async handler(_source, importer, options) {
+        if (!importer) return null
+
+        // skip during dep scanning / SSR — only active in browser serve mode
+        if ((options as { scan?: boolean })?.scan || options?.ssr) 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',
+    resolveId: {
+      filter: { id: /^react$/ },
+      async handler(_source, importer, options) {
+        if (!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',
+    resolveId: {
+      filter: { id: /^react\/jsx-(?:dev-)?runtime$/ },
+      async handler(source, importer, options) {
+        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
+      },
+    },
+    load: {
+      filter: {
+        id: new RegExp(`^${virtualIdPrefix}sootsim:jsx-(?:dev-)?runtime:`),
+      },
+      handler(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',
+    transform: {
+      filter: {
+        id: {
+          include: /\.(?:tsx?|jsx?|mjs|cjs|mts|cts)$/,
+          exclude: /node_modules\/(?:react|react-dom|react-native|react-native-web)\//,
+        },
+        code: REANIMATED_WORKLETIZATION_REGEX,
+      },
+      async handler(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: {
+      filter: {
+        id: /\/node_modules\/.*\.[cm]?jsx?$/,
+        code: /@flow/,
+      },
+      handler(code, id) {
+        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',
+    transform: {
+      filter: {
+        id: /\/node_modules\/.*\.js$/,
+        code: /</,
+      },
+      async handler(code, id) {
+        // 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: {
+      filter: { id: /^\./ },
+      handler(source, importer) {
+        if (!importer) return null
+        if (!importer.includes('node_modules') && !isAppSource(importer)) return null
+        if (platformExts.some((ext) => source.endsWith(ext))) return null
+
+        const dir = path.dirname(importer)
+
+        const hasBaseExt = allExts.some((ext) => source.endsWith(ext))
+        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: {
+      filter: { code: /react-native/ },
+      handler(code, id) {
+        if (!id.includes('node_modules') && !isAppSource(id)) 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 {
+  // 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',
+    transform: {
+      filter: { code: /require\(|</ },
+      async handler(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(`[rnx] 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: {
+      filter: { id: /\.(?:jpg|png|gif)$/ },
+      handler(id, importer) {
+        if (importer?.includes('node_modules') || (importer && isAppSource(importer))) {
+          return '\0stub-image'
+        }
+        return null
+      },
+    },
+    load: {
+      filter: { id: new RegExp(`^${virtualIdPrefix}stub-image$`) },
+      handler() {
+        return 'export default ""'
+      },
+    },
+  }
+}