@gjsify/rolldown-plugin-gjsify 0.51.1 → 0.53.0

package/lib/plugins/node-native-external.js

@@ -0,0 +1,145 @@
+// For `--app node`: keep every Node-API addon PACKAGE external, so Node loads it from
+// `node_modules` exactly as it would without a bundler.
+//
+// An addon package finds its `.node` binary relative to ITS OWN files —
+// `require('node-gyp-build')(__dirname)`, `bindings('x')`, `require('../build/Release/x.node')`,
+// napi-rs' `require(`./x.${triple}.node`)`. Bundled, `__dirname` / `import.meta.dirname`
+// is the bundle's directory, and the lookup misses. Measured on
+// `@signalapp/libsignal-client`: `node-gyp-build(import.meta.dirname + '/..')` threw
+// "No native build was found" from an `--app node` bundle that ran fine as source.
+// `bufferutil` fails SILENTLY instead — its `try { node-gyp-build } catch { fallback }`
+// quietly swaps the native build for the JS one.
+//
+// External, not copied: `--app gjs` has to rewrite an addon (`napiNodeAddonPlugin`
+// routes it through `@gjsify/napi`) because GJS cannot load one itself, but Node can,
+// and every loader convention resolves against a package-shaped directory, not a flat
+// prebuild next to the bundle. So an `--app node` bundle of a native dependency needs
+// `node_modules` at runtime, like any `npm install`-ed program.
+//
+// Detection is by PACKAGE, from its manifest and layout, never by source sniffing, and
+// shares the napi-rs + gjsify-bridge rules with `napiNodeAddonPlugin`.
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { dirname, isAbsolute, join } from 'node:path';
+import { isGjsifyNativeBridge, isNapiRsPackageJson } from './napi-node-addon.js';
+// oxlint-disable-next-line no-control-regex -- NUL marks a bundler virtual id, never a package.
+const BARE_SPECIFIER_RE = /^[^.\\/:\s\x00][^:\s\x00]*$/;
+/** Runtime helpers whose only job is locating an addon binary next to the package. */
+const ADDON_LOADER_DEPENDENCIES = [
+    'node-gyp-build',
+    'node-gyp-build-optional-packages',
+    'bindings',
+    'prebuild-install',
+    'node-pre-gyp',
+    '@mapbox/node-pre-gyp',
+    'cmake-js',
+];
+function readdirSafe(dir) {
+    try {
+        return readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+}
+/** A `.node` file in `dir` or one directory below it (`prebuilds/<target>/`, `build/Release/`). */
+function hasNodeBinary(dir) {
+    for (const name of readdirSafe(dir)) {
+        if (name.endsWith('.node'))
+            return true;
+        if (readdirSafe(join(dir, name)).some((n) => n.endsWith('.node')))
+            return true;
+    }
+    return false;
+}
+/**
+ * Is the package at `pkgRoot` a Node-API addon — one whose code loads a `.node`
+ * relative to its own directory? True on any of: `gypfile`, a `binding.gyp`, a
+ * node-pre-gyp `binary` block, a dependency on an addon loader, the napi-rs manifest
+ * signals, or a `.node` under `prebuilds/` or `build/`. A gjsify native bridge is
+ * never one: it ships a GI typelib loaded through `gi://`.
+ */
+export function isNodeAddonPackage(pkgRoot, pkg) {
+    if (isGjsifyNativeBridge(pkg))
+        return false;
+    if (pkg.gypfile === true)
+        return true;
+    if (pkg.binary !== null && typeof pkg.binary === 'object')
+        return true;
+    if (existsSync(join(pkgRoot, 'binding.gyp')))
+        return true;
+    const deps = { ...pkg.dependencies, ...pkg.optionalDependencies };
+    if (ADDON_LOADER_DEPENDENCIES.some((name) => name in deps))
+        return true;
+    if (isNapiRsPackageJson(pkg))
+        return true;
+    return hasNodeBinary(join(pkgRoot, 'prebuilds')) || hasNodeBinary(join(pkgRoot, 'build'));
+}
+/** `@scope/name/sub` → `@scope/name`, `name/sub` → `name`; null for anything not bare. */
+export function packageNameOf(specifier) {
+    if (specifier.startsWith('.') || specifier.startsWith('/') || specifier.startsWith('\0'))
+        return null;
+    if (specifier.includes(':'))
+        return null; // node:fs, gi://Gtk, data:, C:\…
+    const parts = specifier.split('/');
+    if (specifier.startsWith('@'))
+        return parts.length >= 2 && parts[1] ? `${parts[0]}/${parts[1]}` : null;
+    return parts[0] || null;
+}
+/**
+ * The root of package `name` that `file` belongs to: the nearest ancestor whose
+ * `package.json` is NAMED `name`. Matching on the name skips the nested
+ * `{ "type": "module" }` manifests dual packages put in `dist/esm/`.
+ */
+function packageRootFor(file, name) {
+    let dir = dirname(file);
+    for (let i = 0; i < 64; i++) {
+        const manifest = join(dir, 'package.json');
+        if (existsSync(manifest)) {
+            try {
+                const pkg = JSON.parse(readFileSync(manifest, 'utf8'));
+                if (pkg.name === name)
+                    return { root: dir, pkg };
+            }
+            catch {
+                // An unreadable manifest is not this package's — keep walking up.
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+/** Keeps every import of a Node-API addon package external on `--app node`. */
+export function nodeNativeExternalPlugin() {
+    // Keyed by package name + importer directory: node resolution depends on both.
+    const verdicts = new Map();
+    return {
+        name: 'gjsify-node-native-external',
+        resolveId: {
+            order: 'pre',
+            // Rust-regex compatible (no lookaround, NUL as \x00): `@gjsify/rolldown-native`
+            // hands it to the Rust core as a string. Bare specifiers only.
+            filter: { id: BARE_SPECIFIER_RE },
+            async handler(source, rawImporter) {
+                const name = packageNameOf(source);
+                if (name === null)
+                    return null;
+                const importer = typeof rawImporter === 'string' ? rawImporter : undefined;
+                const key = `${name}\0${importer === undefined ? '' : dirname(importer)}`;
+                let native = verdicts.get(key);
+                if (native === undefined) {
+                    native = false;
+                    const resolved = await this.resolve(source, importer, { skipSelf: true });
+                    if (resolved && !resolved.external && isAbsolute(resolved.id) && existsSync(resolved.id)) {
+                        const owner = packageRootFor(resolved.id, name);
+                        native = owner !== null && isNodeAddonPackage(owner.root, owner.pkg);
+                    }
+                    verdicts.set(key, native);
+                }
+                return native ? { id: source, external: true } : null;
+            },
+        },
+    };
+}

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

@@ -39,6 +39,48 @@ export declare const DESKTOP_OS_SUFFIXES: Readonly<Record<string, string>>;
  * Without that, an author's fork is dead code with nothing anywhere saying so.
  */
 export declare const DESKTOP_REFUSED_SUFFIXES: readonly string[];
+/**
+ * Suffixes that must NEVER be a rung of the BROWSER chain — the mirror of
+ * {@link DESKTOP_REFUSED_SUFFIXES}, built by the same rule read from the other
+ * side: **refuse the other families' UMBRELLA rungs, not their per-target
+ * spellings.** The desktop list names `.web` (the whole browser chain) and
+ * `.native` (the phone family's umbrella) and deliberately leaves
+ * `.android`/`.ios`/`.visionos` out; from here the same rule names the GTK
+ * desktop family's two non-OS rungs plus that same phone umbrella.
+ *
+ * `.gtk` is the one a reader reaches for while chasing a missing widget, and it
+ * is the worst possible answer: `--app browser` redirects `gi://*` and `@girs/*`
+ * to an EMPTY module, so a `.gtk.tsx` reaching `Adw.ActionRow` does not fail to
+ * import — it gets `{}`, and `class X extends Adw.ActionRow` throws
+ * `Class extends value undefined` at load. That is measured, and the ADR 0034
+ * stage 9 e2e keeps exactly that row as its control.
+ *
+ * `.desktop` is named as well as `.gtk`, though only one of the two appears in
+ * this repository today: § 9 writes `.desktop` as the umbrella over `.gtk` and
+ * the three OS spellings, so refusing one and not the other is a gap, and a gap
+ * in a refusal list reads as a judgement that the omitted one is fine here.
+ *
+ * `.native` is the phone bridge — `NativeModules` exists in neither a browser
+ * nor a GTK host, which is why both lists carry it.
+ *
+ * NOT here, and each is a DECISION rather than an omission:
+ * - **the three OS spellings** (`linux`/`macos`/`windows`). They only ever
+ *   appear as rungs of the desktop chain, whose umbrella is already named — the
+ *   same reason `.android` is absent from the desktop list. Naming them would
+ *   put a warning line on every OS-forked module of a normal dual-target tree,
+ *   which is how a warning gets switched off.
+ * - **a refusal list for NativeScript at all.** That chain runs with
+ *   `siblingIndex` OFF under a byte-identical mandate, and with no listing to
+ *   filter them a refusal list costs two real `this.resolve` calls on every
+ *   relative import that has no variant — the majority, inside
+ *   `@nativescript/core` included. The desktop chain's own measurement (+14% on
+ *   a ~1400-module bundle from six failed resolves) is what says failed resolves
+ *   are not free. It is a cost with a measured-zero benefit on this tree: the
+ *   30 `.gtk.*`/`.native.*` pairs in `@gjsify/adwaita-react-native` all HIT the
+ *   NS chain at `.native`, and the refusal probe only runs when the chain found
+ *   nothing. Reopen it from a measurement of that tree with the index on.
+ */
+export declare const BROWSER_REFUSED_SUFFIXES: readonly string[];
 /**
  * The NativeScript chain: platform-specific first, then the platform-agnostic
  * `native` suffix. Without a known platform only `native` applies.
@@ -57,6 +99,37 @@ export declare function nativescriptSuffixChain(platform?: NativescriptPlatform)
  * guessing one.
  */
 export declare function desktopSuffixChain(os?: string): readonly string[];
+/**
+ * The BROWSER chain: `.web` → base. Exactly ONE rung, and the count is the
+ * decision.
+ *
+ * A desktop build knows three different things about itself and so gets three
+ * rungs: the toolkit (`.gtk`), the kernel (`.<os>`) and the target family
+ * (`.desktop`). A `--app browser` build knows ONE — it targets the DOM — and
+ * every candidate second rung was rejected for a stated reason rather than left
+ * out for tidiness:
+ *
+ * - **No engine rung** (`.firefox` / `.chromium`). The target compiles one
+ *   `esnext` bundle with no per-engine branch anywhere in it; a rung nobody can
+ *   fill is a resolution rule that can only ever surprise someone.
+ * - **No OS rung.** One browser bundle is served to every operating system, so
+ *   an OS rung would resolve against the BUILD HOST and bake it into a
+ *   platform-neutral artifact. That is the mistake `plugins/gi-runtime-paths.ts`
+ *   already documents for the GI prologue, committed here at resolution time
+ *   where the evidence is a file name and not a code path.
+ * - **No `.dom` synonym.** Two spellings for one concept is a priority order
+ *   someone has to memorise, and `.web` is what § 9 writes and what every
+ *   `.web.*` file in this repository already uses.
+ * - **No `.browser` umbrella.** `.desktop` earns its rung by sitting above four
+ *   spellings; above `.web` there is nothing for an umbrella to cover.
+ *
+ * Takes no parameter, unlike {@link desktopSuffixChain}: nothing about this
+ * chain depends on the host, which is the previous point restated from the API
+ * side. It is a function rather than a constant so that
+ * {@link PlatformResolvePluginOptions.suffixes} keeps its rule — a hand-written
+ * array is a second resolution order the tree does not state.
+ */
+export declare function browserSuffixChain(): readonly string[];
 /**
  * The desktop suffix for the BUILD HOST, or `undefined` for a host outside
  * ADR 0018's target set.
@@ -81,16 +154,19 @@ export declare function desktopOsSuffix(platform?: string): string | undefined;
 export interface PlatformResolvePluginOptions {
     /**
      * 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.
+     * {@link nativescriptSuffixChain}, {@link desktopSuffixChain} or
+     * {@link browserSuffixChain} — 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.
+     * {@link BROWSER_REFUSED_SUFFIXES} for the browser chain, empty for
+     * NativeScript — where `.native` is a real rung and the rest is a measured
+     * decision written out on `BROWSER_REFUSED_SUFFIXES`. Probed only after the
+     * chain found nothing, so an empty list costs zero extra resolves and the NS
+     * path is byte-unchanged.
      */
     refusedSuffixes?: readonly string[];
     /**
@@ -121,6 +197,20 @@ export interface PlatformResolvePluginOptions {
      * 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.
+     *
+     * ON WHEREVER THE CHAIN CARRIES A REFUSAL LIST, and that is not a preference.
+     * A refused suffix is probed on every miss, so a chain with refusals pays its
+     * probes on the MAJORITY of imports rather than the few that have a variant.
+     * Measured on `tests/e2e/vite-plugin-gjsify`'s fixture with the browser chain
+     * (one rung, three refusals) under `--max-old-space-size=4096`: index off is
+     * 1172 probes and `FATAL ERROR: Reached heap limit`; index on is 0 probes,
+     * 0.25 s and 191 MB. Under Vite each probe re-enters the whole plugin
+     * container, which is where the memory goes. Leaving the index off is
+     * therefore a choice only a chain with NO refusal list can afford.
+     *
+     * Kept fresh by {@link platformResolvePlugin}'s `watchChange` hook, so a
+     * long-lived host (a Vite dev server, `gjsify build --watch`) does not answer
+     * from a directory listing taken before the author added the variant.
      */
     siblingIndex?: boolean;
 }

package/lib/plugins/platform-resolve.js

@@ -1,16 +1,20 @@
-// Platform file resolution — ONE plugin, ONE resolution order, two chains.
+// Platform file resolution — ONE plugin, ONE resolution order, three chains.
 //
 // 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 on disk, in the priority order the caller's chain declares:
 //
-//   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>
+//   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
+//   Browser (`--app browser`)
+//     ./foo.web.<ext>
+//     ./foo.<ext>
+//
+// THREE CHAINS, NOT THREE 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
@@ -82,6 +86,48 @@ export const DESKTOP_OS_SUFFIXES = {
  * Without that, an author's fork is dead code with nothing anywhere saying so.
  */
 export const DESKTOP_REFUSED_SUFFIXES = ['native', 'web'];
+/**
+ * Suffixes that must NEVER be a rung of the BROWSER chain — the mirror of
+ * {@link DESKTOP_REFUSED_SUFFIXES}, built by the same rule read from the other
+ * side: **refuse the other families' UMBRELLA rungs, not their per-target
+ * spellings.** The desktop list names `.web` (the whole browser chain) and
+ * `.native` (the phone family's umbrella) and deliberately leaves
+ * `.android`/`.ios`/`.visionos` out; from here the same rule names the GTK
+ * desktop family's two non-OS rungs plus that same phone umbrella.
+ *
+ * `.gtk` is the one a reader reaches for while chasing a missing widget, and it
+ * is the worst possible answer: `--app browser` redirects `gi://*` and `@girs/*`
+ * to an EMPTY module, so a `.gtk.tsx` reaching `Adw.ActionRow` does not fail to
+ * import — it gets `{}`, and `class X extends Adw.ActionRow` throws
+ * `Class extends value undefined` at load. That is measured, and the ADR 0034
+ * stage 9 e2e keeps exactly that row as its control.
+ *
+ * `.desktop` is named as well as `.gtk`, though only one of the two appears in
+ * this repository today: § 9 writes `.desktop` as the umbrella over `.gtk` and
+ * the three OS spellings, so refusing one and not the other is a gap, and a gap
+ * in a refusal list reads as a judgement that the omitted one is fine here.
+ *
+ * `.native` is the phone bridge — `NativeModules` exists in neither a browser
+ * nor a GTK host, which is why both lists carry it.
+ *
+ * NOT here, and each is a DECISION rather than an omission:
+ * - **the three OS spellings** (`linux`/`macos`/`windows`). They only ever
+ *   appear as rungs of the desktop chain, whose umbrella is already named — the
+ *   same reason `.android` is absent from the desktop list. Naming them would
+ *   put a warning line on every OS-forked module of a normal dual-target tree,
+ *   which is how a warning gets switched off.
+ * - **a refusal list for NativeScript at all.** That chain runs with
+ *   `siblingIndex` OFF under a byte-identical mandate, and with no listing to
+ *   filter them a refusal list costs two real `this.resolve` calls on every
+ *   relative import that has no variant — the majority, inside
+ *   `@nativescript/core` included. The desktop chain's own measurement (+14% on
+ *   a ~1400-module bundle from six failed resolves) is what says failed resolves
+ *   are not free. It is a cost with a measured-zero benefit on this tree: the
+ *   30 `.gtk.*`/`.native.*` pairs in `@gjsify/adwaita-react-native` all HIT the
+ *   NS chain at `.native`, and the refusal probe only runs when the chain found
+ *   nothing. Reopen it from a measurement of that tree with the index on.
+ */
+export const BROWSER_REFUSED_SUFFIXES = ['gtk', 'desktop', 'native'];
 /**
  * The NativeScript chain: platform-specific first, then the platform-agnostic
  * `native` suffix. Without a known platform only `native` applies.
@@ -104,6 +150,39 @@ export function nativescriptSuffixChain(platform) {
 export function desktopSuffixChain(os) {
     return os ? ['gtk', os, 'desktop'] : ['gtk', 'desktop'];
 }
+/**
+ * The BROWSER chain: `.web` → base. Exactly ONE rung, and the count is the
+ * decision.
+ *
+ * A desktop build knows three different things about itself and so gets three
+ * rungs: the toolkit (`.gtk`), the kernel (`.<os>`) and the target family
+ * (`.desktop`). A `--app browser` build knows ONE — it targets the DOM — and
+ * every candidate second rung was rejected for a stated reason rather than left
+ * out for tidiness:
+ *
+ * - **No engine rung** (`.firefox` / `.chromium`). The target compiles one
+ *   `esnext` bundle with no per-engine branch anywhere in it; a rung nobody can
+ *   fill is a resolution rule that can only ever surprise someone.
+ * - **No OS rung.** One browser bundle is served to every operating system, so
+ *   an OS rung would resolve against the BUILD HOST and bake it into a
+ *   platform-neutral artifact. That is the mistake `plugins/gi-runtime-paths.ts`
+ *   already documents for the GI prologue, committed here at resolution time
+ *   where the evidence is a file name and not a code path.
+ * - **No `.dom` synonym.** Two spellings for one concept is a priority order
+ *   someone has to memorise, and `.web` is what § 9 writes and what every
+ *   `.web.*` file in this repository already uses.
+ * - **No `.browser` umbrella.** `.desktop` earns its rung by sitting above four
+ *   spellings; above `.web` there is nothing for an umbrella to cover.
+ *
+ * Takes no parameter, unlike {@link desktopSuffixChain}: nothing about this
+ * chain depends on the host, which is the previous point restated from the API
+ * side. It is a function rather than a constant so that
+ * {@link PlatformResolvePluginOptions.suffixes} keeps its rule — a hand-written
+ * array is a second resolution order the tree does not state.
+ */
+export function browserSuffixChain() {
+    return ['web'];
+}
 /**
  * The desktop suffix for the BUILD HOST, or `undefined` for a host outside
  * ADR 0018's target set.
@@ -155,13 +234,21 @@ export function platformResolvePlugin(options) {
         // 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.');
+        throw new Error('gjsify platform resolve: the suffix chain is empty. Pass nativescriptSuffixChain(…), ' +
+            'desktopSuffixChain(…) or browserSuffixChain(), 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.
+    //
+    // CACHED FOR THE PLUGIN INSTANCE'S LIFE, so it needs the `watchChange` hook
+    // below: in a one-shot build the process ends before a listing can go stale,
+    // but `gjsify build --watch` and a Vite dev server both keep one plugin
+    // instance across rebuilds. Without invalidation an author who ADDS
+    // `foo.web.ts` beside `foo.ts` while the watcher runs keeps being served
+    // `foo.ts` until restart — the filter would be answering from a directory
+    // that no longer exists in that shape.
     const listings = new Map();
     const listingFor = (dir) => {
         const cached = listings.get(dir);
@@ -196,6 +283,19 @@ export function platformResolvePlugin(options) {
     const warned = new Set();
     return {
         name: 'gjsify-platform-resolve',
+        // The sibling index's invalidation. Both hosts call this for every path
+        // the watcher reports (`create` / `update` / `delete`), which is exactly
+        // the event that can make a cached listing wrong — a NEW `foo.web.ts` is
+        // a `create` in the directory the filter already answered for.
+        //
+        // Only the CHANGED path's directory is dropped, not the whole map: the
+        // map is refilled lazily, so a blanket clear would re-`readdirSync` every
+        // directory the next rebuild touches for one unrelated save. `dirname`
+        // of a virtual or `\0`-prefixed id is a directory that was never cached,
+        // and deleting an absent key is a no-op — no guard needed for that.
+        watchChange(id) {
+            listings.delete(dirname(id));
+        },
         resolveId: {
             order: 'pre',
             async handler(source, importer, extraOptions) {
@@ -204,6 +304,23 @@ export function platformResolvePlugin(options) {
                     return null;
                 if (!source.startsWith('./') && !source.startsWith('../'))
                     return null;
+                // A QUERY NAMES A TRANSFORM OF ONE FILE, NOT A FILE TO FORK.
+                //
+                // `./x.blp?shared-tree`, `?raw`, `?url`: the plugin serving the query owns the
+                // resolution, and there is no second FILE for a platform chain to prefer —
+                // whatever the suffix is appended to, `./x.blp?shared-tree.native` is a
+                // specifier no convention gives a meaning to.
+                //
+                // Standing down is not merely tidier here, it is required. A probe that misses
+                // is normally free: `this.resolve('./x.native')` on a path that is not there
+                // returns null and the loop walks on. With a query in the specifier it is NOT
+                // — measured on `--app nativescript`, the missed probe surfaced as
+                // `UNLOADABLE_DEPENDENCY … No such file or directory (os error 2)` against the
+                // ORIGINAL import, and the chain never reached the plugin that would have
+                // resolved it. So the blind probe does not waste a lookup, it fails the build,
+                // and it does so pointing at a line that is correct.
+                if (source.includes('?'))
+                    return null;
                 const extMatch = KNOWN_EXT_RE.exec(source);
                 const origExt = extMatch ? extMatch[0] : '';
                 const base = origExt ? source.slice(0, -origExt.length) : source;
@@ -253,12 +370,16 @@ export function platformResolvePlugin(options) {
                     if (!probe || warned.has(probe.id))
                         continue;
                     warned.add(probe.id);
+                    // The remedy names THIS chain's own rungs. It used to end in
+                    // a hardcoded `.desktop`, which was true of the only chain
+                    // that had a refusal list and became advice to write a file
+                    // the browser chain refuses the moment a second one did.
+                    const ownVariants = suffixes.map((own) => `.${own}`).join(' / ');
                     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.`);
+                        `shows up on screen. Move what applies here into ${ownVariants} or the base file.`);
                 }
                 return null;
             },

package/lib/plugins/rewrite-node-modules-paths.d.ts

@@ -58,13 +58,29 @@ export interface RewriteResult {
     moduleType?: 'ts' | 'js';
     map?: null;
 }
+/** The `import.meta` members the rewriter answers for: Node's three location properties. */
+type ImportMetaProp = 'url' | 'dirname' | 'filename';
+/**
+ * Replace every `import.meta.url` / `.dirname` / `.filename` expression in `src`.
+ *
+ * On the AST, not the text: the token also occurs inside STRINGS, and a text rewrite
+ * put a quoted replacement inside a quoted key — vite's `define: { "import.meta.url":
+ * … }` became `"__gjsifyModuleUrl("vite/…")"`, a PARSE_ERROR ("Expected `:` but found
+ * `Identifier`") that failed every `--app gjs` build reaching vite or wxt. A source
+ * acorn cannot parse keeps the token rewrite it always had.
+ *
+ * `dirname` and `filename` (Node ≥ 20.11) are answered too: GJS defines neither, so
+ * unplugin's `path.resolve(import.meta.dirname, …)` threw `The "path" argument must be
+ * of type string. Received type undefined` at load — where wxt's rebuild stopped next.
+ */
+export declare function replaceImportMeta(src: string, path: string, replacements: Record<ImportMetaProp, string>): string;
 /**
  * Pure rewriter: the rewritten code plus the module type to re-parse it with, or `null`
  * when the file references none of the tokens.
  */
 export declare function rewriteContents(args: {
     path: string;
-}, srcInput: string, bundleDir: string, runtimeResolve: boolean): RewriteResult | null;
+}, srcInput: string, bundleDir: string, runtimeResolve: boolean, declare?: (abs: string) => void): RewriteResult | null;
 export interface NodeModulesPathRewriteOptions {
     /** Bundle output directory, derived from `output.file` / `output.dir`. */
     bundleDir: string;
@@ -85,3 +101,4 @@ export interface NodeModulesPathRewriteOptions {
  * wider scope nearly free. See {@link shouldInline} for why the scopes differ.
  */
 export declare function nodeModulesPathRewritePlugin(options: NodeModulesPathRewriteOptions): Plugin;
+export {};