@gjsify/rolldown-plugin-gjsify 0.45.0 → 0.47.0

package/lib/index.d.ts

@@ -26,9 +26,9 @@ export { platformResolvePlugin, nativescriptSuffixChain, desktopSuffixChain, des
 export type { PlatformResolvePluginOptions, NativescriptPlatform } from './plugins/platform-resolve.js';
 export { rnRouteManifestPlugin, renderRouteManifest, walkRoutes, RouteManifestError, RN_ROUTES_MODULE_ID, MAX_ROUTE_DEPTH, } from './plugins/rn-route-manifest.js';
 export type { RnRouteManifestOptions, FoundRoute } from './plugins/rn-route-manifest.js';
-export { reactNativeAliasPlugin, classifyReactNativeSpecifier, REACT_NATIVE_ALIAS_TARGET, REACT_NATIVE_SPECIFIER, ReactNativeDeepImportError, ReactNativeAliasTargetMissingError, } from './plugins/react-native-alias.js';
-export type { ReactNativeSpecifierKind } from './plugins/react-native-alias.js';
-export { reactNativeSupportGatePlugin, loadSupportTable, findSupportViolations, formatSupportViolations, formatOpaqueReference, formatUnreadableModule, SUPPORT_TABLE_SUBPATH, WATCHED_SPECIFIERS, ReactNativeUnsupportedImportError, SupportTableUnreadableError, } from './plugins/react-native-gate.js';
+export { reactNativeAliasPlugin, classifyReactNativeSpecifier, couldBeSurfaceSpecifier, loadLayer, FALLBACK_SURFACES, REACT_NATIVE_ALIAS_TARGET, REACT_NATIVE_SPECIFIER, ReactNativeDeepImportError, ReactNativeAliasTargetMissingError, SURFACE_MENTION, SURFACE_NAME_PREFIXES, } from './plugins/react-native-alias.js';
+export type { AliasedSurface, LayerReader, ReactNativeAliasOptions, ReactNativeSpecifierKind, } from './plugins/react-native-alias.js';
+export { reactNativeSupportGatePlugin, loadSupportTable, findSupportViolations, formatSupportViolations, formatOpaqueReference, formatUnreadableModule, SUPPORT_TABLE_SUBPATH, WATCHED_SPECIFIERS, watchedSpecifiers, ReactNativeUnsupportedImportError, SupportTableUnreadableError, } from './plugins/react-native-gate.js';
 export type { ReactNativeSupportGateOptions, SupportTableReader, SupportTableResolver, SupportViolation, } from './plugins/react-native-gate.js';
 export { scanNamedImports, ImportScanParseError } from './utils/scan-named-imports.js';
 export type { NamedImport, OpaqueReference, ScanResult } from './utils/scan-named-imports.js';

package/lib/index.js

@@ -16,8 +16,8 @@ export { unresolvedWorkspaceImportPlugin, classifyImport, isWorkspaceSpecifier,
 export { napiNodeAddonPlugin, resolveAddonPath, nearestPackageRoot, classifySpecifier, directNodeShim, nodeGypBuildShim, bindingsShim, napiRsShim, ADDON_FILTER_RE, isNapiRsPackageJson, isNapiRsSibling, isGjsifyNativeBridge, detectNapiRsEntry, hostNapiRsTriple, AddonNotBuiltError, } from './plugins/napi-node-addon.js';
 export { platformResolvePlugin, nativescriptSuffixChain, desktopSuffixChain, desktopOsSuffix, DESKTOP_OS_SUFFIXES, DESKTOP_REFUSED_SUFFIXES, PlatformVariantExternalError, detectNativescriptPlatform, nativescriptPlatformDefines, } from './plugins/platform-resolve.js';
 export { rnRouteManifestPlugin, renderRouteManifest, walkRoutes, RouteManifestError, RN_ROUTES_MODULE_ID, MAX_ROUTE_DEPTH, } from './plugins/rn-route-manifest.js';
-export { reactNativeAliasPlugin, classifyReactNativeSpecifier, REACT_NATIVE_ALIAS_TARGET, REACT_NATIVE_SPECIFIER, ReactNativeDeepImportError, ReactNativeAliasTargetMissingError, } from './plugins/react-native-alias.js';
-export { reactNativeSupportGatePlugin, loadSupportTable, findSupportViolations, formatSupportViolations, formatOpaqueReference, formatUnreadableModule, SUPPORT_TABLE_SUBPATH, WATCHED_SPECIFIERS, ReactNativeUnsupportedImportError, SupportTableUnreadableError, } from './plugins/react-native-gate.js';
+export { reactNativeAliasPlugin, classifyReactNativeSpecifier, couldBeSurfaceSpecifier, loadLayer, FALLBACK_SURFACES, REACT_NATIVE_ALIAS_TARGET, REACT_NATIVE_SPECIFIER, ReactNativeDeepImportError, ReactNativeAliasTargetMissingError, SURFACE_MENTION, SURFACE_NAME_PREFIXES, } from './plugins/react-native-alias.js';
+export { reactNativeSupportGatePlugin, loadSupportTable, findSupportViolations, formatSupportViolations, formatOpaqueReference, formatUnreadableModule, SUPPORT_TABLE_SUBPATH, WATCHED_SPECIFIERS, watchedSpecifiers, ReactNativeUnsupportedImportError, SupportTableUnreadableError, } from './plugins/react-native-gate.js';
 export { scanNamedImports, ImportScanParseError } from './utils/scan-named-imports.js';
 export * from './plugin.js';
 import { gjsifyPlugin } from './plugin.js';

package/lib/plugins/gjs-imports-empty.js

@@ -37,6 +37,21 @@ export function gjsImportsEmptyPlugin(options = {}) {
     const emptyGirs = options.emptyGirs ?? true;
     // When `@girs/*` is carved out, only `gi://*` reaches the empty redirect.
     const matcher = emptyGirs ? /^(@girs\/|gi:\/\/)/ : /^gi:\/\//;
+    // …with one subpath excluded on EVERY target, carve-out or not.
+    //
+    // `@girs/<ns>/vocabulary` is generated DATA — property names, signal names,
+    // enum nicks, versions (ADR 0029). It imports no `gi://`, binds no library and
+    // loads under plain Node; the reason it sits in `@girs` is that ts-for-gir
+    // generates it, not that it needs GJS. Emptying it produces
+    // `[MISSING_EXPORT] "PROVENANCE" is not exported by "\0gjsify-empty-gjs-import"`
+    // at bundle time, which reads like a missing export rather than a substituted
+    // module.
+    //
+    // The same over-broad assumption lived in `GIRS_VALUE_RE`
+    // (manifest-conformance), where it made gtk-host's honest `node: "polyfill"`
+    // read as runtime drift. Two tools, one rule: the package scope says who
+    // generated a file, the subpath says what it needs.
+    const isVocabulary = (source) => /^@girs\/[^/]+\/vocabulary$/.test(source);
     return {
         name: 'gjsify-gjs-imports-empty',
         resolveId: {
@@ -48,7 +63,7 @@ export function gjsImportsEmptyPlugin(options = {}) {
                 // matched specifiers; let everything else (including `@girs/*`
                 // when `emptyGirs` is false) fall through to the default
                 // resolver chain.
-                if (!matcher.test(source))
+                if (!matcher.test(source) || isVocabulary(source))
                     return null;
                 return { id: GJSIMPORTS_VIRTUAL_ID };
             },

package/lib/plugins/react-native-alias.d.ts

@@ -3,15 +3,43 @@ import type { Plugin } from 'rolldown';
 export declare const REACT_NATIVE_ALIAS_TARGET = "@gjsify/react-native";
 /** The specifier an unmodified React Native application writes. */
 export declare const REACT_NATIVE_SPECIFIER = "react-native";
+/**
+ * One npm package the layer answers for, and the specifier that answers it.
+ *
+ * ADR 0036 § 2: `react-native` and `expo-router` are the first two rows of a registry
+ * rather than two special cases, because a real React Native application imports
+ * sixteen more package names and every one of them used to fail at MODULE RESOLUTION —
+ * the bundler said npm could not find it, which names npm rather than this layer.
+ *
+ * READ FROM THE LAYER, never listed here. `@gjsify/react-native/support-table` exports
+ * the registry, the gate already imports that subpath to read the table, and a second
+ * list in the bundler plugin is the drift this whole arrangement exists to remove: the
+ * plugin would then alias a surface whose table it cannot see, or refuse one the layer
+ * has grown.
+ */
+export interface AliasedSurface {
+    readonly module: string;
+    readonly target: string;
+}
 /** What a specifier is, as far as this alias is concerned. */
 export type ReactNativeSpecifierKind = 
-/** Exactly `react-native` — the package root, which is the mirrored surface. */
+/** Exactly a declared surface's own npm name — the mirrored export surface. */
 {
     readonly kind: 'root';
+    readonly target: string;
 }
-/** `react-native/<subpath>` — internals, which are not mirrored. */
+/**
+ * `<a declared surface>/<subpath>` — internals, which are not mirrored.
+ *
+ * The MODULE and the TARGET come along because the refusal names them: `react-native`
+ * is no longer the only surface with a subpath layout below it, and
+ * `@expo/vector-icons/Ionicons` and `expo-router/entry` are both ordinary things a
+ * real application writes.
+ */
  | {
     readonly kind: 'subpath';
+    readonly module: string;
+    readonly target: string;
     readonly subpath: string;
 }
 /** Anything else, including `@gjsify/react-native` itself. */
@@ -29,7 +57,7 @@ export type ReactNativeSpecifierKind =
  * onto the mirror would replace a package that legitimately does not work with
  * one that silently does the wrong thing.
  */
-export declare function classifyReactNativeSpecifier(source: string): ReactNativeSpecifierKind;
+export declare function classifyReactNativeSpecifier(source: string, surfaces?: readonly AliasedSurface[]): ReactNativeSpecifierKind;
 /**
  * Thrown for `react-native/<subpath>` — an import of React Native's internals.
  *
@@ -43,21 +71,96 @@ export declare function classifyReactNativeSpecifier(source: string): ReactNativ
 export declare class ReactNativeDeepImportError extends Error {
     readonly specifier: string;
     readonly importer: string;
+    readonly module: string;
+    readonly target: string;
     readonly name = "ReactNativeDeepImportError";
-    constructor(specifier: string, importer: string);
+    constructor(specifier: string, importer: string, module?: string, target?: string);
 }
 /** Thrown when the alias target itself cannot be resolved. */
 export declare class ReactNativeAliasTargetMissingError extends Error {
+    readonly specifier: string;
+    readonly target: string;
     readonly importer: string;
     readonly name = "ReactNativeAliasTargetMissingError";
-    constructor(importer: string);
+    constructor(specifier: string, target: string, importer: string);
+}
+/** The subpath that carries the registry and the table in an installed layer. */
+export declare const SUPPORT_TABLE_SUBPATH = "@gjsify/react-native/support-table";
+/** The slice of the layer both plugins need, structurally so a spec can supply a fixture. */
+export interface LayerReader {
+    /** Every declared surface, in lookup order. */
+    readonly SURFACES: readonly AliasedSurface[];
+    /** May a build import this name from this module? */
+    isImportable(name: string, module?: string): boolean;
+    /** The one sentence a build error and a runtime throw both print. */
+    explainUnsupported(name: string, module?: string): string;
 }
+/** The resolver slice the loader needs, so it is testable without a bundler. */
+export interface SupportTableResolver {
+    resolve(specifier: string, importer: string): Promise<{
+        id: string;
+        external?: boolean | string;
+    } | null>;
+}
+/** Thrown when a plugin is on but the layer it must read is not reachable. */
+export declare class SupportTableUnreadableError extends Error {
+    readonly name = "SupportTableUnreadableError";
+    constructor(detail: string, cause?: unknown);
+}
+/**
+ * Resolve and import the layer's support-table subpath.
+ *
+ * `importer` is a module from the project being built, so the resolve lands in the
+ * PROJECT's dependency tree rather than the CLI's.
+ */
+export declare function loadLayer(resolver: SupportTableResolver, importer: string, load?: (href: string) => Promise<unknown>): Promise<LayerReader>;
 /**
- * Rewrite the bare `react-native` specifier onto `@gjsify/react-native`.
+ * The one row that is known WITHOUT reading the layer.
+ *
+ * Used when the layer cannot be read at all, and that is a deliberate degradation
+ * rather than a default. `gjsify build --dialect react-native` is an opt-in, so a
+ * consumer who asked for it and has no layer installed meant `react-native` — the one
+ * specifier whose name is a fact rather than a lookup — and that import gets the
+ * named "target does not resolve" error it always got. Every other surface then
+ * simply fails to resolve the way it did before ADR 0036, which is no worse than
+ * before and much better than every `resolveId` in the build throwing.
+ */
+export declare const FALLBACK_SURFACES: readonly AliasedSurface[];
+/**
+ * Rewrite a declared surface's specifier onto the subpath that answers it.
  *
  * `order: 'pre'` so the claim lands before the externals policy and the
  * substitution-table alias layer get a look — the same position
  * `platformResolvePlugin` holds, and for the same reason: a redirect that runs
  * after `externalsPlugin` would find the specifier already externalised.
  */
-export declare function reactNativeAliasPlugin(): Plugin;
+export interface ReactNativeAliasOptions {
+    /** The layer, when the caller already has it. Left unset in a real build. */
+    layer?: LayerReader;
+}
+export declare function reactNativeAliasPlugin(options?: ReactNativeAliasOptions): Plugin;
+/**
+ * The prefixes every declared surface's npm name starts with.
+ *
+ * A PREFILTER AND NOT A DECISION: the registry decides, and these exist only so the
+ * two hot paths — one `resolveId` per specifier in the build, one `transform` per
+ * module — can say "certainly not a surface" without resolving or parsing anything.
+ * `react-native-alias.spec.ts` asserts every row of the LAYER's own registry starts
+ * with one of them, so a surface named outside this list fails a test rather than
+ * being silently skipped by the alias and the gate together.
+ *
+ * `@gjsify/react-native` is here because a gjsify-native application writes the target
+ * directly, and the gate watches both spellings of every surface.
+ */
+export declare const SURFACE_NAME_PREFIXES: readonly string[];
+/** Could this specifier be a declared surface? Cheap, and deliberately over-inclusive. */
+export declare const couldBeSurfaceSpecifier: (specifier: string) => boolean;
+/**
+ * Does this SOURCE mention a specifier that could be a surface?
+ *
+ * Anchored on the opening QUOTE, which is the whole point: a bare `expo-` test over
+ * source text would match the word `export`, so the fragment has to sit where a module
+ * specifier sits. Over-inclusive by design (a string literal in a comment matches);
+ * under-inclusive never, which is the direction that matters for a gate.
+ */
+export declare const SURFACE_MENTION: RegExp;

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

@@ -29,6 +29,7 @@
 // unresolvable target is a named error rather than a silent external — the
 // substitution IS the promise, so its failure is the one thing that must not
 // exit 0.
+import { pathToFileURL } from 'node:url';
 /** The package whose export surface mirrors React Native's (ADR 0032 § 2). */
 export const REACT_NATIVE_ALIAS_TARGET = '@gjsify/react-native';
 /** The specifier an unmodified React Native application writes. */
@@ -44,11 +45,36 @@ export const REACT_NATIVE_SPECIFIER = 'react-native';
  * onto the mirror would replace a package that legitimately does not work with
  * one that silently does the wrong thing.
  */
-export function classifyReactNativeSpecifier(source) {
-    if (source === REACT_NATIVE_SPECIFIER)
-        return { kind: 'root' };
-    if (source.startsWith(`${REACT_NATIVE_SPECIFIER}/`)) {
-        return { kind: 'subpath', subpath: source.slice(REACT_NATIVE_SPECIFIER.length + 1) };
+export function classifyReactNativeSpecifier(source, surfaces = [{ module: REACT_NATIVE_SPECIFIER, target: REACT_NATIVE_ALIAS_TARGET }]) {
+    for (const surface of surfaces) {
+        if (source === surface.module)
+            return { kind: 'root', target: surface.target };
+    }
+    // A DEEP IMPORT is only a deep import of a surface this layer answers for. The
+    // exact-match loop above runs FIRST for the same reason it always did:
+    // `react-native-web`, `react-native-reanimated` and `react-native-svg` all start
+    // with the same eleven characters and none of them is `react-native`, so the
+    // prefix test has to come after every exact name — including the surface names
+    // `react-native-safe-area-context` and `react-native-gesture-handler`, which a
+    // prefix test on `react-native/` would not catch but a careless `react-native-`
+    // one would.
+    //
+    // EVERY SURFACE, not only `react-native`, and that gap was reachable from ordinary
+    // code: `@expo/vector-icons/Ionicons` is the spelling `@expo/vector-icons`' own
+    // documentation uses, and `expo-router/entry` is what an Expo application's
+    // `package.json#main` points at. Both classified as `other` before this, so the
+    // alias returned null and the build failed at MODULE RESOLUTION — npm's "cannot
+    // find package", which is the exact failure ADR 0036 exists to replace with a
+    // sentence.
+    for (const surface of surfaces) {
+        if (source.startsWith(`${surface.module}/`)) {
+            return {
+                kind: 'subpath',
+                module: surface.module,
+                target: surface.target,
+                subpath: source.slice(surface.module.length + 1),
+            };
+        }
     }
     return { kind: 'other' };
 }
@@ -65,64 +91,216 @@ export function classifyReactNativeSpecifier(source) {
 export class ReactNativeDeepImportError extends Error {
     specifier;
     importer;
+    module;
+    target;
     name = 'ReactNativeDeepImportError';
-    constructor(specifier, importer) {
-        super(`gjsify react-native alias: "${specifier}" (imported by ${importer}) reaches into React ` +
-            `Native's internals. The alias to ${REACT_NATIVE_ALIAS_TARGET} covers the PACKAGE ROOT, ` +
-            `because that is the export surface ADR 0032 § 2 mirrors; the subpath layout below it ` +
-            `belongs to Metro and the native bridge and has no counterpart here. Import the name from ` +
-            `"${REACT_NATIVE_SPECIFIER}" instead, or from "${REACT_NATIVE_ALIAS_TARGET}" directly if ` +
-            `it is a gjsify-only addition.`);
+    constructor(specifier, importer, module = REACT_NATIVE_SPECIFIER, target = REACT_NATIVE_ALIAS_TARGET) {
+        super(`gjsify react-native alias: "${specifier}" (imported by ${importer}) reaches into ` +
+            `"${module}"'s internals. The alias to ${target} covers the PACKAGE ROOT, because that is ` +
+            `the export surface ADR 0032 § 2 mirrors and ADR 0036 § 1 gives one subpath each; the ` +
+            `module layout below it has no counterpart here` +
+            (module === REACT_NATIVE_SPECIFIER
+                ? ` — react-native's own exists because of Metro and the native bridge`
+                : '') +
+            `. Import the name from "${module}" instead, or from "${target}" directly if it is a ` +
+            `gjsify-only addition.`);
         this.specifier = specifier;
         this.importer = importer;
+        this.module = module;
+        this.target = target;
     }
 }
 /** Thrown when the alias target itself cannot be resolved. */
 export class ReactNativeAliasTargetMissingError extends Error {
+    specifier;
+    target;
     importer;
     name = 'ReactNativeAliasTargetMissingError';
-    constructor(importer) {
-        super(`gjsify react-native alias: "${REACT_NATIVE_SPECIFIER}" (imported by ${importer}) is aliased ` +
-            `to ${REACT_NATIVE_ALIAS_TARGET}, which does not resolve from this project. Install it, or ` +
-            `drop the react-native opt-in. NOT falling back to the real react-native on purpose: it is ` +
-            `written for a React Native runtime, so the bundle would build and then fail in the window ` +
-            `on a NativeModules bridge that does not exist here.`);
+    constructor(specifier, target, importer) {
+        super(`gjsify react-native alias: "${specifier}" (imported by ${importer}) is aliased ` +
+            `to ${target}, which does not resolve from this project. Install ${REACT_NATIVE_ALIAS_TARGET} ` +
+            `(and build it, if it is a workspace link), or drop the react-native opt-in. NOT falling back ` +
+            `to the real package on purpose: it is written for a React Native runtime, so the bundle ` +
+            `would build and then fail in the window on a native module that does not exist here.`);
+        this.specifier = specifier;
+        this.target = target;
         this.importer = importer;
     }
 }
+// --- reading the layer (ADR 0036 § 2) ----------------------------------------
+//
+// BOTH PLUGINS READ THE LAYER, NEVER A COPY. `@gjsify/react-native/support-table` is
+// a published subpath exporting the surface registry plus `isImportable` and
+// `explainUnsupported`, and it is resolved through the BUNDLER's own resolver from a
+// module of the project being built — so the answer describes the layer this bundle
+// will actually contain, and a version skew between plugin and layer cannot make
+// either lie. Reading the SOURCE the way `scripts/check-rn-surface.mjs` does is not an
+// option here: `files` ships `lib` and not `src`, so a consumer's `node_modules` has
+// no `support-table.ts` to parse.
+//
+// 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`).
+/** The subpath that carries the registry and the table in an installed layer. */
+export const SUPPORT_TABLE_SUBPATH = `${REACT_NATIVE_ALIAS_TARGET}/support-table`;
+/** Thrown when a plugin is on but the layer 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 });
+    }
+}
+/**
+ * Resolve and import the layer's support-table subpath.
+ *
+ * `importer` is a module from the project being built, so the resolve lands in the
+ * PROJECT's dependency tree rather than the CLI's.
+ */
+export async function loadLayer(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' ||
+        !Array.isArray(candidate.SURFACES)) {
+        throw new SupportTableUnreadableError(`${resolved.id} does not export SURFACES + isImportable + explainUnsupported. ` +
+            `That is a version skew between the bundler plugin and the layer, not a missing install`);
+    }
+    return {
+        SURFACES: candidate.SURFACES,
+        isImportable: candidate.isImportable,
+        explainUnsupported: candidate.explainUnsupported,
+    };
+}
 /**
- * Rewrite the bare `react-native` specifier onto `@gjsify/react-native`.
+ * The one row that is known WITHOUT reading the layer.
  *
- * `order: 'pre'` so the claim lands before the externals policy and the
- * substitution-table alias layer get a look — the same position
- * `platformResolvePlugin` holds, and for the same reason: a redirect that runs
- * after `externalsPlugin` would find the specifier already externalised.
+ * Used when the layer cannot be read at all, and that is a deliberate degradation
+ * rather than a default. `gjsify build --dialect react-native` is an opt-in, so a
+ * consumer who asked for it and has no layer installed meant `react-native` — the one
+ * specifier whose name is a fact rather than a lookup — and that import gets the
+ * named "target does not resolve" error it always got. Every other surface then
+ * simply fails to resolve the way it did before ADR 0036, which is no worse than
+ * before and much better than every `resolveId` in the build throwing.
  */
-export function reactNativeAliasPlugin() {
+export const FALLBACK_SURFACES = [
+    { module: REACT_NATIVE_SPECIFIER, target: REACT_NATIVE_ALIAS_TARGET },
+];
+export function reactNativeAliasPlugin(options = {}) {
+    let surfaces = options.layer?.SURFACES ?? null;
+    let unreadable = false;
+    /**
+     * The registry, read once.
+     *
+     * A FAILURE IS CACHED TOO. Without that, a project without the layer installed
+     * would retry the resolve for every specifier in the build and throw from every
+     * one — including `node:fs`, which has nothing to do with this plugin.
+     * {@link FALLBACK_SURFACES} says what the degradation is and why it is the honest
+     * one.
+     */
+    const registry = async (context, importer) => {
+        if (surfaces !== null)
+            return surfaces;
+        if (unreadable)
+            return FALLBACK_SURFACES;
+        try {
+            surfaces = (await loadLayer(context, importer)).SURFACES;
+            return surfaces;
+        }
+        catch {
+            unreadable = true;
+            return FALLBACK_SURFACES;
+        }
+    };
     return {
         name: 'gjsify-react-native-alias',
         resolveId: {
             order: 'pre',
             async handler(source, importer, extraOptions) {
-                const classified = classifyReactNativeSpecifier(source);
-                if (classified.kind === 'other')
+                // A CHEAP PREFILTER BEFORE THE REGISTRY, because this hook runs for
+                // every specifier in the build and the registry needs a resolve.
+                // {@link SURFACE_NAME_PREFIXES} says why the list is a prefilter and
+                // what holds it against the layer's own rows.
+                if (!couldBeSurfaceSpecifier(source))
                     return null;
                 // An ENTRY has no importer to name; report the specifier itself
                 // rather than the string "undefined".
                 const from = importer ?? source;
-                if (classified.kind === 'subpath')
-                    throw new ReactNativeDeepImportError(source, from);
+                const classified = classifyReactNativeSpecifier(source, await registry(this, importer ?? source));
+                if (classified.kind === 'other')
+                    return null;
+                if (classified.kind === 'subpath') {
+                    throw new ReactNativeDeepImportError(source, from, classified.module, classified.target);
+                }
                 // `skipSelf: true` keeps the nested resolve out of this hook. The
-                // target is a plain package name, so the normal chain (workspace
-                // link, node_modules, the exports map) answers it.
-                const resolved = await this.resolve(REACT_NATIVE_ALIAS_TARGET, importer, {
+                // target is a plain package name plus a subpath, so the normal chain
+                // (workspace link, node_modules, the exports map) answers it.
+                const resolved = await this.resolve(classified.target, importer, {
                     skipSelf: true,
                     ...(extraOptions?.kind ? { kind: extraOptions.kind } : {}),
                 });
-                if (!resolved || resolved.external)
-                    throw new ReactNativeAliasTargetMissingError(from);
+                if (!resolved || resolved.external) {
+                    throw new ReactNativeAliasTargetMissingError(source, classified.target, from);
+                }
                 return resolved;
             },
         },
     };
 }
+/**
+ * The prefixes every declared surface's npm name starts with.
+ *
+ * A PREFILTER AND NOT A DECISION: the registry decides, and these exist only so the
+ * two hot paths — one `resolveId` per specifier in the build, one `transform` per
+ * module — can say "certainly not a surface" without resolving or parsing anything.
+ * `react-native-alias.spec.ts` asserts every row of the LAYER's own registry starts
+ * with one of them, so a surface named outside this list fails a test rather than
+ * being silently skipped by the alias and the gate together.
+ *
+ * `@gjsify/react-native` is here because a gjsify-native application writes the target
+ * directly, and the gate watches both spellings of every surface.
+ */
+export const SURFACE_NAME_PREFIXES = [
+    'react-native',
+    'expo-',
+    '@expo/',
+    '@react-native-',
+    'nativewind',
+    REACT_NATIVE_ALIAS_TARGET,
+];
+/** Could this specifier be a declared surface? Cheap, and deliberately over-inclusive. */
+export const couldBeSurfaceSpecifier = (specifier) => SURFACE_NAME_PREFIXES.some((prefix) => specifier.startsWith(prefix));
+/**
+ * Does this SOURCE mention a specifier that could be a surface?
+ *
+ * Anchored on the opening QUOTE, which is the whole point: a bare `expo-` test over
+ * source text would match the word `export`, so the fragment has to sit where a module
+ * specifier sits. Over-inclusive by design (a string literal in a comment matches);
+ * under-inclusive never, which is the direction that matters for a gate.
+ */
+export const SURFACE_MENTION = new RegExp(`['"\`](?:${SURFACE_NAME_PREFIXES.map((prefix) => prefix.replace(/[/@.]/g, '\\$&')).join('|')})`);

package/lib/plugins/react-native-gate.d.ts

@@ -1,36 +1,40 @@
 import type { Plugin } from 'rolldown';
+import { type AliasedSurface, type LayerReader } from './react-native-alias.js';
 import { ImportScanParseError, type NamedImport, type OpaqueReference } from '../utils/scan-named-imports.js';
 /**
- * The two functions the gate needs off the support table.
+ * What the gate needs off the layer, and it is now three things rather than two.
  *
- * Structural, so a spec can pass a three-row fixture and so the plugin never
- * types itself against a tier-3 package it must not import.
+ * `SURFACES` is the addition ADR 0036 makes: the gate has to know WHICH specifiers to
+ * watch, and that list is the layer's rather than the plugin's. A structural type, so
+ * a spec can pass a three-row fixture and so the plugin never types itself against a
+ * tier-3 package it must not import.
  */
-export interface SupportTableReader {
-    /**
-     * May a build import this name from the layer?
-     *
-     * TWO POPULATIONS, and the layer composes them — not this plugin. A React Native
-     * name is `supported` or `partial` in the support table; a name the layer ADDS
-     * (`configureStyle` and the rest of ADR 0032 § 3's token hooks) cannot be in that
-     * table at all, because `check-rn-surface.mjs` holds its key set EQUAL to
-     * react-native's own exports. A gate that asked only the first question refused
-     * the package's own documented API. A name in NEITHER is still false.
-     */
-    isImportable(name: string): boolean;
-    /** The one sentence the build error and the runtime throw both print. */
-    explainUnsupported(name: string): string;
-}
-/** The subpath that carries the table in an installed `@gjsify/react-native`. */
-export declare const SUPPORT_TABLE_SUBPATH = "@gjsify/react-native/support-table";
+export type SupportTableReader = LayerReader;
+export { SUPPORT_TABLE_SUBPATH, SupportTableUnreadableError } from './react-native-alias.js';
+export type { SupportTableResolver } from './react-native-alias.js';
+/**
+ * `loadLayer` under its historical name.
+ *
+ * Kept because it is a published export of `@gjsify/rolldown-plugin-gjsify`, and
+ * renaming a published function to say "surfaces" as well as "table" would be a
+ * breaking change for nothing — the loader reads one module either way.
+ */
+export { loadLayer as loadSupportTable } from './react-native-alias.js';
+/**
+ * Every specifier the gate watches, from the layer's own registry.
+ *
+ * BOTH SPELLINGS OF EACH SURFACE. A ported application writes `expo-status-bar` (the
+ * alias rewrites it, and the rewrite happens in `resolveId` — the SOURCE text still
+ * says `expo-status-bar` when this hook reads it). A gjsify-native application, this
+ * repository's own showcase included, writes `@gjsify/react-native/expo-status-bar`.
+ * The gate is about the SURFACE, not about which name reached it.
+ */
+export declare const watchedSpecifiers: (surfaces: readonly AliasedSurface[]) => readonly string[];
 /**
- * Both spellings of the layer are watched.
+ * The two specifiers that are known WITHOUT reading the layer.
  *
- * 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.
+ * Kept as a published constant because it was one, and it is now the FALLBACK rather
+ * than the whole list: `watchedSpecifiers(layer.SURFACES)` is what a real build uses.
  */
 export declare const WATCHED_SPECIFIERS: readonly string[];
 /** One refused import, with everything the message needs. */
@@ -49,11 +53,6 @@ export declare class ReactNativeUnsupportedImportError extends Error {
     readonly name = "ReactNativeUnsupportedImportError";
     constructor(id: string, violations: readonly SupportViolation[]);
 }
-/** Thrown when the gate is on but the table it must read is not reachable. */
-export declare class SupportTableUnreadableError extends Error {
-    readonly name = "SupportTableUnreadableError";
-    constructor(detail: string, cause?: unknown);
-}
 /**
  * All violations for one module as one message.
  *
@@ -81,21 +80,6 @@ export declare function formatOpaqueReference(id: string, ref: OpaqueReference):
  * loud, per file, rather than degrade quietly.
  */
 export declare function formatUnreadableModule(error: ImportScanParseError): string;
-/** The resolver slice this plugin needs, so `loadSupportTable` is testable. */
-export interface SupportTableResolver {
-    resolve(specifier: string, importer: string): Promise<{
-        id: string;
-        external?: boolean | string;
-    } | null>;
-}
-/**
- * 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 declare function loadSupportTable(resolver: SupportTableResolver, importer: string, load?: (href: string) => Promise<unknown>): Promise<SupportTableReader>;
 export interface ReactNativeSupportGateOptions {
     /**
      * The table, when the caller already has it. Left unset in a real build,

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

@@ -32,22 +32,35 @@
 // 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 { FALLBACK_SURFACES, SURFACE_MENTION, loadLayer, } 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`;
+export { SUPPORT_TABLE_SUBPATH, SupportTableUnreadableError } from './react-native-alias.js';
 /**
- * Both spellings of the layer are watched.
+ * `loadLayer` under its historical name.
  *
- * 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.
+ * Kept because it is a published export of `@gjsify/rolldown-plugin-gjsify`, and
+ * renaming a published function to say "surfaces" as well as "table" would be a
+ * breaking change for nothing — the loader reads one module either way.
  */
-export const WATCHED_SPECIFIERS = [REACT_NATIVE_SPECIFIER, REACT_NATIVE_ALIAS_TARGET];
+export { loadLayer as loadSupportTable } from './react-native-alias.js';
+/**
+ * Every specifier the gate watches, from the layer's own registry.
+ *
+ * BOTH SPELLINGS OF EACH SURFACE. A ported application writes `expo-status-bar` (the
+ * alias rewrites it, and the rewrite happens in `resolveId` — the SOURCE text still
+ * says `expo-status-bar` when this hook reads it). A gjsify-native application, this
+ * repository's own showcase included, writes `@gjsify/react-native/expo-status-bar`.
+ * The gate is about the SURFACE, not about which name reached it.
+ */
+export const watchedSpecifiers = (surfaces) => surfaces.flatMap((surface) => [surface.module, surface.target]);
+/**
+ * The two specifiers that are known WITHOUT reading the layer.
+ *
+ * Kept as a published constant because it was one, and it is now the FALLBACK rather
+ * than the whole list: `watchedSpecifiers(layer.SURFACES)` is what a real build uses.
+ */
+export const WATCHED_SPECIFIERS = watchedSpecifiers(FALLBACK_SURFACES);
 /** Thrown for every refused import in one module, in one message. */
 export class ReactNativeUnsupportedImportError extends Error {
     id;
@@ -59,17 +72,6 @@ export class ReactNativeUnsupportedImportError extends Error {
         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.
  *
@@ -79,7 +81,7 @@ export class SupportTableUnreadableError extends Error {
  * run.
  */
 export function formatSupportViolations(id, violations) {
-    const lines = violations.map((v) => `  ${id}:${v.line}:${v.column}  ${v.name}\n      ${v.reason}`);
+    const lines = violations.map((v) => `  ${id}:${v.line}:${v.column}  ${v.name} (from "${v.specifier}")\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 ` +
@@ -90,7 +92,13 @@ export function formatSupportViolations(id, violations) {
 export function findSupportViolations(named, table) {
     const out = [];
     for (const entry of named) {
-        if (table.isImportable(entry.name))
+        // THE SPECIFIER IS PASSED, and after ADR 0036 it is load-bearing rather than
+        // extra context: `StatusBar` is a `react-native` export AND the whole of
+        // `expo-status-bar`, `Image` is `react-native`'s and `expo-image`'s. Without
+        // the module the lookup answers from whichever surface the registry lists
+        // first, so `import { Image } from 'expo-image'` would report react-native's
+        // "is available" and the build would go green on a name nothing implements.
+        if (table.isImportable(entry.name, entry.specifier))
             continue;
         out.push({
             name: entry.name,
@@ -100,7 +108,7 @@ export function findSupportViolations(named, table) {
             // 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),
+            reason: table.explainUnsupported(entry.name, entry.specifier),
         });
     }
     return out;
@@ -137,44 +145,6 @@ 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`.
@@ -201,20 +171,27 @@ export function reactNativeSupportGatePlugin(options = {}) {
                 // 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))
+                // Text prefilter before the parse AND before the layer is read.
+                // ADR 0036 turned two watched specifiers into eighteen surfaces with
+                // two spellings each, and the list of those is the LAYER's — so the
+                // gate cannot know what to scan for until it has read it, and reading
+                // it on every module would make the one module that mentions a surface
+                // in a comment pay for the whole build. `SURFACE_MENTION` is anchored
+                // on the opening quote of a module specifier, which is why a bare
+                // `expo-` test is not enough: the word `export` contains it.
+                if (!SURFACE_MENTION.test(code))
                     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}.
+                // The layer FIRST, because its registry is what says which specifiers
+                // to scan for. The load is once per build and cached on the closure.
+                table ??= await loadLayer(this, id);
                 let scanned;
                 try {
-                    scanned = scanNamedImports(code, id, WATCHED_SPECIFIERS);
+                    scanned = scanNamedImports(code, id, watchedSpecifiers(table.SURFACES));
                 }
                 catch (error) {
                     if (!(error instanceof ImportScanParseError))
@@ -225,7 +202,6 @@ export function reactNativeSupportGatePlugin(options = {}) {
                 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);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/rolldown-plugin-gjsify",
-    "version": "0.45.0",
+    "version": "0.47.0",
     "description": "Rolldown / Rollup / Vite plugin orchestrator for GJS, Node, and Browser targets",
     "type": "module",
     "main": "lib/index.js",
@@ -60,11 +60,11 @@
     ],
     "license": "MIT",
     "dependencies": {
-        "@gjsify/console": "^0.45.0",
-        "@gjsify/resolve-npm": "^0.45.0",
-        "@gjsify/rolldown-plugin-deepkit": "^0.45.0",
-        "@gjsify/rolldown-plugin-pnp": "^0.45.0",
-        "@gjsify/vite-plugin-blueprint": "^0.45.0",
+        "@gjsify/console": "^0.47.0",
+        "@gjsify/resolve-npm": "^0.47.0",
+        "@gjsify/rolldown-plugin-deepkit": "^0.47.0",
+        "@gjsify/rolldown-plugin-pnp": "^0.47.0",
+        "@gjsify/vite-plugin-blueprint": "^0.47.0",
         "@rollup/pluginutils": "^5.4.0",
         "acorn": "^8.17.0",
         "acorn-typescript": "^1.4.13",
@@ -74,7 +74,7 @@
         "sass": "^1.101.0"
     },
     "peerDependencies": {
-        "@gjsify/lightningcss-native": "^0.45.0",
+        "@gjsify/lightningcss-native": "^0.47.0",
         "rolldown": "^1.1.4"
     },
     "peerDependenciesMeta": {
@@ -86,8 +86,8 @@
         }
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.45.0",
-        "@gjsify/unit": "^0.45.0",
+        "@gjsify/cli": "^0.47.0",
+        "@gjsify/unit": "^0.47.0",
         "@types/node": "^25.9.2",
         "rolldown": "^1.1.4",
         "typescript": "^6.0.3"