@gjsify/rolldown-plugin-gjsify 0.3.20 → 0.4.0

package/lib/app/gjs.js

@@ -18,8 +18,38 @@ import { globToEntryPoints } from '../utils/entry-points.js';
 import { nodeModulesPathRewritePlugin, getBundleDirFromOutput, } from '../plugins/rewrite-node-modules-paths.js';
 import { processStubPlugin } from '../plugins/process-stub.js';
 import { cssAsStringPlugin } from '../plugins/css-as-string.js';
-import { shebangPlugin, resolveShebangLine } from '../plugins/shebang.js';
+import { shebangPlugin, resolveShebangLine, inputShebangStripPlugin } from '../plugins/shebang.js';
 const _shimDir = dirname(fileURLToPath(import.meta.url));
+function resolveConsoleShim() {
+    // Preferred: relative to this module's directory. Works under the
+    // normal Node consumer flow where `_shimDir` = `<pkg>/lib/app/`.
+    const relative = resolve(_shimDir, '../shims/console-gjs.js');
+    let fs = null;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        fs = require('node:fs');
+    }
+    catch {
+        return relative;
+    }
+    if (fs.existsSync(relative))
+        return relative;
+    // Fallback: when the orchestrator is bundled into a single .mjs
+    // (GJS-CLI self-host loop) `_shimDir` collapses to the bundle's
+    // own directory and the relative lookup misses. createRequire's
+    // resolver is `exports`-map-aware (Phase C), so the published
+    // subpath export `./shims/console-gjs` works under both Node and
+    // GJS without further walking.
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const Module = require('node:module');
+        const require_ = Module.createRequire(import.meta.url);
+        return require_.resolve('@gjsify/rolldown-plugin-gjsify/shims/console-gjs');
+    }
+    catch {
+        return relative;
+    }
+}
 export const setupForGjs = async (input) => {
     const userExternal = input.userExternal ?? [];
     // Rolldown's `external` array does not support glob patterns the way
@@ -37,17 +67,32 @@ export const setupForGjs = async (input) => {
     const format = input.pluginOptions.format ?? 'esm';
     const exclude = input.pluginOptions.exclude ?? [];
     const entryPoints = await globToEntryPoints(input.input, exclude);
+    // unicorn-magic gates its full API behind the "node" conditional
+    // exports. We deliberately omit `node` from conditionNames (some
+    // packages ship genuinely Node-only code there — see comment
+    // around `conditionNames` below). Route the package to our
+    // bundled shim so the API is reachable under --app gjs without
+    // turning on the node condition globally.
+    const unicornMagicShim = resolve(_shimDir, '../shims/unicorn-magic.js');
     const aliasMap = {
         ...getAliasesForGjs({ external }),
+        'unicorn-magic': unicornMagicShim,
         ...(input.pluginOptions.aliases ?? {}),
         ...(input.userAliases ?? {}),
     };
     // The console shim replaces all `console` references with print()/printerr()-
     // based implementations that bypass GLib.log_structured() — no prefix,
     // ANSI codes work. Disabled via `pluginOptions.consoleShim === false`.
+    //
+    // Path resolution: `resolve(_shimDir, '../shims/...')` works in normal
+    // Node consumption (_shimDir = `<pkg>/lib/app/`). When the CLI is
+    // bundled into a single .mjs (e.g. the GJS-CLI self-host loop),
+    // `import.meta.url` collapses to the bundle's path and the relative
+    // resolution lands at a non-existent location. Walk up via
+    // createRequire's node_modules-aware resolver as a fallback.
     const consoleShimEnabled = input.pluginOptions.consoleShim !== false;
     const consoleShimPath = consoleShimEnabled
-        ? resolve(_shimDir, '../shims/console-gjs.js')
+        ? resolveConsoleShim()
         : null;
     // The auto-globals inject stub (when present) is side-effect-imported
     // via a virtual entry — its register modules write to globalThis, so
@@ -72,6 +117,19 @@ export const setupForGjs = async (input) => {
             mainFields: format === 'esm' ? ['browser', 'module', 'main'] : ['browser', 'main', 'module'],
             // ESM: omit 'require' — packages listing 'require' before 'import'
             // would silently route through their CJS entry.
+            //
+            // We deliberately do NOT add `'node'` here. Per Node's exports-map
+            // spec the resolver iterates keys in DECLARATION ORDER and picks
+            // the first one whose name is in `conditionNames` — the order of
+            // conditionNames itself is irrelevant. Packages like
+            // `cross-fetch-ponyfill` declare `"node"` first in their exports
+            // map and ship a Node-only entry that imports `blobFrom`/
+            // `fileFrom` (from native `node:fetch`). With `node` enabled,
+            // the resolver picks that branch over `browser` and the bundle
+            // breaks at link time. Packages that genuinely need their `node`
+            // export under GJS (rare — only one known case so far,
+            // `unicorn-magic`'s `traversePathUp`) are handled with explicit
+            // resolve aliases instead.
             conditionNames: format === 'esm' ? ['browser', 'import'] : ['browser', 'require', 'import'],
         },
         transform: {
@@ -110,6 +168,12 @@ export const setupForGjs = async (input) => {
         // Virtual-entry plugin runs FIRST so its resolveId/load match the
         // synthetic input ids that `wrapInputWithSideEffects` produces.
         ...(virtualEntries.plugin ? [virtualEntries.plugin] : []),
+        // Strip leading #! from any input module BEFORE bundling — otherwise
+        // a shebang in e.g. the CLI's own entry file ends up embedded
+        // mid-chunk after our process-stub banner, and acorn (auto-globals
+        // detector) rejects the `#` byte. Final-output shebang is composed
+        // by shebangPlugin's renderChunk hook.
+        inputShebangStripPlugin(),
         // random-access-file's 'browser' field maps to a throwing stub; force
         // the fs-backed Node entry. Implemented via the gjsify alias plugin
         // as a direct entry-table override.

package/lib/plugins/alias.js

@@ -13,6 +13,13 @@
 //   - exact string match (no prefix-aware semantics needed at this layer)
 //   - `node:<name>` specifiers map to the same target as `<name>`
 //     (handled in the alias-builder helpers, not here).
+//
+// `extraOptions.kind` is forwarded to `this.resolve()` so package.json
+// `exports` conditions ("import" / "require") match the original call site.
+// Without this, a CJS `require('stream')` in a bundled npm package would
+// resolve through the "import" condition (Rolldown's default), bypassing the
+// `cjs-compat.cjs` shim that unwraps named-export ESM modules to their
+// constructor — breaking `util.inherits(Child, Stream)` patterns.
 export function aliasPlugin(options) {
     const entries = options.entries;
     const keys = Object.keys(entries);
@@ -20,7 +27,7 @@ export function aliasPlugin(options) {
         name: 'gjsify-alias',
         resolveId: {
             order: 'pre',
-            async handler(source, importer) {
+            async handler(source, importer, extraOptions) {
                 if (!Object.prototype.hasOwnProperty.call(entries, source)) {
                     return null;
                 }
@@ -31,6 +38,7 @@ export function aliasPlugin(options) {
                     return null;
                 const resolved = await this.resolve(target, importer, {
                     skipSelf: true,
+                    kind: extraOptions?.kind,
                 });
                 if (resolved !== null) {
                     return resolved;

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

@@ -19,10 +19,100 @@
 // flattened to GTK4-CSS-engine-compatible output. Targeting is opt-in —
 // a missing `targets` keeps the source pristine.
 //
-// `lightningcss` is a regular dependency of this package; the plugin
-// imports it lazily so missing-arch installs surface the underlying
-// load error instead of crashing every gjsify build.
+// Backend selection (Phase D-2 decision matrix in
+// `docs/poc/lightningcss-decision.md`):
+//
+//   1. `@gjsify/lightningcss-native` when its prebuild is loadable on
+//      the running architecture (3-5× faster than the WASM track,
+//      ~960× faster cold init). Only relevant when `gjsify build`
+//      itself runs under GJS (Phase D-3).
+//   2. npm `lightningcss` for everything else (Node, unsupported
+//      arches, dev machines without the prebuild). Existing behavior;
+//      keeps the regular dependency on this package.
+//
+// Selection is lazy and silent — the first `.css` load probes for
+// the native bridge once, caches the answer, and routes the rest of
+// the build through the chosen backend. Set the env var
+// `GJSIFY_CSS_BACKEND={native|npm}` to force a specific backend
+// (mainly useful for benchmarking + the integration suite).
 import { readFile } from 'node:fs/promises';
+let _bundlerPromise = null;
+async function pickBundler() {
+    const forced = globalThis.process?.env?.GJSIFY_CSS_BACKEND;
+    if (forced === 'npm')
+        return loadNpmBundler();
+    if (forced === 'native') {
+        const native = await tryLoadNativeBundler();
+        if (!native)
+            throw new Error('GJSIFY_CSS_BACKEND=native but @gjsify/lightningcss-native is not loadable');
+        return native;
+    }
+    const native = await tryLoadNativeBundler();
+    return native ?? loadNpmBundler();
+}
+async function tryLoadNativeBundler() {
+    // The native bridge only exists under GJS — `imports.gi` marker. Skip
+    // the dynamic import entirely on Node so it doesn't even register as a
+    // resolved dep, which would inflate the CLI's bundled output.
+    const isGjs = typeof globalThis.imports?.gi !== 'undefined';
+    if (!isGjs)
+        return null;
+    try {
+        // Indirect specifier so tsc + Rolldown don't try to resolve the
+        // optional peer dep at build time. Resolution happens only at
+        // runtime under GJS (where the prebuild is installed).
+        const specifier = '@gjsify/lightningcss-native';
+        const mod = (await import(/* @vite-ignore */ specifier));
+        if (!mod.hasNativeLightningcss())
+            return null;
+        return async (filename, targets) => {
+            // The native shim accepts a browserslist string; the npm
+            // `lightningcss` Targets struct is bitfield-encoded
+            // (`firefox: 60 << 16` etc). Convert by extracting major
+            // version per browser key and re-emitting as the equivalent
+            // browserslist query.
+            const query = targetsToBrowserslist(targets);
+            return mod.bundle({
+                filename,
+                targets: query,
+                minify: false,
+                sourceMap: false,
+                errorRecovery: true,
+            });
+        };
+    }
+    catch {
+        return null;
+    }
+}
+async function loadNpmBundler() {
+    const { bundleAsync } = await import('lightningcss');
+    return async (filename, targets) => {
+        const result = await bundleAsync({
+            filename,
+            targets,
+            minify: false,
+            errorRecovery: true,
+        });
+        return { code: result.code };
+    };
+}
+function targetsToBrowserslist(targets) {
+    if (!targets)
+        return undefined;
+    const parts = [];
+    for (const [browser, encoded] of Object.entries(targets)) {
+        if (typeof encoded !== 'number')
+            continue;
+        // npm lightningcss encodes versions as `(major << 16) | (minor << 8) | patch`.
+        const major = (encoded >>> 16) & 0xff;
+        if (major === 0)
+            continue;
+        const name = browser === 'ios_saf' ? 'ios' : browser;
+        parts.push(`${name} >= ${major}`);
+    }
+    return parts.length ? parts.join(', ') : undefined;
+}
 export function cssAsStringPlugin(options = {}) {
     const { targets, bundle = true } = options;
     return {
@@ -42,12 +132,9 @@ export function cssAsStringPlugin(options = {}) {
     };
 }
 async function loadAndBundleCss(filename, targets) {
-    const { bundleAsync } = await import('lightningcss');
-    const result = await bundleAsync({
-        filename,
-        targets,
-        minify: false,
-        errorRecovery: true,
-    });
-    return result.code;
+    if (!_bundlerPromise)
+        _bundlerPromise = pickBundler();
+    const bundler = await _bundlerPromise;
+    const { code } = await bundler(filename, targets);
+    return code;
 }

package/lib/plugins/shebang.d.ts

@@ -5,6 +5,8 @@ export interface ShebangPluginOptions {
     /** Override the shebang line. Defaults to `GJS_SHEBANG`. */
     line?: string;
 }
+/** Always-on plugin half: strips input shebangs regardless of output options. */
+export declare function inputShebangStripPlugin(): Plugin;
 export declare function shebangPlugin(options?: ShebangPluginOptions): Plugin | null;
 /**
  * Expand `${env:NAME}` and `${env:NAME:-default}` placeholders against

package/lib/plugins/shebang.js

@@ -6,6 +6,29 @@
 // the `#` character is only valid as the very first byte of the file under
 // SpiderMonkey 128+.
 export const GJS_SHEBANG = '#!/usr/bin/env -S gjs -m';
+/**
+ * Strip a leading `#!…\n` from a source module. Rolldown preserves input
+ * shebangs verbatim, which ends up embedded mid-chunk after our process-stub
+ * banner — acorn (used by the auto-globals detector) then rejects `#` because
+ * it's not at byte 0 anymore. Stripping at the transform stage cleans both
+ * the analysis bundle and the final bundle; the gjsify-shebang renderChunk
+ * step then injects the correct line for the output target.
+ */
+const SHEBANG_RE = /^#![^\n]*\n/;
+/** Always-on plugin half: strips input shebangs regardless of output options. */
+export function inputShebangStripPlugin() {
+    return {
+        name: 'gjsify-input-shebang-strip',
+        transform: {
+            order: 'pre',
+            handler(code) {
+                if (!code.startsWith('#!'))
+                    return null;
+                return { code: code.replace(SHEBANG_RE, ''), map: null };
+            },
+        },
+    };
+}
 export function shebangPlugin(options = {}) {
     if (!options.enabled)
         return null;

package/lib/shims/unicorn-magic.d.ts

@@ -0,0 +1,14 @@
+export declare function toPath(urlOrPath: any): any;
+export declare function rootDirectory(pathInput: any): string;
+export declare function traversePathUp(startPath: any): {
+    [Symbol.iterator](): Generator<string, void, unknown>;
+};
+export declare function execFile(file: any, arguments_: any, options?: {}): Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+export declare function execFileSync(file: any, arguments_?: any[], options?: {}): NonSharedBuffer;
+export declare function delay(opts?: {
+    seconds?: number;
+    milliseconds?: number;
+}): Promise<void>;

package/lib/shims/unicorn-magic.js

@@ -0,0 +1,68 @@
+// Shim for `unicorn-magic` under --app gjs.
+//
+// The upstream package gates the full API (`toPath`, `traversePathUp`,
+// `rootDirectory`, `execFile`, `execFileSync`) behind the `"node"`
+// conditional exports entry. Under --app gjs we intentionally omit
+// the `node` resolve-condition (cross-fetch-ponyfill ships
+// Node-only code under that key — see `app/gjs.ts` conditionNames
+// comment), so a bare `import { toPath } from 'unicorn-magic'` falls
+// back to `default.js` which only exposes `delay`.
+//
+// This shim mirrors the node.js entry verbatim — the underlying
+// `node:url`/`node:path`/`node:child_process`/`node:util` imports
+// route through `@gjsify/{url,path,child_process,util}` under GJS
+// and through real Node-internals under Node. The aliasPlugin
+// points `unicorn-magic` here for --app gjs builds.
+//
+// Source-of-truth: refs/unicorn-magic/node.js (when added — for
+// now mirrored from node_modules/unicorn-magic@0.3.0).
+import { promisify } from 'node:util';
+import { execFile as execFileCallback, execFileSync as execFileSyncOriginal } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const execFileOriginal = promisify(execFileCallback);
+export function toPath(urlOrPath) {
+    return urlOrPath instanceof URL ? fileURLToPath(urlOrPath) : urlOrPath;
+}
+export function rootDirectory(pathInput) {
+    return path.parse(toPath(pathInput)).root;
+}
+export function traversePathUp(startPath) {
+    return {
+        *[Symbol.iterator]() {
+            let currentPath = path.resolve(toPath(startPath));
+            let previousPath;
+            while (previousPath !== currentPath) {
+                yield currentPath;
+                previousPath = currentPath;
+                currentPath = path.resolve(currentPath, '..');
+            }
+        },
+    };
+}
+const TEN_MEGABYTES_IN_BYTES = 10 * 1024 * 1024;
+export async function execFile(file, arguments_, options = {}) {
+    return execFileOriginal(file, arguments_, {
+        maxBuffer: TEN_MEGABYTES_IN_BYTES,
+        ...options,
+    });
+}
+export function execFileSync(file, arguments_ = [], options = {}) {
+    return execFileSyncOriginal(file, arguments_, {
+        maxBuffer: TEN_MEGABYTES_IN_BYTES,
+        ...options,
+    });
+}
+// Re-export from default.js so the union API (delay + node helpers)
+// stays intact for callers that import both.
+export async function delay(opts = {}) {
+    const { seconds, milliseconds } = opts;
+    let duration;
+    if (typeof seconds === 'number')
+        duration = seconds * 1000;
+    else if (typeof milliseconds === 'number')
+        duration = milliseconds;
+    else
+        throw new TypeError('Expected an object with either `seconds` or `milliseconds`.');
+    return new Promise((resolveFn) => setTimeout(resolveFn, duration));
+}

package/lib/utils/auto-globals.d.ts

@@ -1,4 +1,19 @@
-import { type InputOptions, type RolldownPluginOption, type TransformOptions } from 'rolldown';
+import type { InputOptions, RolldownPluginOption, TransformOptions } from 'rolldown';
+/**
+ * In-memory bundle function — returns the per-entry chunk code strings.
+ * Implementations: npm rolldown (Node default), `@gjsify/rolldown-native`
+ * (GJS). Pulled out so auto-globals can run under either engine without
+ * hardcoding npm rolldown (which can't load under GJS — the Rust prebuild's
+ * init code uses `require('node:fs')` synchronously).
+ *
+ * The default impl below dynamically imports npm rolldown; the CLI
+ * overrides this from `actions/build.ts` to route via the same engine the
+ * final build uses.
+ */
+export type AnalysisBundler = (input: {
+    rolldownInput: InputOptions;
+    format: 'esm' | 'cjs' | 'iife';
+}) => Promise<string[]>;
 import type { PluginOptions } from '../types/plugin-options.js';
 export interface AutoGlobalsResult {
     /** Global identifiers detected in the bundle */
@@ -68,5 +83,5 @@ type GjsifyPluginFactory = (options: PluginOptions) => RolldownPluginOption | Pr
  * @param verbose Emit per-iteration debug output to console.
  * @param options Optional `extraGlobalsList` / `excludeGlobals`.
  */
-export declare function detectAutoGlobals(analysisOptions: AnalysisOptions, pluginOptions: Omit<PluginOptions, 'autoGlobalsInject'>, gjsifyPluginFactory: GjsifyPluginFactory, verbose?: boolean, options?: DetectAutoGlobalsOptions): Promise<AutoGlobalsResult>;
+export declare function detectAutoGlobals(analysisOptions: AnalysisOptions, pluginOptions: Omit<PluginOptions, 'autoGlobalsInject'>, gjsifyPluginFactory: GjsifyPluginFactory, verbose?: boolean, options?: DetectAutoGlobalsOptions, bundler?: AnalysisBundler): Promise<AutoGlobalsResult>;
 export {};

package/lib/utils/auto-globals.js

@@ -17,7 +17,25 @@
 // We deliberately do NOT minify the analysis builds: minification can
 // alias `globalThis` to a short variable and defeat MemberExpression
 // detection in detect-free-globals.ts.
-import { rolldown } from 'rolldown';
+const defaultBundler = async ({ rolldownInput, format }) => {
+    // Indirect specifier so the GJS bundle doesn't pull npm rolldown in
+    // statically. Only reached when the caller doesn't override (Node).
+    const specifier = 'rolldown';
+    const mod = (await import(/* @vite-ignore */ specifier));
+    const build = await mod.rolldown(rolldownInput);
+    try {
+        const result = await build.generate({ format, minify: false, sourcemap: false });
+        const codes = [];
+        for (const entry of result.output) {
+            if (entry.type === 'chunk')
+                codes.push(entry.code);
+        }
+        return codes;
+    }
+    finally {
+        await build.close();
+    }
+};
 import { detectFreeGlobals } from './detect-free-globals.js';
 import { resolveGlobalsList, writeRegisterInjectFile } from './scan-globals.js';
 import { GJS_GLOBALS_MAP } from '@gjsify/resolve-npm/globals-map';
@@ -69,7 +87,7 @@ function detectedToRegisterPaths(detected) {
  * @param verbose Emit per-iteration debug output to console.
  * @param options Optional `extraGlobalsList` / `excludeGlobals`.
  */
-export async function detectAutoGlobals(analysisOptions, pluginOptions, gjsifyPluginFactory, verbose, options = {}) {
+export async function detectAutoGlobals(analysisOptions, pluginOptions, gjsifyPluginFactory, verbose, options = {}, bundler = defaultBundler) {
     const extraRegisterPaths = options.extraGlobalsList
         ? resolveGlobalsList(options.extraGlobalsList)
         : new Set();
@@ -101,29 +119,17 @@ export async function detectAutoGlobals(analysisOptions, pluginOptions, gjsifyPl
         const inputWithInject = currentInject
             ? appendInjectAsEntry(analysisOptions.input, currentInject)
             : analysisOptions.input;
-        const build = await rolldown({
-            input: inputWithInject,
-            external: analysisOptions.external,
-            resolve: analysisOptions.resolve,
-            transform: analysisOptions.transform,
-            plugins: [...callerPlugins, gjsifyInstance],
-            logLevel: 'silent',
+        const chunkCodes = await bundler({
+            rolldownInput: {
+                input: inputWithInject,
+                external: analysisOptions.external,
+                resolve: analysisOptions.resolve,
+                transform: analysisOptions.transform,
+                plugins: [...callerPlugins, gjsifyInstance],
+                logLevel: 'silent',
+            },
+            format: analysisOptions.format ?? 'esm',
         });
-        const chunkCodes = [];
-        try {
-            const result = await build.generate({
-                format: analysisOptions.format ?? 'esm',
-                minify: false,
-                sourcemap: false,
-            });
-            for (const entry of result.output) {
-                if (entry.type === 'chunk')
-                    chunkCodes.push(entry.code);
-            }
-        }
-        finally {
-            await build.close();
-        }
         if (chunkCodes.length === 0) {
             return { detected: new Set(), injectPath: currentInject };
         }
@@ -133,9 +139,25 @@ export async function detectAutoGlobals(analysisOptions, pluginOptions, gjsifyPl
         // top-level declarations: `File`, `Buffer`, …) that acorn can't
         // parse. Per-chunk parsing keeps each chunk's lexical scope intact.
         const newDetected = new Set();
-        for (const code of chunkCodes) {
-            for (const id of detectFreeGlobals(code))
-                newDetected.add(id);
+        for (let i = 0; i < chunkCodes.length; i++) {
+            const code = chunkCodes[i] ?? '';
+            try {
+                for (const id of detectFreeGlobals(code))
+                    newDetected.add(id);
+            }
+            catch (e) {
+                if (globalThis.process?.env?.GJSIFY_DEBUG_AUTO_GLOBALS) {
+                    const path = `/tmp/gjsify-auto-globals-failed-chunk-${i}.mjs`;
+                    try {
+                        // eslint-disable-next-line @typescript-eslint/no-require-imports
+                        const fs = await import('node:fs');
+                        fs.writeFileSync(path, code);
+                        console.error(`[gjsify-auto-globals] parse failed on chunk #${i} — wrote ${path} for inspection`);
+                    }
+                    catch { /* ignore */ }
+                }
+                throw e;
+            }
         }
         // Apply excludeGlobals BEFORE writing the next iteration's inject file.
         // Otherwise an excluded identifier would still appear in the inject

package/lib/utils/detect-free-globals.js

@@ -93,6 +93,12 @@ export function detectFreeGlobals(code) {
     const ast = acorn.parse(code, {
         ecmaVersion: 'latest',
         sourceType: 'module',
+        // Some bundled chunks carry an embedded `#!shebang` line —
+        // notably any project bundling its own CLI gets the
+        // `#!/usr/bin/env -S gjs -m` shebang hoisted to byte 0.
+        // Acorn rejects shebangs by default; allow them so the
+        // free-globals analyzer doesn't choke on its own input.
+        allowHashBang: true,
     });
     // --- Pass 1: collect all declared names across the entire module ---
     const declaredNames = new Set();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjsify/rolldown-plugin-gjsify",
-  "version": "0.3.20",
+  "version": "0.4.0",
   "description": "Rolldown / Rollup / Vite plugin orchestrator for GJS, Node, and Browser targets",
   "type": "module",
   "main": "lib/index.js",
@@ -42,10 +42,10 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@gjsify/resolve-npm": "^0.3.20",
-    "@gjsify/rolldown-plugin-deepkit": "^0.3.20",
-    "@gjsify/rolldown-plugin-pnp": "^0.3.20",
-    "@gjsify/vite-plugin-blueprint": "^0.3.20",
+    "@gjsify/resolve-npm": "^0.4.0",
+    "@gjsify/rolldown-plugin-deepkit": "^0.4.0",
+    "@gjsify/rolldown-plugin-pnp": "^0.4.0",
+    "@gjsify/vite-plugin-blueprint": "^0.4.0",
     "@rollup/pluginutils": "^5.3.0",
     "acorn": "^8.16.0",
     "acorn-walk": "^8.3.5",
@@ -53,9 +53,13 @@
     "lightningcss": "^1.32.0"
   },
   "peerDependencies": {
+    "@gjsify/lightningcss-native": "^0.4.0",
     "rolldown": "^1.0.0-rc.18"
   },
   "peerDependenciesMeta": {
+    "@gjsify/lightningcss-native": {
+      "optional": true
+    },
     "rolldown": {
       "optional": true
     }

package/src/app/gjs.ts

@@ -26,10 +26,36 @@ import {
 } from '../plugins/rewrite-node-modules-paths.js';
 import { processStubPlugin } from '../plugins/process-stub.js';
 import { cssAsStringPlugin } from '../plugins/css-as-string.js';
-import { shebangPlugin, resolveShebangLine } from '../plugins/shebang.js';
+import { shebangPlugin, resolveShebangLine, inputShebangStripPlugin } from '../plugins/shebang.js';
 
 const _shimDir = dirname(fileURLToPath(import.meta.url));
 
+function resolveConsoleShim(): string {
+    // Preferred: relative to this module's directory. Works under the
+    // normal Node consumer flow where `_shimDir` = `<pkg>/lib/app/`.
+    const relative = resolve(_shimDir, '../shims/console-gjs.js');
+    let fs: typeof import('node:fs') | null = null;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        fs = require('node:fs') as typeof import('node:fs');
+    } catch { return relative; }
+    if (fs.existsSync(relative)) return relative;
+    // Fallback: when the orchestrator is bundled into a single .mjs
+    // (GJS-CLI self-host loop) `_shimDir` collapses to the bundle's
+    // own directory and the relative lookup misses. createRequire's
+    // resolver is `exports`-map-aware (Phase C), so the published
+    // subpath export `./shims/console-gjs` works under both Node and
+    // GJS without further walking.
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const Module = require('node:module') as typeof import('node:module');
+        const require_ = Module.createRequire(import.meta.url);
+        return require_.resolve('@gjsify/rolldown-plugin-gjsify/shims/console-gjs');
+    } catch {
+        return relative;
+    }
+}
+
 /** Resolved Rolldown configuration template + plugins for `--app gjs`. */
 export interface GjsBuildConfig {
     options: RolldownOptions;
@@ -75,8 +101,17 @@ export const setupForGjs = async (input: GjsFactoryInput): Promise<GjsBuildConfi
     const exclude = input.pluginOptions.exclude ?? [];
     const entryPoints = await globToEntryPoints(input.input, exclude);
 
+    // unicorn-magic gates its full API behind the "node" conditional
+    // exports. We deliberately omit `node` from conditionNames (some
+    // packages ship genuinely Node-only code there — see comment
+    // around `conditionNames` below). Route the package to our
+    // bundled shim so the API is reachable under --app gjs without
+    // turning on the node condition globally.
+    const unicornMagicShim = resolve(_shimDir, '../shims/unicorn-magic.js');
+
     const aliasMap = {
         ...getAliasesForGjs({ external }),
+        'unicorn-magic': unicornMagicShim,
         ...(input.pluginOptions.aliases ?? {}),
         ...(input.userAliases ?? {}),
     };
@@ -84,9 +119,16 @@ export const setupForGjs = async (input: GjsFactoryInput): Promise<GjsBuildConfi
     // The console shim replaces all `console` references with print()/printerr()-
     // based implementations that bypass GLib.log_structured() — no prefix,
     // ANSI codes work. Disabled via `pluginOptions.consoleShim === false`.
+    //
+    // Path resolution: `resolve(_shimDir, '../shims/...')` works in normal
+    // Node consumption (_shimDir = `<pkg>/lib/app/`). When the CLI is
+    // bundled into a single .mjs (e.g. the GJS-CLI self-host loop),
+    // `import.meta.url` collapses to the bundle's path and the relative
+    // resolution lands at a non-existent location. Walk up via
+    // createRequire's node_modules-aware resolver as a fallback.
     const consoleShimEnabled = input.pluginOptions.consoleShim !== false;
     const consoleShimPath = consoleShimEnabled
-        ? resolve(_shimDir, '../shims/console-gjs.js')
+        ? resolveConsoleShim()
         : null;
 
     // The auto-globals inject stub (when present) is side-effect-imported
@@ -113,6 +155,19 @@ export const setupForGjs = async (input: GjsFactoryInput): Promise<GjsBuildConfi
             mainFields: format === 'esm' ? ['browser', 'module', 'main'] : ['browser', 'main', 'module'],
             // ESM: omit 'require' — packages listing 'require' before 'import'
             // would silently route through their CJS entry.
+            //
+            // We deliberately do NOT add `'node'` here. Per Node's exports-map
+            // spec the resolver iterates keys in DECLARATION ORDER and picks
+            // the first one whose name is in `conditionNames` — the order of
+            // conditionNames itself is irrelevant. Packages like
+            // `cross-fetch-ponyfill` declare `"node"` first in their exports
+            // map and ship a Node-only entry that imports `blobFrom`/
+            // `fileFrom` (from native `node:fetch`). With `node` enabled,
+            // the resolver picks that branch over `browser` and the bundle
+            // breaks at link time. Packages that genuinely need their `node`
+            // export under GJS (rare — only one known case so far,
+            // `unicorn-magic`'s `traversePathUp`) are handled with explicit
+            // resolve aliases instead.
             conditionNames: format === 'esm' ? ['browser', 'import'] : ['browser', 'require', 'import'],
         },
         transform: {
@@ -153,6 +208,12 @@ export const setupForGjs = async (input: GjsFactoryInput): Promise<GjsBuildConfi
         // Virtual-entry plugin runs FIRST so its resolveId/load match the
         // synthetic input ids that `wrapInputWithSideEffects` produces.
         ...(virtualEntries.plugin ? [virtualEntries.plugin] : []),
+        // Strip leading #! from any input module BEFORE bundling — otherwise
+        // a shebang in e.g. the CLI's own entry file ends up embedded
+        // mid-chunk after our process-stub banner, and acorn (auto-globals
+        // detector) rejects the `#` byte. Final-output shebang is composed
+        // by shebangPlugin's renderChunk hook.
+        inputShebangStripPlugin(),
         // random-access-file's 'browser' field maps to a throwing stub; force
         // the fs-backed Node entry. Implemented via the gjsify alias plugin
         // as a direct entry-table override.

package/src/plugins/alias.ts

@@ -13,6 +13,13 @@
 //   - exact string match (no prefix-aware semantics needed at this layer)
 //   - `node:<name>` specifiers map to the same target as `<name>`
 //     (handled in the alias-builder helpers, not here).
+//
+// `extraOptions.kind` is forwarded to `this.resolve()` so package.json
+// `exports` conditions ("import" / "require") match the original call site.
+// Without this, a CJS `require('stream')` in a bundled npm package would
+// resolve through the "import" condition (Rolldown's default), bypassing the
+// `cjs-compat.cjs` shim that unwraps named-export ESM modules to their
+// constructor — breaking `util.inherits(Child, Stream)` patterns.
 
 import type { Plugin } from 'rolldown';
 
@@ -28,7 +35,7 @@ export function aliasPlugin(options: AliasPluginOptions): Plugin {
         name: 'gjsify-alias',
         resolveId: {
             order: 'pre' as const,
-            async handler(source, importer) {
+            async handler(source, importer, extraOptions) {
                 if (!Object.prototype.hasOwnProperty.call(entries, source)) {
                     return null;
                 }
@@ -39,6 +46,7 @@ export function aliasPlugin(options: AliasPluginOptions): Plugin {
 
                 const resolved = await this.resolve(target, importer, {
                     skipSelf: true,
+                    kind: extraOptions?.kind,
                 });
                 if (resolved !== null) {
                     return resolved;

package/src/plugins/css-as-string.ts

@@ -19,9 +19,22 @@
 // flattened to GTK4-CSS-engine-compatible output. Targeting is opt-in —
 // a missing `targets` keeps the source pristine.
 //
-// `lightningcss` is a regular dependency of this package; the plugin
-// imports it lazily so missing-arch installs surface the underlying
-// load error instead of crashing every gjsify build.
+// Backend selection (Phase D-2 decision matrix in
+// `docs/poc/lightningcss-decision.md`):
+//
+//   1. `@gjsify/lightningcss-native` when its prebuild is loadable on
+//      the running architecture (3-5× faster than the WASM track,
+//      ~960× faster cold init). Only relevant when `gjsify build`
+//      itself runs under GJS (Phase D-3).
+//   2. npm `lightningcss` for everything else (Node, unsupported
+//      arches, dev machines without the prebuild). Existing behavior;
+//      keeps the regular dependency on this package.
+//
+// Selection is lazy and silent — the first `.css` load probes for
+// the native bridge once, caches the answer, and routes the rest of
+// the build through the chosen backend. Set the env var
+// `GJSIFY_CSS_BACKEND={native|npm}` to force a specific backend
+// (mainly useful for benchmarking + the integration suite).
 
 import { readFile } from 'node:fs/promises';
 import type { Plugin } from 'rolldown';
@@ -44,6 +57,108 @@ export interface CssAsStringOptions {
     bundle?: boolean;
 }
 
+interface BundleResult {
+    code: Uint8Array;
+}
+
+type Bundler = (filename: string, targets: import('lightningcss').Targets | undefined) => Promise<BundleResult>;
+
+let _bundlerPromise: Promise<Bundler> | null = null;
+
+async function pickBundler(): Promise<Bundler> {
+    const forced = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env?.GJSIFY_CSS_BACKEND;
+
+    if (forced === 'npm') return loadNpmBundler();
+    if (forced === 'native') {
+        const native = await tryLoadNativeBundler();
+        if (!native) throw new Error('GJSIFY_CSS_BACKEND=native but @gjsify/lightningcss-native is not loadable');
+        return native;
+    }
+
+    const native = await tryLoadNativeBundler();
+    return native ?? loadNpmBundler();
+}
+
+// Local mirror of the @gjsify/lightningcss-native surface we touch. We
+// can't rely on the published types here because the package is an
+// OPTIONAL peer dep — under Node it's not installed, so `import type`
+// from it would break tsc on every Node consumer. Local interface
+// keeps the type narrow + decouples the plugin's typecheck from
+// whether the prebuild package is installed.
+interface NativeLightningcssSurface {
+    hasNativeLightningcss(): boolean;
+    bundle(input: {
+        filename: string;
+        targets?: string;
+        minify?: boolean;
+        sourceMap?: boolean;
+        errorRecovery?: boolean;
+    }): { code: Uint8Array; map?: Uint8Array };
+}
+
+async function tryLoadNativeBundler(): Promise<Bundler | null> {
+    // The native bridge only exists under GJS — `imports.gi` marker. Skip
+    // the dynamic import entirely on Node so it doesn't even register as a
+    // resolved dep, which would inflate the CLI's bundled output.
+    const isGjs = typeof (globalThis as { imports?: { gi?: unknown } }).imports?.gi !== 'undefined';
+    if (!isGjs) return null;
+
+    try {
+        // Indirect specifier so tsc + Rolldown don't try to resolve the
+        // optional peer dep at build time. Resolution happens only at
+        // runtime under GJS (where the prebuild is installed).
+        const specifier = '@gjsify/lightningcss-native';
+        const mod = (await import(/* @vite-ignore */ specifier)) as NativeLightningcssSurface;
+        if (!mod.hasNativeLightningcss()) return null;
+        return async (filename, targets) => {
+            // The native shim accepts a browserslist string; the npm
+            // `lightningcss` Targets struct is bitfield-encoded
+            // (`firefox: 60 << 16` etc). Convert by extracting major
+            // version per browser key and re-emitting as the equivalent
+            // browserslist query.
+            const query = targetsToBrowserslist(targets);
+            return mod.bundle({
+                filename,
+                targets: query,
+                minify: false,
+                sourceMap: false,
+                errorRecovery: true,
+            });
+        };
+    } catch {
+        return null;
+    }
+}
+
+async function loadNpmBundler(): Promise<Bundler> {
+    const { bundleAsync } = await import('lightningcss');
+    return async (filename, targets) => {
+        const result = await bundleAsync({
+            filename,
+            targets,
+            minify: false,
+            errorRecovery: true,
+        });
+        return { code: result.code };
+    };
+}
+
+function targetsToBrowserslist(
+    targets: import('lightningcss').Targets | undefined,
+): string | undefined {
+    if (!targets) return undefined;
+    const parts: string[] = [];
+    for (const [browser, encoded] of Object.entries(targets) as [string, number | undefined][]) {
+        if (typeof encoded !== 'number') continue;
+        // npm lightningcss encodes versions as `(major << 16) | (minor << 8) | patch`.
+        const major = (encoded >>> 16) & 0xff;
+        if (major === 0) continue;
+        const name = browser === 'ios_saf' ? 'ios' : browser;
+        parts.push(`${name} >= ${major}`);
+    }
+    return parts.length ? parts.join(', ') : undefined;
+}
+
 export function cssAsStringPlugin(options: CssAsStringOptions = {}): Plugin {
     const { targets, bundle = true } = options;
     return {
@@ -67,12 +182,8 @@ async function loadAndBundleCss(
     filename: string,
     targets: import('lightningcss').Targets | undefined,
 ): Promise<Uint8Array> {
-    const { bundleAsync } = await import('lightningcss');
-    const result = await bundleAsync({
-        filename,
-        targets,
-        minify: false,
-        errorRecovery: true,
-    });
-    return result.code;
+    if (!_bundlerPromise) _bundlerPromise = pickBundler();
+    const bundler = await _bundlerPromise;
+    const { code } = await bundler(filename, targets);
+    return code;
 }

package/src/plugins/shebang.ts

@@ -16,6 +16,30 @@ export interface ShebangPluginOptions {
     line?: string;
 }
 
+/**
+ * Strip a leading `#!…\n` from a source module. Rolldown preserves input
+ * shebangs verbatim, which ends up embedded mid-chunk after our process-stub
+ * banner — acorn (used by the auto-globals detector) then rejects `#` because
+ * it's not at byte 0 anymore. Stripping at the transform stage cleans both
+ * the analysis bundle and the final bundle; the gjsify-shebang renderChunk
+ * step then injects the correct line for the output target.
+ */
+const SHEBANG_RE = /^#![^\n]*\n/;
+
+/** Always-on plugin half: strips input shebangs regardless of output options. */
+export function inputShebangStripPlugin(): Plugin {
+    return {
+        name: 'gjsify-input-shebang-strip',
+        transform: {
+            order: 'pre' as const,
+            handler(code) {
+                if (!code.startsWith('#!')) return null;
+                return { code: code.replace(SHEBANG_RE, ''), map: null };
+            },
+        },
+    };
+}
+
 export function shebangPlugin(options: ShebangPluginOptions = {}): Plugin | null {
     if (!options.enabled) return null;
     const line = options.line ?? GJS_SHEBANG;

package/src/shims/unicorn-magic.ts

@@ -0,0 +1,75 @@
+// Shim for `unicorn-magic` under --app gjs.
+//
+// The upstream package gates the full API (`toPath`, `traversePathUp`,
+// `rootDirectory`, `execFile`, `execFileSync`) behind the `"node"`
+// conditional exports entry. Under --app gjs we intentionally omit
+// the `node` resolve-condition (cross-fetch-ponyfill ships
+// Node-only code under that key — see `app/gjs.ts` conditionNames
+// comment), so a bare `import { toPath } from 'unicorn-magic'` falls
+// back to `default.js` which only exposes `delay`.
+//
+// This shim mirrors the node.js entry verbatim — the underlying
+// `node:url`/`node:path`/`node:child_process`/`node:util` imports
+// route through `@gjsify/{url,path,child_process,util}` under GJS
+// and through real Node-internals under Node. The aliasPlugin
+// points `unicorn-magic` here for --app gjs builds.
+//
+// Source-of-truth: refs/unicorn-magic/node.js (when added — for
+// now mirrored from node_modules/unicorn-magic@0.3.0).
+
+import { promisify } from 'node:util';
+import { execFile as execFileCallback, execFileSync as execFileSyncOriginal } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const execFileOriginal = promisify(execFileCallback);
+
+export function toPath(urlOrPath) {
+    return urlOrPath instanceof URL ? fileURLToPath(urlOrPath) : urlOrPath;
+}
+
+export function rootDirectory(pathInput) {
+    return path.parse(toPath(pathInput)).root;
+}
+
+export function traversePathUp(startPath) {
+    return {
+        *[Symbol.iterator]() {
+            let currentPath = path.resolve(toPath(startPath));
+            let previousPath;
+
+            while (previousPath !== currentPath) {
+                yield currentPath;
+                previousPath = currentPath;
+                currentPath = path.resolve(currentPath, '..');
+            }
+        },
+    };
+}
+
+const TEN_MEGABYTES_IN_BYTES = 10 * 1024 * 1024;
+
+export async function execFile(file, arguments_, options = {}) {
+    return execFileOriginal(file, arguments_, {
+        maxBuffer: TEN_MEGABYTES_IN_BYTES,
+        ...options,
+    });
+}
+
+export function execFileSync(file, arguments_ = [], options = {}) {
+    return execFileSyncOriginal(file, arguments_, {
+        maxBuffer: TEN_MEGABYTES_IN_BYTES,
+        ...options,
+    });
+}
+
+// Re-export from default.js so the union API (delay + node helpers)
+// stays intact for callers that import both.
+export async function delay(opts: { seconds?: number; milliseconds?: number } = {}): Promise<void> {
+    const { seconds, milliseconds } = opts;
+    let duration: number;
+    if (typeof seconds === 'number') duration = seconds * 1000;
+    else if (typeof milliseconds === 'number') duration = milliseconds;
+    else throw new TypeError('Expected an object with either `seconds` or `milliseconds`.');
+    return new Promise<void>((resolveFn) => setTimeout(resolveFn, duration));
+}

package/src/utils/auto-globals.ts

@@ -18,7 +18,41 @@
 // alias `globalThis` to a short variable and defeat MemberExpression
 // detection in detect-free-globals.ts.
 
-import { rolldown, type InputOptions, type OutputChunk, type RolldownPluginOption, type TransformOptions } from 'rolldown';
+import type { InputOptions, RolldownPluginOption, TransformOptions } from 'rolldown';
+
+/**
+ * In-memory bundle function — returns the per-entry chunk code strings.
+ * Implementations: npm rolldown (Node default), `@gjsify/rolldown-native`
+ * (GJS). Pulled out so auto-globals can run under either engine without
+ * hardcoding npm rolldown (which can't load under GJS — the Rust prebuild's
+ * init code uses `require('node:fs')` synchronously).
+ *
+ * The default impl below dynamically imports npm rolldown; the CLI
+ * overrides this from `actions/build.ts` to route via the same engine the
+ * final build uses.
+ */
+export type AnalysisBundler = (input: {
+    rolldownInput: InputOptions;
+    format: 'esm' | 'cjs' | 'iife';
+}) => Promise<string[]>;
+
+const defaultBundler: AnalysisBundler = async ({ rolldownInput, format }) => {
+    // Indirect specifier so the GJS bundle doesn't pull npm rolldown in
+    // statically. Only reached when the caller doesn't override (Node).
+    const specifier = 'rolldown';
+    const mod = (await import(/* @vite-ignore */ specifier)) as typeof import('rolldown');
+    const build = await mod.rolldown(rolldownInput);
+    try {
+        const result = await build.generate({ format, minify: false, sourcemap: false });
+        const codes: string[] = [];
+        for (const entry of result.output) {
+            if (entry.type === 'chunk') codes.push(entry.code);
+        }
+        return codes;
+    } finally {
+        await build.close();
+    }
+};
 import { detectFreeGlobals } from './detect-free-globals.js';
 import { resolveGlobalsList, writeRegisterInjectFile } from './scan-globals.js';
 import { GJS_GLOBALS_MAP } from '@gjsify/resolve-npm/globals-map';
@@ -139,6 +173,7 @@ export async function detectAutoGlobals(
     gjsifyPluginFactory: GjsifyPluginFactory,
     verbose?: boolean,
     options: DetectAutoGlobalsOptions = {},
+    bundler: AnalysisBundler = defaultBundler,
 ): Promise<AutoGlobalsResult> {
     const extraRegisterPaths = options.extraGlobalsList
         ? resolveGlobalsList(options.extraGlobalsList)
@@ -178,29 +213,18 @@ export async function detectAutoGlobals(
             ? appendInjectAsEntry(analysisOptions.input, currentInject)
             : analysisOptions.input;
 
-        const build = await rolldown({
-            input: inputWithInject,
-            external: analysisOptions.external,
-            resolve: analysisOptions.resolve,
-            transform: analysisOptions.transform,
-            plugins: [...callerPlugins, gjsifyInstance],
-            logLevel: 'silent',
+        const chunkCodes = await bundler({
+            rolldownInput: {
+                input: inputWithInject,
+                external: analysisOptions.external,
+                resolve: analysisOptions.resolve,
+                transform: analysisOptions.transform,
+                plugins: [...callerPlugins, gjsifyInstance],
+                logLevel: 'silent',
+            },
+            format: analysisOptions.format ?? 'esm',
         });
 
-        const chunkCodes: string[] = [];
-        try {
-            const result = await build.generate({
-                format: analysisOptions.format ?? 'esm',
-                minify: false,
-                sourcemap: false,
-            });
-            for (const entry of result.output) {
-                if (entry.type === 'chunk') chunkCodes.push((entry as OutputChunk).code);
-            }
-        } finally {
-            await build.close();
-        }
-
         if (chunkCodes.length === 0) {
             return { detected: new Set(), injectPath: currentInject };
         }
@@ -211,8 +235,22 @@ export async function detectAutoGlobals(
         // top-level declarations: `File`, `Buffer`, …) that acorn can't
         // parse. Per-chunk parsing keeps each chunk's lexical scope intact.
         const newDetected = new Set<string>();
-        for (const code of chunkCodes) {
-            for (const id of detectFreeGlobals(code)) newDetected.add(id);
+        for (let i = 0; i < chunkCodes.length; i++) {
+            const code = chunkCodes[i] ?? '';
+            try {
+                for (const id of detectFreeGlobals(code)) newDetected.add(id);
+            } catch (e) {
+                if ((globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env?.GJSIFY_DEBUG_AUTO_GLOBALS) {
+                    const path = `/tmp/gjsify-auto-globals-failed-chunk-${i}.mjs`;
+                    try {
+                        // eslint-disable-next-line @typescript-eslint/no-require-imports
+                        const fs = await import('node:fs');
+                        fs.writeFileSync(path, code);
+                        console.error(`[gjsify-auto-globals] parse failed on chunk #${i} — wrote ${path} for inspection`);
+                    } catch { /* ignore */ }
+                }
+                throw e;
+            }
         }
 
         // Apply excludeGlobals BEFORE writing the next iteration's inject file.

package/src/utils/detect-free-globals.ts

@@ -101,6 +101,12 @@ export function detectFreeGlobals(code: string): Set<string> {
     const ast = acorn.parse(code, {
         ecmaVersion: 'latest',
         sourceType: 'module',
+        // Some bundled chunks carry an embedded `#!shebang` line —
+        // notably any project bundling its own CLI gets the
+        // `#!/usr/bin/env -S gjs -m` shebang hoisted to byte 0.
+        // Acorn rejects shebangs by default; allow them so the
+        // free-globals analyzer doesn't choke on its own input.
+        allowHashBang: true,
     });
 
     // --- Pass 1: collect all declared names across the entire module ---