@exodus/stasis-plugins 1.0.0-beta.11 → 1.0.0-beta.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exodus/stasis-plugins",
-  "version": "1.0.0-beta.11",
+  "version": "1.0.0-beta.13",
   "description": "Bundler plugins (webpack, esbuild, Rollup, Metro) for @exodus/stasis-core",
   "type": "module",
   "exports": {
@@ -8,11 +8,14 @@
     "./esbuild": "./src/esbuild.js",
     "./rollup": "./src/rollup.js",
     "./metro": "./src/metro.js",
-    "./metro-transformer": "./src/metro-transformer.js"
+    "./metro-transformer": "./src/metro-transformer.js",
+    "./metro-native": "./src/metro-native.js"
   },
   "files": [
     "src/esbuild.js",
     "src/metro.js",
+    "src/metro-babel-transformer.js",
+    "src/metro-native.js",
     "src/metro-transformer.js",
     "src/plugins.js",
     "src/rollup.js",
@@ -33,6 +36,6 @@
   },
   "homepage": "https://github.com/PreventiveMeasures/stasis#readme",
   "dependencies": {
-    "@exodus/stasis-core": "1.0.0-beta.11"
+    "@exodus/stasis-core": "1.0.0-beta.13"
   }
 }

package/src/metro-babel-transformer.js

@@ -0,0 +1,109 @@
+import assert from 'node:assert/strict'
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { createRequire } from 'node:module'
+
+// Stands in for the project's Babel transformer (`babelTransformerPath`) under ./metro-transformer.js,
+// which swaps it in for each worker transform, to keep each import as WRITTEN in the source. Metro
+// names a dependency by the specifier Babel leaves in its output, so a plugin rewriting it (e.g.
+// babel-plugin-module-resolver mapping `#local/abc` to `./src/abc`) leaves the serializer only the
+// rewrite. This adds one plugin that records every specifier in its `pre` -- Babel runs every
+// plugin's `pre` before any plugin's visitor, so nothing has rewritten one yet -- and reads each
+// again once Babel is done, before Metro's own passes replace them in the AST, unless Babel erased
+// it. The real transformer runs as it would; its output is untouched.
+
+const require = createRequire(import.meta.url)
+
+// One per worker transform, run by ./metro-transformer.js: `babelTransformerPath` is the project's
+// (absolute), and `asWritten` maps each specifier Babel left to the ones written there.
+export const transformContext = new AsyncLocalStorage()
+
+// The nodes Metro's collectDependencies takes a specifier from: these declarations, and the calls
+// below (`import()`, `require()`, `__prefetchImport()`, `require.<member>()`).
+const DECLARATIONS = new Set(['ImportDeclaration', 'ExportNamedDeclaration', 'ExportAllDeclaration'])
+const REQUIRE_MEMBERS = new Set(['context', 'resolveWeak', 'unstable_importMaybeSync'])
+
+function isDependencyCall(callee) {
+  if (callee.type === 'Import') return true
+  if (callee.type === 'Identifier') return callee.name === 'require' || callee.name === '__prefetchImport'
+  return callee.type === 'MemberExpression' && !callee.computed &&
+    callee.object.type === 'Identifier' && callee.object.name === 'require' &&
+    callee.property.type === 'Identifier' && REQUIRE_MEMBERS.has(callee.property.name)
+}
+
+// The string `node` holds as a constant: a literal, a template with no substitutions, or a `+` of
+// such, which Metro's collectDependencies evaluates to the specifier as it does a literal.
+function constantString(node) {
+  if (node?.type === 'StringLiteral') return node.value
+  if (node?.type === 'TemplateLiteral' && node.expressions.length === 0) return node.quasis[0].value.cooked ?? undefined
+  if (node?.type !== 'BinaryExpression' || node.operator !== '+') return undefined
+  const left = constantString(node.left)
+  const right = left === undefined ? undefined : constantString(node.right)
+  return right === undefined ? undefined : left + right
+}
+
+// The specifier a dependency node holds as a constant: an import/export's source, a call's first
+// argument. A plugin rewriting it replaces the literal, never the node holding it.
+function specifierOf(node) {
+  return constantString(node.type === 'CallExpression' ? node.arguments[0] : node.source)
+}
+
+function asWrittenPlugin({ types: t }) {
+  return {
+    name: 'stasis-as-written',
+    pre(file) {
+      const { slots } = transformContext.getStore()
+      let evaluate = false
+      t.traverseFast(file.ast, (node) => {
+        if (node.type === 'CallExpression' ? !isDependencyCall(node.callee) : !DECLARATIONS.has(node.type)) return
+        const written = specifierOf(node)
+        if (written !== undefined) slots.push({ node, written })
+        else if (node.type === 'CallExpression' && node.arguments.length > 0) evaluate = true
+      })
+      // Metro takes any argument Babel evaluates to a string with confidence, one bound to a constant
+      // too (`const name = './x'; require(name)`), which only a path, and its scope, can evaluate.
+      if (!evaluate) return
+      file.path.traverse({
+        CallExpression(path) {
+          if (!isDependencyCall(path.node.callee) || specifierOf(path.node) !== undefined || path.node.arguments.length === 0) return
+          const { confident, value } = path.get('arguments.0').evaluate()
+          if (confident && typeof value === 'string') slots.push({ node: path.node, written: value })
+        },
+      })
+    },
+    visitor: {
+      // Babel exits a node only if no plugin removed it on the way in, so a declaration erased for
+      // importing types alone (`import type`, `import { type A }`, a TS import used only as a type)
+      // never exits: flow-strip-types removes it as it enters it, the TS plugin before the
+      // traversal gets there. One lowered to a require exits first: wherever it is listed,
+      // @babel/plugin-transform-modules-commonjs takes the declarations away as the program exits.
+      'ImportDeclaration|ExportNamedDeclaration|ExportAllDeclaration': {
+        exit(path) {
+          transformContext.getStore().kept.add(path.node)
+        },
+      },
+    },
+  }
+}
+
+export function transform(args) {
+  const context = transformContext.getStore()
+  assert.ok(context, 'StasisMetro: the stasis Babel transformer runs only under the stasis metro-transformer')
+  const slots = []
+  const kept = new Set()
+  Object.assign(context, { slots, kept })
+  // Once Babel is done: each specifier as it left it, from the node that held it as written.
+  const collect = (result) => {
+    for (const { node, written } of slots) {
+      if (DECLARATIONS.has(node.type) && !kept.has(node)) continue
+      // One evaluated through its scope stays as written: no plugin rewrites what isn't a literal.
+      const left = specifierOf(node) ?? (node.type === 'CallExpression' ? written : undefined)
+      if (left === undefined) continue
+      if (!context.asWritten.has(left)) context.asWritten.set(left, new Set())
+      context.asWritten.get(left).add(written)
+    }
+    return result
+  }
+  // Sync or async, as the project's transformer is (the RN one is sync).
+  const result = require(context.babelTransformerPath).transform({ ...args, plugins: [...(args.plugins ?? []), asWrittenPlugin] })
+  return typeof result?.then === 'function' ? result.then(collect) : collect(result)
+}

package/src/metro-native.js

@@ -0,0 +1,99 @@
+import { dirname, join } from 'node:path'
+
+import { classifyNativeCapture, isExcludedNativeDir, isNativeArtifact, isPodspec, isSkippedNativeWalkDir, refineNativeCapture } from '@exodus/stasis-core/util'
+
+// The native build inputs of a React Native app's packages, shared by the Metro plugin's capture and
+// `stasis bundle --metro` so the two carry the same files. Both read through `fs`:
+//   readdir(dir) -> Dirent[] (throws where `dir` isn't one), readFile(file) -> Buffer,
+//   stat(path) -> Stats, or null where nothing is there.
+
+// True if the package at `root` ships native code: an ios/ or android/ dir, or a podspec under it.
+export function looksNative(root, fs) {
+  if (fs.stat(join(root, 'ios')) !== null || fs.stat(join(root, 'android')) !== null) return true
+  return hasPodspec(root, fs)
+}
+
+// True if any *.podspec exists under `dir`, pruning the same subtrees the native walk skips.
+function hasPodspec(dir, fs) {
+  let entries
+  try {
+    entries = fs.readdir(dir)
+  } catch {
+    return false
+  }
+  for (const ent of entries) {
+    if (ent.isSymbolicLink()) continue
+    if (ent.isFile()) {
+      if (isPodspec(ent.name)) return true
+    } else if (ent.isDirectory() && !isSkippedNativeWalkDir(ent.name)) {
+      if (hasPodspec(join(dir, ent.name), fs)) return true
+    }
+  }
+  return false
+}
+
+// Each native build input in the package at `root`, walked whole, a native build reading sources
+// from anywhere in it (a podspec compiling `cpp/` beside `ios/`): every file but build output and
+// prebuilt binaries (isSkippedNativeWalkDir, isNativeArtifact), an off-platform top-level dir
+// (isExcludedNativeDir), what the shared classifier skips (the JS and TS Metro's graph owns, docs,
+// secrets) and symlinks (a cycle or escape hazard). A file `skip(file)` holds is passed over unread.
+// `resources` is the allowlist the byte-level rules consult. -> yields { file, source, action, format },
+// `action` 'code' (under the source-language `format`) or 'resource'
+export function* nativeInputs(root, fs, { resources = new Set(), skip = () => false } = {}) {
+  yield* walk(root, true)
+  function* walk(dir, atRoot) {
+    let entries
+    try {
+      entries = fs.readdir(dir)
+    } catch {
+      return // dir missing / not a directory -- nothing to walk
+    }
+    for (const ent of entries) {
+      if (ent.isSymbolicLink()) continue
+      const file = join(dir, ent.name)
+      if (ent.isDirectory()) {
+        if (!isSkippedNativeWalkDir(ent.name) && !(atRoot && isExcludedNativeDir(ent.name))) yield* walk(file, false)
+        continue
+      }
+      if (!ent.isFile() || isNativeArtifact(ent.name) || skip(file)) continue
+      const byName = classifyNativeCapture(ent.name)
+      if (byName.action === 'skip') continue
+      const source = fs.readFile(file)
+      // Byte-level rules (prebuilt binaries, binary plists) -- see refineNativeCapture.
+      const { action, format } = refineNativeCapture(byName, ent.name, source, resources)
+      if (action !== 'skip') yield { file, source, action, format }
+    }
+  }
+}
+
+// A package name as npm takes one (`name` or `@scope/name`), which a path can't climb out with.
+const PACKAGE_NAME = /^(?:@[^/\\@.][^/\\]*\/)?[^/\\@.][^/\\]*$/u
+
+// The app's packages `react-native config` links, as a native build would, read as data rather than
+// by running the CLI: each name the app's package.json lists under dependencies, peerDependencies or
+// devDependencies (the CLI's list), in the nearest node_modules up from `projectDir` that holds it
+// (as the CLI looks), where it ships native code (looksNative). What a react-native.config.js changes,
+// being code, isn't seen. -> the package dirs, as found
+export function linkedNativePackages(projectDir, fs) {
+  let manifest
+  try {
+    manifest = JSON.parse(fs.readFile(join(projectDir, 'package.json')).toString('utf8'))
+  } catch {
+    return []
+  }
+  const listed = (field) => (manifest?.[field] && typeof manifest[field] === 'object' ? Object.keys(manifest[field]) : [])
+  const names = new Set([...listed('dependencies'), ...listed('peerDependencies'), ...listed('devDependencies')])
+  const dirs = []
+  for (const name of names) {
+    if (!PACKAGE_NAME.test(name)) continue
+    for (let dir = projectDir; ; dir = dirname(dir)) {
+      const found = join(dir, 'node_modules', name)
+      if (fs.stat(found)?.isDirectory()) {
+        if (looksNative(found, fs)) dirs.push(found)
+        break
+      }
+      if (dirname(dir) === dir) break
+    }
+  }
+  return dirs
+}

package/src/metro-transformer.js

@@ -1,41 +1,60 @@
 import { Buffer } from 'node:buffer'
 import { createRequire } from 'node:module'
-import { resolve as resolvePath } from 'node:path'
-import { pathToFileURL } from 'node:url'
+import { dirname, isAbsolute, resolve as resolvePath } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
 
 import { State } from '@exodus/stasis-core/state'
+import { transformContext } from './metro-babel-transformer.js'
 
-// Companion to the StasisMetro serializer: the LOAD half of stasis for Metro. Load only READS an
-// immutable bundle and every worker reads the same bytes (no IPC), so a per-worker transformer is
-// the natural seam. Wire it permanently in metro.config.js (transformerPath); outside load mode it
-// is a transparent pass-through, and under load the serializer is too -- the mode picks the active
-// half. In load mode, wrap the user's real transformer and replace Metro's on-disk `data` with the
-// bundle's hash-verified bytes (fail-closed; out-of-scope files pass their disk bytes through).
-// KNOWN LIMITATION: does NOT build with sources absent from disk -- Metro reads + hashes each file
-// before this runs, so the guarantee is "build attested bytes, fail closed on disk drift."
+// Companion to the StasisMetro serializer, which withStasis() wires as Metro's `transformerPath`
+// whenever stasis attests the build (wire it yourself only alongside a hand-wired serializer). It
+// wraps the project's own transformer, and does two things in each worker:
+//  - keeps each import as written for the serializer, through the Babel transformer it swaps in
+//    (./metro-babel-transformer.js): a dependency Babel rewrote (e.g. through
+//    babel-plugin-module-resolver) carries the specifiers written in the source as `stasisAsWritten`;
+//  - is the LOAD half of stasis for Metro (under load the serializer only asserts edges). Load only
+//    READS an immutable bundle and every worker reads the same bytes (no IPC), so a per-worker
+//    transformer is the natural seam: it replaces Metro's on-disk `data` with the bundle's
+//    hash-verified bytes (fail-closed; out-of-scope files pass their disk bytes through).
+//    KNOWN LIMITATION: does NOT build with sources absent from disk -- Metro reads + hashes each
+//    file before this runs, so the guarantee is "build attested bytes, fail closed on disk drift."
 
 const require = createRequire(import.meta.url)
 
-// The real transformer we wrap (default matches Metro's; override for a custom TS/Babel preset).
-// Required lazily per worker so a non-load build pays nothing.
-const BASE_TRANSFORMER = process.env.EXODUS_STASIS_METRO_BASE_TRANSFORMER || 'metro-transform-worker'
+// The project's own transformer, which this one runs: the `transformerPath` withStasis() replaced,
+// handed over in Metro's transformer config, else EXODUS_STASIS_METRO_BASE_TRANSFORMER, else
+// Metro's default. Metro requires a name from its own dir, which only the project's node_modules
+// is sure to reach, so a name resolves from the project root, then from here. A base that is this
+// transformer itself (wired by hand as well) is passed over for Metro's default.
+const bases = new Map()
+function baseOf(config, projectRoot = process.cwd()) {
+  const path = config?.stasisBaseTransformerPath ?? (process.env.EXODUS_STASIS_METRO_BASE_TRANSFORMER || 'metro-transform-worker')
+  const key = `${projectRoot}\0${path}`
+  if (!bases.has(key)) {
+    const resolve = (name) => require.resolve(name, { paths: [projectRoot, dirname(fileURLToPath(import.meta.url))] })
+    let file = resolve(path)
+    if (require(file).transform === transform) file = resolve('metro-transform-worker')
+    bases.set(key, { file, transformer: require(file) })
+  }
+  return bases.get(key)
+}
 
-let base
-function getBase() {
-  base ??= require(BASE_TRANSFORMER)
-  return base
+// The config the project's transformer sees: its own, without what withStasis() handed over.
+function baseConfig({ stasisBaseTransformerPath: _, ...config } = {}) {
+  return config
 }
 
 // Per-worker load State, built once from the usual env + stasis.config.json. Non-load mode -> null
 // -> transparent pass-through, so wiring it permanently is safe. A construction failure is cached
-// and rethrown on every call -- never throw-once-then-silently-pass-through.
+// and rethrown on every call -- never throw-once-then-silently-pass-through. It never writes, so it
+// claims no write path: a capturing worker's own preload State already holds them.
 let stateInited = false
 let loadState = null
 let stateError = null
 function getLoadState() {
   if (!stateInited) {
     try {
-      const state = new State(process.cwd())
+      const state = new State(process.cwd(), { claim: false })
       loadState = state.config.loadBundle ? state : null
     } catch (err) {
       stateError = err
@@ -60,7 +79,35 @@ function inScope(state, absolute) {
   return state.inNodeModules(pathToFileURL(absolute).toString())
 }
 
-export function transform(config, projectRoot, filename, data, options) {
+// The Babel transformer swapped in for the project's, by path as metro-transform-worker requires it.
+const BABEL_TRANSFORMER = fileURLToPath(new URL('./metro-babel-transformer.js', import.meta.url))
+
+// The project's Babel transformer, absolute. Metro resolves a configured one; its default
+// ('metro-babel-transformer') stays a name, which the base transformer requires from its own dir.
+function resolveBabelTransformer(base, path) {
+  return isAbsolute(path) ? path : createRequire(base.file).resolve(path)
+}
+
+// Each dependency as the source wrote it. One named by a specifier Babel rewrote carries the ones
+// written in the source: one Metro dependency can stand for several, written apart and rewritten
+// alike (`#local/abc` and `./src/abc`). One no specifier in the source names carries
+// `stasisInserted`: Babel added it (a helper from @babel/runtime, the JSX runtime), or Metro did (its
+// asyncRequire for an `import()`, an asset's registry). A dependency written as Metro names it is
+// left as is.
+function withAsWritten(result, asWritten) {
+  if (!Array.isArray(result?.dependencies)) return result
+  const dependencies = result.dependencies.map((dep) => {
+    const written = asWritten.get(dep.name)
+    if (written === undefined) return { ...dep, stasisInserted: true }
+    if (written.size === 1 && written.has(dep.name)) return dep
+    return { ...dep, stasisAsWritten: [...written] }
+  })
+  return { ...result, dependencies }
+}
+
+export async function transform(config, projectRoot, filename, data, options) {
+  const base = baseOf(config, projectRoot)
+  config = baseConfig(config)
   const state = getLoadState()
   if (state) {
     // `filename` is project-relative in Metro's contract; resolve against projectRoot.
@@ -72,14 +119,19 @@ export function transform(config, projectRoot, filename, data, options) {
       data = Buffer.isBuffer(source) ? source : Buffer.from(source)
     }
   }
-  return getBase().transform(config, projectRoot, filename, data, options)
+  if (typeof config.babelTransformerPath !== 'string') return base.transformer.transform(config, projectRoot, filename, data, options)
+  const context = { babelTransformerPath: resolveBabelTransformer(base, config.babelTransformerPath), asWritten: new Map() }
+  const result = await transformContext.run(context, () =>
+    base.transformer.transform({ ...config, babelTransformerPath: BABEL_TRANSFORMER }, projectRoot, filename, data, options))
+  return withAsWritten(result, context.asWritten)
 }
 
-export function getCacheKey(config) {
+export function getCacheKey(config, opts) {
   // Fold in the base transformer's cache key, then add a stasis-load discriminator so load results
   // (which can differ from a disk build even when disk == bundle) don't cross-pollinate the cache.
-  // Derive the marker from the resolved load State (not the env) so config.json activation keys too.
-  const baseKey = typeof getBase().getCacheKey === 'function' ? getBase().getCacheKey(config) : ''
+  // Derive the marker from the resolved load State, which transform() goes by.
+  const { transformer } = baseOf(config, opts?.projectRoot)
+  const baseKey = typeof transformer.getCacheKey === 'function' ? transformer.getCacheKey(baseConfig(config), opts) : ''
   const state = getLoadState()
   const marker = state ? `load:${state.config.bundleFile || 'default'}` : 'off'
   return `${baseKey}$stasis-metro-transformer:${marker}`

package/src/metro.js

@@ -3,16 +3,28 @@ import { isUtf8 } from 'node:buffer'
 import { spawnSync } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { createRequire } from 'node:module'
-import { isAbsolute, join } from 'node:path'
-import { pathToFileURL } from 'node:url'
+import { dirname, isAbsolute, join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
 
 import { resolvePluginState } from './plugins.js'
+import { looksNative, nativeInputs } from './metro-native.js'
+import { diskHost } from '@exodus/stasis-core/host'
 import { State } from '@exodus/stasis-core/state'
-import { realReadFileSync, realReaddirSync } from '@exodus/stasis-core/state-util'
-import { RN_CORE_INCLUDE_FILES, classifyExtension, classifyFormat, classifyNativeCapture, isExcludedNativeDir, isNativeArtifact, isPodspec, isSkippedNativeWalkDir, refineNativeCapture, splitNodeModulesPath } from '@exodus/stasis-core/util'
+import { realReadFileSync } from '@exodus/stasis-core/state-util'
+import { RN_CORE_INCLUDE_FILES, classifyExtension, classifyFormat, splitNodeModulesPath } from '@exodus/stasis-core/util'
 
 const require = createRequire(import.meta.url)
 
+// The companion worker transformer withStasis() wires as Metro's `transformerPath`.
+const TRANSFORMER = fileURLToPath(new URL('./metro-transformer.js', import.meta.url))
+
+// A graph module's absolute path (graph modules and preModules both carry it), or undefined for a
+// synthetic/virtual one (require.context's ?ctx=, __prelude__), with no on-disk bytes to hash.
+function diskPath(module) {
+  const modPath = module?.path
+  return typeof modPath === 'string' && isAbsolute(modPath) && existsSync(modPath) ? modPath : undefined
+}
+
 // Metro's `graph.entryPoints` is a Set now, an Array before ~0.71; normalize to a Set.
 function entrySet(graph) {
   const ep = graph?.entryPoints
@@ -28,6 +40,23 @@ const AUTO_INCLUDES = [
   '@react-native-community/cli/setup_env.sh',
 ]
 
+// Metro's own transform plugins, as its transform worker names them for its cache key: the file
+// `metro-transform-plugins` resolves to from the project, else through metro and its transform
+// worker, which depend on it (a pnpm install links it only beside them). -> [] where none resolves
+function metroTransformPluginFiles(projectDir) {
+  for (const chain of [['metro-transform-plugins'], ['metro', 'metro-transform-worker', 'metro-transform-plugins']]) {
+    let file
+    try {
+      for (const name of chain) file = require.resolve(name, { paths: [file === undefined ? projectDir : dirname(file)] })
+    } catch {
+      continue
+    }
+    const { getTransformPluginCacheKeyFiles } = require(file)
+    return typeof getTransformPluginCacheKeyFiles === 'function' ? getTransformPluginCacheKeyFiles() : []
+  }
+  return []
+}
+
 // The worker-side toolchain that only Metro's transform workers load, named in both the
 // --child-process assert and the transform-cache warning so the two can't describe different sets.
 const WORKER_TOOLCHAIN = 'babel.config.js, @babel/core, the RN preset + plugins'
@@ -111,15 +140,16 @@ function metroDefaultSerializer() {
 
 // Stasis capture plugin for Metro (React Native). Hooks Metro's serializer, which runs ONCE in
 // the MAIN process with the full module graph -- a per-worker transformer's process-local State
-// could never be merged. This is the CAPTURE half; the LOAD half is the companion
-// ./metro-transformer.js. Wire both permanently (withStasis + transformerPath); the mode picks
-// the active one, and under bundle=load this serializer is a transparent pass-through.
+// could never be merged. This is the CAPTURE half; the companion ./metro-transformer.js runs in
+// the workers, recording each import as written and serving the LOAD half, and withStasis wires
+// both. Under bundle=load this serializer records nothing: Metro resolved every import itself,
+// so it asserts each edge against the bundle (see #assertEdges).
 // Capture is one-shot (dev-server rebuilds refused, see #run) and REQUIRES --child-process so the
 // worker-side toolchain (babel, RN preset) is attested (enforced in the constructor). withStasis
 // wires the stable customSerializer -- the only surface that receives preModules; serializerHook
 // is a lower-coverage fallback that never sees them. Prefer withStasis for a second reason too: a
-// hand-wired serializer leaves the Metro config -- and therefore its transform cache -- out of
-// stasis's hands (see withStasis).
+// hand-wired serializer leaves the Metro config -- and therefore its transform cache and
+// transformerPath -- out of stasis's hands (see withStasis).
 export class StasisMetro {
   #seen = new Set()
   #state
@@ -198,9 +228,12 @@ export class StasisMetro {
 
   #run(graph, preModules) {
     if (!this.#state) return
-    // bundle=load: pass through (load is served by the worker transformer). Checked BEFORE the
-    // one-shot guard -- load captures nothing and legitimately re-serializes under a dev server.
-    if (this.#state.config.loadBundle) return
+    // bundle=load: assert, don't record (the worker transformer serves the bundle's bytes). Checked
+    // BEFORE the one-shot guard -- load captures nothing and legitimately re-serializes under a dev server.
+    if (this.#state.config.loadBundle) {
+      this.#assertEdges(graph, preModules)
+      return
+    }
     // Watch/dev-server capture is unsupported: dedupe is keyed by PATH not content, so a rebuild
     // with changed bytes would emit new bytes while the bundle/lockfile keep the OLD ones. Refuse
     // the second serialization loudly (the first rebuild is the earliest refusal point Metro allows).
@@ -236,16 +269,18 @@ export class StasisMetro {
     // AFTER the graph so #seen already holds graph modules -- an auto-include that landed in the
     // graph (asyncRequire, when the app uses dynamic import()) is deduped, not re-recorded.
     this.#captureAutoIncludes()
+    this.#captureTransformPlugins()
     // AFTER the graph + auto-includes (same dedupe reason): the native pass only adds the native
     // build-input surface (podspec/gradle/sources) that no module graph carries.
     this.#captureNativeModules()
   }
 
-  // Shared epilogue for the classify-driven capture paths: record under the given format/resource.
-  // `format` null/undefined lets addFile pick (loader format for JS, byte-derived for a resource);
-  // addFile already asserts UTF-8 for a non-resource (code) source, so no guard is needed here.
-  #recordCapture(full, source, { format, resource }) {
-    this.#state.addFile(pathToFileURL(full).toString(), { source, format: format ?? undefined, resource, reason: 'metro' })
+  // Shared epilogue for the classify-driven capture paths: record under the given format/resource,
+  // attributed to `reason`. `format` null/undefined lets addFile pick (loader format for JS unless
+  // `inferFormat` is false, byte-derived for a resource); addFile already asserts UTF-8 for a
+  // non-resource (code) source, so no guard is needed here.
+  #recordCapture(full, source, { format, resource, inferFormat = true, reason = 'metro' }) {
+    this.#state.addFile(pathToFileURL(full).toString(), { source, format: format ?? undefined, resource, inferFormat, reason })
   }
 
   // Attest the AUTO_INCLUDES list. Per entry, skip: unresolvable, already-seen, or resolving
@@ -270,8 +305,34 @@ export class StasisMetro {
       // Tag from the ONE shared classifier so an auto-include agrees with any other path meeting
       // the same file (native walk, --fs): setup_env.sh -> 'shell', not a forced 'resource' that
       // would collide at the format noupsert. Unrecognized -> resource (vetted list, so no allowlist).
+      // JS (asyncRequire.js) is code Metro builds, so it takes no format, as the graph's doesn't.
       const format = classifyFormat(modPath, { content: source })
-      this.#recordCapture(modPath, source, { format, resource: format === undefined })
+      this.#recordCapture(modPath, source, { format, resource: format === undefined, inferFormat: false })
+    }
+  }
+
+  // Attest each of Metro's own transform plugins (metroTransformPluginFiles). Its transform worker
+  // hashes every one into its cache key, but loads one only as the build's options call for it
+  // (import-export-plugin under `experimentalImportSupport`, inline-requires-plugin under
+  // `inlineRequires`, constant-folding-plugin outside dev, normalizePseudoGlobals when minifying), so
+  // a capture loads them all, as Metro would: under `stasis run` the loader then records each with
+  // what it imports, so a bundle builds under any of those options. Each is recorded besides, as the
+  // Node module it is, where no loader records it, attributed to `run` as one Metro loads is: the
+  // build's toolchain, none of it the app's. One outside the project root is passed over.
+  #captureTransformPlugins() {
+    for (const file of metroTransformPluginFiles(this.#projectDir)) {
+      if (this.#seen.has(file)) continue
+      try {
+        this.#state.relative(file)
+      } catch {
+        continue
+      }
+      this.#seen.add(file)
+      try {
+        require(file)
+      } catch { /* one that can't load can't run under Metro either: its bytes are still recorded */ }
+      // Real reader: plugin bookkeeping, not a program fs read -- must not be re-recorded by --fs.
+      this.#recordCapture(file, realReadFileSync(file), { reason: 'run' })
     }
   }
 
@@ -300,7 +361,7 @@ export class StasisMetro {
       } catch {
         continue
       }
-      this.#captureNativeTree(root, true)
+      this.#captureNativeTree(root)
     }
     // RN core's `.js` build scripts the walk skips (Metro-owned by extension, but never in the graph).
     if (typeof rnPath === 'string' && isAbsolute(rnPath)) {
@@ -336,73 +397,59 @@ export class StasisMetro {
       if (!nm || nm.name === 'react-native') continue
       pkgRoots.add(nm.dir)
     }
-    return [...pkgRoots].filter((root) => this.#looksNative(root))
+    return [...pkgRoots].filter((root) => looksNative(root, diskHost))
   }
 
-  #looksNative(root) {
-    if (existsSync(join(root, 'ios')) || existsSync(join(root, 'android'))) return true
-    return this.#hasPodspec(root)
+  // Attest the native build inputs of the package at `root` (nativeInputs, shared with `stasis bundle
+  // --metro`), but what is already captured as a graph module or auto-include. Real readers: plugin
+  // bookkeeping, not re-recorded by --fs.
+  #captureNativeTree(root) {
+    for (const { file, source, action, format } of nativeInputs(root, diskHost, { resources: this.#resources, skip: (f) => this.#seen.has(f) })) {
+      this.#seen.add(file)
+      this.#recordCapture(file, source, { format, resource: action === 'resource' })
+    }
   }
 
-  // True if any *.podspec exists under `dir`, pruning the same subtrees the capture walk skips.
-  #hasPodspec(dir) {
-    let entries
-    try {
-      entries = realReaddirSync(dir, { withFileTypes: true })
-    } catch {
-      return false
-    }
-    for (const ent of entries) {
-      if (ent.isSymbolicLink()) continue
-      if (ent.isFile()) {
-        if (isPodspec(ent.name)) return true
-      } else if (ent.isDirectory() && !isSkippedNativeWalkDir(ent.name)) {
-        if (this.#hasPodspec(join(dir, ent.name))) return true
-      }
+  // bundle=load: Metro resolved every import itself (the loader and the esbuild/webpack plugins
+  // take theirs from the bundle), so before any output each edge must be the one the bundle attests
+  // -- the edges a capture records, from the same modules.
+  // A per-platform edge (a `stasis bundle --metro --platforms=...` bundle added to) is checked for the
+  // platform Metro builds.
+  #assertEdges(graph, preModules) {
+    const platform = graph.transformOptions?.platform ?? undefined
+    for (const module of [...(preModules ?? []), ...graph.dependencies.values()]) {
+      const modPath = diskPath(module)
+      if (modPath === undefined) continue
+      const url = pathToFileURL(modPath).toString()
+      for (const [specifier, target] of this.#edges(module)) this.#state.assertImport(url, specifier, target, { platform })
     }
-    return false
   }
 
-  // Recursively attest native build-input files under `dir`. Genuine readers (plugin bookkeeping,
-  // not re-recorded by --fs); symlinks not followed (cycle/escape hazard).
-  #captureNativeTree(dir, atRoot = false) {
-    let entries
-    try {
-      entries = realReaddirSync(dir, { withFileTypes: true })
-    } catch {
-      return // dir missing / not a directory -- nothing to walk
-    }
-    for (const ent of entries) {
-      if (ent.isSymbolicLink()) continue
-      const full = join(dir, ent.name)
-      if (ent.isDirectory()) {
-        // Skip build-output subtrees, Apple binary bundles + their loose per-arch slice dirs, and an
-        // off-platform toplevel dir.
-        if (!isSkippedNativeWalkDir(ent.name) && !(atRoot && isExcludedNativeDir(ent.name))) this.#captureNativeTree(full)
-        continue
+  // A module's outgoing edges, keyed as written, to `dep.absolutePath`. Metro names a dependency
+  // (`dep.data.name`) by the specifier Babel left; where a plugin rewrote it, the stasis transformer
+  // (./metro-transformer.js) carries the ones written in the source. Code and resource targets alike,
+  // as `stasis bundle --metro` and the esbuild plugin record them: an asset is resolved as code is.
+  // One the source doesn't write (`stasisInserted`: a Babel helper, the JSX runtime, Metro's
+  // asyncRequire) is no edge, as `stasis bundle --metro` has none: its file is carried, as every
+  // module of the graph is, and under load Metro resolves it unasserted.
+  #edges(module) {
+    const edges = []
+    for (const dep of module.dependencies?.values?.() ?? []) {
+      if (dep?.data?.stasisInserted === true) continue
+      const target = dep?.absolutePath
+      if (typeof target !== 'string' || !isAbsolute(target) || !existsSync(target)) continue
+      if (classifyExtension(target, this.#resources) === 'unknown') continue
+      for (const specifier of dep.data?.stasisAsWritten ?? [dep.data?.name]) {
+        if (typeof specifier === 'string') edges.push([specifier, pathToFileURL(target).toString()])
       }
-      if (!ent.isFile()) continue // sockets/FIFOs/etc. -- no attestable bytes
-      // Prebuilt binary artifacts are build output, non-deterministic -- never captured.
-      if (isNativeArtifact(ent.name)) continue
-      if (this.#seen.has(full)) continue // already captured as a graph module or auto-include
-      const byName = classifyNativeCapture(ent.name)
-      // Node-runnable JS/TS is captured via Metro's graph, not here (action==='skip').
-      if (byName.action === 'skip') continue
-      const source = realReadFileSync(full)
-      // Byte-level rules (prebuilt binaries, binary plists) -- see refineNativeCapture.
-      const { action, format } = refineNativeCapture(byName, ent.name, source, this.#resources)
-      if (action === 'skip') continue
-      this.#seen.add(full)
-      this.#recordCapture(full, source, { format, resource: action === 'resource' })
     }
+    return edges
   }
 
   #captureModules(modules, entries) {
     for (const module of modules) {
-      // module.path is the absolute path (both graph modules and preModules carry it).
-      const modPath = module?.path
-      // Skip synthetic/virtual modules (require.context's ?ctx=, __prelude__): no on-disk bytes to hash.
-      if (typeof modPath !== 'string' || !isAbsolute(modPath) || !existsSync(modPath)) continue
+      const modPath = diskPath(module)
+      if (modPath === undefined) continue
 
       const kind = classifyExtension(modPath, this.#resources)
       if (kind === 'unknown') {
@@ -412,17 +459,7 @@ export class StasisMetro {
         )
       }
       const url = pathToFileURL(modPath).toString()
-
-      // Outgoing edges: as-written specifier is `dep.data.name`, target `dep.absolutePath`.
-      // Only code targets get an edge (resource imports are captured as files, no edge).
-      for (const dep of module.dependencies?.values?.() ?? []) {
-        const target = dep?.absolutePath
-        const specifier = dep?.data?.name
-        if (typeof target !== 'string' || !isAbsolute(target) || !existsSync(target)) continue
-        if (typeof specifier !== 'string') continue
-        if (classifyExtension(target, this.#resources) !== 'code') continue
-        this.#state.addImport(url, specifier, pathToFileURL(target).toString())
-      }
+      for (const [specifier, target] of this.#edges(module)) this.#state.addImport(url, specifier, target)
 
       if (this.#seen.has(modPath)) continue
       this.#seen.add(modPath)
@@ -434,14 +471,17 @@ export class StasisMetro {
       if (kind === 'code') {
         assert.ok(isUtf8(source), `StasisMetro: code-classified file has non-UTF-8 bytes: ${modPath}`)
       }
-      this.#state.addFile(url, { source, isEntry: entries.has(modPath), resource: kind === 'resource', reason: 'metro' })
+      // No format for a code file: Metro transforms it from source, so Node's module/commonjs isn't
+      // what runs (a resource still takes its byte-derived one).
+      this.#state.addFile(url, { source, isEntry: entries.has(modPath), resource: kind === 'resource', inferFormat: false, reason: 'metro' })
     }
   }
 }
 
 // Idiomatic Metro-config wrapper: returns a new config with `serializer.customSerializer` wired
 // so stasis captures the graph + preModules while your existing serializer (or Metro's default)
-// still produces the bundle, and with Metro's transform cache dropped so the workers really run.
+// still produces the bundle, with Metro's transform cache dropped so the workers really run, and
+// with Metro's transformer run through stasis's (./metro-transformer.js).
 // Pure -- returns a new object, doesn't mutate `config`.
 export function withStasis(config = {}, options = {}) {
   const stasis = new StasisMetro(options, { ownsConfig: true })
@@ -474,9 +514,18 @@ export function withStasis(config = {}, options = {}) {
       'transform skips the worker, leaving the toolchain it loads unattested'
     )
   }
+  // The workers run the project's transformer through stasis's, which records each import as
+  // written, before Babel rewrites it, and serves bundle=load: handed over in `transformer`, which
+  // Metro passes to each worker's transformer as is. In every active mode, load included, so the
+  // modules a worker loads are the same when recorded and when replayed.
+  const transformer = stasis.needsTransforms && {
+    transformerPath: TRANSFORMER,
+    transformer: { ...config.transformer, stasisBaseTransformerPath: config.transformerPath },
+  }
   return {
     ...config,
     ...(dropCache && { cacheStores: [] }),
+    ...transformer,
     serializer: {
       ...config.serializer,
       customSerializer: stasis.customSerializer(existing),