@gjsify/rolldown-plugin-gjsify 0.36.0 → 0.38.0

package/lib/app/node.d.ts

@@ -1,27 +1,20 @@
 import type { RolldownOptions, RolldownPluginOption } from 'rolldown';
 import type { PluginOptions } from '../types/plugin-options.js';
 /**
- * Reverse-bridge register routing: a node build of a GENUINE GJS SOURCE needs
- * the REAL `@gjsify/*` register bodies (document, HTMLCanvasElement, the `'2d'`
- * context factory, matchMedia, …) running over `@gjsify/node-gi`, not the
- * default `@gjsify/empty` stubs that keep CROSS-PLATFORM node bundles loadable
- * on plain Node.
- *
- * Applied by `setupForNode` when `isGjsSourceBuild` is true — see the comment
- * on that flag for why BOTH reverse-bridge signals qualify, not just the
- * explicit `--globals` stub.
+ * Reverse-bridge register routing: a node build of a GENUINE GJS SOURCE needs the
+ * REAL `@gjsify/*` register bodies (document, HTMLCanvasElement, the `'2d'` context
+ * factory, matchMedia, …) over `@gjsify/node-gi`, not the default `@gjsify/empty`
+ * stubs that keep CROSS-PLATFORM node bundles loadable on plain Node.
  *
  * Two adjustments over the standard node alias map:
- *  1. every `<pkg>/register…` → `@gjsify/empty` entry is DROPPED so the
- *     register import resolves to its real body;
- *  2. the gjs target's bare→scoped register routes (`fetch/register/fetch` →
- *     `@gjsify/fetch/register/fetch`, `xmlhttprequest/register` →
+ *  1. every `<pkg>/register…` → `@gjsify/empty` entry is DROPPED so the register
+ *     import resolves to its real body;
+ *  2. the gjs target's bare→scoped register routes (`xmlhttprequest/register` →
  *     `@gjsify/fetch/register/xhr`, …) are merged in so the inject stub's bare
  *     specifiers resolve on node exactly as they do on gjs.
  *
- * Applied to the BASE map only — `pluginOptions.aliases` / user aliases still
- * override. On a non-reverse-bridge build the map is untouched (the plain-Node
- * loadability guarantee for cross-platform packages is not regressed).
+ * Applied to the BASE map only, when `isGjsSourceBuild` — `pluginOptions.aliases` /
+ * user aliases still override, and a non-reverse-bridge build is untouched.
  */
 export declare function enableGjsRegistersForNode(baseAliases: Record<string, string>): Record<string, string>;
 /**
@@ -30,34 +23,31 @@ export declare function enableGjsRegistersForNode(baseAliases: Record<string, st
  *
  * Two signals qualify, and BOTH must gate the same things:
  *  - `nodeGiGlobalsInject` — the CLI's post-tree-shake detection found bare GJS
- *    ambient globals (`print`/`imports`/`ARGV`/…) OR a static
- *    `@gjsify/node-gi/*` import (the externalised spelling of the bare
- *    `system`/`gettext`/`cairo` built-ins) in the bundled output;
- *  - `registerInject` (the `--globals` auto/explicit inject stub) — the user
- *    asked for GJS registers on the node target explicitly.
+ *    ambient globals (`print`/`imports`/`ARGV`/…) or a static `@gjsify/node-gi/*`
+ *    import (the externalised spelling of the bare built-ins) in the output;
+ *  - `registerInject` — the `--globals` inject stub, i.e. the user asked for GJS
+ *    registers on the node target explicitly.
  *
- * This predicate exists as ONE named function because the two consumers used to
- * ask the question separately and disagree: `emitGirs` took the union while the
- * register-alias lift took only the explicit stub. A reverse-bridge build then
- * got its `@girs/*` routed through to `requireGi` while a `/register`
- * side-effect import in the SAME graph was still emptied to `@gjsify/empty` —
- * silently dropping `@gjsify/dom-elements/register/canvas`'s `'2d'` context
- * factory, so `@gjsify/canvas2d`'s `Canvas2DBridge` never fired `onReady`.
+ * ONE named function because the two consumers used to ask separately and
+ * disagree: with `emitGirs` taking the union and the register-alias lift taking
+ * only the explicit stub, a reverse-bridge build got `@girs/*` routed to
+ * `requireGi` while a `/register` import in the SAME graph was still emptied to
+ * `@gjsify/empty` — silently dropping `@gjsify/dom-elements/register/canvas`'s
+ * `'2d'` context factory, so `@gjsify/canvas2d`'s `Canvas2DBridge` never fired
+ * `onReady`.
  *
- * A build with NEITHER signal is byte-unchanged: the `@gjsify/empty` register
- * routing and the `@girs/*` emptying both stay, so a cross-platform package's
- * node bundle keeps loading on plain Node without node-gi installed.
+ * A build with NEITHER signal is byte-unchanged: register routing and `@girs/*`
+ * emptying both stay, so a cross-platform package's node bundle keeps loading on
+ * plain Node without node-gi installed.
  *
- * KNOWN NARROWNESS (pre-dates this predicate, tracked in status/open-todos.md): the
- * `nodeGiGlobalsInject` detector keys on bare ambient globals + static
- * `@gjsify/node-gi/*` imports, so a genuine GJS source whose ONLY platform
- * reach is `gi://` (no ambient global, no bare `system`/`gettext`/`cairo`) is
- * still not recognised — its `@girs/*` AND its registers are both emptied. A
- * surviving `gi://` import CANNOT simply become a third signal: its shim loads
- * node-gi lazily precisely so a gjs-gated `gi://` import in a cross-platform
- * package keeps that package's node bundle loadable on plain Node (#641,
- * pinned by `tests/e2e/node-gi-globals-inject`), and injecting the eager
- * globals shim for it would break exactly that.
+ * KNOWN NARROWNESS (tracked in status/open-todos.md): a genuine GJS source whose
+ * ONLY platform reach is `gi://` (no ambient global, no bare built-in) is not
+ * recognised — its `@girs/*` and its registers are both emptied. A surviving
+ * `gi://` import cannot simply become a third signal: its shim loads node-gi
+ * lazily precisely so a gjs-gated `gi://` import keeps a cross-platform package's
+ * node bundle loadable on plain Node (#641, pinned by
+ * `tests/e2e/node-gi-globals-inject`), and injecting the eager globals shim would
+ * break exactly that.
  */
 export declare function isGjsSourceBuild(options: {
     nodeGiGlobalsInject?: boolean;

package/lib/app/node.js

@@ -1,9 +1,4 @@
 // `--app node` Rolldown configuration factory.
-//
-// Same external set + alias map as the esbuild predecessor. The
-// `createRequire` banner that esbuild needed for ESM-output CJS interop
-// translates to Rolldown's `output.banner` directly — Rolldown itself does
-// not synthesise a `require()` shim for ESM consumers of bundled CJS code.
 import { aliasPlugin } from '../plugins/alias.js';
 import blueprintPlugin from '@gjsify/vite-plugin-blueprint';
 import { deepkitPlugin } from '@gjsify/rolldown-plugin-deepkit';
@@ -18,60 +13,46 @@ import { unresolvedWorkspaceImportPlugin } from '../plugins/unresolved-workspace
 import { wrapInputWithSideEffects } from '../utils/entry-wrapper.js';
 /**
  * Side-effect specifier the node target injects when GJS ambient globals
- * (`print`/`imports`/…) are detected in the bundled output. Importing it seeds
- * those globals on `globalThis` via the node-gi backend. Kept EXTERNAL (see the
- * external set below) — it loads the native addon and must never be bundled.
+ * (`print`/`imports`/…) are detected in the bundled output; importing it seeds
+ * them on `globalThis` via the node-gi backend. Kept EXTERNAL — it loads the
+ * native addon and must never be bundled.
  */
 const NODE_GI_GLOBALS_SPECIFIER = '@gjsify/node-gi/globals';
 /**
- * The node-gi standalone GJS built-in modules. The bare `system` / `gettext` /
- * `cairo` specifiers a GJS source imports are aliased to these (via
- * `ALIASES_GJS_FOR_NODE`, applied node-target-only by `gjsBuiltinModulesNodePlugin`)
- * and, like `@gjsify/node-gi/gi`, kept EXTERNAL — they load the native node-gi
- * backend and must resolve at runtime against the consumer's node_modules, never
- * be bundled.
+ * The node-gi standalone GJS built-in modules — the targets `ALIASES_GJS_FOR_NODE`
+ * rewrites a GJS source's bare `system`/`gettext`/`cairo` imports to (node-target
+ * only, via `gjsBuiltinModulesNodePlugin`). Kept EXTERNAL like
+ * `@gjsify/node-gi/gi`: they load the native node-gi backend and must resolve at
+ * runtime against the consumer's node_modules.
  *
- * DERIVED from `ALIASES_GJS_FOR_NODE`'s VALUES so this set can never drift from
- * the alias map again — a new bare built-in added there is externalised
- * automatically. That completeness is LOAD-BEARING under `@gjsify/rolldown-native`
- * (the GJS bundler engine): its JSON options boundary silently DROPS the resolveId
- * `{ external: true }` flag that `gjsBuiltinModulesNodePlugin` returns (only the
- * plain `external` string array survives serialization — the same reason
- * `app/gjs.ts` routes its externals through a resolveId hook AND filters the array).
- * So the rewritten `@gjsify/node-gi/<mod>` target stays external ONLY if it is in
- * this array. `@gjsify/node-gi/cairo` was previously MISSING here (only `system` +
- * `gettext` were listed), so under the GJS bundler `cairo` was left as a bare,
- * unresolvable specifier — breaking every Cairo/PangoCairo consumer
- * (`@gjsify/canvas2d-core`) built via the reverse bridge. Under npm `rolldown`
- * (Node) the resolveId `external` flag IS honoured, so the gap was invisible until
- * a Cairo consumer was built on the GJS bundler. e2e: `tests/e2e/node-gi-build`;
- * unit: `packages/infra/cli/src/node-gi-externals.spec.ts`.
+ * DERIVED from the alias map's VALUES so the two cannot drift. That completeness
+ * is LOAD-BEARING under `@gjsify/rolldown-native`: its JSON options boundary drops
+ * the resolveId `{ external: true }` flag `gjsBuiltinModulesNodePlugin` returns
+ * (only the plain `external` string array survives), so a rewritten
+ * `@gjsify/node-gi/<mod>` stays external ONLY if it is in this array. A hardcoded
+ * list missing `cairo` left it bare and unresolvable under the GJS bundler,
+ * breaking every Cairo/PangoCairo reverse-bridge consumer — invisible under npm
+ * `rolldown`, which does honour the flag. e2e `tests/e2e/node-gi-build`; unit
+ * `packages/infra/cli/src/node-gi-externals.spec.ts`.
  */
 const NODE_GI_BARE_MODULE_SPECIFIERS = Object.values(ALIASES_GJS_FOR_NODE);
 /** Matches a register subpath in an alias key: `<pkg>/register` or `<pkg>/register/<feature>`. */
 const REGISTER_SUBPATH_RE = /\/register(\/|$)/;
 /**
- * Reverse-bridge register routing: a node build of a GENUINE GJS SOURCE needs
- * the REAL `@gjsify/*` register bodies (document, HTMLCanvasElement, the `'2d'`
- * context factory, matchMedia, …) running over `@gjsify/node-gi`, not the
- * default `@gjsify/empty` stubs that keep CROSS-PLATFORM node bundles loadable
- * on plain Node.
- *
- * Applied by `setupForNode` when `isGjsSourceBuild` is true — see the comment
- * on that flag for why BOTH reverse-bridge signals qualify, not just the
- * explicit `--globals` stub.
+ * Reverse-bridge register routing: a node build of a GENUINE GJS SOURCE needs the
+ * REAL `@gjsify/*` register bodies (document, HTMLCanvasElement, the `'2d'` context
+ * factory, matchMedia, …) over `@gjsify/node-gi`, not the default `@gjsify/empty`
+ * stubs that keep CROSS-PLATFORM node bundles loadable on plain Node.
  *
  * Two adjustments over the standard node alias map:
- *  1. every `<pkg>/register…` → `@gjsify/empty` entry is DROPPED so the
- *     register import resolves to its real body;
- *  2. the gjs target's bare→scoped register routes (`fetch/register/fetch` →
- *     `@gjsify/fetch/register/fetch`, `xmlhttprequest/register` →
+ *  1. every `<pkg>/register…` → `@gjsify/empty` entry is DROPPED so the register
+ *     import resolves to its real body;
+ *  2. the gjs target's bare→scoped register routes (`xmlhttprequest/register` →
  *     `@gjsify/fetch/register/xhr`, …) are merged in so the inject stub's bare
  *     specifiers resolve on node exactly as they do on gjs.
  *
- * Applied to the BASE map only — `pluginOptions.aliases` / user aliases still
- * override. On a non-reverse-bridge build the map is untouched (the plain-Node
- * loadability guarantee for cross-platform packages is not regressed).
+ * Applied to the BASE map only, when `isGjsSourceBuild` — `pluginOptions.aliases` /
+ * user aliases still override, and a non-reverse-bridge build is untouched.
  */
 export function enableGjsRegistersForNode(baseAliases) {
     const out = {};
@@ -92,74 +73,53 @@ export function enableGjsRegistersForNode(baseAliases) {
  *
  * Two signals qualify, and BOTH must gate the same things:
  *  - `nodeGiGlobalsInject` — the CLI's post-tree-shake detection found bare GJS
- *    ambient globals (`print`/`imports`/`ARGV`/…) OR a static
- *    `@gjsify/node-gi/*` import (the externalised spelling of the bare
- *    `system`/`gettext`/`cairo` built-ins) in the bundled output;
- *  - `registerInject` (the `--globals` auto/explicit inject stub) — the user
- *    asked for GJS registers on the node target explicitly.
+ *    ambient globals (`print`/`imports`/`ARGV`/…) or a static `@gjsify/node-gi/*`
+ *    import (the externalised spelling of the bare built-ins) in the output;
+ *  - `registerInject` — the `--globals` inject stub, i.e. the user asked for GJS
+ *    registers on the node target explicitly.
  *
- * This predicate exists as ONE named function because the two consumers used to
- * ask the question separately and disagree: `emitGirs` took the union while the
- * register-alias lift took only the explicit stub. A reverse-bridge build then
- * got its `@girs/*` routed through to `requireGi` while a `/register`
- * side-effect import in the SAME graph was still emptied to `@gjsify/empty` —
- * silently dropping `@gjsify/dom-elements/register/canvas`'s `'2d'` context
- * factory, so `@gjsify/canvas2d`'s `Canvas2DBridge` never fired `onReady`.
+ * ONE named function because the two consumers used to ask separately and
+ * disagree: with `emitGirs` taking the union and the register-alias lift taking
+ * only the explicit stub, a reverse-bridge build got `@girs/*` routed to
+ * `requireGi` while a `/register` import in the SAME graph was still emptied to
+ * `@gjsify/empty` — silently dropping `@gjsify/dom-elements/register/canvas`'s
+ * `'2d'` context factory, so `@gjsify/canvas2d`'s `Canvas2DBridge` never fired
+ * `onReady`.
  *
- * A build with NEITHER signal is byte-unchanged: the `@gjsify/empty` register
- * routing and the `@girs/*` emptying both stay, so a cross-platform package's
- * node bundle keeps loading on plain Node without node-gi installed.
+ * A build with NEITHER signal is byte-unchanged: register routing and `@girs/*`
+ * emptying both stay, so a cross-platform package's node bundle keeps loading on
+ * plain Node without node-gi installed.
  *
- * KNOWN NARROWNESS (pre-dates this predicate, tracked in status/open-todos.md): the
- * `nodeGiGlobalsInject` detector keys on bare ambient globals + static
- * `@gjsify/node-gi/*` imports, so a genuine GJS source whose ONLY platform
- * reach is `gi://` (no ambient global, no bare `system`/`gettext`/`cairo`) is
- * still not recognised — its `@girs/*` AND its registers are both emptied. A
- * surviving `gi://` import CANNOT simply become a third signal: its shim loads
- * node-gi lazily precisely so a gjs-gated `gi://` import in a cross-platform
- * package keeps that package's node bundle loadable on plain Node (#641,
- * pinned by `tests/e2e/node-gi-globals-inject`), and injecting the eager
- * globals shim for it would break exactly that.
+ * KNOWN NARROWNESS (tracked in status/open-todos.md): a genuine GJS source whose
+ * ONLY platform reach is `gi://` (no ambient global, no bare built-in) is not
+ * recognised — its `@girs/*` and its registers are both emptied. A surviving
+ * `gi://` import cannot simply become a third signal: its shim loads node-gi
+ * lazily precisely so a gjs-gated `gi://` import keeps a cross-platform package's
+ * node bundle loadable on plain Node (#641, pinned by
+ * `tests/e2e/node-gi-globals-inject`), and injecting the eager globals shim would
+ * break exactly that.
  */
 export function isGjsSourceBuild(options) {
     return Boolean(options.nodeGiGlobalsInject || options.registerInject);
 }
 export const setupForNode = async (input) => {
     const userExternal = input.userExternal ?? [];
-    // node-datachannel is a native C++ addon that cannot be bundled — its
-    // `require('../build/Release/node_datachannel.node')` must resolve at
-    // runtime against the real node_modules tree.
+    // node-datachannel and `@gjsify/node-gi` are native addons that cannot be
+    // bundled — their loaders resolve a `.node` binary relative to their own
+    // installed location, so both must stay external.
     //
-    // GJS-specific specifiers (`gi://*`, `@girs/*`) are NOT externalised —
-    // `gi://*` is rewritten to `requireGi` by `gjsGiNodePlugin`, and `@girs/*`
-    // is handled by `gjsGiNodePlugin` + `gjsImportsEmptyPlugin` (both in the
-    // plugins array below). Marking them external would leave bare
-    // `import 'gi://Gio?version=2.0'` strings in the output that Node's default
-    // ESM loader rejects with `ERR_UNSUPPORTED_ESM_URL_SCHEME`. For a
-    // cross-platform package the `@girs/*` empty-module redirect makes node
-    // bundles (which transitively import @girs/* via *.gjs.spec / direct
-    // internal imports) loadable on Node — the GJS-only code paths are still
-    // gated at runtime by `on('Gjs', …)` or `typeof globalThis.imports` guards.
-    // For a GENUINE GJS source built via the node-gi reverse bridge (detected
-    // by `nodeGiGlobalsInject`) the `@girs/*` empty redirect is OFF so the
-    // namespace resolves through to `requireGi` — see the plugins array.
-    // `@gjsify/node-gi` is the Axis-5 GI runtime the `gjsGiNodePlugin` rewrites
-    // `gi://` onto. It is a native (node-gyp) addon whose loader resolves its
-    // `.node` binary relative to its own installed location, so it must NOT be
-    // bundled — keep it external so the `import … from '@gjsify/node-gi/gi'` the
-    // virtual shim emits resolves at runtime against the consumer's node_modules.
+    // GJS-specific specifiers (`gi://*`, `@girs/*`) are deliberately NOT
+    // externalised: `gjsGiNodePlugin` rewrites `gi://` to `requireGi`, and
+    // `@girs/*` is handled by `gjsGiNodePlugin` + `gjsImportsEmptyPlugin`.
+    // Externalising them would leave bare `import 'gi://Gio?version=2.0'` in the
+    // output, which Node's ESM loader rejects with
+    // `ERR_UNSUPPORTED_ESM_URL_SCHEME`.
     const exactExternal = [
         ...EXTERNALS_NODE,
         'node-datachannel',
         '@gjsify/node-gi',
         '@gjsify/node-gi/gi',
-        // The GJS-ambient-globals shim (auto-injected below when `print`/
-        // `imports`/… are referenced). Like `@gjsify/node-gi/gi` it loads the
-        // native addon and must resolve at runtime, never be bundled.
         NODE_GI_GLOBALS_SPECIFIER,
-        // The node-gi standalone GJS built-in modules (`system`/`gettext`),
-        // reached when the alias layer rewrites the bare specifiers. Kept
-        // external for the same reason as the gi/globals shims above.
         ...NODE_GI_BARE_MODULE_SPECIFIERS,
         ...userExternal,
     ];
@@ -173,16 +133,11 @@ export const setupForNode = async (input) => {
     const format = input.pluginOptions.format ?? 'esm';
     const exclude = input.pluginOptions.exclude ?? [];
     const entryPoints = await globToEntryPoints(input.input, exclude);
-    // When the CLI's pre-build detection (`detectNodeGiGlobals`) recognised a
-    // genuine GJS source (bare ambient globals OR a static `@gjsify/node-gi/*`
-    // import in the bundled output), wrap the entry so it side-effect imports
-    // the node-gi globals shim BEFORE the user code runs. The import is
-    // injected ONLY when detected — a bundle that neither touches
-    // `print`/`imports` nor retains a bare `system`/`gettext`/`cairo` import
-    // stays free of `@gjsify/node-gi/globals`, so it loads on plain Node
-    // without node-gi installed (the eager-native-load regression guard, same
-    // lesson as the lazy `gi://` shim in #641). Reuses the SAME virtual-entry
-    // wrapper the GJS `--globals auto` machinery uses.
+    // When `detectNodeGiGlobals` recognised a genuine GJS source, wrap the entry
+    // so it side-effect imports the node-gi globals shim before user code runs —
+    // ONLY then, so an undetected bundle stays free of `@gjsify/node-gi/globals`
+    // and loads on plain Node without node-gi installed (the eager-native-load
+    // guard, same lesson as the lazy `gi://` shim in #641).
     const sideEffectImports = [];
     if (input.pluginOptions.nodeGiGlobalsInject)
         sideEffectImports.push(NODE_GI_GLOBALS_SPECIFIER);
@@ -194,35 +149,9 @@ export const setupForNode = async (input) => {
         sideEffectImports.push(registerInject);
     const virtualEntries = wrapInputWithSideEffects(entryPoints, sideEffectImports);
     const finalInput = virtualEntries.input;
-    /**
-     * Is this a GENUINE GJS SOURCE built via the node-gi reverse bridge (as
-     * opposed to a cross-platform package's plain-Node bundle)?
-     *
-     * TWO signals answer that ONE question and both must count:
-     *
-     *  - `nodeGiGlobalsInject` — the CLI detected BARE GJS ambient globals
-     *    (`print`/`imports`/`ARGV`) or a static `@gjsify/node-gi/*` import
-     *    (a retained bare `system`/`gettext`/`cairo` built-in) in the
-     *    tree-shaken output. Only genuine GJS source has those (the detector
-     *    deliberately ignores the `globalThis.imports` isomorphic-guard shape).
-     *  - `autoGlobalsInject` — the user named EXPLICIT `--globals` (e.g.
-     *    `--globals auto,dom`), i.e. asked for the DOM surface on Node.
-     *
-     * Both already gate `emptyGirs` below. The register routing used to consult
-     * ONLY the explicit stub, and that asymmetry was a
-     * bug: a reverse-bridge build got its `@girs/*` value imports routed
-     * through to `requireGi` while a `/register` side-effect import in the very
-     * same graph was still emptied to `@gjsify/empty`. It surfaced as
-     * `@gjsify/canvas2d`'s `Canvas2DBridge` silently losing the `'2d'` context
-     * factory (`@gjsify/dom-elements/register/canvas` → empty → `getContext('2d')`
-     * null → `onReady` never fires) on a plain `gjsify build … --app node`, with
-     * no `--globals` flag anywhere — guarded by the node-gi
-     * `test/canvas2d-bridge.test.mjs` golden.
-     *
-     * A build with NEITHER signal is byte-unchanged: the `@gjsify/empty`
-     * register routing stays, so a cross-platform package's node bundle keeps
-     * loading on plain Node without node-gi installed.
-     */
+    // Gates both the register-alias lift and `emptyGirs` below — see the
+    // predicate's doc comment. The node-gi golden `test/canvas2d-bridge.test.mjs`
+    // pins the asymmetry it fixed.
     const gjsSourceBuild = isGjsSourceBuild({ ...input.pluginOptions, registerInject });
     const baseAliases = getAliasesForNode({ external });
     const aliasMap = {
@@ -235,42 +164,29 @@ export const setupForNode = async (input) => {
     // promise the alias layer made.
     const aliasEntries = flattenAliases(aliasMap);
     const bundleDir = getBundleDirFromOutput(input.output);
-    // Rolldown's CJS interop wraps bundled CJS via `__commonJSMin` and
-    // routes external Node-builtin `require()` through `__require` —
-    // both injected internally. Unlike esbuild we therefore don't need a
-    // top-of-bundle `const require = createRequire(...)` shim. Keeping
-    // one collides with bundled CJS sources that declare their own
-    // `const require = createRequire(...)` (e.g. yargs's ESM platform
-    // shim) — `SyntaxError: Identifier 'require' has already been
-    // declared`.
+    // No banner on purpose: Rolldown injects its own CJS interop (`__commonJSMin`,
+    // `__require`), so a top-of-bundle `const require = createRequire(...)` is both
+    // unnecessary and harmful — it collides with bundled CJS sources declaring
+    // their own (yargs's ESM platform shim): `SyntaxError: Identifier 'require'
+    // has already been declared`.
     const banner = undefined;
     const options = {
         input: finalInput,
         platform: 'node',
-        // Pass the EXACT-MATCH external set as a plain string array, NOT the
-        // `external` predicate function. `@gjsify/rolldown-native` ships the
-        // whole options object to its Rust core via `JSON.stringify` — a
-        // function value does not survive serialization (it is silently
-        // dropped), so a function `external` is honoured under npm rolldown
-        // (Node) but IGNORED under native rolldown (GJS), leaving
-        // `node-datachannel` (and the rest of EXTERNALS_NODE) bundled. That
-        // descends into node-datachannel's `require('…/node_datachannel.node')`
-        // and fails the `--app node` build with `Module not found`. The
-        // predicate here is pure exact membership, so the array is
-        // behaviourally identical under both engines AND JSON-serializable.
-        // (The gjs target follows the same rule: exact names as an array,
-        // plus an `externalsPlugin` resolveId hook for its gi://-prefix and
-        // register-subpath shape rules — see app/gjs.ts. The browser target
-        // already uses a plain array.)
-        // The function form is still used for `getAliasesForNode({ external })`
-        // above — that runs in-process and is never serialized.
+        // A plain string array, never the `external` predicate function:
+        // `@gjsify/rolldown-native` JSON.stringify's the options to its Rust core,
+        // so a function value is silently dropped and every `EXTERNALS_NODE` entry
+        // gets bundled — the build then descends into node-datachannel's
+        // `require('…/node_datachannel.node')` and fails with `Module not found`.
+        // Exact membership makes the array behaviourally identical on both engines.
+        // The function form survives only for `getAliasesForNode({ external })`,
+        // which runs in-process and is never serialized.
         external: exactExternal,
         resolve: {
             mainFields: format === 'esm' ? ['module', 'main', 'browser'] : ['main', 'module', 'browser'],
-            // CJS-priority conditions for Node bundles. Rolldown uses the first
-            // matching key, so including 'import' would route packages like ws
-            // v8 (whose exports map lists 'import' before 'require') through
-            // their incomplete ESM wrapper.
+            // CJS-priority conditions. Rolldown takes the package's first matching
+            // key, so adding 'import' would route ws v8 (which lists 'import'
+            // before 'require') through its incomplete ESM wrapper.
             conditionNames: format === 'esm' ? ['require', 'node', 'module'] : ['require'],
         },
         transform: {
@@ -285,76 +201,57 @@ export const setupForNode = async (input) => {
             format,
             sourcemap: false,
             banner,
-            // Single-bundle output. `codeSplitting: false` replaces the
-            // deprecated `inlineDynamicImports: true`.
+            // Single-bundle output.
             codeSplitting: false,
         },
         treeshake: true,
     };
     const plugins = [
-        // Virtual-entry plugin runs FIRST so its resolveId/load match the
-        // synthetic `\0gjsify-entry:` ids that `wrapInputWithSideEffects`
-        // produces (no-op when nothing was injected).
+        // Virtual-entry plugin runs FIRST so its resolveId/load match the synthetic
+        // `\0gjsify-entry:` ids `wrapInputWithSideEffects` produces (no-op when
+        // nothing was injected).
         ...(virtualEntries.plugin ? [virtualEntries.plugin] : []),
-        // gjsGiNodePlugin runs FIRST (resolveId order 'pre' + array order): it
-        // claims `gi://Ns?version=X` and rewrites it to the `@gjsify/node-gi`
-        // runtime, so a real GJS/GI source builds + runs on Node. It returns
-        // null for `@girs/*`.
+        // Claims `gi://Ns?version=X` (resolveId `pre` + array order) and rewrites it
+        // onto the `@gjsify/node-gi` runtime so a real GJS/GI source builds and runs
+        // on Node. Returns null for `@girs/*`.
         gjsGiNodePlugin(),
-        // Bare GJS built-in modules (`system`/`gettext`/`cairo`): claimed BEFORE
-        // the aliasPlugin so they resolve to the EXTERNAL `@gjsify/node-gi/<mod>`
-        // shims without a disk resolution (works without node-gi installed,
-        // like gi://). Node-target-only — never active on gjs/browser/ns. The
-        // externalisation itself rides `NODE_GI_BARE_MODULE_SPECIFIERS` in the
-        // `exactExternal` array (the resolveId `external` flag is dropped under
-        // @gjsify/rolldown-native — see that const's doc-comment).
+        // Bare GJS built-ins: claimed BEFORE aliasPlugin so they resolve to the
+        // EXTERNAL `@gjsify/node-gi/<mod>` shims without touching disk (works
+        // without node-gi installed, like gi://). Node-target-only. The
+        // externalisation itself rides `NODE_GI_BARE_MODULE_SPECIFIERS` in
+        // `exactExternal` — see that const's doc comment.
         gjsBuiltinModulesNodePlugin(ALIASES_GJS_FOR_NODE),
-        // gjsImportsEmptyPlugin then decides the fate of `@girs/*` before
-        // `aliasPlugin` and the default resolver. Same composition order as
-        // `app/browser.ts`. `emptyGirs` is GATED on `nodeGiGlobalsInject`:
-        //   • false-flag (default Node build) → `@girs/*` → empty module. A
-        //     cross-platform polyfill package whose GJS-only code paths import
-        //     `@girs/*` transitively (e.g. via `@gjsify/unit`) stays loadable on
-        //     plain Node WITHOUT node-gi installed — exactly the existing
-        //     behaviour, never regressed.
-        //   • node-gi build (`nodeGiGlobalsInject` true — the genuine-GJS-source
-        //     signal) → `@girs/<ns>-<ver>` falls through to its real package
-        //     body (`import Adw from 'gi://Adw?version=1'; export default Adw`),
-        //     whose inner `gi://` is rewritten to `requireGi` by gjsGiNodePlugin
-        //     above. This routes `@girs/adw-1` → `requireGi('Adw','1')` WITHOUT
-        //     a lowercased-pkg→namespace map (the proper-cased namespace comes
-        //     from the @girs package's own `gi://` specifier). `gi://*` is
-        //     already claimed by gjsGiNodePlugin, so this plugin's `gi://`
-        //     branch is dead on the node target either way.
-        // `emptyGirs` also lifts for the explicit-register reverse-bridge case:
-        // the injected register bodies (dom-elements, canvas2d, …) are genuine
-        // GJS code whose `@girs/*` value imports must route through to
-        // `requireGi`, exactly like the ambient-globals case. Same predicate as
-        // the register-alias lift above — one question, one flag.
+        // Decides the fate of `@girs/*` before `aliasPlugin` and the default
+        // resolver (same composition order as `app/browser.ts`). `emptyGirs` is
+        // gated on `gjsSourceBuild`:
+        //   • plain Node build → `@girs/*` → empty module, so a cross-platform
+        //     polyfill whose GJS-only paths import `@girs/*` transitively (e.g. via
+        //     `@gjsify/unit`) stays loadable without node-gi installed.
+        //   • reverse-bridge build → `@girs/<ns>-<ver>` falls through to its real
+        //     package body (`import Adw from 'gi://Adw?version=1'`), whose inner
+        //     `gi://` gjsGiNodePlugin already rewrote — so `@girs/adw-1` reaches
+        //     `requireGi('Adw','1')` with no lowercased-pkg→namespace map needed.
+        //     This plugin's own `gi://` branch is dead on the node target.
         gjsImportsEmptyPlugin({ emptyGirs: !gjsSourceBuild }),
         aliasPlugin({ entries: aliasEntries }),
-        // Blueprint (.blp → XML string): the reverse bridge runs REAL GTK on
-        // Node, so a GJS app entry (composite-template windows) must build for
-        // `--app node` too. Only claims `.blp` files — inert for plain-Node
-        // bundles. Same plugin the gjs/browser targets compose.
+        // Blueprint (.blp → XML string): the reverse bridge runs REAL GTK on Node,
+        // so a GJS app entry with composite-template windows must build for
+        // `--app node` too. Claims only `.blp` — inert for plain-Node bundles.
         blueprintPlugin(),
         deepkitPlugin({ reflection: input.pluginOptions.reflection }),
-        // CSS-as-string. For a node-gi build (the reverse bridge runs REAL GTK on
-        // Node — `nodeGiGlobalsInject`, the same signal that keeps `@girs/*` bodies
-        // above), lower the CSS to GTK 4's subset with `firefox: 60 << 16` — exactly
-        // as `--app gjs` does — so modern authoring (nesting, `&`, …) is FLATTENED
-        // before it reaches `Gtk.CssProvider.load_from_string`. Without this GTK 4's
-        // CSS parser rejects nested rules at runtime ("Expected ';'/an identifier"
-        // theme-parser warnings, styles silently dropped — the Learn6502 app-gnome
-        // symptom). A plain-Node bundle (no node-gi) keeps the CSS pristine.
+        // On a node-gi build (REAL GTK on Node) lower the CSS to GTK 4's subset just
+        // as `--app gjs` does, so nesting/`&` is FLATTENED before it reaches
+        // `Gtk.CssProvider.load_from_string` — GTK 4's parser otherwise rejects
+        // nested rules at runtime and silently drops the styles (the Learn6502
+        // app-gnome symptom). A plain-Node bundle keeps the CSS pristine.
         cssAsStringPlugin(input.pluginOptions.nodeGiGlobalsInject ? { targets: { firefox: 60 << 16 } } : {}),
         nodeModulesPathRewritePlugin({ bundleDir }),
-        // `order: 'post'` — fires only for ids nothing above claimed, i.e. the
-        // ones headed for Rolldown's unresolved-import → external fallback. The
-        // node target has no `node:`-shaped symptom for the emit-time guard to
-        // detect (its `node:` builtins ARE external by policy), so this is the
-        // ONLY thing standing between an unbuilt `@gjsify/*` workspace edge and
-        // a bundle that re-imports the bare specifier at runtime.
+        // `order: 'post'` — fires only for ids headed to Rolldown's
+        // unresolved-import → external fallback. The node target has no
+        // `node:`-shaped symptom the emit-time guard could detect (its `node:`
+        // builtins ARE external by policy), so this is the ONLY thing between an
+        // unbuilt `@gjsify/*` workspace edge and a bundle that re-imports the bare
+        // specifier at runtime.
         unresolvedWorkspaceImportPlugin({ target: 'node', aliases: aliasEntries, isExternal: external }),
     ];
     return { options, plugins };

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

@@ -331,8 +331,16 @@ let _sassPromise = null;
 async function compileSass(filename) {
     if (!_sassPromise) {
         // Lazy + indirect specifier so `sass` is only resolved when a Sass file
-        // is actually imported (mirrors the lazy lightningcss backend). The
-        // `dart-sass` JS API is pure JS, so it loads under GJS + Node alike.
+        // is actually imported (mirrors the lazy lightningcss backend).
+        //
+        // NODE ONLY — this comment used to claim "loads under GJS + Node alike".
+        // Measured on 0.37.0: under GJS it rejects with `Module not found: sass` — a
+        // BARE specifier resolved at RUNTIME is what GJS's ESM loader cannot do, so
+        // `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
+        // (#1053). dart-sass DOES run under GJS: `adwaita-web`'s `build:scss` does.
         _sassPromise = import(/* @vite-ignore */ 'sass');
     }
     try {