@gjsify/rolldown-plugin-gjsify 0.43.0 → 0.45.0

package/lib/app/gjs.js

@@ -9,6 +9,9 @@ import { aliasPlugin } from '../plugins/alias.js';
 import { externalsPlugin } from '../plugins/externals.js';
 import { napiNodeAddonPlugin } from '../plugins/napi-node-addon.js';
 import { unresolvedWorkspaceImportPlugin } from '../plugins/unresolved-workspace-import.js';
+import { platformResolvePlugin, desktopSuffixChain, desktopOsSuffix, DESKTOP_REFUSED_SUFFIXES, } from '../plugins/platform-resolve.js';
+import { reactNativeAliasPlugin } from '../plugins/react-native-alias.js';
+import { reactNativeSupportGatePlugin } from '../plugins/react-native-gate.js';
 import { deepkitPlugin } from '@gjsify/rolldown-plugin-deepkit';
 import blueprintPlugin from '@gjsify/vite-plugin-blueprint';
 import { getAliasesForGjs } from '../utils/alias.js';
@@ -161,6 +164,15 @@ export const setupForGjs = async (input) => {
     // Reflection reads the ORIGINAL TypeScript, so it runs before any user
     // transform can strip the annotations out from under it (see `GjsifyConfig`).
     const prePlugins = [deepkitPlugin({ reflection: input.pluginOptions.reflection })];
+    // ADR 0032 § 8's build-time gate reads the ORIGINAL source for the same reason
+    // reflection does: `import type { ViewProps }` is what tells it a name costs
+    // nothing, and a normal-order transform may already have stripped it.
+    // This target composes a dialect, so it is one of `DIALECT_APPS` — the set
+    // the CLI refuses `--dialect` against for every OTHER target. Adding a
+    // dialect here without adding the target there means a flag accepted and
+    // silently ignored.
+    if (input.pluginOptions.dialect === 'react-native')
+        prePlugins.push(reactNativeSupportGatePlugin());
     const plugins = [
         // Virtual-entry plugin runs FIRST so its resolveId/load match the
         // synthetic input ids that `wrapInputWithSideEffects` produces.
@@ -170,6 +182,22 @@ export const setupForGjs = async (input) => {
         // banner, and acorn (the auto-globals detector) rejects the `#` byte.
         // The final-output shebang is composed by shebangPlugin's renderChunk.
         inputShebangStripPlugin(),
+        // Platform-file forks for the desktop, ADR 0032 § 9: `.gtk` → `.<os>` →
+        // `.desktop` → base. BEFORE the alias layer, so a platform fork of a
+        // module that also has a Node-builtin substitution wins over the
+        // substitution — the fork is the more specific statement. `.native` and
+        // `.web` are deliberately absent from the chain and warned about when
+        // present; `DESKTOP_REFUSED_SUFFIXES` carries the reason.
+        platformResolvePlugin({
+            suffixes: desktopSuffixChain(desktopOsSuffix()),
+            refusedSuffixes: DESKTOP_REFUSED_SUFFIXES,
+            siblingIndex: true,
+        }),
+        // ADR 0032 § 2's alias line, only when the consumer asked for it
+        // (`--dialect react-native`). `pre`, ahead of the substitution table and the
+        // externals policy — a redirect after `externalsPlugin` would find the
+        // specifier already externalised.
+        ...(input.pluginOptions.dialect === 'react-native' ? [reactNativeAliasPlugin()] : []),
         // random-access-file's 'browser' field maps to a throwing stub; the alias
         // table forces the fs-backed Node entry.
         aliasPlugin({ entries: aliasEntries }),

package/lib/app/nativescript.js

@@ -37,7 +37,7 @@ import { deepkitPlugin } from '@gjsify/rolldown-plugin-deepkit';
 import { ALIASES_NODE_FOR_NATIVESCRIPT, getDerivedAliasesSync } from '@gjsify/resolve-npm';
 import { globToEntryPoints } from '../utils/entry-points.js';
 import { gjsImportsEmptyPlugin } from '../plugins/gjs-imports-empty.js';
-import { platformResolvePlugin, detectNativescriptPlatform, nativescriptPlatformDefines, } from '../plugins/platform-resolve.js';
+import { platformResolvePlugin, nativescriptSuffixChain, detectNativescriptPlatform, nativescriptPlatformDefines, } from '../plugins/platform-resolve.js';
 import { unresolvedWorkspaceImportPlugin } from '../plugins/unresolved-workspace-import.js';
 // Never bundled: an app works only with the ONE core instance the runtime boots, and what
 // this target emits is an ENTRY the NS bundler resolves it for. An optional peer absent from
@@ -132,7 +132,7 @@ export const setupForNativescript = async (input) => {
         // Platform-specific source variants (`*.android` / `*.ios` /
         // `*.native`) win over the base file — resolved BEFORE the Node-builtin
         // alias routing so a platform fork of a portable module is honored.
-        platformResolvePlugin({ platform }),
+        platformResolvePlugin({ suffixes: nativescriptSuffixChain(platform) }),
         aliasPlugin({ entries: aliasEntries }),
         // NO blueprintPlugin — Blueprint is a GTK-specific UI DSL
         // NO cssAsStringPlugin — NS ships its own CSS pipeline via

package/lib/app/node.d.ts

@@ -6,12 +6,15 @@ import type { PluginOptions } from '../types/plugin-options.js';
  * factory, matchMedia, …) over `@gjsify/node-gi`, not the default `@gjsify/empty`
  * stubs that keep CROSS-PLATFORM node bundles loadable on plain Node.
  *
- * Two adjustments over the standard node alias map:
+ * Three adjustments over the standard node alias map:
  *  1. every `<pkg>/register…` → `@gjsify/empty` entry is DROPPED so the register
  *     import resolves to its real body;
  *  2. the gjs target's bare→scoped register routes (`xmlhttprequest/register` →
  *     `@gjsify/fetch/register/xhr`, …) are merged in so the inject stub's bare
- *     specifiers resolve on node exactly as they do on gjs.
+ *     specifiers resolve on node exactly as they do on gjs;
+ *  3. `REVERSE_BRIDGE_ENTRY_ROUTES` is merged in, so a package whose `node`
+ *     export condition is a different program (solid-js's SSR build) is routed
+ *     to the entry the `--app gjs` build of the same source gets.
  *
  * Applied to the BASE map only, when `isGjsSourceBuild` — `pluginOptions.aliases` /
  * user aliases still override, and a non-reverse-bridge build is untouched.

package/lib/app/node.js

@@ -1,4 +1,5 @@
 // `--app node` Rolldown configuration factory.
+import { createRequire } from 'node:module';
 import { aliasPlugin } from '../plugins/alias.js';
 import blueprintPlugin from '@gjsify/vite-plugin-blueprint';
 import { deepkitPlugin } from '@gjsify/rolldown-plugin-deepkit';
@@ -10,6 +11,9 @@ import { cssAsStringPlugin } from '../plugins/css-as-string.js';
 import { gjsImportsEmptyPlugin } from '../plugins/gjs-imports-empty.js';
 import { gjsGiNodePlugin, gjsBuiltinModulesNodePlugin } from '../plugins/gjs-gi-node.js';
 import { unresolvedWorkspaceImportPlugin } from '../plugins/unresolved-workspace-import.js';
+import { platformResolvePlugin, desktopSuffixChain, desktopOsSuffix, DESKTOP_REFUSED_SUFFIXES, } from '../plugins/platform-resolve.js';
+import { reactNativeAliasPlugin } from '../plugins/react-native-alias.js';
+import { reactNativeSupportGatePlugin } from '../plugins/react-native-gate.js';
 import { wrapInputWithSideEffects } from '../utils/entry-wrapper.js';
 /**
  * Side-effect specifier the node target injects when GJS ambient globals
@@ -38,18 +42,100 @@ const NODE_GI_GLOBALS_SPECIFIER = '@gjsify/node-gi/globals';
 const NODE_GI_BARE_MODULE_SPECIFIERS = Object.values(ALIASES_GJS_FOR_NODE);
 /** Matches a register subpath in an alias key: `<pkg>/register` or `<pkg>/register/<feature>`. */
 const REGISTER_SUBPATH_RE = /\/register(\/|$)/;
+/**
+ * npm packages a REVERSE-BRIDGE build must be routed away from, because their
+ * `node` export condition is not a node build of the same program — it is a
+ * DIFFERENT program, chosen for an assumption a GJS-on-node bundle does not
+ * hold. The value is the entry the `--app gjs` build of the same source gets,
+ * so the two ADR 0030 legs run one program.
+ *
+ * `solid-js` is the measured case and so far the only one. Its export map
+ * routes `node` (and `deno`, and `worker`) to `dist/server.js` — the SSR
+ * build, whose `createEffect` is `function createEffect(fn, value) {}`, an
+ * empty body. The initial render is therefore PERFECT and every reactive
+ * update silently never reaches GTK: sixteen of @gjsify/gtk-host's node-leg
+ * suites failed as `Expected ["second"], Actual ["first"]` while the identical
+ * source passed on gjs, and under ADR 0030's "same suite green on gjs ⇒
+ * node-gi defect" that read as a binding defect for as long as it stood. The
+ * map's own top-level `import`/`require` keys already point at the client
+ * build — `node` merely shadows them, being declared first.
+ *
+ * A ROUTE and not a condition change, deliberately. The obvious fix is to stop
+ * applying `node`, and it does not work: `platform: 'node'` implies that
+ * condition whatever `conditionNames` says (measured — dropping it from the
+ * list left solid-js on the SSR build). The reachable lever is `browser`,
+ * which outranks `node` in solid-js's map, and taking it wholesale is the
+ * SYMMETRIC defect: the gjs target can afford `browser` only because
+ * `getAliasesForGjs` has already replaced the node-facing npm packages, while
+ * the reverse bridge lifts the `/register` routes and keeps the rest real. Then
+ * `ws` — whose map declares `browser` FIRST, pointing at a one-line
+ * `throw new Error('ws does not work in the browser…')` — took the node-gi
+ * consumer harness from `pass 19/19` to `0/5 passed, 10 failed`, every one
+ * `W.WebSocket is not a constructor`. One named package resolves differently;
+ * every other package, and every cross-platform node bundle, is byte-unchanged.
+ */
+const REVERSE_BRIDGE_ENTRY_ROUTES = {
+    // The client build both legs share. Subpaths need no route: `solid-js/universal`
+    // (the renderer @gjsify/gtk-host binds to) declares no `node` condition at all,
+    // and reaches the root through this same specifier.
+    'solid-js': 'solid-js/dist/solid.js',
+};
+/**
+ * A dangling route above is SILENT, and silence here restores exactly the bug
+ * the route exists to prevent. MEASURED: point the solid-js route at a file
+ * that does not exist and the build exits 0 with an EMPTY log — `aliasPlugin`
+ * answers an unresolvable target with `null`, which a `pre`-order `resolveId`
+ * means as "let the default chain continue", and the default chain is the
+ * `node` condition, i.e. the SSR build with the empty `createEffect`. So a
+ * route that stops resolving fails the BUILD instead, naming the package.
+ *
+ * The CONTROL is the unrouted resolution of the same specifier — what the
+ * route replaces. If that does not resolve, the package is not in this
+ * project's graph at all and there is nothing to route (the routes are a
+ * table, not a dependency list). If it DOES resolve, the routed entry must
+ * too: a package that is installed and whose client entry has moved is the
+ * one case that must not pass quietly.
+ *
+ * `createRequire` is used only as an `exports`-map-aware RESOLVER, as in
+ * `app/gjs.ts`'s `resolveShim`; nothing is loaded through it.
+ */
+function assertReverseBridgeRoutes() {
+    const require_ = createRequire(import.meta.url);
+    const resolves = (specifier) => {
+        try {
+            require_.resolve(specifier);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    for (const [pkg, target] of Object.entries(REVERSE_BRIDGE_ENTRY_ROUTES)) {
+        if (!resolves(pkg))
+            continue; // not in this graph — see the CONTROL note
+        if (resolves(target))
+            continue;
+        throw new Error(`@gjsify/rolldown-plugin-gjsify: the reverse-bridge entry route for "${pkg}" is dangling — ` +
+            `"${target}" does not resolve, while "${pkg}" does. Without the route this build silently ` +
+            `takes ${pkg}'s "node" export condition, which is why the route exists; update ` +
+            `REVERSE_BRIDGE_ENTRY_ROUTES in app/node.ts to the entry the --app gjs build resolves.`);
+    }
+}
 /**
  * Reverse-bridge register routing: a node build of a GENUINE GJS SOURCE needs the
  * REAL `@gjsify/*` register bodies (document, HTMLCanvasElement, the `'2d'` context
  * factory, matchMedia, …) over `@gjsify/node-gi`, not the default `@gjsify/empty`
  * stubs that keep CROSS-PLATFORM node bundles loadable on plain Node.
  *
- * Two adjustments over the standard node alias map:
+ * Three adjustments over the standard node alias map:
  *  1. every `<pkg>/register…` → `@gjsify/empty` entry is DROPPED so the register
  *     import resolves to its real body;
  *  2. the gjs target's bare→scoped register routes (`xmlhttprequest/register` →
  *     `@gjsify/fetch/register/xhr`, …) are merged in so the inject stub's bare
- *     specifiers resolve on node exactly as they do on gjs.
+ *     specifiers resolve on node exactly as they do on gjs;
+ *  3. `REVERSE_BRIDGE_ENTRY_ROUTES` is merged in, so a package whose `node`
+ *     export condition is a different program (solid-js's SSR build) is routed
+ *     to the entry the `--app gjs` build of the same source gets.
  *
  * Applied to the BASE map only, when `isGjsSourceBuild` — `pluginOptions.aliases` /
  * user aliases still override, and a non-reverse-bridge build is untouched.
@@ -65,6 +151,8 @@ export function enableGjsRegistersForNode(baseAliases) {
         if (REGISTER_SUBPATH_RE.test(key))
             out[key] = value;
     }
+    // 3. the packages whose `node` export is a different PROGRAM — see the table.
+    Object.assign(out, REVERSE_BRIDGE_ENTRY_ROUTES);
     return out;
 }
 /**
@@ -153,6 +241,9 @@ export const setupForNode = async (input) => {
     // predicate's doc comment. The node-gi golden `test/canvas2d-bridge.test.mjs`
     // pins the asymmetry it fixed.
     const gjsSourceBuild = isGjsSourceBuild({ ...input.pluginOptions, registerInject });
+    // Only a reverse-bridge build carries the routes, so only it is held to them.
+    if (gjsSourceBuild)
+        assertReverseBridgeRoutes();
     const baseAliases = getAliasesForNode({ external });
     const aliasMap = {
         ...(gjsSourceBuild ? enableGjsRegistersForNode(baseAliases) : baseAliases),
@@ -209,6 +300,15 @@ export const setupForNode = async (input) => {
     // Reflection reads the ORIGINAL TypeScript, so it runs before any user
     // transform can strip the annotations out from under it (see `GjsifyConfig`).
     const prePlugins = [deepkitPlugin({ reflection: input.pluginOptions.reflection })];
+    // ADR 0032 § 8's build-time gate reads the ORIGINAL source for the same reason
+    // reflection does: `import type { ViewProps }` is what tells it a name costs
+    // nothing, and a normal-order transform may already have stripped it.
+    // This target composes a dialect, so it is one of `DIALECT_APPS` — the set
+    // the CLI refuses `--dialect` against for every OTHER target. Adding a
+    // dialect here without adding the target there means a flag accepted and
+    // silently ignored.
+    if (input.pluginOptions.dialect === 'react-native')
+        prePlugins.push(reactNativeSupportGatePlugin());
     const plugins = [
         // Virtual-entry plugin runs FIRST so its resolveId/load match the synthetic
         // `\0gjsify-entry:` ids `wrapInputWithSideEffects` produces (no-op when
@@ -236,6 +336,22 @@ export const setupForNode = async (input) => {
         //     `requireGi('Adw','1')` with no lowercased-pkg→namespace map needed.
         //     This plugin's own `gi://` branch is dead on the node target.
         gjsImportsEmptyPlugin({ emptyGirs: !gjsSourceBuild }),
+        // Platform-file forks for the desktop, ADR 0032 § 9: `.gtk` → `.<os>` →
+        // `.desktop` → base. BEFORE the alias layer, so a platform fork of a
+        // module that also has a Node-builtin substitution wins over the
+        // substitution — the fork is the more specific statement. `.native` and
+        // `.web` are deliberately absent from the chain and warned about when
+        // present; `DESKTOP_REFUSED_SUFFIXES` carries the reason.
+        platformResolvePlugin({
+            suffixes: desktopSuffixChain(desktopOsSuffix()),
+            refusedSuffixes: DESKTOP_REFUSED_SUFFIXES,
+            siblingIndex: true,
+        }),
+        // ADR 0032 § 2's alias line, only when the consumer asked for it
+        // (`--dialect react-native`). `pre`, ahead of the substitution table and the
+        // externals policy — a redirect after `externalsPlugin` would find the
+        // specifier already externalised.
+        ...(input.pluginOptions.dialect === 'react-native' ? [reactNativeAliasPlugin()] : []),
         aliasPlugin({ entries: aliasEntries }),
         // Blueprint (.blp → XML string): the reverse bridge runs REAL GTK on Node,
         // so a GJS app entry with composite-template windows must build for

package/lib/index.d.ts

@@ -22,8 +22,16 @@ export { unresolvedWorkspaceImportPlugin, classifyImport, isWorkspaceSpecifier,
 export type { WorkspaceImportGuardOptions, WorkspaceImportGuardTarget, ImportVerdict, ClassifyImportInput, UnresolvedWorkspaceImportDetails, } from './plugins/unresolved-workspace-import.js';
 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 type { NapiNodeAddonPluginOptions, AddonPackageJson } from './plugins/napi-node-addon.js';
-export { platformResolvePlugin, detectNativescriptPlatform, nativescriptPlatformDefines, } from './plugins/platform-resolve.js';
+export { platformResolvePlugin, nativescriptSuffixChain, desktopSuffixChain, desktopOsSuffix, DESKTOP_OS_SUFFIXES, DESKTOP_REFUSED_SUFFIXES, PlatformVariantExternalError, detectNativescriptPlatform, nativescriptPlatformDefines, } from './plugins/platform-resolve.js';
 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 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';
 export * from './plugin.js';
 import { gjsifyPlugin } from './plugin.js';
 export { gjsifyPlugin };

package/lib/index.js

@@ -14,7 +14,11 @@ export { gjsImportsEmptyPlugin } from './plugins/gjs-imports-empty.js';
 export { externalsPlugin } from './plugins/externals.js';
 export { unresolvedWorkspaceImportPlugin, classifyImport, isWorkspaceSpecifier, formatUnresolvedWorkspaceImport, buildReverseAliasIndex, UnresolvedWorkspaceImportError, } from './plugins/unresolved-workspace-import.js';
 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, detectNativescriptPlatform, nativescriptPlatformDefines, } from './plugins/platform-resolve.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 { scanNamedImports, ImportScanParseError } from './utils/scan-named-imports.js';
 export * from './plugin.js';
 import { gjsifyPlugin } from './plugin.js';
 export { gjsifyPlugin };

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`