@gjsify/rolldown-plugin-gjsify 0.51.1 → 0.53.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,42 @@ 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: by
+        // the time a CSS transform asks for the native bundler, utils' `lib/esm`
+        // is long built, 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.
+        //
+        // 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 +136,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 +189,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 +230,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 +296,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 +309,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 +376,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 +421,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 +434,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-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 {};