@ttsc/metro 0.30.4 → 0.31.1

package/lib/transformer.mjs

@@ -1,9 +1,10 @@
-import { createTtscTransformCache, isTransformTarget, resolveOptions, transformTtsc } from '@ttsc/unplugin/api';
-import { createHash } from 'node:crypto';
+import { createTtscTransformCache, shareTtscTransformCache, readTtscTransformSession, isTransformTarget, resolveOptions, transformTtsc } from '@ttsc/unplugin/api';
+import { createHash, randomBytes } from 'node:crypto';
 import { createRequire } from 'node:module';
 import path from 'node:path';
 import { stableStringify, computeProjectFingerprint, resolveProjectView, createSnapshotRecorder } from './core/fingerprint.mjs';
 import { resolveOptionsFromEnv } from './core/options.mjs';
+import { remapAstLocations } from './core/remapAstLocations.mjs';
 import { resolveUpstreamTransformer } from './core/upstream.mjs';
 
 /**
@@ -22,6 +23,11 @@ import { resolveUpstreamTransformer } from './core/upstream.mjs';
  * generation hit. Cross-file invalidation also rides the project fingerprint
  * {@link getCacheKey} folds into Metro's static transformer key (see
  * `core/fingerprint.ts`).
+ *
+ * The adapter passes no `watching` declaration in its hooks, so a project whose
+ * plugin observations are unavailable (a generation the core can only serve
+ * fresh) fails the transform with an explicit error instead of caching it: the
+ * core refuses fresh-only output unless the host states it is not watching.
  */
 const nodeRequire = createRequire(import.meta.url);
 /**
@@ -33,6 +39,9 @@ const nodeRequire = createRequire(import.meta.url);
 let resolved;
 let unpluginOptions;
 const cache = createTtscTransformCache();
+// Metro's workers share each compile through the session `withTtsc` opened
+// (samchon/ttsc#1390).
+shareTtscTransformCache(cache, readTtscTransformSession());
 let snapshotRecorder;
 /** Lazily resolve the worker-side options (from {@link resolveOptionsFromEnv}). */
 function options() {
@@ -54,6 +63,39 @@ function recorder() {
  * monorepos and when Metro is launched from a parent directory. Getting this
  * wrong makes every file look "outside the project" and silently skips the
  * plugin pass.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Node path.isAbsolute/path.resolve implement Metro's filename contract.
+ *   Absolute input is retained; relative input is anchored at supplied
+ *   projectRoot, with cwd only for callers lacking that option.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   This helper owns the single relative-to-absolute boundary, keeping Metro's
+ *   original filename separate from the compiler address.
+ *
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   This operation chooses a base and delegates native path resolution;
+ *   it owns no input collection or processing strategy.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   It maps one filename and supplied options without shared computation.
+ *
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   The returned path transfers to its caller; no resource is retained.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   This correct owning anchor avoids monorepo misrouting without matching
+ *   error text or special-casing fixture names.
+ *
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Node path handles native separators, roots and drive letters. No URLs or
+ *   shell commands are mixed with filenames and no filesystem is changed.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   The native JSDoc explains the project-relative input, absolute result and
+ *   cwd fallback reason. Checked against the documentation skill: separate
+ *   paragraphs state the contract and why its nonobvious boundary matters;
+ *   field comments retain their own useful facts.
  */
 function resolveAbsoluteFilename(filename, options) {
     if (path.isAbsolute(filename)) {
@@ -71,7 +113,60 @@ function resolveAbsoluteFilename(filename, options) {
  * Expo/React-Native Babel transformer to produce the AST Metro expects. The
  * upstream call receives Metro's original params (notably the project-relative
  * `filename`, which Babel expects); only `src` is replaced with the
- * ttsc-transformed source.
+ * ttsc-transformed source. When the adapter returns a source map for that
+ * source, the upstream AST's locations are moved back through it to the
+ * author's lines, because Metro maps the AST against the file it read
+ * (samchon/ttsc#1392).
+ *
+ * An explicit `project` option selects its tsconfig. Otherwise the adapter
+ * discovers the nearest tsconfig and follows its references to the project
+ * admitting the file, using Metro's `projectRoot` or the current working
+ * directory to resolve a relative file.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Metro's transformer callback composes the shared Unplugin transform core
+ *   with the selected Babel transformer. One resolved project view is frozen
+ *   into compilation and recorder inputs. Noneligible or out-of-program files
+ *   follow the shared core contract; genuine compiler/load failures propagate.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   The entry point gates delivery, freezes one project view for compilation
+ *   and recording, then delegates to Babel. Shared core helpers own checking
+ *   and caching; the adapter owns only Metro transport and AST remapping.
+ *
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Filtering runs before compilation. Eligible deliveries resolve one view
+ *   and record their inputs in a single batch; compiler and AST traversal
+ *   costs belong to their delegated owners rather than repeated per input.
+ *
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   The worker's shared transform cache validates project state on each hit,
+ *   while the inherited session shares compilation across workers. The same
+ *   project view and options feed compilation and generation recording; Babel
+ *   is invoked for the actual delivery and is not memoized by this adapter.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   Worker singletons own resolved options, the transform cache and recorder
+ *   until process termination. The shared core owns cached generations and
+ *   session storage; the recorder owns its cumulative paths. This entry point
+ *   exposes no disposal signal from Metro and does not claim a fixed byte bound.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Only the returned AST's owned locations are updated, with no patched
+ *   loader or test-specific production behavior.
+ *
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Metro-relative filenames drive substring filters; Node path.resolve
+ *   produces absolute compiler addresses. The shared core owns native
+ *   compiler/session access, while Babel retains the original filename.
+ *   Worker transport is JSON and no shell command is constructed here.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   The native JSDoc explains pass order, original parameter preservation,
+ *   project selection and AST location mutation. Checked against the
+ *   documentation skill: separate paragraphs state the contract and why its
+ *   nonobvious boundary matters; field comments retain their own useful
+ *   facts.
  */
 async function transform(params) {
     const opts = options();
@@ -84,6 +179,8 @@ async function transform(params) {
         return upstream.transform(params);
     }
     let transformedSrc = params.src;
+    let transformedMap;
+    let absoluteFilename = params.filename;
     {
         unpluginOptions ??= resolveOptions(opts.ttsc);
         const projectRoot = typeof params.options.projectRoot === "string"
@@ -91,6 +188,7 @@ async function transform(params) {
             : undefined;
         const explicitProject = typeof opts.ttsc.project === "string" ? opts.ttsc.project : undefined;
         const filename = resolveAbsoluteFilename(params.filename, params.options);
+        absoluteFilename = filename;
         const project = resolveProjectView({
             compilerOptions: opts.ttsc.compilerOptions,
             explicitProject,
@@ -136,9 +234,16 @@ async function transform(params) {
         // Genuine compile and type failures still propagate so Metro surfaces them.
         if (result !== undefined && typeof result.code === "string") {
             transformedSrc = result.code;
+            transformedMap = result.map;
         }
     }
-    return upstream.transform({ ...params, src: transformedSrc });
+    const output = await upstream.transform({ ...params, src: transformedSrc });
+    // Metro maps the returned AST against the file it read, so the upstream's
+    // positions in the transformed text are moved back to the author's lines.
+    if (transformedMap !== undefined) {
+        remapAstLocations(output.ast, transformedMap, absoluteFilename);
+    }
+    return output;
 }
 /**
  * Metro transform-cache key.
@@ -159,23 +264,70 @@ async function transform(params) {
  * A change to any fingerprinted input re-keys every transformed file at
  * project-level granularity, forced by Metro's single static key, replacing the
  * former manual `--reset-cache` step. Resolving the upstream is deliberately
- * non-fatal here: a missing peer must not crash cache-key computation. See the
- * README "Caveats" and samchon/ttsc#721.
+ * non-fatal here: a missing peer must not crash cache-key computation, but a
+ * failed upstream key withdraws reuse with a nonce. See the README "Caveats"
+ * and samchon/ttsc#721.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Node sha256 combines package identity, stable resolved options, forwarded
+ *   upstream key and the project fingerprint required by Metro's
+ *   one-static-key contract. Failed upstream loads or callbacks contribute a
+ *   nonce; an absent optional callback contributes no additional key.
+ *   Forwarded compiler and plugin records retain their JSON property order
+ *   because the compiler or a plugin can give that order semantic meaning.
+ *   Fingerprint failure disables reuse through a nonce rather
+ *   than fabricating a proven generation.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One hash assembly combines options, upstream contribution and the project
+ *   fingerprint. The fingerprint owner handles persistence and validity;
+ *   cacheKeyProjectRoot extracts Metro's argument without duplicating discovery.
+ *
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   One static key per Metro run hashes encoded options, the upstream key
+ *   and one project fingerprint. Key assembly is linear in their string bytes;
+ *   the fingerprint owner accounts for project scans and config traversal.
+ *
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   Options, adapter version, upstream key and exact project state contribute
+ *   to the shared key. Project observation failures withdraw reuse through a
+ *   nonce. A failing upstream load or key uses a nonce too, preserving the
+ *   nonfatal keying boundary without pretending its external state is known.
+ *
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   The hash is local to this call. Worker singletons are owned by transform
+ *   and persisted baseline files by prepareSnapshot, not the hash assembler.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Decision values come from the documented inputs and product protocol
+ *   rather than expected test answers. No compensating path is introduced to
+ *   make a known example pass.
+ *
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Native project roots are interpreted by the fingerprint owner and Node
+ *   module loading reads package identity. Hash input has deterministic
+ *   string representation across OSes; filesystem content and identity remain
+ *   deliberately host-specific.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   The native JSDoc explains one key per run, all contributions,
+ *   project-wide invalidation and nonfatal upstream key policy. Checked
+ *   against the documentation skill: separate paragraphs state the contract
+ *   and why its nonobvious boundary matters; field comments retain their own
+ *   useful facts.
  */
 function getCacheKey(...args) {
     const opts = options();
     const hash = createHash("sha256");
     hash.update(`@ttsc/metro:${packageVersion()}`);
     hash.update(stableStringify({
-        ttsc: opts.ttsc,
+        ttsc: JSON.stringify(opts.ttsc),
         include: opts.include,
         exclude: opts.exclude,
         upstreamTransformer: opts.upstreamTransformer ?? null,
     }));
     const upstreamKey = upstreamCacheKey(opts.upstreamTransformer, args);
-    if (upstreamKey.length !== 0) {
-        hash.update(upstreamKey);
-    }
+    hash.update(upstreamKey ?? `nonce:${randomBytes(32).toString("hex")}`);
     hash.update(computeProjectFingerprint({
         // The same overlay `transform` hands the recorder. Both read these
         // options from `options()`, so the walk and the recorder judge one
@@ -208,8 +360,9 @@ function cacheKeyProjectRoot(args) {
  * Fold the upstream transformer's cache key in, defensively. Forwards Metro's
  * own `getCacheKey` arguments so the upstream's babelrc-derived key is
  * preserved, and never throws: a missing peer or a throwing upstream
- * `getCacheKey` yields an empty contribution rather than failing the whole
- * build's cache keying.
+ * `getCacheKey` yields `undefined`, withdrawing cross-run reuse without failing
+ * the whole build's cache keying. An absent optional callback still contributes
+ * the empty string.
  */
 function upstreamCacheKey(upstreamTransformer, args) {
     let upstream;
@@ -217,7 +370,7 @@ function upstreamCacheKey(upstreamTransformer, args) {
         upstream = resolveUpstreamTransformer(upstreamTransformer);
     }
     catch {
-        return "";
+        return undefined;
     }
     if (upstream.getCacheKey === undefined) {
         return "";
@@ -226,14 +379,56 @@ function upstreamCacheKey(upstreamTransformer, args) {
         return String(upstream.getCacheKey(...args) ?? "");
     }
     catch {
-        return "";
+        return undefined;
     }
 }
 /**
  * Decide whether a file should run through the ttsc pass. Only TypeScript
  * sources (`.ts`/`.tsx`/`.mts`/`.cts`, excluding every declaration form)
- * qualify; `exclude` substrings win over `include`, and an empty `include`
- * means "all TypeScript". Exported for unit testing.
+ * qualify, and a file below a `node_modules` directory never does, whatever
+ * `include` says, because the shared `isTransformTarget` predicate rejects it
+ * first. `exclude` substrings win over `include`, and an empty `include` means
+ * "all eligible TypeScript". Patterns use the supplied project-relative
+ * filename literally; this operation does not normalize separators or
+ * filesystem case.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   The shared isTransformTarget predicate owns supported TypeScript
+ *   extensions, declaration exclusions, virtual-module and node_modules
+ *   exclusions. Literal substring filters apply to Metro's project-relative
+ *   filename, with exclusion taking precedence.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   This predicate orders extension eligibility, exclusion and inclusion as
+ *   early returns. Compiler execution remains outside the filtering policy.
+ *
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Extension matching precedes substring scans; exclusion returns early and
+ *   inclusion stops at its first match. Cost follows pattern count and supplied
+ *   filename length without allocating a normalized copy for literal matching.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   This inexpensive predicate coordinates no shared computation and accepts
+ *   caller-owned, potentially mutable option arrays.
+ *
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Filtering retains no caller data and opens no native resource.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   This pure decision neither invokes compilation nor mutates options, and
+ *   has no fixture or test-mode branch.
+ *
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation
+ *   This predicate matches TypeScript extensions and caller-supplied literal
+ *   substrings. It defines no filesystem identity or native path
+ *   normalization contract.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   The native JSDoc explains eligible extensions, declaration and
+ *   node_modules exclusion, empty include and exclusion precedence. Checked
+ *   against the documentation skill: separate paragraphs state the contract
+ *   and why its nonobvious boundary matters; field comments retain their own
+ *   useful facts.
  */
 function shouldTransform(filename, opts) {
     if (!isTransformTarget(filename)) {

package/lib/transformer.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"transformer.mjs","sources":["../src/transformer.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}
+{"version":3,"file":"transformer.mjs","sources":["../src/transformer.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttsc/metro",
-  "version": "0.30.4",
+  "version": "0.31.1",
   "description": "Metro (React Native / Expo) adapter for ttsc plugins.",
   "main": "lib/index.js",
   "module": "lib/index.mjs",
@@ -35,25 +35,13 @@
     "src"
   ],
   "dependencies": {
-    "@ttsc/unplugin": "^0.30.4"
+    "@ttsc/unplugin": "^0.31.1"
   },
   "peerDependencies": {
-    "@expo/metro-config": "*",
-    "@react-native/metro-babel-transformer": "*",
-    "metro-react-native-babel-transformer": "*"
-  },
-  "peerDependenciesMeta": {
-    "@expo/metro-config": {
-      "optional": true
-    },
-    "@react-native/metro-babel-transformer": {
-      "optional": true
-    },
-    "metro-react-native-babel-transformer": {
-      "optional": true
-    }
+    "ttsc": "^0.31.1"
   },
   "devDependencies": {
+    "@wrtnlabs/evidence": "^0.3.1",
     "@rollup/plugin-commonjs": "^29.0.2",
     "@rollup/plugin-node-resolve": "^16.0.3",
     "@types/node": "^25.3.0",
@@ -62,7 +50,7 @@
     "tinyglobby": "^0.2.16",
     "tslib": "^2.8.1",
     "typescript": "^7.0.2",
-    "ttsc": "0.30.4"
+    "ttsc": "0.31.1"
   },
   "repository": {
     "type": "git",
@@ -76,6 +64,7 @@
   "homepage": "https://ttsc.dev",
   "sideEffects": false,
   "scripts": {
-    "build": "rimraf lib && tsc --emitDeclarationOnly && rollup -c"
+    "build": "rimraf lib && tsc --emitDeclarationOnly && rollup -c",
+    "evidence": "evidence"
   }
 }

package/src/core/SnapshotReadOperations.ts

@@ -0,0 +1,121 @@
+/**
+ * The filesystem reads the snapshot reader performs, injectable so a test can
+ * drive the interleaving of a listing with a concurrent compaction. Production
+ * passes nothing and reads the real filesystem.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   A structural record of the three Node filesystem reads the snapshot reader
+ *   makes; the default delegates to node:fs unchanged.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One optional parameter carries the read boundary instead of a test mode
+ *   flag, mirroring the repository's injectable filesystem operations.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Production code never branches on the injection; no fs method is patched.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   The native JSDoc states why the boundary exists and that production uses
+ *   the real filesystem.
+ *
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Declares a shape only; it holds no state, handle or buffer.
+ *
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   Declares a shape only; there is no loop or processing in it.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Declares a shape only; it computes nothing to share.
+ *
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation
+ *   Declares three call signatures; the host filesystem interprets every path it is given.
+ */
+export interface SnapshotReadOperations {
+  /**
+   * Whether a path exists, as `fs.existsSync`.
+   *
+   * @evidence contracts/common.md#principled-implementation
+   *   Signature of the Node call it replaces; the default delegates to it.
+   *
+   * @evidence contracts/common.md#clear-and-simple-design
+   *   One call per member, no behavior of its own.
+   *
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts
+   *   The reader never branches on whether it was injected.
+   *
+   * @evidence contracts/common.md#meaningful-documentation
+   *   States which read this member stands for.
+   *
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+   *   Declares a shape only; it holds no state, handle or buffer.
+   *
+   * @evidenceExclude contracts/performance.md#efficient-algorithms
+   *   Declares a shape only; there is no loop or processing in it.
+   *
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+   *   Declares a shape only; it computes nothing to share.
+   *
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation
+   *   Forwards its path to the host call unchanged; no path is interpreted here.
+   */
+  existsSync: (file: string) => boolean;
+
+  /**
+   * Text of a file, as `fs.readFileSync`; throws a missing-file error when
+   * absent.
+   *
+   * @evidence contracts/common.md#principled-implementation
+   *   Signature of the Node call it replaces; the default delegates to it.
+   *
+   * @evidence contracts/common.md#clear-and-simple-design
+   *   One call per member, no behavior of its own.
+   *
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts
+   *   The reader never branches on whether it was injected.
+   *
+   * @evidence contracts/common.md#meaningful-documentation
+   *   States which read this member stands for.
+   *
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+   *   Declares a shape only; it holds no state, handle or buffer.
+   *
+   * @evidenceExclude contracts/performance.md#efficient-algorithms
+   *   Declares a shape only; there is no loop or processing in it.
+   *
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+   *   Declares a shape only; it computes nothing to share.
+   *
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation
+   *   Forwards its path to the host call unchanged; no path is interpreted here.
+   */
+  readFileSync: (file: string, encoding: "utf8") => string;
+
+  /**
+   * Entry names of a directory, as `fs.readdirSync`.
+   *
+   * @evidence contracts/common.md#principled-implementation
+   *   Signature of the Node call it replaces; the default delegates to it.
+   *
+   * @evidence contracts/common.md#clear-and-simple-design
+   *   One call per member, no behavior of its own.
+   *
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts
+   *   The reader never branches on whether it was injected.
+   *
+   * @evidence contracts/common.md#meaningful-documentation
+   *   States which read this member stands for.
+   *
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+   *   Declares a shape only; it holds no state, handle or buffer.
+   *
+   * @evidenceExclude contracts/performance.md#efficient-algorithms
+   *   Declares a shape only; there is no loop or processing in it.
+   *
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+   *   Declares a shape only; it computes nothing to share.
+   *
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation
+   *   Forwards its directory to the host call unchanged; no path is interpreted here.
+   */
+  readdirSync: (directory: string) => string[];
+}

package/src/core/TtscMetroOptions.ts

@@ -0,0 +1,127 @@
+import type { TtscUnpluginOptions } from "@ttsc/unplugin/api";
+
+/**
+ * Options accepted by {@link withTtsc} and the Metro transformer.
+ *
+ * The `project` / `compilerOptions` / `plugins` fields are inherited from
+ * `@ttsc/unplugin` so the Metro adapter speaks the exact same configuration
+ * language as every other bundler integration. The remaining fields are
+ * Metro-specific.
+ *
+ * Every field is JSON-serialisable on purpose: `withTtsc` runs in the Metro
+ * **config** process, but the transformer runs in Metro's **worker** processes,
+ * so the resolved options have to survive a JSON / env round-trip to reach them
+ * (see {@link serializeOptions}). That is why `include`/`exclude` are plain
+ * substring patterns rather than `RegExp`.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   This interface extends the documented Unplugin option contract rather than
+ *   defining another plugin protocol. Metro adds JSON-compatible upstream and
+ *   substring filters for its config-to-worker transport.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   Inheritance keeps shared compiler options with Unplugin; this interface
+ *   adds only upstream selection and the two Metro substring filters.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The representation follows the documented consumer contract; its fields do
+ *   not introduce fixture-selected variants.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   The native JSDoc explains inherited options, JSON transport, upstream
+ *   precedence and the include/exclude relationship. Checked against the
+ *   documentation skill: separate paragraphs state the contract and why its
+ *   nonobvious boundary matters; field comments retain their own useful
+ *   facts.
+ *
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Declares a shape only; it holds no state, handle or buffer.
+ *
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   Declares a shape only; there is no loop or processing in it.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Declares a shape only; it computes nothing to share.
+ *
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation
+ *   Carries project and upstream paths as strings; every path is resolved by the code that consumes it.
+ */
+export interface TtscMetroOptions extends TtscUnpluginOptions {
+  /**
+   * Explicit module path of the upstream Metro Babel transformer to delegate to
+   * after the ttsc pass.
+   *
+   * When omitted, `withTtsc` inherits the config's existing transformer unless
+   * it names this adapter. Without one it detects
+   * `@expo/metro-config/babel-transformer` first (Expo), then
+   * `@react-native/metro-babel-transformer`, then the legacy
+   * `metro-react-native-babel-transformer`.
+   */
+  upstreamTransformer?: string;
+
+  /**
+   * Substring patterns; when non-empty only files whose path contains one of
+   * them are run through the ttsc pass. Non-matching files are passed straight
+   * to the upstream transformer.
+   */
+  include?: string[];
+
+  /**
+   * Substring patterns; files whose path contains one of them skip the ttsc
+   * pass and go straight to the upstream transformer. Applied after
+   * {@link include}.
+   */
+  exclude?: string[];
+}
+
+/**
+ * Fully-resolved options, split into the ttsc-side overlay and Metro-side
+ * knobs.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   A structural interface separates the existing Unplugin overlay from
+ *   resolved Metro filters and the private run handshake.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   The ttsc member groups the forwarded overlay, while always-present filter
+ *   arrays remove optional-array handling from every worker delivery.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Its optional upstream/run identity and always-present arrays describe
+ *   worker state without executable branches or mutation.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   The native JSDoc explains the forwarded overlay, empty filter arrays,
+ *   optional upstream and private snapshot identity. Checked against the
+ *   documentation skill: separate paragraphs state the contract and why its
+ *   nonobvious boundary matters; field comments retain their own useful
+ *   facts.
+ *
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Declares a shape only; it holds no state, handle or buffer.
+ *
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   Declares a shape only; there is no loop or processing in it.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Declares a shape only; it computes nothing to share.
+ *
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation
+ *   Carries project and upstream paths as strings; every path is resolved by the code that consumes it.
+ */
+export interface ResolvedTtscMetroOptions {
+  /** Options forwarded verbatim to the `@ttsc/unplugin` transform core. */
+  ttsc: TtscUnpluginOptions;
+
+  /** Explicit upstream transformer module path, or `undefined` to auto-detect. */
+  upstreamTransformer?: string;
+
+  /** Resolved include patterns (never `undefined`). */
+  include: string[];
+
+  /** Resolved exclude patterns (never `undefined`). */
+  exclude: string[];
+
+  /** Private run identity shared by `getCacheKey` and Metro workers. */
+  snapshotRunId?: string;
+}