@gjsify/rolldown-plugin-gjsify 0.48.0 → 0.50.0

package/lib/app/browser.js

@@ -2,7 +2,11 @@
 //
 // Browser builds redirect `@girs/*` and `gi://*` to an empty virtual module
 // (they appear transitively via `@gjsify/unit` and similar packages with
-// GJS-specific code paths). Bare Node specifiers + their `node:*` prefix
+// GJS-specific code paths) — unless `--gi-renderer` composes the ADR 0034
+// stage 9 arm, which answers `gi://Adw` / `gi://Gtk` out of `@gjsify/adwaita-web`
+// and carves `@girs/*` out of the empty redirect so they reach it.
+//
+// Bare Node specifiers + their `node:*` prefix
 // variants are routed to `@gjsify/<X>` via the curated
 // `ALIASES_NODE_FOR_BROWSER` table, whose VALUES already carry the
 // per-runtimes-triplet slot routing (`@gjsify/<X>` → `@gjsify/<X>/browser` /
@@ -15,9 +19,10 @@
 import { aliasPlugin } from '../plugins/alias.js';
 import { deepkitPlugin } from '@gjsify/rolldown-plugin-deepkit';
 import blueprintPlugin from '@gjsify/vite-plugin-blueprint';
-import { ALIASES_NODE_FOR_BROWSER, getDerivedAliasesSync } from '@gjsify/resolve-npm';
+import { ALIASES_NODE_FOR_BROWSER, GI_RENDERERS, getDerivedAliasesSync } from '@gjsify/resolve-npm';
 import { globToEntryPoints } from '../utils/entry-points.js';
 import { gjsImportsEmptyPlugin } from '../plugins/gjs-imports-empty.js';
+import { giRendererPlugin } from '../plugins/gi-renderer.js';
 import { cssAsStringPlugin } from '../plugins/css-as-string.js';
 import { unresolvedWorkspaceImportPlugin } from '../plugins/unresolved-workspace-import.js';
 export const setupForBrowser = async (input) => {
@@ -25,6 +30,9 @@ export const setupForBrowser = async (input) => {
     const external = [...userExternal];
     const exclude = input.pluginOptions.exclude ?? [];
     const entryPoints = await globToEntryPoints(input.input, exclude);
+    // The arm is composed only when asked for. `config.ts` already refuses the flag
+    // on a target with no row, so an undefined row here means the flag was not passed.
+    const giRenderer = input.pluginOptions.giRenderer ? GI_RENDERERS['browser'] : undefined;
     // Bare Node-builtin + `node:*` prefix aliases — both forms route to the
     // same `@gjsify/<X>` target. Generated deterministically from
     // `ALIASES_NODE_FOR_BROWSER` so a single source-of-truth in
@@ -90,7 +98,13 @@ export const setupForBrowser = async (input) => {
     // transform can strip the annotations out from under it (see `GjsifyConfig`).
     const prePlugins = [deepkitPlugin({ reflection: input.pluginOptions.reflection })];
     const plugins = [
-        gjsImportsEmptyPlugin(),
+        // ADR 0034 stage 9 — the `gi://` arm, ahead of the empty redirect so it
+        // claims the specifier first, exactly as `gjsGiNodePlugin` does on the node
+        // target. `emptyGirs` follows it: with the arm on, `@girs/<ns>-<ver>` must
+        // reach its real body so its inner `gi://` lands here instead of being
+        // stranded as `{}`.
+        ...(giRenderer ? [giRendererPlugin({ app: 'browser', ...giRenderer })] : []),
+        gjsImportsEmptyPlugin({ emptyGirs: !giRenderer }),
         aliasPlugin({ entries: aliasEntries }),
         blueprintPlugin(),
         cssAsStringPlugin(),

package/lib/app/nativescript.js

@@ -13,7 +13,9 @@
 //
 // `@girs/*` and `gi://*` imports are silenced via `gjsImportsEmptyPlugin` —
 // they appear transitively through `@gjsify/unit` and similar packages with
-// GJS-specific code paths that never execute on NS.
+// GJS-specific code paths that never execute on NS. `--gi-renderer` (ADR 0034
+// stage 9) opts out of that for `gi://Adw` / `gi://Gtk`, answering them from
+// `@gjsify/adwaita-nativescript` and carving `@girs/*` out of the empty redirect.
 //
 // Bare Node specifiers + their `node:*` prefix variants are routed to
 // `@gjsify/<X>` via the curated `ALIASES_NODE_FOR_NATIVESCRIPT` table. Unlike
@@ -34,9 +36,10 @@
 // of `@nativescript/core`) and no `blueprintPlugin` (Blueprint is GTK-only).
 import { aliasPlugin } from '../plugins/alias.js';
 import { deepkitPlugin } from '@gjsify/rolldown-plugin-deepkit';
-import { ALIASES_NODE_FOR_NATIVESCRIPT, getDerivedAliasesSync } from '@gjsify/resolve-npm';
+import { ALIASES_NODE_FOR_NATIVESCRIPT, GI_RENDERERS, getDerivedAliasesSync } from '@gjsify/resolve-npm';
 import { globToEntryPoints } from '../utils/entry-points.js';
 import { gjsImportsEmptyPlugin } from '../plugins/gjs-imports-empty.js';
+import { giRendererPlugin } from '../plugins/gi-renderer.js';
 import { platformResolvePlugin, nativescriptSuffixChain, detectNativescriptPlatform, nativescriptPlatformDefines, } from '../plugins/platform-resolve.js';
 import { unresolvedWorkspaceImportPlugin } from '../plugins/unresolved-workspace-import.js';
 // Never bundled: an app works only with the ONE core instance the runtime boots, and what
@@ -49,6 +52,9 @@ export const setupForNativescript = async (input) => {
     const isExternal = (id) => external.some((entry) => (typeof entry === 'string' ? entry === id : entry.test(id)));
     const exclude = input.pluginOptions.exclude ?? [];
     const entryPoints = await globToEntryPoints(input.input, exclude);
+    // The arm is composed only when asked for. `config.ts` already refuses the flag
+    // on a target with no row, so an undefined row here means the flag was not passed.
+    const giRenderer = input.pluginOptions.giRenderer ? GI_RENDERERS['nativescript'] : undefined;
     // Target platform — discovered from the env NS' CLI sets when it spawns a
     // bundler (else `undefined` → `.native`-only resolution + neutral defines).
     // `gjsify build` is a production bundler, so `__DEV__` is `false` here.
@@ -128,7 +134,13 @@ export const setupForNativescript = async (input) => {
     // transform can strip the annotations out from under it (see `GjsifyConfig`).
     const prePlugins = [deepkitPlugin({ reflection: input.pluginOptions.reflection })];
     const plugins = [
-        gjsImportsEmptyPlugin(),
+        // ADR 0034 stage 9 — the `gi://` arm, ahead of the empty redirect so it
+        // claims the specifier first, exactly as `gjsGiNodePlugin` does on the node
+        // target. `emptyGirs` follows it: with the arm on, `@girs/<ns>-<ver>` must
+        // reach its real body so its inner `gi://` lands here instead of being
+        // stranded as `{}`.
+        ...(giRenderer ? [giRendererPlugin({ app: 'nativescript', ...giRenderer })] : []),
+        gjsImportsEmptyPlugin({ emptyGirs: !giRenderer }),
         // Platform-specific source variants (`*.android` / `*.ios` /
         // `*.native`) win over the base file — resolved BEFORE the Node-builtin
         // alias routing so a platform fork of a portable module is honored.

package/lib/plugins/gi-renderer.d.ts

@@ -0,0 +1,35 @@
+import type { Plugin } from 'rolldown';
+export interface GiRendererOptions {
+    /** The `--app` target, named in every refusal so the message says WHERE it applies. */
+    app: string;
+    /** The package whose `Adw` / `Gtk` namespace exports answer `gi://` on this target. */
+    renderer: string;
+    /** GI namespace → the version this arm answers for, from `@gjsify/resolve-npm`. */
+    namespaces: Readonly<Record<string, string>>;
+}
+/**
+ * The runtime shim for one answered namespace.
+ *
+ * Exports `default` and nothing else, which is what GJS's own `gi://` module exports:
+ * measured on gjs 1.88.1, `import * as Adw from 'gi://Adw?version=1'` yields a namespace
+ * whose only key is `default`, and `import { ActionRow } from 'gi://Adw?version=1'` is a
+ * SyntaxError (`doesn't provide an export named: 'ActionRow'`). Adding named member
+ * exports here would compile on these two targets and fail on `--app gjs` — a second
+ * spelling, which is the thing ADR 0034 exists to remove.
+ *
+ * ITS REFUSAL NAMES THE NAMESPACE AND VERSION SEPARATELY RATHER THAN QUOTING THE
+ * SPECIFIER. `tests/e2e/gi-renderer-arms` asserts `!bundle.includes('gi://')` on the
+ * bundles it builds — a SUBSTRING, because on these two targets an unresolved GI import
+ * is a missing alias (`tests/AGENTS.md`) — and this string is reachable, so rolldown keeps
+ * it. Measured: with the specifier quoted, both green probe bundles carried one `gi://`
+ * occurrence and neither of them was an import.
+ *
+ * THE CONSTRAINT IS SELF-IMPOSED, and only that one suite imposes it. `app-browser` and
+ * `ns-bridge-bundles` hold the same substring rule over their own bundles, but neither
+ * passes `--gi-renderer`, so the arm never composes there and this text cannot reach them
+ * — measured, nothing under `tests/` names the flag but `gi-renderer-arms` itself. Making
+ * that suite's two assertions import-shaped would retire this rule outright; the argument,
+ * the other twelve sites and the retirement condition are in `status/open-todos.md`.
+ */
+export declare function giRendererShimSource(options: GiRendererOptions, namespace: string, version: string): string;
+export declare function giRendererPlugin(options: GiRendererOptions): Plugin;

package/lib/plugins/gi-renderer.js

@@ -0,0 +1,162 @@
+// For `--app browser` / `--app nativescript`: resolve `gi://Ns?version=X` to the
+// TARGET'S WIDGET RENDERER instead of an empty module — ADR 0034 stage 9, the
+// `gi://` arms.
+//
+// WHAT IT BUYS. `import Adw from 'gi://Adw?version=1'` is the spelling every GJS
+// source already uses, and `@girs/adw-1/adw-1.js` is literally that line plus
+// `export default Adw`. Without an arm the specifier lands in
+// `gjsImportsEmptyPlugin` and becomes `{}`, so `Adw.ActionRow` is `undefined` and
+// `class Row extends Adw.ActionRow {}` throws `Class extends value undefined is not
+// a constructor or null` — measured on both targets before this plugin existed, and
+// the exact failure the sibling header records for `@girs/*`. With the arm the same
+// import evaluates to `@gjsify/adwaita-web`'s (or `@gjsify/adwaita-nativescript`'s)
+// `Adw` namespace, which ADR 0034 clause 2 makes a namespace OBJECT precisely so it
+// can stand in for the GI one.
+//
+// IT IS OPT-IN (`--gi-renderer`), and NOT because turning it on breaks anything here.
+// That was the hypothesis and it is measured wrong: forcing the arm on across the 53
+// `--app browser` test entries and the 5 `packages/nativescript-bridge/*` packages in
+// this repository changes ZERO outcomes, because no `gi://` reaches those builds at
+// all — instrumented, the only specifier that arrives at the empty-import plugin is
+// `@girs/gjs` (7 entries), whose body is `globalThis.imports || {}`. That measurement
+// bounds the blast radius HERE and says nothing about a consumer tree, where a
+// transitively-imported `gi://GLib` would go from a silent stub to a build failure.
+//
+// What opt-in buys is that the arm makes a tier-2 widget toolkit a BUILD-TIME
+// DEPENDENCY of any bundle naming `gi://Adw` (measured on the probe fixture:
+// 133 bytes to 500 202 on browser and 214 041 on NativeScript, the latter with a
+// `@nativescript/core` import clause the flag-less bundle did not have), and nothing
+// in a tree can infer that its `gi://Adw` was meant to be `@gjsify/adwaita-web`
+// rather than nothing. `--dialect` is opt-in for the same shape of reason; see
+// `PluginOptions.dialect`.
+//
+// THREE REFUSALS, EACH AT THE EARLIEST POINT ITS FACT IS KNOWN.
+//
+//   1. A namespace with no renderer — `gi://Gio` — is refused at BUILD time, from
+//      `resolveId`. The specifier carries the namespace, so nothing has to run for
+//      the answer to be knowable, and the alternative is the empty module this arm
+//      exists to replace.
+//   2. A `?version=` the renderer's vocabulary was not generated against is refused
+//      at BUILD time too. GJS itself throws here (`Requiring Adw, version 9: Typelib
+//      file for namespace 'Adw', version '9' not found`, measured on gjs 1.88.1), so
+//      accepting it would make these two targets the only place a wrong version
+//      passes.
+//   3. An ABSENT MEMBER — `Adw.Window` on a renderer that ships no window — is
+//      refused at RUNTIME, by a Proxy, because a property access is not knowable
+//      from a specifier. These namespaces are SPARSE by construction (a renderer
+//      implements a fraction of the GIR's widgets), so this is ADR 0034 § 1 clause 3
+//      at member granularity: reading an absent member would hand back `undefined`
+//      and re-create the very `Class extends value undefined` this arm removes,
+//      thrown far from the import that caused it.
+//
+// WHY A PROXY AND NOT A COPIED OBJECT. The member set has to be the renderer's own,
+// read at runtime from the module it re-exports — a second list here would be the
+// copy that drifts, and `Object.keys` of the real namespace is also what makes the
+// refusal able to PRINT what is available.
+//
+// THE EMITTED MODULE IS NOT ALIASED, by construction: `aliasPlugin` skips importers
+// whose id carries `GJSIFY_VIRTUAL_PREFIX`, so the renderer import below names the
+// package the arm decided on and no slot-routing or user `--alias` re-points it. On
+// `--app nativescript` that layer would today be a no-op anyway — the renderer
+// declares `nativescript: "native"` and ships no `globals.mjs`, so the derived map
+// leaves it alone with a warn-once (visible in every NS build's output) — but the
+// exemption is what keeps that true after the slot vocabulary is settled.
+//
+// Portability note (as in `gjs-imports-empty.ts`): the `filter` is a Rolldown
+// fast-path; the guard inside the handler is the load-bearing check, so the plugin
+// stays correct under an engine that does not pre-filter.
+import { GJSIFY_VIRTUAL_PREFIX } from '../utils/virtual-module-id.js';
+import { parseGiSpecifier } from './gjs-gi-node.js';
+const GI_RENDERER_VIRTUAL_PREFIX = `${GJSIFY_VIRTUAL_PREFIX}gi-renderer:`;
+/**
+ * The runtime shim for one answered namespace.
+ *
+ * Exports `default` and nothing else, which is what GJS's own `gi://` module exports:
+ * measured on gjs 1.88.1, `import * as Adw from 'gi://Adw?version=1'` yields a namespace
+ * whose only key is `default`, and `import { ActionRow } from 'gi://Adw?version=1'` is a
+ * SyntaxError (`doesn't provide an export named: 'ActionRow'`). Adding named member
+ * exports here would compile on these two targets and fail on `--app gjs` — a second
+ * spelling, which is the thing ADR 0034 exists to remove.
+ *
+ * ITS REFUSAL NAMES THE NAMESPACE AND VERSION SEPARATELY RATHER THAN QUOTING THE
+ * SPECIFIER. `tests/e2e/gi-renderer-arms` asserts `!bundle.includes('gi://')` on the
+ * bundles it builds — a SUBSTRING, because on these two targets an unresolved GI import
+ * is a missing alias (`tests/AGENTS.md`) — and this string is reachable, so rolldown keeps
+ * it. Measured: with the specifier quoted, both green probe bundles carried one `gi://`
+ * occurrence and neither of them was an import.
+ *
+ * THE CONSTRAINT IS SELF-IMPOSED, and only that one suite imposes it. `app-browser` and
+ * `ns-bridge-bundles` hold the same substring rule over their own bundles, but neither
+ * passes `--gi-renderer`, so the arm never composes there and this text cannot reach them
+ * — measured, nothing under `tests/` names the flag but `gi-renderer-arms` itself. Making
+ * that suite's two assertions import-shaped would retire this rule outright; the argument,
+ * the other twelve sites and the retirement condition are in `status/open-todos.md`.
+ */
+export function giRendererShimSource(options, namespace, version) {
+    return (`import { ${namespace} as namespace } from ${JSON.stringify(options.renderer)};\n` +
+        `const RENDERER = ${JSON.stringify(options.renderer)};\n` +
+        `const APP = ${JSON.stringify(options.app)};\n` +
+        `const NS = ${JSON.stringify(namespace)};\n` +
+        `const VERSION = ${JSON.stringify(version)};\n` +
+        `export default new Proxy(namespace, {\n` +
+        `  get(target, property, receiver) {\n` +
+        // Symbols are protocol probes (`Symbol.toStringTag`, `Symbol.iterator`,
+        // `Symbol.toPrimitive`) and `then` is the thenable probe every `await` and
+        // dynamic `import()` performs; refusing those would break the module rather
+        // than report a missing widget.
+        `    if (typeof property === 'symbol' || property === 'then' || property in target) {\n` +
+        `      return Reflect.get(target, property, receiver);\n` +
+        `    }\n` +
+        `    throw new Error(\n` +
+        `      'the ' + NS + ' arm (version ' + VERSION + ') on --app ' + APP + ': ' + RENDERER +\n` +
+        `      ' has no ' + String(property) + '. A renderer implements a fraction of the GIR ' +\n` +
+        `      'vocabulary, and every absent member is a declared remainder (ADR 0034 clause 3) ' +\n` +
+        `      'rather than an oversight — refused by name here because reading it would be ' +\n` +
+        `      'undefined and \`class X extends undefined\` throws far from the import that asked ' +\n` +
+        `      'for it. It has: ' + Object.keys(target).sort().join(', ') + '.'\n` +
+        `    );\n` +
+        `  },\n` +
+        `});\n`);
+}
+export function giRendererPlugin(options) {
+    const known = Object.keys(options.namespaces).sort();
+    const answered = known.map((name) => `${name} (version ${options.namespaces[name]})`).join(', ');
+    return {
+        name: 'gjsify-gi-renderer',
+        resolveId: {
+            order: 'pre',
+            filter: { id: /^gi:\/\// },
+            handler(source) {
+                const parsed = parseGiSpecifier(source);
+                if (parsed === null)
+                    return null;
+                const expected = options.namespaces[parsed.namespace];
+                if (expected === undefined) {
+                    throw new Error(`gjsify build --app ${options.app}: \`${source}\` has no widget renderer. ` +
+                        `--gi-renderer answers ${answered} out of ${options.renderer} and nothing else — ` +
+                        'there is no GObject introspection on this target, so a namespace with no renderer ' +
+                        'counterpart cannot be substituted for. Drop --gi-renderer to keep the previous ' +
+                        'behaviour (every `gi://` import becomes an empty module), or gate the import to ' +
+                        'a target that has GI (`--app gjs`, `--app node`).');
+                }
+                if (parsed.version !== undefined && parsed.version !== expected) {
+                    throw new Error(`gjsify build --app ${options.app}: \`${source}\` asks for ${parsed.namespace} version ` +
+                        `${parsed.version}; this arm answers version ${expected} — the version ` +
+                        `${options.renderer}'s vocabulary is held against. GJS throws on a version it has no ` +
+                        'typelib for, so accepting it here would make this target the only place a wrong ' +
+                        'version passes.');
+                }
+                return { id: `${GI_RENDERER_VIRTUAL_PREFIX}${parsed.namespace}` };
+            },
+        },
+        load(id) {
+            if (!id.startsWith(GI_RENDERER_VIRTUAL_PREFIX))
+                return null;
+            const namespace = id.slice(GI_RENDERER_VIRTUAL_PREFIX.length);
+            const version = options.namespaces[namespace];
+            if (version === undefined)
+                return null;
+            return { code: giRendererShimSource(options, namespace, version), moduleSideEffects: false };
+        },
+    };
+}

package/lib/types/plugin-options.d.ts

@@ -87,6 +87,24 @@ export interface PluginOptions {
      * opposite questions and once shared a name. See `SourceDialect`.
      */
     dialect?: SourceDialect;
+    /**
+     * Resolve `gi://Ns?version=X` to the target's widget renderer rather than to an
+     * empty module — ADR 0034 stage 9. `--app browser` answers out of
+     * `@gjsify/adwaita-web`, `--app nativescript` out of `@gjsify/adwaita-nativescript`;
+     * the table is `GI_RENDERERS` in `@gjsify/resolve-npm`, and a target with no row
+     * there has no arm.
+     *
+     * Composing it also sets `emptyGirs: false` on the same build, so `@girs/adw-1`
+     * reaches its real body (`import Adw from 'gi://Adw?version=1'; export default Adw`)
+     * and its inner `gi://` is claimed here — identical to the node-gi path.
+     *
+     * OPT-IN and never inferred, for the reason `plugins/gi-renderer.ts` states at
+     * length: a `gi://` import reaching a browser or NativeScript build today is
+     * usually a GJS-only code path pulled in transitively, and answering it by default
+     * would both drag a widget toolkit into bundles that never asked for one and turn
+     * every unanswerable namespace from a silent stub into a hard build failure.
+     */
+    giRenderer?: boolean;
     /**
      * Where to look for a `@gjsify/*` the PROJECT cannot resolve, when the input is
      * TOOLCHAIN rather than user code: a file path inside the running CLI's own

package/lib/utils/index.d.ts

@@ -5,7 +5,7 @@ export * from './runtime.js';
 export * from './merge.js';
 export { detectFreeGlobals } from './detect-free-globals.js';
 export { resolveGlobalsList, writeRegisterInjectFile } from './scan-globals.js';
-export { inlineStaticReads, isAbsoluteFsPath } from './inline-static-reads.js';
+export { inlineStaticReads, isAbsoluteFsPath, isWithin, resourceRootFor } from './inline-static-reads.js';
 export { GJSIFY_VIRTUAL_PREFIX, isGjsifyVirtualModuleId } from './virtual-module-id.js';
 export { locateSurvivingJsx, classifyJsxParseFailure, formatSurvivingJsx } from './jsx-survival.js';
 export type { SurvivingJsx } from './jsx-survival.js';

package/lib/utils/index.js

@@ -5,6 +5,6 @@ export * from './runtime.js';
 export * from './merge.js';
 export { detectFreeGlobals } from './detect-free-globals.js';
 export { resolveGlobalsList, writeRegisterInjectFile } from './scan-globals.js';
-export { inlineStaticReads, isAbsoluteFsPath } from './inline-static-reads.js';
+export { inlineStaticReads, isAbsoluteFsPath, isWithin, resourceRootFor } from './inline-static-reads.js';
 export { GJSIFY_VIRTUAL_PREFIX, isGjsifyVirtualModuleId } from './virtual-module-id.js';
 export { locateSurvivingJsx, classifyJsxParseFailure, formatSurvivingJsx } from './jsx-survival.js';

package/lib/utils/inline-static-reads.d.ts

@@ -2,6 +2,55 @@ export declare function inlineStaticReads(src: string, sourceFilePath: string):
     contents: string;
     inlined: number;
 };
+/**
+ * The tree whose contents are a property of the BUILD rather than of the host —
+ * the reading module's own package.
+ *
+ * A package's own resources are what this module exists to bundle. Anything else
+ * — `/lib`, `/etc`, `/proc`, a sibling package's data — is either the machine's
+ * layout or another package's business, and its answer at build time is not its
+ * answer at run time.
+ *
+ * TWO RULES, because "the package" is answered two different ways and picking one
+ * of them gets the other wrong.
+ *
+ * For an INSTALLED file the root is STRUCTURAL: the directory whose parent is
+ * `node_modules` (or `node_modules/@scope`). Probing for the nearest
+ * `package.json` instead lands on the wrong directory for any package that
+ * dual-publishes, because the `{"type":"commonjs"}` marker beside the emitted
+ * output IS a `package.json`, and some of those markers carry the package's own
+ * `name` too — so neither presence nor a `name` tells a marker from a root.
+ * Measured in this repo's installed tree: `engine.io-client/build/{cjs,esm}` and
+ * `@socket.io/component-emitter/lib/cjs` are that shape. A module there reading
+ * its package's real manifest — the `new URL('../package.json',
+ * import.meta.url)` this file's header opens with, one level deeper — would be
+ * reading OUTSIDE its root, get declined, and ship the live read this module
+ * exists to remove.
+ *
+ * For a FIRST-PARTY file the root is the nearest ancestor carrying a
+ * `package.json`, and it has to be the NEAREST: in a monorepo the outermost one
+ * is the workspace root, which would let one package inline its siblings' files.
+ * The fallback when nothing above declares one is the module's own directory,
+ * which is the narrowest answer available rather than a licence to read upward.
+ */
+export declare function resourceRootFor(sourceFilePath: string): string;
+/**
+ * Is `target` inside `root` (or `root` itself)?
+ *
+ * `relative()` rather than `startsWith`: the string test calls `/lib64` a child
+ * of `/lib`. `resolve()` first, so a `..` composition is normalised before the
+ * comparison rather than after it. `platform` is injected and the branches use
+ * `path.win32`/`path.posix` explicitly, the same shape as
+ * {@link isAbsoluteFsPath}, so both run from either host.
+ *
+ * TEXTUAL, deliberately: no `realpathSync`. Both directions of that choice are
+ * the safe one here. A read that reaches into the package through a symlink
+ * resolves to a path outside the root and is DECLINED, which leaves a working
+ * runtime read; and a path textually inside the root cannot be widened by a
+ * symlink npm never creates. Resolving would also cost a syscall per candidate
+ * and break the zip-resident PnP case, whose paths are not files.
+ */
+export declare function isWithin(target: string, root: string, platform?: string): boolean;
 /**
  * Is `v` an absolute filesystem path on `platform`?
  *

package/lib/utils/inline-static-reads.js

@@ -40,6 +40,27 @@
 //
 // Anything not statically resolvable is left untouched — the legacy
 // `import.meta.url` rewriter still applies as a fallback.
+//
+// WHAT IS DELIBERATELY NOT INLINED, and it is not about resolvability. A read
+// only belongs in the bundle when its answer is a property of the BUILD; a read
+// of the machine's own layout is a property of the HOST, and freezing it ships
+// the build machine's answer to every user. `evalPathExpr` therefore refuses a
+// path that resolves outside the reading module's own package (see
+// `resourceRootFor`), however statically resolvable it is.
+//
+// Measured on a OnePlus 6T (postmarketOS, musl 1.2.6, aarch64) against the
+// bundled CLI of 2026-09-08, before that gate existed:
+//
+//     readdirSync('/lib')                     77 entries, no ld-musl-*
+//     existsSync('/lib/ld-musl-aarch64.so.1') false
+//
+// Both answers were the Fedora build host's, baked in at build time — the real
+// directory holds 2076 entries including `ld-musl-aarch64.so.1`. That is the
+// probe `detectHostLibc` reads, so a bundled `gjsify` answered `glibc` on a musl
+// machine and every musl-aware decision downstream — `prebuildDirCandidates`'
+// `-musl` preference, the launcher shims, the fallback report — was inert for
+// the life of the bundle. Ten runs, ten times `glibc`. Nothing failed loudly:
+// the glibc prebuild loads under musl's loader until it wants a glibc symbol.
 import * as acorn from 'acorn';
 import { tsPlugin } from 'acorn-typescript';
 import { dirname, join, resolve, basename, relative, extname, posix, win32 } from 'node:path';
@@ -138,6 +159,7 @@ export function inlineStaticReads(src, sourceFilePath) {
     }
     const ctx = {
         sourceUrl: pathToFileURL(sourceFilePath).href,
+        resourceRoot: resourceRootFor(sourceFilePath),
     };
     const edits = [];
     forEachCallExpression(ast, (node) => {
@@ -341,18 +363,125 @@ function tryInlineReadFile(node, ctx, forceTextEncoding) {
  */
 function evalPathExpr(node, ctx) {
     const v = evalExpr(node, ctx);
+    // ONE exit for both shapes, and that is the whole point of the arrangement. The
+    // URL branch used to `return` before any gate ran, so `new URL('/proc',
+    // import.meta.url)` and `new URL('file:///lib')` were read on the builder while
+    // the same read spelled `fileURLToPath(new URL(…))` was declined. Two spellings
+    // of one expression cannot answer differently, and `new URL(<lit>,
+    // import.meta.url)` is the spelling this module was written for.
+    let asPath;
     if (v instanceof URL) {
-        if (v.protocol === 'file:')
-            return fileURLToPath(v);
-        return undefined;
+        asPath = v.protocol === 'file:' ? fileURLToPath(v) : undefined;
+    }
+    else if (typeof v === 'string') {
+        asPath = v.startsWith('file://') ? fileURLToPath(v) : isAbsoluteFsPath(v) ? v : undefined;
     }
-    if (typeof v !== 'string')
+    if (asPath === undefined)
         return undefined;
-    if (v.startsWith('file://'))
-        return fileURLToPath(v);
-    if (isAbsoluteFsPath(v))
-        return v;
-    return undefined;
+    // Resolvable is not the same as bundlable. Declining is the safe direction:
+    // the call is simply left in place and reads at runtime, which is what a host
+    // probe wants. Silent on purpose — a probe of `/proc`, `/sys` or `/lib` is
+    // ordinary in a runtime shim, and warning about each one would bury the
+    // decline that matters under the ones that do not. What stops this silence
+    // costing what `isAbsoluteFsPath`'s did is that the declines have ROWS in
+    // `inline-static-reads.spec.ts` — a warning nobody reads would not have caught
+    // that one either.
+    if (!isWithin(asPath, ctx.resourceRoot))
+        return undefined;
+    return asPath;
+}
+/**
+ * The tree whose contents are a property of the BUILD rather than of the host —
+ * the reading module's own package.
+ *
+ * A package's own resources are what this module exists to bundle. Anything else
+ * — `/lib`, `/etc`, `/proc`, a sibling package's data — is either the machine's
+ * layout or another package's business, and its answer at build time is not its
+ * answer at run time.
+ *
+ * TWO RULES, because "the package" is answered two different ways and picking one
+ * of them gets the other wrong.
+ *
+ * For an INSTALLED file the root is STRUCTURAL: the directory whose parent is
+ * `node_modules` (or `node_modules/@scope`). Probing for the nearest
+ * `package.json` instead lands on the wrong directory for any package that
+ * dual-publishes, because the `{"type":"commonjs"}` marker beside the emitted
+ * output IS a `package.json`, and some of those markers carry the package's own
+ * `name` too — so neither presence nor a `name` tells a marker from a root.
+ * Measured in this repo's installed tree: `engine.io-client/build/{cjs,esm}` and
+ * `@socket.io/component-emitter/lib/cjs` are that shape. A module there reading
+ * its package's real manifest — the `new URL('../package.json',
+ * import.meta.url)` this file's header opens with, one level deeper — would be
+ * reading OUTSIDE its root, get declined, and ship the live read this module
+ * exists to remove.
+ *
+ * For a FIRST-PARTY file the root is the nearest ancestor carrying a
+ * `package.json`, and it has to be the NEAREST: in a monorepo the outermost one
+ * is the workspace root, which would let one package inline its siblings' files.
+ * The fallback when nothing above declares one is the module's own directory,
+ * which is the narrowest answer available rather than a licence to read upward.
+ */
+export function resourceRootFor(sourceFilePath) {
+    const own = dirname(resolve(sourceFilePath));
+    const installed = installedPackageRootFor(own);
+    if (installed !== undefined)
+        return installed;
+    let dir = own;
+    for (;;) {
+        if (existsSync(join(dir, 'package.json')))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return own;
+        dir = parent;
+    }
+}
+/**
+ * The `node_modules/<name>` — or `node_modules/@scope/<name>` — directory `dir`
+ * lives in, or `undefined` when it is not inside an installed package.
+ *
+ * The LAST `node_modules` segment on the way up, so a nested dependency
+ * (`node_modules/a/node_modules/b`) and a Yarn-PnP zip
+ * (`…/cache/x.zip/node_modules/@scope/b`) both resolve to themselves rather than
+ * to whatever contains them. No filesystem probe: the layout is the answer, and a
+ * zip-resident path has no `package.json` a plain `existsSync` can see.
+ */
+function installedPackageRootFor(dir) {
+    let cur = dir;
+    for (;;) {
+        const parent = dirname(cur);
+        if (parent === cur)
+            return undefined;
+        const parentName = basename(parent);
+        if (parentName === 'node_modules')
+            return cur;
+        if (parentName.startsWith('@') && basename(dirname(parent)) === 'node_modules')
+            return cur;
+        cur = parent;
+    }
+}
+/**
+ * Is `target` inside `root` (or `root` itself)?
+ *
+ * `relative()` rather than `startsWith`: the string test calls `/lib64` a child
+ * of `/lib`. `resolve()` first, so a `..` composition is normalised before the
+ * comparison rather than after it. `platform` is injected and the branches use
+ * `path.win32`/`path.posix` explicitly, the same shape as
+ * {@link isAbsoluteFsPath}, so both run from either host.
+ *
+ * TEXTUAL, deliberately: no `realpathSync`. Both directions of that choice are
+ * the safe one here. A read that reaches into the package through a symlink
+ * resolves to a path outside the root and is DECLINED, which leaves a working
+ * runtime read; and a path textually inside the root cannot be widened by a
+ * symlink npm never creates. Resolving would also cost a syscall per candidate
+ * and break the zip-resident PnP case, whose paths are not files.
+ */
+export function isWithin(target, root, platform = process.platform) {
+    const p = platform === 'win32' ? win32 : posix;
+    const rel = p.relative(p.resolve(root), p.resolve(target));
+    if (rel === '')
+        return true;
+    return !rel.startsWith('..') && !p.isAbsolute(rel);
 }
 /**
  * Is `v` an absolute filesystem path on `platform`?

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/rolldown-plugin-gjsify",
-    "version": "0.48.0",
+    "version": "0.50.0",
     "description": "Rolldown / Rollup / Vite plugin orchestrator for GJS, Node, and Browser targets",
     "type": "module",
     "main": "lib/index.js",
@@ -60,11 +60,11 @@
     ],
     "license": "MIT",
     "dependencies": {
-        "@gjsify/console": "^0.48.0",
-        "@gjsify/resolve-npm": "^0.48.0",
-        "@gjsify/rolldown-plugin-deepkit": "^0.48.0",
-        "@gjsify/rolldown-plugin-pnp": "^0.48.0",
-        "@gjsify/vite-plugin-blueprint": "^0.48.0",
+        "@gjsify/console": "^0.50.0",
+        "@gjsify/resolve-npm": "^0.50.0",
+        "@gjsify/rolldown-plugin-deepkit": "^0.50.0",
+        "@gjsify/rolldown-plugin-pnp": "^0.50.0",
+        "@gjsify/vite-plugin-blueprint": "^0.50.0",
         "@rollup/pluginutils": "^5.4.0",
         "acorn": "^8.17.0",
         "acorn-typescript": "^1.4.13",
@@ -74,7 +74,7 @@
         "sass": "^1.101.0"
     },
     "peerDependencies": {
-        "@gjsify/lightningcss-native": "^0.48.0",
+        "@gjsify/lightningcss-native": "^0.50.0",
         "rolldown": "^1.1.4"
     },
     "peerDependenciesMeta": {
@@ -86,8 +86,8 @@
         }
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.48.0",
-        "@gjsify/unit": "^0.48.0",
+        "@gjsify/cli": "^0.50.0",
+        "@gjsify/unit": "^0.50.0",
         "@types/node": "^25.9.2",
         "rolldown": "^1.1.4",
         "typescript": "^6.0.3"