@gjsify/cli 0.53.0 → 0.54.0

package/lib/commands/ship.js

@@ -45,7 +45,7 @@ import { compileSchemasForPayload, compileSchemasForStage } from '../utils/ship/
 import { buildMsi, MSI_PAYLOAD_DIR } from '../utils/ship/msi.js';
 import { buildZip, zipEntriesFromPayload } from '../utils/ship/zip.js';
 import { assertEntryRunsUnder } from '../utils/ship/entry-interpreter.js';
-import { scanGiNamespaces } from '../utils/ship/gi-namespaces.js';
+import { scanGiRequirements } from '../utils/ship/gi-namespaces.js';
 import { assertLauncherMatchesInterpreter, assertPayloadMatchesArch, buildTimestamp, isArchIndependent, linuxInstallDependent, readPayloadFacts, } from '../utils/ship/payload.js';
 import { assertOverlayIsLicensed, planOverlay, planStage } from '../utils/ship/plan.js';
 import { assertHostCanSign, notarizeArtifact, stapleArtifact, resolveNotaryPlan, resolveSignPlan, signPayload, } from '../utils/ship/signing.js';
@@ -537,9 +537,20 @@ async function assemble(args) {
     // `gi://` specifiers are what the emitted `Depends:` is derived from
     // (ADR 0024 § 6), and the packing host has the staged copy but no way to
     // tell which staged file is the entry.
-    const namespaces = scanGiNamespaces(bundleSource);
-    if (args.verbose)
+    const gi = scanGiRequirements(bundleSource);
+    const namespaces = gi.namespaces;
+    const optionalNamespaces = gi.optional;
+    if (args.verbose) {
+        const hard = namespaces.filter((ns) => !optionalNamespaces.includes(ns));
         console.log(`${LOG} gi namespaces: ${namespaces.join(', ') || '(none)'}`);
+        // The split is worth its own line whenever it is non-empty: an author who
+        // wrote `&optional` and sees the namespace under the plain list has learned
+        // nothing about whether their package will declare it.
+        if (optionalNamespaces.length > 0) {
+            console.log(`${LOG} gi optional namespaces: ${optionalNamespaces.join(', ')}`);
+            console.log(`${LOG} gi required namespaces: ${hard.join(', ') || '(none)'}`);
+        }
+    }
     // PLACED, like the payload, and through the same map. `planOverlay` answers a
     // question about the FORMAT (`share/doc/<pkg>/copyright` for Debian policy,
     // `share/licenses/<pkg>/LICENSE` for rpm) in the prefix-relative shape every
@@ -578,8 +589,9 @@ async function assemble(args) {
         // into a Debian `Depends:`, at exit 0).
         if (format.depends === null)
             continue;
-        deriveDepends(format.depends, {
+        const derived = deriveDepends(format.depends, {
             namespaces,
+            optionalNamespaces,
             hasIcons: facts.hasIcons,
             hasSchemas: facts.hasSchemas,
             interpreter: settings.app,
@@ -589,6 +601,17 @@ async function assemble(args) {
             minGjsVersion: settings.minGjsVersion,
             minNodeVersion: settings.minNodeVersion,
         });
+        // Reported here and not inside `deriveDepends`, which is also called by
+        // `packOne` on a host that has no project — and this is the only place that
+        // does. An optional namespace nobody mapped produces NO package field, and
+        // the app runs without the typelib either way, so nothing downstream will
+        // ever say so again.
+        for (const namespace of derived.unmappedOptional) {
+            console.warn(`${LOG} gi://${namespace} is imported optionally, but no ${format.depends} package is known ` +
+                'to ship its typelib, so no Recommends entry names it. The package builds and runs ' +
+                `without it. Add the row if the namespace should be recommended: \`gjsify.ship.typelibPackages.` +
+                `${namespace} = { "${format.depends}": "…" }\`.`);
+        }
         // One warning per package, for the interpreter it actually declares. A
         // floor warning about a dependency this package does not emit is noise,
         // and a noisy warning is the one nobody reads when it matters.
@@ -602,7 +625,16 @@ async function assemble(args) {
     // is sometimes packable elsewhere and sometimes not is a worse contract
     // than one that always is, and it is what lets the e2e suite compare the
     // one-process artifact with the two-phase one.
-    const manifest = writeStageManifest({ stageDir, settings, formats, mtime, namespaces, staged, overlay });
+    const manifest = writeStageManifest({
+        stageDir,
+        settings,
+        formats,
+        mtime,
+        namespaces,
+        optionalNamespaces,
+        staged,
+        overlay,
+    });
     if (args.stage) {
         // `(none)` spelled out, because an empty list printed as nothing after
         // "formats " reads as a truncated line rather than as a fact. WHICH fact
@@ -638,6 +670,7 @@ async function assemble(args) {
             stageDir,
             outRoot,
             namespaces,
+            optionalNamespaces,
             mtime,
             sign,
             notarize,
@@ -799,6 +832,9 @@ async function finishFromStage(args, fromStage) {
         for (const file of manifest.staged)
             console.log(`${LOG}   ${file.path}`);
         console.log(`${LOG} gi namespaces: ${manifest.namespaces.join(', ') || '(none)'}`);
+        if ((manifest.optionalNamespaces ?? []).length > 0) {
+            console.log(`${LOG} gi optional namespaces: ${manifest.optionalNamespaces?.join(', ')}`);
+        }
     }
     // The stage's own directory is not written to — `writeStage` wipes what it
     // is pointed at, and pointing it at an arriving stage would delete the
@@ -832,6 +868,7 @@ async function finishFromStage(args, fromStage) {
             stageDir,
             outRoot,
             namespaces: manifest.namespaces,
+            optionalNamespaces: manifest.optionalNamespaces ?? [],
             mtime,
             sign,
             notarize,
@@ -858,10 +895,11 @@ async function packOne(input) {
     // this answers used to be answered from the project's file lists, which are
     // absolute paths on the build host and therefore unavailable here.
     const facts = readPayloadFacts(assembled);
-    const depends = format.depends === null
-        ? []
+    const derived = format.depends === null
+        ? { requires: [], recommends: [], unmappedOptional: [] }
         : deriveDepends(format.depends, {
             namespaces: input.namespaces,
+            optionalNamespaces: input.optionalNamespaces,
             hasIcons: facts.hasIcons,
             hasSchemas: facts.hasSchemas,
             interpreter: settings.app,
@@ -871,6 +909,8 @@ async function packOne(input) {
             minGjsVersion: settings.minGjsVersion,
             minNodeVersion: settings.minNodeVersion,
         });
+    const depends = derived.requires;
+    const recommends = derived.recommends;
     // `--arch` is a CLAIM about the payload and nothing else compared it to one:
     // an x86-64 `.so` staged with `--arch arm64` packed at exit 0 and `rpm -qp
     // --qf %{ARCH}` confirmed `aarch64`, because rpm reads the header and the
@@ -956,7 +996,9 @@ async function packOne(input) {
         })
         : assembled;
     const archLabel = format.archName(input.arch, isArchIndependent(payload));
-    const common = { settings, payload, prefix: format.prefix, depends, archLabel, mtime };
+    // `recommends` rides the shared input object, so a format that does not write the
+    // field (every non-deb/rpm row) simply ignores an extra property it never reads.
+    const common = { settings, payload, prefix: format.prefix, depends, recommends, archLabel, mtime };
     const outDir = join(outRoot, 'out');
     mkdirSync(outDir, { recursive: true });
     const target = join(outDir, format.fileName(settings, archLabel));
@@ -1010,6 +1052,7 @@ async function packOne(input) {
                 minGjsVersion: settings.minGjsVersion,
                 minNodeVersion: settings.minNodeVersion,
                 namespaces: input.namespaces,
+                optionalNamespaces: input.optionalNamespaces,
                 bundledTypelibs: facts.bundledTypelibs,
             });
             const appDir = appDirFor(outRoot);

package/lib/commands/webext/index.js

@@ -5,7 +5,7 @@
 import { webextBuildCommand, webextDevCommand, webextZipCommand } from './subcommands.js';
 export const webextCommand = {
     command: 'webext <subcommand>',
-    description: 'Browser extensions: build, zip and develop one WebExtension for Chrome, Edge, Firefox and Safari.',
+    description: 'Browser extensions: build, zip and develop one WebExtension for Chrome, Edge, Firefox, Opera and Safari.',
     builder: (yargs) => yargs
         .command(webextBuildCommand.command, webextBuildCommand.description, webextBuildCommand.builder, webextBuildCommand.handler)
         .command(webextZipCommand.command, webextZipCommand.description, webextZipCommand.builder, webextZipCommand.handler)

package/lib/utils/oxc-resolve.js

@@ -41,8 +41,8 @@
 // `GJSIFY_OXFMT=native|npm` is the explicit override (native throws when the
 // prebuild isn't loadable instead of silently switching engines).
 //
-// oxlint has NO native path yet: its JS-plugin host (the internal
-// `gjsify/register-class-order` rule wired via `.oxlintrc.json` jsPlugins)
+// oxlint has NO native path yet: its JS-plugin host (the
+// `@gjsify/oxlint-plugin-gjsify` rules wired via `.oxlintrc.json` jsPlugins)
 // lives in the Node launcher, so a native oxlint bridge could only run the
 // Rust rule subset. Lint stays Node-spawned until that trade-off is decided
 // (tracked in status/open-todos/README.md).
@@ -264,11 +264,13 @@ async function tryLoadNativeOxfmt() {
             // `bundler-pick.ts`'s `tryLoadNative()` gives — so a library that will
             // not load names itself instead of failing inside `runOxfmt()`.
             // Resolved and imported, not statically imported — the reasoning is
-            // at the top of this file. By the time a formatter asks for the
-            // native backend, utils' `lib/esm` is built. `./native-library`
-            // rather than `./core`: `core` re-exports `main-loop`, whose
-            // module-level singleton would then exist twice in a process that
-            // already carries it inlined in the GJS bundle.
+            // at the top of this file. `./native-library` rather than `./core`:
+            // `core` re-exports `main-loop`, whose module-level singleton would
+            // then exist twice in a process that already carries it inlined in the
+            // GJS bundle. Off disk, so the walk follows the WORKSPACE and
+            // `@gjsify/utils build:esm` must precede this call — the same
+            // precondition `bundler-pick.ts` carries, held by rule 5 of
+            // `scripts/check-build-infra-order.mjs`.
             //
             // Its own `try` because the outer one cannot tell this apart from
             // "there is no native backend", and `_nativeOxfmtLoadError` is the

package/lib/utils/ship/app-runtime.d.ts

@@ -102,8 +102,8 @@ export interface ResolvedNodeGiPackage {
  * NOT the published tarball. `files` in node-gi's manifest also lists `src/`,
  * `binding.gyp` and `scripts/install.mjs` — the inputs to `node-gyp`, which a
  * `.app` never runs — and the `.d.ts` declarations, which nothing inside a bundle
- * compiles against. And it lists `prebuilds/`, which this module stages into
- * `Contents/Frameworks` instead, where a `.app` keeps loadable code.
+ * compiles against. And it lists `prebuilds/`, which this module stages under
+ * `Layout.dirs().native`, the directory a `.app` keeps loadable code in.
  *
  * So the rule is what `require('@gjsify/node-gi/<subpath>')` can REACH:
  * `package.json` (the `exports` map is what resolves every subpath), every `.js`
@@ -120,15 +120,17 @@ export declare function resolveNodeGiPackage(options?: ResolveRuntimeOptions): R
  * literals, so the paths the launcher exports and the paths the stager writes
  * cannot drift: they are computed here once and both callers read this result.
  *
- * `Contents/Frameworks/node-gi/prebuilds/<target>/` is node-gi's OWN sibling
- * layout reproduced verbatim inside `dirs.native`. It is not a naming preference:
+ * `<dirs.native>/node-gi/prebuilds/<target>/` is node-gi's OWN sibling layout
+ * reproduced verbatim inside `Layout.dirs().native` (`Contents/Resources/native`
+ * on a `.app` — `layout.ts`'s darwin row carries why that is not
+ * `Contents/Frameworks`). It is not a naming preference:
  * `resolveGtkRuntimeBundle()` probes `<dir>/lib` and `<dir>/girepository-1.0`,
  * the addon's `@rpath` is `@loader_path/gtk/lib`, and `loaders.cache` addresses
  * each pixbuf loader relative to the bundle toplevel. Reproducing the shape is
  * what makes every one of those relations still true after the copy.
  */
 export interface AppRuntimePaths {
-    /** `<App>.app/Contents/Frameworks/node-gi` — the package root the layout imitates. */
+    /** `<App>.app/Contents/Resources/native/node-gi` — the package root the layout imitates. */
     nodeGiRoot: string;
     /**
      * `<App>.app/Contents/Resources/lib/node_modules/@gjsify/node-gi` — where

package/lib/utils/ship/app-runtime.js

@@ -47,11 +47,14 @@
 // THAT directory — so `prebuildAddonPath()` looks for
 // `…/node_modules/@gjsify/node-gi/prebuilds/<target>/node_gi.node` and
 // `resolveGtkRuntimeBundle()`'s candidate 2 for `…/prebuilds/<target>/gtk`, and
-// neither is where a `.app` may keep loadable code: `Contents/Frameworks` is, and
-// it is what `codesign` now reaches (ADR 0024 § A4) — M6 landed, and
-// `utils/ship/signing.ts` re-signs every Mach-O in the payload by magic number,
-// which is most of this closure. Putting it under `Resources` to save two
-// `export` lines would trade a correct bundle for a shorter launcher.
+// neither is where a `.app` may keep loadable code: `Layout.dirs().native` is, and
+// `utils/ship/signing.ts` re-signs every Mach-O in the payload by magic number
+// (ADR 0024 § A4 — M6 landed), which is most of this closure. What `native` may NOT
+// be is `Contents/Frameworks`: `codesign` reads a version-named DIRECTORY there as
+// a nested bundle and refuses the seal, which is the whole reason this file's
+// output went into `Contents/Resources/native` instead — see `layout.ts`'s darwin
+// row for the measurement and `gjsify ship darwin --sign` for what it used to
+// cost.
 //
 // WHY NOT `gjsify.ship.bundledTypelibs`. Because it FLATTENS. `plan.ts` stages
 // each such file as `posix.join(libDir, 'gi', basename(file))`, and
@@ -210,8 +213,8 @@ function resolveStagedPackage(specifier, options) {
  * NOT the published tarball. `files` in node-gi's manifest also lists `src/`,
  * `binding.gyp` and `scripts/install.mjs` — the inputs to `node-gyp`, which a
  * `.app` never runs — and the `.d.ts` declarations, which nothing inside a bundle
- * compiles against. And it lists `prebuilds/`, which this module stages into
- * `Contents/Frameworks` instead, where a `.app` keeps loadable code.
+ * compiles against. And it lists `prebuilds/`, which this module stages under
+ * `Layout.dirs().native`, the directory a `.app` keeps loadable code in.
  *
  * So the rule is what `require('@gjsify/node-gi/<subpath>')` can REACH:
  * `package.json` (the `exports` map is what resolves every subpath), every `.js`
@@ -252,7 +255,7 @@ export function appRuntimePaths(layout, identity, target) {
         addonPath: posix.join(prebuildDir, NODE_GI_ADDON_FILENAME),
         // `Contents/MacOS`, because that is where a `.app` keeps executables and
         // because `$here` — which the launcher already computes — is then the whole
-        // path expression. `Contents/Frameworks` would work for dyld and would make
+        // path expression. `dirs.native` would work for dyld and would make
         // the launcher walk back up for the one file it execs. On Windows
         // `dirs.launcher` is the program directory itself, so the interpreter lands
         // beside the `.cmd` for the same reason.

package/lib/utils/ship/appimage.d.ts

@@ -89,6 +89,15 @@ export declare function appImageHostRequirements(input: {
     minGjsVersion?: string;
     minNodeVersion?: string;
     namespaces: readonly string[];
+    /**
+     * The subset of {@link namespaces} the bundle marks optional (ADR 0087).
+     *
+     * An AppImage has no `Depends:` field, so "optional" cannot become a package
+     * list here — it becomes WORDING instead. That is not cosmetic: an AppRun user
+     * told a typelib is required and lacking it goes looking for another distro
+     * package, while one told it is optional reads the same sentence correctly.
+     */
+    optionalNamespaces?: readonly string[];
     bundledTypelibs?: readonly string[];
 }): string[];
 /**

package/lib/utils/ship/appimage.js

@@ -204,9 +204,10 @@ export function appDirFor(outRoot) {
  */
 export function appImageHostRequirements(input) {
     const floor = interpreterFloor(input);
+    const optional = new Set(input.optionalNamespaces ?? []);
     return [
         `${input.app} (>= ${floor})`,
-        ...hostProvidedNamespaces(input.namespaces, input.bundledTypelibs).map((ns) => `the ${ns} typelib`),
+        ...hostProvidedNamespaces(input.namespaces, input.bundledTypelibs).map((ns) => optional.has(ns) ? `the ${ns} typelib (optional)` : `the ${ns} typelib`),
     ];
 }
 /**

package/lib/utils/ship/deb.d.ts

@@ -8,6 +8,16 @@ export interface DebInputs {
     prefix: string;
     /** Already-derived dependency list, in `name`/`name >= version` form. */
     depends: readonly string[];
+    /**
+     * Soft dependencies, rendered as `Recommends:`.
+     *
+     * Debian Policy § 7.2: a recommended package is installed by default and
+     * `--no-install-recommends` is the user's way out. That is what an `&optional`
+     * typelib is (ADR 0087) — the app runs without it and loses a feature — so
+     * putting it in `Depends:` would let an optional integration decide whether
+     * the package installs at all.
+     */
+    recommends?: readonly string[];
     /** Debian architecture (`amd64`, `all`, …). */
     archLabel: string;
     /** Unix seconds stamped into every header. */

package/lib/utils/ship/deb.js

@@ -104,6 +104,13 @@ function renderControl(inputs, installedSize) {
     ];
     if (inputs.depends.length > 0)
         fields.push(['Depends', inputs.depends.map(formatDebDepend).join(', ')]);
+    // After `Depends`, which is the field order dpkg-deb --control writes and the
+    // one `grep '^Depends:'` on a control file assumes. Omitted when empty rather
+    // than written as `Recommends:` with nothing after it — a field with an empty
+    // value is a parse error here, the same reason `formatDebDepend` exists.
+    if (inputs.recommends !== undefined && inputs.recommends.length > 0) {
+        fields.push(['Recommends', inputs.recommends.map(formatDebDepend).join(', ')]);
+    }
     fields.push(['Section', settings.section], ['Priority', 'optional']);
     if (settings.homepage)
         fields.push(['Homepage', settings.homepage]);

package/lib/utils/ship/depends.d.ts

@@ -43,6 +43,17 @@ export declare function warnAboutNodeFloor(format: DistroFormatId, floor: string
 export interface DependsInputs {
     /** GI namespaces the bundle imports, in `Ns-Version` spelling. */
     namespaces: readonly string[];
+    /**
+     * The subset of {@link namespaces} the bundle declares OPTIONAL (ADR 0087 —
+     * `gi://Ns?version=X&optional`): a `Recommends:` entry, never a `Depends:`.
+     *
+     * Kept as its own list rather than filtered out of {@link namespaces}, because
+     * the AppImage has no package list at all and still has to SAY which of its host
+     * requirements are optional — and because a stage manifest written before the
+     * split carries no such field, where answering "everything is hard" is the safe
+     * direction.
+     */
+    optionalNamespaces?: readonly string[];
     /**
      * Whether the payload installs into `share/icons/hicolor/`.
      *
@@ -112,11 +123,34 @@ export interface DependsInputs {
  */
 export declare function hostProvidedNamespaces(namespaces: readonly string[], bundledTypelibs?: readonly string[]): string[];
 /**
- * The `Depends:` / `Requires:` list for one format.
+ * One format's dependency lists, split by how hard the requirement is.
+ *
+ * `requires` is what an absent package makes the app fail over; `recommends` is what
+ * its absence only costs. A namespace the BUNDLE marked optional (ADR 0087) is the
+ * second kind by declaration — the app's own `check()` degrades — and both `.deb`
+ * and `.rpm` have a field for it, so there is no reason to declare it hard.
+ */
+export interface DerivedDepends {
+    /** `Depends:` / `Requires:` — a package the artifact cannot run without. */
+    requires: string[];
+    /** `Recommends:` — installed by default where the format has such a field. */
+    recommends: string[];
+    /**
+     * Optional namespaces no table row is known for.
+     *
+     * REPORTED, never fatal: a `Recommends:` line for a namespace nobody mapped is
+     * the one case where saying nothing is correct — the app runs without the
+     * typelib either way, which is precisely what the flag declared. The HARD
+     * unmapped case still throws, below.
+     */
+    unmappedOptional: string[];
+}
+/**
+ * The `Depends:` / `Requires:` list for one format, plus its `Recommends:`.
  *
- * @throws when a namespace has no entry in the table — see the module header.
+ * @throws when a HARD namespace has no entry in the table — see the module header.
  */
-export declare function deriveDepends(format: DistroFormatId, inputs: DependsInputs): string[];
+export declare function deriveDepends(format: DistroFormatId, inputs: DependsInputs): DerivedDepends;
 /** One parsed dependency. `relation`/`version` are absent for an unversioned one. */
 export interface ParsedDepend {
     name: string;

package/lib/utils/ship/depends.js

@@ -287,9 +287,9 @@ export function hostProvidedNamespaces(namespaces, bundledTypelibs = []) {
     return [...new Set(namespaces)].sort().filter((ns) => !BUNDLED_TYPELIB.test(ns) && !shipped.has(ns));
 }
 /**
- * The `Depends:` / `Requires:` list for one format.
+ * The `Depends:` / `Requires:` list for one format, plus its `Recommends:`.
  *
- * @throws when a namespace has no entry in the table — see the module header.
+ * @throws when a HARD namespace has no entry in the table — see the module header.
  */
 export function deriveDepends(format, inputs) {
     // The interpreter the launcher execs, and nothing else: a package declares ONE.
@@ -297,17 +297,25 @@ export function deriveDepends(format, inputs) {
     // no system Node, so an artifact for those CARRIES one from
     // `@gjsify/node-runtime-<target>`, and that is the whole reason those three
     // packages exist and this one line is their opposite.
-    const out = inputs.interpreter === 'node'
+    const requires = inputs.interpreter === 'node'
         ? [`${NODE_PACKAGE[format]} >= ${inputs.minNodeVersion ?? DEFAULT_NODE_FLOOR}`]
         : [`gjs >= ${inputs.minGjsVersion ?? DEFAULT_GJS_FLOOR}`];
+    const recommends = [];
+    const optional = new Set(inputs.optionalNamespaces ?? []);
     const unmapped = [];
+    const unmappedOptional = [];
     for (const namespace of hostProvidedNamespaces(inputs.namespaces, inputs.bundledTypelibs)) {
         const entry = lookupTypelib(namespace, inputs.typelibPackages);
         if (entry === undefined) {
-            unmapped.push(namespace);
+            (optional.has(namespace) ? unmappedOptional : unmapped).push(namespace);
             continue;
         }
-        out.push(entry[format]);
+        // A namespace imported both ways is a HARD dependency — one importer asked
+        // for it unguarded — and a package manager field may not name it twice.
+        if (optional.has(namespace) && !requires.includes(entry[format]))
+            recommends.push(entry[format]);
+        else
+            requires.push(entry[format]);
     }
     if (unmapped.length > 0) {
         throw new Error(`gjsify ship: the bundle imports ${unmapped.map((n) => `gi://${n.split('-')[0]}`).join(', ')}, ` +
@@ -323,7 +331,7 @@ export function deriveDepends(format, inputs) {
     // The package that owns `/usr/share/icons/hicolor` — so this follows the icons, not the
     // app/cli distinction that used to stand in for them.
     if (inputs.hasIcons)
-        out.push('hicolor-icon-theme');
+        requires.push('hicolor-icon-theme');
     // The package that ships `glib-compile-schemas`, NOT `gsettings-desktop-schemas`
     // (which ships GNOME's own `org.gnome.desktop.*` schemas and has nothing to
     // do with compiling ours). Measured: `rpm -qf /usr/bin/glib-compile-schemas`
@@ -333,11 +341,15 @@ export function deriveDepends(format, inputs) {
     // `Gio.Settings.new()` aborts the app — an install that succeeds and an app
     // that does not start.
     if (inputs.hasSchemas)
-        out.push(SCHEMA_COMPILER_PACKAGE[format]);
-    out.push(...inputs.extra);
+        requires.push(SCHEMA_COMPILER_PACKAGE[format]);
+    requires.push(...inputs.extra);
     // Set-dedupe keeps first-insertion order, so the interpreter stays first and
     // the list is stable across runs.
-    return [...new Set(out)];
+    return {
+        requires: [...new Set(requires)],
+        recommends: [...new Set(recommends)].filter((name) => !requires.includes(name)),
+        unmappedOptional,
+    };
 }
 /**
  * Resolve a scanned specifier to a table row.

package/lib/utils/ship/gi-namespaces.d.ts

@@ -1,7 +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 parseGiSpecifier(specifier: string): string | null;

package/lib/utils/ship/gi-namespaces.js

@@ -34,6 +34,18 @@
 // `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 '@gjsify/rolldown-plugin-gjsify';
 import { importedSpecifier, staticStringValue, walkModuleAst, } from '../cli-runtime-closure.js';
 /** The module a `--app node` bundle reaches GI through. */
 const NODE_GI_MODULE = '@gjsify/node-gi/gi';
@@ -44,7 +56,12 @@ const NAMESPACE = /^[A-Za-z][A-Za-z\d_]*$/;
  * 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
@@ -89,11 +106,57 @@ export function scanGiNamespaces(source) {
             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 [...found].sort();
+    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 parseGiSpecifier(specifier) {

package/lib/utils/ship/launcher.js

@@ -171,7 +171,7 @@ function renderPrefixLauncher(settings, bundleRelPath, layout) {
  * IT EXECS WHAT THE BUNDLE CARRIES. `runtime` comes from
  * `utils/ship/app-runtime.ts` and names the interpreter, the relocated GTK
  * closure and the node-gi addon staged inside `Contents/` — so the exec line is
- * `"$here/node"` and the two locators below point into `Contents/Frameworks`.
+ * `"$here/node"` and the two locators below point into `dirs.native`.
  * When the stage carries none of them every line here is byte-identical to what
  * M2a wrote, which is what keeps a bundle assembled without the runtime packages
  * exactly as (un)usable as it was rather than differently broken.
@@ -261,7 +261,7 @@ function renderAppBundleLauncher(settings, bundleRelPath, layout, runtime) {
     // `node_modules`, and a shipped `.app` has neither: its JavaScript is one
     // bundled file under `Contents/Resources/lib`, so `import.meta.url` there
     // resolves node-gi's "package root" to the bundle's directory and every probed
-    // path lands beside the bundle instead of in `Contents/Frameworks`.
+    // path lands beside the bundle instead of in `dirs.native`.
     //
     // `NODE_GI_NATIVE` is the same problem for the addon: `prebuildAddonPath()`
     // joins `prebuilds/<target>/node_gi.node` onto that same wrong root

package/lib/utils/ship/layout.js

@@ -7,7 +7,8 @@
 // is the first layout that is NOT a prefix substitution: the launcher, the bundle,
 // the shared libraries and the data tree each move somewhere different, and on
 // macOS the native files leave the bundle directory altogether for
-// `Contents/Frameworks`.
+// `Contents/Resources/native` — a path Apple's own layout does not have, for the
+// measured reason {@link layoutForOs}'s darwin row carries.
 //
 // So the layout is a MAP from the prefix-relative plan to a stage-relative path,
 // and `planStage` keeps producing the prefix-relative plan for all three. That
@@ -168,12 +169,34 @@ export const LAYOUTS = {
         // everything that is not, and `Contents/Frameworks` the dylibs — which is
         // the split that makes this more than a prefix: the `gi/` directory that
         // sits INSIDE `lib/<name>/` on Linux leaves the bundle directory entirely.
+        //
+        // …AND THE NATIVE DIRECTORY IS NOT APPLE'S, because `Contents/Frameworks`
+        // is RESERVED FOR NESTED CODE and one directory of it is loadable code
+        // that cannot be there. Measured on darwin-arm64 / macOS 27 with the
+        // published `@gjsify/gtk-runtime-darwin-arm64` staged by M2b: `codesign`
+        // refuses the BUNDLE SEAL with *"bundle format unrecognized, invalid, or
+        // unsuitable / In subcomponent: …/gtk/lib/gstreamer-1.0"*, so
+        // `gjsify ship darwin --sign` cannot sign a real GTK application at all —
+        // and it does so at exit 1 with the payload half-signed. The trigger is not
+        // gstreamer: it is any directory under `Contents/Frameworks` whose last
+        // dot-separated component parses as a version, because `codesign` reads
+        // `foo-1.0`, `foo1.0` and `Versions/1.0` as a VERSIONED NESTED BUNDLE
+        // (`<name>-<version>` is a framework's shape) and then finds no
+        // `Contents/Info.plist` inside. The relocated closure carries three:
+        // `girepository-1.0`, `gdk-pixbuf-2.0/2.10.0` and `lib/gstreamer-1.0`.
+        //
+        // The same three under `Contents/Resources` seal and verify at exit 0, which
+        // is the whole measurement. So `native` is the ONE seam that moves: the
+        // relocated closure, the addon, the app's own `gi/` dylibs and both launchers'
+        // `GI_TYPELIB_PATH`/`GJSIFY_GI_LIBRARY_PATH` all read it, so the tree and
+        // every path that names it move together. Library validation is unaffected —
+        // it follows the SIGNATURE (§ `signing.ts`'s darwin row), not the directory.
         dirs: (identity) => {
             const app = appBundleDir(identity);
             return {
                 launcher: `${app}/Contents/MacOS`,
                 bundle: `${app}/Contents/Resources/lib`,
-                native: `${app}/Contents/Frameworks`,
+                native: `${app}/Contents/Resources/native`,
                 data: `${app}/Contents/Resources/share`,
                 other: `${app}/Contents/Resources`,
             };