@gjsify/rolldown-plugin-gjsify 0.64.12 → 0.64.13-next.283

package/lib/app/nativescript.js

@@ -44,6 +44,7 @@ import { ALIASES_NODE_FOR_NATIVESCRIPT, GI_RENDERERS, getDerivedAliasesSync } fr
 import { globToEntryPoints } from '../utils/entry-points.js';
 import { gjsImportsEmptyPlugin } from '../plugins/gjs-imports-empty.js';
 import { giRendererPlugin } from '../plugins/gi-renderer.js';
+import { nativescriptLocalePlugin } from '../plugins/nativescript-locale.js';
 import { blueprintTemplateExit } from '../utils/blueprint-template-exit.js';
 import { platformResolvePlugin, nativescriptSuffixChain, detectNativescriptPlatform, nativescriptPlatformDefines, } from '../plugins/platform-resolve.js';
 import { unresolvedWorkspaceImportPlugin } from '../plugins/unresolved-workspace-import.js';
@@ -190,6 +191,9 @@ export const setupForNativescript = async (input) => {
         // holds the author's intent; the guard and the absence are untouched.
         gschemaPlugin({ mode: 'emit', register: GSCHEMA_REGISTER.nativescript }),
         gresourcePlugin({ compressed: 'strip' }),
+        ...(input.pluginOptions.nativescriptLocale
+            ? [nativescriptLocalePlugin(input.pluginOptions.nativescriptLocale)]
+            : []),
         implicitGlobalAssignPlugin(),
         // NO cssAsStringPlugin — NS ships its own CSS pipeline via
         // @nativescript/core; .css imports are handled by the consuming

package/lib/index.d.ts

@@ -26,6 +26,10 @@ export { aliasPlugin } from './plugins/alias.js';
 export type { AliasPluginOptions } from './plugins/alias.js';
 export { gjsImportsEmptyPlugin } from './plugins/gjs-imports-empty.js';
 export { giRendererPlugin } from './plugins/gi-renderer.js';
+export { nativescriptLocalePlugin, collectLocaleAssets, NATIVESCRIPT_LOCALE_DIR, NATIVESCRIPT_LOCALE_PLUGIN, } from './plugins/nativescript-locale.js';
+export type { NativescriptLocaleOptions, LocaleAsset } from './plugins/nativescript-locale.js';
+export { nativescriptGiSelectionPlugin, NATIVESCRIPT_GI_SELECTION_PLUGIN, } from './plugins/nativescript-gi-selection.js';
+export type { NativescriptGiSelectionOptions } from './plugins/nativescript-gi-selection.js';
 export { externalsPlugin } from './plugins/externals.js';
 export type { ExternalsPredicate, ExternalsPluginOptions } from './plugins/externals.js';
 export { unresolvedWorkspaceImportPlugin, classifyImport, isWorkspaceSpecifier, formatUnresolvedWorkspaceImport, buildReverseAliasIndex, UnresolvedWorkspaceImportError, } from './plugins/unresolved-workspace-import.js';

package/lib/index.js

@@ -17,6 +17,8 @@ export { shebangPlugin, GJS_SHEBANG, NODE_SHEBANG, expandEnvTemplate, resolveShe
 export { aliasPlugin } from './plugins/alias.js';
 export { gjsImportsEmptyPlugin } from './plugins/gjs-imports-empty.js';
 export { giRendererPlugin } from './plugins/gi-renderer.js';
+export { nativescriptLocalePlugin, collectLocaleAssets, NATIVESCRIPT_LOCALE_DIR, NATIVESCRIPT_LOCALE_PLUGIN, } from './plugins/nativescript-locale.js';
+export { nativescriptGiSelectionPlugin, NATIVESCRIPT_GI_SELECTION_PLUGIN, } from './plugins/nativescript-gi-selection.js';
 export { externalsPlugin } from './plugins/externals.js';
 export { unresolvedWorkspaceImportPlugin, classifyImport, isWorkspaceSpecifier, formatUnresolvedWorkspaceImport, buildReverseAliasIndex, UnresolvedWorkspaceImportError, } from './plugins/unresolved-workspace-import.js';
 export { napiNodeAddonPlugin, resolveAddonPath, enumerateAddonTargets, nearestPackageRoot, classifySpecifier, directNodeShim, nodeGypBuildShim, bindingsShim, napiRsShim, ADDON_FILTER_RE, isNapiRsPackageJson, isNapiRsSibling, isGjsifyNativeBridge, detectNapiRsEntry, hostNapiRsTriple, AddonNotBuiltError, } from './plugins/napi-node-addon.js';

package/lib/plugins/gi-optional.js

@@ -7,7 +7,7 @@
 // The `optional` query flag is the declaration that the app has that decision to make.
 // The import resolves to a virtual module that loads the SAME specifier without the
 // flag inside a try/catch, so the emitted bundle still carries the verbatim
-// `gi://Goa?version=1.0` that `ship/gi-namespaces.ts` and `depends.ts` read, and the
+// `gi://Goa?version=1.0` that `utils/gi-namespaces.ts` and the CLI's `depends.ts` read, and the
 // namespace is `undefined` when it is absent.
 //
 // BOTH app targets, and the second one was the trap. `--app node` already loads a

package/lib/plugins/nativescript-gi-selection.d.ts

@@ -0,0 +1,11 @@
+import type { Plugin } from 'rolldown';
+export declare const NATIVESCRIPT_GI_SELECTION_PLUGIN = "gjsify-nativescript-gi-selection";
+export interface NativescriptGiSelectionOptions {
+    /** `giNamespaces` as the app declares it, `Ns` or `Ns-Version`. */
+    declared: readonly string[];
+}
+/**
+ * Refuse a NativeScript bundle that imports a GI namespace the APK was not told to
+ * carry, and warn about one it was told to carry and does not appear to import.
+ */
+export declare function nativescriptGiSelectionPlugin(options: NativescriptGiSelectionOptions): Plugin;

package/lib/plugins/nativescript-gi-selection.js

@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: MIT
+// The ADR 0117 § 2 gate on the VITE path: every GI namespace the emitted bundle loads
+// has to be one the APK was told to carry.
+//
+// WHY A SECOND PLACE AT ALL. `gjsify build --app nativescript` already checks this in
+// `actions/build.ts`, but a NativeScript app is not built that way: the NS CLI drives
+// Vite, so `defineNativescriptConfig` is the only thing in the loop. Without this the
+// key is accepted by the config loader and acted on by nothing — the exact shape this
+// repo keeps paying for, and on Android it is not advice: a `.deb` that under-declares
+// its typelibs can still be fixed by installing a package, while an APK carries its
+// whole GI stack or does without it.
+//
+// SAME ORACLE, SAME PLANNER, deliberately: {@link planGiSelection} over
+// {@link scanGiNamespaces} of the emitted chunks, so the two paths cannot disagree
+// about what a given config means. `generateBundle` rather than a `resolveId`
+// observer, and that was MEASURED, not preferred:
+//
+//   with `giRenderer: true` (what every NS app here uses) the renderer plugin answers
+//   `gi://Gtk` and `gi://Adw` with `@gjsify/adwaita-nativescript`'s namespaces, so those
+//   specifiers are in the module graph of a build that needs NO Gtk typelib at all.
+//   Feeding them to the planner would demand `giNamespaces: ["Gtk", "Adw"]`, which the
+//   pinned sysroot cannot satisfy (no `cairo-1.0` / `freetype2-2.0` / `fontconfig-2.0`
+//   typelib), i.e. it would refuse a build that works today.
+//
+// The emitted file is what gets installed, and it carries only what survived the
+// renderer. That is the honest input.
+//
+// The scan is a LOWER BOUND, so only one direction is fatal — the asymmetry
+// `gi-selection.ts` carries in full.
+import { scanGiNamespaces } from '../utils/gi-namespaces.js';
+import { assertGiNamespaceEntries, planGiSelection } from '../utils/gi-selection.js';
+export const NATIVESCRIPT_GI_SELECTION_PLUGIN = 'gjsify-nativescript-gi-selection';
+/**
+ * Refuse a NativeScript bundle that imports a GI namespace the APK was not told to
+ * carry, and warn about one it was told to carry and does not appear to import.
+ */
+export function nativescriptGiSelectionPlugin(options) {
+    // Checked when the plugin is composed, not when the bundle is written: a typo
+    // should fail before a full NativeScript build, and this is the Vite path's only
+    // reader of the key.
+    assertGiNamespaceEntries(options.declared, `${NATIVESCRIPT_GI_SELECTION_PLUGIN}: giNamespaces`);
+    return {
+        name: NATIVESCRIPT_GI_SELECTION_PLUGIN,
+        generateBundle(_outputOptions, bundle) {
+            // Namespace → the chunk it was first read from, so a refusal names a file
+            // somebody can open. `planGiSelection` is pure and knows neither.
+            const origin = new Map();
+            for (const [fileName, item] of Object.entries(bundle)) {
+                if (item.type !== 'chunk')
+                    continue;
+                const code = item.code;
+                if (typeof code !== 'string' || code.length === 0)
+                    continue;
+                for (const namespace of scanGiNamespaces(code)) {
+                    if (!origin.has(namespace))
+                        origin.set(namespace, fileName);
+                }
+            }
+            let selection;
+            try {
+                selection = planGiSelection({ declared: [...options.declared], scanned: [...origin.keys()] });
+            }
+            catch (error) {
+                const files = [...new Set(origin.values())].sort().join(', ');
+                throw new Error(`${NATIVESCRIPT_GI_SELECTION_PLUGIN}: ${error.message} (read from ${files})`);
+            }
+            for (const namespace of selection.unscanned) {
+                this.warn(`${NATIVESCRIPT_GI_SELECTION_PLUGIN}: giNamespaces declares ${namespace}, which the bundle ` +
+                    'does not appear to import. The APK carries it anyway — drop it if nothing needs it, ' +
+                    'since every selected namespace costs APK size.');
+            }
+        },
+    };
+}

package/lib/plugins/nativescript-locale.d.ts

@@ -0,0 +1,20 @@
+import type { Plugin } from 'rolldown';
+export declare const NATIVESCRIPT_LOCALE_PLUGIN = "gjsify-nativescript-locale";
+/** Directory below the app root (`<filesDir>/app`) that holds the catalogs. */
+export declare const NATIVESCRIPT_LOCALE_DIR = "locale";
+export interface NativescriptLocaleOptions {
+    /** Directory with the `<lang>.po` catalogs. */
+    poDirectory: string;
+    /** gettext domain — the `.mo` file name, and what the app passes to `bindtextdomain`. */
+    domain: string;
+    /** Output names for catalogs the built-in table does not know, as in `gettextPlugin`. */
+    localeNames?: Record<string, readonly string[]>;
+}
+export interface LocaleAsset {
+    fileName: string;
+    source: Uint8Array;
+}
+/** `msgfmt` with an argv array (no shell); `-o -` streams the `.mo` to stdout. */
+export declare function msgfmtToBuffer(poFile: string): Promise<Uint8Array>;
+export declare function collectLocaleAssets(options: NativescriptLocaleOptions, compile?: (poFile: string) => Promise<Uint8Array>): Promise<LocaleAsset[]>;
+export declare function nativescriptLocalePlugin(options: NativescriptLocaleOptions): Plugin;

package/lib/plugins/nativescript-locale.js

@@ -0,0 +1,56 @@
+// Compile an app's `po/` into `locale/<lang>/LC_MESSAGES/<domain>.mo` ASSETS of the bundle.
+//
+// On Android the GLib gettext (gi-runtime-android's libintl reader) opens the catalog from the
+// real filesystem, and NativeScript extracts `assets/app/**` to `<filesDir>/app/**`. So the `.mo`
+// tree has to ride along in the staging dir the NS build copies — emitted as assets rather than
+// written beside the output, because Vite's `emptyOutDir` wipes anything written before the
+// bundle. The runtime resolves the same directory with `localeDir` (`@gjsify/adwaita-app/locale`).
+import { execFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { findAvailableLanguages, planCatalogNames } from '@gjsify/vite-plugin-gettext';
+const run = promisify(execFile);
+export const NATIVESCRIPT_LOCALE_PLUGIN = 'gjsify-nativescript-locale';
+/** Directory below the app root (`<filesDir>/app`) that holds the catalogs. */
+export const NATIVESCRIPT_LOCALE_DIR = 'locale';
+/** `msgfmt` with an argv array (no shell); `-o -` streams the `.mo` to stdout. */
+export async function msgfmtToBuffer(poFile) {
+    const { stdout } = await run('msgfmt', ['--output-file=-', poFile], {
+        encoding: 'buffer',
+        maxBuffer: 64 * 1024 * 1024,
+    });
+    return stdout;
+}
+export async function collectLocaleAssets(options, compile = msgfmtToBuffer) {
+    if (!existsSync(options.poDirectory)) {
+        throw new Error(`${NATIVESCRIPT_LOCALE_PLUGIN}: PO directory ${options.poDirectory} does not exist`);
+    }
+    const languages = await findAvailableLanguages(options.poDirectory, NATIVESCRIPT_LOCALE_PLUGIN, false);
+    const plans = planCatalogNames(languages, {
+        pluginName: NATIVESCRIPT_LOCALE_PLUGIN,
+        namespace: 'posix',
+        localeNames: options.localeNames,
+    });
+    const assets = [];
+    for (const plan of plans) {
+        const source = await compile(join(options.poDirectory, `${plan.catalog}.po`));
+        for (const dir of plan.posix) {
+            assets.push({
+                fileName: `${NATIVESCRIPT_LOCALE_DIR}/${dir}/LC_MESSAGES/${options.domain}.mo`,
+                source,
+            });
+        }
+    }
+    return assets;
+}
+export function nativescriptLocalePlugin(options) {
+    return {
+        name: NATIVESCRIPT_LOCALE_PLUGIN,
+        async generateBundle() {
+            for (const asset of await collectLocaleAssets(options)) {
+                this.emitFile({ type: 'asset', fileName: asset.fileName, source: asset.source });
+            }
+        },
+    };
+}

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

@@ -1,3 +1,4 @@
+import type { NativescriptLocaleOptions } from '../plugins/nativescript-locale.js';
 import type { App } from './app.js';
 import type { SourceDialect } from './source-dialect.js';
 /** CSS handling forwarded to Rolldown / Lightning CSS. */
@@ -105,6 +106,12 @@ export interface PluginOptions {
      * every unanswerable namespace from a silent stub into a hard build failure.
      */
     giRenderer?: boolean;
+    /**
+     * `--app nativescript` only: compile this PO directory to
+     * `locale/<lang>/LC_MESSAGES/<domain>.mo` assets of the bundle, so the Android libintl
+     * reader finds them under `<filesDir>/app/locale`. See `plugins/nativescript-locale.ts`.
+     */
+    nativescriptLocale?: NativescriptLocaleOptions;
     /**
      * 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/gi-namespaces.d.ts

@@ -0,0 +1,23 @@
+/**
+ * What a bundle loads, split by whether the host must provide it.
+ *
+ * `namespaces` is the union — the same answer {@link scanGiNamespaces} has always
+ * given — and `optional` is the subset the artifact itself marks optional. A namespace
+ * in both is still a hard dependency as far as anything else is concerned: the
+ * importer asked for it both ways, and only one of those edges degrades.
+ */
+export interface GiRequirements {
+    /** Every GI namespace the bundle loads, `Ns-Version` where a specifier pins one. */
+    namespaces: string[];
+    /** The subset carrying the bundler's optional marker — absent is not fatal. */
+    optional: string[];
+}
+/**
+ * Extract the GI namespaces a bundle imports, as `Ns-Version` when the
+ * specifier pins one and bare `Ns` when it does not.
+ */
+export declare function scanGiNamespaces(source: string): string[];
+/** {@link scanGiNamespaces}, plus which of them the artifact marks optional (ADR 0087). */
+export declare function scanGiRequirements(source: string): GiRequirements;
+/** `gi://Gtk?version=4.0` → `Gtk-4.0`; `gi://Gtk` → `Gtk`; anything else → null. */
+export declare function giSpecifierKey(specifier: string): string | null;

package/lib/utils/gi-namespaces.js

@@ -0,0 +1,275 @@
+// Which GI namespaces does this bundle actually load?
+//
+// Read off the EMITTED bundle, because that is the file that gets installed —
+// and the emitted form is not one form but two, which is the correction this
+// header carries. Under `--app gjs`, `gi://` is a real module protocol, so the
+// bundler keeps those specifiers in the output verbatim
+// (`rolldown-plugin-gjsify`'s externals plugin) and the artifact carries its own
+// dependency list. Under `--app node` there is no such protocol:
+// `gjsGiNodePlugin` rewrites every `gi://Ns?version=X` into a shim whose body is
+// `require('@gjsify/node-gi/gi').requireGi("Ns", "X")`, so the specifier this
+// scanner was written to find is gone from the file by construction.
+//
+// WHAT THAT COST, and why reading one form is not "mostly right": these
+// namespaces are what `depends.ts` maps to `gir1.2-gtk-4.0` and friends
+// (ADR 0024 § 6). A `--app node` project therefore derived an EMPTY typelib
+// dependency set — the package installed cleanly and died at its first GI call,
+// which is the same failure the bare-side-effect-import fix below was written to
+// prevent, arriving again through the other build target. Nothing caught it
+// because every ship fixture's "node bundle" was hand-written with `gi://`
+// imports in it: a shape `gjsify build --app node` cannot emit and node cannot
+// run.
+//
+// PARSED, not pattern-matched, and the first version of this file is why. A
+// regex over the bundle text got it wrong in both directions at once:
+//
+//   * it missed `import "gi://Soup?version=3.0"` — the bare side-effect form,
+//     which is exactly what `@gjsify/fetch` puts at the top of every bundle
+//     that pulls it. The package would have shipped without libsoup, installed
+//     cleanly, and died at the first request.
+//   * it matched `gi://…` inside a diagnostic STRING containing the word
+//     `from`, and since an unmapped namespace fails the build, that made a
+//     correct project unbuildable.
+//
+// `walkModuleAst` answers both questions in ONE pass, and it is the same acorn
+// pass the CLI already uses to compute its own runtime closure — so there is one
+// definition of "what does this file import" rather than two.
+//
+// HARD OR OPTIONAL, since ADR 0087: a `gi://Ns?version=X&optional` import still
+// appears in the emitted file, so this scanner still reports its namespace — and
+// `depends.ts` has to know it may be absent. The discriminator is the marker
+// statement the bundler's own optional shim emits (`GI_OPTIONAL_MARKER`, imported
+// from the plugin that writes it rather than restated here). NOT the `import()`
+// SHAPE, which was the tempting reading of the same file: an app that writes its own
+// `await import('gi://Goa')` without the flag must stay a HARD dependency, and
+// classifying it as optional would move a package the host must have out of its
+// `Depends:` — the failure this whole chain exists to prevent, reached from the other
+// direction.
+import { GI_OPTIONAL_MARKER } from '../plugins/gi-optional.js';
+import { importedSpecifier, staticStringValue, walkModuleAst } from './module-ast.js';
+/** The module a `--app node` bundle reaches GI through. */
+const NODE_GI_MODULE = '@gjsify/node-gi/gi';
+/** Namespaces are GI identifiers; anything else is a call this reader misread. */
+const NAMESPACE = /^[A-Za-z][A-Za-z\d_]*$/;
+/**
+ * Extract the GI namespaces a bundle imports, as `Ns-Version` when the
+ * specifier pins one and bare `Ns` when it does not.
+ */
+export function scanGiNamespaces(source) {
+    return scanGiRequirements(source).namespaces;
+}
+/** {@link scanGiNamespaces}, plus which of them the artifact marks optional (ADR 0087). */
+export function scanGiRequirements(source) {
+    const found = new Set();
+    const optional = new Set();
+    // TWO SETS, because the two kinds of binding are not interchangeable and
+    // treating them as one over-approximated on a real minified bundle. A
+    // namespace object (`import * as gi`) and a required module object are only
+    // ever the OBJECT of `.requireGi(…)`: calling a module namespace is a
+    // TypeError, so a bare `gi(…)` is never one of ours. Only `requireGi` itself
+    // — the named import, or the default export, which IS `requireGi` — is
+    // callable on its own.
+    //
+    // Measured on `gjsify build --app node` (minify is the DEFAULT): a file with
+    // `import * as gi from '@gjsify/node-gi/gi'` and a callback parameter emitted
+    // as `function render(e,t){return e(t)+e(\`Zzqfoo\`)}` — where the minifier
+    // gave the import and the parameter the SAME short name in different scopes.
+    // Read as one set, `e(\`Zzqfoo\`)` became the namespace `Zzqfoo`, and
+    // `deriveDepends` then refused to package a correct project.
+    const callable = new Set();
+    const objects = new Set();
+    const calls = [];
+    walkModuleAst(source, (node) => {
+        const specifier = importedSpecifier(node);
+        if (specifier !== null) {
+            const key = giSpecifierKey(specifier);
+            if (key !== null)
+                found.add(key);
+            if (node.type === 'ImportDeclaration' && specifier === NODE_GI_MODULE) {
+                collectNodeGiBindings(node, callable, objects);
+            }
+            return;
+        }
+        if (node.type === 'VariableDeclarator' && loadsNodeGiModule(node.init)) {
+            const id = node.id;
+            // An OBJECT: `const gi = require('@gjsify/node-gi/gi')` is the module,
+            // reached as `gi.requireGi(…)` and never called directly.
+            if (id?.type === 'Identifier' && typeof id.name === 'string')
+                objects.add(id.name);
+            return;
+        }
+        // Collected rather than resolved in place: a call can precede the
+        // `require` that binds its callee (the shim's `load()` is hoisted above
+        // nothing, but a minifier is free to reorder declarations), so the
+        // binding set has to be complete before any call is judged.
+        if (node.type === 'CallExpression')
+            calls.push(node);
+    });
+    for (const call of calls) {
+        const marker = optionalMarkerNamespace(call);
+        if (marker !== null) {
+            optional.add(marker);
+            continue;
+        }
+        const key = requireGiNamespace(call, callable, objects);
+        if (key !== null)
+            found.add(key);
+    }
+    return { namespaces: [...found].sort(), optional: [...optional].filter((ns) => found.has(ns)).sort() };
+}
+/**
+ * The namespace an optional-marker call names, or `null` when this is not one.
+ *
+ * The shape is the bundler's: `globalThis[Symbol.for(GI_OPTIONAL_MARKER)]?.("Ns", "X")`,
+ * matched on BOTH halves rather than on the whole statement — the minifier rewrites
+ * the string literals to backticks and the optional call to a `ChainExpression`
+ * around the `CallExpression` this walk still reaches, and a plain call (a host that
+ * has a handler the minifier could prove is non-null) reads the same way.
+ */
+function optionalMarkerNamespace(call) {
+    const callee = call.callee;
+    if (callee?.type !== 'MemberExpression' || callee.computed !== true)
+        return null;
+    // `globalThis[Symbol.for(KEY)]` — a computed member whose PROPERTY is the
+    // `Symbol.for` call, so the key is an argument of that inner call rather than
+    // of the outer one. Verified against acorn's own shape: `optional` chaining
+    // wraps the whole thing in a `ChainExpression`, which the walk descends into,
+    // so the `CallExpression` reaches this function either way.
+    const keyCall = callee.property;
+    if (keyCall?.type !== 'CallExpression')
+        return null;
+    const keyCallee = keyCall.callee;
+    const keyObject = keyCallee?.type === 'MemberExpression' ? keyCallee.object : undefined;
+    const keyProperty = keyCallee?.type === 'MemberExpression' ? keyCallee.property : undefined;
+    if (keyObject?.type !== 'Identifier' || keyObject.name !== 'Symbol')
+        return null;
+    if (keyProperty?.type !== 'Identifier' || keyProperty.name !== 'for')
+        return null;
+    const keyArgs = keyCall.arguments ?? [];
+    if (staticStringValue(keyArgs[0]) !== GI_OPTIONAL_MARKER)
+        return null;
+    const host = callee.object;
+    if (host?.type !== 'Identifier' || host.name !== 'globalThis')
+        return null;
+    const args = call.arguments ?? [];
+    const namespace = staticStringValue(args[0]);
+    if (namespace === null || !NAMESPACE.test(namespace))
+        return null;
+    const version = staticStringValue(args[1]);
+    return version === null || version === '' ? namespace : `${namespace}-${version}`;
+}
+/** `gi://Gtk?version=4.0` → `Gtk-4.0`; `gi://Gtk` → `Gtk`; anything else → null. */
+export function giSpecifierKey(specifier) {
+    if (!specifier.startsWith('gi://'))
+        return null;
+    const rest = specifier.slice('gi://'.length);
+    const [namespace, query] = rest.split('?', 2);
+    if (namespace === undefined || !NAMESPACE.test(namespace))
+        return null;
+    if (query === undefined)
+        return namespace;
+    const version = /(?:^|&)version=([^&]+)/.exec(query)?.[1];
+    return version === undefined ? namespace : `${namespace}-${version}`;
+}
+/**
+ * What an `import … from '@gjsify/node-gi/gi'` binds, split by what it can BE.
+ *
+ * All three spellings appear in real code and the default export IS `requireGi`
+ * (`packages/node-gi/node-gi/gi.d.ts`), so the named import (under any local
+ * name — `import { requireGi as gi }` renames it) and the default import are
+ * CALLABLE. A namespace import is not: calling a module namespace object throws,
+ * so it can only ever be the object of `.requireGi(…)`, and putting it in the
+ * callable set is what let a minified callback parameter of the same name be
+ * read as a `requireGi` call.
+ */
+function collectNodeGiBindings(node, callable, objects) {
+    const specifiers = node.specifiers ?? [];
+    for (const specifier of specifiers) {
+        const local = specifier.local;
+        if (local?.type !== 'Identifier' || typeof local.name !== 'string')
+            continue;
+        const imported = specifier.imported;
+        if (specifier.type === 'ImportNamespaceSpecifier')
+            objects.add(local.name);
+        else if (specifier.type === 'ImportDefaultSpecifier')
+            callable.add(local.name);
+        else if (imported?.type === 'Identifier' && imported.name === 'requireGi')
+            callable.add(local.name);
+    }
+}
+/**
+ * A call that LOADS `@gjsify/node-gi/gi` — recognised by its argument, never by
+ * the name of the callee.
+ *
+ * THE CALLEE NAME DOES NOT SURVIVE BUNDLING, and reading it is how the first cut
+ * of this function passed its own tests while answering `[]` for every real
+ * artifact. Measured on `gjsify build --app node` output for a two-import app,
+ * which is the exact input this module exists to read:
+ *
+ *     unminified   const require$1 = createRequire(import.meta.url);
+ *                  … require$1("@gjsify/node-gi/gi").requireGi("Gtk", "4.0")
+ *     minified     const n = e(import.meta.url);
+ *                  … n(`@gjsify/node-gi/gi`).requireGi(`Gtk`, `4.0`)
+ *
+ * Two shims in one bundle means two `require` bindings, so the second is renamed
+ * even without `--minify` (which is the DEFAULT). A reader keyed on the
+ * identifier `require` therefore loses one namespace unminified and both
+ * minified — silently, since an empty namespace list is a legal answer.
+ *
+ * The module STRING is what survives every rename, and it is a precise
+ * discriminator: a call taking `'@gjsify/node-gi/gi'` as its first argument is a
+ * load of that module under any name a bundler gives the loader.
+ */
+function loadsNodeGiModule(node) {
+    if (!node || typeof node !== 'object')
+        return false;
+    const call = node;
+    if (call.type !== 'CallExpression')
+        return false;
+    const args = call.arguments ?? [];
+    return staticStringValue(args[0]) === NODE_GI_MODULE;
+}
+/**
+ * The namespace a `requireGi(…)` call names, or `null` when this is not one.
+ *
+ * BINDING-TRACED rather than name-matched, and the asymmetry is deliberate: a
+ * bare `.requireGi(…)` on any object would over-approximate, and
+ * over-approximating is NOT the harmless direction here — an unmapped namespace
+ * fails the build, so a foreign method sharing the name would make a correct
+ * project unpackageable. Every accepted shape traces back to an import or
+ * require of `@gjsify/node-gi/gi` in this same file, which is what a bundle
+ * always has: the shim carries its own `require`, and a hand-written node-gi app
+ * carries its own import.
+ *
+ * Shadowing is the one gap left, and the split above is what makes it small.
+ * This reader has no scope analysis, so a local binding that reuses the name of
+ * the CALLABLE import — `requireGi` itself, or the default import — and is called
+ * with a GI-shaped string literal would still be read as one. A minifier can
+ * manufacture exactly that collision, which is why the two shapes it produces
+ * most (the namespace object and the required module object) are the two that no
+ * longer count as callees.
+ */
+function requireGiNamespace(call, callable, objects) {
+    const callee = call.callee;
+    let reached = false;
+    if (callee?.type === 'Identifier') {
+        reached = typeof callee.name === 'string' && callable.has(callee.name);
+    }
+    else if (callee?.type === 'MemberExpression' && callee.computed !== true) {
+        const property = callee.property;
+        if (property?.type !== 'Identifier' || property.name !== 'requireGi')
+            return null;
+        const object = callee.object;
+        reached =
+            loadsNodeGiModule(object) ||
+                (object?.type === 'Identifier' && typeof object.name === 'string' && objects.has(object.name));
+    }
+    if (!reached)
+        return null;
+    const args = call.arguments ?? [];
+    const namespace = staticStringValue(args[0]);
+    if (namespace === null || !NAMESPACE.test(namespace))
+        return null;
+    const version = staticStringValue(args[1]);
+    return version === null ? namespace : `${namespace}-${version}`;
+}

package/lib/utils/gi-selection.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Refuse a `giNamespaces` entry that is not a GI namespace, naming the entry.
+ *
+ * ONE definition for both paths that accept the key — `gjsify build`'s config loader
+ * and `defineNativescriptConfig` — because a shape check that holds on one of them is
+ * a project that builds through Vite and fails through the CLI for a typo. A free-form
+ * string surfaces as "the prefix has no typelib for …" hours later in the AAR build,
+ * naming the sysroot rather than the mistake.
+ *
+ * @param where how the caller spells the key, so the message points at the file the
+ *   reader is editing (`nativescript.giNamespaces` vs `giNamespaces`).
+ */
+export declare function assertGiNamespaceEntries(declared: readonly string[], where: string): void;
+/** What {@link planGiSelection} decided, and what it wants the build to say out loud. */
+export interface GiSelection {
+    /** The namespaces to hand the AAR builder, as the config spells them, deduped and sorted. */
+    selected: string[];
+    /** Declared but not found in the bundle — worth a warning, never a refusal. */
+    unscanned: string[];
+}
+/**
+ * Reconcile the configured namespace set with the one the emitted bundle imports.
+ *
+ * @param spec.declared `nativescript.giNamespaces`, as `Ns` or `Ns-Version`
+ * @param spec.scanned what {@link scanGiNamespaces} read off the emitted bundle
+ * @throws when the bundle imports a namespace the config does not cover
+ */
+export declare function planGiSelection({ declared, scanned }: {
+    declared: string[];
+    scanned: string[];
+}): GiSelection;

package/lib/utils/gi-selection.js

@@ -0,0 +1,94 @@
+// Which GI namespaces does this Android APK carry? — ADR 0117 § 2, the CLI half.
+//
+// THE CONFIG DECIDES AND THE BUNDLE IS CHECKED AGAINST IT, which is the asymmetry
+// the ADR turns on. The payload is cross-compiled hours earlier by
+// `build-gi-runtime-android.mjs` against a sha256-pinned sysroot; nothing at app-build
+// time can conjure a typelib that is not in it. So the config is the input, and the
+// scan of the emitted bundle is the EVIDENCE that the input is complete.
+//
+// The scan is a LOWER BOUND, and the two directions of disagreement are therefore not
+// symmetric:
+//
+//   * IMPORTED, NOT CONFIGURED → build error naming the namespace. The scanner found a
+//     real import; the APK will not have the typelib; the device throws at that import,
+//     after the download, reading like an application bug. This is the same failure
+//     `deriveDepends` refuses for distro packages (ADR 0024 § 6), reached from Android.
+//   * CONFIGURED, NOT IMPORTED → warning. `scanGiNamespaces` reads the emitted file and
+//     cannot see a namespace reached through a computed specifier, nor one loaded by a
+//     native dependency. Refusing here would make a correct project unbuildable on the
+//     scanner's blind spot — so it reports a probably-larger-than-necessary APK and
+//     builds it.
+//
+// COMPARED BY NAMESPACE, NOT BY STRING. A config may pin an ABI (`Gtk-4.0`) where the
+// bundle's specifier carries no version (`import 'gi://Gtk'`), and vice versa. Both
+// sides mean the same namespace, and string equality would fail a correct project on
+// the spelling.
+/** `Gtk-4.0` → `Gtk`; `Gtk` → `Gtk`. */
+function namespaceOf(entry) {
+    const dash = entry.indexOf('-');
+    return dash === -1 ? entry : entry.slice(0, dash);
+}
+/** `Ns` or `Ns-Version` — what the AAR builder resolves against the sysroot's typelib names. */
+const GI_SELECTION_ENTRY = /^[A-Za-z][A-Za-z\d_]*(-\d+(\.\d+)*)?$/;
+/**
+ * Refuse a `giNamespaces` entry that is not a GI namespace, naming the entry.
+ *
+ * ONE definition for both paths that accept the key — `gjsify build`'s config loader
+ * and `defineNativescriptConfig` — because a shape check that holds on one of them is
+ * a project that builds through Vite and fails through the CLI for a typo. A free-form
+ * string surfaces as "the prefix has no typelib for …" hours later in the AAR build,
+ * naming the sysroot rather than the mistake.
+ *
+ * @param where how the caller spells the key, so the message points at the file the
+ *   reader is editing (`nativescript.giNamespaces` vs `giNamespaces`).
+ */
+export function assertGiNamespaceEntries(declared, where) {
+    for (const entry of declared) {
+        if (!GI_SELECTION_ENTRY.test(entry)) {
+            throw new Error(`${where} entry "${entry}" is not a GI namespace. Write it as \`Gtk\` or \`Gtk-4.0\`.`);
+        }
+    }
+}
+/**
+ * The namespaces every AAR carries whether or not anything declares them.
+ *
+ * These back `libnode_gi.so` itself, so they are in the payload's DT_NEEDED closure
+ * before any selection happens (ADR 0110's measured core set). Demanding them in the
+ * config would make the key boilerplate and fail every project that exists today, for
+ * a selection that cannot change the bytes.
+ */
+const ALWAYS_PRESENT = new Set(['GLib', 'GObject', 'Gio', 'GioUnix', 'GLibUnix', 'GModule', 'GIRepository']);
+/**
+ * Reconcile the configured namespace set with the one the emitted bundle imports.
+ *
+ * @param spec.declared `nativescript.giNamespaces`, as `Ns` or `Ns-Version`
+ * @param spec.scanned what {@link scanGiNamespaces} read off the emitted bundle
+ * @throws when the bundle imports a namespace the config does not cover
+ */
+export function planGiSelection({ declared, scanned }) {
+    // A bare and a pinned declaration of one namespace are one selection, and the
+    // pinned spelling wins: it says something the bare one does not.
+    const byNamespace = new Map();
+    for (const entry of declared) {
+        const ns = namespaceOf(entry);
+        const held = byNamespace.get(ns);
+        if (held === undefined || (held === ns && entry !== ns))
+            byNamespace.set(ns, entry);
+    }
+    const missing = [
+        ...new Set(scanned.map(namespaceOf).filter((ns) => !byNamespace.has(ns) && !ALWAYS_PRESENT.has(ns))),
+    ].sort();
+    if (missing.length > 0) {
+        throw new Error(`The bundle imports ${missing.join(', ')}, which nativescript.giNamespaces does not declare. ` +
+            'An Android APK carries only the typelibs the config selects (ADR 0117), so this would ' +
+            `install and then throw at the import. Add ${missing.length === 1 ? 'it' : 'them'} to ` +
+            'nativescript.giNamespaces, or stop importing ' +
+            `${missing.length === 1 ? 'it' : 'them'}.`);
+    }
+    const seen = new Set(scanned.map(namespaceOf));
+    const unscanned = [...byNamespace.entries()]
+        .filter(([ns]) => !seen.has(ns))
+        .map(([, entry]) => entry)
+        .sort();
+    return { selected: [...byNamespace.values()].sort(), unscanned };
+}

package/lib/utils/index.d.ts

@@ -10,3 +10,9 @@ export { GJSIFY_VIRTUAL_PREFIX, isGjsifyVirtualModuleId } from './virtual-module
 export { locateSurvivingJsx, classifyJsxParseFailure, formatSurvivingJsx } from './jsx-survival.js';
 export type { SurvivingJsx } from './jsx-survival.js';
 export { wrapInputWithSideEffects } from './entry-wrapper.js';
+export { staticStringValue, walkModuleAst, importedSpecifier, moduleSpecifiers } from './module-ast.js';
+export type { SpecifierNode, AstNode } from './module-ast.js';
+export { scanGiNamespaces, scanGiRequirements, giSpecifierKey } from './gi-namespaces.js';
+export type { GiRequirements } from './gi-namespaces.js';
+export { planGiSelection, assertGiNamespaceEntries } from './gi-selection.js';
+export type { GiSelection } from './gi-selection.js';

package/lib/utils/index.js

@@ -9,3 +9,6 @@ export { inlineStaticReads, isAbsoluteFsPath, isWithin, resourceRootFor } from '
 export { GJSIFY_VIRTUAL_PREFIX, isGjsifyVirtualModuleId } from './virtual-module-id.js';
 export { locateSurvivingJsx, classifyJsxParseFailure, formatSurvivingJsx } from './jsx-survival.js';
 export { wrapInputWithSideEffects } from './entry-wrapper.js';
+export { staticStringValue, walkModuleAst, importedSpecifier, moduleSpecifiers } from './module-ast.js';
+export { scanGiNamespaces, scanGiRequirements, giSpecifierKey } from './gi-namespaces.js';
+export { planGiSelection, assertGiNamespaceEntries } from './gi-selection.js';

package/lib/utils/module-ast.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Literal module specifiers of `code`: static `import`/`export … from`, plus
+ * `import('<literal>')`.
+ *
+ * acorn rather than a regex — see the header. `allowHashBang` because a CLI's
+ * own entry is a bin (`#!/usr/bin/env node`), and a parse failure yields NO
+ * specifiers, which under-selects rather than mis-selects.
+ */
+export interface SpecifierNode {
+    type?: string;
+    value?: unknown;
+    expressions?: unknown[];
+    quasis?: Array<{
+        value?: {
+            cooked?: unknown;
+        };
+    }>;
+}
+/**
+ * The string a node names statically, or `null` when it is computed.
+ *
+ * A substitution-free TEMPLATE LITERAL is as static as a quoted string, and
+ * skipping it is not hypothetical: the minifier rewrites `await
+ * import('gi://GLib?version=2.0')` to a backtick form, so a Literal-only reader
+ * silently loses every dynamic import in a built bundle.
+ *
+ * Not named for specifiers, because it does not only read them: the same
+ * question is asked of a CALL ARGUMENT by `gi-namespaces.ts`, whose
+ * `requireGi("Gtk", "4.0")` carries a namespace and a version in exactly the two
+ * spellings above.
+ */
+export declare function staticStringValue(node: SpecifierNode | undefined): string | null;
+/** One node of the walk: whatever acorn produced, seen as a bag of properties. */
+export type AstNode = {
+    type?: string;
+} & Record<string, unknown>;
+/**
+ * Parse `code` as a module and call `visit` for every node in it.
+ *
+ * Exported because a SECOND parse is how the readers of a built bundle would drift
+ * apart: {@link moduleSpecifiers} answers "what does this file import" and
+ * `gi-namespaces.ts` answers "which GI namespaces does it load", and the second
+ * question has an answer the first cannot see — a `--app node` bundle carries no
+ * `gi://` specifier at all, only the `requireGi()` calls the bundler rewrote them
+ * into. One walker, many readers.
+ *
+ * A parse failure yields NO nodes rather than throwing: every caller is
+ * summarising a file it did not write, and under-selecting is the failure mode
+ * that keeps a correct project buildable.
+ */
+export declare function walkModuleAst(code: string, visit: (node: AstNode) => void): void;
+/**
+ * The module `node` imports from, or `null` when `node` is not an import at all.
+ *
+ * FOUR node types, in one place. Every reader of a built bundle in this tree asks
+ * the same question of the same four — a static `import`, both `export … from`
+ * forms and `import()` — and each copy of that list is a chance for one reader to
+ * miss a form the others catch. The bare side-effect `import "gi://Soup"` is what
+ * that costs when it happens (`gi-namespaces.ts`).
+ */
+export declare function importedSpecifier(node: AstNode): string | null;
+export declare function moduleSpecifiers(code: string): string[];

package/lib/utils/module-ast.js

@@ -0,0 +1,103 @@
+// One acorn walk over a built module, for every reader in the tree that has to
+// summarise a file it did not write.
+//
+// WHY HERE AND NOT IN THE CLI, where these four functions were born: the readers
+// are no longer all in the CLI. `gjsify build --app nativescript` asks which GI
+// namespaces its bundle loads, and so does the Vite path (`defineNativescriptConfig`,
+// ADR 0117 § stage 1b), which never boots the CLI at all. The bundler-plugin package
+// is what both of those depend on, so it is where the walk can be ONE walk — and a
+// second parse in the Vite path is exactly how the two answers would drift.
+//
+// A parse failure yields NO nodes rather than throwing: every caller is summarising
+// somebody else's artifact, and under-selecting keeps a correct project buildable
+// where mis-selecting breaks one.
+import * as acorn from 'acorn';
+/**
+ * The string a node names statically, or `null` when it is computed.
+ *
+ * A substitution-free TEMPLATE LITERAL is as static as a quoted string, and
+ * skipping it is not hypothetical: the minifier rewrites `await
+ * import('gi://GLib?version=2.0')` to a backtick form, so a Literal-only reader
+ * silently loses every dynamic import in a built bundle.
+ *
+ * Not named for specifiers, because it does not only read them: the same
+ * question is asked of a CALL ARGUMENT by `gi-namespaces.ts`, whose
+ * `requireGi("Gtk", "4.0")` carries a namespace and a version in exactly the two
+ * spellings above.
+ */
+export function staticStringValue(node) {
+    if (node?.type === 'Literal')
+        return typeof node.value === 'string' ? node.value : null;
+    if (node?.type === 'TemplateLiteral' && node.expressions?.length === 0) {
+        const cooked = node.quasis?.[0]?.value?.cooked;
+        return typeof cooked === 'string' ? cooked : null;
+    }
+    return null;
+}
+/**
+ * Parse `code` as a module and call `visit` for every node in it.
+ *
+ * Exported because a SECOND parse is how the readers of a built bundle would drift
+ * apart: {@link moduleSpecifiers} answers "what does this file import" and
+ * `gi-namespaces.ts` answers "which GI namespaces does it load", and the second
+ * question has an answer the first cannot see — a `--app node` bundle carries no
+ * `gi://` specifier at all, only the `requireGi()` calls the bundler rewrote them
+ * into. One walker, many readers.
+ *
+ * A parse failure yields NO nodes rather than throwing: every caller is
+ * summarising a file it did not write, and under-selecting is the failure mode
+ * that keeps a correct project buildable.
+ */
+export function walkModuleAst(code, visit) {
+    let ast;
+    try {
+        ast = acorn.parse(code, { ecmaVersion: 'latest', sourceType: 'module', allowHashBang: true });
+    }
+    catch {
+        return;
+    }
+    const descend = (node) => {
+        if (!node || typeof node !== 'object')
+            return;
+        if (Array.isArray(node)) {
+            for (const child of node)
+                descend(child);
+            return;
+        }
+        const n = node;
+        visit(n);
+        for (const [key, value] of Object.entries(n)) {
+            if (key === 'type' || key === 'start' || key === 'end' || key === 'loc')
+                continue;
+            descend(value);
+        }
+    };
+    descend(ast);
+}
+/**
+ * The module `node` imports from, or `null` when `node` is not an import at all.
+ *
+ * FOUR node types, in one place. Every reader of a built bundle in this tree asks
+ * the same question of the same four — a static `import`, both `export … from`
+ * forms and `import()` — and each copy of that list is a chance for one reader to
+ * miss a form the others catch. The bare side-effect `import "gi://Soup"` is what
+ * that costs when it happens (`gi-namespaces.ts`).
+ */
+export function importedSpecifier(node) {
+    if (node.type !== 'ImportDeclaration' &&
+        node.type !== 'ExportNamedDeclaration' &&
+        node.type !== 'ExportAllDeclaration' &&
+        node.type !== 'ImportExpression') {
+        return null;
+    }
+    return staticStringValue(node.source);
+}
+export function moduleSpecifiers(code) {
+    const out = [];
+    walkModuleAst(code, (node) => {
+        const specifier = importedSpecifier(node);
+        if (specifier !== null)
+            out.push(specifier);
+    });
+    return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/rolldown-plugin-gjsify",
-    "version": "0.64.12",
+    "version": "0.64.13-next.283",
     "description": "Rolldown / Rollup / Vite plugin orchestrator for GJS, Node, and Browser targets",
     "type": "module",
     "main": "lib/index.js",
@@ -67,12 +67,13 @@
     ],
     "license": "MIT",
     "dependencies": {
-        "@gjsify/console": "^0.64.12",
-        "@gjsify/resolve-npm": "^0.64.12",
-        "@gjsify/rolldown-plugin-deepkit": "^0.64.12",
-        "@gjsify/rolldown-plugin-pnp": "^0.64.12",
-        "@gjsify/utils": "^0.64.12",
-        "@gjsify/vite-plugin-blueprint": "^0.64.12",
+        "@gjsify/console": "0.64.13-next.283",
+        "@gjsify/resolve-npm": "0.64.13-next.283",
+        "@gjsify/rolldown-plugin-deepkit": "0.64.13-next.283",
+        "@gjsify/rolldown-plugin-pnp": "0.64.13-next.283",
+        "@gjsify/utils": "0.64.13-next.283",
+        "@gjsify/vite-plugin-blueprint": "0.64.13-next.283",
+        "@gjsify/vite-plugin-gettext": "0.64.13-next.283",
         "@rollup/pluginutils": "^5.4.0",
         "acorn": "^8.17.0",
         "acorn-typescript": "^1.4.13",
@@ -82,7 +83,7 @@
         "sass": "^1.101.0"
     },
     "peerDependencies": {
-        "@gjsify/lightningcss-native": "^0.64.12",
+        "@gjsify/lightningcss-native": "0.64.13-next.283",
         "rolldown": "^1.1.4"
     },
     "peerDependenciesMeta": {
@@ -94,8 +95,8 @@
         }
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.64.12",
-        "@gjsify/unit": "^0.64.12",
+        "@gjsify/cli": "0.64.13-next.283",
+        "@gjsify/unit": "0.64.13-next.283",
         "@types/node": "^25.9.2",
         "rolldown": "^1.1.4",
         "typescript": "^6.0.3"
@@ -107,5 +108,6 @@
             "darwin": "supported",
             "win32": "supported"
         }
-    }
+    },
+    "gitHead": "05fae97125a374e84bf57c2d2d086fb53523f205"
 }