@gjsify/rolldown-plugin-gjsify 0.3.14 → 0.3.16

package/lib/app/gjs.d.ts

@@ -19,8 +19,13 @@ export interface GjsFactoryInput {
     userBanner?: string;
     /** User-supplied resolve.alias overrides. */
     userAliases?: Record<string, string>;
-    /** Whether to prepend the `#!/usr/bin/env -S gjs -m` shebang. */
-    shebang?: boolean;
+    /**
+     * Shebang to prepend to the output bundle.
+     *   `true`  → default `#!/usr/bin/env -S gjs -m`
+     *   `false` → no shebang
+     *   `"…"`   → custom line, supports `${env:NAME[:-default]}` placeholders
+     */
+    shebang?: boolean | string;
     /** Plugin options forwarded to sub-plugins (deepkit, css, …). */
     pluginOptions: PluginOptions;
 }

package/lib/app/gjs.js

@@ -2,7 +2,7 @@
 //
 // Mirrors the esbuild predecessor's `setupForGjs` exactly in terms of the
 // effective build behaviour: same externals, same alias map, same target
-// (firefox128 for JS, firefox60 for CSS), same console-shim injection,
+// (firefox140 for JS, firefox60 for CSS), same console-shim injection,
 // same process-stub banner, same `random-access-file` fs-backed-fallback.
 //
 // Returns a partial `RolldownOptions` template plus the plugin array the
@@ -18,7 +18,7 @@ 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, GJS_SHEBANG } from '../plugins/shebang.js';
+import { shebangPlugin, resolveShebangLine } from '../plugins/shebang.js';
 const _shimDir = dirname(fileURLToPath(import.meta.url));
 export const setupForGjs = async (input) => {
     const userExternal = input.userExternal ?? [];
@@ -75,8 +75,8 @@ export const setupForGjs = async (input) => {
             conditionNames: format === 'esm' ? ['browser', 'import'] : ['browser', 'require', 'import'],
         },
         transform: {
-            // Compile target: GJS 1.86 / SpiderMonkey 128 ≈ firefox128.
-            target: 'firefox128',
+            // Compile target: GJS 1.86 / SpiderMonkey 140 ≈ firefox140.
+            target: 'firefox140',
             define: {
                 global: 'globalThis',
                 window: 'globalThis',
@@ -122,10 +122,19 @@ export const setupForGjs = async (input) => {
         }),
         blueprintPlugin(),
         deepkitPlugin({ reflection: input.pluginOptions.reflection }),
-        cssAsStringPlugin(),
+        // GTK4's CSS engine is much older than browser engines — its
+        // parser predates nesting + many modern selectors. Targeting
+        // `firefox: 60 << 16` makes lightningcss flatten the source
+        // into the subset GTK4 understands.
+        cssAsStringPlugin({ targets: { firefox: 60 << 16 } }),
         nodeModulesPathRewritePlugin({ bundleDir }),
         processStubPlugin({ userBanner: input.userBanner }),
-        shebangPlugin({ enabled: input.shebang === true, line: GJS_SHEBANG }),
+        // resolveShebangLine returns null when disabled (false/undefined) and
+        // the resolved line otherwise — also handles `${env:…}` expansion.
+        (() => {
+            const line = resolveShebangLine(input.shebang);
+            return shebangPlugin({ enabled: line !== null, line: line ?? undefined });
+        })(),
     ];
     return { options, plugins };
 };

package/lib/index.d.ts

@@ -7,7 +7,9 @@ export type { NodeModulesPathRewriteOptions, RewriteResult, } from './plugins/re
 export { processStubPlugin, GJS_PROCESS_STUB, composeBanner } from './plugins/process-stub.js';
 export type { ProcessStubPluginOptions } from './plugins/process-stub.js';
 export { cssAsStringPlugin } from './plugins/css-as-string.js';
-export { shebangPlugin, GJS_SHEBANG } from './plugins/shebang.js';
+export { textLoaderPlugin } from './plugins/text-loader.js';
+export type { TextLoaderPluginOptions } from './plugins/text-loader.js';
+export { shebangPlugin, GJS_SHEBANG, expandEnvTemplate, resolveShebangLine } from './plugins/shebang.js';
 export type { ShebangPluginOptions } from './plugins/shebang.js';
 export { gjsImportsEmptyPlugin } from './plugins/gjs-imports-empty.js';
 export * from './plugin.js';

package/lib/index.js

@@ -6,7 +6,8 @@ export * from './library/index.js';
 export { REWRITE_FILTER, getBundleDirFromOutput, rewriteContents, shouldRewrite, nodeModulesPathRewritePlugin, } from './plugins/rewrite-node-modules-paths.js';
 export { processStubPlugin, GJS_PROCESS_STUB, composeBanner } from './plugins/process-stub.js';
 export { cssAsStringPlugin } from './plugins/css-as-string.js';
-export { shebangPlugin, GJS_SHEBANG } from './plugins/shebang.js';
+export { textLoaderPlugin } from './plugins/text-loader.js';
+export { shebangPlugin, GJS_SHEBANG, expandEnvTemplate, resolveShebangLine } from './plugins/shebang.js';
 export { gjsImportsEmptyPlugin } from './plugins/gjs-imports-empty.js';
 export * from './plugin.js';
 import { gjsifyPlugin } from './plugin.js';

package/lib/plugin.d.ts

@@ -13,8 +13,13 @@ export interface GjsifyPluginInput {
     userExternal?: string[];
     userBanner?: string;
     userAliases?: Record<string, string>;
-    /** Whether to prepend `#!/usr/bin/env -S gjs -m` to the GJS bundle. */
-    shebang?: boolean;
+    /**
+     * Shebang to prepend to the GJS bundle.
+     *   `true`  → default `#!/usr/bin/env -S gjs -m`
+     *   `false` → no shebang
+     *   `"…"`   → custom line, supports `${env:NAME[:-default]}` placeholders
+     */
+    shebang?: boolean | string;
 }
 /**
  * Build the Rolldown configuration template + plugin array for the given

package/lib/plugins/css-as-string.d.ts

@@ -1,2 +1,19 @@
 import type { Plugin } from 'rolldown';
-export declare function cssAsStringPlugin(): Plugin;
+export interface CssAsStringOptions {
+    /**
+     * lightningcss browser targets passed to `bundleAsync`. When set,
+     * nesting + modern syntax are lowered for the given engines. The
+     * GJS orchestrator defaults this to `{ firefox: 60 << 16 }` to
+     * match the GTK4 CSS parser. Omit or leave undefined to skip
+     * lowering (output stays as-authored except for `@import` inlining).
+     */
+    targets?: import('lightningcss').Targets;
+    /**
+     * When true (default), `@import` statements are resolved by
+     * lightningcss `bundleAsync`. Set false to fall back to a plain
+     * `readFile` — useful only when you want to keep `@import` strings
+     * verbatim in the bundled JS (rare).
+     */
+    bundle?: boolean;
+}
+export declare function cssAsStringPlugin(options?: CssAsStringOptions): Plugin;

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

@@ -12,18 +12,27 @@
 //
 // — the canonical pattern for `Gtk.CssProvider` under GJS.
 //
-// `@import` resolution is left to the user / CSS preprocessor. For simple
-// app CSS this is fine; for @import-heavy CSS, run a preprocessor (e.g.
-// sass / postcss) ahead of `gjsify build` so the input file is already
-// flat.
+// `@import` resolution + nesting/modern-syntax lowering are handled via
+// lightningcss `bundleAsync`. The defaults work for the common case
+// (resolve `@import`s, no targeting); 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.
+//
+// `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.
 import { readFile } from 'node:fs/promises';
-export function cssAsStringPlugin() {
+export function cssAsStringPlugin(options = {}) {
+    const { targets, bundle = true } = options;
     return {
         name: 'gjsify-css-as-string',
         load: {
             filter: { id: /\.css$/ },
             async handler(id) {
-                const code = await readFile(id, 'utf8');
+                const code = bundle
+                    ? new TextDecoder('utf-8').decode(await loadAndBundleCss(id, targets))
+                    : await readFile(id, 'utf8');
                 return {
                     code: `export default ${JSON.stringify(code)};`,
                     moduleType: 'js',
@@ -32,3 +41,13 @@ export function cssAsStringPlugin() {
         },
     };
 }
+async function loadAndBundleCss(filename, targets) {
+    const { bundleAsync } = await import('lightningcss');
+    const result = await bundleAsync({
+        filename,
+        targets,
+        minify: false,
+        errorRecovery: true,
+    });
+    return result.code;
+}

package/lib/plugins/shebang.d.ts

@@ -6,3 +6,25 @@ export interface ShebangPluginOptions {
     line?: string;
 }
 export declare function shebangPlugin(options?: ShebangPluginOptions): Plugin | null;
+/**
+ * Expand `${env:NAME}` and `${env:NAME:-default}` placeholders against
+ * `process.env`. Missing without default → `''`. Used to let the shebang
+ * config field reference build-time env vars (e.g. `GJS_CONSOLE` set by
+ * meson-driven Flatpak builds where the GJS interpreter lives at
+ * `/usr/bin/gjs-console`).
+ */
+export declare function expandEnvTemplate(input: string, env?: Record<string, string | undefined>): string;
+/**
+ * Normalize the user-facing `shebang` config value into the literal line
+ * that should be prepended to the bundle (without trailing newline), or
+ * `null` when shebang injection is disabled.
+ *
+ *   `true`            → default GJS shebang
+ *   `false|undefined` → null (disabled)
+ *   `"…"`             → string with `${env:NAME[:-default]}` expanded
+ *
+ * If the resolved string does not start with `#!`, it is prefixed
+ * automatically so users can write `"shebang": "/usr/bin/gjs -m"` instead
+ * of `"#!/usr/bin/gjs -m"`.
+ */
+export declare function resolveShebangLine(value: boolean | string | undefined): string | null;

package/lib/plugins/shebang.js

@@ -24,3 +24,41 @@ export function shebangPlugin(options = {}) {
         },
     };
 }
+/**
+ * Expand `${env:NAME}` and `${env:NAME:-default}` placeholders against
+ * `process.env`. Missing without default → `''`. Used to let the shebang
+ * config field reference build-time env vars (e.g. `GJS_CONSOLE` set by
+ * meson-driven Flatpak builds where the GJS interpreter lives at
+ * `/usr/bin/gjs-console`).
+ */
+export function expandEnvTemplate(input, env = process.env) {
+    return input.replace(/\$\{env:([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g, (_match, name, fallback) => {
+        const value = env[name];
+        if (value !== undefined && value !== '')
+            return value;
+        return fallback ?? '';
+    });
+}
+/**
+ * Normalize the user-facing `shebang` config value into the literal line
+ * that should be prepended to the bundle (without trailing newline), or
+ * `null` when shebang injection is disabled.
+ *
+ *   `true`            → default GJS shebang
+ *   `false|undefined` → null (disabled)
+ *   `"…"`             → string with `${env:NAME[:-default]}` expanded
+ *
+ * If the resolved string does not start with `#!`, it is prefixed
+ * automatically so users can write `"shebang": "/usr/bin/gjs -m"` instead
+ * of `"#!/usr/bin/gjs -m"`.
+ */
+export function resolveShebangLine(value) {
+    if (value === undefined || value === false)
+        return null;
+    if (value === true)
+        return GJS_SHEBANG;
+    const expanded = expandEnvTemplate(value);
+    if (!expanded.trim())
+        return null;
+    return expanded.startsWith('#!') ? expanded : '#!' + expanded;
+}

package/lib/plugins/text-loader.d.ts

@@ -0,0 +1,10 @@
+import type { Plugin } from 'rolldown';
+export interface TextLoaderPluginOptions {
+    /**
+     * Map of file extension (with leading `.`) → loader kind. Currently only
+     * `'text'` is implemented; the field is shaped this way to leave room
+     * for `'json'` / `'binary'` later without a config break.
+     */
+    loaders?: Record<string, 'text'>;
+}
+export declare function textLoaderPlugin(options?: TextLoaderPluginOptions): Plugin | null;

package/lib/plugins/text-loader.js

@@ -0,0 +1,41 @@
+// Generic "load file as JS string default export" plugin.
+//
+// Mirrors `css-as-string` but lets the user opt-in arbitrary extensions
+// through `bundler.loaders` config, e.g.:
+//
+//   "bundler": { "loaders": { ".ui": "text", ".asm": "text" } }
+//
+// — replaces the esbuild `loader: { '.ui': 'text' }` shorthand from the
+// pre-Rolldown era. Rolldown does not classify unknown extensions as text
+// by default; without a hook it tries to parse them as JS and fails.
+import { readFile } from 'node:fs/promises';
+export function textLoaderPlugin(options = {}) {
+    const exts = Object.entries(options.loaders ?? {})
+        .filter(([, kind]) => kind === 'text')
+        .map(([ext]) => ext);
+    if (exts.length === 0)
+        return null;
+    // Build a single regex matching any of the configured extensions:
+    //   ['.ui', '.asm'] → /\.(ui|asm)$/
+    const escaped = exts.map((e) => e.replace(/^\./, '').replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+    const filter = new RegExp(`\\.(?:${escaped.join('|')})$`);
+    // Use the function-form `load(id)` (Rollup-compatible) rather than the
+    // newer `load: { filter, handler }` shape. The newer shape was observed
+    // not to claim unknown-extension files reliably under Rolldown rc.18 —
+    // Rolldown's parser ran BEFORE the filtered handler fired and rejected
+    // `.ui`/`.asm` content as invalid JS/JSX. Using the function form (same
+    // as `@gjsify/vite-plugin-blueprint`'s `.blp` hook) intercepts during
+    // module-load lookup and works under both Vite and Rolldown.
+    return {
+        name: 'gjsify-text-loader',
+        async load(id) {
+            if (!filter.test(id))
+                return null;
+            const code = await readFile(id, 'utf8');
+            return {
+                code: `export default ${JSON.stringify(code)};`,
+                moduleType: 'js',
+            };
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjsify/rolldown-plugin-gjsify",
-  "version": "0.3.14",
+  "version": "0.3.16",
   "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.14",
-    "@gjsify/rolldown-plugin-deepkit": "^0.3.14",
-    "@gjsify/rolldown-plugin-pnp": "^0.3.14",
-    "@gjsify/vite-plugin-blueprint": "^0.3.14",
+    "@gjsify/resolve-npm": "^0.3.16",
+    "@gjsify/rolldown-plugin-deepkit": "^0.3.16",
+    "@gjsify/rolldown-plugin-pnp": "^0.3.16",
+    "@gjsify/vite-plugin-blueprint": "^0.3.16",
     "@rollup/pluginutils": "^5.1.4",
     "acorn": "^8.14.0",
     "acorn-walk": "^8.3.4",

package/src/app/gjs.ts

@@ -2,7 +2,7 @@
 //
 // Mirrors the esbuild predecessor's `setupForGjs` exactly in terms of the
 // effective build behaviour: same externals, same alias map, same target
-// (firefox128 for JS, firefox60 for CSS), same console-shim injection,
+// (firefox140 for JS, firefox60 for CSS), same console-shim injection,
 // same process-stub banner, same `random-access-file` fs-backed-fallback.
 //
 // Returns a partial `RolldownOptions` template plus the plugin array the
@@ -26,7 +26,7 @@ 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, GJS_SHEBANG } from '../plugins/shebang.js';
+import { shebangPlugin, resolveShebangLine } from '../plugins/shebang.js';
 
 const _shimDir = dirname(fileURLToPath(import.meta.url));
 
@@ -47,8 +47,13 @@ export interface GjsFactoryInput {
     userBanner?: string;
     /** User-supplied resolve.alias overrides. */
     userAliases?: Record<string, string>;
-    /** Whether to prepend the `#!/usr/bin/env -S gjs -m` shebang. */
-    shebang?: boolean;
+    /**
+     * Shebang to prepend to the output bundle.
+     *   `true`  → default `#!/usr/bin/env -S gjs -m`
+     *   `false` → no shebang
+     *   `"…"`   → custom line, supports `${env:NAME[:-default]}` placeholders
+     */
+    shebang?: boolean | string;
     /** Plugin options forwarded to sub-plugins (deepkit, css, …). */
     pluginOptions: PluginOptions;
 }
@@ -111,8 +116,8 @@ export const setupForGjs = async (input: GjsFactoryInput): Promise<GjsBuildConfi
             conditionNames: format === 'esm' ? ['browser', 'import'] : ['browser', 'require', 'import'],
         },
         transform: {
-            // Compile target: GJS 1.86 / SpiderMonkey 128 ≈ firefox128.
-            target: 'firefox128',
+            // Compile target: GJS 1.86 / SpiderMonkey 140 ≈ firefox140.
+            target: 'firefox140',
             define: {
                 global: 'globalThis',
                 window: 'globalThis',
@@ -160,10 +165,19 @@ export const setupForGjs = async (input: GjsFactoryInput): Promise<GjsBuildConfi
         }),
         blueprintPlugin() as RolldownPluginOption,
         deepkitPlugin({ reflection: input.pluginOptions.reflection }),
-        cssAsStringPlugin(),
+        // GTK4's CSS engine is much older than browser engines — its
+        // parser predates nesting + many modern selectors. Targeting
+        // `firefox: 60 << 16` makes lightningcss flatten the source
+        // into the subset GTK4 understands.
+        cssAsStringPlugin({ targets: { firefox: 60 << 16 } }),
         nodeModulesPathRewritePlugin({ bundleDir }),
         processStubPlugin({ userBanner: input.userBanner }),
-        shebangPlugin({ enabled: input.shebang === true, line: GJS_SHEBANG }),
+        // resolveShebangLine returns null when disabled (false/undefined) and
+        // the resolved line otherwise — also handles `${env:…}` expansion.
+        (() => {
+            const line = resolveShebangLine(input.shebang);
+            return shebangPlugin({ enabled: line !== null, line: line ?? undefined });
+        })(),
     ];
 
     return { options, plugins };

package/src/index.ts

@@ -20,7 +20,9 @@ export type {
 export { processStubPlugin, GJS_PROCESS_STUB, composeBanner } from './plugins/process-stub.js';
 export type { ProcessStubPluginOptions } from './plugins/process-stub.js';
 export { cssAsStringPlugin } from './plugins/css-as-string.js';
-export { shebangPlugin, GJS_SHEBANG } from './plugins/shebang.js';
+export { textLoaderPlugin } from './plugins/text-loader.js';
+export type { TextLoaderPluginOptions } from './plugins/text-loader.js';
+export { shebangPlugin, GJS_SHEBANG, expandEnvTemplate, resolveShebangLine } from './plugins/shebang.js';
 export type { ShebangPluginOptions } from './plugins/shebang.js';
 export { gjsImportsEmptyPlugin } from './plugins/gjs-imports-empty.js';
 

package/src/plugin.ts

@@ -27,8 +27,13 @@ export interface GjsifyPluginInput {
     userExternal?: string[];
     userBanner?: string;
     userAliases?: Record<string, string>;
-    /** Whether to prepend `#!/usr/bin/env -S gjs -m` to the GJS bundle. */
-    shebang?: boolean;
+    /**
+     * Shebang to prepend to the GJS bundle.
+     *   `true`  → default `#!/usr/bin/env -S gjs -m`
+     *   `false` → no shebang
+     *   `"…"`   → custom line, supports `${env:NAME[:-default]}` placeholders
+     */
+    shebang?: boolean | string;
 }
 
 /**

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

@@ -12,21 +12,48 @@
 //
 // — the canonical pattern for `Gtk.CssProvider` under GJS.
 //
-// `@import` resolution is left to the user / CSS preprocessor. For simple
-// app CSS this is fine; for @import-heavy CSS, run a preprocessor (e.g.
-// sass / postcss) ahead of `gjsify build` so the input file is already
-// flat.
+// `@import` resolution + nesting/modern-syntax lowering are handled via
+// lightningcss `bundleAsync`. The defaults work for the common case
+// (resolve `@import`s, no targeting); 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.
+//
+// `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.
 
 import { readFile } from 'node:fs/promises';
 import type { Plugin } from 'rolldown';
 
-export function cssAsStringPlugin(): Plugin {
+export interface CssAsStringOptions {
+    /**
+     * lightningcss browser targets passed to `bundleAsync`. When set,
+     * nesting + modern syntax are lowered for the given engines. The
+     * GJS orchestrator defaults this to `{ firefox: 60 << 16 }` to
+     * match the GTK4 CSS parser. Omit or leave undefined to skip
+     * lowering (output stays as-authored except for `@import` inlining).
+     */
+    targets?: import('lightningcss').Targets;
+    /**
+     * When true (default), `@import` statements are resolved by
+     * lightningcss `bundleAsync`. Set false to fall back to a plain
+     * `readFile` — useful only when you want to keep `@import` strings
+     * verbatim in the bundled JS (rare).
+     */
+    bundle?: boolean;
+}
+
+export function cssAsStringPlugin(options: CssAsStringOptions = {}): Plugin {
+    const { targets, bundle = true } = options;
     return {
         name: 'gjsify-css-as-string',
         load: {
             filter: { id: /\.css$/ },
             async handler(id: string) {
-                const code = await readFile(id, 'utf8');
+                const code = bundle
+                    ? new TextDecoder('utf-8').decode(await loadAndBundleCss(id, targets))
+                    : await readFile(id, 'utf8');
                 return {
                     code: `export default ${JSON.stringify(code)};`,
                     moduleType: 'js' as const,
@@ -35,3 +62,17 @@ export function cssAsStringPlugin(): Plugin {
         },
     };
 }
+
+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;
+}

package/src/plugins/shebang.ts

@@ -31,3 +31,39 @@ export function shebangPlugin(options: ShebangPluginOptions = {}): Plugin | null
         },
     };
 }
+
+/**
+ * Expand `${env:NAME}` and `${env:NAME:-default}` placeholders against
+ * `process.env`. Missing without default → `''`. Used to let the shebang
+ * config field reference build-time env vars (e.g. `GJS_CONSOLE` set by
+ * meson-driven Flatpak builds where the GJS interpreter lives at
+ * `/usr/bin/gjs-console`).
+ */
+export function expandEnvTemplate(input: string, env: Record<string, string | undefined> = process.env): string {
+    return input.replace(/\$\{env:([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g, (_match, name: string, fallback?: string) => {
+        const value = env[name];
+        if (value !== undefined && value !== '') return value;
+        return fallback ?? '';
+    });
+}
+
+/**
+ * Normalize the user-facing `shebang` config value into the literal line
+ * that should be prepended to the bundle (without trailing newline), or
+ * `null` when shebang injection is disabled.
+ *
+ *   `true`            → default GJS shebang
+ *   `false|undefined` → null (disabled)
+ *   `"…"`             → string with `${env:NAME[:-default]}` expanded
+ *
+ * If the resolved string does not start with `#!`, it is prefixed
+ * automatically so users can write `"shebang": "/usr/bin/gjs -m"` instead
+ * of `"#!/usr/bin/gjs -m"`.
+ */
+export function resolveShebangLine(value: boolean | string | undefined): string | null {
+    if (value === undefined || value === false) return null;
+    if (value === true) return GJS_SHEBANG;
+    const expanded = expandEnvTemplate(value);
+    if (!expanded.trim()) return null;
+    return expanded.startsWith('#!') ? expanded : '#!' + expanded;
+}

package/src/plugins/text-loader.ts

@@ -0,0 +1,54 @@
+// Generic "load file as JS string default export" plugin.
+//
+// Mirrors `css-as-string` but lets the user opt-in arbitrary extensions
+// through `bundler.loaders` config, e.g.:
+//
+//   "bundler": { "loaders": { ".ui": "text", ".asm": "text" } }
+//
+// — replaces the esbuild `loader: { '.ui': 'text' }` shorthand from the
+// pre-Rolldown era. Rolldown does not classify unknown extensions as text
+// by default; without a hook it tries to parse them as JS and fails.
+
+import { readFile } from 'node:fs/promises';
+import type { Plugin } from 'rolldown';
+
+export interface TextLoaderPluginOptions {
+    /**
+     * Map of file extension (with leading `.`) → loader kind. Currently only
+     * `'text'` is implemented; the field is shaped this way to leave room
+     * for `'json'` / `'binary'` later without a config break.
+     */
+    loaders?: Record<string, 'text'>;
+}
+
+export function textLoaderPlugin(options: TextLoaderPluginOptions = {}): Plugin | null {
+    const exts = Object.entries(options.loaders ?? {})
+        .filter(([, kind]) => kind === 'text')
+        .map(([ext]) => ext);
+
+    if (exts.length === 0) return null;
+
+    // Build a single regex matching any of the configured extensions:
+    //   ['.ui', '.asm'] → /\.(ui|asm)$/
+    const escaped = exts.map((e) => e.replace(/^\./, '').replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+    const filter = new RegExp(`\\.(?:${escaped.join('|')})$`);
+
+    // Use the function-form `load(id)` (Rollup-compatible) rather than the
+    // newer `load: { filter, handler }` shape. The newer shape was observed
+    // not to claim unknown-extension files reliably under Rolldown rc.18 —
+    // Rolldown's parser ran BEFORE the filtered handler fired and rejected
+    // `.ui`/`.asm` content as invalid JS/JSX. Using the function form (same
+    // as `@gjsify/vite-plugin-blueprint`'s `.blp` hook) intercepts during
+    // module-load lookup and works under both Vite and Rolldown.
+    return {
+        name: 'gjsify-text-loader',
+        async load(id: string) {
+            if (!filter.test(id)) return null;
+            const code = await readFile(id, 'utf8');
+            return {
+                code: `export default ${JSON.stringify(code)};`,
+                moduleType: 'js' as const,
+            };
+        },
+    };
+}