@ttsc/metro 0.30.4 → 0.31.0

package/README.md

@@ -39,11 +39,11 @@ const { withTtsc } = require("@ttsc/metro");
 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`).
+`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`). Those candidates, and a package name passed as `upstreamTransformer`, resolve from your project (`projectRoot`), so a transformer only the app installed is found even when the adapter itself lives outside the app's `node_modules`, as it does under pnpm or a linked workspace.
 
 If your config already set `transformer.babelTransformerPath`, that transformer is **chained rather than replaced**: the `ttsc` pass runs first and then delegates to it, so wrapping a working config keeps what it configured. This is what makes `react-native-svg-transformer`, whose entire installation is that one assignment, keep working after you adopt `@ttsc/metro`. Pass `upstreamTransformer` explicitly to override both that and auto-detection.
 
-The value is resolved from your `projectRoot`, exactly as Metro resolves it, so a relative `"./metro-svg.cjs"` and a bare `"react-native-svg-transformer"` both mean what they mean in your project rather than inside this package. A path that names `@ttsc/metro`'s own transformer is never chained in any spelling, including a second copy installed elsewhere in your tree, because delegating this transformer into itself would recurse on every file.
+The value is resolved from your `projectRoot`, exactly as Metro resolves it, so a relative `"./metro-svg.cjs"` and a bare `"react-native-svg-transformer"` both mean what they mean in your project rather than inside this package. A `babelTransformerPath` that names `@ttsc/metro`'s own transformer is never adopted as the upstream in any spelling, including a second copy installed elsewhere in your tree, because delegating this transformer into itself would recurse on every file. An explicit `upstreamTransformer` is taken as written, so it must not name this package.
 
 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, whether from a top-level throw, an incompatible runtime ABI, or a missing peer or 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.
 
@@ -65,7 +65,7 @@ module.exports = withTtsc(getDefaultConfig(__dirname), {
 - `compilerOptions`: a temporary overlay layered on the selected project config.
 - `plugins`: an explicit `ttsc` plugin list override, or `false` to disable project plugins.
 - `upstreamTransformer`: an explicit module path for the Babel transformer to delegate to, when neither the config's own transformer nor auto-detection is what you want.
-- `include` / `exclude`: substring patterns matched against the project-relative file path, selecting which files run through the `ttsc` pass (`.ts`/`.tsx`/`.cts`/`.mts` only; declaration and JavaScript files always pass straight through).
+- `include` / `exclude`: substring patterns matched against the project-relative file path, selecting which files run through the `ttsc` pass (`.ts`/`.tsx`/`.cts`/`.mts` only; declaration files, JavaScript files and anything below a `node_modules` directory always pass straight through).
 
 Options are forwarded from the Metro **config** process to Metro's **worker** processes through the `TTSC_METRO_OPTIONS` environment variable, so they must stay JSON-serialisable (hence substring patterns rather than `RegExp`).
 
@@ -75,6 +75,7 @@ For each TypeScript file Metro asks to transform:
 
 1. `@ttsc/metro` runs the `ttsc` plugin pass (reusing `@ttsc/unplugin`'s transform core) → transformed **TypeScript** source.
 2. The transformed source is handed to the upstream Expo/React-Native Babel transformer, which strips types, applies the RN transforms, and returns the Babel AST Metro consumes.
+3. The pass also returns a source map back to your text, and `@ttsc/metro` moves the returned AST's locations through it, so the map Metro builds from that AST, and every stack trace and breakpoint, points at the lines you wrote rather than at the transformed text.
 
 The plugin contract and `tsconfig` discovery match the Unplugin integrations. Metro's worker has no build-start callback, so its shared transform cache validates the complete project snapshot on every hit instead of using a build-scoped first-delivery shortcut.
 
@@ -90,16 +91,18 @@ should apply to it.
 
 This is not a build error. The file is simply not this project's to transform, and the usual cause is a Metro graph reaching past the `tsconfig`'s `include`, such as a source beside `src` rather than inside it or one in a sibling workspace folder. Add it to that project's `include` if `ttsc` plugins should apply to it.
 
-The report matters because passing through is not the same as leaving alone: a file that skips the `ttsc` pass keeps whatever plugin-driven syntax it carries, which fails at runtime rather than at build time. Declaration and JavaScript files never reach the pass at all, so they are not reported; they are filtered before it, as `include` / `exclude` above describes.
+The report matters because passing through is not the same as leaving alone: a file that skips the `ttsc` pass keeps whatever plugin-driven syntax it carries, which fails at runtime rather than at build time. Declaration files, JavaScript files and files below `node_modules` never reach the pass at all, so they are not reported; they are filtered before it, as `include` / `exclude` above describes.
 
 This is the shared core's answer rather than Metro's own, so every `@ttsc/unplugin` adapter gives the identical one. `@ttsc/metro` used to be alone in treating it as non-fatal while every adapter failed the build.
 
 ## Cache invalidation
 
-Metro keys its transform cache on each file's own content plus one static transformer key, and its babel-transformer contract has no per-file dependency registration. A `ttsc` transform can depend on a _type_ in another file, so `@ttsc/metro` folds a project fingerprint into that static key: every regular file reached by the project walk, every effective config source, and transform inputs recorded under `node_modules/.cache/ttsc-metro`. In a workspace with nested or directory-linked `tsconfig.json` projects, each lexical subtree is walked under the nearest config that transformed files use; the project-map traversal follows symlinks and Windows junctions while a physical ancestor set cuts cycles without collapsing independent aliases. The project map itself is hashed so adding or removing a nested or linked project config also changes the key. Worker discovery retains the exact candidate predicates that selected its project instead of reconstructing them after selection. A module passed through because its Program has no output still records those candidates and the universal config inputs that can later admit it. `withTtsc` gives each run a private identity, `getCacheKey` records the exact file state and static coverage that identity hashed, and workers compare every derived input's compiler-generation hash, realpath, or resolution predicate with that baseline. Inputs outside proven static coverage stay in one batched worker snapshot. A missing input, an out-of-root `watchFolders` project, a symlink or Windows junction transition, an `extends` change, or any A-to-B-to-A change between static keying and transformation taints the observation and rotates the next snapshot epoch, so it cannot collide with the earlier A key. Editing any fingerprinted input re-keys the next run, so `metro bundle` and dev-server starts pick up cross-file type changes without `--reset-cache`.
+Metro keys its transform cache on each file's own content plus one static transformer key, and its babel-transformer contract has no per-file dependency registration. A `ttsc` transform can depend on a _type_ in another file, so `@ttsc/metro` folds a project fingerprint into that static key: every file the project walk admits under the project's membership policy, every effective config source, and transform inputs recorded under `node_modules/.cache/ttsc-metro`. In a workspace with nested or directory-linked `tsconfig.json` projects, each lexical subtree is walked under the nearest config that transformed files use; the project-map traversal follows symlinks and Windows junctions while a physical ancestor set cuts cycles without collapsing independent aliases. The project map itself is hashed so adding or removing a nested or linked project config also changes the key. Worker discovery retains the exact candidate predicates that selected its project instead of reconstructing them after selection. A module passed through because its Program has no output still records those candidates and the universal config inputs that can later admit it. `withTtsc` gives each run a private identity, `getCacheKey` records the exact file state and static coverage that identity hashed, and workers compare every derived input's compiler-generation hash, realpath, or resolution predicate with that baseline. Inputs outside proven static coverage stay in one batched worker snapshot. A missing input, an out-of-root `watchFolders` project, a symlink or Windows junction transition, an `extends` change, or any A-to-B-to-A change between static keying and transformation taints the observation and rotates the next snapshot epoch, so it cannot collide with the earlier A key. Editing any fingerprinted input re-keys the next run, so `metro bundle` and dev-server starts pick up cross-file type changes without `--reset-cache`.
 
 Snapshot compaction is serialized across Metro config processes. If two builds prepare the same project cache at once, one compacts the shared worker documents and the contender uses a private non-reusable key for that run instead of racing the main snapshot rewrite.
 
+Upstream loading and cache-key errors remain nonfatal during key computation. They disable cross-run reuse through a nonce because the upstream contribution is unknown. An upstream without an optional `getCacheKey` callback still contributes no additional key. Loading failures propagate when Metro actually transforms a file.
+
 The granularity is project-level by necessity: Metro evaluates the transformer key once per run, so any fingerprinted change re-transforms every file on the next run. What remains outside the mechanism's reach:
 
 - **Within a running dev server**, Metro re-transforms only files its watcher reports changed. Editing a type in file B updates a dependent file A on A's next transform: save A, or restart the dev server (no `--reset-cache` needed).
@@ -108,7 +111,9 @@ The granularity is project-level by necessity: Metro evaluates the transformer k
 
 ## Caveats (v1)
 
-- **Cost model.** This release reuses `@ttsc/unplugin`'s transform core, which type-checks the whole `tsconfig` project and caches the result per process. Metro runs transforms in a multi-process worker pool, so the project is compiled once per worker (on that worker's first file). A resident, incremental, per-file compiler shared across workers is the planned optimization, tracked in [samchon/ttsc#255](https://github.com/samchon/ttsc/issues/255).
+- **Cost model.** This release reuses `@ttsc/unplugin`'s transform core, which type-checks the whole `tsconfig` project. Metro runs transforms in a multi-process worker pool, and the workers share each compile: `withTtsc` opens a session in the Metro process, and the first worker to need a project state compiles it while the others wait and adopt it, after proving it against their own filesystem. So a cold build and each edit compile the project once, not once per worker. The session's store lives under the system temporary directory, one per user, and outlives Metro: a restarted Metro's workers adopt what the last one compiled, after the same proof, and a compile is named by the ttsc, TypeScript-Go, and adapter versions it ran under. A resident, incremental, per-file compiler is the next step, tracked in [samchon/ttsc#255](https://github.com/samchon/ttsc/issues/255).
+- **Unobservable plugin inputs fail the build.** `@ttsc/metro` does not tell the shared core whether Metro is watching, so a compile whose plugin input observation is unavailable on the host fails the transform with an error naming that, rather than being cached.
+- **A stale compaction lock keeps the cache cold.** If the process that held `node_modules/.cache/ttsc-metro/snapshot-compaction.lock` died and its process id now belongs to a live process, every run takes a non-reusable key until that process exits or you delete the lock directory.
 - **Type errors fail the build.** The `ttsc` pass type-checks; a project type error surfaces as a Metro build error, matching the other `ttsc` bundler integrations.
 
 ## Sponsors

package/lib/core/SnapshotReadOperations.d.ts

@@ -0,0 +1,119 @@
+/**
+ * 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/lib/core/SnapshotReadOperations.js

@@ -0,0 +1,3 @@
+'use strict';
+
+//# sourceMappingURL=SnapshotReadOperations.js.map

package/lib/core/SnapshotReadOperations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SnapshotReadOperations.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;"}

package/lib/core/SnapshotReadOperations.mjs

@@ -0,0 +1,2 @@
+
+//# sourceMappingURL=SnapshotReadOperations.mjs.map

package/lib/core/SnapshotReadOperations.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"SnapshotReadOperations.mjs","sources":[],"sourcesContent":[],"names":[],"mappings":""}

package/lib/core/TtscMetroOptions.d.ts

@@ -0,0 +1,119 @@
+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;
+}

package/lib/core/TtscMetroOptions.js

@@ -0,0 +1,3 @@
+'use strict';
+
+//# sourceMappingURL=TtscMetroOptions.js.map

package/lib/core/TtscMetroOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TtscMetroOptions.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;"}

package/lib/core/TtscMetroOptions.mjs

@@ -0,0 +1,2 @@
+
+//# sourceMappingURL=TtscMetroOptions.mjs.map

package/lib/core/TtscMetroOptions.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"TtscMetroOptions.mjs","sources":[],"sourcesContent":[],"names":[],"mappings":""}

package/lib/core/TtscMetroProjectView.d.ts

@@ -0,0 +1,64 @@
+import type { TtscWatchInput, readProjectMembershipPolicy } from "@ttsc/unplugin/api";
+/**
+ * One project, and the membership policy that describes it.
+ *
+ * The recorder's question is whether the project walk already covers an input,
+ * so it needs both the walk's roots and the policy that walk used, and it is
+ * wrong exactly when those two describe different projects. Passing them
+ * separately made that mismatch expressible — the policy for one project
+ * alongside the root of another — and passing the policy alone made it
+ * expressible in a quieter way still, since a recorder that resolved its own
+ * could describe a different program than the walk hashed. Both halves travel
+ * together so neither can be supplied without the other (samchon/ttsc#1316).
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   A readonly structural interface carries the selected config, discovery
+ *   observations, membership policy and walk roots as one view.
+ *   resolveProjectView supplies that coherent view to the recorder instead of
+ *   independently resolving its parts.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   The view groups config, policy, roots and discovery observations so a
+ *   recorder receives one selected project rather than independently chosen
+ *   pieces. Readonly members prevent replacement through this interface.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The type does not structurally prohibit an inconsistent manually
+ *   constructed value; it introduces no executable branches, consumer
+ *   exceptions or foreign mutation.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   The native JSDoc explains each readonly field, one selected project and
+ *   the reason policy and roots travel together. 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 absolute paths chosen by the project resolver; it compares or normalizes none.
+ */
+export interface TtscMetroProjectView {
+    /** The base directory both fingerprint sides agree on. */
+    readonly base: string;
+    /** Config candidates observed while selecting this transform's project. */
+    readonly discoveryInputs: readonly TtscWatchInput[];
+    /** The caller's explicit `project`, if any. */
+    readonly explicitProject: string | undefined;
+    /** The membership policy resolved for that project. */
+    readonly policy: ReturnType<typeof readProjectMembershipPolicy>;
+    /** The policy used by the routed static walk. */
+    readonly walkPolicy: ReturnType<typeof readProjectMembershipPolicy>;
+    /** Lexical roots whose fingerprint uses this project's policy. */
+    readonly roots: readonly string[];
+    /** The exact config selected for this project. */
+    readonly tsconfig: string;
+}

package/lib/core/TtscMetroProjectView.js

@@ -0,0 +1,3 @@
+'use strict';
+
+//# sourceMappingURL=TtscMetroProjectView.js.map

package/lib/core/TtscMetroProjectView.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TtscMetroProjectView.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;"}

package/lib/core/TtscMetroProjectView.mjs

@@ -0,0 +1,2 @@
+
+//# sourceMappingURL=TtscMetroProjectView.mjs.map

package/lib/core/TtscMetroProjectView.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"TtscMetroProjectView.mjs","sources":[],"sourcesContent":[],"names":[],"mappings":""}

package/lib/core/UpstreamTransformer.d.ts

@@ -0,0 +1,127 @@
+/**
+ * The subset of the Metro Babel-transformer contract this adapter relies on.
+ *
+ * Metro loads the module named by `transformer.babelTransformerPath` and calls
+ * its `transform` once per file, expecting a Babel AST back. `getCacheKey` is
+ * an optional export Metro folds into its transform-cache key; Metro invokes it
+ * with arguments (e.g. `{ projectRoot, enableBabelRCLookup }`), so it is typed
+ * variadic.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   This structural interface describes Metro's Babel-transformer extension:
+ *   one transform operation and an optional variadic cache key. It does not
+ *   implement Babel, install peers or alter their exports. Concrete modules
+ *   supply the callbacks through normal Node loading.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   This peer-independent interface exposes only the transform and cache-key
+ *   callbacks the adapter invokes, avoiding a dependency on Metro's full API.
+ *
+ * @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 the awaited AST result and optional cache-key
+ *   callback including forwarded arguments. 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
+ *   Describes the callbacks of a Babel transformer; it names no path or process.
+ */
+export interface UpstreamTransformer {
+    /**
+     * Parse the supplied source and return the Babel AST Metro consumes.
+     *
+     * The adapter preserves Metro's filename, options and additional parameters;
+     * only `src` may hold successfully transformed TypeScript. The returned AST
+     * may have its locations remapped by the adapter before Metro receives it.
+     *
+     * @evidence contracts/common.md#principled-implementation
+     *   This method signature represents the upstream transformer that Metro
+     *   selected.
+     *
+     * @evidence contracts/common.md#clear-and-simple-design
+     *   One parameter record preserves Metro's extensible delivery shape and
+     *   the result exposes only the AST this adapter needs.
+     *
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts
+     *   It accepts the original Metro parameter record, with src replaced only by
+     *   the owning adapter after a successful compiler pass; the type declares no
+     *   implementation or test-specific branch.
+     *
+     * @evidence contracts/common.md#meaningful-documentation
+     *   The native JSDoc explains source, filename, extra Metro parameters and
+     *   the awaited Babel AST result. 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
+     *   The filename is Metro's own string, passed through to Babel unchanged.
+     */
+    transform(params: {
+        src: string;
+        filename: string;
+        options: Record<string, unknown>;
+        [key: string]: unknown;
+    }): Promise<{
+        ast: object;
+    }>;
+    /**
+     * Optional upstream contribution to Metro's static transformer key.
+     *
+     * Metro's arguments are forwarded unchanged. Absence contributes no upstream
+     * key; the adapter treats a throwing key as nonfatal and disables reuse,
+     * while transformer loading failures still fail actual transformation.
+     *
+     * @evidence contracts/common.md#principled-implementation
+     *   The optional callback follows Metro's upstream transformer contract.
+     *   Arguments are variadic because Metro supplies its own key options; absence
+     *   is handled by the adapter.
+     *
+     * @evidence contracts/common.md#clear-and-simple-design
+     *   An optional variadic callback expresses the one upstream contribution
+     *   without adapter-specific copies of Metro's cache-key options.
+     *
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts
+     *   This signature executes nothing and never replaces a foreign callback.
+     *
+     * @evidence contracts/common.md#meaningful-documentation
+     *   The native JSDoc explains optional absence, forwarded Metro arguments and
+     *   the upstream key contribution. 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
+     *   Metro's arguments are forwarded unchanged; no path is interpreted here.
+     */
+    getCacheKey?: (...args: unknown[]) => string;
+}

package/lib/core/UpstreamTransformer.js

@@ -0,0 +1,3 @@
+'use strict';
+
+//# sourceMappingURL=UpstreamTransformer.js.map

package/lib/core/UpstreamTransformer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"UpstreamTransformer.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;"}

package/lib/core/UpstreamTransformer.mjs

@@ -0,0 +1,2 @@
+
+//# sourceMappingURL=UpstreamTransformer.mjs.map

package/lib/core/UpstreamTransformer.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"UpstreamTransformer.mjs","sources":[],"sourcesContent":[],"names":[],"mappings":""}