@exodus/stasis-plugins 1.0.0-beta.2 → 1.0.0-beta.3

package/package.json

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

package/src/esbuild.js

@@ -7,11 +7,8 @@ import assert from 'node:assert/strict'
 import { Bundle } from '@exodus/stasis-core/bundle'
 import { resolvePluginState } from './plugins.js'
 import { State } from '@exodus/stasis-core/state'
-// Pre-patch snapshot, NOT `import { readFile } from 'node:fs/promises'`: under
-// `stasis run --fs=async` that builtin is monkey-patched, and this plugin loads after
-// the patch, so a direct import would route esbuild's own source reads through the
-// --fs capture hook. The snapshot in state-util (taken during the --import preload) is
-// the genuine reader.
+// Pre-patch snapshot, not `import { readFile }`: under --fs=async that builtin is patched, and
+// this plugin loads after, so a direct import would route esbuild's reads through the capture hook.
 import { realReadFile } from '@exodus/stasis-core/state-util'
 import { classifyExtension } from '@exodus/stasis-core/util'
 
@@ -20,31 +17,32 @@ export class StasisEsbuild {
   #state
   #resources
   #loaders
+  #transform
 
-  // Build starts observed by this (capture-mode) instance, across rebuilds AND across separate
-  // esbuild.build()/context() calls sharing one instance. The second start is refused -- see
-  // the onStart hook in setup().
+  // Build starts observed by this instance (across rebuilds and separate build()/context() calls);
+  // the second is refused in onStart.
   #captureBuildCount = 0
 
-  constructor(options = {}, { loaders } = {}) {
-    // A caller that owns a State (e.g. `stasis build`) can pass it directly to drive the plugin, bypassing resolvePluginState; mode follows that State's config, and a foreign-copy State fails closed via the instanceof miss.
+  constructor(options = {}, { loaders, transform } = {}) {
+    // A caller that owns a State (e.g. `stasis build`) can pass it directly; a foreign-copy State
+    // fails closed via the instanceof miss.
     const state = options instanceof State
       ? options
       : resolvePluginState('StasisEsbuild', options, process.cwd()).state
     this.#state = state  // null when plugin should be inert
-    // resources is a Config field now (validated + coordinated against any preload in
-    // resolvePluginState); cache the resolved Set for the per-file classify hot path.
+    // Cache the resolved resources Set for the per-file classify hot path.
     this.#resources = state?.config.resources ?? new Set()
-    // Per-extension esbuild loader overrides (e.g. { '.js' -> 'jsx' } so a .js file
-    // carrying JSX -- the React Native convention -- parses; esbuild's default 'js'
-    // loader rejects JSX). Keyed by extname WITH the dot; falls back to the
-    // extension-derived loader (see #loaderFor) when an extension isn't overridden.
+    // Per-extension esbuild loader overrides (e.g. { '.js' -> 'jsx' } for RN's JSX-in-.js),
+    // keyed by extname with the dot; falls back to #loaderFor.
     this.#loaders = loaders ?? new Map()
+    // Load-mode-only code rewrite hook (e.g. `stasis build --platform=hermes` downleveling):
+    // (source, { path, loader }) => { contents, loader } | undefined, may be async. Never
+    // runs at capture -- capture attests the file's raw bytes.
+    this.#transform = transform
   }
 
-  // The esbuild loader for a served file: an explicit per-extension override if the
-  // caller configured one, else derived from the extension (.cjs/.mjs/.cts/.mts strip
-  // their leading module letter to js/ts; other code extensions map 1:1 to a loader).
+  // esbuild loader for a served file: configured override, else derived from extension
+  // (.cjs/.mjs/.cts/.mts strip their module letter to js/ts).
   #loaderFor(path) {
     const ext = extname(path)
     return this.#loaders.get(ext) ?? ext.replace(/^\.[cm]?/u, '')
@@ -54,21 +52,12 @@ export class StasisEsbuild {
     return 'stasis'
   }
 
-  setup = ({ onResolve, onLoad, onStart, onEnd, resolve }) => {
+  setup = ({ onResolve, onLoad, onStart, onEnd, resolve, initialOptions }) => {
     if (!this.#state) return  // noop plugin
 
-    // Watch/rebuild capture is EXPLICITLY UNSUPPORTED -- fail the second build loudly before it
-    // captures anything. Capture's dedupe is keyed by PATH, not content (#seen below, plus
-    // State.write's compare-and-skip caches), so on a rebuild where a file's bytes changed the
-    // plugin would skip re-capture: the emitted output would use the new bytes while the
-    // bundle/lockfile silently kept attesting the OLD ones. Rather than track content changes
-    // across rebuilds, refuse them outright. esbuild rebuilds (watch mode, context.rebuild())
-    // re-fire onStart/onEnd against the SAME setup registrations, so an instance-level counter
-    // sees every start; it also covers reusing one plugin instance across two esbuild.build()
-    // calls, which has the same staleness hazard. Returning errors from onStart is the
-    // esbuild-idiomatic hard failure (the build reports them and onEnd's clean-build gate then
-    // skips the write). Load mode registers nothing here: it serves immutable attested bytes,
-    // so rebuilds have no drift hazard.
+    // Watch/rebuild capture is unsupported: dedupe is keyed by PATH not content, so a rebuild with
+    // changed bytes would emit new bytes while the bundle/lockfile keep the OLD ones. Rebuilds re-fire
+    // onStart against the same registrations, so an instance counter catches the second and errors.
     if (!this.#state.config.loadBundle) {
       onStart(() => {
         this.#captureBuildCount += 1
@@ -81,10 +70,8 @@ export class StasisEsbuild {
       })
     }
 
-    // The stasis preload owns its own write via beforeExit/exit hooks (stasis-core/hooks.js).
-    // Standalone and sidecar States have no such hook, so the plugin writes them when the
-    // build finishes -- but only on a clean build, otherwise a partial bundle/lockfile
-    // would overwrite the user's good file.
+    // The preload writes itself (hooks.js); standalone/sidecar States are written on build finish --
+    // only on a clean build (a partial one would overwrite the user's good file).
     if (this.#state !== State.preload) {
       onEnd((result) => {
         if (result.errors.length > 0) return
@@ -92,61 +79,33 @@ export class StasisEsbuild {
       })
     }
 
-    // Load mode: resolution comes from the bundle's import map, not esbuild's
-    // resolver. The on-disk file may not even exist -- the bundle is the source
-    // of truth (mirrors `stasis run --bundle=load`; see stasis-core/src/hooks.js).
-    // We keep `namespace: 'file'` with the original absolute path, even though the
-    // file isn't on disk: esbuild stats the path only when its own default resolver
-    // produced it; paths returned from a plugin's onResolve are trusted as-is. That
-    // gives the same output bytes as a capture-mode build -- esbuild's path-banner
-    // comments, asset names, and source maps all use the original paths.
+    // Load mode: resolution comes from the bundle's import map, not esbuild's resolver -- the file
+    // may not be on disk. Keep namespace:'file' with the original absolute path (esbuild doesn't stat
+    // plugin-returned paths) so output bytes -- banners, asset names, source maps -- match a capture build.
     onResolve({ filter: /$/ }, ({ path: specifier, importer, kind: resolveKind, with: attrs }) => {
       if (!this.#state.config.loadBundle) return undefined
-      // Node built-ins (`constants`, `node:fs`, ...) are never carried in the bundle
-      // and never recorded as import edges -- the capture side (and the Node run
-      // loader, stasis-core/hooks.js) defer isBuiltin() specifiers before addImport
-      // sees them. Returning undefined hands the builtin back to esbuild's own
-      // resolution, which externalizes it under platform:'node' exactly as in a build
-      // without this plugin; state.getImport would instead throw ERR_MODULE_NOT_FOUND
-      // ("Cannot find module 'constants' imported from <file>"). Mirrors the webpack
-      // plugin's load-mode builtin guard.
+      // Built-ins are never bundled or recorded as edges; hand them back to esbuild (undefined)
+      // so it externalizes under platform:'node', rather than getImport throwing ERR_MODULE_NOT_FOUND.
       if (isBuiltin(specifier)) return undefined
       const isEntry = resolveKind === 'entry-point'
       let url
       if (isEntry) {
-        // esbuild's entryPoints are typically absolute, but a bare/relative entry
-        // is anchored to cwd just like the run loader does (resolvePath(cwd, ...))
-        // so the entry file doesn't need to be on disk.
+        // Bare/relative entries are anchored to cwd (like the run loader), so the file needn't be on disk.
         url = specifier.startsWith('file:')
           ? specifier
           : pathToFileURL(resolvePath(process.cwd(), specifier)).toString()
         if (this.#state.config.full) this.#state.assertEntry(url)
       } else {
         const parentURL = pathToFileURL(importer).toString()
-        // Forward import attributes (e.g. `with { type: 'json' }`) so a
-        // plugin-captured bundle round-trips to plugin-load symmetrically: both
-        // sides key the edge under `* (with: ...)` (no conditions because the
-        // plugin doesn't know them). KNOWN GAP: a bundle captured by the Node
-        // run loader keys edges under specific conditions like `node, import,
-        // ... (with: ...)`; the plugin's `*`-keyed lookup misses that, and the
-        // wildcard fallback in state.getImport only falls back to `*` (without
-        // attrs), so a Node-loader-captured bundle with attributed imports
-        // won't reload via the esbuild plugin without further work
-        // (state.getImport would need a multi-conditions match scan, or the
-        // Node loader would need to mirror under '*' too).
+        // Forward import attributes (`with { type: 'json' }`) so plugin-capture round-trips to
+        // plugin-load, both keyed under `* (with: ...)`. KNOWN GAP: a Node-loader-captured bundle
+        // keys attributed edges under specific conditions the plugin's `*` lookup won't match.
         try {
           ;({ url } = this.#state.getImport(parentURL, specifier, { importAttributes: attrs }))
         } catch (err) {
-          // No attested edge. getImport tried the recorded edge under every conditions
-          // bucket (resolveBundled), so a miss means the request names nothing the
-          // bundle carries -- at a successful capture it was an EXTERNAL (a user
-          // `external` entry; built-ins are handled above). Externals are never recorded
-          // as edges, so return undefined to hand it back to esbuild, which externalizes it as it would
-          // without this plugin. This relaxes only the resolve-time edge lookup:
-          // a genuinely missing in-scope FILE still fails closed at onLoad
-          // (state.getFile serves in-scope bytes from the bundle or throws), so no
-          // disk fallback is introduced. A non-MODULE_NOT_FOUND error is a real
-          // fault -- rethrow it.
+          // No attested edge -- at a successful capture that's an EXTERNAL (never recorded as an
+          // edge), so hand it back to esbuild. File BYTES still fail closed at onLoad.
+          // A non-MODULE_NOT_FOUND error is a real fault -- rethrow.
           if (err?.code === 'ERR_MODULE_NOT_FOUND') return undefined
           throw err
         }
@@ -162,12 +121,8 @@ export class StasisEsbuild {
       // Recurse with a synthetic namespace so esbuild's default resolver runs without re-entering us
       const res = await resolve(specifier, { ...args, with: attrs, namespace: 'stasis' })
       if (res.errors.length > 0) return res
-      // Warnings from sibling plugins or esbuild itself (deprecation notices, etc.) are
-      // not our concern -- propagate them upward, don't crash.
-      // A non-empty `suffix` is set by sibling plugins that want to preserve a
-      // query-style suffix on the resolved path (some CSS-modules plugins do).
-      // stasis doesn't know how to persist suffixes to the bundle, so we refuse
-      // them explicitly rather than silently dropping the suffix at capture time.
+      // A non-empty `suffix` (some CSS-modules plugins set one) can't be persisted to the bundle,
+      // so refuse it rather than silently dropping it at capture.
       assert.equal(res.suffix, '',
         `StasisEsbuild: a sibling plugin set res.suffix='${res.suffix}' on '${specifier}'; ` +
         `stasis can't persist suffixes to the bundle. Disable that plugin or drop suffix from its resolve result.`)
@@ -182,13 +137,14 @@ export class StasisEsbuild {
             }],
           }
         }
-        if (kind === 'code' && !isEntry) {
+        // Record the edge for BOTH code and resource targets (never entries): load mode resolves
+        // every specifier through this map, so a resource with no edge would miss at bundle=load and
+        // fall through to esbuild's disk resolver -- serving the asset UNATTESTED. kind is code|resource here.
+        if (!isEntry) {
           const parentURL = pathToFileURL(args.importer).toString()
           const url = pathToFileURL(res.path).toString()
-          // Forward import attributes (e.g. `with { type: 'json' }`) symmetrically
-          // with the load path: addImport stores under a conditions-with-attributes
-          // key when attributes are present, so getImport at load time can find
-          // the same edge.
+          // Forward import attributes symmetrically with load: addImport keys by attributes so
+          // getImport finds the same edge.
           this.#state.addImport(parentURL, specifier, url, { importAttributes: attrs })
         }
       }
@@ -199,52 +155,46 @@ export class StasisEsbuild {
     onLoad({ filter: /$/, namespace: 'file' }, async ({ path, pluginData, with: attrs }) => {
       const kind = pluginData?.kind ?? 'skip'
       if (kind === 'skip') return undefined
-      // Accept the `type` import attribute (e.g. `with { type: 'json' }`); reject
-      // anything else loudly since saving import-attribute state to the lockfile
-      // isn't designed yet.
+      // Accept only the `type` import attribute; other attributes aren't persistable to the lockfile yet.
       for (const k of Object.keys(attrs)) {
         assert.equal(k, 'type', `unsupported import attribute: ${k}`)
       }
 
-      // Load mode: serve bytes the bundle attested. `getFile` verifies the hash
-      // against the lockfile (when one is loaded), and throws on a file the
-      // bundle doesn't carry -- a missing in-scope file is a hard error, not a
-      // silent disk fallback. Resources return `{ contents }` only; esbuild's
-      // loader config (file/dataurl/copy/...) interprets and emits them by
-      // extension, the same way capture mode lets esbuild's loader machinery
-      // handle resource emission.
+      // Load mode: serve bytes the bundle attested. getFile verifies the hash and throws on a file
+      // the bundle doesn't carry -- a missing in-scope file is a hard error, not a disk fallback.
       if (this.#state.config.loadBundle) {
         const { source } = this.#state.getFile(pathToFileURL(path).toString())
-        if (kind === 'resource') return { contents: source }
-        return { contents: source, loader: this.#loaderFor(path) }
+        if (kind === 'resource') {
+          // Plugin-provided contents with no `loader` default to `js` (esbuild applies the build's
+          // per-extension loader only on its own load path), so replay the configured loader from
+          // initialOptions.loader. No configured loader fails symmetrically with a capture build.
+          const loader = initialOptions.loader?.[extname(path)]
+          return loader ? { contents: source, loader } : { contents: source }
+        }
+        const loader = this.#loaderFor(path)
+        // A transform that declines (undefined) serves the attested bytes unchanged.
+        const transformed = await this.#transform?.(source, { path, loader })
+        return transformed ?? { contents: source, loader }
       }
 
       const source = await realReadFile(path)
 
       if (kind === 'resource') {
-        // Mark this file as a resource. State picks the encoding from its bytes:
-        // 'resource' (raw UTF-8 -- e.g. SVG stays human-readable in the bundle)
-        // for valid UTF-8 content, 'resource:base64' for binary. We do NOT return
-        // contents/loader: emission is esbuild's job via the build's own `loader`
-        // config (file, dataurl, copy, ...), the same way webpack's file-loader
-        // runs independently of stasis's afterResolve hook. An asset with no
-        // configured loader errors in esbuild, which
-        // is the user's responsibility (symmetric with file-loader being required).
+        // Mark as a resource (State picks 'resource' vs 'resource:base64' from bytes). Return no
+        // contents/loader: emission is esbuild's job via the build's own `loader` config.
         if (!this.#seen.has(path)) {
           this.#seen.add(path)
-          this.#state.addFile(pathToFileURL(path).toString(), { source, isEntry: pluginData?.isEntry, resource: true, reason: 'StasisEsbuild' })
+          this.#state.addFile(pathToFileURL(path).toString(), { source, isEntry: pluginData?.isEntry, resource: true, reason: 'esbuild' })
         }
         return undefined
       }
 
-      // Code-classified files must be UTF-8. A code extension with non-UTF-8 bytes
-      // is malformed input (e.g. a .json mis-saved as UTF-16); refuse it rather
-      // than silently encoding it as a resource and hiding the underlying problem.
+      // Code-classified files must be UTF-8; refuse non-UTF-8 rather than silently encode as a resource.
       assert.ok(isUtf8(source), `StasisEsbuild: code-classified file has non-UTF-8 bytes: ${path}`)
 
       if (!this.#seen.has(path)) {
         this.#seen.add(path)
-        this.#state.addFile(pathToFileURL(path).toString(), { source, isEntry: pluginData?.isEntry, reason: 'StasisEsbuild' })
+        this.#state.addFile(pathToFileURL(path).toString(), { source, isEntry: pluginData?.isEntry, reason: 'esbuild' })
       }
 
       return { contents: source, loader: this.#loaderFor(path) }

package/src/metro-transformer.js

@@ -5,56 +5,19 @@ import { pathToFileURL } from 'node:url'
 
 import { State } from '@exodus/stasis-core/state'
 
-// Companion to the StasisMetro serializer plugin: the LOAD half of stasis for Metro.
-//
-// WHY A TRANSFORMER (the asymmetry that makes this possible):
-//   Capture must MERGE every worker's observations into one lockfile/bundle, so it
-//   runs in the main process (the serializer -- see metro.js). Load is the opposite:
-//   it only ever READS an immutable bundle, and every worker reads the SAME bytes, so
-//   there is nothing to synchronize between them. That makes the per-worker transformer
-//   the natural seam for load -- each worker independently serves attested bytes, no IPC.
-//
-// HOW IT WIRES IN (metro.config.js) -- wire it PERMANENTLY, alongside the serializer half:
-//   module.exports = {
-//     transformerPath: require.resolve('@exodus/stasis/metro-transformer'),  // top-level, a sibling of `transformer`
-//   }
-//   // run with EXODUS_STASIS_BUNDLE=load (+ EXODUS_STASIS_BUNDLE_FILE / LOCK / SCOPE),
-//   // OR a stasis.config.json with "bundle":"load". Outside load mode this transformer is
-//   // a transparent pass-through (see getLoadState), and under load the StasisMetro
-//   // serializer is one too -- one committed metro.config.js carries both halves, the
-//   // mode picks the active one (the config is itself attested at capture, so a load
-//   // run must execute it unedited).
-//
-//   Metro calls `transformerPath`'s `transform(config, projectRoot, filename, data,
-//   options)` in each worker with `data` = the file's on-disk bytes (a Buffer) and
-//   `filename` project-relative. We wrap the user's real transformer (default
-//   `metro-transform-worker`, override via EXODUS_STASIS_METRO_BASE_TRANSFORMER) and,
-//   in load mode, replace `data` with the bundle's attested bytes before delegating --
-//   so the transform consumes bundle bytes, hash-verified, fail-closed.
-//
-// WHAT THIS DOES AND DOESN'T GUARANTEE:
-//   - The bytes that get TRANSFORMED are the bundle's, verified by State.getFile
-//     (against the lockfile when one is loaded; against the bundle's own bytes under
-//     lock=none). A tampered on-disk source is therefore ignored for the build output
-//     and, under a lockfile, rejected outright. An in-scope file the bundle doesn't
-//     carry throws -- never a silent disk fallback. Out-of-scope files pass their disk
-//     bytes through untouched (mirrors webpack/esbuild load scope handling).
-//   - KNOWN LIMITATION: this does NOT let Metro build with the sources fully absent
-//     from disk. Metro reads each file from disk in the worker (and hashes it in the
-//     main process for its transform cache) BEFORE this transformer runs, and resolves
-//     package.json via its own fs in the main process. Serving those reads from the
-//     bundle would need fs interception across the main + worker processes (stasis
-//     --mock territory), which is larger than this seam. So today's guarantee is
-//     "build the bundle's attested bytes, fail closed on disk drift," not "build from
-//     a bundle with no source tree." This mirrors the documented node_modules-crossing
-//     gap in the webpack load path.
+// Companion to the StasisMetro serializer: the LOAD half of stasis for Metro. Load only READS an
+// immutable bundle and every worker reads the same bytes (no IPC), so a per-worker transformer is
+// the natural seam. Wire it permanently in metro.config.js (transformerPath); outside load mode it
+// is a transparent pass-through, and under load the serializer is too -- the mode picks the active
+// half. In load mode, wrap the user's real transformer and replace Metro's on-disk `data` with the
+// bundle's hash-verified bytes (fail-closed; out-of-scope files pass their disk bytes through).
+// KNOWN LIMITATION: does NOT build with sources absent from disk -- Metro reads + hashes each file
+// before this runs, so the guarantee is "build attested bytes, fail closed on disk drift."
 
 const require = createRequire(import.meta.url)
 
-// The real transformer we wrap. Default matches Metro's default; an app with a custom
-// transformer (e.g. a TS/Babel preset) points this at theirs so we sit transparently
-// in front of it. Resolved + required lazily (per worker process) so a non-load build
-// pays nothing and we don't require Metro internals at import time.
+// The real transformer we wrap (default matches Metro's; override for a custom TS/Babel preset).
+// Required lazily per worker so a non-load build pays nothing.
 const BASE_TRANSFORMER = process.env.EXODUS_STASIS_METRO_BASE_TRANSFORMER || 'metro-transform-worker'
 
 let base
@@ -63,25 +26,30 @@ function getBase() {
   return base
 }
 
-// Per-worker load State, built once. We construct a normal State (it reads the same
-// EXODUS_STASIS_* env + stasis.config.json the rest of stasis does) and only act when
-// it resolves to load mode; any other mode -> null -> this transformer is a transparent
-// pass-through, so wiring it permanently in metro.config.js is safe.
+// Per-worker load State, built once from the usual env + stasis.config.json. Non-load mode -> null
+// -> transparent pass-through, so wiring it permanently is safe. A construction failure is cached
+// and rethrown on every call -- never throw-once-then-silently-pass-through.
 let stateInited = false
 let loadState = null
+let stateError = null
 function getLoadState() {
   if (!stateInited) {
-    stateInited = true
-    const state = new State(process.cwd())
-    loadState = state.config.loadBundle ? state : null
+    try {
+      const state = new State(process.cwd())
+      loadState = state.config.loadBundle ? state : null
+    } catch (err) {
+      stateError = err
+      throw err
+    } finally {
+      stateInited = true
+    }
   }
+  if (stateError) throw stateError
   return loadState
 }
 
-// True iff `absolute` is a path the bundle is supposed to cover under load mode.
-// `state.relative` throws for paths outside the project root, which we treat as
-// out-of-scope (system files, scratch dirs) and defer to disk. Mirrors the webpack
-// plugin's load-mode inScope.
+// True iff `absolute` is in scope for load mode. state.relative throws outside the project root
+// (out-of-scope: system files, scratch) -> defer to disk. Mirrors the webpack plugin's inScope.
 function inScope(state, absolute) {
   try {
     state.relative(absolute)
@@ -95,14 +63,11 @@ function inScope(state, absolute) {
 export function transform(config, projectRoot, filename, data, options) {
   const state = getLoadState()
   if (state) {
-    // `filename` is project-relative in Metro's transformer contract; resolve against
-    // projectRoot (resolvePath ignores projectRoot when filename is already absolute).
+    // `filename` is project-relative in Metro's contract; resolve against projectRoot.
     const absolute = resolvePath(projectRoot, filename)
     if (inScope(state, absolute)) {
-      // getFile re-verifies the hash against the lockfile on every read and throws on a
-      // file the bundle doesn't carry -- so an in-scope path the bundle is missing
-      // surfaces here as a hard build error, not a silent disk fallback. Code sources
-      // come back as strings; resources as Buffers (already decoded from base64).
+      // getFile re-verifies the hash and throws on a file the bundle doesn't carry (fail-closed,
+      // no disk fallback). Code sources come back as strings; resources as Buffers.
       const { source } = state.getFile(pathToFileURL(absolute).toString())
       data = Buffer.isBuffer(source) ? source : Buffer.from(source)
     }
@@ -111,14 +76,9 @@ export function transform(config, projectRoot, filename, data, options) {
 }
 
 export function getCacheKey(config) {
-  // Fold the wrapped transformer's own cache key in (so changing the base transformer
-  // still invalidates), then add a stasis-load discriminator: load-mode transforms can
-  // produce different bytes than a disk build for the same file (and Metro hashes the
-  // on-disk bytes into its cache key BEFORE we substitute, so when disk == bundle the
-  // content hash alone wouldn't tell a load result apart from a plain build), so their
-  // cached results must not cross-pollinate. Derive the marker from the resolved load
-  // State -- the SAME source of truth as transform() -- not the env var, so load activated
-  // via stasis.config.json is keyed correctly too; the bundle path keys it to the bundle.
+  // Fold in the base transformer's cache key, then add a stasis-load discriminator so load results
+  // (which can differ from a disk build even when disk == bundle) don't cross-pollinate the cache.
+  // Derive the marker from the resolved load State (not the env) so config.json activation keys too.
   const baseKey = typeof getBase().getCacheKey === 'function' ? getBase().getCacheKey(config) : ''
   const state = getLoadState()
   const marker = state ? `load:${state.config.bundleFile || 'default'}` : 'off'