@gjsify/rolldown-plugin-gjsify 0.43.0 → 0.45.0

package/lib/plugins/react-native-gate.js

@@ -0,0 +1,240 @@
+// The build-time half of ADR 0032 § 8's gate: fail the BUILD on an import of a
+// React Native name this layer does not answer for.
+//
+// § 8 makes `packages/framework/react-native/src/support-table.ts` the one source
+// three readers share — the bundler gate, the runtime refusals, and the generated
+// README. Two of the three existed. This is the first, and the only thing it has
+// over the runtime backstop is WHEN and WHERE: it names the importing file and
+// the line before anything runs, instead of throwing the first time a code path
+// is reached in a window. That is the whole point ADR 0032 states as the project
+// goal — "porting is cheap and every divergence is knowable at build time rather
+// than discoverable in a window".
+//
+// IT READS THE TABLE, NEVER A COPY. `@gjsify/react-native/support-table` is a
+// published subpath (`./lib/esm/support-table.js`) exporting `isImportable` and
+// `explainUnsupported`, and the plugin resolves it through the bundler's own
+// resolver and imports it. Reading the SOURCE the way `scripts/check-rn-surface.mjs`
+// does is not an option here: `files` on that package ships `lib` and not `src`,
+// so in a consumer's `node_modules` there is no `support-table.ts` to parse.
+//
+// WHAT THAT IMPORT DRAGS IN, measured on the built file rather than assumed: two
+// RELATIVE imports, rolldown's two-helper runtime shim and the generated
+// `own-exports.js`, which is a string array importing nothing. Relative is the half
+// that matters twice over — nothing reachable from here can pull GTK into the
+// bundler process, and GJS's ESM loader follows a relative specifier where it does
+// not follow `package.json#exports`. This comment used to claim "no imports at all",
+// which the runtime shim already disproved before the second one arrived.
+//
+// AND IT IS NOT A DEPENDENCY, deliberately. `@gjsify/rolldown-plugin-gjsify` is
+// tier 1 and `@gjsify/react-native` is tier 3; a tier-1 package may not depend on
+// a higher tier (`scripts/audit-runtimes.mjs`). Resolving the table from the
+// PROJECT is also the more correct answer than bundling a snapshot would be: the
+// gate then states exactly what the build's own copy of the layer supports, so a
+// version skew between plugin and layer cannot make the gate lie in either
+// direction.
+import { pathToFileURL } from 'node:url';
+import { REACT_NATIVE_ALIAS_TARGET, REACT_NATIVE_SPECIFIER } from './react-native-alias.js';
+import { REWRITE_FILTER } from './rewrite-node-modules-paths.js';
+import { ImportScanParseError, scanNamedImports, } from '../utils/scan-named-imports.js';
+/** The subpath that carries the table in an installed `@gjsify/react-native`. */
+export const SUPPORT_TABLE_SUBPATH = `${REACT_NATIVE_ALIAS_TARGET}/support-table`;
+/**
+ * Both spellings of the layer are watched.
+ *
+ * A ported application writes `react-native` (the alias rewrites it, and the
+ * rewrite happens in `resolveId` — the SOURCE text still says `react-native`
+ * when this hook reads it). A gjsify-native application, this repository's own
+ * showcase included, writes `@gjsify/react-native`. The gate is about the
+ * SURFACE, not about which name reached it.
+ */
+export const WATCHED_SPECIFIERS = [REACT_NATIVE_SPECIFIER, REACT_NATIVE_ALIAS_TARGET];
+/** Thrown for every refused import in one module, in one message. */
+export class ReactNativeUnsupportedImportError extends Error {
+    id;
+    violations;
+    name = 'ReactNativeUnsupportedImportError';
+    constructor(id, violations) {
+        super(formatSupportViolations(id, violations));
+        this.id = id;
+        this.violations = violations;
+    }
+}
+/** Thrown when the gate is on but the table it must read is not reachable. */
+export class SupportTableUnreadableError extends Error {
+    name = 'SupportTableUnreadableError';
+    constructor(detail, cause) {
+        super(`gjsify react-native gate: cannot read ${SUPPORT_TABLE_SUBPATH} — ${detail}. The gate has no ` +
+            `second source to fall back on, and ADR 0032 § 8 is explicit that a hand-maintained table ` +
+            `beside it would be the second truth this repository has already collected several times. ` +
+            `Install ${REACT_NATIVE_ALIAS_TARGET} (and build it, if it is a workspace link), or drop ` +
+            `the react-native opt-in.`, cause === undefined ? undefined : { cause });
+    }
+}
+/**
+ * All violations for one module as one message.
+ *
+ * One message and not one per name: an application that imports `FlatList`,
+ * `Animated` and `Image` from the same file has one porting decision to make,
+ * and three separate build failures would show it one third of that decision per
+ * run.
+ */
+export function formatSupportViolations(id, violations) {
+    const lines = violations.map((v) => `  ${id}:${v.line}:${v.column}  ${v.name}\n      ${v.reason}`);
+    return (`gjsify react-native gate: ${violations.length} import(s) this layer does not answer for:\n` +
+        `${lines.join('\n')}\n` +
+        `Each sentence above is the support table's own (ADR 0032 § 8), so it is the same reason the ` +
+        `runtime would give. A "not implemented yet" entry is where to contribute; a refusal names what ` +
+        `to write instead.`);
+}
+/** The refused subset of a scan, in the table's words. */
+export function findSupportViolations(named, table) {
+    const out = [];
+    for (const entry of named) {
+        if (table.isImportable(entry.name))
+            continue;
+        out.push({
+            name: entry.name,
+            specifier: entry.specifier,
+            line: entry.line,
+            column: entry.column,
+            // The table's sentence, never a rephrasing of it: `explainUnsupported`
+            // exists so the build error and the runtime throw cannot describe the
+            // same gap differently.
+            reason: table.explainUnsupported(entry.name),
+        });
+    }
+    return out;
+}
+/** The warning for a reference whose names the scan cannot see. */
+export function formatOpaqueReference(id, ref) {
+    const forms = {
+        namespace: 'a namespace import (`import * as …`)',
+        default: 'a default import',
+        'export-all': 'a star re-export (`export * from …`)',
+        'dynamic-import': 'a dynamic `import()`',
+        require: 'a `require()`',
+    };
+    return (`gjsify react-native gate: ${id}:${ref.line}:${ref.column} reaches "${ref.specifier}" through ` +
+        `${forms[ref.form]}, so the NAMES it uses are not knowable at build time and this gate cannot ` +
+        `check them. The runtime refusal still covers them — it reads the same table (ADR 0032 § 8) — but ` +
+        `it fires when the code path runs, not now. Import the names you use to move the answer back to ` +
+        `build time.`);
+}
+/**
+ * The warning for a module the parser could not read.
+ *
+ * A WARNING and not a build error, which is the one place this gate deliberately
+ * does not fail. `acorn-typescript` 1.4.13 cannot parse a `satisfies` expression
+ * or a `const` type parameter (measured; see `scan-named-imports.ts`), both of
+ * which are ordinary TypeScript in a tree pinned to `typescript: "^6.0.3"`.
+ * Erroring there would refuse a program that is correct, and this repository has
+ * already written down what that costs: "a false violation is how a checker
+ * teaches people to ignore it" (`check-rn-surface.mjs`). The shape used instead
+ * is the one that file also uses — degrade to the weaker half and SAY SO, out
+ * loud, per file, rather than degrade quietly.
+ */
+export function formatUnreadableModule(error) {
+    return (`${error.message} The build continues: the runtime refusal reads the same table (ADR 0032 § 8) and ` +
+        `still covers this module, but it fires when the code path runs rather than now.`);
+}
+/**
+ * Resolve and import the support table.
+ *
+ * `importer` is a module from the project being built, so the resolve lands in
+ * the PROJECT's dependency tree rather than the CLI's — the gate must describe
+ * the layer this bundle will actually contain.
+ */
+export async function loadSupportTable(resolver, importer, load = (href) => import(/* @vite-ignore */ href)) {
+    let resolved;
+    try {
+        resolved = await resolver.resolve(SUPPORT_TABLE_SUBPATH, importer);
+    }
+    catch (cause) {
+        throw new SupportTableUnreadableError(`the resolver threw for ${importer}`, cause);
+    }
+    if (!resolved)
+        throw new SupportTableUnreadableError(`it does not resolve from ${importer}`);
+    if (resolved.external) {
+        throw new SupportTableUnreadableError(`it resolved as EXTERNAL from ${importer}, so there is no file to read`);
+    }
+    let mod;
+    try {
+        // A file path, not the bare specifier: GJS's ESM loader does not follow
+        // `package.json#exports`, so the bare form works on Node and fails under
+        // the GJS engine — the same limitation the CLI's by-name plugin loader
+        // documents. The resolver already did the exports-map hop.
+        mod = await load(pathToFileURL(resolved.id).href);
+    }
+    catch (cause) {
+        throw new SupportTableUnreadableError(`importing ${resolved.id} failed`, cause);
+    }
+    const candidate = mod;
+    if (typeof candidate.isImportable !== 'function' || typeof candidate.explainUnsupported !== 'function') {
+        throw new SupportTableUnreadableError(`${resolved.id} does not export isImportable + explainUnsupported. ` +
+            `That is a version skew between the bundler plugin and the layer, not a missing install`);
+    }
+    return { isImportable: candidate.isImportable, explainUnsupported: candidate.explainUnsupported };
+}
+/**
+ * Fail the build on an import of a React Native name whose status is not
+ * `supported` or `partial`.
+ *
+ * A `transform` hook at `order: 'pre'`, which is what makes `import type` visible
+ * — by the time a normal-order hook runs, the annotations may already have been
+ * stripped, and the gate would then be unable to tell the five type-only imports
+ * ADR 0032 measured from five value imports. Same reason `deepkitPlugin` is
+ * composed as a prePlugin.
+ */
+export function reactNativeSupportGatePlugin(options = {}) {
+    let table = options.table;
+    return {
+        name: 'gjsify-react-native-gate',
+        transform: {
+            order: 'pre',
+            filter: { id: REWRITE_FILTER },
+            async handler(code, id) {
+                // Re-applied inside the handler, the way
+                // `nodeModulesPathRewritePlugin` does: the object-form `filter` is
+                // engine plumbing (under GJS `toNativePlugin` lifts `filter.id`
+                // into `@gjsify/rolldown-native`'s plugin-level `idFilter`), and a
+                // gate must not depend on plumbing to stay off `.css` / `.blp` /
+                // a data URL, all of which acorn would reject as invalid JS.
+                if (!REWRITE_FILTER.test(id))
+                    return null;
+                // Text prefilter before the parse, the same cheap gate
+                // `shouldInline` uses: both watched specifiers contain
+                // `react-native`, so one `includes` clears every module that has
+                // nothing to do with this layer.
+                if (!code.includes(REACT_NATIVE_SPECIFIER))
+                    return null;
+                // The ONE catch in this file, with a real throw path and a
+                // stated reason: `scanNamedImports` throws on syntax the pinned
+                // acorn-typescript cannot read, and the policy for that lives
+                // here rather than in the pure function — see
+                // {@link formatUnreadableModule}.
+                let scanned;
+                try {
+                    scanned = scanNamedImports(code, id, WATCHED_SPECIFIERS);
+                }
+                catch (error) {
+                    if (!(error instanceof ImportScanParseError))
+                        throw error;
+                    this.warn(formatUnreadableModule(error));
+                    return null;
+                }
+                const { named, opaque } = scanned;
+                if (named.length === 0 && opaque.length === 0)
+                    return null;
+                table ??= await loadSupportTable(this, id);
+                const violations = findSupportViolations(named, table);
+                if (violations.length > 0)
+                    throw new ReactNativeUnsupportedImportError(id, violations);
+                for (const ref of opaque)
+                    this.warn(formatOpaqueReference(id, ref));
+                // A gate, not a transform: the source is returned unchanged and
+                // the module goes on through the chain.
+                return null;
+            },
+        },
+    };
+}

package/lib/plugins/rn-route-manifest.d.ts

@@ -0,0 +1,67 @@
+import type { Plugin } from 'rolldown';
+/** The specifier an application imports. Overridable, because a name is a name. */
+export declare const RN_ROUTES_MODULE_ID = "virtual:gjsify-rn-routes";
+/**
+ * How deep the walk goes before it refuses.
+ *
+ * A LOUD limit rather than none: an unbounded walk turns a symlink cycle into a hang
+ * or an out-of-memory in the bundler, where the failure is not attributable to the
+ * directory that caused it. Ten levels is far past any real route tree — the measured
+ * application in ADR 0032 uses three — so hitting this is a finding, not a tuning
+ * problem, and the message says which path was at the bottom.
+ */
+export declare const MAX_ROUTE_DEPTH = 10;
+/** A file the walk found, relative to the routes directory. */
+export interface FoundRoute {
+    /** Path relative to the routes directory, with `/` separators. */
+    readonly contextKey: string;
+    /** Absolute path, for the generated import. */
+    readonly file: string;
+}
+export interface RnRouteManifestOptions {
+    /** The directory holding the route files — expo-router's `app/`. */
+    routesDir: string;
+    /** The specifier to answer. Defaults to `virtual:gjsify-rn-routes`. */
+    virtualId?: string;
+}
+/** The error this plugin refuses a build with. */
+export declare class RouteManifestError extends Error {
+    readonly name = "RouteManifestError";
+    constructor(message: string);
+}
+/**
+ * Every file under `root`, deepest last, sorted — WALKED, never globbed.
+ *
+ * A glob is blind to the first file that lands in a subdirectory it did not think to
+ * match, and going blind is the failure this plugin exists to remove: a route file
+ * nobody imports is a screen that is simply not there. Sorted in CODE-UNIT order so the
+ * emitted module is byte-identical for the same tree on every machine, which is what
+ * makes a build cache honest — see the comparator for what a locale-aware sort cost.
+ *
+ * Directories are walked and every FILE is reported, whatever its extension. Filtering
+ * here would be a silent drop with a plausible excuse — the router refuses a file that
+ * matches no convention BY NAME, and that message is the one a reader can act on.
+ */
+export declare function walkRoutes(root: string, depth?: number, prefix?: string): readonly FoundRoute[];
+/**
+ * The virtual module's source.
+ *
+ * Exported so a spec can assert the text rather than run a bundler for it, and so a
+ * consumer's own tooling can produce the same module for a different bundler.
+ *
+ * The generated imports use POSIX separators even on Windows, because a module
+ * specifier is not a path and a backslash in one is an escape.
+ */
+export declare function renderRouteManifest(routes: readonly FoundRoute[], routesDir: string): string;
+/**
+ * Serve the route manifest for `routesDir` as a virtual module.
+ *
+ * ```ts
+ * gjsifyPlugin({ … }),
+ * rnRouteManifestPlugin({ routesDir: 'app' }),
+ * ```
+ * ```ts
+ * import { manifest } from 'virtual:gjsify-rn-routes';
+ * ```
+ */
+export declare function rnRouteManifestPlugin(options: RnRouteManifestOptions): Plugin;

package/lib/plugins/rn-route-manifest.js

@@ -0,0 +1,166 @@
+// The file-based route manifest, as a virtual module.
+//
+// `expo-router` discovers its routes with Metro's `require.context`, which does not
+// exist in this chain and is not going to. What replaces it is this: walk a declared
+// directory, emit one module that STATICALLY imports every file in it, and let
+// `@gjsify/react-native/router` turn that list into a tree.
+//
+// WHERE THE SPLIT IS, AND WHY IT IS HERE. This plugin knows about a FILESYSTEM: which
+// directory, which files, whether the directory exists. It knows nothing about what a
+// name MEANS — `(group)`, `[param]`, `_layout` and `+not-found` are the router's
+// semantics, and `@gjsify/react-native/router`'s `buildRouteTree` owns them. That is
+// not tidiness: ADR 0032 § 12 says the build chain belongs to the consumer, so a
+// consumer on another bundler, or one writing the nine-line manifest by hand, has to
+// get the same refusals — and they only can if the conventions live in the package
+// they import rather than in the plugin they replaced. It also means there is ONE
+// parser; a copy here would be the second truth this repository keeps paying for.
+//
+// So the refusals below are exactly the ones a filesystem can produce, and each names
+// the resolved absolute path, because "routes directory not found" without the path it
+// looked for is the least useful build error there is.
+//
+// STATIC IMPORTS, NOT `() => import(…)`. A lazy route needs a Suspense boundary, and
+// `@gjsify/gtk-host/react`'s `render()` is synchronous by construction — a boundary
+// that suspends on the first commit leaves the container EMPTY and returns cleanly,
+// which is the silent-empty-window failure that host exists to refuse. A desktop
+// application also ships as one artifact (ADR 0024), so there is no download for
+// laziness to defer.
+import { readdirSync, statSync } from 'node:fs';
+import { posix, resolve, sep } from 'node:path';
+/** The specifier an application imports. Overridable, because a name is a name. */
+export const RN_ROUTES_MODULE_ID = 'virtual:gjsify-rn-routes';
+/**
+ * How deep the walk goes before it refuses.
+ *
+ * A LOUD limit rather than none: an unbounded walk turns a symlink cycle into a hang
+ * or an out-of-memory in the bundler, where the failure is not attributable to the
+ * directory that caused it. Ten levels is far past any real route tree — the measured
+ * application in ADR 0032 uses three — so hitting this is a finding, not a tuning
+ * problem, and the message says which path was at the bottom.
+ */
+export const MAX_ROUTE_DEPTH = 10;
+/** The error this plugin refuses a build with. */
+export class RouteManifestError extends Error {
+    name = 'RouteManifestError';
+    constructor(message) {
+        super(`@gjsify/rolldown-plugin-gjsify: rnRouteManifestPlugin — ${message}`);
+    }
+}
+/**
+ * Every file under `root`, deepest last, sorted — WALKED, never globbed.
+ *
+ * A glob is blind to the first file that lands in a subdirectory it did not think to
+ * match, and going blind is the failure this plugin exists to remove: a route file
+ * nobody imports is a screen that is simply not there. Sorted in CODE-UNIT order so the
+ * emitted module is byte-identical for the same tree on every machine, which is what
+ * makes a build cache honest — see the comparator for what a locale-aware sort cost.
+ *
+ * Directories are walked and every FILE is reported, whatever its extension. Filtering
+ * here would be a silent drop with a plausible excuse — the router refuses a file that
+ * matches no convention BY NAME, and that message is the one a reader can act on.
+ */
+export function walkRoutes(root, depth = 0, prefix = '') {
+    if (depth > MAX_ROUTE_DEPTH) {
+        throw new RouteManifestError(`the routes directory nests more than ${MAX_ROUTE_DEPTH} levels deep at "${prefix}". That is past any ` +
+            'real route tree, so this is almost certainly a symlink cycle — an unbounded walk would hang the ' +
+            'bundler instead of naming the path');
+    }
+    const entries = readdirSync(root, { withFileTypes: true });
+    const found = [];
+    // CODE-UNIT ORDER, NOT `localeCompare`. Measured: `localeCompare` put
+    // `_layout.tsx` before `README.md` here and `index.tsx` between them under ICU's
+    // default collation, which treats `_` as variable punctuation and letters
+    // case-insensitively — an order that depends on the machine's collation data. A
+    // build whose emitted module text depends on the host's locale is a build cache
+    // that misses for no reason, and a diff that appears on someone else's laptop.
+    for (const entry of [...entries].sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0)) {
+        const absolute = `${root}${sep}${entry.name}`;
+        const contextKey = prefix === '' ? entry.name : `${prefix}/${entry.name}`;
+        // `statSync` rather than the dirent's own kind, so a SYMLINK to a directory is
+        // walked like the directory it points at — which is what a monorepo doing
+        // route sharing produces, and `isDirectory()` on the dirent answers false for.
+        if (statSync(absolute).isDirectory())
+            found.push(...walkRoutes(absolute, depth + 1, contextKey));
+        else
+            found.push({ contextKey, file: absolute });
+    }
+    return found;
+}
+/**
+ * The virtual module's source.
+ *
+ * Exported so a spec can assert the text rather than run a bundler for it, and so a
+ * consumer's own tooling can produce the same module for a different bundler.
+ *
+ * The generated imports use POSIX separators even on Windows, because a module
+ * specifier is not a path and a backslash in one is an escape.
+ */
+export function renderRouteManifest(routes, routesDir) {
+    if (routes.length === 0) {
+        throw new RouteManifestError(`the routes directory "${routesDir}" holds no files, so there is nothing to route to. Add an ` +
+            '`index.tsx` and a `_layout.tsx` to it, or point `routesDir` at the directory that has them');
+    }
+    const lines = [
+        '// GENERATED by rnRouteManifestPlugin — do not edit, and do not commit.',
+        '//',
+        '// One static import per route file, and the manifest `@gjsify/react-native/router`',
+        `// takes. Walked from ${JSON.stringify(routesDir)}.`,
+        '',
+    ];
+    routes.forEach((route, index) => {
+        lines.push(`import * as route${index} from ${JSON.stringify(route.file.split(sep).join(posix.sep))};`);
+    });
+    lines.push('', 'export const manifest = [');
+    routes.forEach((route, index) => {
+        lines.push(`    { contextKey: ${JSON.stringify(route.contextKey)}, module: route${index} },`);
+    });
+    lines.push('];', '', 'export default manifest;', '');
+    return lines.join('\n');
+}
+/**
+ * Serve the route manifest for `routesDir` as a virtual module.
+ *
+ * ```ts
+ * gjsifyPlugin({ … }),
+ * rnRouteManifestPlugin({ routesDir: 'app' }),
+ * ```
+ * ```ts
+ * import { manifest } from 'virtual:gjsify-rn-routes';
+ * ```
+ */
+export function rnRouteManifestPlugin(options) {
+    const virtualId = options.virtualId ?? RN_ROUTES_MODULE_ID;
+    // `\0` is rollup's own convention for "this id is mine": it survives the resolver
+    // chain and makes any other plugin's path handling leave it alone.
+    const resolved = `\0${virtualId}`;
+    return {
+        name: 'gjsify-rn-route-manifest',
+        resolveId(source) {
+            return source === virtualId ? resolved : null;
+        },
+        load(id) {
+            if (id !== resolved)
+                return null;
+            const routesDir = resolve(options.routesDir);
+            let stats;
+            try {
+                stats = statSync(routesDir);
+            }
+            catch {
+                throw new RouteManifestError(`the routes directory "${routesDir}" does not exist. \`routesDir\` is resolved against the ` +
+                    'process working directory, so a relative path means something different when the ' +
+                    'bundler is spawned from elsewhere — pass an absolute one if that is in play');
+            }
+            if (!stats.isDirectory()) {
+                throw new RouteManifestError(`"${routesDir}" is a file, not a directory. \`routesDir\` names the directory that holds the route files`);
+            }
+            const routes = walkRoutes(routesDir);
+            // Every file becomes a WATCHED dependency, so adding a route file
+            // invalidates this module in a watch build. Without it a new screen needs a
+            // restart, which reads as "the router did not pick it up".
+            for (const route of routes)
+                this.addWatchFile(route.file);
+            return renderRouteManifest(routes, routesDir);
+        },
+    };
+}

package/lib/types/index.d.ts

@@ -1,3 +1,4 @@
+export * from './source-dialect.js';
 export * from './app.js';
 export * from './resolve-alias-options.js';
 export * from './plugin-options.js';

package/lib/types/index.js

@@ -1,3 +1,4 @@
+export * from './source-dialect.js';
 export * from './app.js';
 export * from './resolve-alias-options.js';
 export * from './plugin-options.js';

package/lib/types/plugin-options.d.ts

@@ -1,4 +1,5 @@
 import type { App } from './app.js';
+import type { SourceDialect } from './source-dialect.js';
 /** CSS handling forwarded to Rolldown / Lightning CSS. */
 export interface GjsifyCssOptions {
     /** Browserslist-compatible target list. Defaults to `['firefox60']` for `--app gjs`. */
@@ -67,6 +68,25 @@ export interface PluginOptions {
      * the wrapper. Defaults to `false`.
      */
     preserveDefaultExport?: boolean;
+    /**
+     * The dialect the SOURCE is written in (ADR 0032 § 2 + § 8), unset by default.
+     * `'react-native'` composes two plugins on the `gjs` and `node` targets:
+     *
+     *   1. the alias line `'react-native'` → `'@gjsify/react-native'`, so an
+     *      unmodified React Native application builds without a rename per file;
+     *   2. the build-time support gate, which fails on an import of a name whose
+     *      support-table status is not `supported` or `partial`.
+     *
+     * OPT-IN and never inferred. A tree with a phone leg has the real
+     * `react-native` installed on purpose, and redirecting the specifier for
+     * every build in it would change what that leg resolves; `@gjsify/react-native`
+     * is also tier 3 and optional, so an unconditional alias would fail builds
+     * that never asked for it. Full reasoning: `plugins/react-native-alias.ts`.
+     *
+     * This is the SOURCE dialect, never the target runtime — the two answer
+     * opposite questions and once shared a name. See `SourceDialect`.
+     */
+    dialect?: SourceDialect;
     /**
      * Where to look for a `@gjsify/*` the PROJECT cannot resolve, when the input is
      * TOOLCHAIN rather than user code: a file path inside the running CLI's own

package/lib/types/source-dialect.d.ts

@@ -0,0 +1,42 @@
+import type { App } from './app.js';
+/**
+ * The dialect the SOURCE is written in — not the runtime it is built for.
+ *
+ * Two vocabularies in this toolchain used to answer the same-sounding question
+ * with the same word, and they mean opposite directions:
+ *
+ *   `gjsify.runtimes['react-native']`  — this PACKAGE runs on React Native (Hermes)
+ *   `gjsify build --dialect react-native` — this SOURCE is a React Native app, being
+ *                                           built for GTK
+ *
+ * A package can truthfully be both: shipped to a phone through Metro AND ported to
+ * the desktop through this build. While the flag was also spelled `react-native`,
+ * those two true statements read as a contradiction, and a reader could reasonably
+ * expect a manifest declaring `react-native: 'none'` to fail a `--react-native`
+ * build. It never should — they are unrelated facts.
+ *
+ * So the closed runtime vocabulary keeps the name (it is the older, machine-checked
+ * one, parallel to `nativescript`), and the dialect is spelled as what it is. The
+ * type is a union rather than a boolean because NativeScript is the named follow-on:
+ * `--dialect nativescript` fits here without a second flag.
+ */
+export type SourceDialect = 'react-native';
+/** Every dialect this build understands, for CLI choices and error messages. */
+export declare const SOURCE_DIALECTS: readonly SourceDialect[];
+/** Whether `value` names a dialect this build understands. */
+export declare function isSourceDialect(value: unknown): value is SourceDialect;
+/**
+ * The `--app` targets that actually compose a dialect's plugins.
+ *
+ * Declared here rather than inferred, because it cannot be inferred: the
+ * composition happens in `app/gjs.ts` and `app/node.ts`, and a plugin only ever
+ * sees the target it was composed on — so nothing downstream can tell "this
+ * target has no dialect support" from "this dialect asked for nothing". The CLI
+ * refuses the pair up front instead, and this is the set it refuses against.
+ *
+ * KEEP IN STEP with the two composition sites. A third target that starts
+ * composing and is not added here gets a build refused for no reason; one added
+ * here without composing gets a flag accepted and silently ignored, which is the
+ * failure this set exists to prevent.
+ */
+export declare const DIALECT_APPS: ReadonlySet<App>;

package/lib/types/source-dialect.js

@@ -0,0 +1,21 @@
+/** Every dialect this build understands, for CLI choices and error messages. */
+export const SOURCE_DIALECTS = ['react-native'];
+/** Whether `value` names a dialect this build understands. */
+export function isSourceDialect(value) {
+    return typeof value === 'string' && SOURCE_DIALECTS.includes(value);
+}
+/**
+ * The `--app` targets that actually compose a dialect's plugins.
+ *
+ * Declared here rather than inferred, because it cannot be inferred: the
+ * composition happens in `app/gjs.ts` and `app/node.ts`, and a plugin only ever
+ * sees the target it was composed on — so nothing downstream can tell "this
+ * target has no dialect support" from "this dialect asked for nothing". The CLI
+ * refuses the pair up front instead, and this is the set it refuses against.
+ *
+ * KEEP IN STEP with the two composition sites. A third target that starts
+ * composing and is not added here gets a build refused for no reason; one added
+ * here without composing gets a flag accepted and silently ignored, which is the
+ * failure this set exists to prevent.
+ */
+export const DIALECT_APPS = new Set(['gjs', 'node']);

package/lib/utils/scan-named-imports.d.ts

@@ -0,0 +1,47 @@
+/** One named import (or re-export) of `name` from a watched package. */
+export interface NamedImport {
+    /** The name as the SOURCE module exports it, not the local alias. */
+    readonly name: string;
+    /** The verbatim specifier it came from. */
+    readonly specifier: string;
+    /** 1-based line, as acorn reports it. */
+    readonly line: number;
+    /** 0-based column, as acorn reports it. */
+    readonly column: number;
+}
+/** A reference to a watched package whose imported NAMES are not statically knowable. */
+export interface OpaqueReference {
+    /** Which form hid the names. */
+    readonly form: 'namespace' | 'default' | 'export-all' | 'dynamic-import' | 'require';
+    readonly specifier: string;
+    readonly line: number;
+    readonly column: number;
+}
+export interface ScanResult {
+    readonly named: readonly NamedImport[];
+    readonly opaque: readonly OpaqueReference[];
+}
+/** Raised when a module that mentions a watched package cannot be parsed. */
+export declare class ImportScanParseError extends Error {
+    readonly id: string;
+    readonly name = "ImportScanParseError";
+    constructor(id: string, cause: unknown);
+}
+/**
+ * Every named import and every opaque reference to one of `specifiers`.
+ *
+ * `specifiers` is matched EXACTLY. `react-native-web` and
+ * `react-native/Libraries/…` are different modules with different contracts, and
+ * a prefix match would fail a build over a package this layer never claimed —
+ * the deep-subpath case has its own named error in the alias plugin, where the
+ * importer is known and the message can say what to do.
+ *
+ * Type-only imports are absent from the result by construction. ADR 0032 counted
+ * five of them (`ViewProps`, `TextProps`, `PressableProps`, `LayoutChangeEvent`,
+ * `ColorValue`) in the measured application and recorded that they cost nothing:
+ * a type erases at build time and reaches no runtime, so a gate that failed on
+ * `import type { ViewProps }` would refuse a program that cannot fail.
+ *
+ * @throws {ImportScanParseError} when the source cannot be parsed.
+ */
+export declare function scanNamedImports(code: string, id: string, specifiers: readonly string[]): ScanResult;