@gjsify/rolldown-plugin-gjsify 0.53.0 → 0.54.0

package/lib/app/gjs.js

@@ -8,6 +8,7 @@ import { createRequire } from 'node:module';
 import { aliasPlugin } from '../plugins/alias.js';
 import { externalsPlugin } from '../plugins/externals.js';
 import { napiNodeAddonPlugin } from '../plugins/napi-node-addon.js';
+import { giOptionalPlugin } from '../plugins/gi-optional.js';
 import { unresolvedWorkspaceImportPlugin } from '../plugins/unresolved-workspace-import.js';
 import { platformResolvePlugin, desktopSuffixChain, desktopOsSuffix, DESKTOP_REFUSED_SUFFIXES, } from '../plugins/platform-resolve.js';
 import { reactNativeAliasPlugin } from '../plugins/react-native-alias.js';
@@ -191,6 +192,9 @@ export const setupForGjs = async (input) => {
         // A module assigning the global `console` gets a local binding, or the inject
         // below turns its assignment into `ASSIGN_TO_IMPORT` and fails the build.
         ...(consoleShimPath ? [consoleAssignPlugin()] : []),
+        // `gi://Ns?version=X&optional` → a guarded import (ADR 0087), claimed `pre`
+        // so the externals policy never sees the flagged specifier.
+        giOptionalPlugin('gjs'),
         // Platform-file forks for the desktop, ADR 0032 § 9: `.gtk` → `.<os>` →
         // `.desktop` → base. BEFORE the alias layer, so a platform fork of a
         // module that also has a Node-builtin substitution wins over the

package/lib/app/node.js

@@ -10,6 +10,7 @@ import { nodeModulesPathRewritePlugin, getBundleDirFromOutput } from '../plugins
 import { cssAsStringPlugin } from '../plugins/css-as-string.js';
 import { gjsImportsEmptyPlugin } from '../plugins/gjs-imports-empty.js';
 import { gjsGiNodePlugin, gjsBuiltinModulesNodePlugin } from '../plugins/gjs-gi-node.js';
+import { giOptionalPlugin } from '../plugins/gi-optional.js';
 import { unresolvedWorkspaceImportPlugin } from '../plugins/unresolved-workspace-import.js';
 import { nodeNativeExternalPlugin } from '../plugins/node-native-external.js';
 import { platformResolvePlugin, desktopSuffixChain, desktopOsSuffix, DESKTOP_REFUSED_SUFFIXES, } from '../plugins/platform-resolve.js';
@@ -326,6 +327,13 @@ export const setupForNode = async (input) => {
         // `\0gjsify-entry:` ids `wrapInputWithSideEffects` produces (no-op when
         // nothing was injected).
         ...(virtualEntries.plugin ? [virtualEntries.plugin] : []),
+        // `gi://Ns?version=X&optional` → the guarded load, claimed `pre` and
+        // AHEAD of `gjsGiNodePlugin` on array order, because both match a flagged
+        // specifier and the optional arm has to win: the hard arm's lazy Proxy
+        // answers every member access with `load()` and is never `undefined`, so an
+        // app that degrades on `Ns === undefined` would compile and then throw at
+        // the first real access — on one target only (ADR 0087).
+        giOptionalPlugin('node'),
         // Claims `gi://Ns?version=X` (resolveId `pre` + array order) and rewrites it
         // onto the `@gjsify/node-gi` runtime so a real GJS/GI source builds and runs
         // on Node. Returns null for `@girs/*`.

package/lib/index.d.ts

@@ -6,6 +6,8 @@ export { REWRITE_FILTER, extractPackageSpec, getBundleDirFromOutput, rewriteCont
 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 { giOptionalPlugin, giOptionalShimSource, giOptionalNodeShimSource, giOptionalMarkerSource, parseOptionalGiSpecifier, GI_OPTIONAL_FLAG, GI_OPTIONAL_MARKER, } from './plugins/gi-optional.js';
+export type { GiOptionalTarget } from './plugins/gi-optional.js';
 export { bindConsoleLocally, consoleAssignPlugin, freeConsoleAssignmentInsertion, CONSOLE_LOCAL_BINDING, } from './plugins/console-assign.js';
 export type { GiSystemProbe } from './plugins/gi-runtime-paths.js';
 export type { ProcessStubPluginOptions } from './plugins/process-stub.js';

package/lib/index.js

@@ -6,6 +6,7 @@ export * from './library/index.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 { giOptionalPlugin, giOptionalShimSource, giOptionalNodeShimSource, giOptionalMarkerSource, parseOptionalGiSpecifier, GI_OPTIONAL_FLAG, GI_OPTIONAL_MARKER, } from './plugins/gi-optional.js';
 export { bindConsoleLocally, consoleAssignPlugin, freeConsoleAssignmentInsertion, CONSOLE_LOCAL_BINDING, } from './plugins/console-assign.js';
 export { cssAsStringPlugin } from './plugins/css-as-string.js';
 export { textLoaderPlugin } from './plugins/text-loader.js';

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

@@ -99,12 +99,14 @@ async function tryLoadNativeBundler() {
         // specifier. A library that will not load then names its missing
         // dependency and the npm fallback runs, instead of the nameless
         // "Unsupported type void" inside `transform()`.
-        // The same resolve-then-import dance as above, for the probe itself: by
-        // the time a CSS transform asks for the native bundler, utils' `lib/esm`
-        // is long built, so the lazy edge costs nothing and the static one would
-        // have cost a bootable CLI. `./native-library` rather than `./core`:
-        // `core` re-exports `main-loop`, whose module-level singleton would then
-        // exist twice in a process that already has it inlined in the GJS bundle.
+        // The same resolve-then-import dance as above, for the probe itself:
+        // off disk, so the lazy edge costs nothing and the static one would have
+        // cost a bootable CLI. `./native-library` rather than `./core`: `core`
+        // re-exports `main-loop`, whose module-level singleton would then exist
+        // twice in a process that already has it inlined in the GJS bundle. The
+        // walk follows the WORKSPACE, so `@gjsify/utils build:esm` must precede
+        // it — rule 5 of `scripts/check-build-infra-order.mjs` orders that edge,
+        // the one `bundler-pick.ts` is on the success path of.
         //
         // Its own `try` because the outer one cannot tell this apart from "there
         // is no native backend" — and reporting nothing is the one outcome this

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

@@ -0,0 +1,60 @@
+import type { Plugin } from 'rolldown';
+declare const GI_OPTIONAL_VIRTUAL_PREFIX: {
+    readonly gjs: "\0gjsify-gi-optional:";
+    readonly node: "\0gjsify-gi-optional-node:";
+};
+/** Which build target's shim a flagged specifier gets. */
+export type GiOptionalTarget = keyof typeof GI_OPTIONAL_VIRTUAL_PREFIX;
+/** The query flag that declares a `gi://` import optional. */
+export declare const GI_OPTIONAL_FLAG = "optional";
+/**
+ * `Symbol.for` key of the marker statement every optional shim emits, naming its own
+ * namespace so a reader of the ARTIFACT can tell an optional namespace from a hard one.
+ *
+ * WHY IT IS IN THE BUNDLE AND NOT ALONGSIDE IT, which is the design decision this
+ * constant exists to pin: `gjsify ship` reads the emitted file, not the build tree,
+ * and reads the STAGE MANIFEST when it packs on another host — so a sidecar next to
+ * the bundle is a second source that can be stale, absent, or a different file. The
+ * marker is therefore one statement in the module body the plugin already emits, and
+ * it is a `globalThis[Symbol.for(…)]?.(…)` call for two reasons, both measured on
+ * rolldown's own minifier: an unknown global call is not statically pure, so it
+ * survives minification where a bare string constant is dropped by tree-shaking, and
+ * the optional call means nothing on a host that never registers a handler.
+ */
+export declare const GI_OPTIONAL_MARKER = "gjsify.optionalGi";
+/**
+ * The statement that records `namespace` as optional in the artifact.
+ *
+ * Two string arguments in the spelling the node arm's `requireGi("Ns", "X")` already
+ * uses, so one reader answers both targets. The version argument is OMITTED when
+ * there is none, rather than sent empty: a `requireGi` call cannot tell `''` from a
+ * version, and neither can this.
+ */
+export declare function giOptionalMarkerSource(namespace: string, version?: string): string;
+/**
+ * Split `gi://Ns?version=X&optional` into the clean specifier the loader sees and the
+ * flag; `null` when the specifier is not a `gi://` one or does not carry the flag.
+ */
+export declare function parseOptionalGiSpecifier(source: string): {
+    specifier: string;
+    namespace: string;
+    version?: string;
+} | null;
+/**
+ * The module body for one optional namespace. Self-contained: it runs at module
+ * evaluation, where no bundled helper may be assumed, and reaches ambient globals
+ * through `globalThis.` only.
+ */
+export declare function giOptionalShimSource(specifier: string, namespace: string, version?: string): string;
+/**
+ * The `--app node` body: the same contract, reached through `@gjsify/node-gi`.
+ *
+ * The load is EAGER, which is the one place this arm differs from the hard node shim
+ * and the reason is the flag: `requireGi` only fails when it is called, so a lazy Proxy
+ * cannot answer "is it there" without loading it — and the answer is the whole point.
+ * A missing `@gjsify/node-gi` itself lands in the same catch and yields `undefined`,
+ * which is honest: without node-gi no GI namespace loads, optional or not.
+ */
+export declare function giOptionalNodeShimSource(namespace: string, version?: string): string;
+export declare function giOptionalPlugin(target: GiOptionalTarget): Plugin;
+export {};

package/lib/plugins/gi-optional.js

@@ -0,0 +1,152 @@
+// SPDX-License-Identifier: MIT
+// `import Goa from 'gi://Goa?version=1.0&optional'` — a GI namespace the app can run
+// without (ADR 0087). Composed by `--app gjs` and `--app node`.
+//
+// A plain `gi://` import is a hard edge: GJS loads the typelib when the specifier is
+// EVALUATED and a missing one aborts the module graph before the app decides anything.
+// 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
+// namespace is `undefined` when it is absent.
+//
+// BOTH app targets, and the second one was the trap. `--app node` already loads a
+// `gi://` namespace LAZILY (`gjsGiNodePlugin` default-exports a Proxy that calls
+// `requireGi` on first member access), so with the flag ignored the same source kept
+// returning a truthy Proxy where the app checks `Goa === undefined`, and the first
+// real member access threw instead of degrading — a degrade path that works on one
+// build target and not the other is the defect, not the laziness. Hence a NODE
+// shim with the SAME contract: the namespace or `undefined`, plus one warn. It is
+// synchronous rather than a top-level `await import()` (the shape the node arm's
+// synchronous `require()` already has), because a flag whose whole point is that
+// the app can branch on the result must not force every importer to be async.
+import { GJSIFY_VIRTUAL_PREFIX } from '../utils/virtual-module-id.js';
+import { parseGiSpecifier } from './gjs-gi-node.js';
+const GI_OPTIONAL_VIRTUAL_PREFIX = {
+    gjs: `${GJSIFY_VIRTUAL_PREFIX}gi-optional:`,
+    node: `${GJSIFY_VIRTUAL_PREFIX}gi-optional-node:`,
+};
+/** The query flag that declares a `gi://` import optional. */
+export const GI_OPTIONAL_FLAG = 'optional';
+/**
+ * `Symbol.for` key of the marker statement every optional shim emits, naming its own
+ * namespace so a reader of the ARTIFACT can tell an optional namespace from a hard one.
+ *
+ * WHY IT IS IN THE BUNDLE AND NOT ALONGSIDE IT, which is the design decision this
+ * constant exists to pin: `gjsify ship` reads the emitted file, not the build tree,
+ * and reads the STAGE MANIFEST when it packs on another host — so a sidecar next to
+ * the bundle is a second source that can be stale, absent, or a different file. The
+ * marker is therefore one statement in the module body the plugin already emits, and
+ * it is a `globalThis[Symbol.for(…)]?.(…)` call for two reasons, both measured on
+ * rolldown's own minifier: an unknown global call is not statically pure, so it
+ * survives minification where a bare string constant is dropped by tree-shaking, and
+ * the optional call means nothing on a host that never registers a handler.
+ */
+export const GI_OPTIONAL_MARKER = 'gjsify.optionalGi';
+/**
+ * The statement that records `namespace` as optional in the artifact.
+ *
+ * Two string arguments in the spelling the node arm's `requireGi("Ns", "X")` already
+ * uses, so one reader answers both targets. The version argument is OMITTED when
+ * there is none, rather than sent empty: a `requireGi` call cannot tell `''` from a
+ * version, and neither can this.
+ */
+export function giOptionalMarkerSource(namespace, version) {
+    const args = version === undefined ? JSON.stringify(namespace) : `${JSON.stringify(namespace)}, ${JSON.stringify(version)}`;
+    return `globalThis[Symbol.for(${JSON.stringify(GI_OPTIONAL_MARKER)})]?.(${args});`;
+}
+/**
+ * Split `gi://Ns?version=X&optional` into the clean specifier the loader sees and the
+ * flag; `null` when the specifier is not a `gi://` one or does not carry the flag.
+ */
+export function parseOptionalGiSpecifier(source) {
+    if (!source.startsWith('gi://'))
+        return null;
+    const queryIndex = source.indexOf('?');
+    if (queryIndex === -1)
+        return null;
+    const params = new URLSearchParams(source.slice(queryIndex + 1));
+    if (!params.has(GI_OPTIONAL_FLAG))
+        return null;
+    params.delete(GI_OPTIONAL_FLAG);
+    const rest = params.toString();
+    const specifier = source.slice(0, queryIndex) + (rest ? `?${rest}` : '');
+    const parsed = parseGiSpecifier(specifier);
+    if (parsed === null)
+        return null;
+    return { specifier, ...parsed };
+}
+/**
+ * The module body for one optional namespace. Self-contained: it runs at module
+ * evaluation, where no bundled helper may be assumed, and reaches ambient globals
+ * through `globalThis.` only.
+ */
+export function giOptionalShimSource(specifier, namespace, version) {
+    const label = version ? `${namespace} ${version}` : namespace;
+    return (`let ns;\n` +
+        `try {\n` +
+        `  const m = await import(${JSON.stringify(specifier)});\n` +
+        `  ns = m.default ?? m;\n` +
+        `} catch (error) {\n` +
+        `  let searched = '';\n` +
+        `  try {\n` +
+        `    const r = globalThis.imports.gi.GIRepository.Repository.dup_default();\n` +
+        `    searched = ' (typelib search path: ' + r.get_search_path().join(':') + ')';\n` +
+        `  } catch {}\n` +
+        `  console.warn(${JSON.stringify(`optional GI namespace ${label} is not available`)} + searched + ': ' + (error && error.message ? error.message : String(error)));\n` +
+        `}\n` +
+        `${giOptionalMarkerSource(namespace, version)}\n` +
+        `export default ns;\n`);
+}
+/**
+ * The `--app node` body: the same contract, reached through `@gjsify/node-gi`.
+ *
+ * The load is EAGER, which is the one place this arm differs from the hard node shim
+ * and the reason is the flag: `requireGi` only fails when it is called, so a lazy Proxy
+ * cannot answer "is it there" without loading it — and the answer is the whole point.
+ * A missing `@gjsify/node-gi` itself lands in the same catch and yields `undefined`,
+ * which is honest: without node-gi no GI namespace loads, optional or not.
+ */
+export function giOptionalNodeShimSource(namespace, version) {
+    const label = version ? `${namespace} ${version}` : namespace;
+    const versionArg = version === undefined ? '' : `, ${JSON.stringify(version)}`;
+    return (`import { createRequire } from 'node:module';\n` +
+        `const require = createRequire(import.meta.url);\n` +
+        `let ns;\n` +
+        `try {\n` +
+        `  ns = require('@gjsify/node-gi/gi').requireGi(${JSON.stringify(namespace)}${versionArg});\n` +
+        `} catch (error) {\n` +
+        `  console.warn(${JSON.stringify(`optional GI namespace ${label} is not available`)} + ': ' + (error && error.message ? error.message : String(error)));\n` +
+        `}\n` +
+        `${giOptionalMarkerSource(namespace, version)}\n` +
+        `export default ns;\n`);
+}
+export function giOptionalPlugin(target) {
+    const prefix = GI_OPTIONAL_VIRTUAL_PREFIX[target];
+    return {
+        name: `gjsify-gi-optional-${target}`,
+        resolveId: {
+            order: 'pre',
+            filter: { id: /^gi:\/\/.*[?&]optional(?:&|=|$)/ },
+            handler(source) {
+                const parsed = parseOptionalGiSpecifier(source);
+                if (parsed === null)
+                    return null;
+                const version = parsed.version ? `@${parsed.version}` : '';
+                return { id: `${prefix}${parsed.namespace}${version}` };
+            },
+        },
+        load(id) {
+            if (!id.startsWith(prefix))
+                return null;
+            const spec = id.slice(prefix.length);
+            const at = spec.lastIndexOf('@');
+            const namespace = at === -1 ? spec : spec.slice(0, at);
+            const version = at === -1 ? undefined : spec.slice(at + 1);
+            const code = target === 'gjs'
+                ? giOptionalShimSource(`gi://${namespace}${version ? `?version=${version}` : ''}`, namespace, version)
+                : giOptionalNodeShimSource(namespace, version);
+            return { code, moduleSideEffects: false };
+        },
+    };
+}

package/package.json

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