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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exodus/stasis-plugins",
-  "version": "1.0.0-beta.13",
+  "version": "1.0.0-beta.14",
   "description": "Bundler plugins (webpack, esbuild, Rollup, Metro) for @exodus/stasis-core",
   "type": "module",
   "exports": {
@@ -36,6 +36,6 @@
   },
   "homepage": "https://github.com/PreventiveMeasures/stasis#readme",
   "dependencies": {
-    "@exodus/stasis-core": "1.0.0-beta.13"
+    "@exodus/stasis-core": "1.0.0-beta.14"
   }
 }

package/src/esbuild.js

@@ -4,7 +4,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url'
 import assert from 'node:assert/strict'
 
 import { Bundle } from '@exodus/stasis-core/bundle'
-import { resolvePluginState } from './plugins.js'
+import { attestedImport, resolvePluginState, unsupportedExtension } from './plugins.js'
 import { State } from '@exodus/stasis-core/state'
 // Pre-patch snapshot, not `import { readFile }`: under --fs=async that builtin is patched, and
 // this plugin loads after, so a direct import would route esbuild's reads through the capture hook.
@@ -71,6 +71,8 @@ export class StasisEsbuild {
   #resources
   #loaders
   #transform
+  #resource
+  #platform
   #emptyModule  // URL of the empty module disabled imports point at, once capture recorded it
   #browserScopes = new Map()  // dir -> Promise<[{ dir, keys }]>: `false` keys of it and its ancestors
   #probes = new Map()  // [kind, resolveDir, specifier] -> Promise<disabled path | null>
@@ -79,7 +81,7 @@ export class StasisEsbuild {
   // the second is refused in onStart.
   #captureBuildCount = 0
 
-  constructor(options = {}, { loaders, transform } = {}) {
+  constructor(options = {}, { loaders, transform, resource, platform } = {}) {
     // A caller that owns a State (e.g. `stasis build`) can pass it directly; a foreign-copy State
     // fails closed via the instanceof miss.
     const state = options instanceof State
@@ -95,6 +97,12 @@ export class StasisEsbuild {
     // (source, { path, loader }) => { contents, loader } | undefined, may be async. Never
     // runs at capture -- capture attests the file's raw bytes.
     this.#transform = transform
+    // Load-mode-only module builder for a resource no loader override names (e.g. `stasis build
+    // --metro`'s asset module): (source, { path }) => { contents, loader } | undefined, may be async.
+    this.#resource = resource
+    // Load mode: the platform whose target a --metro per-platform edge resolves to (none fails
+    // closed on one, as plain bundle=load does).
+    this.#platform = platform
   }
 
   // esbuild loader for a served file: configured override, else derived from extension
@@ -223,16 +231,11 @@ export class StasisEsbuild {
         // keys attributed edges under specific conditions the plugin's `*` lookup won't match.
         // The edge is looked up even for a built-in's name: a browser build records `fs` when a
         // `browser` field disables it (an edge to the empty module) or a package by that name serves it.
-        try {
-          ;({ url } = this.#state.getImport(parentURL, specifier, { importAttributes: attrs }))
-        } catch (err) {
-          // No attested edge -- at a successful capture that's a built-in or another EXTERNAL (never
-          // recorded as an edge), so hand it back to esbuild, which externalizes it as without us
-          // (built-ins under platform:'node'). File BYTES still fail closed at onLoad.
-          // A non-MODULE_NOT_FOUND error is a real fault -- rethrow.
-          if (err?.code === 'ERR_MODULE_NOT_FOUND') return undefined
-          throw err
-        }
+        // No attested edge (a built-in, or another external): esbuild's, which externalizes it as
+        // without us (built-ins under platform:'node'). File BYTES still fail closed at onLoad.
+        const attested = attestedImport(this.#state, parentURL, specifier, { importAttributes: attrs, platform: this.#platform })
+        if (attested === undefined) return undefined
+        ;({ url } = attested)
       }
       const format = this.#state.getFormat(url)
       const isEmpty = url === pathToFileURL(resolvePath(this.#state.root, EMPTY_MODULE_PATH)).toString()
@@ -268,11 +271,7 @@ export class StasisEsbuild {
       if (res.namespace === 'file' && !res.external) {
         kind = classifyExtension(res.path, this.#resources)
         if (kind === 'unknown') {
-          return {
-            errors: [{
-              text: `StasisEsbuild: unsupported extension for '${res.path}' -- add its extension or filename to the plugin's resources option or stop importing it`,
-            }],
-          }
+          return { errors: [{ text: unsupportedExtension('StasisEsbuild', `'${res.path}'`) }] }
         }
         // Record the edge for BOTH code and resource targets (never entries): load mode resolves
         // every specifier through this map, so a resource with no edge would miss at bundle=load and
@@ -305,11 +304,15 @@ export class StasisEsbuild {
         // one a CSS @import, `composes` or url() accepts, so one empty module serves JS and CSS importers.
         if (kind === 'empty') return { contents: source, loader: 'empty' }
         if (kind === 'resource') {
-          // Plugin-provided contents with no `loader` default to `js` (esbuild applies the build's
-          // per-extension loader only on its own load path), so replay the configured loader from
-          // initialOptions.loader. No configured loader fails symmetrically with a capture build.
-          const loader = initialOptions.loader?.[extname(path)]
-          return loader ? { contents: source, loader } : { contents: source }
+          // A loader override for its extension (`stasis build --loader=.png:dataurl`) wins; else the
+          // resource hook's module, where it builds one.
+          const override = this.#loaders.get(extname(path))
+          if (override) return { contents: source, loader: override }
+          const built = await this.#resource?.(source, { path })
+          if (built) return built
+          // Else the loader esbuild's own load path takes (the build's `loader` option, else its default
+          // for the extension), so a resource none loads fails as at capture, not parsed as js.
+          return { contents: source, loader: 'default' }
         }
         const loader = this.#loaderFor(path)
         // A transform that declines (undefined) serves the attested bytes unchanged.

package/src/metro-babel-transformer.js

@@ -8,13 +8,16 @@ import { createRequire } from 'node:module'
 // 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.
+// again once Babel is done, before Metro's own passes replace them in the AST, but one importing
+// types alone that Babel erased. One a plugin consumed, gone from Babel's output with nothing left
+// naming its module (`require('./messages.po')`, which @exodus/i18n's plugin-inline-po reads and
+// inlines), it keeps apart. 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.
+// (absolute), `asWritten` maps each specifier Babel left to the ones written there, and `consumed`
+// holds each one a plugin consumed, as Babel last left it.
 export const transformContext = new AsyncLocalStorage()
 
 // The nodes Metro's collectDependencies takes a specifier from: these declarations, and the calls
@@ -22,7 +25,10 @@ export const transformContext = new AsyncLocalStorage()
 const DECLARATIONS = new Set(['ImportDeclaration', 'ExportNamedDeclaration', 'ExportAllDeclaration'])
 const REQUIRE_MEMBERS = new Set(['context', 'resolveWeak', 'unstable_importMaybeSync'])
 
-function isDependencyCall(callee) {
+// Whether `node` is one of them.
+function isDependency(node) {
+  if (node.type !== 'CallExpression') return DECLARATIONS.has(node.type)
+  const { callee } = node
   if (callee.type === 'Import') return true
   if (callee.type === 'Identifier') return callee.name === 'require' || callee.name === '__prefetchImport'
   return callee.type === 'MemberExpression' && !callee.computed &&
@@ -47,16 +53,43 @@ function specifierOf(node) {
   return constantString(node.type === 'CallExpression' ? node.arguments[0] : node.source)
 }
 
+const TYPE_KINDS = new Set(['type', 'typeof'])
+
+// A declaration of types alone, which Babel may erase, and then it names no module Metro depends on:
+// Flow's `import type`/`import typeof`, TypeScript's `import type`, `export type ... from`, and one
+// whose every specifier is a type (`import { type A }`, which TypeScript's `onlyRemoveTypeImports`
+// keeps as `import {} from`).
+function typesOnly(node) {
+  if (TYPE_KINDS.has(node.importKind ?? node.exportKind)) return true
+  const specifiers = node.specifiers ?? []
+  return specifiers.length > 0 && specifiers.every((specifier) => TYPE_KINDS.has(specifier.importKind ?? specifier.exportKind))
+}
+
+// The dependency nodes in Babel's output, and the specifiers they hold as constants.
+function dependenciesLeft(t, ast) {
+  const nodes = new Set()
+  const specifiers = new Set()
+  t.traverseFast(ast, (node) => {
+    if (!isDependency(node)) return
+    nodes.add(node)
+    const specifier = specifierOf(node)
+    if (specifier !== undefined) specifiers.add(specifier)
+  })
+  return { nodes, specifiers }
+}
+
 function asWrittenPlugin({ types: t }) {
   return {
     name: 'stasis-as-written',
     pre(file) {
-      const { slots } = transformContext.getStore()
+      const context = transformContext.getStore()
+      context.types = t
+      const { slots } = context
       let evaluate = false
       t.traverseFast(file.ast, (node) => {
-        if (node.type === 'CallExpression' ? !isDependencyCall(node.callee) : !DECLARATIONS.has(node.type)) return
+        if (!isDependency(node)) return
         const written = specifierOf(node)
-        if (written !== undefined) slots.push({ node, written })
+        if (written !== undefined) slots.push({ node, written, types: node.type !== 'CallExpression' && typesOnly(node) })
         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
@@ -64,18 +97,17 @@ function asWrittenPlugin({ types: t }) {
       if (!evaluate) return
       file.path.traverse({
         CallExpression(path) {
-          if (!isDependencyCall(path.node.callee) || specifierOf(path.node) !== undefined || path.node.arguments.length === 0) return
+          if (!isDependency(path.node) || 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.
+      // Babel exits a node only if no plugin removed it on the way in, so a declaration of types
+      // alone that Babel erased never exits: flow-strip-types removes it as it enters it, the TS
+      // plugin before the traversal gets there. One it kept (`import {} from` under
+      // `onlyRemoveTypeImports`) exits, still naming its module.
       'ImportDeclaration|ExportNamedDeclaration|ExportAllDeclaration': {
         exit(path) {
           transformContext.getStore().kept.add(path.node)
@@ -91,15 +123,24 @@ export function transform(args) {
   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.
+  // Once Babel is done: each specifier as it left it, from the node that held it as written, but a
+  // declaration of types alone Babel erased. One a plugin replaced keeps it too: lowered to a require
+  // (the commonjs transform), or split in two (`export * as ns from` into an import and an export,
+  // the export-namespace-from transform), it names the same module, its specifier as rewritten
+  // before (module-resolver rewrites every one as the program enters). One gone from the output,
+  // with no node there naming its module, a plugin consumed in its stead.
   const collect = (result) => {
-    for (const { node, written } of slots) {
-      if (DECLARATIONS.has(node.type) && !kept.has(node)) continue
+    const left = result?.ast && context.types ? dependenciesLeft(context.types, result.ast) : null
+    for (const { node, written, types } of slots) {
+      if (types && !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)
+      const specifier = specifierOf(node) ?? written
+      if (left !== null && !left.nodes.has(node) && !left.specifiers.has(specifier)) {
+        context.consumed.add(specifier)
+        continue
+      }
+      if (!context.asWritten.has(specifier)) context.asWritten.set(specifier, new Set())
+      context.asWritten.get(specifier).add(written)
     }
     return result
   }

package/src/metro-native.js

@@ -1,54 +1,168 @@
-import { dirname, join } from 'node:path'
+import { isUtf8 } from 'node:buffer'
+import { basename, dirname, join, posix, relative, sep } from 'node:path'
 
-import { classifyNativeCapture, isExcludedNativeDir, isNativeArtifact, isPodspec, isSkippedNativeWalkDir, refineNativeCapture } from '@exodus/stasis-core/util'
+import { readJson } from '@exodus/stasis-core/bundle-util'
+import { diskHost } from '@exodus/stasis-core/host'
+import { CODE_EXTENSIONS, classifyFormat, isAutoExcludedDir, isBinaryPlist, isDotEnvFile, isExcludedNativeFile, isNativeArtifact, nameFormat, pathExt, toPosix } 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.
 
+// Files a React Native build requires that neither Metro's module graph nor a run's loader carries,
+// each as a require() of it from the project root resolves it (one that doesn't, or lies outside the
+// root, is passed over), tagged by the shared classifier: setup_env.sh, which the React Native CLI runs
+// (`execFileSync`) as every command of it starts, `react-native config` the Metro plugin runs included.
+// The run's toolchain, none of it the app's: the Metro plugin records each under `run`, `stasis bundle
+// --metro` as its own (`bundle`).
+export const AUTO_INCLUDES = ['@react-native-community/cli/setup_env.sh']
+
+// The entries of the directory `dir`, none where it's missing or no directory.
+export function listing(dir, fs) {
+  try {
+    return fs.readdir(dir)
+  } catch {
+    return []
+  }
+}
+
+// RN core build scripts the native walk would defer to Metro as `.js`, but Metro never sees them (RN's
+// podspecs invoke them at pod-install). Project-relative, so react-native's `exports` can't hide them.
+export const RN_CORE_INCLUDE_FILES = ['sdks/hermes-engine/utils/replace_hermes_version.js']
+
+// Discovered by name: RN scatters podspecs in subdirs `react-native config` misses.
+function isPodspec(name) {
+  return name.endsWith('.podspec') || name.endsWith('.podspec.json')
+}
+
+// The off-platform top-level dir of a native package, which no build on this host compiles.
+export function isExcludedNativeDir(name, { win32 = process.platform === 'win32' } = {}) {
+  return !win32 && name === 'windows'
+}
+
+// Dirs the NATIVE walks (Metro plugin + the static --metro bundler) skip, on top of the shared set:
+// nested packages (attested separately) and regenerated build output -- none is a build input.
+const NATIVE_BUILD_OUTPUT_DIRS = new Set(['node_modules', 'build', '.gradle', '.cxx', 'Pods', 'DerivedData'])
+function isSkippedNativeWalkDir(name) {
+  return NATIVE_BUILD_OUTPUT_DIRS.has(name) || isAutoExcludedDir(name) || isNativeArtifact(name)
+}
+
+// An extensionless non-UTF-8 file is a compiled tool (Hermes' `hermesc`), never source -- skipped.
+function isExtensionlessBinary(name, content) {
+  return pathExt(name) === '' && Buffer.isBuffer(content) && !isUtf8(content)
+}
+
+// The Metro native capture's policy view. Returns { action, format }: 'code' (a native build input),
+// 'skip' (excluded noise, or a JS-family file matched BY EXTENSION -- Metro owns those), else 'resource'.
+export function classifyNativeCapture(name, { win32 = process.platform === 'win32', content } = {}) {
+  // `.env` files carry secrets: an automated capture must never sweep them in.
+  if (isExcludedNativeFile(name, { win32 }) || isDotEnvFile(name)) return { action: 'skip' }
+  // Name-matched code is always a native build input, even when its tag is a Node format the JS
+  // graph would otherwise own.
+  const byName = nameFormat(name)
+  if (byName !== undefined) return { action: 'code', format: byName }
+  if (CODE_EXTENSIONS.has(pathExt(name))) return { action: 'skip' }
+  const format = classifyFormat(name, { content })
+  return format === undefined ? { action: 'resource' } : { action: 'code', format }
+}
+
+// The byte-level half of the native classification, refining what classifyNativeCapture derived from the
+// NAME. Both rules only ever demote. A 'resource' carries no format: storage derives base64 from bytes.
+export function refineNativeCapture(classified, name, content, resources = new Set()) {
+  if (isExtensionlessBinary(name, content)) return { action: 'skip' }
+  if (isBinaryPlist(name, content)) return { action: resources.has('plist') ? 'resource' : 'skip' }
+  return classified
+}
+
+// A file name as Metro's AssetPaths reads it (parsePlatformFilePath, then parseBaseName): its asset,
+// `${name}.${type}` less any scale (`a@2x.png` is `a.png`'s), its scale (`resolution`, 1 where it
+// names none), and its platform where it names `platform` (`a.ios.png`; another's, `a.android.png`,
+// is an asset of its own). -> { asset, name, type, resolution, platform }, or null for a name with no type
+const METRO_PLATFORM_FILE = /^(.+?)(?:\.([^.]+))?\.([^.]+)$/u
+const METRO_ASSET_SCALE = /^(.+?)(?:@([\d.]+)x)?$/u
+export function parseMetroAssetName(name, platform) {
+  const match = METRO_PLATFORM_FILE.exec(name)
+  if (match === null) return null
+  const [, base, suffix, type] = match
+  const ofPlatform = suffix !== undefined && suffix === platform
+  const [, root, scale] = METRO_ASSET_SCALE.exec(suffix === undefined || ofPlatform ? base : `${base}.${suffix}`)
+  const resolution = Number.parseFloat(scale)
+  return { asset: `${root}.${type}`, name: root, type, resolution: Number.isNaN(resolution) ? 1 : resolution, platform: ofPlatform ? platform : null }
+}
+
+// What a file's stat answers to metroAssetFiles, for a file a listing names but the disk lacks.
+export const FILE_STAT = { isFile: () => true }
+
+// The files `state` (a loaded State) carries, as a directory listing of them (metroAssetFiles' host):
+// an asset's files as captured.
+export function bundleDirHost(state) {
+  const dirs = Map.groupBy([...state.sources.keys(), ...state.resources.keys()], (rel) => posix.dirname(rel))
+  return {
+    readdir: (dir) => (dirs.get(toPosix(state.relative(dir)) || '.') ?? []).map((rel) => ({ name: posix.basename(rel) })),
+    stat: () => FILE_STAT,
+  }
+}
+
+// Metro's record of the asset module `path` (its Assets' getAbsoluteAssetRecord): the files it reads
+// to build the module (its `scales` and `hash`) and copies out with it. In `path`'s directory, each of
+// the asset's name and type at any scale (`a.png`, `a@2x.png`, `a@3x.png`): those for `platform`
+// (`a.ios.png`, `a@3x.ios.png`) where it has any, else those for none. -> absolute paths
+export function metroAssetFiles(path, platform = null, host = diskHost) {
+  const own = parseMetroAssetName(basename(path), platform)
+  if (own === null) return []
+  const dir = dirname(path)
+  const byPlatform = new Map()
+  for (const { name } of host.readdir(dir)) {
+    const parsed = parseMetroAssetName(name, platform)
+    if (parsed?.asset !== own.asset || host.stat(join(dir, name))?.isFile() !== true) continue
+    if (!byPlatform.has(parsed.platform)) byPlatform.set(parsed.platform, [])
+    byPlatform.get(parsed.platform).push(join(dir, name))
+  }
+  return (platform === null ? undefined : byPlatform.get(platform)) ?? byPlatform.get(null) ?? []
+}
+
 // 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)
+  return fs.stat(join(root, 'ios')) !== null || fs.stat(join(root, 'android')) !== null || 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
+  return listing(dir, fs).some((ent) => !ent.isSymbolicLink() &&
+    (ent.isFile() ? isPodspec(ent.name) : ent.isDirectory() && !isSkippedNativeWalkDir(ent.name) && hasPodspec(join(dir, ent.name), fs)))
 }
 
+// The specs React Native's codegen parses in a package's codegen sources (codegenSources), as its own
+// filter takes them (filterJSFile): a JS or TS module named `Native…` or `…NativeComponent` (a platform's
+// `.ios`/`.android` one too), but a type declaration.
+const isCodegenSpec = (name) => /^(?:Native.+|.+NativeComponent)/u.test(name) && /\.(?:jsx?|tsx?)$/u.test(name) && !name.endsWith('.d.ts')
+
 // 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'
+// secrets) and symlinks (a cycle or escape hazard). And the specs of its codegen sources
+// (codegenSources, isCodegenSpec), as code with no format, as Metro's code has none: none of the
+// other JS there (a react-native.config.js, the package's build, where `jsSrcsDir` is its root), which
+// codegen never reads. 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`,
+// none for JS and TS) 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 dir of codegenSources(root, fs)) yield* sources(dir)
+  function* sources(dir) {
+    for (const ent of listing(dir, fs)) {
+      // None in a dot, node_modules or tests directory, as codegen skips one.
+      if (ent.isSymbolicLink() || ent.name.startsWith('.') || ent.name === 'node_modules' || ent.name.startsWith('__tests')) continue
+      const file = join(dir, ent.name)
+      if (ent.isDirectory()) yield* sources(file)
+      else if (ent.isFile() && isCodegenSpec(ent.name) && !skip(file)) yield { file, source: fs.readFile(file), action: 'code', format: undefined }
     }
-    for (const ent of entries) {
+  }
+  function* walk(dir, atRoot) {
+    for (const ent of listing(dir, fs)) {
       if (ent.isSymbolicLink()) continue
       const file = join(dir, ent.name)
       if (ent.isDirectory()) {
@@ -66,21 +180,39 @@ export function* nativeInputs(root, fs, { resources = new Set(), skip = () => fa
   }
 }
 
+// The directories of the package at `root` its package.json's `codegenConfig` names as its JS sources
+// (`jsSrcsDir`, or each of its `libraries`', as React Native's own names `src`), each reached within it
+// through no symlink, as the walk follows none: React Native's codegen parses the specs there to
+// generate the native code a build compiles (a missing one fails it), and `react-native config` reads
+// them for the components they declare (`codegenNativeComponent`, in a `…NativeComponent` spec).
+// -> the absolute dirs
+function codegenSources(root, fs) {
+  const config = readJson(join(root, 'package.json'), fs)?.codegenConfig
+  const named = [config?.jsSrcsDir, ...(Array.isArray(config?.libraries) ? config.libraries.map((library) => library?.jsSrcsDir) : [])]
+  return named.filter((dir) => typeof dir === 'string' && dir !== '').map((dir) => packageDir(root, dir, fs)).filter((dir) => dir !== null)
+}
+
+// The directory `rel` names in the package at `root`, each step of it one (a link's entry is none, and
+// none is `..`). -> its absolute path, or null
+function packageDir(root, rel, fs) {
+  let dir = root
+  for (const name of relative(root, join(root, rel)).split(sep)) {
+    if (name === '') continue
+    if (!listing(dir, fs).some((ent) => ent.name === name && ent.isDirectory())) return null
+    dir = join(dir, name)
+  }
+  return dir
+}
+
 // 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 []
-  }
+// The app's packages `react-native config` reads, 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). What
+// a react-native.config.js changes, being code, isn't seen. -> the package dirs, as found
+export function linkedPackages(projectDir, fs) {
+  const manifest = readJson(join(projectDir, 'package.json'), fs)
   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 = []
@@ -89,7 +221,7 @@ export function linkedNativePackages(projectDir, fs) {
     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)
+        dirs.push(found)
         break
       }
       if (dirname(dir) === dir) break
@@ -97,3 +229,9 @@ export function linkedNativePackages(projectDir, fs) {
   }
   return dirs
 }
+
+// Of those, the ones `react-native config` links, as a native build would: those that ship native
+// code (looksNative). -> the package dirs, as found
+export function linkedNativePackages(projectDir, fs) {
+  return linkedPackages(projectDir, fs).filter((dir) => looksNative(dir, fs))
+}

package/src/metro-transformer.js

@@ -4,6 +4,7 @@ import { dirname, isAbsolute, resolve as resolvePath } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 
 import { State } from '@exodus/stasis-core/state'
+import { servedByBundle } from '@exodus/stasis-core/state-util'
 import { transformContext } from './metro-babel-transformer.js'
 
 // Companion to the StasisMetro serializer, which withStasis() wires as Metro's `transformerPath`
@@ -11,7 +12,8 @@ import { transformContext } from './metro-babel-transformer.js'
 // 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`;
+//    babel-plugin-module-resolver) carries the specifiers written in the source as `stasisAsWritten`,
+//    and the output, the ones of the imports a Babel plugin consumed as `stasisConsumed`;
 //  - 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
@@ -48,35 +50,18 @@ function baseConfig({ stasisBaseTransformerPath: _, ...config } = {}) {
 // -> 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. 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
+let loaded
 function getLoadState() {
-  if (!stateInited) {
+  if (loaded === undefined) {
     try {
       const state = new State(process.cwd(), { claim: false })
-      loadState = state.config.loadBundle ? state : null
-    } catch (err) {
-      stateError = err
-      throw err
-    } finally {
-      stateInited = true
+      loaded = { state: state.config.loadBundle ? state : null }
+    } catch (error) {
+      loaded = { error }
     }
   }
-  if (stateError) throw stateError
-  return loadState
-}
-
-// True iff `absolute` is in scope for load mode. state.relative throws outside the project root
-// (out-of-scope: system files, scratch) -> defer to disk. Mirrors the webpack plugin's inScope.
-function inScope(state, absolute) {
-  try {
-    state.relative(absolute)
-  } catch {
-    return false
-  }
-  if (state.config.full) return true
-  return state.inNodeModules(pathToFileURL(absolute).toString())
+  if ('error' in loaded) throw loaded.error
+  return loaded.state
 }
 
 // The Babel transformer swapped in for the project's, by path as metro-transform-worker requires it.
@@ -93,8 +78,10 @@ function resolveBabelTransformer(base, path) {
 // 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) {
+// left as is. The imports a Babel plugin consumed, read and inlined in their stead
+// (`require('./messages.po')`, @exodus/i18n's plugin-inline-po), no dependency of Metro's, ride on
+// the output Metro keeps for the module, its first entry's data, as `stasisConsumed`.
+function withAsWritten(result, { asWritten, consumed }) {
   if (!Array.isArray(result?.dependencies)) return result
   const dependencies = result.dependencies.map((dep) => {
     const written = asWritten.get(dep.name)
@@ -102,7 +89,9 @@ function withAsWritten(result, asWritten) {
     if (written.size === 1 && written.has(dep.name)) return dep
     return { ...dep, stasisAsWritten: [...written] }
   })
-  return { ...result, dependencies }
+  if (consumed.size === 0 || !Array.isArray(result.output) || result.output.length === 0) return { ...result, dependencies }
+  const [first, ...rest] = result.output
+  return { ...result, dependencies, output: [{ ...first, data: { ...first.data, stasisConsumed: [...consumed] } }, ...rest] }
 }
 
 export async function transform(config, projectRoot, filename, data, options) {
@@ -112,7 +101,7 @@ export async function transform(config, projectRoot, filename, data, options) {
   if (state) {
     // `filename` is project-relative in Metro's contract; resolve against projectRoot.
     const absolute = resolvePath(projectRoot, filename)
-    if (inScope(state, absolute)) {
+    if (servedByBundle(state, absolute)) {
       // getFile re-verifies the hash and throws on a file the bundle doesn't carry (fail-closed,
       // no disk fallback). Code sources come back as strings; resources as Buffers.
       const { source } = state.getFile(pathToFileURL(absolute).toString())
@@ -120,10 +109,10 @@ export async function 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 context = { babelTransformerPath: resolveBabelTransformer(base, config.babelTransformerPath), asWritten: new Map(), consumed: new Set() }
   const result = await transformContext.run(context, () =>
     base.transformer.transform({ ...config, babelTransformerPath: BABEL_TRANSFORMER }, projectRoot, filename, data, options))
-  return withAsWritten(result, context.asWritten)
+  return withAsWritten(result, context)
 }
 
 export function getCacheKey(config, opts) {

package/src/metro.js

@@ -1,17 +1,17 @@
 import assert from 'node:assert/strict'
-import { isUtf8 } from 'node:buffer'
+import { Buffer, isUtf8 } from 'node:buffer'
 import { spawnSync } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { createRequire } from 'node:module'
-import { dirname, isAbsolute, join } from 'node:path'
+import { dirname, isAbsolute, join, resolve } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 
-import { resolvePluginState } from './plugins.js'
-import { looksNative, nativeInputs } from './metro-native.js'
+import { resolvePluginState, unsupportedExtension } from './plugins.js'
+import { AUTO_INCLUDES, FILE_STAT, RN_CORE_INCLUDE_FILES, bundleDirHost, looksNative, metroAssetFiles, nativeInputs } from './metro-native.js'
 import { diskHost } from '@exodus/stasis-core/host'
 import { State } from '@exodus/stasis-core/state'
-import { realReadFileSync } from '@exodus/stasis-core/state-util'
-import { RN_CORE_INCLUDE_FILES, classifyExtension, classifyFormat, splitNodeModulesPath } from '@exodus/stasis-core/util'
+import { inScope, realReadFileSync } from '@exodus/stasis-core/state-util'
+import { classifyExtension, classifyFormat, isPathWithin, nodeExtFormat, splitNodeModulesPath } from '@exodus/stasis-core/util'
 
 const require = createRequire(import.meta.url)
 
@@ -33,13 +33,6 @@ function entrySet(graph) {
   return new Set()
 }
 
-// Files a React Native build requires that Metro's module graph never carries; attested (tagged by
-// the shared classifier, see #captureAutoIncludes) when they resolve from the project.
-const AUTO_INCLUDES = [
-  'metro-runtime/src/modules/asyncRequire.js',
-  '@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
@@ -152,6 +145,10 @@ function metroDefaultSerializer() {
 // transformerPath -- out of stasis's hands (see withStasis).
 export class StasisMetro {
   #seen = new Set()
+  // The project root's real path, once a consumed resource needs it (#consumedResources).
+  #realRoot
+  // Under load, the bundle's files as a directory listing, once an asset needs them (#bundleDirHost).
+  #bundleDirs
   #state
   #resources
 
@@ -262,12 +259,11 @@ export class StasisMetro {
 
   #capture(graph, preModules) {
     const entries = entrySet(graph)
+    const platform = graph.transformOptions?.platform ?? null
     // preModules first (Metro's prepended polyfills/runtime; synthetic ones like __prelude__ are
     // skipped by the existsSync guard below), then the app graph.
-    if (preModules) this.#captureModules(preModules, entries)
-    this.#captureModules(graph.dependencies.values(), entries)
-    // 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.
+    if (preModules) this.#captureModules(preModules, entries, platform)
+    this.#captureModules(graph.dependencies.values(), entries, platform)
     this.#captureAutoIncludes()
     this.#captureTransformPlugins()
     // AFTER the graph + auto-includes (same dedupe reason): the native pass only adds the native
@@ -283,8 +279,9 @@ export class StasisMetro {
     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
-  // outside the project root (keys are root-relative). Attested entries ride the normal addFile path.
+  // Attest the AUTO_INCLUDES list (./metro-native.js, shared with `stasis bundle --metro`). Per entry,
+  // skip: unresolvable, already-seen, or resolving outside the project root (keys are root-relative).
+  // Attested entries ride the normal addFile path.
   #captureAutoIncludes() {
     for (const specifier of AUTO_INCLUDES) {
       let modPath
@@ -293,21 +290,15 @@ export class StasisMetro {
       } catch {
         continue
       }
-      if (this.#seen.has(modPath)) continue
-      try {
-        this.#state.relative(modPath)
-      } catch {
-        continue
-      }
+      if (this.#seen.has(modPath) || !this.#within(modPath)) continue
       this.#seen.add(modPath)
       // Real reader: plugin bookkeeping, not a program fs read -- must not be re-recorded by --fs.
       const source = realReadFileSync(modPath)
       // 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, inferFormat: false })
+      this.#recordCapture(modPath, source, { format, resource: format === undefined, inferFormat: false, reason: 'run' })
     }
   }
 
@@ -321,12 +312,7 @@ export class StasisMetro {
   // 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
-      }
+      if (this.#seen.has(file) || !this.#within(file)) continue
       this.#seen.add(file)
       try {
         require(file)
@@ -353,23 +339,12 @@ export class StasisMetro {
     // RN CORE isn't a `dependencies` entry (config reports only reactNativePath) and autolinking
     // never lists it, but its native source (React/, ReactCommon/, ReactAndroid/, sdks/, ...) is a
     // build input like any other dep's -- walk it in full, the same way.
-    const rnPath = config.reactNativePath
-    if (typeof rnPath === 'string' && isAbsolute(rnPath)) roots.add(rnPath)
-    for (const root of roots) {
-      try {
-        this.#state.relative(root) // asserts the package lives inside the project root
-      } catch {
-        continue
-      }
-      this.#captureNativeTree(root)
-    }
+    const rnPath = typeof config.reactNativePath === 'string' && isAbsolute(config.reactNativePath) ? config.reactNativePath : null
+    if (rnPath !== null) roots.add(rnPath)
+    // One outside the project root is unattestable.
+    for (const root of roots) if (this.#within(root)) 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)) {
-      try {
-        this.#state.relative(rnPath)
-        for (const file of RN_CORE_INCLUDE_FILES) this.#captureNativeFile(join(rnPath, file))
-      } catch { /* react-native resolved outside the project root -- unattestable */ }
-    }
+    if (rnPath !== null && this.#within(rnPath)) for (const file of RN_CORE_INCLUDE_FILES) this.#captureNativeFile(join(rnPath, file))
   }
 
   // Attest a single vetted file (RN_CORE_INCLUDE_FILES) the tree walk skips; absent -> skipped.
@@ -401,12 +376,13 @@ export class StasisMetro {
   }
 
   // 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.
+  // --metro`), but what is already captured as a graph module or auto-include, each in the format it
+  // gives (none for a codegen source, as Metro's code has none, so none is inferred). 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' })
+      this.#recordCapture(file, source, { format, resource: action === 'resource', inferFormat: false })
     }
   }
 
@@ -422,6 +398,8 @@ export class StasisMetro {
       if (modPath === undefined) continue
       const url = pathToFileURL(modPath).toString()
       for (const [specifier, target] of this.#edges(module)) this.#state.assertImport(url, specifier, target, { platform })
+      this.#assertConsumed(module, modPath)
+      this.#assertAssetFiles(module, modPath, platform ?? null)
     }
   }
 
@@ -446,17 +424,14 @@ export class StasisMetro {
     return edges
   }
 
-  #captureModules(modules, entries) {
+  #captureModules(modules, entries, platform) {
     for (const module of modules) {
       const modPath = diskPath(module)
       if (modPath === undefined) continue
 
       const kind = classifyExtension(modPath, this.#resources)
       if (kind === 'unknown') {
-        throw new Error(
-          `StasisMetro: unsupported extension for '${modPath}' -- ` +
-          `add its extension or filename to the plugin's resources option or stop importing it`
-        )
+        throw new Error(unsupportedExtension('StasisMetro', `'${modPath}'`))
       }
       const url = pathToFileURL(modPath).toString()
       for (const [specifier, target] of this.#edges(module)) this.#state.addImport(url, specifier, target)
@@ -472,10 +447,153 @@ export class StasisMetro {
         assert.ok(isUtf8(source), `StasisMetro: code-classified file has non-UTF-8 bytes: ${modPath}`)
       }
       // 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' })
+      // what runs. But the one its name alone gives it (.json, .mjs, .cjs: nodeExtFormat), as Node
+      // loads it too, which a --fs read of it records besides (a resource still takes its
+      // byte-derived format).
+      const format = kind === 'code' ? nodeExtFormat(modPath) : undefined
+      this.#state.addFile(url, { source, format, isEntry: entries.has(modPath), resource: kind === 'resource', inferFormat: false, reason: 'metro' })
+      this.#captureConsumed(module, modPath)
+      this.#captureAssetFiles(module, modPath, platform)
+    }
+  }
+
+  // Whether `path` lies within the project root, as the State's root-relative keys need.
+  #within(path) {
+    return isPathWithin(this.#state.root, path)
+  }
+
+  // `path`'s real path, where it lies within the project root (not linked out of it), else null.
+  #realWithin(path) {
+    let real
+    try {
+      real = diskHost.realpath(path)
+      this.#realRoot ??= diskHost.realpath(this.#state.root)
+    } catch {
+      return null
+    }
+    return this.#within(real) && isPathWithin(this.#realRoot, real) ? real : null
+  }
+
+  // The resources a Babel plugin consumed in transforming `module`, read and inlined in their imports'
+  // stead (`require('./messages.po')`, @exodus/i18n's plugin-inline-po), as the stasis transformer
+  // carries them (`stasisConsumed`): no module of Metro's, so no edge, but the build's input all the
+  // same. One named by path, as such a plugin reads it, from the module's dir, by its real path, as
+  // Metro names its modules. One naming code (an import a plugin split into others, as
+  // babel-plugin-lodash does), no file, or one outside the project root is passed over; one the
+  // resources don't carry is refused. -> each as { file: its real path, read: the path read }
+  * #consumedResources(module, modPath) {
+    for (const specifier of module.output?.[0]?.data?.stasisConsumed ?? []) {
+      if (typeof specifier !== 'string' || !(isAbsolute(specifier) || /^\.\.?\//u.test(specifier))) continue
+      const read = resolve(dirname(modPath), specifier)
+      const file = diskHost.stat(read)?.isFile() ? this.#realWithin(read) : null
+      if (file === null) continue
+      const kind = classifyExtension(file, this.#resources)
+      if (kind === 'code') continue
+      if (kind === 'unknown') {
+        throw new Error(unsupportedExtension('StasisMetro', `'${file}', which a Babel plugin inlines into '${modPath}'`))
+      }
+      yield { file, read }
+    }
+  }
+
+  // Capture: each, attributed to `metro`, as `stasis bundle --metro` records them under `bundle:metro`.
+  #captureConsumed(module, modPath) {
+    for (const { file } of this.#consumedResources(module, modPath)) this.#captureRead(file, 'resource')
+  }
+
+  // Capture `path`, a file Metro's build reads that its graph doesn't carry, once, attributed to
+  // `metro`, as the `kind` classifyExtension gives it.
+  #captureRead(path, kind) {
+    if (this.#seen.has(path)) return
+    this.#seen.add(path)
+    // Real reader: plugin bookkeeping, not a program fs read -- must not be re-recorded by --fs.
+    this.#recordCapture(path, realReadFileSync(path), { format: kind === 'code' ? nodeExtFormat(path) : undefined, resource: kind === 'resource', inferFormat: false })
+  }
+
+  // Load: the Babel plugin reads each from disk, past the stasis transformer (#assertOnDisk).
+  #assertConsumed(module, modPath) {
+    for (const files of this.#consumedResources(module, modPath)) {
+      this.#assertOnDisk(files, { what: `which a Babel plugin inlines into '${modPath}'`, servedBy: ['sync', 'async'] })
+    }
+  }
+
+  // The files of the asset module `module` Metro builds, by the names it reads them by (#assetDirHost):
+  // as Metro reads them to build it (its `scales` and `hash`) and copies them out with it, it and its
+  // other scales (`logo@2x.png`, `logo@3x.png`; metroAssetFiles, Metro's own rule for `platform`). No
+  // import names one, so no edge. -> their paths, none for a module no asset
+  #assetFiles(module, modPath, platform) {
+    return module.output?.[0]?.type === 'js/module/asset' ? metroAssetFiles(modPath, platform, this.#assetDirHost()) : []
+  }
+
+  // The directory listing Metro finds an asset's files in (fs.promises.readdir): the disk's, but under
+  // load with --fs=async, which serves it, the bundle's where it has one (a file added on disk since
+  // is no file of the asset Metro builds), each name in it a file where it is one on disk or the bundle
+  // serves one (gone from disk, it holds no drift).
+  #assetDirHost() {
+    const state = this.#state
+    if (!state.config.loadBundle || state.config.fs !== 'async') return diskHost
+    return {
+      readdir: (dir) => state.getFsDirFamily(pathToFileURL(dir).toString())?.map((name) => ({ name })) ?? diskHost.readdir(dir),
+      stat: (path) => diskHost.stat(path) ?? (state.getFsStatFamily(pathToFileURL(path).toString()) === 'file' ? FILE_STAT : null),
     }
   }
+
+  // The files the bundle carries, as a directory listing of them (`metroAssetFiles`' host): an asset's
+  // files as captured.
+  #bundleDirHost() {
+    this.#bundleDirs ??= bundleDirHost(this.#state)
+    return this.#bundleDirs
+  }
+
+  // Capture: each but the module itself, attributed to `metro`, as `stasis bundle --metro` records them:
+  // by the name Metro reads it by, with the bytes it reads there (one linked in, its target's), so a
+  // load holds that name to them. One linked from outside the project is passed over.
+  #captureAssetFiles(module, modPath, platform) {
+    for (const read of this.#assetFiles(module, modPath, platform)) {
+      const kind = classifyExtension(read, this.#resources)
+      // One of a kind unknown, as the module itself, which the graph capture refused.
+      if (kind !== 'unknown' && this.#realWithin(read) !== null) this.#captureRead(read, kind)
+    }
+  }
+
+  // Load: Metro's asset transformer reads each of an asset's files from disk (fs.promises), the module's
+  // own too, past the stasis transformer, which serves the module's `data` that it never reads. Each it
+  // reads on disk must be the bundle's under the name it reads it by (#assertOnDisk: a scale added since
+  // the capture, or one a symlink redirects, reads bytes the bundle doesn't carry there); and each the
+  // bundle carries must be among those it reads (one gone builds another asset, its `scales` and `hash`,
+  // from what remains) -- unless --fs=async serves them.
+  #assertAssetFiles(module, modPath, platform) {
+    const read = this.#assetFiles(module, modPath, platform)
+    if (read.length === 0) return
+    const what = `a file of the asset '${modPath}' Metro builds`
+    for (const path of read) {
+      if (diskHost.stat(path)?.isFile()) this.#assertOnDisk({ file: path, read: path }, { what, servedBy: ['async'] })
+    }
+    if (!inScope(this.#state, pathToFileURL(modPath).toString())) return
+    for (const file of metroAssetFiles(modPath, platform, this.#bundleDirHost())) {
+      if (read.includes(file)) continue
+      throw new Error(`StasisMetro: '${file}', ${what} as the bundle carries it, is gone -- Metro would build the asset without it under load; restore it`)
+    }
+  }
+
+  // Load: a file Metro's build reads from disk by `read`, past the stasis transformer, which serves only
+  // the module it transforms. One in scope (as the transformer's: any under scope=full, else one in
+  // node_modules) is held to the bundle's bytes for `file` (getFile throws on one it doesn't carry),
+  // fail closed on drift -- unless --fs, in a mode of `servedBy` (async patches fs.promises too), serves
+  // the read from the bundle itself, which it does by the path read (not a symlink to the file the
+  // bundle carries).
+  #assertOnDisk({ file, read }, { what, servedBy }) {
+    const state = this.#state
+    const url = pathToFileURL(file).toString()
+    if (!inScope(state, url)) return
+    if (servedBy.includes(state.config.fs) && state.getFsFileFamily(pathToFileURL(read).toString()) !== undefined) return
+    const { source } = state.getFile(url)
+    if (realReadFileSync(file).equals(Buffer.isBuffer(source) ? source : Buffer.from(source))) return
+    throw new Error(
+      `StasisMetro: '${file}', ${what}, differs on disk from the bundle -- ` +
+      'Metro\'s build reads it from disk under load; restore it, or run with --fs to serve it from the bundle'
+    )
+  }
 }
 
 // Idiomatic Metro-config wrapper: returns a new config with `serializer.customSerializer` wired

package/src/plugins.js

@@ -22,7 +22,7 @@ import { extSetsEqual, parseResourcesOption } from '@exodus/stasis-core/util'
 //  7. lock='none' AND bundle='none' with no preload is a no-op (env-controlled-off framework plugins).
 export function resolvePluginState(label, options, cwd) {
   validatePluginOptions(label, options)
-  const { scope, lock, bundle, bundleFile, resourcesBundleFile, debug, childProcess, packageJSON, resources } = options
+  const { lock, bundle, bundleFile, resourcesBundleFile, resources } = options
   // Same-instance fast path: loader installed but lazy initState hasn't fired (webpack builds plugins
   // before user code). Force-init so the plugin lands in the ambient branch. NOT for a separate
   // stasis-core copy -- that would mint a phantom State.preload racing the real loader's write.
@@ -69,21 +69,13 @@ export function resolvePluginState(label, options, cwd) {
 
   // Preload active: the lockfile is necessarily the ambient's. Enforce field coordination, then reuse or sidecar.
   const pc = ambient.config
-  if (lock !== undefined && lock !== pc.lock) {
-    throw new Error(`${label}: lock='${lock}' conflicts with active preload lock='${pc.lock}'`)
-  }
-  // scope/debug/childProcess must agree with the preload (reuse adopts it, sidecar copies it).
-  if (scope !== undefined && scope !== pc.scope) {
-    throw new Error(`${label}: scope='${scope}' conflicts with active preload scope='${pc.scope}'`)
-  }
-  if (debug !== undefined && debug !== pc.debug) {
-    throw new Error(`${label}: debug=${debug} conflicts with active preload debug=${pc.debug}`)
-  }
-  if (childProcess !== undefined && childProcess !== pc.childProcess) {
-    throw new Error(`${label}: childProcess=${childProcess} conflicts with active preload childProcess=${pc.childProcess}`)
-  }
-  if (packageJSON !== undefined && packageJSON !== pc.packageJSON) {
-    throw new Error(`${label}: packageJSON=${packageJSON} conflicts with active preload packageJSON=${pc.packageJSON}`)
+  // lock/scope/debug/childProcess/packageJSON must agree with the preload (reuse adopts it, sidecar
+  // copies it). The string modes are quoted, the boolean toggles not (validatePluginOptions typed them).
+  const shown = (value) => (typeof value === 'string' ? `'${value}'` : value)
+  for (const key of ['lock', 'scope', 'debug', 'childProcess', 'packageJSON']) {
+    if (options[key] !== undefined && options[key] !== pc[key]) {
+      throw new Error(`${label}: ${key}=${shown(options[key])} conflicts with active preload ${key}=${shown(pc[key])}`)
+    }
   }
   // resources is process-wide, so a plugin's allowlist must agree with the preload's -- compare
   // parsed sets (order/dupes/case-insensitive) to prevent one plugin silently widening the asset set.
@@ -100,13 +92,27 @@ export function resolvePluginState(label, options, cwd) {
   // fs-READ during the build from genuine run dependencies recorded before any plugin existed.
   ambient.markPluginAttached()
 
+  // A State of its own bundle (`mode`, at bundleFile) beside the preload, whose lockfile it shares
+  // and whose other settings it carries over (sidecars skip stasis.config.json discovery).
+  const sidecar = (mode) => ({
+    state: new State(cwd, {
+      parent: ambient,
+      scope: pc.scope,
+      lock: pc.lock,
+      bundle: mode,
+      bundleFile,
+      resourcesBundleFile,
+      debug: pc.debug,
+      childProcess: pc.childProcess,
+      packageJSON: pc.packageJSON,
+      resources: [...pc.resources],
+      brotliQuality: pc.brotliQuality,
+    }),
+    isNoop: false,
+  })
+
   if (pc.bundle) {
-    // Preload has bundle on -- plugin can't disable, must match mode.
-    if (bundle === 'none' || bundle === 'ignore') {
-      throw new Error(
-        `${label}: bundle='${bundle}' conflicts with active preload bundle='${pc.bundleMode}'`
-      )
-    }
+    // Preload has bundle on -- plugin can't disable (pc.bundleMode is neither 'none' nor 'ignore'), must match mode.
     if (bundle !== undefined && bundle !== pc.bundleMode) {
       throw new Error(
         `${label}: bundle='${bundle}' conflicts with active preload bundle='${pc.bundleMode}'`
@@ -118,21 +124,7 @@ export function resolvePluginState(label, options, cwd) {
       return { state: ambient, isNoop: false }
     }
     // Rule 6: different path -- sidecar inherits preload's modes, overrides bundleFile.
-    const sidecar = new State(cwd, {
-      parent: ambient,
-      scope: pc.scope,
-      lock: pc.lock,
-      bundle: pc.bundleMode,
-      bundleFile,
-      resourcesBundleFile,
-      debug: pc.debug,
-      childProcess: pc.childProcess,
-      packageJSON: pc.packageJSON,
-      resources: [...pc.resources],
-      // carried over: sidecars skip stasis.config.json discovery
-      brotliQuality: pc.brotliQuality,
-    })
-    return { state: sidecar, isNoop: false }
+    return sidecar(pc.bundleMode)
   }
 
   // Preload exists but has no bundle.
@@ -152,18 +144,23 @@ export function resolvePluginState(label, options, cwd) {
       `${label}: bundle='${bundle}' alongside a preload without bundle requires an explicit bundleFile`
     )
   }
-  const sidecar = new State(cwd, {
-    parent: ambient,
-    scope: pc.scope,
-    lock: pc.lock,
-    bundle,
-    bundleFile,
-    resourcesBundleFile,
-    debug: pc.debug,
-    childProcess: pc.childProcess,
-    packageJSON: pc.packageJSON,
-    resources: [...pc.resources],
-    brotliQuality: pc.brotliQuality, // carried over, like the Rule 6 sidecar above
-  })
-  return { state: sidecar, isNoop: false }
+  return sidecar(bundle)
+}
+
+// What a plugin (`label`) says of a file it is given (`what`, as it names it) whose extension it
+// neither bundles as code nor is allowed as a resource.
+export const unsupportedExtension = (label, what) =>
+  `${label}: unsupported extension for ${what} -- add its extension or filename to the plugin's resources option or stop importing it`
+
+// `state.getImport(parentURL, specifier, options)`, or undefined where the bundle attests no such edge:
+// at a successful capture that's an EXTERNAL (never recorded as an edge), the bundler's to resolve as
+// without us. File BYTES still fail closed where the plugin loads them; any other error is a real
+// fault, thrown.
+export function attestedImport(state, parentURL, specifier, options) {
+  try {
+    return state.getImport(parentURL, specifier, options)
+  } catch (err) {
+    if (err?.code === 'ERR_MODULE_NOT_FOUND') return undefined
+    throw err
+  }
 }

package/src/rollup.js

@@ -6,12 +6,12 @@ import { dirname, isAbsolute, resolve as resolvePath } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 
 import { Bundle } from '@exodus/stasis-core/bundle'
-import { resolvePluginState } from './plugins.js'
+import { attestedImport, resolvePluginState, unsupportedExtension } from './plugins.js'
 import { State } from '@exodus/stasis-core/state'
 // Pre-patch snapshot, not `import { readFile }`: under --fs=async that builtin is patched, and
 // this plugin loads after, so a direct import would route rollup's reads through the capture hook.
-import { realReadFile } from '@exodus/stasis-core/state-util'
-import { classifyExtension } from '@exodus/stasis-core/util'
+import { inScope, realReadFile } from '@exodus/stasis-core/state-util'
+import { classifyExtension, isPathWithin } from '@exodus/stasis-core/util'
 
 // Rollup chains resolveId/load hooks first-non-null-wins, so put this plugin FIRST in `plugins`:
 // listed later, a sibling resolver (node-resolve, commonjs) answers before stasis sees the edge --
@@ -145,20 +145,13 @@ export class StasisRollup {
   #classifyOrThrow(id) {
     const kind = classifyExtension(id, this.#resources)
     if (kind === 'unknown') {
-      throw new Error(
-        `StasisRollup: unsupported extension for '${id}' -- add its extension or filename to the plugin's resources option or stop importing it`
-      )
+      throw new Error(unsupportedExtension('StasisRollup', `'${id}'`))
     }
     return kind
   }
 
   #inRoot(path) {
-    try {
-      this.#state.relative(path)
-      return true
-    } catch {
-      return false
-    }
+    return isPathWithin(this.#state.root, path)
   }
 
   async #resolveId(ctx, source, importer, opts) {
@@ -191,21 +184,15 @@ export class StasisRollup {
       this.#assertPersistableAttributes(attrs)
       // Forward import attributes (`with { type: 'json' }`) so plugin-capture round-trips to
       // plugin-load, both keyed under `* (with: ...)`.
-      let url, format
-      try {
-        ;({ url, format } = this.#state.getImport(parentURL, source, { importAttributes: attrs }))
-      } catch (err) {
-        // No attested edge -- at a successful capture that's an EXTERNAL (never recorded as an
-        // edge), so hand it back to rollup. File BYTES still fail closed at the load hook.
-        // A non-MODULE_NOT_FOUND error is a real fault -- rethrow.
-        if (err?.code === 'ERR_MODULE_NOT_FOUND') return null
-        throw err
-      }
+      // No attested edge: rollup's. File BYTES still fail closed at the load hook.
+      const attested = attestedImport(this.#state, parentURL, source, { importAttributes: attrs })
+      if (attested === undefined) return null
+      const { url, format } = attested
       const path = fileURLToPath(url)
       // Refuse a resource only when load mode would actually serve it: an out-of-scope workspace
       // resource under node_modules scope comes from disk via the user's asset plugin, exactly
       // like a capture build (the load hook defers it with the same scope gate).
-      if (Bundle.isResourceFormat(format) && (this.#state.config.full || this.#state.inNodeModules(url))) {
+      if (Bundle.isResourceFormat(format) && inScope(this.#state, url)) {
         this.#refuseResourceLoad(path)
       }
       // KNOWN GAP: sibling resolution metadata (moduleSideEffects, syntheticNamedExports, meta)
@@ -253,7 +240,7 @@ export class StasisRollup {
       // a sibling's bare resolve() probe carries isEntry too but never loads, so only genuine
       // roots reach this gate.
       if (this.#state.config.full && ctx.getModuleInfo(id)?.isEntry) this.#state.assertEntry(url)
-      if (!this.#state.config.full && !this.#state.inNodeModules(url)) return null
+      if (!inScope(this.#state, url)) return null
       const { source, format } = this.#state.getFile(url)
       if (Bundle.isResourceFormat(format)) this.#refuseResourceLoad(id)
       // Code is stored as UTF-8 text, exactly what rollup's parser expects.

package/src/webpack.js

@@ -5,9 +5,9 @@ import { createRequire, isBuiltin } from 'node:module'
 import path from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 
-import { resolvePluginState } from './plugins.js'
+import { attestedImport, resolvePluginState, unsupportedExtension } from './plugins.js'
 import { State } from '@exodus/stasis-core/state'
-import { realReadFileSync } from '@exodus/stasis-core/state-util'
+import { realReadFileSync, servedByBundle } from '@exodus/stasis-core/state-util'
 import { classifyExtension } from '@exodus/stasis-core/util'
 
 // CJS require anchored here, used only to locate the PROJECT's babel-plugin-module-resolver below.
@@ -95,14 +95,8 @@ export class StasisWebpack {
     const state = this.#state
     const orig = compiler.inputFileSystem
 
-    // True iff `p` is in scope for load mode. state.relative throws outside state.root (treated
-    // as out-of-scope: system files, scratch).
-    const inScope = (p) => {
-      if (typeof p !== 'string') return false
-      try { state.relative(p) } catch { return false }
-      if (state.config.full) return true
-      return state.inNodeModules(pathToFileURL(p).toString())
-    }
+    // True iff `p` is served from the bundle under load (servedByBundle).
+    const served = (p) => typeof p === 'string' && p !== '' && servedByBundle(state, p)
 
     // Family = the sidecar's own app-graph bundle first, then its parent (loaders + resolution-path
     // dirs the ambient preload captured). Both share one lockfile; no parent -> just [state].
@@ -121,7 +115,7 @@ export class StasisWebpack {
     // must keep `this` = orig; we override only readFile and stat.
     const wrappedReadFile = (p, options, callback) => {
       if (typeof options === 'function') { callback = options; options = undefined }
-      if (inScope(p)) {
+      if (served(p)) {
         try {
           const src = serveFromBundle(p)
           const buf = Buffer.isBuffer(src) ? src : Buffer.from(src)
@@ -136,7 +130,7 @@ export class StasisWebpack {
       return orig.readFile(p, options, callback)
     }
     const wrappedStat = (p, callback) => {
-      if (inScope(p)) {
+      if (served(p)) {
         // Directories have no bundle content, so serve a synthetic dir Stats from the family's
         // existence record (getFsStat) -- webpack's resolver stat()s intermediate dirs while walking.
         const url = pathToFileURL(p).toString()
@@ -168,21 +162,14 @@ export class StasisWebpack {
         const issuer = data.contextInfo?.issuer
         if (!issuer) return  // entries: already absolute, inputFileSystem covers them
         // Out-of-scope parents were never the bundle's responsibility -- defer to webpack's resolver.
-        if (!inScope(issuer)) return
+        if (!served(issuer)) return
         // Built-ins are never bundled or recorded as edges; skip up front. SECURITY: never consult
         // getImport for a builtin name, so a tampered bundle can't redirect `fs` to an arbitrary file.
         if (isBuiltin(data.request)) return
         const parentURL = pathToFileURL(issuer).toString()
-        let resolved
-        try {
-          resolved = state.getImport(parentURL, data.request)
-        } catch (err) {
-          // No attested edge -- at a successful capture that's an EXTERNAL (never recorded as an
-          // edge), so defer to webpack. File BYTES still fail closed at the inputFileSystem wrapper.
-          // A non-MODULE_NOT_FOUND error is a real fault -- rethrow.
-          if (err?.code === 'ERR_MODULE_NOT_FOUND') return
-          throw err
-        }
+        // No attested edge: defer to webpack. File BYTES still fail closed at the inputFileSystem wrapper.
+        const resolved = attestedImport(state, parentURL, data.request)
+        if (resolved === undefined) return
         // Redirect the resolver to the absolute bundle path; the stat wrapper then reports it exists.
         data.request = fileURLToPath(resolved.url)
       })
@@ -267,10 +254,7 @@ export class StasisWebpack {
 
         const kind = classifyExtension(filePath, this.#resources)
         if (kind === 'unknown') {
-          throw new Error(
-            `StasisWebpack: unsupported extension for '${filePath}' -- ` +
-            `add its extension or filename to the plugin's resources option or stop importing it`
-          )
+          throw new Error(unsupportedExtension('StasisWebpack', `'${filePath}'`))
         }
 
         const url = pathToFileURL(filePath).toString()