@gjsify/cli 0.51.0 → 0.52.0

package/lib/utils/ship/appimage.js

@@ -99,6 +99,7 @@ import { describeExit, spawnToCompletion } from '../spawn.js';
 import { encodeUtf8 } from './bytes.js';
 import { DEFAULT_GJS_FLOOR, DEFAULT_NODE_FLOOR, hostProvidedNamespaces } from './depends.js';
 import { LAYOUTS } from './layout.js';
+import { isSchemaSource, SCHEMA_CACHE } from './schemas.js';
 import { SHARE } from './share-dirs.js';
 /** The tool this packer execs. One spelling, read by this module AND by the format row. */
 export const APPIMAGE_TOOL = 'appimagetool';
@@ -234,6 +235,17 @@ export function interpreterFloor(input) {
  * drifts is the one nothing tests: `tests/e2e/ship-layout` compares the staged
  * trees, not this script.
  *
+ * THAT CLAIM WAS RE-MEASURED AGAINST THE ARTIFACT and it holds — which is worth
+ * writing down, because when Learn6502 0.8.0's AppImage died on `GSettings schema
+ * … not found` this script was the obvious suspect and adding
+ * `GSETTINGS_SCHEMA_DIR` here was the obvious fix. It would have changed nothing.
+ * Measured on the real 0.8.0 image, by compiling `gschemas.compiled` into the
+ * extracted AppDir and touching NO environment variable anywhere: the application
+ * started. The launcher's `XDG_DATA_DIRS` was already pointing GSettings at the
+ * right directory; the directory had no cache in it. An extra export would have
+ * been a second name for a path that was already correct, and it would have
+ * "fixed" the bug by sitting next to the change that did.
+ *
  * WHAT IT DOES ADD is the refusal ADR 0024 § 9 asks for. An AppImage whose
  * interpreter is missing exits with the loader's own message — `gjs: not found`
  * from a shell, or nothing at all when a desktop launches it — and the user
@@ -435,7 +447,7 @@ function rootIconRank(path, appId) {
  * those two are separate from each other (ADR 0024 § A3): three failures, three
  * different fixes — a different machine, a package, or a line in package.json.
  */
-export function assertAppImageIsPackable(payload, settings) {
+export function assertAppImageIsPackable(payload, settings, schemaCache) {
     const desktopEntry = `${SHARE.applications}/${settings.appId}.desktop`;
     if (!payload.some((entry) => entry.path === desktopEntry)) {
         throw new Error(`gjsify ship: an AppImage needs a desktop entry and this payload has no ${desktopEntry}. ` +
@@ -450,10 +462,40 @@ export function assertAppImageIsPackable(payload, settings) {
             'file keeping its own basename is an icon nothing looks up — point `gjsify.ship.icon` at a PNG ' +
             'or an SVG and it is renamed into the theme for you.');
     }
+    // THE THIRD REFUSAL, and the only one whose failure is invisible until a user
+    // double-clicks the file. The two above are decided by `package.json` and
+    // appimagetool would have caught both eventually; this one is decided by the
+    // PACK PATH and nothing catches it — the image builds, the oracle reads it
+    // back, every listing agrees, and the app dies at its first
+    // `Gio.Settings.new()` because `share/glib-2.0/schemas` holds a source with no
+    // compiled cache beside it. That is exactly what Learn6502 0.8.0 shipped.
+    //
+    // A GUARD ON THE PURE FUNCTION rather than a step in `packOne`, because this
+    // is the INVARIANT and not the procedure: whoever assembles an AppDir from a
+    // payload carrying schema sources owes it a cache, and an assembler that
+    // forgets must not be able to produce a tree. It is also what keeps the e2e
+    // honest — the suite calls this function to build its own AppDir, so it
+    // inherits the refusal instead of quietly modelling the defect.
+    if (schemaCache === undefined && payload.some((entry) => isSchemaSource(entry.path))) {
+        throw new Error(`gjsify ship: this payload stages GSettings schema sources under ${SHARE.schemas}/ and no ` +
+            `${SCHEMA_CACHE} was compiled for it. An AppImage has NO INSTALL STEP — that is the whole ` +
+            'point of the format — so the `.deb`/`.rpm` postinst that compiles the system schema ' +
+            'directory never runs, and GSettings aborts on a directory holding only sources. The AppDir ' +
+            `must carry ${SCHEMA_CACHE}; \`compileSchemasForPayload\` produces it from this payload.`);
+    }
 }
 /**
- * The whole AppDir as one payload: the prefix under `usr/`, plus the three files
- * at its root.
+ * The whole AppDir as one payload: the prefix under `usr/`, plus the compiled
+ * schema cache, plus the three files at its root.
+ *
+ * THE SCHEMA CACHE IS AN ARGUMENT AND NOT A COMPILE, so this function stays pure
+ * and so the one impure step in the AppDir has exactly one home (`packOne`). It
+ * is prefix-relative on the way in — `share/glib-2.0/schemas/gschemas.compiled`,
+ * the same shape every other entry has — and gets the `usr/` prefix from the same
+ * map below, because a second spelling of that prefix is the thing this packer
+ * spent a comment explaining it must not have. `undefined` is legal and means the
+ * payload has no schemas at all; a payload that HAS them and no cache is refused
+ * by {@link assertAppImageIsPackable}, not silently packed.
  *
  * PURE, AND ONE LIST RATHER THAN A WRITER, which is the shape `msi.ts` and
  * `dmg.ts` already have — `packOne` owns the single `writePayload` call for every
@@ -471,15 +513,18 @@ export function assertAppImageIsPackable(payload, settings) {
  * its schemas one directory too high — at exit 0, until the first
  * `Gio.Settings.new()`.
  */
-export function appDirPayload(settings, payload, hostRequirements) {
-    assertAppImageIsPackable(payload, settings);
+export function appDirPayload(settings, payload, hostRequirements, schemaCache) {
+    assertAppImageIsPackable(payload, settings, schemaCache);
     // Non-null by construction: the assertion above refuses a payload with
     // neither, and both reads are the SAME selection it made.
     const icon = selectAppDirIcon(payload, settings.appId);
     const desktopPath = `${SHARE.applications}/${settings.appId}.desktop`;
     const desktop = payload.find((entry) => entry.path === desktopPath);
     return [
-        ...payload.map((entry) => ({ ...entry, path: `${APPDIR_PREFIX_DIR}/${entry.path}` })),
+        ...[...payload, ...(schemaCache === undefined ? [] : [schemaCache])].map((entry) => ({
+            ...entry,
+            path: `${APPDIR_PREFIX_DIR}/${entry.path}`,
+        })),
         { path: APPRUN_NAME, mode: 0o755, data: encodeUtf8(renderAppRun(settings, hostRequirements)) },
         // THE SAME BYTES, TWICE, and that is the AppImage specification rather
         // than a duplication to lift: the entry under `usr/share/applications` is

package/lib/utils/ship/formats.js

@@ -396,23 +396,56 @@ export const FORMATS = {
             // is: the container is an ELF runtime for Linux with a Linux filesystem
             // behind it, so the format is bound the way the application is.
             finishOn: ['linux'],
-            // The SCHEMA COMPILER IS ABSENT here, unlike the two windows rows and
-            // for the `.dmg`'s reason inverted: this layout HAS an install step in
-            // every other format, and inside an AppImage it does not — there is no
-            // `postinst` to run `glib-compile-schemas` in a read-only squashfs. But
-            // `compileSchemasForStage` has already run at ASSEMBLY time and
-            // `gschemas.compiled` is in the payload, so declaring the compiler on
-            // the PACK path would refuse a `--from-stage` pack that works.
-            requiredTools: [APPIMAGE_TOOL],
+            // THE SCHEMA COMPILER IS DECLARED HERE, and this row is the one place
+            // in the table where it sits on a PACK path. It used to be absent, on
+            // an argument that read well and was false: "this layout has an install
+            // step in every other format, and `compileSchemasForStage` has already
+            // run at assembly time, so declaring the compiler here would refuse a
+            // `--from-stage` pack that works." The second clause never held.
+            // `compileSchemasForStage` is skipped for `layout.os === 'linux'` —
+            // deliberately, because the Linux stage is SHARED with the `.deb` and
+            // the `.rpm`, whose `share/glib-2.0/schemas` is the SYSTEM directory
+            // that a postinst compiles and that our cache must never be installed
+            // over. So no Linux stage carries `gschemas.compiled`, a `--from-stage`
+            // AppImage pack has to produce it, and this row needs the tool.
+            //
+            // MEASURED, not reasoned: Learn6502 0.8.0's first CI-built AppImage
+            // shipped `eu.jumplink.Learn6502.gschema.xml` with nothing beside it
+            // and died at `Gio.Settings.new()` on the first line it ran.
+            //
+            // AND ONLY THIS ONE OF THE FOUR, which is the question the fix had to
+            // answer next and which is measured rather than argued.
+            // `cacheRefreshCommands` (`scripts.ts`) names four install-time steps,
+            // and an AppImage runs none of them. Three DEGRADE and one ABORTS:
+            //
+            //   * `glib-compile-schemas` — ABORTS. GSettings refuses a schema
+            //     directory holding a source with no cache; there is no fallback.
+            //   * `gtk-update-icon-cache` — does not. Measured against the rebuilt
+            //     0.8.0 image on GTK 4 / glib 2.88.3: with `XDG_DATA_DIRS` pointing
+            //     at the mounted `usr/share` and no `icon-theme.cache` anywhere,
+            //     `Gtk.IconTheme.has_icon('eu.jumplink.Learn6502')` is `true` — and
+            //     `false` for a name that is not there, so the probe discriminates.
+            //     GTK scans the directory; the cache is a lookup optimisation.
+            //   * `update-desktop-database`, `update-mime-database` — about a
+            //     SYSTEM database an install writes into. An AppImage is not
+            //     installed, so there is nothing for them to update: what a desktop
+            //     reads is the entry at the AppDir root, via the runtime's own
+            //     integration.
+            //
+            // `share/locale` needs no step on any layout — the launcher exports
+            // `GJSIFY_LOCALE_DIR` and gettext reads the `.mo` directly.
+            requiredTools: [APPIMAGE_TOOL, SCHEMA_COMPILER],
             // A URL AND NOT A PACKAGE NAME, and it is the first hint in this table
             // that has to be. `flatpak-builder` and `msitools` are in Fedora and in
             // Debian; `appimagetool` is in neither, so pointing at a distro would
             // send the reader to an `E: Unable to locate package`. The `--stage`
             // half is repeated here because it is the answer for a CI image that is
-            // not going to grow a hand-installed binary.
-            installHint: 'no distribution packages it — take the release from ' +
+            // not going to grow a hand-installed binary. The compiler IS packaged,
+            // so its half of the hint is the ordinary one.
+            installHint: 'no distribution packages appimagetool — take the release from ' +
                 'https://github.com/AppImage/appimagetool/releases, `chmod +x` it and put it on PATH as ' +
-                '`appimagetool`; or assemble here with `gjsify ship linux --stage` and pack where it is',
+                '`appimagetool`; or assemble here with `gjsify ship linux --stage` and pack where it is. ' +
+                `The schema compiler is packaged: ${SCHEMA_COMPILER_HINT}`,
             oracle: {
                 // TWO READERS, NEITHER OF THEM appimagetool AND NEITHER OF THEM THE
                 // ARTIFACT'S OWN RUNTIME — which is what `--appimage-offset` and

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

@@ -0,0 +1,14 @@
+import type { AppIconRasters } from './icons.js';
+/** One element of the container: Apple's type code and the pixel size of the PNG it holds. */
+export interface IcnsElement {
+    readonly type: string;
+    readonly size: number;
+    /** The `.iconset` filename `iconutil` gives this element — the reader's spelling, for messages. */
+    readonly iconset: string;
+}
+/** The ten PNG-backed element types of a modern application icon, in `iconutil`'s order. */
+export declare const ICNS_ELEMENTS: readonly IcnsElement[];
+/** The distinct pixel sizes the ten elements need — what the layout asks the raster step for. */
+export declare const ICNS_SIZES: readonly number[];
+/** The `.icns` file, `TOC ` first, then the ten elements in {@link ICNS_ELEMENTS} order. */
+export declare function buildIcns(icon: AppIconRasters): Uint8Array;

package/lib/utils/ship/icns.js

@@ -0,0 +1,83 @@
+// The macOS icon container — what `iconutil -c icns` produces from an
+// `.iconset`, written here from the same rasters the Windows icon uses.
+//
+// THE FORMAT is a big-endian tagged container: an 8-byte header (`icns`, total
+// length), then elements, each an 8-byte head (4-char type, length INCLUDING the
+// head) and its data. Since Mac OS X 10.7 an element's data may be a whole PNG
+// file, one element type per (size, scale) pair — which is what lets this file
+// be written with no image encoder of its own.
+//
+// THE ELEMENT TABLE is Apple's iconset naming turned into type codes, and it is
+// cited to two readers rather than typed from memory: Pillow's
+// `IcnsImagePlugin.SIZES` (12.3) maps exactly these ten types to these (size,
+// scale) pairs, and `iconutil` on macOS 15 — see the report that lands this file
+// — accepts the result. `icp4`/`icp5` (16 and 32 at 1x) are the two Pillow's
+// WRITER omits and its READER accepts; they are included because Apple's own
+// `iconutil` writes them for `icon_16x16.png` and `icon_32x32.png`, and the Finder
+// list view and the Dock's smallest sizes are drawn from exactly those two.
+//
+// TEN ELEMENTS OVER SEVEN SIZES: a `@2x` element and a 1x element of twice the
+// point size hold the SAME pixels (`ic11` = 16@2x and `icp5` = 32@1x are both 32 px
+// PNGs), so the raster map is asked for seven sizes and three of them are written
+// twice. Writing all ten rather than the seven distinct sizes is what makes the
+// file complete in the Finder's terms: it looks up by (size, scale), not by pixel
+// count.
+//
+// `TOC ` FIRST, as `iconutil` and Pillow both write it: an optional index of the
+// elements that follow, which lets a reader seek without walking. Optional to
+// read, cheap to write, and its absence is the first thing a strict reader
+// notices.
+//
+// WHAT NO LINUX READER HERE CAN SAY. `icns2png` (libicns 0.8.1) parses `ic08`,
+// `ic09` and `ic10` and refuses the other seven types by name — measured on this
+// workstation, so it reads three of ten and is not an oracle for the file. Pillow
+// reads all ten and is NOT in the CI image. `verify-app-plist.py` therefore reads
+// the container with CPython `struct` and checks each PNG's IHDR against the type's
+// size, which is one independent family; the `iconutil` run on macOS is the
+// reader with authority, and it is a VM measurement, not a CI leg.
+import { concatBytes } from './bytes.js';
+import { readPngSize } from './icons.js';
+/** The ten PNG-backed element types of a modern application icon, in `iconutil`'s order. */
+export const ICNS_ELEMENTS = [
+    { type: 'icp4', size: 16, iconset: 'icon_16x16.png' },
+    { type: 'ic11', size: 32, iconset: 'icon_16x16@2x.png' },
+    { type: 'icp5', size: 32, iconset: 'icon_32x32.png' },
+    { type: 'ic12', size: 64, iconset: 'icon_32x32@2x.png' },
+    { type: 'ic07', size: 128, iconset: 'icon_128x128.png' },
+    { type: 'ic13', size: 256, iconset: 'icon_128x128@2x.png' },
+    { type: 'ic08', size: 256, iconset: 'icon_256x256.png' },
+    { type: 'ic14', size: 512, iconset: 'icon_256x256@2x.png' },
+    { type: 'ic09', size: 512, iconset: 'icon_512x512.png' },
+    { type: 'ic10', size: 1024, iconset: 'icon_512x512@2x.png' },
+];
+/** The distinct pixel sizes the ten elements need — what the layout asks the raster step for. */
+export const ICNS_SIZES = [...new Set(ICNS_ELEMENTS.map((element) => element.size))].sort((a, b) => a - b);
+/** An element head: the four-character type and the big-endian length including these 8 bytes. */
+function head(type, length) {
+    const out = Buffer.alloc(8);
+    out.write(type, 0, 'latin1');
+    out.writeUInt32BE(length, 4);
+    return new Uint8Array(out);
+}
+/** The `.icns` file, `TOC ` first, then the ten elements in {@link ICNS_ELEMENTS} order. */
+export function buildIcns(icon) {
+    const elements = ICNS_ELEMENTS.map((element) => {
+        const png = icon.png.get(element.size);
+        if (png === undefined) {
+            throw new Error(`gjsify ship: the macOS icon needs a ${element.size} px image (${element.iconset}) and the raster ` +
+                `set has none — \`resolveAppIcon\` was asked for the wrong sizes.`);
+        }
+        const { width, height } = readPngSize(png, `the ${element.size} px icon image`);
+        if (width !== element.size || height !== element.size) {
+            throw new Error(`gjsify ship: the image keyed ${element.size} in the icon raster set is ${width}×${height}.`);
+        }
+        return { ...element, png };
+    });
+    const toc = concatBytes([
+        head('TOC ', 8 + 8 * elements.length),
+        ...elements.map((element) => head(element.type, 8 + element.png.length)),
+    ]);
+    const body = elements.map((element) => concatBytes([head(element.type, 8 + element.png.length), element.png]));
+    const total = 8 + toc.length + body.reduce((sum, element) => sum + element.length, 0);
+    return concatBytes([head('icns', total), toc, ...body]);
+}

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

@@ -0,0 +1,25 @@
+import type { AppIconRasters } from './icons.js';
+/** The edge lengths a Windows application icon carries. Ascending, so the entry order is too. */
+export declare const ICO_SIZES: readonly number[];
+/** `RT_ICON` and `RT_GROUP_ICON`: the two resource type ids. */
+export declare const RT_ICON = 3;
+export declare const RT_GROUP_ICON = 14;
+/**
+ * The `.ico` file: `ICONDIR`, one `ICONDIRENTRY` per image, then the PNGs.
+ */
+export declare function buildIco(icon: AppIconRasters): Uint8Array;
+/** What the PE resource directory carries: the group, and the images the group names by id. */
+export interface IconResources {
+    /** The `RT_GROUP_ICON` payload: `GRPICONDIR` with 14-byte entries naming `icons` by 1-based id. */
+    group: Uint8Array;
+    /** The `RT_ICON` payloads, in id order: `icons[i]` is resource id `i + 1`. */
+    icons: readonly Uint8Array[];
+}
+/**
+ * The same images as resources: `RT_ICON` id `n` is the n-th image, and the
+ * `RT_GROUP_ICON` names them by that id.
+ *
+ * Ids start at 1 because resource id 0 is never used by convention and some
+ * readers treat it as "no icon".
+ */
+export declare function iconResources(icon: AppIconRasters): IconResources;

package/lib/utils/ship/ico.js

@@ -0,0 +1,120 @@
+// The Windows icon container, in its two spellings: the `.ico` FILE, and the
+// pair of resource types (`RT_GROUP_ICON`, `RT_ICON`) the same bytes take inside
+// a PE image.
+//
+// WHY BOTH. Explorer, the Start menu, the taskbar and the Alt-Tab list all ask
+// the EXECUTABLE for its icon, so the launcher `pe-launcher.ts` emits carries the
+// resource form. The `.ico` file form is what an independent reader opens —
+// Pillow, `icotool`, ImageMagick — and it is how `verify-program-dir.py`
+// reassembles what it extracted from the `.rsrc` section to hand it to one.
+//
+// THE RESOURCE FORM IS NOT THE FILE FORM, and the difference is the one thing
+// worth knowing about this format. An `.ico` is an `ICONDIR` whose entries end in
+// a 4-byte `dwImageOffset` into the file. Inside a PE the images are separate
+// `RT_ICON` resources, so the group directory's entries end in a 2-byte `nId`
+// naming the resource instead — `GRPICONDIRENTRY` is 14 bytes where
+// `ICONDIRENTRY` is 16. Writing the file form into `RT_GROUP_ICON` produces a
+// resource Windows reads as a group with garbage ids, and the shell shows the
+// generic icon with no error anywhere.
+//
+// PNG PAYLOADS AT EVERY SIZE. Since Windows Vista an image entry may be a whole
+// PNG file rather than a BMP `BITMAPINFOHEADER` + pixel rows + AND mask, and that
+// is what removes the need for a BMP encoder here. Confirmed against two readers
+// on this workstation rather than trusted: Pillow 12.3 and `icotool -l`
+// (icoutils 0.32) both list a six-entry PNG-only `.ico` at 16/24/32/48/64/256
+// as six 32-bit images. The 256 entry is the one every guide says MUST be PNG
+// (a BMP at that size is 256 KiB); the smaller ones are PNG for the same reason
+// and because one encoding is one code path. Whether Windows 11's shell draws the
+// small PNG entries at the same quality as BMP ones is a VM measurement this
+// tree has not made — see the report that lands this file.
+//
+// THE SIZES are Microsoft's list for a classic desktop application icon — 16,
+// 24, 32, 48 and 256, "the full set" in the *Icons (Design basics)* guidance —
+// plus 64, which the same page names for the 200 % scaling of the 32 slot. The
+// Start menu and the taskbar pick from these by DPI; a set missing 16 or 32
+// renders the entry as a scaled 256, which is the blur every reader has seen on a
+// half-finished port.
+import { concatBytes } from './bytes.js';
+import { readPngSize } from './icons.js';
+/** The edge lengths a Windows application icon carries. Ascending, so the entry order is too. */
+export const ICO_SIZES = [16, 24, 32, 48, 64, 256];
+/** `RT_ICON` and `RT_GROUP_ICON`: the two resource type ids. */
+export const RT_ICON = 3;
+export const RT_GROUP_ICON = 14;
+/** The ICONDIRENTRY / GRPICONDIRENTRY head shared by both forms: 8 bytes. */
+function entryHead(size) {
+    const head = Buffer.alloc(8);
+    // 0 means 256 in the one-byte width/height fields — the format predates 256
+    // px icons and a byte cannot hold the number.
+    head.writeUInt8(size >= 256 ? 0 : size, 0); // bWidth
+    head.writeUInt8(size >= 256 ? 0 : size, 1); // bHeight
+    head.writeUInt8(0, 2); // bColorCount — 0 for anything past 8 bpp
+    head.writeUInt8(0, 3); // bReserved
+    head.writeUInt16LE(1, 4); // wPlanes
+    head.writeUInt16LE(32, 6); // wBitCount — what a PNG-backed entry declares
+    return new Uint8Array(head);
+}
+/** The sizes in ascending order, each one asserted present and square at that size. */
+function entries(icon) {
+    const out = [];
+    for (const size of ICO_SIZES) {
+        const png = icon.png.get(size);
+        if (png === undefined) {
+            throw new Error(`gjsify ship: the Windows icon needs a ${size} px image and the raster set has none — ` +
+                `\`resolveAppIcon\` was asked for the wrong sizes (it has ${[...icon.png.keys()].join(', ')}).`);
+        }
+        const { width, height } = readPngSize(png, `the ${size} px icon image`);
+        if (width !== size || height !== size) {
+            throw new Error(`gjsify ship: the image keyed ${size} in the icon raster set is ${width}×${height}.`);
+        }
+        if (size > 256) {
+            // The one-byte size fields cannot say more than 256, and Windows reads
+            // nothing larger from an icon.
+            throw new Error(`gjsify ship: a Windows icon image cannot be ${size} px — 256 is the format's ceiling.`);
+        }
+        out.push({ size, png });
+    }
+    return out;
+}
+/**
+ * The `.ico` file: `ICONDIR`, one `ICONDIRENTRY` per image, then the PNGs.
+ */
+export function buildIco(icon) {
+    const images = entries(icon);
+    const header = Buffer.alloc(6);
+    header.writeUInt16LE(0, 0); // idReserved
+    header.writeUInt16LE(1, 2); // idType — 1 is an icon, 2 a cursor
+    header.writeUInt16LE(images.length, 4);
+    const directory = [];
+    let offset = 6 + 16 * images.length;
+    for (const { size, png } of images) {
+        const tail = Buffer.alloc(8);
+        tail.writeUInt32LE(png.length, 0); // dwBytesInRes
+        tail.writeUInt32LE(offset, 4); // dwImageOffset — a FILE offset
+        directory.push(entryHead(size), new Uint8Array(tail));
+        offset += png.length;
+    }
+    return concatBytes([new Uint8Array(header), ...directory, ...images.map((image) => image.png)]);
+}
+/**
+ * The same images as resources: `RT_ICON` id `n` is the n-th image, and the
+ * `RT_GROUP_ICON` names them by that id.
+ *
+ * Ids start at 1 because resource id 0 is never used by convention and some
+ * readers treat it as "no icon".
+ */
+export function iconResources(icon) {
+    const images = entries(icon);
+    const header = Buffer.alloc(6);
+    header.writeUInt16LE(0, 0);
+    header.writeUInt16LE(1, 2);
+    header.writeUInt16LE(images.length, 4);
+    const directory = [];
+    images.forEach(({ size, png }, index) => {
+        const tail = Buffer.alloc(6);
+        tail.writeUInt32LE(png.length, 0); // dwBytesInRes
+        tail.writeUInt16LE(index + 1, 4); // nId — the RT_ICON resource, NOT an offset
+        directory.push(entryHead(size), new Uint8Array(tail));
+    });
+    return { group: concatBytes([new Uint8Array(header), ...directory]), icons: images.map((image) => image.png) };
+}

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

@@ -0,0 +1,191 @@
+import { spawnToCompletion } from '../spawn.js';
+import type { SystemGiOptions } from '../system-gi.js';
+/** The runtime that renders. On `PATH`, like `glib-compile-schemas` — a GJS host has it by definition. */
+export declare const RASTERIZER = "gjs";
+/**
+ * How to get the typelib the script imports, in the two distributions' words.
+ *
+ * `librsvg2` on Fedora carries the typelib itself (measured: `rpm -qf
+ * /usr/lib64/girepository-1.0/Rsvg-2.0.typelib` → `librsvg2-2.62.3`); Debian
+ * splits it into `gir1.2-rsvg-2.0`.
+ *
+ * The macOS row IS measured, on the `macos-suites` darwin leg, and its first
+ * spelling was WRONG: `brew install gjs librsvg` alone still failed, with the
+ * error moving from `namespace 'Rsvg' not found` to `namespace 'cairo', version
+ * '1.0' not found`. The script imports both, and `Cairo-1.0.typelib` belongs to
+ * `gobject-introspection` rather than to the `cairo` formula (`rpm -qf` says so
+ * for the Fedora twin). A hint that names two thirds of what is needed sends a
+ * stranger round the same loop this one went round.
+ *
+ * INSTALLING ALL THREE IS STILL NOT ENOUGH on macOS, and this sentence cost the
+ * third red run: the dylib then EXISTS and dyld does not look where it is. That
+ * half is not a hint, it is {@link rasterizerEnv} — and the message deliberately
+ * stays quiet about it, because a host that reaches this line after the repair
+ * really is missing a package.
+ *
+ * Assembly is a Linux step by ADR 0024 § A2, so a darwin host reaching this line
+ * is running `ship` outside the documented arrangement; the message should still
+ * tell it what to install rather than name two Linuxes at it.
+ */
+export declare const RASTERIZER_HINT: string;
+/**
+ * The pixels of the app icon, one PNG per square edge length.
+ *
+ * A MAP keyed by size and not an array, because every consumer asks "the PNG for
+ * N" — the `.ico` writer for its six entries, the `.icns` writer for its ten
+ * elements over seven sizes — and an array would make each of them search.
+ */
+export interface AppIconRasters {
+    /** Where the pixels came from, for the log line: the SVG's path, or how many sized PNGs. */
+    readonly source: string;
+    readonly png: ReadonlyMap<number, Uint8Array>;
+}
+/**
+ * Whether an icon belongs in the theme's SYMBOLIC context rather than at a size.
+ *
+ * `symbolic` is a directory of its own in a hicolor theme and NOT a size value.
+ * Measured in `refs/adwaita-icon-theme/index.theme`, which lists `symbolic/apps`
+ * in `Directories=` beside `scalable/apps` and `16x16/apps` and gives it its own
+ * section — `Context=Applications`, `Size=16`, `MinSize=8`, `MaxSize=512`,
+ * `Type=Scalable` — against the scalable row's `Size=128`. The freedesktop icon
+ * theme specification has no notion of `symbolic` at all: a theme expresses it by
+ * giving the directory a section, which is exactly why reading the EXTENSION
+ * cannot see it, and why this question has to be asked before the size one.
+ *
+ * TWO SIGNALS, the same pair `iconThemeDir` already reads for a size: the
+ * directory an author put the file in, and the name they gave it. GTK resolves a
+ * symbolic icon by the `-symbolic` name suffix, so an author who wrote the name
+ * has said as much as one who wrote the path.
+ *
+ * SVG ONLY, because the symbolic directory is declared `Type=Scalable`: the
+ * raster form GTK's own `gtk-encode-symbolic-svg` produces
+ * (`<name>-symbolic.symbolic.png`) is installed at a SIZE instead. So a PNG keeps
+ * answering the size question, and one that cannot answer it stays refused rather
+ * than quietly becoming a scalable icon that does not scale.
+ */
+export declare function isSymbolicIcon(iconPath: string): boolean;
+/**
+ * The hicolor subdirectory for an icon: the `symbolic` CONTEXT, else `scalable`
+ * for an SVG, else the pixel size read from a `<n>x<n>` path component or a
+ * trailing number in the filename.
+ *
+ * Named for the theme DIRECTORY rather than a size from the moment the first of
+ * those answers stopped being one: `iconSizeDir` returning `symbolic` would be a
+ * name every caller has to read past.
+ */
+export declare function iconThemeDir(iconPath: string): string;
+/**
+ * A PNG's pixel size, read from its IHDR — with the file's two ends checked.
+ *
+ * The signature and the IHDR say what the file CLAIMS to be; the `IEND` trailer
+ * says it is all there. A PNG truncated by a half-written copy still has a valid
+ * header, and an icon container built around one embeds a picture that decodes
+ * to nothing on the target OS with no error at pack time. Twelve bytes at the end
+ * is the cheapest check that catches that whole class.
+ */
+export declare function readPngSize(bytes: Uint8Array, what: string): {
+    width: number;
+    height: number;
+};
+/**
+ * The program the child GJS runs. `ARGV` is the SVG path followed by the sizes;
+ * stdout is one JSON object mapping each size to the PNG, base64.
+ *
+ * Legacy `imports`, deliberately: `gjs -c` takes a script, not a module, and the
+ * legacy namespace is the one a script can reach synchronously. `imports.cairo`
+ * is GJS's own cairo binding — `ImageSurface` and `writeToPNG` are its, not the
+ * typelib's, which has no constructors.
+ *
+ * `render_document` scales the document to the viewport, so each size is a
+ * fresh vector render and never a resample of a larger one — the difference
+ * between a crisp 16 px icon and a blurred one, which is the whole reason to
+ * render per size rather than once.
+ *
+ * Through a file rather than a memory surface's bytes: `writeToPNG` is the PNG
+ * ENCODER, and cairo is the one this process has. Base64 on stdout because it is
+ * the transport both runtimes' `child_process` read the same way.
+ */
+export declare const RASTERIZE_SCRIPT: string;
+/**
+ * The launch env for the rasterizing child — the HOST's GI libdirs put back.
+ *
+ * THE INCIDENT, measured on both `macos-suites` legs (2026-09-13). `brew install
+ * gjs librsvg gobject-introspection` installs everything the script imports, and
+ * the render still died:
+ *
+ *     Failed to load shared library 'librsvg-2.2.dylib' referenced by the typelib:
+ *       dlopen(librsvg-2.2.dylib): tried: 'librsvg-2.2.dylib' (no such file),
+ *       '/usr/local/Cellar/gjs/1.88.1/bin/../../../../opt/glib/lib/librsvg-2.2.dylib',
+ *       '/usr/lib/librsvg-2.2.dylib' (not in dyld cache)
+ *     JS ERROR: Error: Unsupported type void, deriving from fundamental void
+ *
+ * `/usr/local/lib` (x64) and `/opt/homebrew/lib` (arm64) — where Homebrew puts
+ * the dylib — are in NEITHER list, because a typelib names its library by bare
+ * leaf and Homebrew's `gjs` carries one rpath, into GLIB's keg alone. The second
+ * line is the symptom, not the cause: the typelib loads, its library does not,
+ * and the first call then marshals a type that is no longer resolvable. It reads
+ * like GJS was built without cairo, and this comment exists because that is what
+ * it was first diagnosed as.
+ *
+ * {@link buildNativeEnv} already repairs exactly this, and its own header calls
+ * itself "the ONE place `gjsify run`, `showcase`, `storybook`, `tsc` and `info`
+ * all pass through". `ship` opened a SECOND gjs child that went around it — which
+ * is the class, not the bug: the repair is per-call-site, so every new child
+ * inherits the gap until someone reads that header. `rasterizerEnv` is what the
+ * spec beside it pins, so the wiring is asserted and not just the composition.
+ *
+ * No packages are passed: the gap is in the host's loader, not in a prebuild we
+ * ship, and the child is a bare `gjs -c` that loads no `.node` at all.
+ *
+ * `env` FIRST, so the composed values win over the inherited ones rather than
+ * being shadowed by them.
+ */
+export declare function rasterizerEnv(opts?: {
+    platform?: string;
+    env?: Record<string, string | undefined>;
+    /** Injectable for tests — the darwin branch is asserted from Linux. */
+    systemGiDirs?: (opts: SystemGiOptions) => string[];
+}): NodeJS.ProcessEnv;
+export interface RasterizeInput {
+    /** Absolute path of the SVG. */
+    svg: string;
+    /** Square edge lengths to render, each one a separate vector render. */
+    sizes: readonly number[];
+    /**
+     * Injectable for tests. NOT a convenience: the {@link rasterizerEnv} repair is
+     * only worth anything if it reaches the child, and a spec over the composition
+     * alone passes just as well when nobody wires it in.
+     */
+    spawn?: typeof spawnToCompletion;
+}
+/**
+ * Render an SVG at every size through librsvg, in a child GJS.
+ *
+ * Every PNG that comes back is read for its IHDR before it is returned: the size
+ * the child rendered is the size the caller asked for or the whole batch is
+ * refused, because the writer that would embed it trusts the map's key.
+ */
+export declare function rasterizeSvg(input: RasterizeInput): Promise<Map<number, Uint8Array>>;
+export interface ResolveAppIconInput {
+    /** Absolute paths of the project's icons — `ShipSettings.iconFiles`. */
+    iconFiles: readonly string[];
+    appId: string;
+    /** The square sizes the layout's writer needs, from {@link Layout.icon}. */
+    sizes: readonly number[];
+    /** What the sizes are FOR, in the refusal: "the Windows launcher's icon". */
+    target: string;
+    /** The renderer, injectable so the selection is testable without a GJS. */
+    rasterize?: (input: RasterizeInput) => Promise<Map<number, Uint8Array>>;
+}
+/**
+ * The raster set a layout needs, from whatever the project declares.
+ *
+ * Sized PNGs the project ships are used at their (IHDR-read) size; every size
+ * they leave uncovered is rendered from the scalable SVG; a size neither can
+ * answer is a refusal that names the file to add. The `-symbolic` icon is never
+ * a source: it is the monochrome status-bar glyph, and an app icon drawn from it
+ * would be a grey silhouette on both platforms.
+ */
+export declare function resolveAppIcon(input: ResolveAppIconInput): Promise<AppIconRasters>;
+/** The sizes in a raster set, ascending — for log lines and error messages. */
+export declare function iconSizes(icon: AppIconRasters): number[];