@exodus/stasis 1.0.0-beta.2 → 1.0.0-beta.5

package/src/cmd/bundle.js

@@ -1,46 +1,53 @@
 import { isUtf8 } from 'node:buffer'
-import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs'
-import { dirname, extname, isAbsolute, join, posix, relative, resolve } from 'node:path'
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs'
+import { extname, join, posix, relative, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { brotliCompressSync } from 'node:zlib'
+import { brotliDecompressSync } from 'node:zlib'
 
 import { Bundle } from '@exodus/stasis-core/bundle'
 import { Lockfile } from '@exodus/stasis-core/lockfile'
 import { scan } from '../scan.js'
 import { createFieldResolver, resolveConditions } from '../resolve-fields.js'
+import { discoverTsconfig, isDir, loadTsconfigPaths } from '../resolve-typescript.js'
+import { createMetroResolver } from '../metro-resolver.js'
 import { State } from '@exodus/stasis-core/state'
-import { brotliOptions } from '@exodus/stasis-core/brotli'
 import { sha512integrity } from '@exodus/stasis-core/state-util'
-import { assertRealPathWithinBase, moduleFileKey, splitNodeModulesPath } from '@exodus/stasis-core/util'
+import { detectRepo, findPackageMetadata, normalizeEntries, packageType, readJson, readModuleManifest, readPackageJson, readRegularFileOrNull } from '@exodus/stasis-core/bundle-util'
+import { RN_CORE_INCLUDE_FILES, assertRealPathWithinBase, classifyNativeCapture, hasNodeModulesSegment, isDotEnvFile, isExcludedNativeDir, isExecutableFile, isNativeArtifact, isNativeManifest, isPodspec, isSkippedNativeWalkDir, moduleFileKey, parseResourcesOption, posixPathEscapes, refineNativeCapture, relativeEscapes, splitNodeModulesPath, toPosix } from '@exodus/stasis-core/util'
+import { diskHost } from '@exodus/stasis-core/host'
 import {
+  SOLIDITY_PACKAGE_MANIFESTS,
+  SOLIDITY_ROOT_MANIFESTS,
   buildSolidityTree,
   collectSolidityFilesFromDisk,
-  readRemappingsFile,
+  discoverSolidityConfig,
+  expandSolidityEntries,
 } from '../loaders/solidity.js'
+import { decodeUtf8 } from '../loaders/solidity-ownership.js'
 import { buildBashTree, collectBashFilesFromDisk } from '../loaders/bash.js'
-import { buildRustTree, collectRustFilesFromDisk } from '../loaders/rust.js'
+import { boundaryOf, collectRustBundle, withinRealDir } from '../loaders/rust.js'
+import { createCargoContext } from '../loaders/cargo.js'
 import {
   bucketizePhpSources,
   buildPhpTree,
   collectPhpFilesFromDisk,
   loadComposerAutoload,
+  loadComposerPackages,
   loadLaravelProviderFiles,
 } from '../loaders/php.js'
+import { DEFAULT_BUNDLE_FILE, bundledSummary, packagesLabel, writeBundle, writeFile } from './output.js'
 
 const JS_EXTS = new Set(['.js', '.cjs', '.mjs', '.ts', '.cts', '.mts'])
 const BASH_EXTS = new Set(['.sh', '.bash'])
 const RUST_EXTS = new Set(['.rs'])
 
-// Fallback package identity for the workspace bucket when no package.json
-// with a name+version can be found by walking up from any of the bundled
-// files. Bundle.parse requires every workspace/module bucket to have
-// both fields, so we have to attest something.
+// Fallback identity for the workspace bucket; Bundle.parse requires every bucket to attest name+version.
 const SOLIDITY_WORKSPACE_NAME = 'solidity-bundle'
 const SOLIDITY_WORKSPACE_VERSION = '0.0.0'
 const SOLIDITY_FORMAT = 'solidity'
 const BASH_WORKSPACE_NAME = 'bash-bundle'
 const BASH_WORKSPACE_VERSION = '0.0.0'
-const BASH_FORMAT = 'bash'
+const SHELL_FORMAT = 'shell'
 
 const RUST_WORKSPACE_NAME = 'rust-bundle'
 const RUST_WORKSPACE_VERSION = '0.0.0'
@@ -50,50 +57,11 @@ const PHP_WORKSPACE_NAME = 'php-bundle'
 const PHP_WORKSPACE_VERSION = '0.0.0'
 const PHP_FORMAT = 'php'
 
-// Walk up from the file's directory looking for the nearest package.json
-// with both `name` and `version`. Returns { pkgDir, name, version }
-// (pkgDir relative to `baseDir`, "." for the project root) or null when no
-// such package.json exists at or above the file.
-function findPackageMetadata(baseDir, fileRelPath) {
-  let dir = dirname(fileRelPath)
-  while (true) {
-    const pkgPath = join(baseDir, dir, 'package.json')
-    if (existsSync(pkgPath)) {
-      try {
-        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
-        if (pkg.name && pkg.version) {
-          return { pkgDir: dir, name: pkg.name, version: pkg.version }
-        }
-      } catch { /* malformed — keep walking */ }
-    }
-    if (dir === '.' || dir === '/' || dir === '') return null
-    const parent = dirname(dir)
-    if (parent === dir) return null
-    dir = parent
-  }
-}
-
-function normalizeEntries(entries, cwd) {
-  const baseDir = resolve(cwd)
-  return entries.map((e) => {
-    const abs = resolve(cwd, e)
-    const rel = relative(baseDir, abs).split(/[\\/]/u).join('/')
-    // On Windows, `path.relative()` returns an absolute path when `abs` is on
-    // a different drive than `baseDir` — that wouldn't start with `..` but
-    // still escapes, so reject both forms.
-    if (rel.startsWith('..') || isAbsolute(rel)) throw new Error(`Entry escapes baseDir: ${e}`)
-    return rel.replace(/^\.\//u, '')
-  })
-}
-
-// Deepest directory that is a parent of every file in `paths`, expressed
-// relative to `cwd`. `paths` may be POSIX-relative-to-cwd; entries that
-// escape cwd (e.g. `../deps/X.sol` via remapping) push the result above
-// cwd, in which case the returned path starts with `..`. Returns "." when
-// the outermost directory IS cwd itself.
+// Deepest common parent dir of `paths`, relative to `cwd`; starts with `..` when entries
+// escape cwd (e.g. via remapping), or "." when it is cwd itself.
 export function outermostDir(paths, cwd) {
   if (paths.length === 0) return '.'
-  const cwdAbs = posix.resolve(cwd.replaceAll(/\\/gu, '/'))
+  const cwdAbs = posix.resolve(toPosix(cwd))
   const absDirs = paths.map((p) => posix.dirname(posix.resolve(cwdAbs, p)))
   const partsList = absDirs.map((d) => d.split('/'))
   const common = []
@@ -107,81 +75,37 @@ export function outermostDir(paths, cwd) {
   return rel === '' ? '.' : rel
 }
 
-function readJson(file) {
-  try {
-    return JSON.parse(readFileSync(file, 'utf8'))
-  } catch {
-    return null
-  }
-}
-
-// Split a Soldeer dependency dir name (`<name>-<version>`) into its parts, e.g.
-// `@openzeppelin-contracts-5.0.2` -> { name: '@openzeppelin-contracts',
-// version: '5.0.2' }. Soldeer encodes the version into the directory name, so
-// that's the authoritative identity for a Soldeer package. Falls back to
-// version 0.0.0 when the dir doesn't end in a semver (every bucket must attest
-// a version).
+// Split a Soldeer dep dir `<name>-<version>` (its authoritative identity); falls back to
+// version 0.0.0 when it doesn't end in a semver (every bucket must attest a version).
 function parseSoldeerDir(seg) {
   const m = /^(.+)-(\d+\.\d+\.\d+(?:[-+][\w.-]+)?)$/u.exec(seg)
   return m ? { name: m[1], version: m[2] } : { name: seg, version: '0.0.0' }
 }
 
-// Extract `owner/repo` from a github.com remote (https, ssh, or scp-style),
-// dropping a trailing `.git`. Returns null for non-github hosts.
+// Extract `owner/repo` from a github.com remote (https/ssh/scp); null for non-github hosts.
 function githubSlug(url) {
   const m = /github\.com[/:]([^/]+)\/([^/]+?)(?:\.git)?\/?$/iu.exec(url)
   return m ? `${m[1]}/${m[2]}` : null
 }
 
-// Parse `.gitmodules` into Map<submodulePath, { name, branch }>, keeping only
-// github.com submodules (the ones we can attribute as `github`). `.gitmodules`
-// is git-config INI: `[submodule "<n>"]` sections with `path`/`url`/`branch`.
-function parseGithubSubmodules(baseDir) {
+// The github.com ones of `submodules` (readGitmodules), as Map<submodulePath, { name, branch }>.
+function githubSubmodules(submodules) {
   const byPath = new Map()
-  const text = readFileSyncOrNull(join(baseDir, '.gitmodules'))
-  if (!text) return byPath
-  let cur = null
-  const flush = () => {
-    if (cur?.path && cur?.url) {
-      const name = githubSlug(cur.url)
-      if (name) byPath.set(cur.path.replace(/\/+$/u, ''), { name, branch: cur.branch })
-    }
-    cur = null
-  }
-  for (const raw of text.split('\n')) {
-    const line = raw.trim()
-    if (line.startsWith('[')) {
-      flush()
-      cur = line.startsWith('[submodule') ? {} : null
-      continue
-    }
-    if (!cur) continue
-    const eq = line.indexOf('=')
-    if (eq === -1) continue
-    const key = line.slice(0, eq).trim()
-    if (key === 'path' || key === 'url' || key === 'branch') cur[key] = line.slice(eq + 1).trim()
+  for (const { path, url, branch } of submodules) {
+    const name = url && githubSlug(url)
+    if (name) byPath.set(path, { name, branch })
   }
-  flush()
   return byPath
 }
 
-function readFileSyncOrNull(file) {
-  try {
-    return readFileSync(file, 'utf8')
-  } catch {
-    return null
-  }
-}
-
-// Classify a bundled Solidity file into its dependency bucket. Solidity installs
-// deps three ways, each its own ecosystem: npm (`node_modules`, left to the
-// shared bucketizer), Soldeer (`dependencies/<name>-<version>/` → `soldeer`),
-// and `forge install` git submodules (`lib/<dir>/`, when `.gitmodules` records a
-// github.com URL → `github`, per SBOM/Package-URL `pkg:github/owner/repo`).
-// Returns { bucketDir, name, version, ecosystem } for a Soldeer/github dep, or
-// null to defer to the package.json/node_modules/workspace logic.
-function makeSolidityClassifier(baseDir) {
-  const submodules = parseGithubSubmodules(baseDir)
+// Classify a Solidity file's dep bucket: Soldeer (`dependencies/<name>-<version>/`) or a
+// github submodule (`lib/`, via the `.gitmodules` `ownership` read), else null to defer to the
+// node_modules/workspace logic. `ownership.assert` vets a package.json path before it is read
+// through `host`.
+function makeSolidityClassifier(baseDir, ownership, host) {
+  const submodules = githubSubmodules(ownership.submodules)
+  const check = ownership.assert
+  const versions = new Map() // a submodule's package.json version, read once
   return (path) => {
     if (path.startsWith('dependencies/')) {
       const seg = path.slice('dependencies/'.length).split('/')[0]
@@ -192,87 +116,83 @@ function makeSolidityClassifier(baseDir) {
     }
     for (const [sub, { name, branch }] of submodules) {
       if (path === sub || path.startsWith(`${sub}/`)) {
-        const pkg = readJson(join(baseDir, sub, 'package.json'))
-        return { bucketDir: sub, name, version: pkg?.version ?? branch ?? '0.0.0', ecosystem: 'github' }
+        if (!versions.has(sub)) versions.set(sub, readPackageJson(baseDir, moduleFileKey(sub, 'package.json'), { strict: true, check, host })?.version)
+        return { bucketDir: sub, name, version: versions.get(sub) ?? branch ?? '0.0.0', ecosystem: 'github' }
       }
     }
     return null
   }
 }
 
-// Minimal Cargo.toml reader: pull `name`/`version` from the `[package]` table.
-// A full TOML parse isn't warranted — those two string keys are all we need to
-// identify a vendored crate. Returns null when there's no readable package name.
-function parseCargoToml(file) {
-  const text = readFileSyncOrNull(file)
-  if (!text) return null
-  const at = text.search(/^\[package\]\s*$/mu)
-  let body = text
-  if (at !== -1) {
-    const rest = text.slice(at)
-    const next = rest.slice(1).search(/^\[/mu) // start of the table after [package]
-    body = next === -1 ? rest : rest.slice(0, next + 1)
-  }
-  const name = /^\s*name\s*=\s*"([^"]+)"/mu.exec(body)?.[1]
-  const version = /^\s*version\s*=\s*"([^"]+)"/mu.exec(body)?.[1]
-  return name ? { name, version: version ?? '0.0.0' } : null
+// Classify a Rust file by the nearest Cargo.toml `[package]`: a `cargo vendor`ed crate under the
+// vendor dir (`vendor/<dir>/`, or where .cargo/config.toml points) is a dependency (tagged
+// `cargo`); any other package (the crate itself, a workspace member reached through a `path`
+// dependency) is first-party, so no ecosystem. Null (no manifest above the file) defers to the
+// package.json/placeholder logic.
+function makeRustClassifier(cargo) {
+  return (path) => {
+    const pkg = cargo.packageInfo(path)
+    if (!pkg) return null
+    return { bucketDir: pkg.dir, name: pkg.name, version: pkg.version, ecosystem: cargo.isVendored(path) ? 'cargo' : undefined }
+  }
 }
 
-// Classify a bundled Rust file. `cargo vendor` copies external crates in-tree
-// under `vendor/<dir>/`; each is its own crate with a Cargo.toml, so bucket it
-// under `vendor/<dir>` and tag it `cargo` (Package-URL `pkg:cargo/<name>`). The
-// workspace's own code and path/workspace members defer to the workspace logic.
-function makeRustClassifier(baseDir) {
-  return (path) => {
-    if (!path.startsWith('vendor/')) return null
-    const dir = path.slice('vendor/'.length).split('/')[0]
-    if (!dir) return null
-    const bucketDir = `vendor/${dir}`
-    const pkg = parseCargoToml(join(baseDir, bucketDir, 'Cargo.toml'))
-    return pkg ? { bucketDir, name: pkg.name, version: pkg.version, ecosystem: 'cargo' } : null
+// A file's key inside its bucket: the inverse of moduleFileKey.
+const fileInBucket = (bucketDir, path) => (bucketDir === '.' ? path : path.slice(bucketDir.length + 1))
+
+// A file of the bundle root (`realBase` its real path), its bytes, by project-relative path, or
+// null when it isn't a regular file there (a manifest the context saw may have gone since; a FIFO
+// would hang a read) or, with `within` a directory, doesn't really lie in it (a vendored crate's
+// manifest linked to a project file).
+function readFileWithinBase(baseDir, realBase, rel, within) {
+  try {
+    assertRealPathWithinBase(realBase, baseDir, rel)
+    if (!withinRealDir(baseDir, rel, within, { who: 'loader.cargo' })) return null
+    if (!statSync(join(baseDir, rel)).isFile()) return null
+    return readFileSync(join(baseDir, rel))
+  } catch (err) {
+    if (err.code === 'ENOENT' || err.code === 'EISDIR') return null
+    throw err
+  }
+}
+
+// Project-relative paths in `sources` whose on-disk file carries a POSIX execute bit -- the
+// `executable` list both artifacts record. The State-driven path derives this in addFile; the
+// static builders never touch a State, so they stat here.
+function executableSources(baseDir, sources, host) {
+  const executable = new Set()
+  for (const path of sources.keys()) {
+    if (isExecutableFile(join(baseDir, path), host)) executable.add(path)
+  }
+  return executable
+}
+
+// Bundles must be self-contained: throw on a missing entry or an unresolved `noun` (import, script,
+// module) of a `lang` bundle -- `missing`'s { spec, from }, with the `reason` it was refused if given.
+function assertSelfContained(lang, noun, entries, sources, missing) {
+  const issues = []
+  for (const entry of entries) {
+    if (!sources.has(entry)) issues.push(`Missing entry: ${entry}`)
+  }
+  for (const { spec, from, reason } of missing) {
+    issues.push(`Unresolved ${noun}: ${spec} from ${from}${reason ? ` (refused: ${reason})` : ''}`)
+  }
+  if (issues.length > 0) {
+    throw new Error(`${lang} bundle has unresolved ${noun}s:\n${issues.map((s) => `  ${s}`).join('\n')}`)
   }
 }
 
-// Assemble a scope=full code Bundle from a collected source set and its
-// resolution graph. Shared by every non-JS bundler (Solidity/Bash/Rust): the
-// language-specific work (collecting files, resolving the graph, deciding what
-// counts as "missing") happens in the caller; here every file is bucketized
-// the same way, tagged `format`, and the whole resolution graph is keyed under
-// a single `conditionKey`.
-//
-// Files are partitioned into per-package buckets by the nearest package.json
-// with name+version: node_modules files into `node_modules/<pkg>` buckets,
-// workspace files into their package dir, and anything with no discoverable
-// package.json into the "." bucket with the given placeholder identity (the
-// Bundle layout requires every bucket to attest a name+version). A file under
-// node_modules whose nearest package.json is the workspace root is rejected —
-// that hides a misconfigured dependency rather than silently mislabeling it.
-//
-// Unlike the wildcard "*" JS bundles use, these formats don't vary by Node
-// resolution condition, so every edge lands under the one `conditionKey`.
-//
-// Dependency buckets (those under node_modules) are tagged `ecosystem: 'npm'`:
-// node_modules is npm's install layout, so that's where the package came from,
-// regardless of the bundle's language — a Solidity or Bash import resolved out
-// of node_modules is an npm package all the same. This mirrors State's own
-// node_modules tagging (see stasis-core state.js) and lets consumers tell deps
-// apart from the workspace's own packages; the workspace/`.` bucket carries no
-// ecosystem. (PHP's Composer `vendor/` deps are tagged `composer` separately, by
-// the PHP bucketizer.)
-//
-// `classifyDep(path)` is an optional language-specific hook: when it returns a
-// { bucketDir, name, version, ecosystem } record the file is placed there
-// directly, which is how non-node_modules ecosystems are attributed (e.g.
-// Solidity's Soldeer `dependencies/` and github submodules). Returning null (or
-// omitting the hook) defers to the node_modules/package.json/workspace logic.
-// `format` tags every file uniformly (the single-language non-JS callers); pass
-// `formats` (a Map<path, format>) instead to tag per file, as the JS resolver path
-// does (a graph mixes module / commonjs / *-typescript / json). `resolutions`
-// values may be a target string (a flat edge) or a Map<platform, target> (a `--metro`
-// edge that resolves differently per platform) -- both round-trip through the bundle's
-// recursive serializer untouched.
+// Assemble a full-scope code Bundle shared by the non-JS bundlers. Files are bucketed by
+// nearest package.json (node_modules -> `npm`-tagged bucket, workspace -> its dir, none ->
+// "." with the placeholder identity); a node_modules file whose nearest package.json is the
+// workspace root is rejected, not mislabeled; `packageOf(path)` finds that package.json
+// (packageLookup by default, which walks past a malformed one). `classifyDep(path)` optionally
+// places a file directly (non-node_modules ecosystems like Soldeer/github); null defers. `format` tags
+// every file; `formats` (Map<path,format>) overrides it per file. `resolutions` values are
+// a flat target string or a Map<platform,target>; both round-trip untouched.
 function assembleCodeBundle({
-  baseDir, entries, sources, resolutions, workspaceName, workspaceVersion, format, formats, conditionKey, classifyDep,
+  baseDir, entries, sources, resolutions, workspaceName, workspaceVersion, format, formats, conditionKey, classifyDep, host,
+  packageOf = packageLookup(baseDir, { host }),
 }) {
   const modules = new Map()
   const ensureBucket = (dir, name, version, bucketEcosystem) => {
@@ -287,25 +207,29 @@ function assembleCodeBundle({
   for (const [path, content] of sources) {
     const dep = classifyDep?.(path)
     if (dep) {
-      ensureBucket(dep.bucketDir, dep.name, dep.version, dep.ecosystem)
-        .files[path.slice(dep.bucketDir.length + 1)] = content
+      ensureBucket(dep.bucketDir, dep.name, dep.version, dep.ecosystem).files[fileInBucket(dep.bucketDir, path)] = content
       continue
     }
-    const meta = findPackageMetadata(baseDir, path)
+    const meta = packageOf(path)
     const inNodeModules = splitNodeModulesPath(path) !== null
     if (meta) {
-      if (inNodeModules && !meta.pkgDir.includes('node_modules')) {
+      if (inNodeModules && !hasNodeModulesSegment(meta.pkgDir)) {
         throw new Error(`No package.json with name+version found for ${path}`)
       }
-      const rel = meta.pkgDir === '.' ? path : path.slice(meta.pkgDir.length + 1)
-      const bucketEcosystem = meta.pkgDir.includes('node_modules') ? 'npm' : undefined
-      ensureBucket(meta.pkgDir, meta.name, meta.version, bucketEcosystem).files[rel] = content
+      const bucketEcosystem = hasNodeModulesSegment(meta.pkgDir) ? 'npm' : undefined
+      ensureBucket(meta.pkgDir, meta.name, meta.version, bucketEcosystem).files[fileInBucket(meta.pkgDir, path)] = content
     } else {
       if (inNodeModules) throw new Error(`No package.json with name+version found for ${path}`)
       ensureBucket('.', workspaceName, workspaceVersion).files[path] = content
     }
   }
 
+  return codeBundle({ baseDir, entries, sources, modules, resolutions, format, formats, conditionKey, host })
+}
+
+// A full-scope code Bundle of `sources`, bucketed as `modules`: `format` tags every file, `formats`
+// (Map<path,format>) overrides it per file, and the `resolutions` edges are keyed under `conditionKey`.
+function codeBundle({ baseDir, entries, sources, modules, resolutions, format, formats, conditionKey, host }) {
   const formatsMap = new Map()
   for (const path of sources.keys()) formatsMap.set(path, formats?.get(path) ?? format)
 
@@ -313,75 +237,163 @@ function assembleCodeBundle({
   for (const [parent, specMap] of resolutions) importsForKey.set(parent, specMap)
   const imports = new Map([[conditionKey, importsForKey]])
 
+  // Executable bits, straight off disk (a synthetic source with no file there is simply not
+  // executable). Shell bundles lean on this most: `stasis extract` puts the +x back on the scripts.
+  const executable = executableSources(baseDir, sources, host)
+
+  // Attribute files to the `bundle` consumer (static builders skip State's per-file tagging).
   return new Bundle({
     config: { scope: 'full' },
     entries: new Set(entries),
     modules,
     formats: formatsMap,
     imports,
-  })
+    executable,
+  }).withReason('bundle')
 }
 
-// Build a stasis Bundle (in-memory) from a list of entry .sol files and
-// an optional mapping file. The mapping file (foundry.toml or
-// remappings.txt) is parsed for remappings but NOT included in the
-// bundle's sources. Returns the constructed `Bundle`.
-export async function buildSolidityBundle({ cwd = process.cwd(), entries, mappingFile } = {}) {
-  if (!Array.isArray(entries) || entries.length === 0) {
-    throw new Error('buildSolidityBundle: at least one entry .sol file is required')
+// Files never carried, whatever reads them: `.env` files, and Hardhat's config, which is code
+// (both however they're cased).
+const neverCarried = (rel) => isDotEnvFile(rel) || posix.basename(rel).toLowerCase().startsWith('hardhat.config.')
+
+// findPackageMetadata (with `options`) once per directory, the only thing its answer depends on.
+function packageLookup(baseDir, options) {
+  const byDir = new Map()
+  return (path) => {
+    const dir = posix.dirname(path)
+    if (!byDir.has(dir)) byDir.set(dir, findPackageMetadata(baseDir, path, options))
+    return byDir.get(dir)
   }
-  for (const e of entries) {
-    if (!e.endsWith('.sol')) throw new Error(`buildSolidityBundle: not a .sol file: ${e}`)
+}
+
+// The build-description files of a Solidity bundle (--manifests), as Map<path, text>, sorted:
+// `configFiles` (what discoverSolidityConfig read, whatever they're called), each of which must be
+// carried -- one outside the root, neverCarried, refused or gone is an error, as the bundle
+// couldn't reproduce the resolution without it -- plus the SOLIDITY_*_MANIFESTS that exist, for the
+// root and for each package dir `classifyDep`/`packageOf` places a bundled source in, but none
+// whose path `ownership` refuses (see solidityOwnership). Carried as written: whatever they hold
+// (an RPC URL with its API key, an Etherscan key, a URL's credentials) is in the bundle too, as
+// with --package-json. Read through `host`.
+function solidityManifests(baseDir, sources, configFiles, { classifyDep, packageOf, ownership, host }) {
+  const realBase = host.realpath(baseDir)
+  // `{ text }`, or `{ why }` it can't be carried (null: nothing is there). Read by the real path
+  // `ownership` resolved `rel` to, so what's carried is the file it vouched for.
+  const carry = (rel) => {
+    const { reason, real, outside } = ownership.of(rel)
+    if (reason) return { why: reason }
+    if (real === null) return { why: null }
+    if (outside) throw new Error(`Refusing to follow symlink escaping bundle root: ${rel} -> ${resolve(realBase, real)}`)
+    const buf = readRegularFileOrNull(join(realBase, real), rel, host)
+    if (buf === null) return { why: null } // a directory
+    return { text: decodeUtf8(buf, rel) }
+  }
+  const unreproducible = (rel, why) => new Error(`--manifests can't carry ${rel}, which the Solidity resolution read: ${why}`)
+  const out = new Map()
+  for (const rel of configFiles) {
+    // Absolute: the OS couldn't give its real path (see projectRelative).
+    if (posix.isAbsolute(rel)) throw unreproducible(rel, "its real path can't be resolved")
+    if (posixPathEscapes(rel)) throw unreproducible(rel, 'it lies outside the bundle root')
+    if (neverCarried(rel)) throw unreproducible(rel, '.env files and hardhat.config.* are never carried')
+    if (sources.has(rel)) continue
+    const { text, why } = carry(rel)
+    if (text === undefined) throw unreproducible(rel, why ?? 'it is gone')
+    out.set(rel, text)
+  }
+  const optional = new Set(SOLIDITY_ROOT_MANIFESTS)
+  for (const path of sources.keys()) {
+    const dirs = [classifyDep(path)?.bucketDir, packageOf(path)?.pkgDir].filter((d) => d !== undefined)
+    for (const dir of dirs) for (const name of SOLIDITY_PACKAGE_MANIFESTS) optional.add(moduleFileKey(dir, name))
+  }
+  for (const rel of optional) {
+    if (sources.has(rel) || out.has(rel)) continue
+    const { text, why } = carry(rel)
+    if (why) console.warn(`[stasis] Not carrying ${rel}: ${why}`)
+    if (text !== undefined) out.set(rel, text)
+  }
+  return new Map([...out.keys()].toSorted().map((rel) => [rel, out.get(rel)]))
+}
+
+// An entry `stasis bundle` takes for a directory: one that is, or an extensionless path that
+// doesn't exist (a project without `script/` still bundles with `src test script`).
+export const isDirEntry = (abs, host = diskHost) => isDir(abs, host) || (extname(abs) === '' && host.stat(abs) === null)
+
+// Whether `entry` (resolved against `cwd`) is a Solidity bundle's: a .sol file or a directory entry.
+export const isSolidityEntry = (entry, cwd = process.cwd(), host = diskHost) => entry.endsWith('.sol') || isDirEntry(resolve(cwd, entry), host)
+
+// What's wrong with `entries`' directory entries (resolved against `cwd`), or null: a directory
+// entry stands for the .sol files under it, so it goes with Solidity entries only; and entries
+// that are all missing extensionless paths are a mistyped file, not a project without those dirs.
+// `fetched` false: `host` is an empty tree standing in for one not fetched yet, which can't say
+// what is missing.
+export function directoryEntryError(entries, cwd = process.cwd(), host = diskHost, { fetched = true } = {}) {
+  const dirs = entries.filter((e) => isDirEntry(resolve(cwd, e), host))
+  const absent = fetched ? dirs.filter((e) => host.stat(resolve(cwd, e)) === null) : []
+  if (absent.length > 0 && absent.length === entries.length) return `no such file or directory: ${absent[0]}`
+  if (dirs.length === 0 || entries.every((e) => e.endsWith('.sol') || dirs.includes(e))) return null
+  return absent.length > 0
+    ? `no such file or directory: ${absent[0]}`
+    : `a directory entry is only supported for Solidity bundles (it stands for the .sol files under it): ${dirs[0]}`
+}
+
+// Build an in-memory Bundle from entry .sol files and directories (a directory stands for the .sol
+// files under it, as forge's src/test/script dirs and Hardhat's contracts dir do; a missing or
+// empty one is skipped). Imports resolve through the remappings the project's build uses
+// (discoverSolidityConfig: forge's discovery for a Foundry project); `mappingFile`
+// (foundry.toml/remappings.txt) pins them to exactly what it lists. An import is refused when it
+// reaches a non-.sol file or leaves the root, or when a dependency's reaches the project's own
+// files. Config files are read, and bundled only with `manifests` (see solidityManifests). `env`
+// supplies FOUNDRY_PROFILE / FOUNDRY_REMAPPINGS, reported when they apply. The project is read
+// through `host`.
+export async function buildSolidityBundle({ cwd = process.cwd(), entries, mappingFile, manifests = false, env = process.env, host = diskHost } = {}) {
+  if (!Array.isArray(entries) || entries.length === 0) {
+    throw new Error('buildSolidityBundle: at least one entry .sol file or directory is required')
   }
 
   const baseDir = resolve(cwd)
-  const remappings = mappingFile ? await readRemappingsFile(resolve(cwd, mappingFile)) : []
   const normalized = normalizeEntries(entries, cwd)
+  for (const e of normalized) {
+    if (!isSolidityEntry(e, baseDir, host)) throw new Error(`buildSolidityBundle: not a .sol file or directory: ${e}`)
+  }
+  const expanded = expandSolidityEntries(baseDir, normalized, host)
 
-  const sources = await collectSolidityFilesFromDisk(baseDir, normalized, remappings)
-  const { resolutions, missing } = buildSolidityTree(sources, { remappings, baseDir })
+  const { remappings, libs, ownership, files: configFiles, envUsed } = discoverSolidityConfig(baseDir, { mappingFile, env, host })
+  // The bundle doesn't record the environment, so say when it shaped the resolution.
+  if (envUsed.length > 0) console.warn(`[stasis] Solidity imports resolved with ${envUsed.join(', ')} from the environment`)
+  const sources = collectSolidityFilesFromDisk(baseDir, expanded, remappings, { libs, ownership, host })
+  const { resolutions, missing } = buildSolidityTree(sources, { remappings, baseDir, libs, ownership, host })
 
-  // Bundles must be self-contained. Refuse to write one when an entry
-  // can't be loaded from disk, or when any in-bundle file has an import
-  // we couldn't resolve — otherwise downstream consumers would silently
-  // operate on a partial set of sources.
-  const issues = []
-  for (const entry of normalized) {
-    if (!sources.has(entry)) issues.push(`Missing entry: ${entry}`)
-  }
-  for (const { spec, from } of missing) {
-    issues.push(`Unresolved import: ${spec} from ${from}`)
-  }
-  if (issues.length > 0) {
-    throw new Error(`Solidity bundle has unresolved imports:\n${issues.map((s) => `  ${s}`).join('\n')}`)
+  assertSelfContained('Solidity', 'import', expanded, sources, missing)
+
+  const classifyDep = makeSolidityClassifier(baseDir, ownership, host)
+  const packageOf = packageLookup(baseDir, { strict: true, check: ownership.assert, host })
+  const bundled = new Map(sources)
+  const formats = new Map()
+  if (manifests) {
+    for (const [path, text] of solidityManifests(baseDir, sources, configFiles, { classifyDep, packageOf, ownership, host })) {
+      bundled.set(path, text)
+      formats.set(path, posix.basename(path) === 'package.json' ? 'json' : 'resource')
+    }
   }
 
   return assembleCodeBundle({
     baseDir,
-    entries: normalized,
-    sources,
+    entries: expanded,
+    sources: bundled,
     resolutions,
     workspaceName: SOLIDITY_WORKSPACE_NAME,
     workspaceVersion: SOLIDITY_WORKSPACE_VERSION,
     format: SOLIDITY_FORMAT,
+    formats,
     conditionKey: 'solidity',
-    classifyDep: makeSolidityClassifier(baseDir),
+    classifyDep,
+    packageOf,
+    host,
   })
 }
 
-// Build a stasis Bundle (in-memory) from a list of entry .sh/.bash files by
-// walking the source/exec graph and reading every reachable script from disk.
-// Mirrors buildSolidityBundle's bucketizing, with a bash-specific policy:
-//   - a .sh/.bash reference whose path lands INSIDE the bundle root
-//     (`source ./lib.sh`, `dir/x.sh`) but resolves to no bundled script is
-//     fatal — a self-contained bundle can't carry a dangling local source —
-//     as is a missing entry.
-//   - everything else is best-effort and dropped: PATH commands (`grep`,
-//     `node`), dynamic `$VAR` paths, extensionless sources, absolute system
-//     paths (`source /etc/profile.d/x.sh`), and `../` paths that escape the
-//     root — none can live in the bundle.
-//   - imports live under a dedicated "bash" condition key (like "solidity"),
-//     not the JS-bundle wildcard "*".
+// Build an in-memory Bundle from entry .sh/.bash files by walking the source/exec graph.
+// A local `source` inside the bundle root that resolves to no bundled script is fatal;
+// external refs (PATH commands, `$VAR`, absolute, `../`-escaping) are dropped.
 export async function buildBashBundle({ cwd = process.cwd(), entries } = {}) {
   if (!Array.isArray(entries) || entries.length === 0) {
     throw new Error('buildBashBundle: at least one entry .sh/.bash file is required')
@@ -396,21 +408,8 @@ export async function buildBashBundle({ cwd = process.cwd(), entries } = {}) {
   const sources = await collectBashFilesFromDisk(baseDir, normalized)
   const { resolutions, missing } = buildBashTree(sources)
 
-  // Bundles must be self-contained: every entry must load, and every .sh/.bash
-  // reference pointing inside the bundle root must resolve to a bundled script.
-  // External/best-effort references (commands, $VAR paths, extensionless,
-  // absolute, or `../`-escaping sources) are left out by buildBashTree and
-  // never reach `missing`.
-  const issues = []
-  for (const entry of normalized) {
-    if (!sources.has(entry)) issues.push(`Missing entry: ${entry}`)
-  }
-  for (const { spec, from } of missing) {
-    issues.push(`Unresolved script: ${spec} from ${from}`)
-  }
-  if (issues.length > 0) {
-    throw new Error(`Bash bundle has unresolved scripts:\n${issues.map((s) => `  ${s}`).join('\n')}`)
-  }
+  // Self-contained (external refs never reach `missing`).
+  assertSelfContained('Bash', 'script', normalized, sources, missing)
 
   return assembleCodeBundle({
     baseDir,
@@ -419,20 +418,27 @@ export async function buildBashBundle({ cwd = process.cwd(), entries } = {}) {
     resolutions,
     workspaceName: BASH_WORKSPACE_NAME,
     workspaceVersion: BASH_WORKSPACE_VERSION,
-    format: BASH_FORMAT,
-    conditionKey: 'bash',
+    format: SHELL_FORMAT,
+    conditionKey: SHELL_FORMAT,
   })
 }
 
-// Build a stasis Bundle (in-memory) from a list of entry .rs files by walking
-// `mod` declarations from each crate root and reading every reachable module
-// from disk. The bundle must be self-contained: an unresolvable `mod foo;`
-// (no backing file) is fatal, as is a missing entry. `use crate::` edges are
-// recorded in the import graph but stay best-effort — they never widen the
-// file set, and their resolution is approximate (item-vs-module, re-exports),
-// so they aren't gated; external crates and std are ignored outright. Imports
-// live under a dedicated "rust" condition key.
-export async function buildRustBundle({ cwd = process.cwd(), entries } = {}) {
+// Build an in-memory Bundle from entry .rs files (crate roots) by walking `mod` declarations and
+// references to in-tree crates (the package's own lib, Cargo `path` deps, `cargo vendor`ed
+// crates). An unresolvable unconditional `mod` is fatal; path edges (`crate::`/`self::`/`super::`/
+// relative `use`s) are recorded best-effort and never widen the file set. Registry deps that
+// aren't vendored can't be bundled: they're reported, with a `cargo vendor` hint when there is no
+// `vendor/` dir at all. Each crate's features are resolved from the manifests (Cargo.toml +
+// Cargo.lock) the way `cargo build` of the entries' packages would, so `#[cfg(feature = …)]` code
+// that is off stays out; `cargo` takes them from `cargo metadata` instead (opt-in: it runs cargo).
+// `cargoFeatures` / `cargoNoDefaultFeatures` / `cargoAllFeatures` are cargo's `--features` /
+// `--no-default-features` / `--all-features` for the entries' packages, in either mode.
+// `cargoTarget` (a triple, or `host`) names the build's target: its cfgs, asked of rustc, decide
+// `#[cfg(unix)]`-style code and target-specific dependency tables, which are otherwise all kept.
+// `cargoManifests` also carries what describes each bundled package's build: its Cargo.toml (and
+// the workspace's), its build script -- walked like a crate root, so its modules and the in-tree
+// build-dependencies it reaches come along -- plus the root's Cargo.lock and .cargo/config.toml.
+export async function buildRustBundle({ cwd = process.cwd(), entries, cargo = false, cargoFeatures = [], cargoNoDefaultFeatures = false, cargoAllFeatures = false, cargoTarget = null, cargoManifests = false } = {}) {
   if (!Array.isArray(entries) || entries.length === 0) {
     throw new Error('buildRustBundle: at least one entry .rs file is required')
   }
@@ -443,18 +449,76 @@ export async function buildRustBundle({ cwd = process.cwd(), entries } = {}) {
   const baseDir = resolve(cwd)
   const normalized = normalizeEntries(entries, cwd)
 
-  const sources = await collectRustFilesFromDisk(baseDir, normalized)
-  const { resolutions, missing } = buildRustTree(sources)
+  // One Cargo context for the walk, the edge pass and the bucketing: manifests are read once, and
+  // the walk's crate resolution and the tree's feature decisions agree.
+  const cargoCtx = createCargoContext(baseDir, {
+    entries: normalized,
+    cargo,
+    features: cargoFeatures,
+    noDefaultFeatures: cargoNoDefaultFeatures,
+    allFeatures: cargoAllFeatures,
+    target: cargoTarget,
+  })
+  // `include_str!` / `include_bytes!` assets ride along as resources: the walk records their
+  // format. With `cargoManifests`, each package's build script is walked too (collectRustBundle).
+  const { sources, formats, tree } = await collectRustBundle(baseDir, normalized, { cargo: cargoCtx, buildScripts: cargoManifests })
+  if (cargoManifests) {
+    // Each bundled package's manifests, and its workspace's lockfile and cargo config, carried as
+    // written: whatever they hold (a registry token, a `git` URL's credentials) is in the bundle
+    // too, as with --package-json. A file that isn't UTF-8 text is refused, not altered.
+    const files = new Set()
+    for (const path of sources.keys()) for (const f of cargoCtx.buildFilesFor(path)) files.add(f.path)
+    const realBase = realpathSync(baseDir)
+    for (const rel of files) {
+      if (sources.has(rel)) continue
+      const buf = readFileWithinBase(baseDir, realBase, rel, boundaryOf(rel, cargoCtx))
+      if (buf === null) continue
+      cargoCtx.checkVendoredFile(rel, buf)
+      if (!isUtf8(buf)) throw new Error(`Rust manifest is not valid UTF-8: ${rel}`)
+      sources.set(rel, buf.toString('utf8'))
+      formats.set(rel, 'resource')
+    }
+  }
+  const { resolutions, missing, unresolvedCrates } = tree
 
-  const issues = []
-  for (const entry of normalized) {
-    if (!sources.has(entry)) issues.push(`Missing entry: ${entry}`)
+  assertSelfContained('Rust', 'module', normalized, sources, missing)
+
+  // Where the features the cfg decisions rest on come from: cargo's resolver, or -- something it
+  // takes missing -- a replay of the manifests, said so (a project without Cargo has neither).
+  const resolution = cargoCtx.resolution()
+  if (resolution.mode === 'replay' && normalized.some((e) => cargoCtx.packageInfo(e) !== null)) {
+    console.warn(`[stasis] Rust features from a replay of the manifests, not cargo's resolver: ${resolution.why}`)
   }
-  for (const { spec, from } of missing) {
-    issues.push(`Unresolved module: ${spec} from ${from}`)
+  // EXODUS_STASIS_DEBUG=1: show the feature resolution the cfg decisions came from, per package and
+  // context, so the replay, cargo's resolver and `cargo metadata` (which unifies dev/build deps
+  // like resolver 1) can be compared.
+  if (process.env.EXODUS_STASIS_DEBUG === '1' || process.env.EXODUS_STASIS_DEBUG === 'true') {
+    const mode = { cargo: "cargo's resolver", metadata: 'cargo metadata', replay: 'manifest replay' }[resolution.mode]
+    for (const context of ['target', 'host']) {
+      const resolved = [...cargoCtx.resolvedFeatures(context)].toSorted(([a], [b]) => (a < b ? -1 : 1))
+      console.warn(`[stasis] Rust features (${mode}, ${context}), ${resolved.length} package${resolved.length === 1 ? '' : 's'}:`)
+      for (const [dir, set] of resolved) {
+        const pkg = cargoCtx.packageInfo(moduleFileKey(dir, 'Cargo.toml'))
+        console.warn(`[stasis]   ${pkg?.name ?? '?'}@${pkg?.version ?? '?'} (${dir}): ${[...set].toSorted().join(', ') || '(none)'}`)
+      }
+    }
   }
-  if (issues.length > 0) {
-    throw new Error(`Rust bundle has unresolved modules:\n${issues.map((s) => `  ${s}`).join('\n')}`)
+
+  // A crate the code names that the bundle doesn't hold: a registry dependency that isn't vendored
+  // (or not in a version its requirement allows), a path or patch outside the bundle root (the
+  // loader warned of those), or a crate root the walk refused -- and any other dependency a bundled
+  // package's build links that nothing in-tree answers, however the code names it, if at all.
+  // Reported whatever the vendor dir holds; with none, the fix is one command.
+  const notLoaded = tree.wantedRoots.filter((r) => !sources.has(r)).map((r) => `${cargoCtx.packageInfo(r)?.name ?? r} (${r})`)
+  const bundledPackages = new Set([...sources.keys()].map((p) => cargoCtx.packageInfo(p)?.dir).filter((d) => d !== undefined))
+  const lacking = cargoCtx.lackingDependencies(bundledPackages, { buildScripts: cargoManifests })
+    .filter((d) => !unresolvedCrates.has(d.key))
+    .map((d) => `${d.name} (a dependency of ${d.from})`)
+  if (unresolvedCrates.size > 0 || notLoaded.length > 0 || lacking.length > 0) {
+    const names = [...new Set([...unresolvedCrates, ...notLoaded, ...lacking])].toSorted()
+    const shown = names.slice(0, 10).join(', ') + (names.length > 10 ? `, ... and ${names.length - 10} more` : '')
+    console.warn(`[stasis] ${names.length} crate${names.length === 1 ? '' : 's'} referenced but not in the bundle: ${shown}`)
+    if (!existsSync(join(baseDir, cargoCtx.vendorDir))) console.warn('[stasis] Registry dependencies are bundled only when vendored in-tree: run `cargo vendor` first.')
   }
 
   return assembleCodeBundle({
@@ -465,30 +529,16 @@ export async function buildRustBundle({ cwd = process.cwd(), entries } = {}) {
     workspaceName: RUST_WORKSPACE_NAME,
     workspaceVersion: RUST_WORKSPACE_VERSION,
     format: RUST_FORMAT,
+    formats,
     conditionKey: 'rust',
-    classifyDep: makeRustClassifier(baseDir),
+    classifyDep: makeRustClassifier(cargoCtx),
   })
 }
 
-// Build a stasis Bundle (in-memory) from a list of entry .php files by
-// statically scanning their `require`/`include` graph -- and, when the project
-// uses Composer, the class-autoload graph too -- reading every reachable file
-// from disk. No PHP is ever executed. Mirrors buildSolidityBundle: files are
-// bucketed per package.json, tagged with the `php` format, and edges are keyed
-// under a dedicated "php" condition bucket.
-//
-// Composer autoloading is followed automatically when a composer.json (or
-// generated vendor/composer/autoload_*.php map) is present: PSR-4/PSR-0/
-// classmap/files config is read and the classes each file references (`use`
-// imports, `new`/`extends`/`implements`, type hints, …) are resolved to their
-// files the way Composer's ClassLoader would. That resolution is best-effort
-// (unresolvable references are typically built-in or extension classes), so it
-// never blocks the bundle; explicit `require`/`include` of a literal path is
-// still strict.
-//
-// Refuses to write when an entry can't be loaded or any explicit include is
-// unresolved -- a bundle with holes would silently operate on a partial set of
-// sources.
+// Build an in-memory Bundle from entry .php files by statically scanning the
+// require/include graph (and Composer's class-autoload graph when present); no PHP is
+// executed. Autoload resolution is best-effort; explicit require/include of a literal path
+// is strict, and a missing entry or unresolved explicit include is fatal.
 export async function buildPhpBundle({ cwd = process.cwd(), entries } = {}) {
   if (!Array.isArray(entries) || entries.length === 0) {
     throw new Error('buildPhpBundle: at least one entry .php file is required')
@@ -500,58 +550,49 @@ export async function buildPhpBundle({ cwd = process.cwd(), entries } = {}) {
   const baseDir = resolve(cwd)
   const normalized = normalizeEntries(entries, cwd)
   const autoload = loadComposerAutoload(baseDir)
+  // The Composer packages, of composer.lock (vendor/composer/installed.json held identical to it
+  // where both are), or of installed.json alone: read once, before anything is scanned.
+  const packages = loadComposerPackages(baseDir)
 
-  // Laravel auto-discovers vendor/app service providers (via composer metadata
-  // and bootstrap/providers.php) rather than referencing them statically; seed
-  // them as extra roots so the config/route/view files they pull in get bundled.
-  const providerRoots = loadLaravelProviderFiles(baseDir, autoload)
+  // Laravel auto-discovers service providers rather than referencing them statically; seed
+  // them as extra roots so their config/route/view files get bundled.
+  const providerRoots = loadLaravelProviderFiles(baseDir, autoload, packages)
 
   const sources = await collectPhpFilesFromDisk(baseDir, [...normalized, ...providerRoots], { autoload })
   const { resolutions, missing } = buildPhpTree(sources, { baseDir, autoload })
 
-  const issues = []
-  for (const entry of normalized) {
-    if (!sources.has(entry)) issues.push(`Missing entry: ${entry}`)
-  }
-  for (const { spec, from } of missing) {
-    issues.push(`Unresolved import: ${spec} from ${from}`)
-  }
-  if (issues.length > 0) {
-    throw new Error(`PHP bundle has unresolved imports:\n${issues.map((s) => `  ${s}`).join('\n')}`)
-  }
-
-  // Group per Composer package (vendor/<pkg> buckets with name+version from
-  // composer.json / installed.json), not the node_modules-based bucketizer.
-  const modules = bucketizePhpSources(baseDir, sources, PHP_WORKSPACE_NAME, PHP_WORKSPACE_VERSION)
-
-  const formats = new Map()
-  for (const path of sources.keys()) formats.set(path, PHP_FORMAT)
+  assertSelfContained('PHP', 'import', normalized, sources, missing)
 
-  // PHP includes don't depend on Node conditions; key them under a dedicated
-  // "php" bucket rather than the wildcard "*" used for JS code bundles.
-  const importsForKey = new Map()
-  for (const [parent, specMap] of resolutions) importsForKey.set(parent, specMap)
-  const imports = new Map([['php', importsForKey]])
-
-  return new Bundle({
-    config: { scope: 'full' },
-    entries: new Set(normalized),
-    modules,
-    formats,
-    imports,
+  return codeBundle({
+    baseDir,
+    entries: normalized,
+    sources,
+    // Group per Composer package (vendor/<pkg>), not the node_modules bucketizer.
+    modules: bucketizePhpSources(baseDir, sources, PHP_WORKSPACE_NAME, PHP_WORKSPACE_VERSION, packages),
+    resolutions,
+    format: PHP_FORMAT,
+    // PHP includes don't vary by Node condition; key edges under "php", not the JS wildcard "*".
+    conditionKey: 'php',
   })
 }
 
-// Classify a scanner's unresolved edges + parse errors into `fatal` (the bundle
-// would be broken, or silently divergent from plain node, at load) vs tolerated
-// (a miss runtime code can catch). The rationale for each rule lives at the call
-// site in buildJsBundle; this is the shared computation so the plain and the
-// resolver-driven (`--mainFields`) JS paths gate identically.
-function analyzeScanner(scanner) {
-  // Static reachability: files reached from an entry through static ESM
-  // `import`/`export ... from` edges load eagerly, before any user code runs, so
-  // a failure there is uncatchable; below a require()/dynamic-import() boundary it
-  // surfaces as a catchable miss and only warns.
+// Render a scanned file URL for diagnostics: project-relative when inside `baseDir`, else absolute.
+// The scan issue checks run on the LIVE scan, whose files/imports are keyed by absolute file: URLs
+// (the resolver returns absolute paths); relativizing here matches the project-relative paths the
+// bundle itself stores (toRel), rather than leaking the machine's absolute paths into the message.
+function displayPath(url, baseDir) {
+  const abs = fileURLToPath(url)
+  const rel = relative(baseDir, abs)
+  return rel && !relativeEscapes(rel) ? rel : abs
+}
+
+// Classify scanner unresolved edges + parse errors into fatal (broken/divergent at load)
+// vs tolerated (a catchable runtime miss). Shared so the plain and --mainFields JS paths
+// gate identically. `baseDir` relativizes the paths in the emitted messages (see displayPath).
+function analyzeScanner(scanner, { baseDir }) {
+  const show = (url) => displayPath(url, baseDir)
+  // Static ESM import/export-from edges load eagerly before user code, so a failure there is
+  // uncatchable (fatal); misses below a require()/dynamic-import() boundary are catchable (warn).
   const staticKinds = new Set(['import', 'export-from'])
   const staticReachable = new Set(scanner.entries)
   const walk = [...scanner.entries]
@@ -566,20 +607,19 @@ function analyzeScanner(scanner) {
   const fatalUnresolved = (u) => staticKinds.has(u.kind) && staticReachable.has(u.parentURL)
   const fatal = scanner.unresolved
     .filter((u) => fatalUnresolved(u))
-    .map((u) => `unresolved ${u.kind} ${u.spec} from ${fileURLToPath(u.parentURL)} (${u.reason})`)
-  // Parse failures whose edges are genuinely unknown: a module-family file in the
-  // eagerly-linked set, or any file the parser couldn't process at all.
+    .map((u) => `unresolved ${u.kind} ${u.spec} from ${show(u.parentURL)} (${u.reason})`)
+  // Fatal parse: an eagerly-linked module-family file, or any file the parser couldn't process.
   const fatalParse = (p) => staticReachable.has(p.url) && (p.format?.startsWith('module') === true || !p.recovered)
   for (const p of scanner.parseErrors) {
-    if (fatalParse(p)) fatal.push(`parse error in ${fileURLToPath(p.url)}: ${p.message}`)
+    if (fatalParse(p)) fatal.push(`parse error in ${show(p.url)}: ${p.message}`)
   }
-  // Edges resolving to a file a source bundle can't carry (extensionless, .node,
-  // .wasm): scan records the edge but never queues the child, so load would die.
+  // Edge resolving to a file a source bundle can't carry (.node/.wasm/extensionless): scan
+  // records it but never queues the child, so load would die.
   for (const [, byParent] of scanner.imports) {
     for (const [parentURL, specMap] of byParent) {
       for (const [spec, childURL] of specMap) {
         if (!scanner.files.has(childURL)) {
-          fatal.push(`${spec} from ${fileURLToPath(parentURL)} resolves to ${fileURLToPath(childURL)}, which a source bundle can't carry`)
+          fatal.push(`${spec} from ${show(parentURL)} resolves to ${show(childURL)}, which a source bundle can't carry`)
         }
       }
     }
@@ -589,67 +629,47 @@ function analyzeScanner(scanner) {
   return { fatal, tolerated, toleratedParse }
 }
 
-// Throw on any fatal scan issue (the bundle can't be written); warn on tolerated
-// ones. `label`, when set, tags the scan pass in the message.
-function reportScanIssues({ fatal, tolerated, toleratedParse }, { label = '' } = {}) {
+// Throw on fatal scan issues; warn on tolerated ones. `label` tags the scan pass; `baseDir`
+// relativizes the paths in the warnings (see displayPath), matching analyzeScanner's messages.
+function reportScanIssues({ fatal, tolerated, toleratedParse }, { label = '', baseDir }) {
   const where = label ? ` (${label})` : ''
+  const show = (url) => displayPath(url, baseDir)
+  // The first 10 of `items` as indented lines (`line` renders one), then how many more there are.
+  const listed = (items, line = (s) => s) => {
+    const more = items.length > 10 ? `\n  ... and ${items.length - 10} more` : ''
+    return items.slice(0, 10).map((x) => `  ${line(x)}`).join('\n') + more
+  }
   if (fatal.length > 0) {
-    const shown = fatal.slice(0, 10).map((s) => `  ${s}`).join('\n')
-    const more = fatal.length > 10 ? `\n  ... and ${fatal.length - 10} more` : ''
-    throw new Error(`JS bundle would be broken at load time${where}:\n${shown}${more}`)
+    throw new Error(`JS bundle would be broken at load time${where}:\n${listed(fatal)}`)
   }
   if (tolerated.length > 0) {
-    const summary = tolerated
-      .slice(0, 10)
-      .map((u) => `  ${u.kind} ${u.spec ?? '<dynamic>'} from ${fileURLToPath(u.parentURL)} (${u.reason})`)
-      .join('\n')
-    const more = tolerated.length > 10 ? `\n  ... and ${tolerated.length - 10} more` : ''
-    console.warn(`[stasis] Bundle has ${tolerated.length} unresolved import(s)${where}; they will fall through at load time:\n${summary}${more}`)
+    const summary = listed(tolerated, (u) => `${u.kind} ${u.spec ?? '<dynamic>'} from ${show(u.parentURL)} (${u.reason})`)
+    console.warn(`[stasis] Bundle has ${tolerated.length} unresolved import(s)${where}; they will fall through at load time:\n${summary}`)
   }
   if (toleratedParse.length > 0) {
-    const summary = toleratedParse
-      .slice(0, 10)
-      .map((p) => `  ${fileURLToPath(p.url)}: ${p.message}`)
-      .join('\n')
-    const more = toleratedParse.length > 10 ? `\n  ... and ${toleratedParse.length - 10} more` : ''
-    console.warn(`[stasis] Bundle has ${toleratedParse.length} file(s) with parse errors${where}; their recorded imports may be incomplete:\n${summary}${more}`)
+    const summary = listed(toleratedParse, (p) => `${show(p.url)}: ${p.message}`)
+    console.warn(`[stasis] Bundle has ${toleratedParse.length} file(s) with parse errors${where}; their recorded imports may be incomplete:\n${summary}`)
   }
 }
 
-// Build a stasis Bundle (in-memory) from a list of entry .js/.cjs/.mjs (or
-// .ts/.cts/.mts) files by statically scanning the require/import graph and
-// reading reachable file contents from disk -- no user code is ever loaded or
-// executed. TypeScript files behave exactly like JS ones: sources are stored
-// verbatim with Node's type-stripping formats recorded, and Node strips the
-// types at load time. The bundle shape matches what @exodus/stasis-core/hooks
-// records at runtime, so the result loads via `stasis run --bundle=load`
-// interchangeably with a runtime-produced one.
-//
-// Refuses to write when the bundle is guaranteed broken (or silently divergent
-// from plain node) at load time: an unresolved static ESM `import`/`export ...
-// from` edge reachable from an entry through static edges alone (link-time,
-// uncatchable), a module file that can't be parsed (its static edges are
-// unknown), or an edge resolving to a file a source bundle can't carry
-// (extensionless, .node, .wasm). Failures that runtime code can catch --
-// unresolved require()/dynamic import() edges, including entire subtrees
-// behind such a boundary -- only warn (see below).
-//
-// Scope comes from the project's stasis.config.json (or `EXODUS_STASIS_SCOPE`);
-// pass `scope` explicitly to override.
-//
-// `conditions` are extra `exports`/`imports` resolution conditions, merged on top
-// of the format-derived base set Node always asserts (`node`, `import`/`require`,
-// `module-sync`, `node-addons`). They change which branch of a package's
-// conditional `exports` the static scan follows -- and therefore which file lands
-// in the bundle -- exactly as if Node resolved with those conditions active. Empty
-// (the default) reproduces plain Node resolution.
-//
-// NOTE: conditions are only one input to module resolution. On their own they do
-// NOT honour legacy package `mainFields` (`react-native`/`browser`/`main`) or
-// platform-specific file suffixes (`.ios`/`.android`/`.native`), neither of which
-// the `exports` field expresses; `--mainFields` (see buildResolvedJsBundle) adds
-// the former.
-export async function buildJsBundle({ cwd = process.cwd(), entries, scope, conditions = [] } = {}) {
+// Normalize conditions (trim, drop empties) so a sloppy programmatic caller can't push a bogus
+// token into the resolver.
+const cleanConditions = (conditions) => conditions.map((c) => (typeof c === 'string' ? c.trim() : c)).filter(Boolean)
+
+// --typescript honours tsconfig `paths` aliases: an explicit --tsconfig must exist, otherwise the
+// project root's tsconfig.json applies when present (null matcher = no aliases).
+const typescriptPathsFor = (typescript, baseDir, tsconfig, host) => (typescript ? loadTsconfigPaths(discoverTsconfig(baseDir, tsconfig, host), host) : null)
+
+// Build a JS/TS Bundle (in-memory) by statically scanning the require/import graph; no
+// user code is executed, and TS is stored verbatim (Node strips types at load). Scope comes
+// from stasis.config.json / `EXODUS_STASIS_SCOPE` unless `scope` overrides. `conditions` are
+// extra `exports`/`imports` conditions; on their own they don't honour legacy mainFields or
+// platform suffixes (see `--mainFields` / buildResolvedJsBundle). `typescript` maps a failed
+// resolution to its on-disk TS source (tsc's rules; see resolve-typescript.js), honouring the
+// `paths` aliases of `tsconfig` (an explicit config path, default the project's tsconfig.json).
+// Files are read through `host` (@exodus/stasis-core/host), the disk by default; EXODUS_STASIS_*
+// settings from `env`.
+export async function buildJsBundle({ cwd = process.cwd(), env = process.env, entries, scope, conditions = [], jsx = false, flow = false, typescript = false, tsconfig, resources = [], packageJSON = false, host = diskHost } = {}) {
   if (!Array.isArray(entries) || entries.length === 0) {
     throw new Error('buildJsBundle: at least one entry .js/.cjs/.mjs/.ts/.cts/.mts file is required')
   }
@@ -660,126 +680,199 @@ export async function buildJsBundle({ cwd = process.cwd(), entries, scope, condi
   const baseDir = resolve(cwd)
   const absEntries = entries.map((e) => resolve(baseDir, e))
 
-  // Normalize conditions the way the CLI already does (trim, drop empties), so the
-  // programmatic API (`buildBundle({ conditions })`) tolerates the same sloppy input.
-  // A '' or whitespace-only condition never matches an `exports` key, so dropping it
-  // is a no-op for clean input -- this just stops a bogus token reaching the resolver.
-  const scanConditions = conditions.map((c) => (typeof c === 'string' ? c.trim() : c)).filter(Boolean)
-
-  const scanner = scan(absEntries, { conditions: scanConditions })
-
-  // Fail closed exactly where the bundle is GUARANTEED broken (or silently
-  // divergent from plain node) at load time; warn where runtime code can catch
-  // the miss the same way it would without a bundle. Static ESM edges load
-  // eagerly (uncatchable) so unresolved ones / unknown parse holes there are
-  // fatal; require()/dynamic-import() misses surface at the callsite and only
-  // warn -- the optional-dependency pattern (`try { require(x) } catch {}`) keeps
-  // bundling, because the runtime loader never records those edges either and
-  // state.getImport throws the same catchable MODULE_NOT_FOUND at load. Edges
-  // resolving to a file a source bundle can't carry are always fatal. (See
-  // analyzeScanner for the precise rules.)
-  reportScanIssues(analyzeScanner(scanner))
-
-  // Use a non-preload State to materialise the bundle: addFile bucketizes by
-  // package.json + records hashes/sources/formats, and addImport replays the
-  // per-edge import map. State.s `serialize` then emits the same v1 layout
-  // the runtime loader writes — see @exodus/stasis-core/hooks for the matching pair.
-  //
-  // bundle=replace skips reading any pre-existing stasis.code.br on disk;
-  // bundle=add would merge it, leaking stale formats/imports entries for
-  // files the new bundle doesn't carry. lock=ignore tolerates a pre-existing
-  // stasis.lock.json without loading or validating it (the bundle path
-  // doesn't consume one), and refusing to coexist with one (lock=none) would
-  // make `stasis bundle` brittle in any project that's also using `stasis run`.
-  const state = new State(baseDir, { bundle: 'replace', lock: 'ignore', ...(scope ? { scope } : {}) })
+  const scanConditions = cleanConditions(conditions)
+  // --resources: extensions/filenames carried as opaque assets instead of failing "can't carry".
+  const resourceSet = parseResourcesOption('buildJsBundle', resources)
+
+  const typescriptPaths = typescriptPathsFor(typescript, baseDir, tsconfig, host)
+
+  const scanner = scan(absEntries, { conditions: scanConditions, jsx, flow, typescript, typescriptPaths, resources: resourceSet, host })
+
+  // Fail closed where the bundle is guaranteed broken at load; warn on catchable misses (see analyzeScanner).
+  reportScanIssues(analyzeScanner(scanner, { baseDir }), { baseDir })
+
+  // Materialise via a non-preload State: addFile bucketizes + records sources/formats,
+  // addImport replays the edge map; serialize emits the runtime loader's v1 layout.
+  // bundle:'replace' skips reading any on-disk stasis.code.br (bundle:'add' would leak stale
+  // entries); lock:'ignore' tolerates a pre-existing lockfile without consuming it; and it is never
+  // written, so it claims no write target.
+  const state = new State(baseDir, { bundle: 'replace', lock: 'ignore', ...(scope ? { scope } : {}), host, env, claim: false })
   for (const [url, info] of scanner.files) {
+    // A resource carries bytes only: addFile derives resource vs resource:base64 from the content
+    // and stores it under `resources` (a resource can't be an entry, so no isEntry).
+    if (info.resource) {
+      state.addFile(url, { resource: true })
+      continue
+    }
     const isEntry = scanner.entries.has(url)
     state.addFile(url, { format: info.format, isEntry })
   }
-  // Static bundles can't anticipate the full condition set Node will pass to
-  // its resolve hook at load time (Node adds runtime conditions like
-  // 'module-sync', 'node-addons' that aren't accept-list conditions). Store
-  // every edge under the wildcard '*' key; State.getImport falls back to it
-  // when the runtime-condition lookup misses.
-  for (const [, byParent] of scanner.imports) {
-    for (const [parentURL, specs] of byParent) {
+  // Edges where every context agrees keep the wildcard '*' key (getImport's fallback when a
+  // condition lookup misses). Where the require()- and import()-context resolutions of one
+  // (parent, specifier) DIVERGE, each target keeps its real condition key -- one '*' entry
+  // would serve one context the other's file; an unmatched set fails closed via resolveBundled.
+  const byParent = new Map()
+  for (const [key, parents] of scanner.imports) {
+    for (const [parentURL, specs] of parents) {
+      if (!byParent.has(parentURL)) byParent.set(parentURL, new Map())
+      const bySpec = byParent.get(parentURL)
       for (const [spec, childURL] of specs) {
-        state.addImport(parentURL, spec, childURL, { conditions: '*' })
+        if (!bySpec.has(spec)) bySpec.set(spec, new Map())
+        bySpec.get(spec).set(key, childURL)
       }
     }
   }
+  for (const [parentURL, bySpec] of byParent) {
+    for (const [spec, byKey] of bySpec) {
+      const targets = new Set(byKey.values())
+      if (targets.size === 1) {
+        state.addImport(parentURL, spec, [...targets][0], { conditions: '*' })
+      } else {
+        for (const [key, childURL] of byKey) {
+          state.addImport(parentURL, spec, childURL, { conditions: key.split(', ') })
+        }
+      }
+    }
+  }
+  // --package-json: fold each bundled module's package.json into the State's buckets (idempotent --
+  // no-ops any manifest the scan already reached). State's bundle=replace makes writeBundle true, so addFile accepts them.
+  if (packageJSON) state.includePackageJson()
   return state
 }
 
-// Source extensions probed when a resolved entry/redirect target names no extension.
-// Limited to what a source bundle can actually carry (scan's RESOLVABLE_EXTS), so the
-// resolver never resolves a file the bundle would then reject. `--mainFields` lets a
-// caller pick its own fields, `--metro` presets the React Native fields, and
-// `--conditions` adds its own extra exports conditions.
+// Extensions probed when a resolved target names none. Limited to what a source bundle can
+// carry (scan's RESOLVABLE_EXTS) so the resolver never resolves a file the bundle would reject.
+// --jsx widens this to the JSX/TSX extensions (mirroring scan's jsx-gated RESOLVABLE_EXTS) so an
+// extensionless `import './Foo'` can land on Foo.jsx/Foo.tsx, as Metro's sourceExts do. `.js`/`.ts`
+// keep their existing precedence (base order preserved as a subsequence); collisions across the
+// added extensions are rare and, like the base list, don't track the project's real Metro order.
 const SOURCE_EXTS = ['js', 'json', 'ts']
-// React Native preset mainFields asserted by `--metro` (which sets these plus the
-// react-native/browser conditions and platform suffixes, so the user supplies neither
-// --mainFields nor --conditions alongside it).
+const SOURCE_EXTS_JSX = ['js', 'jsx', 'json', 'ts', 'tsx']
+// React Native preset mainFields for `--metro` (which also sets the RN conditions + platform suffixes).
 const METRO_MAIN_FIELDS = ['react-native', 'browser', 'main']
-// Synthetic, project-relative path for the empty module a browser/react-native
-// `false` redirect resolves to. Carried in the bundle as a real (empty) CJS file
-// so the edge points at attestable bytes rather than a sentinel.
+// Synthetic path for the empty module a browser/react-native `false` redirect resolves to,
+// carried as a real empty CJS file so the edge points at attestable bytes.
 const EMPTY_MODULE_PATH = '.stasis/empty-module.js'
 
-// Build a JS/TS Bundle (and companion Lockfile) through the legacy-field resolver
-// (src/resolve-fields.js) rather than Node's resolver -- the `--mainFields` and
-// `--metro` paths. The graph is scanned once PER platform (just `[null]` in
-// `--mainFields` mode, where there are no platform suffixes); the file set is the union
-// across platforms, and each `(parent, specifier)` edge is recorded FLAT (a single
-// target) when every platform that has it agrees, and UNFLATTENED to a
-// `{ platform: target }` map only where platforms genuinely diverge. A single platform
-// therefore never unflattens; platform keys are exactly the supplied platforms (no
-// wildcard). A browser/react-native `false` redirect resolves to a synthetic empty
-// module carried in the bundle. Returns { bundle, lockfile } (the lockfile attests the
-// same files + the same -- possibly per-platform -- edges, by integrity).
-async function buildResolvedJsBundle({ cwd = process.cwd(), entries, mainFields, platforms, conditions = [], metro = false }) {
+// Recursively collect the files under `dirAbs` whose name `keep` takes, skipping build output,
+// symlinks (cycle/escape hazard) and, directly in `dirAbs`, the dirs `skipAtRoot` names. Absolute
+// paths into `out`.
+function walkNative(dirAbs, out, host, keep, skipAtRoot) {
+  let entries
+  try {
+    entries = host.readdir(dirAbs)
+  } catch {
+    return // absent -- nothing for this platform
+  }
+  for (const ent of entries) {
+    if (ent.isSymbolicLink()) continue
+    const full = join(dirAbs, ent.name)
+    if (ent.isDirectory()) {
+      if (!isSkippedNativeWalkDir(ent.name) && !skipAtRoot?.(ent.name)) walkNative(full, out, host, keep)
+    } else if (ent.isFile() && keep(ent.name)) {
+      out.push(full)
+    }
+  }
+}
+
+// The files of a native ios/android dir: all but build artifacts.
+const isNativeSource = (name) => !isNativeArtifact(name)
+
+// Native source files a bundled RN dep contributes to the app's native build (podspecs +
+// ios/android sources). Manifests are kept only when the package is actually native (podspec
+// or ios/android dir), else a JS-only dep's package.json would be pulled in. Deduped absolute paths.
+function nativeModuleFiles(pkgAbs, host) {
+  // Podspec-load manifests: RN's own podspecs live in scattered subdirs a root-only scan would miss,
+  // so recurse fully.
+  const manifests = []
+  walkNative(pkgAbs, manifests, host, isNativeManifest, isExcludedNativeDir)
+  const hasIos = host.stat(join(pkgAbs, 'ios')) !== null
+  const hasAndroid = host.stat(join(pkgAbs, 'android')) !== null
+  if (!hasIos && !hasAndroid && !manifests.some((f) => isPodspec(f))) return []
+  const out = [...manifests]
+  if (hasIos) walkNative(join(pkgAbs, 'ios'), out, host, isNativeSource)
+  if (hasAndroid) walkNative(join(pkgAbs, 'android'), out, host, isNativeSource)
+  return [...new Set(out)]
+}
+
+// The built-in field/suffix resolver (resolve-fields.js) the legacy-field build resolves with on
+// `platform` (null for --mainFields), its `mainFields` (Metro's under --metro), and the conditions
+// it adds to Node's: --metro asserts the RN conditions (+ browser on web); --mainFields carries the
+// user's --conditions.
+export function fieldResolverFor(platform, { mainFields, metro = false, conditions = [], jsx = false, typescript = false, typescriptPaths = null, host = diskHost }) {
+  const extras = metro ? ['react-native', ...(platform === 'web' ? ['browser'] : [])] : conditions
+  const fields = metro ? METRO_MAIN_FIELDS : mainFields
+  const resolver = createFieldResolver({
+    mainFields: fields,
+    platform,
+    preferNative: platform !== null && platform !== 'web',
+    // Under --jsx the resolver probes .jsx/.tsx too, matching scan's jsx-widened carryable set.
+    sourceExts: jsx ? SOURCE_EXTS_JSX : SOURCE_EXTS,
+    conditions: resolveConditions('commonjs', extras),
+    // Opt into Metro's package-entry browser-field quirks only on the --metro path.
+    metro,
+    // --typescript: tsc's mapping, inside the field resolver (the scanner's own fallback
+    // only backs the built-in resolver). Unreachable under --metro-resolver
+    // (classifyEntries rejects the combination -- metro-resolver can't substitute).
+    typescript,
+    typescriptPaths,
+    host,
+  })
+  return { extras, mainFields: fields, resolver }
+}
+
+// Build a JS/TS Bundle + companion Lockfile via the legacy-field resolver (`--mainFields`/
+// `--metro`). Scanned once per platform; each edge is recorded flat when the platforms that
+// have it agree, or as a `{ platform: target }` map where they diverge. Returns { bundle, lockfile }.
+async function buildResolvedJsBundle({ cwd = process.cwd(), entries, mainFields, platforms, conditions = [], metro = false, metroResolver = false, jsx = false, flow = false, typescript = false, tsconfig, resources = [], packageJSON = false, host = diskHost }) {
   const baseDir = resolve(cwd)
   const absEntries = entries.map((e) => resolve(baseDir, e))
   const normalized = normalizeEntries(entries, cwd)
 
   const toRel = (abs) => {
-    const rel = relative(baseDir, abs).split(/[\\/]/u).join('/')
-    if (rel.startsWith('..') || isAbsolute(rel)) {
+    const rel = toPosix(relative(baseDir, abs))
+    if (relativeEscapes(rel)) {
       throw new Error(`Bundle would reach a file outside the project root: ${abs}`)
     }
     return rel
   }
 
-  // Normalize conditions like buildJsBundle does, so a sloppy programmatic caller
-  // (stray '' / whitespace) can't push a bogus token into the resolver.
-  const scanConditions = conditions.map((c) => (typeof c === 'string' ? c.trim() : c)).filter(Boolean)
+  const scanConditions = cleanConditions(conditions)
+
+  // Under --jsx the resolver probes .jsx/.tsx too, matching scan's jsx-widened carryable set.
+  const sourceExts = jsx ? SOURCE_EXTS_JSX : SOURCE_EXTS
+  // --typescript's tsconfig `paths` matcher, shared by every per-platform resolver below.
+  const typescriptPaths = typescriptPathsFor(typescript, baseDir, tsconfig, host)
+  // --resources: extensions/filenames carried as opaque assets instead of failing "can't carry".
+  const resourceSet = parseResourcesOption('buildResolvedJsBundle', resources)
 
   const formatsByRel = new Map()
-  // parentRel -> specifier -> Map<platformKey, targetRel>. Collapsed into flat /
-  // platform-map edges after every platform has been scanned.
+  // Reached files the scanner tagged as resources (rel keys); read as bytes below, not UTF-8 source.
+  const resourceRels = new Set()
+  // parentRel -> specifier -> Map<platformKey, targetRel>; collapsed after all platforms scanned.
   const edges = new Map()
-  const reached = new Set() // absolute paths of every real file reached on any platform
+  const reached = new Set() // absolute paths reached on any platform
   let usesEmpty = false
 
   for (const platform of platforms) {
-    // `--metro` asserts the React Native preset's conditions (react-native, plus
-    // browser for the web platform); `--mainFields` (platform === null) carries the
-    // user's own `--conditions`. scan layers these on the format-derived base.
-    const extras = metro ? ['react-native', ...(platform === 'web' ? ['browser'] : [])] : scanConditions
-    const resolver = createFieldResolver({
-      mainFields,
-      platform,
-      preferNative: platform !== null && platform !== 'web',
-      sourceExts: SOURCE_EXTS,
-      conditions: resolveConditions('commonjs', extras),
-    })
-    const scanner = scan(absEntries, { conditions: extras, resolve: resolver })
-    reportScanIssues(analyzeScanner(scanner), { label: platform ?? 'mainFields' })
+    const field = fieldResolverFor(platform, { mainFields, metro, conditions: scanConditions, jsx, typescript, typescriptPaths, host })
+    const { extras } = field
+    // --metro --metro-resolver delegates to the project's own metro-resolver for byte-for-byte Metro
+    // fidelity; otherwise the built-in field/suffix resolver reproduces it. metro-resolver derives
+    // default/require|import/platform conditions itself, so it takes only the extra `react-native`
+    // condition (browser comes from its per-platform map, keyed on `web`).
+    const resolver = metroResolver
+      ? createMetroResolver({ projectDir: baseDir, platform, sourceExts, mainFields, conditionNames: ['react-native'], host })
+      : field.resolver
+    const scanner = scan(absEntries, { conditions: extras, resolve: resolver, jsx, flow, resources: resourceSet, host })
+    reportScanIssues(analyzeScanner(scanner, { baseDir }), { baseDir, label: platform ?? 'mainFields' })
 
     const platformKey = platform ?? '*' // '*' is a private placeholder for the single mainFields pass; it never unflattens
     for (const [url, info] of scanner.files) {
-      const rel = toRel(fileURLToPath(url))
-      reached.add(fileURLToPath(url))
+      const abs = fileURLToPath(url)
+      const rel = toRel(abs)
+      reached.add(abs)
+      if (info.resource) resourceRels.add(rel)
       formatsByRel.set(rel, info.format)
       for (const e of info.edges) {
         if (e.builtin || e.dynamic) continue
@@ -795,38 +888,124 @@ async function buildResolvedJsBundle({ cwd = process.cwd(), entries, mainFields,
     }
   }
 
-  // Read every reached file's bytes once: content for the bundle, integrity for the
-  // lockfile (hash the raw bytes so it matches `stasis run --lock=frozen`). The stored
-  // source is UTF-8 text, so the bytes must BE valid UTF-8 -- otherwise toString('utf8')
-  // would lossily diverge from the hashed bytes.
+  // Read each reached file once: bytes for the bundle, integrity for the lockfile. Source is
+  // stored as UTF-8 text, so non-UTF-8 bytes would diverge from the hashed bytes -- reject them.
   const sources = new Map()
   const integrities = new Map()
-  const realBase = realpathSync(baseDir)
+  // Carry `rel`: `content` in the bundle as `format`, the integrity of its bytes `buf` in the lockfile.
+  const put = (rel, content, format, buf) => {
+    sources.set(rel, content)
+    formatsByRel.set(rel, format)
+    integrities.set(rel, sha512integrity(buf))
+  }
+  // A resource carries bytes, not source: UTF-8 verbatim or base64 when binary, tagged with the
+  // byte-derived format (here and in the --metro native capture below).
+  const putResource = (rel, buf) => (isUtf8(buf) ? put(rel, buf.toString('utf8'), 'resource', buf) : put(rel, buf.toString('base64'), 'resource:base64', buf))
+  const realBase = host.realpath(baseDir)
   for (const abs of reached) {
     const rel = toRel(abs)
-    // A bundle must carry only in-tree, attestable bytes. The field resolver returns the
-    // lexical path it probed, so an in-tree-named symlink whose real target escapes the
-    // project root would slip past toRel's textual check -- realpath it and fail closed,
-    // the same way the State-based JS path and the non-JS loaders do.
-    assertRealPathWithinBase(realBase, baseDir, rel)
-    const buf = readFileSync(abs)
-    if (!isUtf8(buf)) throw new Error(`JS bundle source is not valid UTF-8: ${rel}`)
-    sources.set(rel, buf.toString('utf8'))
-    integrities.set(rel, sha512integrity(buf))
+    // Security: the field resolver returns the lexical path, so an in-tree-named symlink
+    // escaping the root would slip past toRel's textual check -- realpath and fail closed.
+    assertRealPathWithinBase(realBase, baseDir, rel, host)
+    const buf = host.readFile(abs)
+    if (resourceRels.has(rel)) {
+      putResource(rel, buf)
+    } else {
+      if (!isUtf8(buf)) throw new Error(`JS bundle source is not valid UTF-8: ${rel}`)
+      // Its format is the scan's.
+      put(rel, buf.toString('utf8'), formatsByRel.get(rel), buf)
+    }
   }
   if (usesEmpty) {
-    // The empty module is synthetic; refuse to shadow a real reached file that
-    // happens to sit at the reserved path rather than silently clobber it.
+    // Refuse to shadow a real reached file sitting at the reserved empty-module path.
     if (formatsByRel.has(EMPTY_MODULE_PATH)) {
       throw new Error(`Bundle needs the reserved empty-module path ${EMPTY_MODULE_PATH}, but the project has a real file there`)
     }
-    sources.set(EMPTY_MODULE_PATH, '')
-    formatsByRel.set(EMPTY_MODULE_PATH, 'commonjs')
-    integrities.set(EMPTY_MODULE_PATH, sha512integrity(Buffer.alloc(0)))
+    put(EMPTY_MODULE_PATH, '', 'commonjs', Buffer.alloc(0))
   }
 
-  // Collapse each edge: one distinct target across the platforms that have it -> flat
-  // string; otherwise a Map<platform, target> (platform keys only, sorted).
+  // --metro also carries each bundled dependency's native build-input surface (ios/android
+  // sources + podspecs), scoped to the node_modules packages actually in the bundle. Native
+  // source is stored as code under a language tag; other assets as 'resource'/'resource:base64'.
+  if (metro) {
+    const pkgDirs = new Set()
+    for (const abs of reached) {
+      // Follow the CODE/module graph only: a package reached solely for an asset (--resources) is
+      // not a linked native dependency, so it must not drag in its ios/android surface.
+      const rel = toRel(abs)
+      if (resourceRels.has(rel)) continue
+      const nm = splitNodeModulesPath(rel)
+      if (nm) pkgDirs.add(nm.dir)
+    }
+    for (const pkgDir of [...pkgDirs].toSorted()) {
+      const pkgAbs = join(baseDir, pkgDir)
+      // react-native core isn't a Pod (config reports it via reactNativePath, not `dependencies`),
+      // so walk its whole tree for native source (React/, ReactCommon/, ReactAndroid/, ...) the same
+      // way a native dep's ios/android surface is walked; every other dep gets its ios/android + podspecs.
+      const isRnCore = pkgDir.slice(pkgDir.lastIndexOf('node_modules/') + 'node_modules/'.length) === 'react-native'
+      const files = isRnCore ? [] : nativeModuleFiles(pkgAbs, host)
+      if (isRnCore) walkNative(pkgAbs, files, host, isNativeSource)
+      for (const abs of files) {
+        const rel = toRel(abs)
+        if (sources.has(rel)) continue
+        assertRealPathWithinBase(realBase, baseDir, rel, host)
+        // classifyNativeCapture (shared with the StasisMetro plugin) returns action skip/code/resource with a format tag.
+        const byName = classifyNativeCapture(rel)
+        if (byName.action === 'skip') continue
+        const buf = host.readFile(abs)
+        // Byte-level rules (prebuilt binaries, binary plists) -- see refineNativeCapture.
+        const { action, format } = refineNativeCapture(byName, rel, buf, resourceSet)
+        if (action === 'skip') continue
+        if (action === 'code') {
+          if (!isUtf8(buf)) throw new Error(`native source is not valid UTF-8: ${rel}`)
+          put(rel, buf.toString('utf8'), format, buf)
+        } else {
+          putResource(rel, buf)
+        }
+      }
+      // RN core's `.js` build scripts the classify loop skips (Metro-owned by extension, but never in
+      // the graph): force-include as code so the podspec/Ruby that invokes them at pod-install resolves.
+      if (isRnCore) {
+        for (const file of RN_CORE_INCLUDE_FILES) {
+          const abs = join(pkgAbs, file)
+          if (host.stat(abs) === null) continue
+          const rel = toRel(abs)
+          if (sources.has(rel)) continue
+          assertRealPathWithinBase(realBase, baseDir, rel, host)
+          const buf = host.readFile(abs)
+          if (!isUtf8(buf)) throw new Error(`native source is not valid UTF-8: ${rel}`)
+          put(rel, buf.toString('utf8'), packageType(abs, host) === 'module' ? 'module' : 'commonjs', buf)
+        }
+      }
+    }
+  }
+
+  // --package-json: fold each bundled module's package.json into `sources` (and its integrity into
+  // the companion lockfile) even when the scan never reached it. Buckets are the ones
+  // assembleCodeBundle derives, from the same `packageOf` (findPackageMetadata -> pkgDir, else the
+  // '.' workspace bucket; packageLookup memoizes it per directory so a package's many files don't
+  // each re-walk to the same manifest). readModuleManifest applies the read/validate rules shared
+  // with the State path (containment, UTF-8-aborts); no identity check here -- these buckets are
+  // all fresh from disk.
+  const packageOf = packageLookup(baseDir, { host })
+  if (packageJSON) {
+    const pkgDirs = new Set()
+    for (const abs of reached) {
+      const rel = toRel(abs)
+      const meta = packageOf(rel)
+      if (meta) pkgDirs.add(meta.pkgDir)
+      else if (!splitNodeModulesPath(rel)) pkgDirs.add('.')
+    }
+    for (const pkgDir of pkgDirs) {
+      const rel = moduleFileKey(pkgDir, 'package.json')
+      if (sources.has(rel)) continue
+      const buf = readModuleManifest({ baseDir, realBase, rel, host })
+      if (!buf) continue
+      put(rel, buf.toString('utf8'), 'json', buf)
+    }
+  }
+
+  // Collapse each edge: one distinct target across platforms -> flat string; else a sorted Map<platform, target>.
   const resolutions = new Map()
   for (const [parent, bySpec] of edges) {
     const specMap = new Map()
@@ -841,7 +1020,7 @@ async function buildResolvedJsBundle({ cwd = process.cwd(), entries, mainFields,
     resolutions.set(parent, specMap)
   }
 
-  const rootPkg = readJson(join(baseDir, 'package.json')) ?? {}
+  const rootPkg = readJson(join(baseDir, 'package.json'), host) ?? {}
   const bundle = assembleCodeBundle({
     baseDir,
     entries: normalized,
@@ -851,11 +1030,11 @@ async function buildResolvedJsBundle({ cwd = process.cwd(), entries, mainFields,
     workspaceName: rootPkg.name ?? 'workspace',
     workspaceVersion: rootPkg.version ?? '0.0.0',
     conditionKey: '*',
+    host,
+    packageOf,
   })
 
-  // The companion lockfile mirrors the bundle exactly, swapping file content for
-  // its integrity. modules/imports/formats/entries are shared shapes, so a frozen
-  // lockfile attests the same resolution graph the bundle carries.
+  // The companion lockfile mirrors the bundle, swapping file content for its integrity.
   const lockModules = new Map()
   for (const [dir, m] of bundle.modules) {
     const files = Object.create(null)
@@ -868,20 +1047,23 @@ async function buildResolvedJsBundle({ cwd = process.cwd(), entries, mainFields,
     modules: lockModules,
     imports: bundle.imports,
     formats: bundle.formats,
+    // Same file set as the bundle, so the same executable list attests it.
+    executable: bundle.executable,
   })
 
   return { bundle, lockfile }
 }
 
-// Classify entries into the single bundle language they all share and check
-// option applicability. Shared by buildBundle and bundleCommand; `name`
-// prefixes error messages with the caller.
-function classifyEntries(name, { entries, mappingFile, scope, lockfile, conditions, mainFields, platforms, metro }) {
+// Classify entries into their single shared language and check option applicability; `name` prefixes
+// errors. A directory entry (resolved against `cwd`, on `host`) stands for the .sol files under it: Solidity only.
+function classifyEntries(name, { cwd = process.cwd(), entries, mappingFile, manifests, scope, lockfile, conditions, mainFields, platforms, metro, metroResolver, jsx, flow, typescript, tsconfig, resources, packageJSON, cargo, cargoFeatures, cargoNoDefaultFeatures, cargoAllFeatures, cargoTarget, cargoManifests, host = diskHost, fetched }) {
   if (!Array.isArray(entries) || entries.length === 0) {
     throw new Error(`${name}: at least one entry file is required`)
   }
+  const dirError = directoryEntryError(entries, cwd, host, { fetched })
+  if (dirError !== null) throw new Error(`${name}: ${dirError}`)
   let kind
-  if (entries.every((e) => e.endsWith('.sol'))) kind = 'sol'
+  if (entries.every((e) => isSolidityEntry(e, cwd, host))) kind = 'sol'
   else if (entries.every((e) => e.endsWith('.php'))) kind = 'php'
   else if (entries.every((e) => JS_EXTS.has(extname(e)))) kind = 'js'
   else if (entries.every((e) => BASH_EXTS.has(extname(e)))) kind = 'bash'
@@ -892,28 +1074,63 @@ function classifyEntries(name, { entries, mappingFile, scope, lockfile, conditio
   if (mappingFile && kind !== 'sol') {
     throw new Error(`${name}: --mapping is only valid for .sol bundles`)
   }
+  // --manifests carries the Solidity build's description files (foundry.toml, remappings.txt, ...).
+  if (manifests && kind !== 'sol') {
+    throw new Error(`${name}: --manifests is only valid for .sol bundles`)
+  }
+  // --cargo runs `cargo metadata` for the Rust feature/dependency resolution and the --cargo-*
+  // flags steer that resolution; nothing else reads Cargo.
+  if (kind !== 'rust') {
+    const given = { cargo, 'cargo-features': Array.isArray(cargoFeatures) && cargoFeatures.length > 0, 'cargo-no-default-features': cargoNoDefaultFeatures, 'cargo-all-features': cargoAllFeatures, 'cargo-target': cargoTarget, 'cargo-manifests': cargoManifests }
+    for (const [flag, on] of Object.entries(given)) if (on) throw new Error(`${name}: --${flag} is only valid for Rust bundles`)
+  }
   if (scope !== undefined && kind !== 'js') {
     throw new Error(`${name}: --scope is only valid for JS bundles`)
   }
   if (lockfile !== undefined && kind !== 'js') {
     throw new Error(`${name}: --lockfile is only valid for JS bundles`)
   }
-  // Conditions only steer Node's `exports`/`imports` resolution, which the other
-  // languages' resolvers don't consult -- reject them rather than accept a flag
-  // that would silently do nothing.
+  // Reject --conditions for non-JS: their resolvers don't consult exports/imports conditions, so it would silently do nothing.
   if (Array.isArray(conditions) && conditions.length > 0 && kind !== 'js') {
     throw new Error(`${name}: --conditions is only valid for JS bundles`)
   }
+  // --flow strips Flow type syntax before the JS parser; the non-JS loaders never parse with oxc.
+  if (flow && kind !== 'js') {
+    throw new Error(`${name}: --flow is only valid for JS bundles`)
+  }
+  // --typescript maps JS-output specifiers to their on-disk TS sources; only the JS resolvers do it.
+  if (typescript && kind !== 'js') {
+    throw new Error(`${name}: --typescript is only valid for JS bundles`)
+  }
+  // --tsconfig names the config whose `paths` aliases --typescript honours; meaningless without it.
+  if (tsconfig !== undefined && !typescript) {
+    throw new Error(`${name}: --tsconfig is only valid with --typescript`)
+  }
+  // --resources carries allowlisted assets reached through the JS import graph; JS-only. The list
+  // is validated (parseResourcesOption) in the builders, but reject a code extension here too so a
+  // typo surfaces with the command name rather than deep in the scan.
+  if (Array.isArray(resources) && resources.length > 0) {
+    if (kind !== 'js') throw new Error(`${name}: --resources is only valid for JS bundles`)
+    parseResourcesOption(name, resources)
+  }
   // --mainFields and --metro/--platforms are legacy-/platform-resolution knobs; JS-only.
   if (mainFields !== undefined && kind !== 'js') {
     throw new Error(`${name}: --mainFields is only valid for JS bundles`)
   }
+  // --jsx toggles the scanner's JSX parsing for the .js family; only JS entries are scanned.
+  if (jsx && kind !== 'js') {
+    throw new Error(`${name}: --jsx is only valid for JS bundles`)
+  }
+  // --package-json folds each bundled module's npm package.json in; JS-only (the sol/php/bash/rust
+  // bucketizers group by their own ecosystems' manifests, not an npm package.json).
+  if (packageJSON && kind !== 'js') {
+    throw new Error(`${name}: --package-json is only valid for JS bundles`)
+  }
   if ((metro || (Array.isArray(platforms) && platforms.length > 0)) && kind !== 'js') {
     throw new Error(`${name}: --metro is only valid for JS bundles`)
   }
-  // `--metro` is a preset for conditions + mainFields + platform suffixes, so it can't
-  // be combined with explicit --conditions/--mainFields (they'd conflict), and it needs
-  // --platforms to know which suffixes to resolve. `--platforms` is meaningless without it.
+  // --metro presets conditions + mainFields + platform suffixes, so it can't combine with
+  // explicit --conditions/--mainFields and requires --platforms; --platforms is meaningless without it.
   if (metro) {
     if (Array.isArray(conditions) && conditions.length > 0) {
       throw new Error(`${name}: --conditions can't be combined with --metro (it sets its own conditions)`)
@@ -924,9 +1141,8 @@ function classifyEntries(name, { entries, mappingFile, scope, lockfile, conditio
     if (!Array.isArray(platforms) || platforms.length === 0) {
       throw new Error(`${name}: --metro requires --platforms (e.g. --platforms=ios,android)`)
     }
-    // A platform name becomes a bundle/lockfile edge key (Bundle/Lockfile parse reject
-    // a '/'); '*' is the reserved private placeholder. Reject both so the writer can
-    // never emit an edge map the readers refuse -- a divergent-edge, data-dependent break.
+    // A platform name becomes an edge key: reject '/' (Bundle/Lockfile parse refuse it) and
+    // the reserved '*' placeholder, so the writer never emits a map the readers reject.
     for (const p of platforms) {
       if (typeof p !== 'string' || p.length === 0 || p === '*' || p.includes('/')) {
         throw new Error(`${name}: invalid platform '${p}' (a platform name can't be empty, contain '/', or be '*')`)
@@ -935,147 +1151,167 @@ function classifyEntries(name, { entries, mappingFile, scope, lockfile, conditio
   } else if (Array.isArray(platforms) && platforms.length > 0) {
     throw new Error(`${name}: --platforms is only valid with --metro`)
   }
-  // The field resolver always emits a full-scope bundle (no node_modules-only mode), so
-  // --scope alongside --mainFields/--metro would be silently ignored -- reject it.
+  // --metro-resolver swaps in the project's real metro-resolver; it only means something under --metro.
+  if (metroResolver && !metro) {
+    throw new Error(`${name}: --metro-resolver is only valid with --metro`)
+  }
+  // metro-resolver has no TS extension substitution, so --typescript would silently not apply -- reject it.
+  if (typescript && metroResolver) {
+    throw new Error(`${name}: --typescript is not supported with --metro-resolver (the project's metro-resolver doesn't substitute .js -> .ts)`)
+  }
+  // The field resolver always emits full-scope, so --scope with --mainFields/--metro would be silently ignored -- reject it.
   if (scope !== undefined && (mainFields !== undefined || metro)) {
     throw new Error(`${name}: --scope is not supported with --mainFields or --metro`)
   }
   return kind
 }
 
-// Programmatic equivalent of `stasis bundle`: build and return an in-memory
-// Bundle from a list of entry files, without writing anything to disk
-// (serialize with bundle.serialize() to get the JSON that `stasis bundle`
-// brotli-compresses into stasis.code.br).
-//
-// Dispatch by extension matches the CLI: all entries must be one language —
-// .sol (Solidity), .php (PHP), .js/.cjs/.mjs/.ts/.cts/.mts (JS/TS, via static
-// scan), .sh/.bash (Bash), or .rs (Rust); mixing fails fast. `mappingFile` is
-// the optional Solidity remappings file (foundry.toml or remappings.txt) and
-// is only valid for .sol entries; `scope` overrides the configured bundle
-// scope and is only valid for JS/TS entries; `conditions` are extra `exports`
-// resolution conditions (e.g. `['react-native']`) and are JS/TS-only too.
-//
-// `mainFields` (an array of legacy package fields, e.g. `['react-native','browser','main']`)
-// selects the legacy-field resolver -- see buildResolvedJsBundle. It resolves
-// non-`exports` packages via those fields, including the browser-field object
-// redirection, and composes with `conditions`. `metro: true` is instead a preset that
-// sets its OWN React Native fields + conditions + platform suffixes (so it is not
-// combined with `mainFields`/`conditions`) and requires `platforms` (e.g.
-// `['ios','android']`); the edge graph is then per-platform. JS/TS-only.
-export async function buildBundle({ cwd = process.cwd(), entries, mappingFile, scope, conditions, mainFields, platforms, metro } = {}) {
-  const kind = classifyEntries('buildBundle', { entries, mappingFile, scope, conditions, mainFields, platforms, metro })
-  if (kind === 'sol') return buildSolidityBundle({ cwd, entries, mappingFile })
-  if (kind === 'php') return buildPhpBundle({ cwd, entries })
-  if (kind === 'bash') return buildBashBundle({ cwd, entries })
-  if (kind === 'rust') return buildRustBundle({ cwd, entries })
+// A JS bundle as `stasis bundle` builds it: by the legacy-field resolver with `mainFields` or
+// `metro`, whose per-platform edges and synthetic empty module a State can't hold, else through a
+// State, which detects the bundle's repo itself. -> { bundle, lockfile: () => Lockfile, stateBuilt }
+async function buildJs({ mainFields, platforms, metro, metroResolver, ...options }) {
   if (metro || mainFields !== undefined) {
-    const { bundle } = await buildResolvedJsBundle({
-      cwd,
-      entries,
-      mainFields: metro ? METRO_MAIN_FIELDS : mainFields,
-      platforms: metro ? platforms : [null],
-      conditions,
-      metro: Boolean(metro),
-    })
-    return bundle
-  }
-  const state = await buildJsBundle({ cwd, entries, scope, conditions })
-  return state.sourceBundle
+    const built = await buildResolvedJsBundle({ ...options, mainFields: metro ? METRO_MAIN_FIELDS : mainFields, platforms: metro ? platforms : [null], metro: Boolean(metro), metroResolver: Boolean(metroResolver) })
+    return { bundle: built.bundle, lockfile: () => built.lockfile, stateBuilt: false }
+  }
+  const state = await buildJsBundle(options)
+  // Stamp the `bundle` consumer (the static build carries none).
+  return { bundle: state.sourceBundle.withReason('bundle'), lockfile: () => state.lockfile, stateBuilt: true }
 }
 
-// Where `stasis bundle` writes when no --output is given: stasis.code.br, the
-// same name `stasis run --bundle=load` discovers by default, so the two commands
-// round-trip with no flags. A file (not stdout) is the common case; pass
-// --output=- to stream the raw brotli bytes to stdout.
-const DEFAULT_BUNDLE_FILE = 'stasis.code.br'
-
-// Run the bundle CLI command end-to-end. Always produces a brotli-compressed
-// stasis bundle (matching the on-disk format of `stasis.code.br`). Writes to
-// `output` when given, to stasis.code.br in `cwd` by default, or to stdout
-// when `output` is `-`. Prints a one-line `[stasis] Bundled <n> files in <p>
-// packages from <dir> to <dest>` summary to stderr so it doesn't interleave
-// with binary output written to stdout.
-//
-// Dispatch by extension: all entries must be one language — .sol (Solidity),
-// .php (PHP), .js/.cjs/.mjs/.ts/.cts/.mts (JS/TS, via static scan), .sh/.bash
-// (Bash, via source/exec graph walk), or .rs (Rust, via mod-declaration walk).
-// Mixing fails fast; --mapping is .sol only, --scope/--lockfile/--conditions are
-// JS/TS only.
-//
-// `conditions` are extra Node `exports`/`imports` resolution conditions to assert
-// during the static scan (e.g. `['react-native']` or `['browser']`). They only
-// affect `exports`/`imports` condition matching -- not legacy mainFields -- so on
-// their own they don't honour a package's legacy entry fields. See buildJsBundle.
-//
-// For JS bundles, an optional `lockfile` path writes a stasis.lock.json that
-// attests every file in the bundle. The static scan walks both branches of
-// conditional requires (e.g. debug/src/index.js' `if (browser) require('./browser')
-// else require('./node')`), so the runtime lockfile from `stasis run --lock=add`
-// won't attest the unused branch -- if the user wants `lock=frozen` against a
-// statically-built bundle, they need this companion lockfile.
-//
-// With `--conditions`, that companion lockfile attests the conditions-SELECTED
-// resolution graph. A plain `stasis run --lock=frozen` doesn't replay `--conditions`,
-// so it resolves different files on disk and fails closed (correctly -- the lockfile
-// genuinely attests a different graph). Pair such a lockfile with `--bundle=load`, or
-// replay the same `--conditions` at run time, so the attested and observed graphs agree.
-// `brotliQuality` (integer 0..11, optional; unset = brotli's default 11) tunes the
-// output compression, forwarded to brotliOptions().
-export async function bundleCommand({ cwd = process.cwd(), entries, mappingFile, output, scope, lockfile, conditions, mainFields, platforms, metro, brotliQuality } = {}) {
-  const kind = classifyEntries('bundleCommand', { entries, mappingFile, scope, lockfile, conditions, mainFields, platforms, metro })
-
-  let bundle
-  let lockData
-  if (kind === 'js' && (metro || mainFields !== undefined)) {
-    // The legacy-field resolver path builds the Bundle (and the matching Lockfile)
-    // directly -- it carries per-platform edges and a synthetic empty module (for a
-    // browser/react-native `false` redirect) that State's disk-reading addFile can't
-    // represent.
-    const built = await buildResolvedJsBundle({
-      cwd,
-      entries,
-      mainFields: metro ? METRO_MAIN_FIELDS : mainFields,
-      platforms: metro ? platforms : [null],
-      conditions,
-      metro: Boolean(metro),
-    })
-    bundle = built.bundle
-    if (lockfile) lockData = built.lockfile.serialize()
-  } else if (kind === 'js' && lockfile) {
-    // The companion lockfile attests file hashes, which only State carries —
-    // a Bundle holds sources, not digests — so this path keeps the State.
-    const state = await buildJsBundle({ cwd, entries, scope, conditions })
-    bundle = state.sourceBundle
-    lockData = state.lockData
-  } else {
-    bundle = await buildBundle({ cwd, entries, mappingFile, scope, conditions })
+// The bundle of `kind` (classifyEntries') built from buildBundle's options.
+// -> { bundle, lockfile: () => Lockfile, stateBuilt } (the last two of a JS bundle alone)
+async function buildOfKind(kind, { cwd, env, entries, mappingFile, manifests, scope, conditions, mainFields, platforms, metro, metroResolver, jsx, flow, typescript, tsconfig, resources, packageJSON, cargo, cargoFeatures, cargoNoDefaultFeatures, cargoAllFeatures, cargoTarget, cargoManifests }) {
+  if (kind === 'sol') return { bundle: await buildSolidityBundle({ cwd, env, entries, mappingFile, manifests }) }
+  if (kind === 'php') return { bundle: await buildPhpBundle({ cwd, entries }) }
+  if (kind === 'bash') return { bundle: await buildBashBundle({ cwd, entries }) }
+  if (kind === 'rust') return { bundle: await buildRustBundle({ cwd, entries, cargo, cargoFeatures, cargoNoDefaultFeatures, cargoAllFeatures, cargoTarget, cargoManifests }) }
+  return buildJs({ cwd, env, entries, scope, conditions, mainFields, platforms, metro, metroResolver, jsx, flow, typescript, tsconfig, resources, packageJSON })
+}
+
+// buildVfsBundle's checks of `options`, which hold before anything is fetched (`host` the
+// project's, or an empty tree's with `fetched: false`): no metro-resolver, which reads the disk.
+// -> the kind of bundle its entries make
+export function checkVfsOptions(name, options) {
+  const kind = classifyEntries(name, options)
+  if (options.metroResolver) throw new Error(`${name}: metroResolver is not supported`)
+  return kind
+}
+
+// A bundle from the lockfile of the project held in `vfs` alone (@exodus/stasis/vfs-bundle), `cwd` a
+// path there: buildBundle's JS options, resolved through the node_modules 'pnpm', 'yarn1' or 'npm'
+// would install, or its Solidity options, through the dependencies folder 'soldeer' would install; with
+// nothing read from disk but tarballs and zips, nor from the environment: a Solidity bundle is
+// built with foundry.toml's default profile, whatever FOUNDRY_PROFILE or remappings one sets, and no
+// EXODUS_STASIS_* setting is read. `repo`, the informational `{ github, directory | root, commit }`,
+// is the Bundle's, over what is detected in the Vfs as `stasis bundle` detects it on disk. `os`,
+// `cpu` and `libc` are loadNodeModules'. Without a `packageManager`, it is the one whose lockfile
+// installs cwd, where only one's does.
+// -> { bundle: Bundle, lockfile: Lockfile (of a JS bundle), stats, packageManager }
+export async function buildVfsBundle({ vfs, packageManager, cwd = '/', packageManagerVersion, os, cpu, libc, repo, ...options } = {}) {
+  const { checkKind, checkTarget, checkVfs, loadTree, packageManagerFor, packageManagerOf, vfsHost } = await import('../vfs-bundle/tree.js')
+  checkVfs('buildVfsBundle', vfs)
+  checkTarget('buildVfsBundle', { os, cpu, libc })
+  // Checked as the Bundle checks it, before anything is fetched.
+  if (repo !== undefined) repo = new Bundle({ repo }).repo
+  const project = vfsHost(vfs)
+  // A real path, as every file the scan reaches is.
+  cwd = project.realpath(posix.resolve('/', cwd))
+  packageManager = packageManagerFor('buildVfsBundle', project, cwd, { packageManager, packageManagerVersion, os })
+  const pm = packageManagerOf('buildVfsBundle', packageManager)
+  checkKind('buildVfsBundle', checkVfsOptions('buildVfsBundle', { ...options, cwd, host: project }), [packageManager])
+  // Checked before anything is fetched: an entry out of what the tree installs is in the project
+  // already. (A Solidity entry that is no .sol file is a directory, skipped where it is missing.)
+  for (const entry of options.entries) {
+    const abs = posix.resolve(cwd, entry)
+    if (pm.kind === 'sol' && !abs.endsWith('.sol')) continue
+    if (!posix.relative(cwd, abs).split('/').includes(pm.installs) && project.stat(abs) === null) throw new Error(`entry not found: ${abs}`)
+  }
+  const { host, stats } = await loadTree({ project, packageManager, cwd, packageManagerVersion, os, cpu, libc })
+  const args = { ...options, cwd, host, env: {} }
+  const { bundle, lockfile, stateBuilt } = pm.kind === 'sol' ? { bundle: await buildSolidityBundle(args) } : await buildJs(args)
+  if (repo !== undefined) bundle.repo = repo
+  // Rooted at cwd, where `stasis bundle` detects its repo.
+  else if (!stateBuilt) bundle.repo ??= detectRepo(cwd, host)
+  return { bundle, lockfile: lockfile?.(), stats, packageManager }
+}
+
+// Programmatic equivalent of `stasis bundle`: build and return an in-memory Bundle without
+// writing to disk. Files are attributed to the `bundle` consumer. Option applicability
+// (--mapping|--manifests/.sol, --scope|--conditions|--mainFields|--metro|--jsx|--flow|--typescript/JS) is enforced by classifyEntries.
+export async function buildBundle({ cwd = process.cwd(), env = process.env, entries, mappingFile, manifests = false, scope, conditions, mainFields, platforms, metro, metroResolver, jsx = false, flow = false, typescript = false, tsconfig, resources = [], packageJSON = false, cargo = false, cargoFeatures = [], cargoNoDefaultFeatures = false, cargoAllFeatures = false, cargoTarget = null, cargoManifests = false } = {}) {
+  const options = { cwd, env, entries, mappingFile, manifests, scope, conditions, mainFields, platforms, metro, metroResolver, jsx, flow, typescript, tsconfig, resources, packageJSON, cargo, cargoFeatures, cargoNoDefaultFeatures, cargoAllFeatures, cargoTarget, cargoManifests }
+  return (await buildOfKind(classifyEntries('buildBundle', options), options)).bundle
+}
+
+// Run `stasis bundle`: build a brotli-compressed bundle and write it to `output`
+// (stasis.code.br by default, `-` for stdout; the summary goes to stderr so it never
+// interleaves with binary stdout). An optional JS `lockfile` attests every bundled file;
+// with `--conditions` it attests the conditions-selected graph, so a plain
+// `stasis run --lock=frozen` (which doesn't replay them) fails closed -- pair it with
+// `--bundle=load` or replay the conditions. `add` unions the fresh build into the bundle
+// already on disk (strict; a conflicting file throws) and can't target stdout.
+export async function bundleCommand({ cwd = process.cwd(), env = process.env, entries, mappingFile, manifests = false, output, scope, lockfile, conditions, mainFields, platforms, metro, metroResolver, jsx = false, flow = false, typescript = false, tsconfig, resources = [], packageJSON = false, cargo = false, cargoFeatures = [], cargoNoDefaultFeatures = false, cargoAllFeatures = false, cargoTarget = null, cargoManifests = false, brotliQuality, add = false } = {}) {
+  const options = { cwd, env, entries, mappingFile, manifests, scope, conditions, mainFields, platforms, metro, metroResolver, jsx, flow, typescript, tsconfig, resources, packageJSON, cargo, cargoFeatures, cargoNoDefaultFeatures, cargoAllFeatures, cargoTarget, cargoManifests }
+  const kind = classifyEntries('bundleCommand', { ...options, lockfile })
+
+  const target = output ?? DEFAULT_BUNDLE_FILE
+  // --add has nothing to merge into on stdout (write-only).
+  if (add && target === '-') {
+    throw new Error('bundleCommand: --add cannot be combined with --output=- (nothing to merge into on stdout)')
   }
+
+  const built = await buildOfKind(kind, options)
+  let { bundle } = built
+  // Only a JS bundle has a lockfile (classifyEntries refuses one for the others).
+  let lockData = lockfile ? built.lockfile().serialize() : undefined
+
+  // State-built bundles keep the State root's repo (no cwd fallback: their paths are relative to that root).
+  if (!built.stateBuilt) bundle.repo ??= detectRepo(cwd)
+
+  // --add: union the fresh build into the existing on-disk bundle; a conflicting file throws. Skipped when nothing is on disk.
+  const outAbs = target === '-' ? undefined : resolve(cwd, target)
+  const lockAbs = lockData ? resolve(cwd, lockfile) : undefined
+  // Files the pre-existing bundle carried; undefined when no merge happened (the summary's merged sentinel).
+  let mergedFrom
+  if (add && existsSync(outAbs)) {
+    let existing
+    try {
+      existing = Bundle.parse(brotliDecompressSync(readFileSync(outAbs)).toString('utf8'))
+    } catch (cause) {
+      throw new Error(`bundleCommand: --add failed to read the existing bundle at ${target}`, { cause })
+    }
+    mergedFrom = existing.sources.size
+    bundle = existing.merge(bundle)
+    // Keep the companion lockfile consistent with the merged bundle: union an existing one.
+    // With none on disk we can't attest the pre-existing bundle's files (their hashes live
+    // only in that missing lockfile), so refuse rather than write an under-attesting lockfile.
+    if (lockData) {
+      if (!existsSync(lockAbs)) {
+        throw new Error(`bundleCommand: --add can't write a complete lockfile at ${lockfile}: the bundle at ${target} already carries files a fresh lockfile wouldn't attest, and there's no existing lockfile to merge into. Write --lockfile alongside the bundle from the first build, or drop --lockfile.`)
+      }
+      let existingLock
+      try {
+        existingLock = Lockfile.parse(readFileSync(lockAbs, 'utf8'))
+      } catch (cause) {
+        throw new Error(`bundleCommand: --add failed to read the existing lockfile at ${lockfile}`, { cause })
+      }
+      lockData = existingLock.merge(Lockfile.parse(lockData)).serialize()
+    }
+  }
+
   const serialized = bundle.serialize()
   const files = [...bundle.sources.keys()]
   const modules = bundle.modules
 
-  const data = brotliCompressSync(serialized, brotliOptions(brotliQuality))
-  // Default to writing stasis.code.br in cwd; `-` is the conventional opt-in
-  // for streaming the raw brotli bytes to stdout (e.g. to pipe somewhere else).
-  const target = output ?? DEFAULT_BUNDLE_FILE
-  if (target === '-') {
-    process.stdout.write(data)
+  const dest = writeBundle(cwd, target, serialized, brotliQuality)
+  if (lockData) writeFile(lockAbs, lockData)
+  const fromDir = outermostDir(files, resolve(cwd))
+  // On a merge, report newly-added files alongside the totals; a fresh write keeps the plain line.
+  if (mergedFrom !== undefined) {
+    const added = files.length - mergedFrom
+    console.warn(`[stasis] Added ${added} file${added === 1 ? '' : 's'} (${files.length} total in ${packagesLabel(modules)}) from ${fromDir} to ${dest}`)
   } else {
-    const outAbs = resolve(cwd, target)
-    mkdirSync(dirname(outAbs), { recursive: true })
-    writeFileSync(outAbs, data)
-  }
-  if (lockData) {
-    const lockAbs = resolve(cwd, lockfile)
-    mkdirSync(dirname(lockAbs), { recursive: true })
-    writeFileSync(lockAbs, lockData)
+    console.warn(bundledSummary(files.length, modules, fromDir, dest))
   }
-  const fromDir = outermostDir(files, resolve(cwd))
-  const dest = target === '-' ? '<stdout>' : target
-  // Count packages: every non-empty bucket, with the project's own source (the
-  // "." workspace bucket) counting as one package alongside each dependency.
-  const packages = [...modules.values()].filter((m) => Object.keys(m.files).length > 0).length
-  const pkgLabel = `${packages} package${packages === 1 ? '' : 's'}`
-  console.warn(`[stasis] Bundled ${files.length} files in ${pkgLabel} from ${fromDir} to ${dest}`)
 }