@gjsify/cli 0.64.1-next.249 → 0.64.2-next.253

package/lib/actions/build.d.ts

@@ -94,6 +94,22 @@ export declare class BuildAction {
      * on the prediction, not a second opinion.
      */
     private assertNodeOutputGlobals;
+    /**
+     * Post-bundle gate for `--app nativescript`: every GI namespace the emitted
+     * bundle loads has to be one the APK was told to carry (ADR 0117 § 2).
+     *
+     * THE ORACLE IS THE EMITTED FILE, like the two gates above and for the same
+     * reason — that is the artifact that gets installed. What it reads there is a
+     * LOWER BOUND, which is why only one direction is fatal: a namespace the scan
+     * found and the config omits WILL be missing from the APK, while a namespace the
+     * config names and the scan missed may simply be reached in a way no static read
+     * can see (`planGiSelection` carries the full argument).
+     *
+     * Android is the one target where this is not advice. A `.deb` that under-declares
+     * its typelibs can still be fixed by installing a package; an APK carries its
+     * whole GI stack or does without it.
+     */
+    private assertNativescriptGiSelected;
     /**
      * Post-bundle step for a `--app browser` HTML entry: write the processed
      * `index.html` beside the JS bundle, with the entry `<script>`'s `src`

package/lib/actions/build.js

@@ -15,6 +15,8 @@ import { collectEntryPaths, describeJsxConfig, findJsxEntryPoint, jsxConfigMissi
 import { giSystemProbes } from '../utils/gi-runtime-paths.js';
 import { escapeRawNulForGjs } from '../utils/gjs-source-escape.js';
 import { assertNodeBundleGlobalsShimmed } from '../utils/node-bundle-guard.js';
+import { scanGiNamespaces } from '../utils/ship/gi-namespaces.js';
+import { planGiSelection } from '../utils/ship/gi-selection.js';
 import { DEP_CHANGE_LOCKFILES } from '../utils/package-inputs.js';
 const DEFAULT_GJS_SHEBANG = '#!/usr/bin/env -S gjs -m';
 /**
@@ -439,6 +441,51 @@ export class BuildAction {
             assertNodeBundleGlobalsShimmed(code, item.fileName ? `${label} (${item.fileName})` : label);
         }
     }
+    /**
+     * Post-bundle gate for `--app nativescript`: every GI namespace the emitted
+     * bundle loads has to be one the APK was told to carry (ADR 0117 § 2).
+     *
+     * THE ORACLE IS THE EMITTED FILE, like the two gates above and for the same
+     * reason — that is the artifact that gets installed. What it reads there is a
+     * LOWER BOUND, which is why only one direction is fatal: a namespace the scan
+     * found and the config omits WILL be missing from the APK, while a namespace the
+     * config names and the scan missed may simply be reached in a way no static read
+     * can see (`planGiSelection` carries the full argument).
+     *
+     * Android is the one target where this is not advice. A `.deb` that under-declares
+     * its typelibs can still be fixed by installing a package; an APK carries its
+     * whole GI stack or does without it.
+     */
+    assertNativescriptGiSelected(result, outfile, outdir) {
+        const label = outfile ?? outdir ?? 'the nativescript bundle';
+        const scanned = new Set();
+        for (const item of result.output ?? []) {
+            if (item.type !== 'chunk')
+                continue;
+            const code = item.code;
+            if (typeof code !== 'string' || code.length === 0)
+                continue;
+            for (const namespace of scanGiNamespaces(code))
+                scanned.add(namespace);
+        }
+        let selection;
+        try {
+            selection = planGiSelection({
+                declared: this.configData.nativescript?.giNamespaces ?? [],
+                scanned: [...scanned],
+            });
+        }
+        catch (error) {
+            // Re-thrown with the artifact in it: `planGiSelection` is pure and knows
+            // the namespaces but not which file they were read from.
+            throw new Error(`gjsify build: ${label}: ${error.message}`);
+        }
+        for (const namespace of selection.unscanned) {
+            console.warn(`[gjsify] --app nativescript: nativescript.giNamespaces declares ${namespace}, which ` +
+                `${label} does not appear to import. The APK carries it anyway — drop it if nothing ` +
+                'needs it, since every selected namespace costs APK size.');
+        }
+    }
     /**
      * Post-bundle step for a `--app browser` HTML entry: write the processed
      * `index.html` beside the JS bundle, with the entry `<script>`'s `src`
@@ -849,6 +896,13 @@ export class BuildAction {
         if (app === 'node' && autoMode && !pluginOpts.nodeGiGlobalsInject) {
             this.assertNodeOutputGlobals(writeResult, outfile, outdir);
         }
+        // Refuse to hand back a `--app nativescript` bundle that imports a GI namespace
+        // the APK will not carry. The payload is selected from a pinned sysroot at
+        // package-build time (ADR 0117), so there is no host to fall back on: the
+        // alternative to this gate is an APK that installs and throws at the import.
+        if (app === 'nativescript') {
+            this.assertNativescriptGiSelected(writeResult, outfile, outdir);
+        }
         // Browser HTML entry: emit the processed `index.html` beside the bundle
         // (engine-portable post-step — the native rolldown engine has no
         // `emitFile`, so this can't live in a plugin). `outfile` is guaranteed

package/lib/commands/ship.js

@@ -454,13 +454,21 @@ async function assemble(args) {
             })),
     ];
     // THE APPLICATION ICON, rendered once for the sizes this layout's writers
-    // embed — six for the `.exe`'s resource directory, seven for the `.icns` —
-    // and nothing for a CLI or for Linux, where the theme carries the SVG the
-    // project declared. `resolveAppIcon` REFUSES an app that has no source for a
-    // size rather than staging without it: the released artifacts this closes
-    // shipped for a year with the generic icon on two platforms, and the only
-    // reason was that nothing said so (`utils/ship/icons.ts`).
-    const icon = settings.kind === 'app' && layout.icon !== undefined
+    // embed — six for the `.exe`'s resource directory, seven for the `.icns`,
+    // three for the hicolor theme — and nothing for a CLI. `resolveAppIcon`
+    // REFUSES an app that has no source for a size rather than staging without
+    // it: the released artifacts this closes shipped for a year with the generic
+    // icon on two platforms, and the only reason was that nothing said so
+    // (`utils/ship/icons.ts`).
+    //
+    // …EXCEPT WHERE THE ROW SAYS THE ICON IS NOT REQUIRED, which is Linux and is
+    // not a softening of that rule. An icon-less app there is reported by
+    // `resolveShipSettings`'s warning and then by its own menu entry, so refusing
+    // would stop a project that has not drawn its icon yet from building a `.deb`
+    // over a defect it can already see (`LayoutIcon.required`). The guard belongs
+    // HERE as well as in `iconFor`, because `resolveAppIcon` is the half that
+    // refuses an empty `iconFiles` — reaching it at all is what has to not happen.
+    const icon = settings.kind === 'app' && layout.icon !== undefined && (layout.icon.required || settings.iconFiles.length > 0)
         ? await resolveAppIcon({
             iconFiles: settings.iconFiles,
             appId: settings.appId,

package/lib/config.js

@@ -317,6 +317,25 @@ export class Config {
                 'introspection to answer `gi://` with. `--app gjs` resolves it natively and `--app node` ' +
                 'through @gjsify/node-gi, so neither needs a widget renderer standing in for it.');
         }
+        // And the same rule once more for the namespace selection, which only an
+        // Android payload can act on: on every other target `gi://` is answered by a
+        // system typelib or by `requireGi`, so a list here would be read, validated
+        // and then change nothing about the artifact.
+        if (configData.nativescript?.giNamespaces !== undefined && configData.app !== 'nativescript') {
+            throw new Error(`gjsify build: nativescript.giNamespaces has no effect on --app ${configData.app}. ` +
+                'It selects what an Android APK carries (ADR 0117); every other target resolves ' +
+                '`gi://` against a GI stack the host already has.');
+        }
+        for (const entry of configData.nativescript?.giNamespaces ?? []) {
+            // `Ns` or `Ns-Version`, because that is what the AAR builder resolves
+            // against the typelib names in the sysroot. A free-form string here
+            // surfaces as "the prefix has no typelib for …" hours later, naming the
+            // typo rather than the shape.
+            if (!/^[A-Za-z][A-Za-z\d_]*(-\d+(\.\d+)*)?$/.test(entry)) {
+                throw new Error(`gjsify build: nativescript.giNamespaces entry "${entry}" is not a GI namespace. ` +
+                    'Write it as `Gtk` or `Gtk-4.0`.');
+            }
+        }
         if (cliArgs.globals !== undefined)
             configData.globals = cliArgs.globals;
         // Fallback applied post-merge (not as a yargs `default:`) so a

package/lib/types/config-data.d.ts

@@ -213,6 +213,37 @@ export interface ConfigData {
     format?: ConfigDataFormat;
     /** Config for `gjsify test`. `--entry`, `--outdir`, `--runtime` override these. */
     test?: ConfigDataTest;
+    /** Config for the `nativescript` target — what the APK carries (ADR 0117). */
+    nativescript?: ConfigDataNativescript;
+}
+/**
+ * What a NativeScript build decides that no other target has to.
+ *
+ * Its own namespace rather than top-level keys, for the reason `flatpak` and `ship`
+ * have one: these settings mean nothing on `gjs`, `node` or `browser`, and a
+ * top-level `giNamespaces` would read like a bundler option on every target.
+ */
+export interface ConfigDataNativescript {
+    /**
+     * The GI namespaces this APK carries, as `Ns` or `Ns-Version` (ADR 0117 § 2).
+     *
+     * ANDROID HAS NO SYSTEM GI STACK, so unlike a `.deb` there is no `Depends:` that
+     * a host can satisfy: every typelib and every backing `.so` is in the APK or is
+     * not reachable at all. The payload is cross-compiled against a sha256-pinned
+     * sysroot long before an app build, so this list cannot conjure a namespace the
+     * sysroot lacks — it SELECTS from what the sysroot has.
+     *
+     * Declared rather than inferred, and the asymmetry is the point: the scan of the
+     * emitted bundle is a LOWER BOUND (a namespace reached through a computed
+     * specifier is invisible to it), so an imported namespace missing from this list
+     * fails the build by name, while a listed one the scan did not see is only a
+     * warning about a larger-than-necessary APK.
+     *
+     * Unset is not the same as `[]` in intent but is in effect: both mean the
+     * measured core set (GLib, GObject, Gio and friends), which backs the runtime
+     * itself and ships whether or not anything declares it.
+     */
+    giNamespaces?: string[];
 }
 /** Optional pointer to a non-default oxc config file. */
 export interface ConfigDataFormat {

package/lib/utils/ship/flatpak-config.d.ts

@@ -43,6 +43,39 @@ export interface PickedFlatpakBuildKeys {
 export declare function pickFlatpakBuildKeys(preferred: ShipFlatpakOptions | undefined, legacy: ConfigDataFlatpak): PickedFlatpakBuildKeys;
 /** The branch a `ship` Flatpak is exported under when the project names none. */
 export declare const DEFAULT_SHIP_FLATPAK_BRANCH = "stable";
+/**
+ * The scalable icon directory a `kind: 'app'` Flatpak drops before
+ * `appstreamcli compose` reads the tree.
+ *
+ * THE OTHER HALF OF `LAYOUTS.linux.icon`, and the half that cannot live in the
+ * layout: the stage is one payload for four Linux formats (ADR 0024 § 2) and the
+ * `.deb`, the `.rpm` and the AppImage all WANT the SVG — it is the icon GTK
+ * prefers, and `selectAppDirIcon` ranks it above every raster. Only the Flatpak
+ * has a build step that reads the theme, so only the Flatpak removes it, and it
+ * does so inside the sandbox rather than in the tree `ship` staged.
+ *
+ * WHY IT IS REMOVED AT ALL. `flatpak-builder` runs `appstreamcli compose` on the
+ * HOST to produce `/app/share/app-info`; AppStream 1.1.3 decodes icons through
+ * gdk-pixbuf, which reads SVG only through a loader module Fedora 44 no longer
+ * ships (`LAYOUTS.linux.icon` carries the measurement). Three probes: with the
+ * SVG present compose fails whether or not rasters are there, because it PREFERS
+ * the scalable icon and does not fall back; with the SVG gone and the rasters
+ * present it succeeds and emits 64×64 and 128×128 into the catalogue. So the
+ * rasters are necessary and this is what makes them sufficient.
+ *
+ * UNCONDITIONAL, not host-detected, and that is the point. `org.flatpak.Builder`
+ * on Flathub bundles a gdk-pixbuf that CAN read SVG, so probing the host would
+ * make the same source produce a different `.flatpak` depending on where it was
+ * built — the one property ADR 0024 § A2 asks a pack to keep. One tree, every
+ * host, at the cost of a scalable icon inside a sandbox whose only reader
+ * (`Icon=<appId>` in the exported desktop entry) resolves the 256 px raster.
+ *
+ * THE UPSTREAM FIX IS NOT OURS: `libappstream-compose.so.0` already links
+ * `librsvg-2.so.2` and uses it for fonts alone, so AppStream could render the
+ * icon without gdk-pixbuf at all. Reported as an `Upstream (AppStream, file by
+ * hand)` issue rather than filed there (root AGENTS.md).
+ */
+export declare const SCALABLE_ICONS_CLEANUP = "/share/icons/hicolor/scalable";
 export interface ShipFlatpakInput {
     ship: ConfigDataShip;
     flatpak: ConfigDataFlatpak;

package/lib/utils/ship/flatpak-config.js

@@ -88,6 +88,39 @@ export function pickFlatpakBuildKeys(preferred, legacy) {
 }
 /** The branch a `ship` Flatpak is exported under when the project names none. */
 export const DEFAULT_SHIP_FLATPAK_BRANCH = 'stable';
+/**
+ * The scalable icon directory a `kind: 'app'` Flatpak drops before
+ * `appstreamcli compose` reads the tree.
+ *
+ * THE OTHER HALF OF `LAYOUTS.linux.icon`, and the half that cannot live in the
+ * layout: the stage is one payload for four Linux formats (ADR 0024 § 2) and the
+ * `.deb`, the `.rpm` and the AppImage all WANT the SVG — it is the icon GTK
+ * prefers, and `selectAppDirIcon` ranks it above every raster. Only the Flatpak
+ * has a build step that reads the theme, so only the Flatpak removes it, and it
+ * does so inside the sandbox rather than in the tree `ship` staged.
+ *
+ * WHY IT IS REMOVED AT ALL. `flatpak-builder` runs `appstreamcli compose` on the
+ * HOST to produce `/app/share/app-info`; AppStream 1.1.3 decodes icons through
+ * gdk-pixbuf, which reads SVG only through a loader module Fedora 44 no longer
+ * ships (`LAYOUTS.linux.icon` carries the measurement). Three probes: with the
+ * SVG present compose fails whether or not rasters are there, because it PREFERS
+ * the scalable icon and does not fall back; with the SVG gone and the rasters
+ * present it succeeds and emits 64×64 and 128×128 into the catalogue. So the
+ * rasters are necessary and this is what makes them sufficient.
+ *
+ * UNCONDITIONAL, not host-detected, and that is the point. `org.flatpak.Builder`
+ * on Flathub bundles a gdk-pixbuf that CAN read SVG, so probing the host would
+ * make the same source produce a different `.flatpak` depending on where it was
+ * built — the one property ADR 0024 § A2 asks a pack to keep. One tree, every
+ * host, at the cost of a scalable icon inside a sandbox whose only reader
+ * (`Icon=<appId>` in the exported desktop entry) resolves the 256 px raster.
+ *
+ * THE UPSTREAM FIX IS NOT OURS: `libappstream-compose.so.0` already links
+ * `librsvg-2.so.2` and uses it for fonts alone, so AppStream could render the
+ * icon without gdk-pixbuf at all. Reported as an `Upstream (AppStream, file by
+ * hand)` issue rather than filed there (root AGENTS.md).
+ */
+export const SCALABLE_ICONS_CLEANUP = '/share/icons/hicolor/scalable';
 /**
  * Resolve the Flatpak half of `gjsify.ship`, reading the legacy block where the
  * new one is silent, and applying `ship`'s own defaults.
@@ -116,7 +149,13 @@ export function resolveShipFlatpakSettings(input) {
         // extension not being installed.
         appendPath: appendPath ?? (extensions.length > 0 ? deriveAppendPath(extensions) : []),
         finishArgs: finishArgs ?? (input.kind === 'cli' ? DEFAULT_CLI_FINISH_ARGS : DEFAULT_GUI_FINISH_ARGS),
-        cleanup: cleanup ?? [],
+        // APPENDED to what the project declared, not defaulted to — the one entry
+        // here that is not the author's choice. A project with its own `cleanup`
+        // list would otherwise lose the entry that keeps its own Flatpak buildable
+        // (see {@link SCALABLE_ICONS_CLEANUP}), and `??` cannot express "ours as
+        // well as theirs". Deduplicated so a project that already wrote the glob —
+        // the workaround this replaces — gets one, and in ITS position.
+        cleanup: [...new Set([...(cleanup ?? []), ...(input.kind === 'app' ? [SCALABLE_ICONS_CLEANUP] : [])])],
     };
     return { settings, warnings: fromLegacy.length === 0 ? [] : [deprecationWarning(fromLegacy)] };
 }

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

@@ -0,0 +1,18 @@
+/** 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/ship/gi-selection.js

@@ -0,0 +1,73 @@
+// 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);
+}
+/**
+ * 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/ship/layout.d.ts

@@ -70,15 +70,44 @@ export interface LayoutMetadataInput extends LayoutIdentity {
  * Declared on the row rather than computed from it because the orchestrator
  * renders the rasters BEFORE the row runs — `resolveAppIcon` is asynchronous (a
  * child GJS) and `Layout.metadata` is not — so the row states its needs up front
- * and receives exactly those sizes. Absent on Linux, deliberately: the hicolor
+ * and receives exactly those sizes.
+ *
+ * ON ALL THREE ROWS, and it was absent from the Linux one until a Flatpak build
+ * measured why that was wrong. The reasoning it was absent for — "the hicolor
  * theme carries the SVG the project declared and GTK renders it itself, so there
- * is nothing to convert and nothing to refuse.
+ * is nothing to convert" — is true of GTK and NOT of the tooling that reads the
+ * same theme at BUILD time: `appstreamcli compose` resolves an SVG through
+ * gdk-pixbuf, which needs an SVG LOADER MODULE, and a host without one fails the
+ * whole compose run rather than falling back to a raster. The same host-packaging
+ * fact `icons.ts` records for the rasterizer, one phase to the right — see
+ * {@link LAYOUTS.linux.icon}.
  */
 export interface LayoutIcon {
     /** Square edge lengths the writer embeds. */
     sizes: readonly number[];
     /** What is written, for the refusal: "the Windows launcher's icon". */
     writes: string;
+    /**
+     * Whether a `kind: 'app'` stage is REFUSED when the project declares no icon
+     * source, or assembled without one.
+     *
+     * REQUIRED on every row, like {@link Layout.metadata} and
+     * {@link Layout.arches}: `false` is an answer, and an optional field is one a
+     * fourth OS forgets and then silently inherits whichever default was typed
+     * first.
+     *
+     * The two answers are different FAILURE MODES, not different strictnesses.
+     * On macOS and Windows the icon lives inside a container — an `.icns` named by
+     * `CFBundleIconFile`, a `.rsrc` in the launcher — and an application that
+     * ships without it shows the generic icon with nothing anywhere saying so:
+     * measured on released artifacts, for a year (`icons.ts`). On Linux the icon
+     * is a FILE in a theme, the desktop entry's `Icon=` names it, and an
+     * icon-less app is visibly icon-less in the menu the first time it is
+     * installed — which `resolveShipSettings` already warns about. Turning that
+     * warning into a refusal would stop a project that has not drawn its icon yet
+     * from building a `.deb` at all, for a defect its own menu entry reports.
+     */
+    required: boolean;
 }
 /** The four places a payload file can belong, as stage-relative directories. */
 export interface LayoutDirs {
@@ -252,6 +281,15 @@ export interface LayoutArches {
     /** What a reader must know to act on the refusal: who blocks it, and where it is tracked. */
     why: string;
 }
+/**
+ * The square sizes the Linux row writes into the hicolor theme.
+ *
+ * Here and not in a writer module like {@link ICO_SIZES} and {@link ICNS_SIZES},
+ * because there is no writer: the rasters ARE the artifact, one file per size,
+ * and the row below is the only thing that names them. See
+ * {@link LAYOUTS.linux.icon} for what asked for each of the three.
+ */
+export declare const HICOLOR_RASTER_SIZES: readonly [64, 128, 256];
 export declare const LAYOUTS: Record<LayoutName, Layout>;
 /** Every layout name, derived from the table so a new row cannot be missed. */
 export declare const LAYOUT_NAMES: LayoutName[];

package/lib/utils/ship/layout.js

@@ -36,6 +36,15 @@ import { SHARE } from './share-dirs.js';
  * `hdiutil` time, which is three milestones away and on another host.
  */
 const BUNDLE_NAME_FORBIDDEN = /[/:\\]/;
+/**
+ * The square sizes the Linux row writes into the hicolor theme.
+ *
+ * Here and not in a writer module like {@link ICO_SIZES} and {@link ICNS_SIZES},
+ * because there is no writer: the rasters ARE the artifact, one file per size,
+ * and the row below is the only thing that names them. See
+ * {@link LAYOUTS.linux.icon} for what asked for each of the three.
+ */
+export const HICOLOR_RASTER_SIZES = [64, 128, 256];
 /**
  * The value `ATSApplicationFontsPath` takes for this bundle, or nothing when the
  * payload carries no face (ADR 0038).
@@ -81,6 +90,10 @@ function iconFor(input, layout) {
     if (input.kind !== 'app')
         return undefined;
     if (input.icon === undefined) {
+        // The row's own answer, not a uniform one — {@link LayoutIcon.required}
+        // carries which failure mode this layout has.
+        if (LAYOUTS[layout].icon?.required !== true)
+            return undefined;
         throw new Error(`gjsify ship: the ${layout} layout writes the application's icon and was given none. ` +
             'A `kind: "app"` stage is rendered its icon by `resolveAppIcon` before the layout runs; ' +
             'reaching this row without one is a caller that skipped that step.');
@@ -105,10 +118,78 @@ export const LAYOUTS = {
             data: 'share',
             other: '',
         }),
+        // THE RASTERS THE BUILD-TIME READERS OF THE THEME NEED, and the one row
+        // whose icon is written as ordinary payload files rather than into a
+        // container. A GNOME app declares one scalable SVG, `planIcons` stages it
+        // at `share/icons/hicolor/scalable/apps/<appId>.svg`, and GTK renders it —
+        // so for three milestones this row wrote nothing.
+        //
+        // WHAT READS THE THEME BEFORE GTK DOES is `appstreamcli compose`, which
+        // `flatpak-builder` runs to produce `/app/share/app-info` — the catalogue
+        // every app store shows the app out of. AppStream 1.1.3 loads an icon
+        // through gdk-pixbuf, gdk-pixbuf reads SVG only through a LOADER MODULE,
+        // and that module is a property of the host's packaging rather than of
+        // this payload: on Fedora 44, workstation and `ghcr.io/gjsify/ci-fedora:44`
+        // alike, `/usr/lib64/gdk-pixbuf-2.0/2.10.0/loaders/` holds the xpm loader
+        // and nothing else, and `dnf provides '*/libpixbufloader-svg.so'` answers
+        // with no package at all — librsvg dropped it. So the compose run dies
+        // `file-read-error` ("image file format unknown") on the SVG and takes the
+        // whole `gjsify ship linux --target flatpak` with it. Exactly the fact
+        // `icons.ts` records for the rasterizer, one phase to the right, and the
+        // reason this is the SAME list of sizes rather than a flatpak-only patch:
+        // a `.deb` installing rasters beside its SVG is what every other GNOME app
+        // does, and the artifact stays one payload.
+        //
+        // IT IS NOT ENOUGH TO ADD THEM, measured in three probes: with the SVG
+        // present appstreamcli PREFERS it and does not fall back, so SVG + 128 and
+        // SVG + 64/128/256 both still fail and PNG-only succeeds. The SVG has to
+        // leave the tree the compose run sees — which is a Flatpak-only move,
+        // because only there is the tree built, and it is the generated manifest's
+        // `cleanup` that makes it (`flatpak-config.ts`).
+        //
+        // 64/128/256 is what a store needs and what the theme spec's own
+        // `index.theme` sizes cover: AppStream asks for 64 and 128 (it emitted
+        // exactly those two from the PNG-only probe), and 256 is the HiDPI entry
+        // Flathub's quality guidelines expect.
+        icon: {
+            sizes: HICOLOR_RASTER_SIZES,
+            writes: "the hicolor theme's raster icons (`share/icons/hicolor/<n>x<n>/apps/<appId>.png`)",
+            // The ONE row that assembles without an icon rather than refusing —
+            // `LayoutIcon.required` carries why.
+            required: false,
+        },
         // A `/usr` prefix has no manifest of its own — everything a Linux package
         // says about itself is in the `.deb`/`.rpm` header or in the freedesktop
-        // files the payload already carries.
-        metadata: () => [],
+        // files the payload already carries. What it owns is the rasters above.
+        //
+        // SKIPPING A SIZE THE PAYLOAD ALREADY STAGES is not an optimisation: a
+        // project shipping its own hand-tuned `data/icons/hicolor/128x128/apps/…`
+        // has it planned by `planIcons` at the identical path, and `placeStage`
+        // REFUSES two sources for one destination (`claim`). The project's file is
+        // the one to keep — it is drawn for that size, which is the whole point of
+        // the hicolor convention (`icons.ts`) — so the row yields rather than
+        // colliding. `resolveAppIcon` has already read that same PNG into the
+        // raster map, so the bytes agree either way; what differs is only which
+        // file the stage records as the source.
+        metadata: (input, payload) => {
+            const icon = iconFor(input, 'linux');
+            if (icon === undefined)
+                return [];
+            const planned = new Set(payload.map((file) => file.path));
+            const out = [];
+            for (const size of [...icon.png.keys()].sort((a, b) => a - b)) {
+                const rel = `${SHARE.icons}/${size}x${size}/apps/${input.appId}.png`;
+                const data = icon.png.get(size);
+                if (data === undefined || planned.has(rel))
+                    continue;
+                out.push({
+                    path: place(LAYOUTS.linux, input, rel),
+                    mode: 0o644,
+                    source: { kind: 'bytes', data },
+                });
+            }
+            return out;
+        },
         // Every architecture Debian and rpm have a name for, which is what
         // `DEBIAN_ARCH`/`RPM_ARCH` already enumerate — the layout adds nothing.
         arches: null,
@@ -213,7 +294,11 @@ export const LAYOUTS = {
         // released 0.8.0 bundle of one app (macOS 15.7, 2026-09-13): no key, no
         // `.icns`, generic icon — the twin of the Windows defect `pe-launcher.ts`
         // records.
-        icon: { sizes: ICNS_SIZES, writes: 'the macOS bundle icon (`Contents/Resources/<binaryName>.icns`)' },
+        icon: {
+            sizes: ICNS_SIZES,
+            writes: 'the macOS bundle icon (`Contents/Resources/<binaryName>.icns`)',
+            required: true,
+        },
         metadata: (input, payload) => {
             const icon = iconFor(input, 'darwin');
             const iconFile = icon === undefined ? undefined : `${input.binaryName}.icns`;
@@ -359,7 +444,11 @@ export const LAYOUTS = {
         // the target's out of its resource directory — so the `.exe` carries the
         // six sizes as `RT_ICON`/`RT_GROUP_ICON` (`ico.ts`, `pe-launcher.ts`) and
         // there is no `.ico` file in the program directory to fall out of sync.
-        icon: { sizes: ICO_SIZES, writes: 'the Windows launcher icon (`.rsrc` of `<binaryName>.exe`)' },
+        icon: {
+            sizes: ICO_SIZES,
+            writes: 'the Windows launcher icon (`.rsrc` of `<binaryName>.exe`)',
+            required: true,
+        },
         metadata: (input) => {
             const icon = iconFor(input, 'windows');
             return input.arch === 'x64'

package/lib/utils/ship/settings.js

@@ -181,9 +181,10 @@ export function resolveShipSettings(input) {
     const description = descriptionParagraphs(metadata.description) ?? [summary];
     const sections = sectionsFor(metadata.categories);
     if (kind === 'app' && discovered.iconFiles.length === 0) {
-        warnings.push(`gjsify ship: no icon found — the installed app will show a placeholder in menus and app stores ` +
-            'on Linux, and the darwin and windows layouts refuse to stage without one. Point ' +
-            '`gjsify.ship.icon` at an SVG (or a directory of sized PNGs).');
+        warnings.push(`gjsify ship: no icon found — the installed app will show a placeholder in menus on Linux, the ` +
+            'Flatpak will carry no catalogue icon for an app store to show, and the darwin and windows ' +
+            'layouts refuse to stage without one. Point `gjsify.ship.icon` at an SVG (or a directory of ' +
+            'sized PNGs).');
     }
     // Resolved here rather than in the packer, because the packer may run on a
     // host with no `package.json` at all (ADR 0024 § A2) — and because the