@gjsify/rolldown-plugin-gjsify 0.41.0 → 0.43.0

package/lib/app/browser.d.ts

@@ -1,6 +1,8 @@
 import type { RolldownOptions, RolldownPluginOption } from 'rolldown';
 import type { PluginOptions } from '../types/plugin-options.js';
 export interface BrowserBuildConfig {
+    /** Transforms that must see the ORIGINAL source; composed before the caller's plugins. */
+    prePlugins: RolldownPluginOption[];
     options: RolldownOptions;
     plugins: RolldownPluginOption[];
 }

package/lib/app/browser.js

@@ -86,11 +86,13 @@ export const setupForBrowser = async (input) => {
     // the unresolved-workspace-import guard below so the guard reports the same
     // promise the alias layer made.
     const aliasEntries = flattenAliases(aliasMap);
+    // Reflection reads the ORIGINAL TypeScript, so it runs before any user
+    // transform can strip the annotations out from under it (see `GjsifyConfig`).
+    const prePlugins = [deepkitPlugin({ reflection: input.pluginOptions.reflection })];
     const plugins = [
         gjsImportsEmptyPlugin(),
         aliasPlugin({ entries: aliasEntries }),
         blueprintPlugin(),
-        deepkitPlugin({ reflection: input.pluginOptions.reflection }),
         cssAsStringPlugin(),
         // `order: 'post'` — see app/gjs.ts. The browser target's whole job is to
         // replace Node builtins with their `@gjsify/*` browser entries; when one
@@ -103,7 +105,7 @@ export const setupForBrowser = async (input) => {
             isExternal: (id) => external.includes(id),
         }),
     ];
-    return { options, plugins };
+    return { options, prePlugins, plugins };
 };
 function flattenAliases(map) {
     const out = {};

package/lib/app/gjs.d.ts

@@ -1,7 +1,10 @@
 import type { RolldownOptions, RolldownPluginOption } from 'rolldown';
 import type { PluginOptions } from '../types/plugin-options.js';
+import type { GiSystemProbe } from '../plugins/gi-runtime-paths.js';
 /** Resolved Rolldown configuration template + plugins for `--app gjs`. */
 export interface GjsBuildConfig {
+    /** Transforms that must see the ORIGINAL source; composed before the caller's plugins. */
+    prePlugins: RolldownPluginOption[];
     options: RolldownOptions;
     plugins: RolldownPluginOption[];
 }
@@ -26,6 +29,13 @@ export interface GjsFactoryInput {
      *   `"…"`   → custom line, supports `${env:NAME[:-default]}` placeholders
      */
     shebang?: boolean | string;
+    /**
+     * System GI library dirs the byte-1 prologue tries at RUNTIME — see `GiSystemProbe`.
+     * The only half a build can honestly fill: the build machine is not the host that
+     * runs the bundle, so what travels is a candidate plus the markers that decide it
+     * there. See `GjsifyPluginInput.giSystemProbes` for why the relative half is absent.
+     */
+    giSystemProbes?: readonly GiSystemProbe[];
     /** Plugin options forwarded to sub-plugins (deepkit, css, …). */
     pluginOptions: PluginOptions;
 }

package/lib/app/gjs.js

@@ -158,6 +158,9 @@ export const setupForGjs = async (input) => {
         'random-access-file': 'random-access-file/index.js',
         ...flattenAliases(aliasMap),
     };
+    // Reflection reads the ORIGINAL TypeScript, so it runs before any user
+    // transform can strip the annotations out from under it (see `GjsifyConfig`).
+    const prePlugins = [deepkitPlugin({ reflection: input.pluginOptions.reflection })];
     const plugins = [
         // Virtual-entry plugin runs FIRST so its resolveId/load match the
         // synthetic input ids that `wrapInputWithSideEffects` produces.
@@ -184,14 +187,17 @@ export const setupForGjs = async (input) => {
         // first.
         externalsPlugin(external, { name: 'gjsify-gjs-externalize' }),
         blueprintPlugin(),
-        deepkitPlugin({ reflection: input.pluginOptions.reflection }),
         // 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, runtimeResolve: format === 'esm' }),
-        processStubPlugin({ userBanner: input.userBanner, captureBundleUrl: format === 'esm' }),
+        processStubPlugin({
+            userBanner: input.userBanner,
+            captureBundleUrl: format === 'esm',
+            giSystemProbes: input.giSystemProbes,
+        }),
         // resolveShebangLine returns null when disabled, else the resolved line
         // with `${env:…}` expanded.
         (() => {
@@ -205,9 +211,16 @@ export const setupForGjs = async (input) => {
         // Unsupported URI scheme for importing: node`) — the same failure
         // `utils/gjs-bundle-guard.ts` catches at emit time, caught here at its
         // source with the importer and cause named.
-        unresolvedWorkspaceImportPlugin({ target: 'gjs', aliases: aliasEntries, isExternal: external }),
+        unresolvedWorkspaceImportPlugin({
+            target: 'gjs',
+            aliases: aliasEntries,
+            isExternal: external,
+            ...(input.pluginOptions.toolchainAnchor !== undefined
+                ? { toolchainAnchor: input.pluginOptions.toolchainAnchor }
+                : {}),
+        }),
     ];
-    return { options, plugins };
+    return { options, prePlugins, plugins };
 };
 /** Copy the alias map, dropping entries with an empty target. */
 function flattenAliases(map) {

package/lib/app/nativescript.d.ts

@@ -1,6 +1,8 @@
 import type { RolldownOptions, RolldownPluginOption } from 'rolldown';
 import type { PluginOptions } from '../types/plugin-options.js';
 export interface NativescriptBuildConfig {
+    /** Transforms that must see the ORIGINAL source; composed before the caller's plugins. */
+    prePlugins: RolldownPluginOption[];
     options: RolldownOptions;
     plugins: RolldownPluginOption[];
 }

package/lib/app/nativescript.js

@@ -124,6 +124,9 @@ export const setupForNativescript = async (input) => {
     // the unresolved-workspace-import guard below so the guard reports the same
     // promise the alias layer made.
     const aliasEntries = flattenAliases(aliasMap);
+    // Reflection reads the ORIGINAL TypeScript, so it runs before any user
+    // transform can strip the annotations out from under it (see `GjsifyConfig`).
+    const prePlugins = [deepkitPlugin({ reflection: input.pluginOptions.reflection })];
     const plugins = [
         gjsImportsEmptyPlugin(),
         // Platform-specific source variants (`*.android` / `*.ios` /
@@ -135,7 +138,6 @@ export const setupForNativescript = async (input) => {
         // NO cssAsStringPlugin — NS ships its own CSS pipeline via
         // @nativescript/core; .css imports are handled by the consuming
         // @nativescript/webpack or @nativescript/vite build
-        deepkitPlugin({ reflection: input.pluginOptions.reflection }),
         // `order: 'post'` — see app/gjs.ts. Native-bridge identifiers
         // (`java.*`, `NS*`, …) are ambient GLOBALS on this target, never
         // imports, so they never reach this hook; only a `@gjsify/*` edge does,
@@ -147,7 +149,7 @@ export const setupForNativescript = async (input) => {
             isExternal,
         }),
     ];
-    return { options, plugins };
+    return { options, prePlugins, plugins };
 };
 function flattenAliases(map) {
     const out = {};

package/lib/app/node.d.ts

@@ -54,6 +54,8 @@ export declare function isGjsSourceBuild(options: {
     registerInject?: string | undefined;
 }): boolean;
 export interface NodeBuildConfig {
+    /** Transforms that must see the ORIGINAL source; composed before the caller's plugins. */
+    prePlugins: RolldownPluginOption[];
     options: RolldownOptions;
     plugins: RolldownPluginOption[];
 }

package/lib/app/node.js

@@ -206,6 +206,9 @@ export const setupForNode = async (input) => {
         },
         treeshake: true,
     };
+    // Reflection reads the ORIGINAL TypeScript, so it runs before any user
+    // transform can strip the annotations out from under it (see `GjsifyConfig`).
+    const prePlugins = [deepkitPlugin({ reflection: input.pluginOptions.reflection })];
     const plugins = [
         // Virtual-entry plugin runs FIRST so its resolveId/load match the synthetic
         // `\0gjsify-entry:` ids `wrapInputWithSideEffects` produces (no-op when
@@ -238,7 +241,6 @@ export const setupForNode = async (input) => {
         // 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 }),
         // 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
@@ -254,7 +256,7 @@ export const setupForNode = async (input) => {
         // specifier at runtime.
         unresolvedWorkspaceImportPlugin({ target: 'node', aliases: aliasEntries, isExternal: external }),
     ];
-    return { options, plugins };
+    return { options, prePlugins, plugins };
 };
 function flattenAliases(map) {
     const out = {};

package/lib/index.d.ts

@@ -2,10 +2,11 @@ export * from './types/index.js';
 export * from './utils/index.js';
 export * from './app/index.js';
 export * from './library/index.js';
-export { REWRITE_FILTER, extractPackageSpec, getBundleDirFromOutput, rewriteContents, shouldRewrite, nodeModulesPathRewritePlugin, } from './plugins/rewrite-node-modules-paths.js';
+export { REWRITE_FILTER, extractPackageSpec, getBundleDirFromOutput, rewriteContents, shouldRewrite, shouldInline, nodeModulesPathRewritePlugin, } from './plugins/rewrite-node-modules-paths.js';
 export type { NodeModulesPathRewriteOptions, RewriteResult } from './plugins/rewrite-node-modules-paths.js';
 export { processStubPlugin, GJS_PROCESS_STUB, composeBanner } from './plugins/process-stub.js';
 export { giRuntimePathsStub } from './plugins/gi-runtime-paths.js';
+export type { GiSystemProbe } from './plugins/gi-runtime-paths.js';
 export type { ProcessStubPluginOptions } from './plugins/process-stub.js';
 export { cssAsStringPlugin } from './plugins/css-as-string.js';
 export { textLoaderPlugin } from './plugins/text-loader.js';

package/lib/index.js

@@ -3,7 +3,7 @@ export * from './types/index.js';
 export * from './utils/index.js';
 export * from './app/index.js';
 export * from './library/index.js';
-export { REWRITE_FILTER, extractPackageSpec, getBundleDirFromOutput, rewriteContents, shouldRewrite, nodeModulesPathRewritePlugin, } from './plugins/rewrite-node-modules-paths.js';
+export { REWRITE_FILTER, extractPackageSpec, getBundleDirFromOutput, rewriteContents, shouldRewrite, shouldInline, nodeModulesPathRewritePlugin, } from './plugins/rewrite-node-modules-paths.js';
 export { processStubPlugin, GJS_PROCESS_STUB, composeBanner } from './plugins/process-stub.js';
 export { giRuntimePathsStub } from './plugins/gi-runtime-paths.js';
 export { cssAsStringPlugin } from './plugins/css-as-string.js';

package/lib/library/lib.d.ts

@@ -1,6 +1,8 @@
 import type { RolldownOptions, RolldownPluginOption } from 'rolldown';
 import type { PluginOptions } from '../types/plugin-options.js';
 export interface LibBuildConfig {
+    /** Transforms that must see the ORIGINAL source; composed before the caller's plugins. */
+    prePlugins: RolldownPluginOption[];
     options: RolldownOptions;
     plugins: RolldownPluginOption[];
 }

package/lib/library/lib.js

@@ -9,6 +9,7 @@
 // library config: consumers downstream (downstream apps using `gjsify
 // build --app gjs|node|browser`) re-bundle and apply their own target
 // lowering. Library output stays maximally portable.
+import blueprintPlugin from '@gjsify/vite-plugin-blueprint';
 import { aliasPlugin } from '../plugins/alias.js';
 import { cssAsStringPlugin } from '../plugins/css-as-string.js';
 import { externalsPlugin } from '../plugins/externals.js';
@@ -90,8 +91,18 @@ export const setupLib = async (input) => {
         // tiny JS module re-exporting the CSS source, which preserveModules
         // emits 1:1.
         cssAsStringPlugin(),
+        // Same shape as the CSS hook above, and needed for the same reason: without it a `.blp`
+        // import reaches rolldown's JS parser, and a Blueprint file's first line — `using Gtk 4.0;`
+        // — is VALID JavaScript (a `using` resource declaration missing its initializer), so the
+        // build dies on "Using declarations must have an initializer" and nothing points at
+        // Blueprint. Only the app factories installed it, which quietly made Blueprint an
+        // application-only feature: a shared widget in a library package could not have a
+        // template, so its captions had to be assigned from TypeScript, where they carry no
+        // `translatable` attribute and no catalogue can ever reach them.
+        blueprintPlugin(),
     ];
-    return { options, plugins };
+    // Library mode wires no reflection at all; the empty slot says so out loud.
+    return { options, prePlugins: [], plugins };
 };
 /**
  * Whether a specifier should stay external in library mode: a bare /

package/lib/plugin.d.ts

@@ -1,7 +1,23 @@
 import type { RolldownOptions, RolldownPluginOption } from 'rolldown';
 import type { PluginOptions } from './types/plugin-options.js';
+import type { GiSystemProbe } from './plugins/gi-runtime-paths.js';
 export interface GjsifyConfig {
     options: RolldownOptions;
+    /**
+     * Transforms that must see the ORIGINAL module source — composed BEFORE the
+     * caller's own plugins, while `plugins` stays after them.
+     *
+     * The split exists because the two positions answer different questions. User
+     * plugins go first so their `resolveId`/`load` wins over gjsify's alias and
+     * externals chain. But a user `transform: { order: 'pre' }` that REWRITES the
+     * source then also beats gjsify's own pre-transforms, and Deepkit's type
+     * compiler is one of them: `@gjsify/rolldown-plugin-solid` runs
+     * `@babel/preset-typescript` over every `.tsx`, so Deepkit was handed a file
+     * with no type annotations left. MEASURED on one `.tsx` carrying both a
+     * `typeOf<T>()` and a JSX tag: `const reflected = typeOf()` in the artifact,
+     * exit 0, not one diagnostic, and `Error: No type given` thrown at runtime.
+     */
+    prePlugins: RolldownPluginOption[];
     plugins: RolldownPluginOption[];
 }
 export interface GjsifyPluginInput {
@@ -20,6 +36,15 @@ export interface GjsifyPluginInput {
      *   `"…"`   → custom line, supports `${env:NAME[:-default]}` placeholders
      */
     shebang?: boolean | string;
+    /**
+     * `--app gjs` only: system GI library dirs the byte-1 prologue probes on the RUNNING
+     * host. The bundle-relative half of that prologue is deliberately NOT plumbed here —
+     * `processStubPlugin`'s `giRuntimePaths` still takes it, but nothing in this repo can
+     * fill it with a path that is true on the machine a shipped bundle runs on
+     * (`packages/infra/cli/src/utils/gi-runtime-paths.ts` records what was measured), and
+     * an option no caller fills is the defect this wiring was added to remove.
+     */
+    giSystemProbes?: readonly GiSystemProbe[];
 }
 /**
  * Build the Rolldown configuration template + plugin array for the given

package/lib/plugin.js

@@ -42,6 +42,7 @@ export const gjsifyPlugin = async (input, pluginOptions = {}) => {
                 userBanner: input.userBanner,
                 userAliases: input.userAliases,
                 shebang: input.shebang,
+                giSystemProbes: input.giSystemProbes,
                 pluginOptions,
             });
         case 'node':

package/lib/plugins/gi-runtime-paths.d.ts

@@ -1,10 +1,32 @@
 /**
- * The byte-1 prologue that prepends `dirs` to the default repository's typelib
- * search path and library path. Empty list → `''`: a no-op prologue in every
- * bundle is a guard that can never fire, and a banner that is not there cannot
- * drift.
+ * An absolute candidate library dir, the path that proves it IS one, and the path
+ * that proves the running host is the PLATFORM the candidate belongs to.
+ *
+ * Both gates, because they answer different questions and only one of them travels
+ * well. `/usr/local/lib` holding a `girepository-1.0/` says "a GI stack is installed
+ * here"; it does NOT say "this host's loader needs help finding it" — on Linux
+ * `ld.so`'s system-wide cache already resolves those leaves, and a `meson setup
+ * --prefix=/usr/local` or jhbuild tree is a normal shape there. Prepending it anyway
+ * puts a second GI stack ahead of the distro's for every bundle on that host, which
+ * is the two-registries failure ADR 0023 § 4 / #910 describe. The bundle cannot ask
+ * `process.platform` (it is platform-neutral JavaScript built on a machine that is
+ * not the host), so the platform scope travels as a marker path too.
+ */
+export type GiSystemProbe = readonly [libDir: string, marker: string, hostMarker: string];
+/**
+ * The byte-1 prologue that prepends directories to the default repository's typelib
+ * search path and library path. Nothing to prepend → `''`: a no-op prologue in every
+ * bundle is a guard that can never fire, and a banner that is not there cannot drift.
+ *
+ * Prepending REVERSES a list, so both loops count down and the emitted order is the
+ * order given. `systemProbes` are applied first and therefore end up BEHIND `dirs`:
+ * ADR 0023's bundle-before-system precedence, which #910 paid for.
  *
  * @param dirs directories RELATIVE to the program's own directory, `/`-separated —
  *   an absolute path baked at build time is the BUILD machine's
+ * @param systemProbes absolute directories prepended only where BOTH of a probe's
+ *   marker paths exist on the RUNNING host; the markers are passed in so the
+ *   `girepository-1.0` layout rule and the platform scope around it keep their single
+ *   definition in the caller
  */
-export declare function giRuntimePathsStub(dirs: readonly string[]): string;
+export declare function giRuntimePathsStub(dirs: readonly string[], systemProbes?: readonly GiSystemProbe[]): string;

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

@@ -1,37 +1,84 @@
-// Tell GI where a bundle's own typelibs and their backing libraries are — from
-// INSIDE the process, so a `--app gjs` bundle needs no launcher and no environment.
-// Why it exists, what it does NOT cover (a dylib reached through another dylib's
-// link closure never passes through GI, so only `@rpath`/`$ORIGIN` reaches it) and
-// the macOS measurements behind it: `status/open-todos.md` § "A globally installed
-// GJS launcher still cannot load a system GTK on macOS", ADR 0023 § 4.
+// SPDX-License-Identifier: MIT
+// The GI runtime search-path prologue for `--app gjs` bundles: the only repair shape
+// that survives macOS (a typelib names its library by bare leaf, and the link closure
+// never passes through GI, so only `@rpath`/`$ORIGIN` reaches it). Measurements:
+// `status/open-todos.md` § "A globally installed GJS launcher still cannot load a
+// system GTK on macOS", ADR 0023 § 4.
+//
+// WHAT IT REACHES, MEASURED (gjs 1.88.1, linux; pinned by the `gi-runtime-prologue`
+// e2e): a banner is the entry chunk's BODY and ESM evaluates imports first, so a
+// STATIC `import … from 'gi://Ns'` has already loaded its typelib before this runs.
+// What is left is what loads LATER — `await import('gi://Soup')` and the other
+// optional namespaces. Reaching the static ones changes how a bundle acquires GI
+// namespaces at all; that is an ADR, filed in the same entry.
+//
+// TWO KINDS OF DIRECTORY, split by WHOSE FACT each is. `dirs` describe the SHIPPED
+// TREE, so they are baked, relative to the program. `systemProbes` describe the host
+// that will RUN it, which the build machine cannot know — so the candidate travels
+// and is dropped on the host when it names nothing.
 /**
- * The byte-1 prologue that prepends `dirs` to the default repository's typelib
- * search path and library path. Empty list → `''`: a no-op prologue in every
- * bundle is a guard that can never fire, and a banner that is not there cannot
- * drift.
+ * The byte-1 prologue that prepends directories to the default repository's typelib
+ * search path and library path. Nothing to prepend → `''`: a no-op prologue in every
+ * bundle is a guard that can never fire, and a banner that is not there cannot drift.
+ *
+ * Prepending REVERSES a list, so both loops count down and the emitted order is the
+ * order given. `systemProbes` are applied first and therefore end up BEHIND `dirs`:
+ * ADR 0023's bundle-before-system precedence, which #910 paid for.
  *
  * @param dirs directories RELATIVE to the program's own directory, `/`-separated —
  *   an absolute path baked at build time is the BUILD machine's
+ * @param systemProbes absolute directories prepended only where BOTH of a probe's
+ *   marker paths exist on the RUNNING host; the markers are passed in so the
+ *   `girepository-1.0` layout rule and the platform scope around it keep their single
+ *   definition in the caller
  */
-export function giRuntimePathsStub(dirs) {
-    if (dirs.length === 0)
+export function giRuntimePathsStub(dirs, systemProbes = []) {
+    if (dirs.length === 0 && systemProbes.length === 0)
         return '';
     const list = dirs.map((d) => JSON.stringify(d)).join(',');
+    const probes = systemProbes.map((probe) => `[${probe.map((v) => JSON.stringify(v)).join(',')}]`).join(',');
     // Four rules, each pinned with its incident by `gi-runtime-paths-banner.spec.ts`:
-    // every ambient global through `globalThis.` (a bare `imports` at byte 1 binds to
-    // a bundled module's own top-level `const imports`, still in its TDZ); guarded
-    // probes, not try/catch (no call here has a throw path, so a catch would hide a
-    // real absence); one line (the banner precedes source-map-aware machinery); both
-    // prepends (search path alone finds the typelib, then fails the dlopen).
-    return (`(function(){var i=globalThis.imports;if(!i||!i.gi||!i.system)return;` +
-        `var R=i.gi.GIRepository;if(!R||!R.Repository||!R.Repository.dup_default)return;` +
+    // every ambient global through `globalThis.` (a bare `imports` at byte 1 binds to a
+    // bundled module's own top-level `const imports`, still in its TDZ); capability
+    // guards rather than try/catch for every CALL, since none has a throw path in the
+    // GIR; one line (the banner precedes source-map-aware machinery); both prepends
+    // (search path alone finds the typelib, then fails the dlopen).
+    //
+    // The ONE try wraps a namespace LOAD, the only operation here that does throw:
+    // distributions ship the GIRepository typelib separately from the girepository
+    // library GJS links against (Debian's `gir1.2-girepository-3.0` vs
+    // `libgirepository-2.0-0`), so a host with only the second raises "Typelib file
+    // for namespace 'GIRepository' (any version) not found" — measured, and why
+    // `activateNativePrebuilds()` wraps the same access. At byte 1 that throw takes
+    // down a program that ran fine while this prologue was the empty string. Not
+    // logged, for that function's reason: every outcome leaves the caller where it
+    // was before the prologue existed, so no host is made worse.
+    const head = `(function(){var i=globalThis.imports;if(!i||!i.gi)return;` +
+        `var R;try{R=i.gi.GIRepository}catch(e){return}` +
+        `if(!R||!R.Repository||!R.Repository.dup_default)return;` +
         `var r=R.Repository.dup_default();if(!r||!r.prepend_search_path||!r.prepend_library_path)return;` +
-        `var p=i.system.programPath||i.system.programInvocationName||'';` +
-        // Both separators: the program path is the HOST's, and on win32 a `/`-only
-        // cut matches nothing (same rule as `lastPathSeparatorIndex`, #1143).
-        `var m=/^(.*)[\\/\\\\][^\\/\\\\]*$/.exec(p);if(!m)return;` +
-        // Absolute stays absolute: joining a system libdir under the program dir names nothing.
-        `var b=m[1];for(var d of [${list}]){var f=/^([A-Za-z]:[\\/\\\\]|[\\/\\\\])/.test(d)?d:b+'/'+d;` +
-        `r.prepend_search_path(f);r.prepend_library_path(f)}` +
-        `})();`);
+        `var a=function(f){r.prepend_search_path(f);r.prepend_library_path(f)};`;
+    // GLib gets its own try for the same reason, separate so a host that cannot
+    // introspect it still gets the relative half.
+    //
+    // The HOST marker is tested first and short-circuits: on a host the candidate does
+    // not belong to, the whole table costs one `stat` per entry and changes nothing.
+    const probeHalf = probes.length === 0
+        ? ''
+        : `var G;try{G=i.gi.GLib}catch(e){}` +
+            `if(G&&G.file_test&&G.FileTest){var S=[${probes}];` +
+            `for(var j=S.length;j--;)` +
+            `if(G.file_test(S[j][2],G.FileTest.EXISTS)&&G.file_test(S[j][1],G.FileTest.IS_DIR))a(S[j][0])}`;
+    // Guards rather than returns, so a program path with no separator (`gjs -c`) still
+    // leaves the system half applied.
+    const relativeHalf = list.length === 0
+        ? ''
+        : `var p=(i.system&&(i.system.programPath||i.system.programInvocationName))||'';` +
+            // Both separators: the program path is the HOST's, and on win32 a `/`-only
+            // cut matches nothing (same rule as `lastPathSeparatorIndex`, #1143).
+            `var m=/^(.*)[\\/\\\\][^\\/\\\\]*$/.exec(p);if(m){var b=m[1];var D=[${list}];` +
+            `for(var k=D.length;k--;){var d=D[k];` +
+            // Absolute stays absolute: joining a system libdir under the program dir names nothing.
+            `var q=/^([A-Za-z]:[\\/\\\\]|[\\/\\\\])/.test(d)?d:b+'/'+d;a(q)}}`;
+    return `${head}${probeHalf}${relativeHalf}})();`;
 }

package/lib/plugins/intl-segmenter-banner.d.ts

@@ -0,0 +1 @@
+export declare const GJS_INTL_SEGMENTER_STUB: string;

package/lib/plugins/intl-segmenter-banner.js

@@ -0,0 +1,42 @@
+// One-line banner that supplies `Intl.Segmenter` on a GJS built without it.
+//
+// THE INCIDENT — measured, not hypothetical. `gjsify ship`'s first CI leg on a
+// bare `ubuntu-latest` (the one that exists to hand a `.deb` to a real `dpkg`)
+// installed the shipped package, ran the binary, and got:
+//
+//     JS ERROR: TypeError: Intl.Segmenter is not a constructor
+//
+// Not an old runtime: that host had **gjs 1.88.1**, the same version as the
+// Fedora container where everything passes. The difference is the ICU the two
+// were built against, so a version number does not predict it — and the `.deb`
+// this project ships declares `Depends: gjs >= 1.82`, which apt satisfies on
+// that host. Install succeeds, program does not start: verbatim the failure
+// class `depends.ts` was written to prevent, one layer below where it looks.
+//
+// WHY THE CLI NEEDS IT AT ALL, and why no application code is involved:
+// `@gjsify/cli` → `yargs@18` → `string-width@7` → `get-east-asian-width`, which
+// constructs a `Intl.Segmenter` AT MODULE SCOPE. It is the argument parser, so
+// every command dies, `--help` included — reproduced locally by deleting
+// `Intl.Segmenter` before importing the published bundle.
+//
+// WHAT THIS FALLBACK IS, AND IS NOT. It segments by CODE POINT, not by grapheme
+// cluster, because a correct cluster algorithm is a Unicode table this banner
+// cannot carry. Measured against native, via `string-width`:
+//
+//     'hello' 5→5   'あいう' 6→6   '🇩🇪' 2→2   'café' 4→4      (identical)
+//     '👨‍👩‍👧‍👦'  2→8   '👍🏽'    2→4                            (over-counted)
+//
+// So ASCII, CJK, flags and combining accents are exact; ZWJ sequences and skin
+// tone modifiers come out too wide. The cost is a misaligned column in terminal
+// output containing those emoji. The cost of not having it is that nothing runs
+// at all. It is installed ONLY when the constructor is missing, so on every GJS
+// with a full ICU — every currently green CI leg — this line does nothing.
+//
+// Kept on a single line, like the sibling banners: the banner runs before any
+// source-map-aware machinery, so a newline here shifts every bundle line by one.
+export const GJS_INTL_SEGMENTER_STUB = 'if(typeof Intl.Segmenter!=="function")Intl.Segmenter=class Segmenter{' +
+    'constructor(){}' +
+    'resolvedOptions(){return{locale:"en",granularity:"grapheme"}}' +
+    'segment(input){const s=String(input);return{input:s,[Symbol.iterator]:function*(){' +
+    'let i=0;for(const c of s){yield{segment:c,index:i,input:s};i+=c.length}}}}' +
+    '};';

package/lib/plugins/process-stub.d.ts

@@ -1,4 +1,5 @@
 import type { Plugin } from 'rolldown';
+import { type GiSystemProbe } from './gi-runtime-paths.js';
 export declare const GJS_PROCESS_STUB: string;
 /**
  * Compose the GJS process stub with the user-supplied banner so the result is
@@ -23,6 +24,12 @@ export interface ProcessStubPluginOptions {
      * Empty or unset emits nothing.
      */
     giRuntimePaths?: readonly string[];
+    /**
+     * Absolute system GI library directories, each paired with the path that proves the
+     * host really has one. Prepended BEHIND {@link giRuntimePaths} and only where the
+     * marker exists at RUNTIME. Empty or unset emits nothing.
+     */
+    giSystemProbes?: readonly GiSystemProbe[];
 }
 /** Inject the byte-1 banner as a chunk banner, after any user `output.banner`. */
 export declare function processStubPlugin(options?: ProcessStubPluginOptions): Plugin;

package/lib/plugins/process-stub.js

@@ -1,4 +1,5 @@
 import { BUNDLE_URL_BANNER } from './bundle-url-banner.js';
+import { GJS_INTL_SEGMENTER_STUB } from './intl-segmenter-banner.js';
 import { GJS_WELLKNOWN_SYMBOLS_STUB } from './wellknown-symbols-banner.js';
 import { giRuntimePathsStub } from './gi-runtime-paths.js';
 // Every GJS ambient global is reached through `globalThis.` — NEVER as a bare
@@ -84,8 +85,11 @@ export function processStubPlugin(options = {}) {
     // is single-line and idempotent.
     const stub = (options.captureBundleUrl ? BUNDLE_URL_BANNER : '') +
         GJS_WELLKNOWN_SYMBOLS_STUB +
+        // Before the process stub and before module init: `get-east-asian-width`
+        // constructs a Segmenter at module scope, so a later injection is too late.
+        GJS_INTL_SEGMENTER_STUB +
         GJS_PROCESS_STUB +
-        giRuntimePathsStub(options.giRuntimePaths ?? []);
+        giRuntimePathsStub(options.giRuntimePaths ?? [], options.giSystemProbes ?? []);
     const banner = composeBanner(stub, options.userBanner ?? '');
     return {
         name: 'gjsify-process-stub',

package/lib/plugins/rewrite-node-modules-paths.d.ts

@@ -2,6 +2,36 @@ import type { Plugin } from 'rolldown';
 export declare const REWRITE_FILTER: RegExp;
 /** True when the rewriter wants to look at this path — node_modules + supported ext. */
 export declare function shouldRewrite(path: string): boolean;
+/**
+ * True when the static-read INLINER wants to look at this path — any supported
+ * source, first-party included.
+ *
+ * Deliberately wider than {@link shouldRewrite}, because the two answer different
+ * questions. The inliner asks *is this read resolvable at build time*, which is a
+ * property of the expression and can be true in any file. The rewriter asks *does
+ * this file's `import.meta.url` still mean anything once bundled*, which is only
+ * worth asking of a file whose original location was `node_modules` — the whole
+ * subject of this plugin.
+ *
+ * They were ONE gate until 2026-08-22, and the cost was silent. Each of
+ * `@gjsify/cli`'s own six `readFileSync(new URL(<literal>, import.meta.url))`
+ * template loaders shipped into `dist/cli.gjs.mjs` as a LIVE read pointing at a
+ * `templates/` directory that exists neither in the repo (the sources are in
+ * `src/templates/`; the build copies them to `lib/templates/`) nor in the
+ * published tarball (`files` ships `lib`, not a root `templates`). Measured on a
+ * fresh build: `gjs -m dist/cli.gjs.mjs ship --stage` died with
+ * `ENOENT … packages/infra/cli/templates/app/desktop.tmpl` while the identical
+ * command through `lib/index.js` staged the desktop entry. Two of those six files
+ * carry a comment asserting the inliner handles them, so reading the code
+ * confirmed the belief rather than the behaviour.
+ *
+ * Consequence for a CONSUMER's build, stated because it is a behaviour change: a
+ * statically resolvable read in their own source is baked into their bundle too.
+ * That is the promise the inliner exists to make — a bundle that survives leaving
+ * its build site — and a read meant to stay dynamic keeps working by not being
+ * statically resolvable, since anything the evaluator cannot fold is left alone.
+ */
+export declare function shouldInline(path: string): boolean;
 /** The directory the bundle's outfile lives in, from `output.file` or `output.dir`. */
 export declare function getBundleDirFromOutput(opts: {
     file?: string;
@@ -48,5 +78,10 @@ export interface NodeModulesPathRewriteOptions {
 /**
  * Build a Rolldown plugin that runs the path rewriter as a `transform(code, id)`
  * hook with `order: 'post'`.
+ *
+ * Two scopes in one transform, not two plugins: a second transform would parse
+ * every module a second time, and the inliner's own fast path (skip unless the
+ * source mentions `readFileSync`/`readdirSync`/`existsSync`) already makes the
+ * wider scope nearly free. See {@link shouldInline} for why the scopes differ.
  */
 export declare function nodeModulesPathRewritePlugin(options: NodeModulesPathRewriteOptions): Plugin;