@gjsify/rolldown-plugin-gjsify 0.42.0 → 0.44.0

package/lib/plugins/platform-resolve.d.ts

@@ -1,19 +1,144 @@
 import type { Plugin } from 'rolldown';
 export type NativescriptPlatform = 'android' | 'ios' | 'visionos';
+/**
+ * The desktop suffix for one host OS, keyed by `process.platform`.
+ *
+ * TWO VOCABULARIES MEET HERE and neither is negotiable. The KEYS are
+ * `process.platform`'s (`linux`/`darwin`/`win32`) — ADR 0018's target set, the
+ * spelling `gjsify.os` and `gjsify.platforms` use, and what a running process
+ * computes about itself. The VALUES are React Native's `Platform.OS` spelling
+ * (`linux`/`macos`/`windows`), which is what ADR 0032 § 9 writes and what
+ * `@gjsify/react-native`'s own `Platform.OS` reports — so a `foo.macos.tsx`
+ * agrees with the `Platform.OS === 'macos'` branch beside it. Spelling the file
+ * `foo.darwin.tsx` would make those two disagree in the one place a reader looks
+ * to check them against each other.
+ *
+ * Exported so `platform-resolve.spec.ts` can iterate the real values instead of
+ * a copy: nothing in the type system stops someone adding a `web` row here, and
+ * that row is exactly what § 9 forbids.
+ */
+export declare const DESKTOP_OS_SUFFIXES: Readonly<Record<string, string>>;
+/**
+ * Suffixes that must NEVER be a rung of the DESKTOP chain, with § 9's reason.
+ *
+ * `.native` looks like an oversight and is the opposite: a `.native.tsx` is by
+ * definition written for a React Native runtime, so reaching for it would
+ * silently feed the GTK build code that expects `NativeModules` — a bridge that
+ * exists only in the phone host. No import error, no type error, no failing
+ * test; the divergence surfaces as a window that does not work. Falling through
+ * to the BASE file is the honest outcome, because the base file at least has to
+ * compile against what this target really has.
+ *
+ * `.web` is worse. It reads as the obvious pick for a desktop target — a desktop
+ * is not a phone, so surely the web variant? — and it carries exactly the DOM
+ * assumptions ADR 0032 rules out, the same two-lossy-mappings-stacked shape that
+ * rules out react-native-web over a DOM (§ 3, Rejected).
+ *
+ * Not silence, though: when the desktop chain falls through to base and one of
+ * these siblings exists, {@link platformResolvePlugin} warns naming the file.
+ * Without that, an author's fork is dead code with nothing anywhere saying so.
+ */
+export declare const DESKTOP_REFUSED_SUFFIXES: readonly string[];
+/**
+ * The NativeScript chain: platform-specific first, then the platform-agnostic
+ * `native` suffix. Without a known platform only `native` applies.
+ */
+export declare function nativescriptSuffixChain(platform?: NativescriptPlatform): readonly string[];
+/**
+ * The GTK/desktop chain (ADR 0032 § 9): `.gtk` → `.<os>` → `.desktop` → base.
+ *
+ * `.gtk` outranks the OS because a GTK fork is a statement about the TOOLKIT,
+ * which is the more specific claim: `foo.gtk.tsx` says "this is how the widget
+ * tree does it", `foo.linux.tsx` says "this is how this kernel does it", and a
+ * project holding both means the first on a GTK build.
+ *
+ * `os` is a suffix from {@link DESKTOP_OS_SUFFIXES}, never a `process.platform`
+ * token — see {@link desktopOsSuffix}. Omitting it drops the OS rung rather than
+ * guessing one.
+ */
+export declare function desktopSuffixChain(os?: string): readonly string[];
+/**
+ * The desktop suffix for the BUILD HOST, or `undefined` for a host outside
+ * ADR 0018's target set.
+ *
+ * The host, not a cross-target: there is no cross-OS desktop build in this chain
+ * (ADR 0032's Consequences put macOS and Windows on Node + `@gjsify/node-gi`,
+ * whose installable artifact is ADR 0024 stages 4 and 5 and does not exist yet).
+ * A future cross-build states its own suffix by passing one to
+ * {@link desktopSuffixChain}, which is why the decision function takes the value
+ * and only this one function reads the ambient.
+ *
+ * The ambient read is `process.platform` behind a defaulted parameter — the
+ * shape `extractPackageSpec` and `isAbsoluteFsPath` already use in this package.
+ * The canonical repo-wide spelling is `@gjsify/utils/core`'s `hostOs()`, and
+ * `os-axis.mjs` sanctions infra keeping its own raw read for the purity reason
+ * `cli/src/utils/platform-check.ts` documents. Here there is a second, harder
+ * reason: `@gjsify/utils` is BUILT BY the CLI this package is part of, so
+ * depending on it would make `build:infra` need its own output.
+ * `package.json#gjsify.os` on this package already carries the ADR 0018 claim.
+ */
+export declare function desktopOsSuffix(platform?: string): string | undefined;
 export interface PlatformResolvePluginOptions {
     /**
-     * Target platform. When omitted, only `.native.*` variants are tried
-     * (the platform-specific `.android.*` / `.ios.*` lookups are skipped).
+     * The suffix chain, most specific first. Build it with
+     * {@link nativescriptSuffixChain} or {@link desktopSuffixChain} — a
+     * hand-written array is a second resolution order the tree does not state.
+     */
+    suffixes: readonly string[];
+    /**
+     * Suffixes deliberately NOT resolved, but whose presence on disk is worth
+     * saying out loud: {@link DESKTOP_REFUSED_SUFFIXES} for the desktop chain,
+     * empty for NativeScript (where `.native` is a real rung). Probed only after
+     * the chain found nothing, so an empty list costs zero extra resolves and
+     * the NS path is byte-unchanged.
      */
-    platform?: NativescriptPlatform;
+    refusedSuffixes?: readonly string[];
+    /**
+     * Consult the importer's directory listing before entering the resolver.
+     *
+     * MEASURED, and the reason this option exists at all. The NativeScript chain
+     * runs on one build target; the desktop chain runs on every `--app gjs` and
+     * `--app node` build in the repository, and a three-rung chain costs up to
+     * six failed `this.resolve` calls per relative import. On this repository's
+     * largest bundle (`dist/cli.gjs.mjs`, ~1400 modules) that was 21.9–22.2 s
+     * without the plugin against 25.0–26.3 s with it — about +14%, and Rolldown
+     * reported the plugin as 49% of all plugin time. Skipping `node_modules`
+     * importers recovered under a second of it: the cost is FIRST-PARTY imports,
+     * which is exactly the population the feature is for.
+     *
+     * So the filter is a directory listing, cached per directory: one
+     * `readdirSync` answers every suffix for every import in that directory, and
+     * the resolver is entered only for a candidate that has a matching sibling.
+     * Same bundle, 22.0–22.8 s and 25% of plugin time — the surcharge is gone and
+     * the plugin now sits alongside its four siblings instead of ahead of them.
+     * The listing is a FILTER and never an answer — a directory it cannot read
+     * (a virtual importer id, a `\0`-prefixed module) falls straight through to
+     * the resolver, and names are compared lowercased so a case-insensitive
+     * filesystem can only make the filter more permissive, never less.
+     *
+     * OFF for NativeScript, deliberately: `@nativescript/core` ships
+     * `.android`/`.ios` siblings and imports them relatively, and the mandate on
+     * that chain is byte-identical behaviour — a filter that another plugin's
+     * virtual `resolveId` could see past is not something to switch on there
+     * without a measurement of that tree.
+     */
+    siblingIndex?: boolean;
+}
+/** Thrown when a variant is on disk but the resolver hands it back as external. */
+export declare class PlatformVariantExternalError extends Error {
+    readonly candidate: string;
+    readonly importer: string;
+    readonly name = "PlatformVariantExternalError";
+    constructor(candidate: string, importer: string);
 }
 /**
- * Resolve platform-specific source-file variants (`*.android` / `*.ios` /
- * `*.native`) ahead of the base file. Relative imports only — bare/package
- * specifiers are left to the normal resolver chain (package platform-`main`
- * fields are a separate, rarer concern handled by the alias layer).
+ * Resolve platform-specific source-file variants ahead of the base file.
+ *
+ * Relative imports only — bare/package specifiers are left to the normal
+ * resolver chain (package platform-`main` fields are a separate, rarer concern
+ * handled by the alias layer).
  */
-export declare function platformResolvePlugin(options?: PlatformResolvePluginOptions): Plugin;
+export declare function platformResolvePlugin(options: PlatformResolvePluginOptions): Plugin;
 /**
  * Best-effort detection of the NativeScript target platform from the
  * environment NS' CLI sets when it spawns a bundler (`NATIVESCRIPT_BUNDLER_ENV`

package/lib/plugins/platform-resolve.js

@@ -1,14 +1,20 @@
-// NativeScript / React-Native-style platform file resolution.
+// Platform file resolution — ONE plugin, ONE resolution order, two chains.
 //
-// Lets a shared codebase fork a single module per target platform by file
-// name — `foo.android.ts` / `foo.ios.ts` (platform-specific) or `foo.native.ts`
-// (any native platform, as opposed to the browser's `foo.ts`). An
+// Lets a shared codebase fork a single module per target by file name. An
 // `import './foo'` (or `import './foo.js'`) resolves to the most specific
-// variant that exists, in priority order:
+// variant on disk, in the priority order the caller's chain declares:
 //
-//   ./foo.<platform>.<ext>   (e.g. ./foo.android.ts) — when a platform is known
-//   ./foo.native.<ext>       — native-but-not-browser
-//   ./foo.<ext>              — the base file (default resolver fallthrough)
+//   NativeScript (`--app nativescript`)     GTK / desktop (`--app gjs|node`)
+//   ./foo.<android|ios|visionos>.<ext>      ./foo.gtk.<ext>
+//   ./foo.native.<ext>                      ./foo.<linux|macos|windows>.<ext>
+//   ./foo.<ext>                             ./foo.desktop.<ext>
+//                                           ./foo.<ext>
+//
+// TWO CHAINS, NOT TWO PLUGINS (ADR 0032 § 9). A second plugin would give the
+// tree two resolution orders that no single file states, and the order IS the
+// contract — `.gtk` before `.<os>` before `.desktop` is a decision, not an
+// implementation detail. So the chain is a PARAMETER and the builders below are
+// the only way to spell one.
 //
 // WHY THIS LIVES IN GJSIFY (not just a dependency on @nativescript/vite):
 // `@nativescript/vite` implements the same lookup as a Vite `resolve.alias`
@@ -17,13 +23,15 @@
 // 'ViteAlias' … function replacement into rust type String`), which breaks the
 // NS production build under Vite 8. Implemented here as a proper `resolveId`
 // plugin HOOK (not a `resolve.alias`), it works identically under Rolldown
-// (the `gjsify build --app nativescript` CLI) AND under Vite 7/8 (the
-// `gjsifyNativescript()` preset) — the function-alias limitation only affects
-// the `resolve.alias` config shorthand, not plugin `resolveId` hooks.
+// (the `gjsify build` CLI) AND under Vite 7/8 (the `gjsifyNativescript()`
+// preset) — the function-alias limitation only affects the `resolve.alias`
+// config shorthand, not plugin `resolveId` hooks.
 //
 // Reference: @nativescript/vite `helpers/package-platform-aliases.js`. Original
 // Copyright (c) NativeScript contributors, Apache-2.0. Reimplemented for the
 // gjsify Rolldown/Vite plugin pipeline.
+import { readdirSync } from 'node:fs';
+import { basename, dirname, resolve as resolvePath } from 'node:path';
 const PLATFORMS = ['android', 'ios', 'visionos'];
 // JS/TS extensions a source specifier may carry. Stripped so the platform
 // suffix lands BEFORE the extension (`./foo.js` → `./foo.android`).
@@ -32,18 +40,162 @@ function isPlatform(value) {
     return PLATFORMS.includes(value);
 }
 /**
- * Resolve platform-specific source-file variants (`*.android` / `*.ios` /
- * `*.native`) ahead of the base file. Relative imports only — bare/package
- * specifiers are left to the normal resolver chain (package platform-`main`
- * fields are a separate, rarer concern handled by the alias layer).
+ * The desktop suffix for one host OS, keyed by `process.platform`.
+ *
+ * TWO VOCABULARIES MEET HERE and neither is negotiable. The KEYS are
+ * `process.platform`'s (`linux`/`darwin`/`win32`) — ADR 0018's target set, the
+ * spelling `gjsify.os` and `gjsify.platforms` use, and what a running process
+ * computes about itself. The VALUES are React Native's `Platform.OS` spelling
+ * (`linux`/`macos`/`windows`), which is what ADR 0032 § 9 writes and what
+ * `@gjsify/react-native`'s own `Platform.OS` reports — so a `foo.macos.tsx`
+ * agrees with the `Platform.OS === 'macos'` branch beside it. Spelling the file
+ * `foo.darwin.tsx` would make those two disagree in the one place a reader looks
+ * to check them against each other.
+ *
+ * Exported so `platform-resolve.spec.ts` can iterate the real values instead of
+ * a copy: nothing in the type system stops someone adding a `web` row here, and
+ * that row is exactly what § 9 forbids.
+ */
+export const DESKTOP_OS_SUFFIXES = {
+    linux: 'linux',
+    darwin: 'macos',
+    win32: 'windows',
+};
+/**
+ * Suffixes that must NEVER be a rung of the DESKTOP chain, with § 9's reason.
+ *
+ * `.native` looks like an oversight and is the opposite: a `.native.tsx` is by
+ * definition written for a React Native runtime, so reaching for it would
+ * silently feed the GTK build code that expects `NativeModules` — a bridge that
+ * exists only in the phone host. No import error, no type error, no failing
+ * test; the divergence surfaces as a window that does not work. Falling through
+ * to the BASE file is the honest outcome, because the base file at least has to
+ * compile against what this target really has.
+ *
+ * `.web` is worse. It reads as the obvious pick for a desktop target — a desktop
+ * is not a phone, so surely the web variant? — and it carries exactly the DOM
+ * assumptions ADR 0032 rules out, the same two-lossy-mappings-stacked shape that
+ * rules out react-native-web over a DOM (§ 3, Rejected).
+ *
+ * Not silence, though: when the desktop chain falls through to base and one of
+ * these siblings exists, {@link platformResolvePlugin} warns naming the file.
+ * Without that, an author's fork is dead code with nothing anywhere saying so.
+ */
+export const DESKTOP_REFUSED_SUFFIXES = ['native', 'web'];
+/**
+ * The NativeScript chain: platform-specific first, then the platform-agnostic
+ * `native` suffix. Without a known platform only `native` applies.
+ */
+export function nativescriptSuffixChain(platform) {
+    return platform ? [platform, 'native'] : ['native'];
+}
+/**
+ * The GTK/desktop chain (ADR 0032 § 9): `.gtk` → `.<os>` → `.desktop` → base.
+ *
+ * `.gtk` outranks the OS because a GTK fork is a statement about the TOOLKIT,
+ * which is the more specific claim: `foo.gtk.tsx` says "this is how the widget
+ * tree does it", `foo.linux.tsx` says "this is how this kernel does it", and a
+ * project holding both means the first on a GTK build.
+ *
+ * `os` is a suffix from {@link DESKTOP_OS_SUFFIXES}, never a `process.platform`
+ * token — see {@link desktopOsSuffix}. Omitting it drops the OS rung rather than
+ * guessing one.
+ */
+export function desktopSuffixChain(os) {
+    return os ? ['gtk', os, 'desktop'] : ['gtk', 'desktop'];
+}
+/**
+ * The desktop suffix for the BUILD HOST, or `undefined` for a host outside
+ * ADR 0018's target set.
+ *
+ * The host, not a cross-target: there is no cross-OS desktop build in this chain
+ * (ADR 0032's Consequences put macOS and Windows on Node + `@gjsify/node-gi`,
+ * whose installable artifact is ADR 0024 stages 4 and 5 and does not exist yet).
+ * A future cross-build states its own suffix by passing one to
+ * {@link desktopSuffixChain}, which is why the decision function takes the value
+ * and only this one function reads the ambient.
+ *
+ * The ambient read is `process.platform` behind a defaulted parameter — the
+ * shape `extractPackageSpec` and `isAbsoluteFsPath` already use in this package.
+ * The canonical repo-wide spelling is `@gjsify/utils/core`'s `hostOs()`, and
+ * `os-axis.mjs` sanctions infra keeping its own raw read for the purity reason
+ * `cli/src/utils/platform-check.ts` documents. Here there is a second, harder
+ * reason: `@gjsify/utils` is BUILT BY the CLI this package is part of, so
+ * depending on it would make `build:infra` need its own output.
+ * `package.json#gjsify.os` on this package already carries the ADR 0018 claim.
  */
-export function platformResolvePlugin(options = {}) {
-    const platform = options.platform;
-    // Priority: platform-specific suffix first, then the platform-agnostic
-    // `native` suffix. Without a known platform, only `native` applies.
-    const suffixes = platform ? [platform, 'native'] : ['native'];
+export function desktopOsSuffix(platform = process.platform) {
+    return DESKTOP_OS_SUFFIXES[platform];
+}
+/** Thrown when a variant is on disk but the resolver hands it back as external. */
+export class PlatformVariantExternalError extends Error {
+    candidate;
+    importer;
+    name = 'PlatformVariantExternalError';
+    constructor(candidate, importer) {
+        super(`gjsify platform resolve: "${candidate}" (imported by ${importer}) resolved to an EXTERNAL id, ` +
+            `so the platform fork cannot be bundled. A platform variant is first-party source by ` +
+            `construction — it is a sibling file — so an externals pattern or a user --external is ` +
+            `claiming it. Narrow that pattern, or rename the variant.`);
+        this.candidate = candidate;
+        this.importer = importer;
+    }
+}
+/**
+ * Resolve platform-specific source-file variants ahead of the base file.
+ *
+ * Relative imports only — bare/package specifiers are left to the normal
+ * resolver chain (package platform-`main` fields are a separate, rarer concern
+ * handled by the alias layer).
+ */
+export function platformResolvePlugin(options) {
+    const suffixes = options.suffixes;
+    if (suffixes.length === 0) {
+        // A caller meaning "no platform forks" composes no plugin at all. An
+        // EMPTY chain is one that was computed and came out empty — the shape a
+        // mis-wired orchestrator has — and it would send every import to base
+        // while looking installed.
+        throw new Error('gjsify platform resolve: the suffix chain is empty. Pass nativescriptSuffixChain(…) or ' +
+            'desktopSuffixChain(…), or omit the plugin.');
+    }
+    const refused = options.refusedSuffixes ?? [];
+    const useIndex = options.siblingIndex ?? false;
+    // Per-directory listing cache, lowercased. `null` marks a directory that
+    // could not be read, which means "no opinion" — the resolver decides.
+    const listings = new Map();
+    const listingFor = (dir) => {
+        const cached = listings.get(dir);
+        if (cached !== undefined)
+            return cached;
+        let entries;
+        try {
+            entries = new Set(readdirSync(dir).map((name) => name.toLowerCase()));
+        }
+        catch {
+            // An unreadable directory is the normal case for a virtual importer
+            // id, not an error worth reporting: the resolver still gets asked.
+            entries = null;
+        }
+        listings.set(dir, entries);
+        return entries;
+    };
+    /** Could a `<stem>.<suffix>` sibling exist in `dir`? A file OR a directory. */
+    const hasSibling = (entries, stem, suffix) => {
+        const name = `${stem}.${suffix}`.toLowerCase();
+        if (entries.has(name))
+            return true;
+        for (const entry of entries) {
+            if (entry.startsWith(`${name}.`))
+                return true;
+        }
+        return false;
+    };
+    // One warning per resolved variant id, not per import site: a shared module
+    // reached from twenty files would print twenty identical lines and train the
+    // reader to skip them.
+    const warned = new Set();
     return {
-        name: 'gjsify-nativescript-platform-resolve',
+        name: 'gjsify-platform-resolve',
         resolveId: {
             order: 'pre',
             async handler(source, importer, extraOptions) {
@@ -55,7 +207,23 @@ export function platformResolvePlugin(options = {}) {
                 const extMatch = KNOWN_EXT_RE.exec(source);
                 const origExt = extMatch ? extMatch[0] : '';
                 const base = origExt ? source.slice(0, -origExt.length) : source;
+                const kind = extraOptions?.kind ? { kind: extraOptions.kind } : {};
+                // The filter, only when the caller asked for it — the NS path does
+                // not even resolve the sibling directory. `null` = no opinion.
+                let entries = null;
+                let stem = '';
+                if (useIndex) {
+                    const target = resolvePath(dirname(importer), base);
+                    entries = listingFor(dirname(target));
+                    stem = basename(target);
+                }
+                const worthProbing = (suffix) => entries === null || hasSibling(entries, stem, suffix);
+                // `skipSelf: true` re-runs the resolver chain WITHOUT this
+                // plugin → no recursion on the nested resolve.
+                const tryResolve = (candidate) => this.resolve(candidate, importer, { skipSelf: true, ...kind });
                 for (const suffix of suffixes) {
+                    if (!worthProbing(suffix))
+                        continue;
                     // Try the bare form first (the resolver extension-probes,
                     // so `./foo.android` finds `./foo.android.ts`), then the
                     // extension-preserving form as a fallback.
@@ -65,17 +233,33 @@ export function platformResolvePlugin(options = {}) {
                     for (const candidate of candidates) {
                         if (candidate === source)
                             continue;
-                        // `skipSelf: true` re-runs the resolver chain WITHOUT
-                        // this plugin → no recursion on the nested resolve.
-                        const resolved = await this.resolve(candidate, importer, {
-                            skipSelf: true,
-                            ...(extraOptions?.kind ? { kind: extraOptions.kind } : {}),
-                        });
-                        if (resolved && !resolved.external)
-                            return resolved;
+                        const resolved = await tryResolve(candidate);
+                        if (!resolved)
+                            continue;
+                        // An external variant is NOT a miss to walk past: the
+                        // file is there and the author expects it in the bundle.
+                        if (resolved.external)
+                            throw new PlatformVariantExternalError(candidate, importer);
+                        return resolved;
                     }
                 }
-                // No variant on disk → let the default chain resolve the base.
+                // No variant on disk → the default chain resolves the base. Say
+                // so when a REFUSED sibling exists: § 9 wants the fall-through,
+                // not the silence around it.
+                for (const suffix of refused) {
+                    if (!worthProbing(suffix))
+                        continue;
+                    const probe = await tryResolve(`${base}.${suffix}`);
+                    if (!probe || warned.has(probe.id))
+                        continue;
+                    warned.add(probe.id);
+                    this.warn(`gjsify platform resolve: "${base}.${suffix}" exists but is NOT a rung of this ` +
+                        `target's chain (${suffixes.join(' → ')} → base), so ${importer} gets the base ` +
+                        `file. ADR 0032 § 9: a .${suffix} variant is written for a runtime this build ` +
+                        `is not, and reaching for it would hand this target code whose failure only ` +
+                        `shows up on screen. Move what applies here into a .${suffixes[0]} or ` +
+                        `.desktop variant.`);
+                }
                 return null;
             },
         },

package/lib/plugins/process-stub.js

@@ -1,4 +1,5 @@
 import { BUNDLE_URL_BANNER } from './bundle-url-banner.js';
+import { GJS_INTL_SEGMENTER_STUB } from './intl-segmenter-banner.js';
 import { GJS_WELLKNOWN_SYMBOLS_STUB } from './wellknown-symbols-banner.js';
 import { giRuntimePathsStub } from './gi-runtime-paths.js';
 // Every GJS ambient global is reached through `globalThis.` — NEVER as a bare
@@ -84,6 +85,9 @@ export function processStubPlugin(options = {}) {
     // is single-line and idempotent.
     const stub = (options.captureBundleUrl ? BUNDLE_URL_BANNER : '') +
         GJS_WELLKNOWN_SYMBOLS_STUB +
+        // Before the process stub and before module init: `get-east-asian-width`
+        // constructs a Segmenter at module scope, so a later injection is too late.
+        GJS_INTL_SEGMENTER_STUB +
         GJS_PROCESS_STUB +
         giRuntimePathsStub(options.giRuntimePaths ?? [], options.giSystemProbes ?? []);
     const banner = composeBanner(stub, options.userBanner ?? '');

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

@@ -0,0 +1,63 @@
+import type { Plugin } from 'rolldown';
+/** The package whose export surface mirrors React Native's (ADR 0032 § 2). */
+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";
+/** 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. */
+{
+    readonly kind: 'root';
+}
+/** `react-native/<subpath>` — internals, which are not mirrored. */
+ | {
+    readonly kind: 'subpath';
+    readonly subpath: string;
+}
+/** Anything else, including `@gjsify/react-native` itself. */
+ | {
+    readonly kind: 'other';
+};
+/**
+ * Classify an import specifier.
+ *
+ * EXACT match on the root, never a prefix: `react-native-web`,
+ * `react-native-reanimated` and `react-native-gesture-handler` all start with
+ * the same eleven characters and none of them is this package. ADR 0032 records
+ * the last two as `not-reachable` (they need a Babel worklet transform that is
+ * not in this chain) and the first as rejected by design; aliasing any of them
+ * 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;
+/**
+ * Thrown for `react-native/<subpath>` — an import of React Native's internals.
+ *
+ * The alias rests on the export SURFACE being mirrored (§ 2), and a subpath is
+ * by definition not part of that surface: `react-native/Libraries/Components/…`
+ * reaches into a module layout that exists because of Metro and the native
+ * bridge. There is nothing to map it to and nothing honest to stub it with, so
+ * the build says so with the importer named rather than resolving to the real
+ * React Native source and failing later on `NativeModules`.
+ */
+export declare class ReactNativeDeepImportError extends Error {
+    readonly specifier: string;
+    readonly importer: string;
+    readonly name = "ReactNativeDeepImportError";
+    constructor(specifier: string, importer: string);
+}
+/** Thrown when the alias target itself cannot be resolved. */
+export declare class ReactNativeAliasTargetMissingError extends Error {
+    readonly importer: string;
+    readonly name = "ReactNativeAliasTargetMissingError";
+    constructor(importer: string);
+}
+/**
+ * Rewrite the bare `react-native` specifier onto `@gjsify/react-native`.
+ *
+ * `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;

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

@@ -0,0 +1,128 @@
+// `'react-native'` → `'@gjsify/react-native'`: the alias line ADR 0032 § 2 names.
+//
+// § 2 puts it this way: the package NAME `@gjsify/react-native` "is the
+// documentation of the bundler alias line, and that alias only works if the
+// export surface mirrors React Native's". Without the line the mirror has no
+// consumer — an unmodified React Native application still cannot build, because
+// every one of its files imports `react-native` and nothing rewrites it. This
+// repository's own showcase had to import the gjsify name instead, which is the
+// measurement: the port that was supposed to be free was a rename per file.
+//
+// OPT-IN, NEVER UNCONDITIONAL, and this is the part to not "simplify":
+//
+//   1. A build that is not a React Native port must not have `react-native`
+//      redirected under it. A monorepo with a phone leg and a desktop leg has
+//      the real `react-native` installed on purpose; rewriting the specifier for
+//      every `gjsify build` in that tree changes what the PHONE build resolves,
+//      and `--app nativescript` has its own vocabulary that this layer does not
+//      speak (ADR 0032, "What this does not decide").
+//   2. `@gjsify/react-native` is tier 3 and optional. An unconditional alias
+//      makes every build in a tree without it fail on a package nobody asked
+//      for — and the failure names a gjsify package, so it reads as our bug.
+//
+// So the redirect happens only where the consumer asked for it: `gjsify build
+// --dialect react-native`, or this plugin composed by hand.
+//
+// A `resolveId` hook and not an `aliasPlugin` entry, for two reasons the alias
+// table cannot express: a deep import into React Native's internals is a NAMED
+// REFUSAL rather than a rewrite (see {@link ReactNativeDeepImportError}), and an
+// 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.
+/** 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. */
+export const REACT_NATIVE_SPECIFIER = 'react-native';
+/**
+ * Classify an import specifier.
+ *
+ * EXACT match on the root, never a prefix: `react-native-web`,
+ * `react-native-reanimated` and `react-native-gesture-handler` all start with
+ * the same eleven characters and none of them is this package. ADR 0032 records
+ * the last two as `not-reachable` (they need a Babel worklet transform that is
+ * not in this chain) and the first as rejected by design; aliasing any of them
+ * 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) };
+    }
+    return { kind: 'other' };
+}
+/**
+ * Thrown for `react-native/<subpath>` — an import of React Native's internals.
+ *
+ * The alias rests on the export SURFACE being mirrored (§ 2), and a subpath is
+ * by definition not part of that surface: `react-native/Libraries/Components/…`
+ * reaches into a module layout that exists because of Metro and the native
+ * bridge. There is nothing to map it to and nothing honest to stub it with, so
+ * the build says so with the importer named rather than resolving to the real
+ * React Native source and failing later on `NativeModules`.
+ */
+export class ReactNativeDeepImportError extends Error {
+    specifier;
+    importer;
+    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.`);
+        this.specifier = specifier;
+        this.importer = importer;
+    }
+}
+/** Thrown when the alias target itself cannot be resolved. */
+export class ReactNativeAliasTargetMissingError extends Error {
+    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.`);
+        this.importer = importer;
+    }
+}
+/**
+ * Rewrite the bare `react-native` specifier onto `@gjsify/react-native`.
+ *
+ * `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 function reactNativeAliasPlugin() {
+    return {
+        name: 'gjsify-react-native-alias',
+        resolveId: {
+            order: 'pre',
+            async handler(source, importer, extraOptions) {
+                const classified = classifyReactNativeSpecifier(source);
+                if (classified.kind === 'other')
+                    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);
+                // `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, {
+                    skipSelf: true,
+                    ...(extraOptions?.kind ? { kind: extraOptions.kind } : {}),
+                });
+                if (!resolved || resolved.external)
+                    throw new ReactNativeAliasTargetMissingError(from);
+                return resolved;
+            },
+        },
+    };
+}