@gjsify/rolldown-plugin-gjsify 0.43.0 → 0.44.0

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/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;
+            },
+        },
+    };
+}

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

@@ -0,0 +1,108 @@
+import type { Plugin } from 'rolldown';
+import { ImportScanParseError, type NamedImport, type OpaqueReference } from '../utils/scan-named-imports.js';
+/**
+ * The two functions the gate needs off the support table.
+ *
+ * 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.
+ */
+export interface SupportTableReader {
+    /** True for `supported` and `partial` — the statuses a build may import. */
+    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";
+/**
+ * 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 declare const WATCHED_SPECIFIERS: readonly string[];
+/** One refused import, with everything the message needs. */
+export interface SupportViolation {
+    readonly name: string;
+    readonly specifier: string;
+    readonly line: number;
+    readonly column: number;
+    /** The table's own sentence for this name. */
+    readonly reason: string;
+}
+/** Thrown for every refused import in one module, in one message. */
+export declare class ReactNativeUnsupportedImportError extends Error {
+    readonly id: string;
+    readonly violations: readonly SupportViolation[];
+    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.
+ *
+ * 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 declare function formatSupportViolations(id: string, violations: readonly SupportViolation[]): string;
+/** The refused subset of a scan, in the table's words. */
+export declare function findSupportViolations(named: readonly NamedImport[], table: SupportTableReader): readonly SupportViolation[];
+/** The warning for a reference whose names the scan cannot see. */
+export declare function formatOpaqueReference(id: string, ref: OpaqueReference): string;
+/**
+ * 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 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,
+     * where {@link loadSupportTable} reads the project's own copy on the first
+     * module that mentions the layer.
+     */
+    table?: SupportTableReader;
+}
+/**
+ * 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 declare function reactNativeSupportGatePlugin(options?: ReactNativeSupportGateOptions): Plugin;