@gjsify/rolldown-plugin-gjsify 0.52.0 → 0.54.0

package/lib/plugins/css-as-string.js

@@ -17,7 +17,7 @@
 // `@import`s are resolved + inlined in JS first (`flattenCssImports`, so bare
 // node_modules specifiers work — the native `bundle()` FileProvider can't walk
 // node_modules), then the flattened CSS goes through the native `transform()`
-// for lowering. Both use the same `cssBundleResolver`. The `--app gjs`
+// for lowering. Both use the same resolver. The `--app gjs`
 // orchestrator passes `targets: { firefox: 60 << 16 }` so nesting + modern
 // selectors get flattened to GTK4-CSS-engine-compatible output. Targeting is
 // opt-in — a missing `targets` keeps the source pristine.
@@ -43,7 +43,10 @@ import { createRequire } from 'node:module';
 import { dirname, isAbsolute, resolve as resolvePath } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { isGjs } from '../utils/runtime.js';
+import { declareBuildInput } from '../utils/declare-build-input.js';
 let _bundlerPromise = null;
+/** Why the native bridge's library would not open, when `tryLoadNativeBundler()` measured it. */
+let _nativeLoadError = null;
 async function pickBundler() {
     const forced = globalThis.process?.env
         ?.GJSIFY_CSS_BACKEND;
@@ -52,11 +55,22 @@ async function pickBundler() {
     if (forced === 'native') {
         const native = await tryLoadNativeBundler();
         if (!native)
-            throw new Error('GJSIFY_CSS_BACKEND=native but @gjsify/lightningcss-native is not loadable');
+            throw new Error('GJSIFY_CSS_BACKEND=native but @gjsify/lightningcss-native is not loadable' +
+                (_nativeLoadError ? `\n${_nativeLoadError.message}` : ''));
         return native;
     }
     const native = await tryLoadNativeBundler();
-    return native ?? loadNpmBundler();
+    if (native)
+        return native;
+    // The npm fallback is the right answer, and it is silent on purpose — a
+    // missing optional backend is not an error. But if we MEASURED why the
+    // native one would not load, that measurement is the only place the user
+    // ever hears it, so it goes to the same `console.debug` channel
+    // `loadOptionalNativeModule` uses rather than into nothing. A backend that
+    // cannot load is the reason someone reaches for this flag.
+    if (_nativeLoadError)
+        console.debug(_nativeLoadError.message);
+    return loadNpmBundler();
 }
 async function tryLoadNativeBundler() {
     // The native bridge only exists under GJS — `imports.gi` marker. Skip
@@ -79,14 +93,44 @@ async function tryLoadNativeBundler() {
         const mod = (await import(/* @vite-ignore */ pathToFileURL(resolved).href));
         if (!mod.hasNativeLightningcss())
             return null;
-        return async (filename, targets) => {
+        // The typelib resolved; its library opens at the first class access. Open
+        // it now, beside that typelib: this module cannot leave it to the wrapper,
+        // whose `lib/` is imported by file URL where GJS resolves no bare
+        // specifier. A library that will not load then names its missing
+        // dependency and the npm fallback runs, instead of the nameless
+        // "Unsupported type void" inside `transform()`.
+        // The same resolve-then-import dance as above, for the probe itself:
+        // off disk, so the lazy edge costs nothing and the static one would have
+        // cost a bootable CLI. `./native-library` rather than `./core`: `core`
+        // re-exports `main-loop`, whose module-level singleton would then exist
+        // twice in a process that already has it inlined in the GJS bundle. The
+        // walk follows the WORKSPACE, so `@gjsify/utils build:esm` must precede
+        // it — rule 5 of `scripts/check-build-infra-order.mjs` orders that edge,
+        // the one `bundler-pick.ts` is on the success path of.
+        //
+        // Its own `try` because the outer one cannot tell this apart from "there
+        // is no native backend" — and reporting nothing is the one outcome this
+        // file must not produce: a missing measurement reads as a passing one.
+        let openNativeLibrary;
+        try {
+            const utilsHref = pathToFileURL(createRequire(import.meta.url).resolve('@gjsify/utils/native-library')).href;
+            ({ openNativeLibrary } = (await import(/* @vite-ignore */ utilsHref)));
+        }
+        catch (err) {
+            _nativeLoadError = err instanceof Error ? err : new Error(String(err));
+            return null;
+        }
+        _nativeLoadError = openNativeLibrary('GjsifyLightningcss');
+        if (_nativeLoadError)
+            return null;
+        return async (filename, targets, declare) => {
             // The native `@gjsify/lightningcss-native` `bundle()` resolves
             // `@import` chains through lightningcss's filesystem-backed
             // FileProvider, which walks relative + absolute paths but NOT
             // bare node_modules specifiers (`@import "@scope/pkg/x.css"`) —
             // a JS resolver callback can't cross the GI/Rust boundary. So we
             // do `@import` resolution in JS first, using the SAME
-            // `cssBundleResolver` the npm `bundleAsync` path uses (npm-package
+            // resolver the npm `bundleAsync` path uses (npm-package
             // + `exports`-map aware), and hand the fully-flattened CSS to the
             // native `transform()` for the GTK4 nesting/modern-syntax lowering
             // (`targets`). The native shim accepts a browserslist string; the
@@ -94,7 +138,7 @@ async function tryLoadNativeBundler() {
             // (`firefox: 60 << 16` etc), so convert per browser key.
             let flattened;
             try {
-                flattened = await flattenCssImports(filename);
+                flattened = await flattenCssImports(filename, declare);
             }
             catch (err) {
                 // The native rolldown engine flattens a thrown plugin error to
@@ -147,13 +191,16 @@ async function loadNpmBundler() {
     // `dependency` of this package, so the runtime resolve finds it.
     const specifier = 'lightningcss';
     const { bundleAsync } = (await import(/* @vite-ignore */ specifier));
-    return async (filename, targets) => {
+    return async (filename, targets, declare) => {
         const result = await bundleAsync({
             filename,
             targets,
             minify: false,
             errorRecovery: true,
-            resolver: cssBundleResolver,
+            // Per call, not a module singleton: the resolver is where every
+            // `@import` target is resolved, so it is where the declaration has
+            // to happen — and it must carry THIS load's sink.
+            resolver: createCssBundleResolver(declare),
         });
         return { code: result.code };
     };
@@ -185,35 +232,50 @@ const ASSET_REF_RE = /\.(woff2?|ttf|otf|eot|svg|png|jpe?g|gif|webp|avif|ico)(\?|
 function isAssetReference(specifier) {
     return /^(data|https?|file):/i.test(specifier) || ASSET_REF_RE.test(specifier);
 }
-const cssBundleResolver = {
-    resolve(specifier, from) {
-        if (isAbsolute(specifier))
-            return specifier;
-        if (specifier.startsWith('./') || specifier.startsWith('../')) {
-            return resolvePath(dirname(from), specifier);
-        }
-        // Bare specifier — walk node_modules and honor package.json exports.
-        // `createRequire` takes a file URL or path; passing the importer
-        // lets it scope its node_modules walk to the right starting point.
-        const req = createRequire(pathToFileURL(from).href);
-        try {
-            return req.resolve(specifier);
-        }
-        catch (err) {
-            // Not an installed module. If it's a `url()`/asset reference,
-            // leave it verbatim so lightningcss keeps the `@font-face` /
-            // `url()` rule intact (the consumer serves the asset) instead of
-            // crashing the build. A genuine unresolvable CSS `@import`
-            // re-throws with actionable context so the missing dependency
-            // surfaces clearly on both backends (npm and native).
-            if (isAssetReference(specifier))
+function createCssBundleResolver(declare) {
+    return {
+        resolve(specifier, from) {
+            // A relative `@import` is resolved here, but lightningcss reads the
+            // target itself — so the resolver is the only place its name is known.
+            if (isAbsolute(specifier)) {
+                declare(stripQuery(specifier));
                 return specifier;
-            throw new Error(`cannot resolve @import "${specifier}" from ${from} (${err.message}). ` +
-                'If it is a workspace/npm package, ensure it is installed and exposes the CSS ' +
-                'file via its package.json "exports".');
-        }
-    },
-};
+            }
+            if (specifier.startsWith('./') || specifier.startsWith('../')) {
+                const resolved = resolvePath(dirname(from), specifier);
+                declare(resolved);
+                return resolved;
+            }
+            // Bare specifier — walk node_modules and honor package.json exports.
+            // `createRequire` takes a file URL or path; passing the importer
+            // lets it scope its node_modules walk to the right starting point.
+            const req = createRequire(pathToFileURL(from).href);
+            try {
+                const resolved = req.resolve(specifier);
+                declare(resolved);
+                return resolved;
+            }
+            catch (err) {
+                // Not an installed module. If it's a `url()`/asset reference,
+                // leave it verbatim so lightningcss keeps the `@font-face` /
+                // `url()` rule intact (the consumer serves the asset) instead of
+                // crashing the build. A genuine unresolvable CSS `@import`
+                // re-throws with actionable context so the missing dependency
+                // surfaces clearly on both backends (npm and native).
+                if (isAssetReference(specifier))
+                    return specifier;
+                throw new Error(`cannot resolve @import "${specifier}" from ${from} (${err.message}). ` +
+                    'If it is a workspace/npm package, ensure it is installed and exposes the CSS ' +
+                    'file via its package.json "exports".');
+            }
+        },
+    };
+}
+/** `@scope/pkg/x.css?v=2` is a cache-busting convention; the file is the part before it. */
+function stripQuery(specifier) {
+    const cut = specifier.search(/[?#]/);
+    return cut === -1 ? specifier : specifier.slice(0, cut);
+}
 // Matches a CSS `@import` at-rule and captures the specifier + any trailing
 // condition tokens (media query / `layer()` / `supports()`) before the `;`.
 // Covers `@import "x";`, `@import 'x';`, and `@import url("x")` / `url(x)`.
@@ -236,7 +298,7 @@ async function replaceAllAsync(source, re, fn) {
 }
 /**
  * Recursively resolve + inline every bundleable `@import` in `entry`, using the
- * same {@link cssBundleResolver} the npm `bundleAsync` path uses. Returns a
+ * same resolver the npm `bundleAsync` path uses. Returns a
  * single flattened CSS string with no bundleable `@import` statements left — the
  * native `transform()` then applies GTK4 nesting/target lowering.
  *
@@ -249,20 +311,26 @@ async function replaceAllAsync(source, re, fn) {
  * URL) are kept verbatim (the resolver leaves them alone), matching the npm
  * path. A cycle inlines each file at most once.
  */
-async function flattenCssImports(entry) {
+async function flattenCssImports(entry, declare) {
     const seen = new Set();
+    const resolver = createCssBundleResolver(declare);
     const inline = async (file, isRoot) => {
-        const abs = isAbsolute(file) ? file : resolvePath(file);
+        const abs = isAbsolute(file) ? stripQuery(file) : resolvePath(file);
         if (seen.has(abs))
             return ''; // @import cycle — inline once
         seen.add(abs);
+        // Declared at the READ, not at the resolution: the root stylesheet, and
+        // any import a form the regex does not match, are still inputs of the
+        // output — and a resolution declares nothing if lightningcss then
+        // decides not to read it.
+        declare(abs);
         let source = await readFile(abs, 'utf8');
         // `@charset` is only valid as the very first token of a stylesheet;
         // an inlined sub-file's `@charset` mid-stream would be invalid CSS.
         if (!isRoot)
             source = source.replace(/@charset[^;]*;/gi, '');
         return replaceAllAsync(source, IMPORT_RE, async (match, spec, condition) => {
-            const resolved = cssBundleResolver.resolve(spec, abs);
+            const resolved = resolver.resolve(spec, abs);
             // Asset-reference `@import` (rare): resolver returns it verbatim —
             // keep the at-rule intact.
             if (resolved === spec)
@@ -310,13 +378,29 @@ export function cssAsStringPlugin(options = {}) {
             // flattens nesting, so no further lightningcss lowering is needed).
             filter: { id: /\.(css|s[ac]ss)$/ },
             async handler(id) {
+                // Every file the backends read on our behalf, declared through
+                // the standard contract — `gjsify test`'s freshness check reads
+                // this list, and it is the only account of a stylesheet's
+                // `@import`/`@use` chain, which no module graph names. Why the
+                // call is feature-detected: `utils/declare-build-input.ts`.
+                const declare = (abs) => declareBuildInput(this, abs);
+                // The entry itself is read here in every branch, and a Sass
+                // file's PARTIALS are not: dart-sass resolves a relative
+                // `@use "./x"` through its own filesystem importer before any
+                // custom importer is consulted (measured 2026-09-29 with
+                // dart-sass 1.101: `importers[].findFileUrl` and
+                // `canonicalize` are called zero times for a relative load, and
+                // for a bare one only on the way to being declined, so the path
+                // is never ours to declare). Tracking that:
+                // status/open-todos/bundler.md.
+                declare(stripQuery(id));
                 let code;
                 if (/\.s[ac]ss$/.test(id)) {
                     code = await compileSass(id);
                 }
                 else {
                     code = bundle
-                        ? new TextDecoder('utf-8').decode(await loadAndBundleCss(id, targets))
+                        ? new TextDecoder('utf-8').decode(await loadAndBundleCss(id, targets, declare))
                         : await readFile(id, 'utf8');
                 }
                 return {
@@ -339,7 +423,7 @@ async function compileSass(filename) {
         // `import './x.scss'` fails with UNLOADABLE_DEPENDENCY. Resolving it to a file
         // first (`tryLoadNativeBundler`'s trick) does not help: `sass.default.js` then
         // imports a bare `immutable`. Only INLINING dart-sass works, and 3.6 MB minified
-        // onto a 6.6 MB CLI bundle is a carrier-package decision — status/open-todos.md
+        // onto a 6.6 MB CLI bundle is a carrier-package decision — status/open-todos/README.md
         // (#1053). dart-sass DOES run under GJS: `adwaita-web`'s `build:scss` does.
         _sassPromise = import(/* @vite-ignore */ 'sass');
     }
@@ -352,10 +436,10 @@ async function compileSass(filename) {
             `Is the \`sass\` package installed? (${err.message})`);
     }
 }
-async function loadAndBundleCss(filename, targets) {
+async function loadAndBundleCss(filename, targets, declare) {
     if (!_bundlerPromise)
         _bundlerPromise = pickBundler();
     const bundler = await _bundlerPromise;
-    const { code } = await bundler(filename, targets);
+    const { code } = await bundler(filename, targets, declare);
     return code;
 }

package/lib/plugins/gi-optional.d.ts

@@ -0,0 +1,60 @@
+import type { Plugin } from 'rolldown';
+declare const GI_OPTIONAL_VIRTUAL_PREFIX: {
+    readonly gjs: "\0gjsify-gi-optional:";
+    readonly node: "\0gjsify-gi-optional-node:";
+};
+/** Which build target's shim a flagged specifier gets. */
+export type GiOptionalTarget = keyof typeof GI_OPTIONAL_VIRTUAL_PREFIX;
+/** The query flag that declares a `gi://` import optional. */
+export declare const GI_OPTIONAL_FLAG = "optional";
+/**
+ * `Symbol.for` key of the marker statement every optional shim emits, naming its own
+ * namespace so a reader of the ARTIFACT can tell an optional namespace from a hard one.
+ *
+ * WHY IT IS IN THE BUNDLE AND NOT ALONGSIDE IT, which is the design decision this
+ * constant exists to pin: `gjsify ship` reads the emitted file, not the build tree,
+ * and reads the STAGE MANIFEST when it packs on another host — so a sidecar next to
+ * the bundle is a second source that can be stale, absent, or a different file. The
+ * marker is therefore one statement in the module body the plugin already emits, and
+ * it is a `globalThis[Symbol.for(…)]?.(…)` call for two reasons, both measured on
+ * rolldown's own minifier: an unknown global call is not statically pure, so it
+ * survives minification where a bare string constant is dropped by tree-shaking, and
+ * the optional call means nothing on a host that never registers a handler.
+ */
+export declare const GI_OPTIONAL_MARKER = "gjsify.optionalGi";
+/**
+ * The statement that records `namespace` as optional in the artifact.
+ *
+ * Two string arguments in the spelling the node arm's `requireGi("Ns", "X")` already
+ * uses, so one reader answers both targets. The version argument is OMITTED when
+ * there is none, rather than sent empty: a `requireGi` call cannot tell `''` from a
+ * version, and neither can this.
+ */
+export declare function giOptionalMarkerSource(namespace: string, version?: string): string;
+/**
+ * Split `gi://Ns?version=X&optional` into the clean specifier the loader sees and the
+ * flag; `null` when the specifier is not a `gi://` one or does not carry the flag.
+ */
+export declare function parseOptionalGiSpecifier(source: string): {
+    specifier: string;
+    namespace: string;
+    version?: string;
+} | null;
+/**
+ * The module body for one optional namespace. Self-contained: it runs at module
+ * evaluation, where no bundled helper may be assumed, and reaches ambient globals
+ * through `globalThis.` only.
+ */
+export declare function giOptionalShimSource(specifier: string, namespace: string, version?: string): string;
+/**
+ * The `--app node` body: the same contract, reached through `@gjsify/node-gi`.
+ *
+ * The load is EAGER, which is the one place this arm differs from the hard node shim
+ * and the reason is the flag: `requireGi` only fails when it is called, so a lazy Proxy
+ * cannot answer "is it there" without loading it — and the answer is the whole point.
+ * A missing `@gjsify/node-gi` itself lands in the same catch and yields `undefined`,
+ * which is honest: without node-gi no GI namespace loads, optional or not.
+ */
+export declare function giOptionalNodeShimSource(namespace: string, version?: string): string;
+export declare function giOptionalPlugin(target: GiOptionalTarget): Plugin;
+export {};

package/lib/plugins/gi-optional.js

@@ -0,0 +1,152 @@
+// SPDX-License-Identifier: MIT
+// `import Goa from 'gi://Goa?version=1.0&optional'` — a GI namespace the app can run
+// without (ADR 0087). Composed by `--app gjs` and `--app node`.
+//
+// A plain `gi://` import is a hard edge: GJS loads the typelib when the specifier is
+// EVALUATED and a missing one aborts the module graph before the app decides anything.
+// The `optional` query flag is the declaration that the app has that decision to make.
+// The import resolves to a virtual module that loads the SAME specifier without the
+// flag inside a try/catch, so the emitted bundle still carries the verbatim
+// `gi://Goa?version=1.0` that `ship/gi-namespaces.ts` and `depends.ts` read, and the
+// namespace is `undefined` when it is absent.
+//
+// BOTH app targets, and the second one was the trap. `--app node` already loads a
+// `gi://` namespace LAZILY (`gjsGiNodePlugin` default-exports a Proxy that calls
+// `requireGi` on first member access), so with the flag ignored the same source kept
+// returning a truthy Proxy where the app checks `Goa === undefined`, and the first
+// real member access threw instead of degrading — a degrade path that works on one
+// build target and not the other is the defect, not the laziness. Hence a NODE
+// shim with the SAME contract: the namespace or `undefined`, plus one warn. It is
+// synchronous rather than a top-level `await import()` (the shape the node arm's
+// synchronous `require()` already has), because a flag whose whole point is that
+// the app can branch on the result must not force every importer to be async.
+import { GJSIFY_VIRTUAL_PREFIX } from '../utils/virtual-module-id.js';
+import { parseGiSpecifier } from './gjs-gi-node.js';
+const GI_OPTIONAL_VIRTUAL_PREFIX = {
+    gjs: `${GJSIFY_VIRTUAL_PREFIX}gi-optional:`,
+    node: `${GJSIFY_VIRTUAL_PREFIX}gi-optional-node:`,
+};
+/** The query flag that declares a `gi://` import optional. */
+export const GI_OPTIONAL_FLAG = 'optional';
+/**
+ * `Symbol.for` key of the marker statement every optional shim emits, naming its own
+ * namespace so a reader of the ARTIFACT can tell an optional namespace from a hard one.
+ *
+ * WHY IT IS IN THE BUNDLE AND NOT ALONGSIDE IT, which is the design decision this
+ * constant exists to pin: `gjsify ship` reads the emitted file, not the build tree,
+ * and reads the STAGE MANIFEST when it packs on another host — so a sidecar next to
+ * the bundle is a second source that can be stale, absent, or a different file. The
+ * marker is therefore one statement in the module body the plugin already emits, and
+ * it is a `globalThis[Symbol.for(…)]?.(…)` call for two reasons, both measured on
+ * rolldown's own minifier: an unknown global call is not statically pure, so it
+ * survives minification where a bare string constant is dropped by tree-shaking, and
+ * the optional call means nothing on a host that never registers a handler.
+ */
+export const GI_OPTIONAL_MARKER = 'gjsify.optionalGi';
+/**
+ * The statement that records `namespace` as optional in the artifact.
+ *
+ * Two string arguments in the spelling the node arm's `requireGi("Ns", "X")` already
+ * uses, so one reader answers both targets. The version argument is OMITTED when
+ * there is none, rather than sent empty: a `requireGi` call cannot tell `''` from a
+ * version, and neither can this.
+ */
+export function giOptionalMarkerSource(namespace, version) {
+    const args = version === undefined ? JSON.stringify(namespace) : `${JSON.stringify(namespace)}, ${JSON.stringify(version)}`;
+    return `globalThis[Symbol.for(${JSON.stringify(GI_OPTIONAL_MARKER)})]?.(${args});`;
+}
+/**
+ * Split `gi://Ns?version=X&optional` into the clean specifier the loader sees and the
+ * flag; `null` when the specifier is not a `gi://` one or does not carry the flag.
+ */
+export function parseOptionalGiSpecifier(source) {
+    if (!source.startsWith('gi://'))
+        return null;
+    const queryIndex = source.indexOf('?');
+    if (queryIndex === -1)
+        return null;
+    const params = new URLSearchParams(source.slice(queryIndex + 1));
+    if (!params.has(GI_OPTIONAL_FLAG))
+        return null;
+    params.delete(GI_OPTIONAL_FLAG);
+    const rest = params.toString();
+    const specifier = source.slice(0, queryIndex) + (rest ? `?${rest}` : '');
+    const parsed = parseGiSpecifier(specifier);
+    if (parsed === null)
+        return null;
+    return { specifier, ...parsed };
+}
+/**
+ * The module body for one optional namespace. Self-contained: it runs at module
+ * evaluation, where no bundled helper may be assumed, and reaches ambient globals
+ * through `globalThis.` only.
+ */
+export function giOptionalShimSource(specifier, namespace, version) {
+    const label = version ? `${namespace} ${version}` : namespace;
+    return (`let ns;\n` +
+        `try {\n` +
+        `  const m = await import(${JSON.stringify(specifier)});\n` +
+        `  ns = m.default ?? m;\n` +
+        `} catch (error) {\n` +
+        `  let searched = '';\n` +
+        `  try {\n` +
+        `    const r = globalThis.imports.gi.GIRepository.Repository.dup_default();\n` +
+        `    searched = ' (typelib search path: ' + r.get_search_path().join(':') + ')';\n` +
+        `  } catch {}\n` +
+        `  console.warn(${JSON.stringify(`optional GI namespace ${label} is not available`)} + searched + ': ' + (error && error.message ? error.message : String(error)));\n` +
+        `}\n` +
+        `${giOptionalMarkerSource(namespace, version)}\n` +
+        `export default ns;\n`);
+}
+/**
+ * The `--app node` body: the same contract, reached through `@gjsify/node-gi`.
+ *
+ * The load is EAGER, which is the one place this arm differs from the hard node shim
+ * and the reason is the flag: `requireGi` only fails when it is called, so a lazy Proxy
+ * cannot answer "is it there" without loading it — and the answer is the whole point.
+ * A missing `@gjsify/node-gi` itself lands in the same catch and yields `undefined`,
+ * which is honest: without node-gi no GI namespace loads, optional or not.
+ */
+export function giOptionalNodeShimSource(namespace, version) {
+    const label = version ? `${namespace} ${version}` : namespace;
+    const versionArg = version === undefined ? '' : `, ${JSON.stringify(version)}`;
+    return (`import { createRequire } from 'node:module';\n` +
+        `const require = createRequire(import.meta.url);\n` +
+        `let ns;\n` +
+        `try {\n` +
+        `  ns = require('@gjsify/node-gi/gi').requireGi(${JSON.stringify(namespace)}${versionArg});\n` +
+        `} catch (error) {\n` +
+        `  console.warn(${JSON.stringify(`optional GI namespace ${label} is not available`)} + ': ' + (error && error.message ? error.message : String(error)));\n` +
+        `}\n` +
+        `${giOptionalMarkerSource(namespace, version)}\n` +
+        `export default ns;\n`);
+}
+export function giOptionalPlugin(target) {
+    const prefix = GI_OPTIONAL_VIRTUAL_PREFIX[target];
+    return {
+        name: `gjsify-gi-optional-${target}`,
+        resolveId: {
+            order: 'pre',
+            filter: { id: /^gi:\/\/.*[?&]optional(?:&|=|$)/ },
+            handler(source) {
+                const parsed = parseOptionalGiSpecifier(source);
+                if (parsed === null)
+                    return null;
+                const version = parsed.version ? `@${parsed.version}` : '';
+                return { id: `${prefix}${parsed.namespace}${version}` };
+            },
+        },
+        load(id) {
+            if (!id.startsWith(prefix))
+                return null;
+            const spec = id.slice(prefix.length);
+            const at = spec.lastIndexOf('@');
+            const namespace = at === -1 ? spec : spec.slice(0, at);
+            const version = at === -1 ? undefined : spec.slice(at + 1);
+            const code = target === 'gjs'
+                ? giOptionalShimSource(`gi://${namespace}${version ? `?version=${version}` : ''}`, namespace, version)
+                : giOptionalNodeShimSource(namespace, version);
+            return { code, moduleSideEffects: false };
+        },
+    };
+}

package/lib/plugins/gi-renderer.d.ts

@@ -29,7 +29,7 @@ export interface GiRendererOptions {
  * passes `--gi-renderer`, so the arm never composes there and this text cannot reach them
  * — measured, nothing under `tests/` names the flag but `gi-renderer-arms` itself. Making
  * that suite's two assertions import-shaped would retire this rule outright; the argument,
- * the other twelve sites and the retirement condition are in `status/open-todos.md`.
+ * the other twelve sites and the retirement condition are in `status/open-todos/README.md`.
  */
 export declare function giRendererShimSource(options: GiRendererOptions, namespace: string, version: string): string;
 export declare function giRendererPlugin(options: GiRendererOptions): Plugin;

package/lib/plugins/gi-renderer.js

@@ -90,7 +90,7 @@ const GI_RENDERER_VIRTUAL_PREFIX = `${GJSIFY_VIRTUAL_PREFIX}gi-renderer:`;
  * passes `--gi-renderer`, so the arm never composes there and this text cannot reach them
  * — measured, nothing under `tests/` names the flag but `gi-renderer-arms` itself. Making
  * that suite's two assertions import-shaped would retire this rule outright; the argument,
- * the other twelve sites and the retirement condition are in `status/open-todos.md`.
+ * the other twelve sites and the retirement condition are in `status/open-todos/README.md`.
  */
 export function giRendererShimSource(options, namespace, version) {
     return (`import { ${namespace} as namespace } from ${JSON.stringify(options.renderer)};\n` +

package/lib/plugins/gi-runtime-paths.js

@@ -9,8 +9,11 @@
 // e2e): a banner is the entry chunk's BODY and ESM evaluates imports first, so a
 // STATIC `import … from 'gi://Ns'` has already loaded its typelib before this runs.
 // What is left is what loads LATER — `await import('gi://Soup')` and the other
-// optional namespaces. Reaching the static ones changes how a bundle acquires GI
-// namespaces at all; that is an ADR, filed in the same entry.
+// optional namespaces. Confirmed on darwin-arm64 in the same shape (macOS 27 / M4 /
+// Homebrew, the bundle loading Gtk through `await import` and failing through a
+// static one). Reaching the static ones changes how a bundle acquires GI namespaces
+// at all: ADR 0085 decides to lower them here, in `renderChunk`, to awaited dynamic
+// imports placed after this prologue — proposed, not implemented.
 //
 // TWO KINDS OF DIRECTORY, split by WHOSE FACT each is. `dirs` describe the SHIPPED
 // TREE, so they are baked, relative to the program. `systemProbes` describe the host

package/lib/plugins/napi-node-addon.d.ts

@@ -12,11 +12,49 @@ export interface NapiNodeAddonPluginOptions {
      * `@gjsify/napi` is not resolvable in the consumer graph. Default `true`.
      */
     warnOnMissingNapi?: boolean;
+    /**
+     * Is the output an ESM single-file build, i.e. does it carry the
+     * bundle-URL banner the run-time resolver anchors on? Default `true`;
+     * `app/gjs.ts` passes the same `format === 'esm'` the node-modules path
+     * rewriter gates its own runtime resolution on.
+     *
+     * `false` DECLINES every rewrite, with one warning naming the reason. It is
+     * a decline and not the pre-ADR baked path because there is no correct baked
+     * path left: the whole point of ADR 0084 is that a path chosen at build time
+     * is what made the artifact unusable off the build machine, so emitting one
+     * again would reintroduce the defect for a mode that cannot anchor at run
+     * time anyway. A `--library cjs` build is a library for a consumer's own
+     * toolchain, which resolves its addons itself.
+     */
+    runtimeResolve?: boolean;
 }
 /** A native addon package root has no resolvable compiled `.node`. */
 export declare class AddonNotBuiltError extends Error {
     constructor(pkgRoot: string);
 }
+/**
+ * Enumerate every `.node` an addon package ships, keyed by platform, as a
+ * `<package>/<subpath>` spec per entry. ADR 0084: the build ENUMERATES, it
+ * does not select — the bundle picks the right entry at RUN time from the
+ * host it finds itself on.
+ *
+ * The table has:
+ *   - One entry per `prebuilds/<tuple>/` directory, keyed by the tuple's
+ *     platform and EVERY architecture it declares, and per libc variant. Each
+ *     entry is chosen by {@link selectPrebuildFile} — node-gyp-build's own
+ *     algorithm, run for a synthetic host of that tuple — so the entry for the
+ *     build host is exactly the binary Node would load, and a foreign platform's
+ *     entry is the best one that host could load rather than the best-looking
+ *     file in the directory.
+ *   - One entry per `build/Release` and `build/Debug`, keyed by the BUILD host
+ *     ({@link buildHostTarget}, deliberately not the `npm_config_*` override
+ *     those files are not built for), overriding the prebuilds entry for the
+ *     same key: node-gyp-build's order has build/Release winning.
+ *
+ * Returns an empty record when no `.node` exists anywhere — the caller then
+ * throws {@link AddonNotBuiltError} as a build-time gate.
+ */
+export declare function enumerateAddonTargets(pkgRoot: string, pkg: AddonPackageJson): Record<string, string>;
 /**
  * Locate the compiled `.node` for an addon package root, matching node-gyp-build's
  * probe order: `build/Release` → `build/Debug` →
@@ -28,14 +66,19 @@ export declare function resolveAddonPath(pkgRoot: string, opts?: {
 }): string;
 /** Nearest ancestor directory of `importerFile` holding a `package.json`. */
 export declare function nearestPackageRoot(importerFile: string): string | null;
+/**
+ * The addon table as a JSON string — the platform-key → `<pkg>/<subpath>`
+ * map the runtime resolver (`__gjsifyAddonResolve`) picks from. ADR 0084.
+ */
+type AddonTable = string;
 /** Direct `.node` import → the addon's exports (ESM default). */
-export declare function directNodeShim(addonPath: string): string;
+export declare function directNodeShim(addonTable: AddonTable): string;
 /** `node-gyp-build` replacement — a callable `load(dir)` carrying `.path()`. */
-export declare function nodeGypBuildShim(addonPath: string): string;
+export declare function nodeGypBuildShim(addonTable: AddonTable): string;
 /** `bindings` replacement — a callable `bindings(name)` returning the addon. */
-export declare function bindingsShim(addonPath: string): string;
+export declare function bindingsShim(addonTable: AddonTable): string;
 /** napi-rs sibling → the raw native exports as the module value. */
-export declare function napiRsShim(addonPath: string): string;
+export declare function napiRsShim(addonTable: AddonTable): string;
 /** Classify a specifier for interception — pure decision logic, no filesystem. */
 export declare function classifySpecifier(source: string): {
     kind: 'node-gyp-build' | 'bindings';
@@ -122,3 +165,4 @@ export declare function hostNapiRsTriple(): string | null;
  * else. Register ONLY for `--app gjs` — the C-ABI runs under `@gjsify/napi`.
  */
 export declare function napiNodeAddonPlugin(options?: NapiNodeAddonPluginOptions): Plugin;
+export {};