@ttsc/metro 0.18.4 → 0.19.0

package/README.md

@@ -41,6 +41,8 @@ module.exports = withTtsc(getDefaultConfig(__dirname));
 
 `withTtsc` sets `transformer.babelTransformerPath` and leaves the rest of your config untouched. It auto-detects the upstream transformer to delegate to (`@expo/metro-config/babel-transformer` for Expo, then `@react-native/metro-babel-transformer`, then the legacy `metro-react-native-babel-transformer`).
 
+Auto-detection only skips a candidate whose entry point is genuinely **not available** — the package is not installed, or it is installed but the requested subpath is not exported (Expo/React Native version skew). A candidate that _does_ resolve but fails while loading — a top-level throw, an incompatible runtime ABI, or a missing peer/transitive dependency — surfaces its original error (as the `cause` of a `@ttsc/metro` wrapper) instead of being treated as absent. This stops a broken Expo/React Native install from silently falling through to the wrong transformer, and stops an explicit `upstreamTransformer` failure from being reported as if the module did not exist.
+
 ## Configuration
 
 By default `@ttsc/metro` finds the nearest `tsconfig.json` from the file being transformed and runs the plugins configured there: the standard `ttsc` model. If that is the config you want, `withTtsc(getDefaultConfig(__dirname))` is enough.

package/lib/core/upstream.js

@@ -33,14 +33,33 @@ const UPSTREAM_CANDIDATES = [
  */
 function resolveUpstreamTransformer(customPath, load = tryRequire) {
     if (customPath !== undefined && customPath.length !== 0) {
-        const upstream = load(customPath);
+        let upstream;
+        try {
+            upstream = load(customPath);
+        }
+        catch (cause) {
+            // The module resolves but failed while initializing (a top-level throw,
+            // a missing peer/transitive dependency, or a runtime-ABI rejection).
+            // Preserve the original diagnostic instead of masking it as absence.
+            throw new Error(`[@ttsc/metro] Failed to load the configured upstream transformer "${customPath}": ${errorMessage(cause)}`, { cause });
+        }
         if (upstream === undefined) {
             throw new Error(`[@ttsc/metro] Could not load the configured upstream transformer: ${customPath}`);
         }
         return upstream;
     }
     for (const candidate of UPSTREAM_CANDIDATES) {
-        const upstream = load(candidate);
+        let upstream;
+        try {
+            upstream = load(candidate);
+        }
+        catch (cause) {
+            // A candidate that resolves but throws while initializing is a broken
+            // installation of the active stack, not an absent optional peer. Surface
+            // it rather than silently falling through to a candidate that does not
+            // match this project.
+            throw new Error(`[@ttsc/metro] The upstream Metro transformer "${candidate}" is installed but failed to initialize: ${errorMessage(cause)}`, { cause });
+        }
         if (upstream !== undefined) {
             return upstream;
         }
@@ -50,13 +69,66 @@ function resolveUpstreamTransformer(customPath, load = tryRequire) {
         "(React Native), or set the `upstreamTransformer` option to an explicit " +
         "module path.");
 }
+/**
+ * Load an upstream transformer module, separating genuine absence from a broken
+ * installation.
+ *
+ * Resolution and execution are split deliberately. `require.resolve` only walks
+ * the module graph for the requested specifier; it never executes third-party
+ * code, so a failure there proves the requested candidate itself is not present
+ * — reported as `undefined` (absence) so automatic probing continues to the
+ * next optional peer. Once resolution succeeds, any error thrown by the actual
+ * `require` comes from executing the module body, including a missing peer or
+ * transitive dependency; that is a real initialization failure and is rethrown
+ * with its original message and stack so the caller can preserve it.
+ */
 function tryRequire(modulePath) {
     try {
-        return nodeRequire(modulePath);
+        nodeRequire.resolve(modulePath);
+    }
+    catch (error) {
+        if (isCandidateAbsent(error)) {
+            return undefined;
+        }
+        // A resolution error that is not one of the known "entry point absent"
+        // codes (e.g. an invalid specifier) is not evidence of a plain absence;
+        // surface it rather than silently skipping the candidate.
+        throw error;
     }
-    catch {
-        return undefined;
+    return nodeRequire(modulePath);
+}
+/**
+ * Whether a resolution error means the requested candidate's entry point is not
+ * available here — i.e. genuine absence, not a broken initialization.
+ *
+ * Resolution never executes the module body, so a `require.resolve` failure can
+ * only concern the requested specifier, never a transitive import of it. Each
+ * recognised code says the same thing about that specifier:
+ *
+ * - `MODULE_NOT_FOUND` / `ERR_MODULE_NOT_FOUND` — the package or file itself is
+ *   not installed (CJS and ESM loaders respectively).
+ * - `ERR_PACKAGE_PATH_NOT_EXPORTED` — the package is installed but the requested
+ *   subpath is not exported (or its export target is missing). This matters for
+ *   the `@expo/metro-config/babel-transformer` candidate, a package subpath:
+ *   under Expo/React Native version skew a present but non-exporting package
+ *   must stay non-fatal so auto-detection falls through to the next candidate,
+ *   exactly as a wholly absent package does.
+ *
+ * An error thrown later, while the resolved module executes, is a real
+ * initialization failure and is never routed here — the caller preserves it.
+ */
+function isCandidateAbsent(error) {
+    const code = error?.code;
+    return (code === "MODULE_NOT_FOUND" ||
+        code === "ERR_MODULE_NOT_FOUND" ||
+        code === "ERR_PACKAGE_PATH_NOT_EXPORTED");
+}
+/** Best-effort message extraction for wrapping an unknown thrown value. */
+function errorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
     }
+    return String(error);
 }
 
 exports.UPSTREAM_CANDIDATES = UPSTREAM_CANDIDATES;

package/lib/core/upstream.js.map

@@ -1 +1 @@
-{"version":3,"file":"upstream.js","sources":["../../src/core/upstream.ts"],"sourcesContent":[null],"names":["createRequire"],"mappings":";;;;;AAEA,MAAM,WAAW,GAAGA,yBAAa,CAAC,kQAAe,CAAC;AAqBlD;;;;AAIG;AACI,MAAM,mBAAmB,GAAG;IACjC,sCAAsC;IACtC,uCAAuC;IACvC,sCAAsC;;AAGxC;;;;;;;;;;;;;;;;AAgBG;SACa,0BAA0B,CACxC,UAAmB,EACnB,OAAgE,UAAU,EAAA;IAE1E,IAAI,UAAU,KAAK,SAAS,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE;AACvD,QAAA,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC;AACjC,QAAA,IAAI,QAAQ,KAAK,SAAS,EAAE;AAC1B,YAAA,MAAM,IAAI,KAAK,CACb,qEAAqE,UAAU,CAAA,CAAE,CAClF;QACH;AACA,QAAA,OAAO,QAAQ;IACjB;AAEA,IAAA,KAAK,MAAM,SAAS,IAAI,mBAAmB,EAAE;AAC3C,QAAA,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC;AAChC,QAAA,IAAI,QAAQ,KAAK,SAAS,EAAE;AAC1B,YAAA,OAAO,QAAQ;QACjB;IACF;IAEA,MAAM,IAAI,KAAK,CACb,sEAAsE;QACpE,qEAAqE;QACrE,yEAAyE;AACzE,QAAA,cAAc,CACjB;AACH;AAEA,SAAS,UAAU,CAAC,UAAkB,EAAA;AACpC,IAAA,IAAI;AACF,QAAA,OAAO,WAAW,CAAC,UAAU,CAAwB;IACvD;AAAE,IAAA,MAAM;AACN,QAAA,OAAO,SAAS;IAClB;AACF;;;;;"}
+{"version":3,"file":"upstream.js","sources":["../../src/core/upstream.ts"],"sourcesContent":[null],"names":["createRequire"],"mappings":";;;;;AAEA,MAAM,WAAW,GAAGA,yBAAa,CAAC,kQAAe,CAAC;AAqBlD;;;;AAIG;AACI,MAAM,mBAAmB,GAAG;IACjC,sCAAsC;IACtC,uCAAuC;IACvC,sCAAsC;;AAGxC;;;;;;;;;;;;;;;;AAgBG;SACa,0BAA0B,CACxC,UAAmB,EACnB,OAAgE,UAAU,EAAA;IAE1E,IAAI,UAAU,KAAK,SAAS,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE;AACvD,QAAA,IAAI,QAAyC;AAC7C,QAAA,IAAI;AACF,YAAA,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC;QAC7B;QAAE,OAAO,KAAK,EAAE;;;;AAId,YAAA,MAAM,IAAI,KAAK,CACb,CAAA,kEAAA,EAAqE,UAAU,MAAM,YAAY,CAAC,KAAK,CAAC,EAAE,EAC1G,EAAE,KAAK,EAAE,CACV;QACH;AACA,QAAA,IAAI,QAAQ,KAAK,SAAS,EAAE;AAC1B,YAAA,MAAM,IAAI,KAAK,CACb,qEAAqE,UAAU,CAAA,CAAE,CAClF;QACH;AACA,QAAA,OAAO,QAAQ;IACjB;AAEA,IAAA,KAAK,MAAM,SAAS,IAAI,mBAAmB,EAAE;AAC3C,QAAA,IAAI,QAAyC;AAC7C,QAAA,IAAI;AACF,YAAA,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC;QAC5B;QAAE,OAAO,KAAK,EAAE;;;;;AAKd,YAAA,MAAM,IAAI,KAAK,CACb,CAAA,8CAAA,EAAiD,SAAS,4CAA4C,YAAY,CAAC,KAAK,CAAC,EAAE,EAC3H,EAAE,KAAK,EAAE,CACV;QACH;AACA,QAAA,IAAI,QAAQ,KAAK,SAAS,EAAE;AAC1B,YAAA,OAAO,QAAQ;QACjB;IACF;IAEA,MAAM,IAAI,KAAK,CACb,sEAAsE;QACpE,qEAAqE;QACrE,yEAAyE;AACzE,QAAA,cAAc,CACjB;AACH;AAEA;;;;;;;;;;;;AAYG;AACH,SAAS,UAAU,CAAC,UAAkB,EAAA;AACpC,IAAA,IAAI;AACF,QAAA,WAAW,CAAC,OAAO,CAAC,UAAU,CAAC;IACjC;IAAE,OAAO,KAAK,EAAE;AACd,QAAA,IAAI,iBAAiB,CAAC,KAAK,CAAC,EAAE;AAC5B,YAAA,OAAO,SAAS;QAClB;;;;AAIA,QAAA,MAAM,KAAK;IACb;AACA,IAAA,OAAO,WAAW,CAAC,UAAU,CAAwB;AACvD;AAEA;;;;;;;;;;;;;;;;;;;AAmBG;AACH,SAAS,iBAAiB,CAAC,KAAc,EAAA;AACvC,IAAA,MAAM,IAAI,GAAI,KAA+C,EAAE,IAAI;IACnE,QACE,IAAI,KAAK,kBAAkB;AAC3B,QAAA,IAAI,KAAK,sBAAsB;QAC/B,IAAI,KAAK,+BAA+B;AAE5C;AAEA;AACA,SAAS,YAAY,CAAC,KAAc,EAAA;AAClC,IAAA,IAAI,KAAK,YAAY,KAAK,EAAE;QAC1B,OAAO,KAAK,CAAC,OAAO;IACtB;AACA,IAAA,OAAO,MAAM,CAAC,KAAK,CAAC;AACtB;;;;;"}

package/lib/core/upstream.mjs

@@ -30,14 +30,33 @@ const UPSTREAM_CANDIDATES = [
  */
 function resolveUpstreamTransformer(customPath, load = tryRequire) {
     if (customPath !== undefined && customPath.length !== 0) {
-        const upstream = load(customPath);
+        let upstream;
+        try {
+            upstream = load(customPath);
+        }
+        catch (cause) {
+            // The module resolves but failed while initializing (a top-level throw,
+            // a missing peer/transitive dependency, or a runtime-ABI rejection).
+            // Preserve the original diagnostic instead of masking it as absence.
+            throw new Error(`[@ttsc/metro] Failed to load the configured upstream transformer "${customPath}": ${errorMessage(cause)}`, { cause });
+        }
         if (upstream === undefined) {
             throw new Error(`[@ttsc/metro] Could not load the configured upstream transformer: ${customPath}`);
         }
         return upstream;
     }
     for (const candidate of UPSTREAM_CANDIDATES) {
-        const upstream = load(candidate);
+        let upstream;
+        try {
+            upstream = load(candidate);
+        }
+        catch (cause) {
+            // A candidate that resolves but throws while initializing is a broken
+            // installation of the active stack, not an absent optional peer. Surface
+            // it rather than silently falling through to a candidate that does not
+            // match this project.
+            throw new Error(`[@ttsc/metro] The upstream Metro transformer "${candidate}" is installed but failed to initialize: ${errorMessage(cause)}`, { cause });
+        }
         if (upstream !== undefined) {
             return upstream;
         }
@@ -47,13 +66,66 @@ function resolveUpstreamTransformer(customPath, load = tryRequire) {
         "(React Native), or set the `upstreamTransformer` option to an explicit " +
         "module path.");
 }
+/**
+ * Load an upstream transformer module, separating genuine absence from a broken
+ * installation.
+ *
+ * Resolution and execution are split deliberately. `require.resolve` only walks
+ * the module graph for the requested specifier; it never executes third-party
+ * code, so a failure there proves the requested candidate itself is not present
+ * — reported as `undefined` (absence) so automatic probing continues to the
+ * next optional peer. Once resolution succeeds, any error thrown by the actual
+ * `require` comes from executing the module body, including a missing peer or
+ * transitive dependency; that is a real initialization failure and is rethrown
+ * with its original message and stack so the caller can preserve it.
+ */
 function tryRequire(modulePath) {
     try {
-        return nodeRequire(modulePath);
+        nodeRequire.resolve(modulePath);
+    }
+    catch (error) {
+        if (isCandidateAbsent(error)) {
+            return undefined;
+        }
+        // A resolution error that is not one of the known "entry point absent"
+        // codes (e.g. an invalid specifier) is not evidence of a plain absence;
+        // surface it rather than silently skipping the candidate.
+        throw error;
     }
-    catch {
-        return undefined;
+    return nodeRequire(modulePath);
+}
+/**
+ * Whether a resolution error means the requested candidate's entry point is not
+ * available here — i.e. genuine absence, not a broken initialization.
+ *
+ * Resolution never executes the module body, so a `require.resolve` failure can
+ * only concern the requested specifier, never a transitive import of it. Each
+ * recognised code says the same thing about that specifier:
+ *
+ * - `MODULE_NOT_FOUND` / `ERR_MODULE_NOT_FOUND` — the package or file itself is
+ *   not installed (CJS and ESM loaders respectively).
+ * - `ERR_PACKAGE_PATH_NOT_EXPORTED` — the package is installed but the requested
+ *   subpath is not exported (or its export target is missing). This matters for
+ *   the `@expo/metro-config/babel-transformer` candidate, a package subpath:
+ *   under Expo/React Native version skew a present but non-exporting package
+ *   must stay non-fatal so auto-detection falls through to the next candidate,
+ *   exactly as a wholly absent package does.
+ *
+ * An error thrown later, while the resolved module executes, is a real
+ * initialization failure and is never routed here — the caller preserves it.
+ */
+function isCandidateAbsent(error) {
+    const code = error?.code;
+    return (code === "MODULE_NOT_FOUND" ||
+        code === "ERR_MODULE_NOT_FOUND" ||
+        code === "ERR_PACKAGE_PATH_NOT_EXPORTED");
+}
+/** Best-effort message extraction for wrapping an unknown thrown value. */
+function errorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
     }
+    return String(error);
 }
 
 export { UPSTREAM_CANDIDATES, resolveUpstreamTransformer };

package/lib/core/upstream.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"upstream.mjs","sources":["../../src/core/upstream.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAEA,MAAM,WAAW,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;AAqBlD;;;;AAIG;AACI,MAAM,mBAAmB,GAAG;IACjC,sCAAsC;IACtC,uCAAuC;IACvC,sCAAsC;;AAGxC;;;;;;;;;;;;;;;;AAgBG;SACa,0BAA0B,CACxC,UAAmB,EACnB,OAAgE,UAAU,EAAA;IAE1E,IAAI,UAAU,KAAK,SAAS,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE;AACvD,QAAA,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC;AACjC,QAAA,IAAI,QAAQ,KAAK,SAAS,EAAE;AAC1B,YAAA,MAAM,IAAI,KAAK,CACb,qEAAqE,UAAU,CAAA,CAAE,CAClF;QACH;AACA,QAAA,OAAO,QAAQ;IACjB;AAEA,IAAA,KAAK,MAAM,SAAS,IAAI,mBAAmB,EAAE;AAC3C,QAAA,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC;AAChC,QAAA,IAAI,QAAQ,KAAK,SAAS,EAAE;AAC1B,YAAA,OAAO,QAAQ;QACjB;IACF;IAEA,MAAM,IAAI,KAAK,CACb,sEAAsE;QACpE,qEAAqE;QACrE,yEAAyE;AACzE,QAAA,cAAc,CACjB;AACH;AAEA,SAAS,UAAU,CAAC,UAAkB,EAAA;AACpC,IAAA,IAAI;AACF,QAAA,OAAO,WAAW,CAAC,UAAU,CAAwB;IACvD;AAAE,IAAA,MAAM;AACN,QAAA,OAAO,SAAS;IAClB;AACF;;;;"}
+{"version":3,"file":"upstream.mjs","sources":["../../src/core/upstream.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAEA,MAAM,WAAW,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;AAqBlD;;;;AAIG;AACI,MAAM,mBAAmB,GAAG;IACjC,sCAAsC;IACtC,uCAAuC;IACvC,sCAAsC;;AAGxC;;;;;;;;;;;;;;;;AAgBG;SACa,0BAA0B,CACxC,UAAmB,EACnB,OAAgE,UAAU,EAAA;IAE1E,IAAI,UAAU,KAAK,SAAS,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE;AACvD,QAAA,IAAI,QAAyC;AAC7C,QAAA,IAAI;AACF,YAAA,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC;QAC7B;QAAE,OAAO,KAAK,EAAE;;;;AAId,YAAA,MAAM,IAAI,KAAK,CACb,CAAA,kEAAA,EAAqE,UAAU,MAAM,YAAY,CAAC,KAAK,CAAC,EAAE,EAC1G,EAAE,KAAK,EAAE,CACV;QACH;AACA,QAAA,IAAI,QAAQ,KAAK,SAAS,EAAE;AAC1B,YAAA,MAAM,IAAI,KAAK,CACb,qEAAqE,UAAU,CAAA,CAAE,CAClF;QACH;AACA,QAAA,OAAO,QAAQ;IACjB;AAEA,IAAA,KAAK,MAAM,SAAS,IAAI,mBAAmB,EAAE;AAC3C,QAAA,IAAI,QAAyC;AAC7C,QAAA,IAAI;AACF,YAAA,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC;QAC5B;QAAE,OAAO,KAAK,EAAE;;;;;AAKd,YAAA,MAAM,IAAI,KAAK,CACb,CAAA,8CAAA,EAAiD,SAAS,4CAA4C,YAAY,CAAC,KAAK,CAAC,EAAE,EAC3H,EAAE,KAAK,EAAE,CACV;QACH;AACA,QAAA,IAAI,QAAQ,KAAK,SAAS,EAAE;AAC1B,YAAA,OAAO,QAAQ;QACjB;IACF;IAEA,MAAM,IAAI,KAAK,CACb,sEAAsE;QACpE,qEAAqE;QACrE,yEAAyE;AACzE,QAAA,cAAc,CACjB;AACH;AAEA;;;;;;;;;;;;AAYG;AACH,SAAS,UAAU,CAAC,UAAkB,EAAA;AACpC,IAAA,IAAI;AACF,QAAA,WAAW,CAAC,OAAO,CAAC,UAAU,CAAC;IACjC;IAAE,OAAO,KAAK,EAAE;AACd,QAAA,IAAI,iBAAiB,CAAC,KAAK,CAAC,EAAE;AAC5B,YAAA,OAAO,SAAS;QAClB;;;;AAIA,QAAA,MAAM,KAAK;IACb;AACA,IAAA,OAAO,WAAW,CAAC,UAAU,CAAwB;AACvD;AAEA;;;;;;;;;;;;;;;;;;;AAmBG;AACH,SAAS,iBAAiB,CAAC,KAAc,EAAA;AACvC,IAAA,MAAM,IAAI,GAAI,KAA+C,EAAE,IAAI;IACnE,QACE,IAAI,KAAK,kBAAkB;AAC3B,QAAA,IAAI,KAAK,sBAAsB;QAC/B,IAAI,KAAK,+BAA+B;AAE5C;AAEA;AACA,SAAS,YAAY,CAAC,KAAc,EAAA;AAClC,IAAA,IAAI,KAAK,YAAY,KAAK,EAAE;QAC1B,OAAO,KAAK,CAAC,OAAO;IACtB;AACA,IAAA,OAAO,MAAM,CAAC,KAAK,CAAC;AACtB;;;;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttsc/metro",
-  "version": "0.18.4",
+  "version": "0.19.0",
   "description": "Metro (React Native / Expo) adapter for ttsc plugins.",
   "main": "lib/index.js",
   "module": "lib/index.mjs",
@@ -35,7 +35,7 @@
     "src"
   ],
   "dependencies": {
-    "@ttsc/unplugin": "0.18.4"
+    "@ttsc/unplugin": "0.19.0"
   },
   "peerDependencies": {
     "@expo/metro-config": "*",
@@ -59,12 +59,10 @@
     "@types/node": "^25.3.0",
     "rimraf": "^6.1.2",
     "rollup": "^4.60.3",
-    "rollup-plugin-auto-external": "^2.0.0",
-    "rollup-plugin-node-externals": "^9.0.1",
     "tinyglobby": "^0.2.16",
     "tslib": "^2.8.1",
     "typescript": "^7.0.2",
-    "ttsc": "0.18.4"
+    "ttsc": "0.19.0"
   },
   "repository": {
     "type": "git",

package/src/core/upstream.ts

@@ -54,7 +54,18 @@ export function resolveUpstreamTransformer(
   load: (modulePath: string) => UpstreamTransformer | undefined = tryRequire,
 ): UpstreamTransformer {
   if (customPath !== undefined && customPath.length !== 0) {
-    const upstream = load(customPath);
+    let upstream: UpstreamTransformer | undefined;
+    try {
+      upstream = load(customPath);
+    } catch (cause) {
+      // The module resolves but failed while initializing (a top-level throw,
+      // a missing peer/transitive dependency, or a runtime-ABI rejection).
+      // Preserve the original diagnostic instead of masking it as absence.
+      throw new Error(
+        `[@ttsc/metro] Failed to load the configured upstream transformer "${customPath}": ${errorMessage(cause)}`,
+        { cause },
+      );
+    }
     if (upstream === undefined) {
       throw new Error(
         `[@ttsc/metro] Could not load the configured upstream transformer: ${customPath}`,
@@ -64,7 +75,19 @@ export function resolveUpstreamTransformer(
   }
 
   for (const candidate of UPSTREAM_CANDIDATES) {
-    const upstream = load(candidate);
+    let upstream: UpstreamTransformer | undefined;
+    try {
+      upstream = load(candidate);
+    } catch (cause) {
+      // A candidate that resolves but throws while initializing is a broken
+      // installation of the active stack, not an absent optional peer. Surface
+      // it rather than silently falling through to a candidate that does not
+      // match this project.
+      throw new Error(
+        `[@ttsc/metro] The upstream Metro transformer "${candidate}" is installed but failed to initialize: ${errorMessage(cause)}`,
+        { cause },
+      );
+    }
     if (upstream !== undefined) {
       return upstream;
     }
@@ -78,10 +101,67 @@ export function resolveUpstreamTransformer(
   );
 }
 
+/**
+ * Load an upstream transformer module, separating genuine absence from a broken
+ * installation.
+ *
+ * Resolution and execution are split deliberately. `require.resolve` only walks
+ * the module graph for the requested specifier; it never executes third-party
+ * code, so a failure there proves the requested candidate itself is not present
+ * — reported as `undefined` (absence) so automatic probing continues to the
+ * next optional peer. Once resolution succeeds, any error thrown by the actual
+ * `require` comes from executing the module body, including a missing peer or
+ * transitive dependency; that is a real initialization failure and is rethrown
+ * with its original message and stack so the caller can preserve it.
+ */
 function tryRequire(modulePath: string): UpstreamTransformer | undefined {
   try {
-    return nodeRequire(modulePath) as UpstreamTransformer;
-  } catch {
-    return undefined;
+    nodeRequire.resolve(modulePath);
+  } catch (error) {
+    if (isCandidateAbsent(error)) {
+      return undefined;
+    }
+    // A resolution error that is not one of the known "entry point absent"
+    // codes (e.g. an invalid specifier) is not evidence of a plain absence;
+    // surface it rather than silently skipping the candidate.
+    throw error;
+  }
+  return nodeRequire(modulePath) as UpstreamTransformer;
+}
+
+/**
+ * Whether a resolution error means the requested candidate's entry point is not
+ * available here — i.e. genuine absence, not a broken initialization.
+ *
+ * Resolution never executes the module body, so a `require.resolve` failure can
+ * only concern the requested specifier, never a transitive import of it. Each
+ * recognised code says the same thing about that specifier:
+ *
+ * - `MODULE_NOT_FOUND` / `ERR_MODULE_NOT_FOUND` — the package or file itself is
+ *   not installed (CJS and ESM loaders respectively).
+ * - `ERR_PACKAGE_PATH_NOT_EXPORTED` — the package is installed but the requested
+ *   subpath is not exported (or its export target is missing). This matters for
+ *   the `@expo/metro-config/babel-transformer` candidate, a package subpath:
+ *   under Expo/React Native version skew a present but non-exporting package
+ *   must stay non-fatal so auto-detection falls through to the next candidate,
+ *   exactly as a wholly absent package does.
+ *
+ * An error thrown later, while the resolved module executes, is a real
+ * initialization failure and is never routed here — the caller preserves it.
+ */
+function isCandidateAbsent(error: unknown): boolean {
+  const code = (error as { code?: unknown } | null | undefined)?.code;
+  return (
+    code === "MODULE_NOT_FOUND" ||
+    code === "ERR_MODULE_NOT_FOUND" ||
+    code === "ERR_PACKAGE_PATH_NOT_EXPORTED"
+  );
+}
+
+/** Best-effort message extraction for wrapping an unknown thrown value. */
+function errorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
   }
+  return String(error);
 }