@gjsify/cli 0.51.1 → 0.52.0

package/lib/utils/ship/layout.js

@@ -21,8 +21,10 @@
 // the data tree is addressed by `appId`. Nothing here is derived from gjsify's own
 // tree, and nothing here has a gjsify-specific default.
 import { posix } from 'node:path';
+import { buildIcns, ICNS_SIZES } from './icns.js';
+import { ICO_SIZES, iconResources } from './ico.js';
 import { buildGuiLauncher } from './pe-launcher.js';
-import { BUNDLE_INFO_PLIST, BUNDLE_PKGINFO, renderInfoPlist, renderPkgInfo } from './plist.js';
+import { BUNDLE_INFO_PLIST, BUNDLE_PKGINFO, BUNDLE_RESOURCES, renderInfoPlist, renderPkgInfo } from './plist.js';
 import { SHARE } from './share-dirs.js';
 /**
  * Characters a `<App>.app` directory name may not contain.
@@ -63,6 +65,27 @@ function appBundleDir(identity) {
     }
     return `${identity.name}.app`;
 }
+/**
+ * The rasters a row writes its icon from, or nothing for a CLI — and a refusal
+ * for an application that arrives without them.
+ *
+ * The second of two guards. `commands/ship.ts` renders the icon for every row
+ * that declares {@link Layout.icon}; this is the row itself checking it was
+ * given one, so a stage assembled through any other path (a test, a future
+ * caller) cannot produce an application whose Start-menu entry or Finder icon is
+ * the generic one without saying so. That silence is the measured defect the
+ * whole seam exists against (`icons.ts`).
+ */
+function iconFor(input, layout) {
+    if (input.kind !== 'app')
+        return undefined;
+    if (input.icon === 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.');
+    }
+    return input.icon;
+}
 export const LAYOUTS = {
     linux: {
         name: 'linux',
@@ -102,15 +125,15 @@ export const LAYOUTS = {
             'macOS ships no Node, and there is no RELOCATABLE GJS (`build-gtk-runtime-darwin.mjs`: "GJS ' +
             'ships no relocation"), so ADR 0024 § 4 derives Node here. A self-contained bundle needs `@gjsify/node-runtime-darwin-<arch>` and a ' +
             '`--app node` payload (#1354 M0), or `@gjsify/gjs-runtime-darwin-<arch>` (ADR 0024 stage 7).',
-        // THE ONE LAYOUT WHERE THE ENV VARIABLE IS NOT THE MECHANISM, and assuming it
-        // was is the mistake this comment exists to stop being made again. macOS Pango
-        // is CORETEXT, not fontconfig: GTK's own `meson.build` carries
-        // `fontconfig_dep = []  # only used in x11 backend` and Homebrew's gtk4 formula
-        // builds `-Dx11-backend=false -Dmacos-backend=true`, while cairo's `quartz`
+        // THE LAYOUT WHERE THE ENV VARIABLE IS NOT THE MECHANISM BY DEFAULT, and assuming
+        // it was is the mistake this comment exists to stop being made again. macOS Pango
+        // resolves CORETEXT unless something chooses otherwise: GTK's own `meson.build`
+        // carries `fontconfig_dep = []  # only used in x11 backend` and Homebrew's gtk4
+        // formula builds `-Dx11-backend=false -Dmacos-backend=true`, while cairo's `quartz`
         // option defaults to `auto` and auto-enables on darwin — so a `fonts.conf`
-        // inside a `.app` would be inert twice over, wrong Pango backend AND no
+        // inside a `.app` is inert twice over there, wrong Pango backend AND no
         // GTK-side fontconfig. `XDG_DATA_DIRS` still carries the icons and the schemas
-        // here; it does not carry the faces.
+        // in that case; it does not carry the faces.
         //
         // What does is `ATSApplicationFontsPath`, emitted into `Info.plist` by
         // `metadata` above — Apple's own per-app activation, and the ORDERING is why it
@@ -120,14 +143,25 @@ export const LAYOUTS = {
         // path in `pangocoretext-fontmap.c`, so a face registered after the font map
         // initialises is not recoverable by poking it. The system activates this key's
         // directory at LAUNCH, before any of the app's code runs.
+        //
+        // WHAT CHOOSES OTHERWISE is `@gjsify/node-gi`'s loader, which sets
+        // `PANGOCAIRO_BACKEND=fc` for the bundled windowing runtime (ADR 0038 § Amendment
+        // 3) — so a `--app node` `.app` carrying that bundle reads the faces through
+        // fontconfig and registers them like the other two layouts. The declarative route
+        // stays emitted all the same: it is what a CoreText map still needs, and nothing
+        // here can know which runtime a given `.app` ends up carrying. Both routes named,
+        // neither assumed — which is also why `fontGap` prints the probe that answers it
+        // for a particular build rather than a claim about the platform.
         fontGap: 'the faces are staged in `share/fonts/<appId>` and `Info.plist` carries `ATSApplicationFontsPath` ' +
-            "at it, which is macOS's own per-app activation — NOT the XDG_DATA_DIRS path, because Pango on " +
-            'macOS is CoreText-backed and GTK is not built against fontconfig there. That the activation ' +
-            "reaches Pango's CoreText font map is UNVERIFIED: no leg in this repository runs a `.app`. " +
-            'Confirm with `PangoCairo.FontMap.get_default().list_families()` in the shipped bundle, and ' +
-            '`PANGOCAIRO_BACKEND=bogus` to print which backend it was built with. An app that calls ' +
-            '`initFonts()` from `@gjsify/gtk-host/fonts` for the Windows row needs no branch around it: the ' +
-            'CoreText map answers G_IO_ERROR_NOT_SUPPORTED and that call deliberately does nothing here.',
+            "at it, which is macOS's own per-app activation and the route that matters whenever Pango on " +
+            'macOS resolves CoreText by default — which it does on a Homebrew GTK, because that one is not ' +
+            'built against fontconfig. A `.app` carrying the bundled GTK runtime reads the same faces through ' +
+            "fontconfig instead: `@gjsify/node-gi`'s loader selects it with `PANGOCAIRO_BACKEND=fc` " +
+            '(ADR 0038 § Amendment 3), and `initFonts()` from `@gjsify/gtk-host/fonts` registers them as it ' +
+            'does on Windows. Either way no branch is needed in your app: a CoreText map answers ' +
+            'G_IO_ERROR_NOT_SUPPORTED and the call reports that as declined. Confirm in the shipped bundle ' +
+            'with `PangoCairo.FontMap.get_default().list_families()`, and `PANGOCAIRO_BACKEND=bogus` to ' +
+            'print which backends it was built with.',
         launcherExt: '',
         root: appBundleDir,
         // Apple's, all four. `Contents/MacOS` holds executables, `Contents/Resources`
@@ -148,18 +182,40 @@ export const LAYOUTS = {
         // nothing tells LaunchServices which file under `Contents/MacOS` to exec,
         // and a `*.app` with no `Info.plist` is a folder with a suffix — which is
         // exactly what M1 staged. `plist.ts` carries the per-key citations.
-        metadata: (input, payload) => [
-            {
-                path: `${appBundleDir(input)}/${BUNDLE_INFO_PLIST}`,
-                mode: 0o644,
-                source: { kind: 'text', text: renderInfoPlist(input, darwinFontsPath(input, payload)) },
-            },
-            {
-                path: `${appBundleDir(input)}/${BUNDLE_PKGINFO}`,
-                mode: 0o644,
-                source: { kind: 'text', text: renderPkgInfo() },
-            },
-        ],
+        //
+        // AND THE ICON, the third file — `Contents/Resources/<binaryName>.icns`,
+        // named by `CFBundleIconFile`. Both halves or neither: the key without the
+        // file is a dangling reference the Finder resolves to the generic icon, and
+        // the file without the key is bytes nothing reads. Measured absent on the
+        // 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`)' },
+        metadata: (input, payload) => {
+            const icon = iconFor(input, 'darwin');
+            const iconFile = icon === undefined ? undefined : `${input.binaryName}.icns`;
+            return [
+                {
+                    path: `${appBundleDir(input)}/${BUNDLE_INFO_PLIST}`,
+                    mode: 0o644,
+                    source: { kind: 'text', text: renderInfoPlist(input, darwinFontsPath(input, payload), iconFile) },
+                },
+                {
+                    path: `${appBundleDir(input)}/${BUNDLE_PKGINFO}`,
+                    mode: 0o644,
+                    source: { kind: 'text', text: renderPkgInfo() },
+                },
+                ...(icon === undefined || iconFile === undefined
+                    ? []
+                    : [
+                        {
+                            path: `${appBundleDir(input)}/${BUNDLE_RESOURCES}/${iconFile}`,
+                            mode: 0o644,
+                            source: { kind: 'bytes', data: buildIcns(icon) },
+                        },
+                    ]),
+            ];
+        },
         // The two architectures macOS runs on, which is also exactly what
         // `@gjsify/gtk-runtime-darwin-*` and `@gjsify/node-runtime-darwin-*` are
         // published for. Nothing upstream blocks a third; there is no third.
@@ -227,8 +283,10 @@ export const LAYOUTS = {
         // warning, which is exactly what the probe family did BEFORE the call.
         fontGap: 'the faces are staged in `share/fonts/<appId>` and the launcher exports GJSIFY_FONT_DIR at it, ' +
             'but WINDOWS HAS NO DECLARATIVE FONT ACTIVATION and nothing here reaches a bundled face on its ' +
-            'own: GTK4 uses pangowin32, whose font map is populated from DirectWrite and never from ' +
-            'fontconfig or from GDI. MEASURED on Windows 11 / GTK 4.22.4 rather than inferred (ADR 0038 ' +
+            'own: GTK4 resolves pangowin32, whose font map is populated from DirectWrite and never from ' +
+            'fontconfig or from GDI, unless something selects otherwise — which the bundled GTK runtime does ' +
+            '(`PANGOCAIRO_BACKEND=fc`, ADR 0038 § Amendment 3), and an app may. MEASURED on the DirectWrite ' +
+            'map, Windows 11 / GTK 4.22.4, rather than inferred (ADR 0038 ' +
             'W1-W5): a FONTCONFIG_FILE naming the staged directory moves the default font map by nothing ' +
             'even when it is the ONLY configuration present — that map does not read fontconfig, and exposes ' +
             'no config_changed or set_config with which to make it — while add_font_file on the same map a ' +
@@ -272,15 +330,31 @@ export const LAYOUTS = {
         // refusal, about our own file). `arches.only` already says there is no
         // other Windows architecture; a stage for one stays assemblable and stays
         // unpackable, which is the split `Layout.runtimeGap` draws everywhere else.
-        metadata: (input) => input.arch === 'x64'
-            ? [
-                {
-                    path: windowsGuiLauncherPath(input),
-                    mode: 0o755,
-                    source: { kind: 'bytes', data: buildGuiLauncher({ logLeaf: windowsLaunchLogLeaf(input) }) },
-                },
-            ]
-            : [],
+        //
+        // THE ICON RIDES INSIDE THAT PROGRAM. A shortcut with no icon of its own
+        // shows its target's, and Explorer, the Start menu and the taskbar all read
+        // 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`)' },
+        metadata: (input) => {
+            const icon = iconFor(input, 'windows');
+            return input.arch === 'x64'
+                ? [
+                    {
+                        path: windowsGuiLauncherPath(input),
+                        mode: 0o755,
+                        source: {
+                            kind: 'bytes',
+                            data: buildGuiLauncher({
+                                logLeaf: windowsLaunchLogLeaf(input),
+                                ...(icon === undefined ? {} : { icon: iconResources(icon) }),
+                            }),
+                        },
+                    },
+                ]
+                : [];
+        },
         // ONE, and the blocker is a project we do not own. `wingtk/gvsbuild`
         // hardcodes `self.platform = "x64"` in `utils/base_project.py` and its last
         // five releases publish exactly two assets each, both x64 — so there is no

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

@@ -60,7 +60,7 @@ export declare function msiProductVersion(version: string): string;
  * agree still differ. `renderWxs` asserts uniqueness anyway rather than trusting
  * 48 bits, because the failure of a collision is two files fighting over one row.
  */
-export declare function msiIdentifier(prefix: string, path: string): string;
+export declare function msiIdentifier(prefix: string, path: string, suffix?: string): string;
 /** One payload file, as the installer will address it. */
 export interface MsiFile {
     /** Program-directory-relative path, POSIX-separated. */

package/lib/utils/ship/msi.js

@@ -175,11 +175,13 @@ export function msiProductVersion(version) {
  * agree still differ. `renderWxs` asserts uniqueness anyway rather than trusting
  * 48 bits, because the failure of a collision is two files fighting over one row.
  */
-export function msiIdentifier(prefix, path) {
+export function msiIdentifier(prefix, path, suffix = '') {
     const digest = createHash('sha1').update(new TextEncoder().encode(path)).digest('hex').slice(0, 12);
     const safe = path.replace(/[^A-Za-z0-9_.]/g, '_');
-    const room = 72 - prefix.length - 2 - digest.length;
-    return `${prefix}_${safe.length > room ? safe.slice(safe.length - room) : safe}_${digest}`;
+    // The suffix is part of the 72, or an `Icon` id (which has to END in `.exe`)
+    // built from a long path would be the one identifier over the limit.
+    const room = 72 - prefix.length - 2 - digest.length - suffix.length;
+    return `${prefix}_${safe.length > room ? safe.slice(safe.length - room) : safe}_${digest}${suffix}`;
 }
 /**
  * What Windows Installer will not hold in a `FileName`/`DefaultDir` cell.
@@ -264,9 +266,27 @@ export function renderWxs(input) {
         identifiers.set(id, what);
         return id;
     };
+    // THE ICON IS THE LAUNCHER ITSELF. The Icon table holds a file — an `.ico`,
+    // or an `.exe`/`.dll` the installer reads an icon OUT OF by `IconIndex` — and
+    // the stub already carries the app's icon in its resource directory
+    // (`pe-launcher.ts`). Naming the launcher as the icon source means one file
+    // holds the pixels the shortcut, Add/Remove Programs and Explorer all show,
+    // and nothing in `ship/msi/` can drift from what is installed.
+    //
+    // WHY THE MSI NEEDS ITS OWN ROW when the `.exe` already has the icon. A
+    // shortcut with no `Icon_` shows its target's icon once the target exists;
+    // this one is ADVERTISED, and Windows Installer's Shortcut table documents the
+    // `Icon_` column as the icon shown for an advertised shortcut — whose target
+    // is a descriptor the shell resolves through the installer, not the file. And
+    // `ARPPRODUCTICON` is the only route to an icon in Add/Remove Programs at all;
+    // the `.exe` is never consulted there. Two consumers the embedded icon cannot
+    // reach, one row. Windows Installer requires the Icon NAME to carry the
+    // extension of the file it holds, so the id ends in `.exe`.
+    const launcherIconId = claim(msiIdentifier('i', launcher, '.exe'), 'the launcher icon');
     const lines = [];
     const componentIds = [];
     let launcherFound = false;
+    let launcherSource;
     const emitDir = (node, indent) => {
         for (const file of node.files) {
             const componentId = claim(msiIdentifier('c', file.path), file.path);
@@ -289,12 +309,13 @@ export function renderWxs(input) {
             // with it.
             if (file.path === launcher) {
                 launcherFound = true;
+                launcherSource = file.source;
                 lines.push(`${indent}    <File Id="${fileId}" Name="${name}" ` +
                     `Source="${xmlEscape(file.source)}" KeyPath="yes">`);
                 lines.push(`${indent}        <Shortcut Id="${claim('s_startmenu', 'the Start-Menu shortcut')}" ` +
                     `Directory="ProgramMenuFolder" Name="${xmlEscape(settings.name)}" ` +
                     `WorkingDirectory="INSTALLDIR" Description="${xmlEscape(settings.summary)}" ` +
-                    `Advertise="yes" />`);
+                    `Icon="${launcherIconId}" IconIndex="0" Advertise="yes" />`);
                 lines.push(`${indent}    </File>`);
             }
             else {
@@ -317,7 +338,7 @@ export function renderWxs(input) {
     if (componentIds.length === 0) {
         throw new Error('gjsify ship: the windows payload is empty, so there is nothing for an `.msi` to install.');
     }
-    if (!launcherFound) {
+    if (!launcherFound || launcherSource === undefined) {
         throw new Error(`gjsify ship: the windows payload carries no "${launcher}" at the root of the program directory, ` +
             'so the installer would have nothing to point a Start-Menu shortcut at — an application a user ' +
             'installs and\n    cannot start. `windows-dir` puts the launcher there; a payload without one ' +
@@ -343,6 +364,10 @@ export function renderWxs(input) {
         // downloads rather than an `.msi` plus loose `.cab` siblings that a user
         // will separate from it.
         '        <Media Id="1" Cabinet="app.cab" EmbedCab="yes" />',
+        // The launcher, a second time, as the Icon table's binary — see
+        // `launcherIconId` above for why the same file is both.
+        `        <Icon Id="${launcherIconId}" SourceFile="${xmlEscape(launcherSource)}" />`,
+        `        <Property Id="ARPPRODUCTICON" Value="${launcherIconId}" />`,
         ...about,
         '        <Directory Id="TARGETDIR" Name="SourceDir">',
         '            <Directory Id="ProgramFiles64Folder">',

package/lib/utils/ship/pe-launcher.d.ts

@@ -1,3 +1,4 @@
+import { type IconResources } from './ico.js';
 /**
  * `IMAGE_SUBSYSTEM_WINDOWS_GUI` — the one field this whole file exists to set.
  *
@@ -17,7 +18,24 @@ export interface GuiLauncherInput {
      * Files\<App>` is read-only for the user who runs the app.
      */
     logLeaf: string;
+    /**
+     * The application icon as PE resources, or absent for a launcher with none.
+     *
+     * Absent is what a `kind: 'cli'` project gets; an `app` always has one, and
+     * the layout refuses to stage otherwise (`layout.ts`, `LAYOUTS.windows`), so
+     * "no `.rsrc`" is never how an application quietly loses its icon again.
+     */
+    icon?: IconResources;
 }
+/** `IMAGE_DIRECTORY_ENTRY_RESOURCE` — the data directory slot the `.rsrc` section is named in. */
+export declare const PE_DIRECTORY_RESOURCE = 2;
+/**
+ * The language every resource is filed under: `en-US`, 0x0409, which is what
+ * `rc.exe` and `windres` emit when a script names none. Icon lookup does not
+ * depend on it — `FindResource` falls back through neutral to the first language
+ * present — so one language is enough and it is the conventional one.
+ */
+export declare const RESOURCE_LANGUAGE = 1033;
 /**
  * The GUI-subsystem launcher, as a complete PE32+ image.
  *

package/lib/utils/ship/pe-launcher.js

@@ -51,6 +51,22 @@
 // `objdump -x` (binutils' `pei-x86-64`) and `.github/ship-oracle/verify-program-dir.py`
 // both parse the emitted file, and `tests/e2e/ship-windows` drives the emitted
 // image through the same `readBinaryArch` that reads a real `node.exe`.
+//
+// IT CARRIES THE APP'S ICON, AND THAT IS WHY IT IS THE FILE THE SHORTCUT NAMES.
+// Explorer, the Start menu, the taskbar, Alt-Tab and a pinned entry all read an
+// application's icon out of the EXECUTABLE's resource directory; the running
+// window's own icon comes from GTK at runtime and is the one place the icon
+// showed before this section existed. Measured on Windows 11 against Learn6502
+// 0.8.0: taskbar button iconed, Start-menu entry the generic blank document —
+// the shortcut asked this file, and this file had nothing. So the image gets a
+// third section, `.rsrc`, holding the three-level resource tree Windows expects
+// (type → id → language) with one `RT_GROUP_ICON` naming `n` `RT_ICON` entries
+// (`ico.ts` builds both payloads). Three things in it are silent mistakes and
+// are therefore written down: a data entry's `OffsetToData` is an RVA and not a
+// file offset; directory entries must be SORTED ascending by id, because the
+// loader binary-searches them; and the group's entries name resources by id, not
+// by the file offset an `.ico` carries.
+import { RT_GROUP_ICON, RT_ICON } from './ico.js';
 /**
  * `IMAGE_SUBSYSTEM_WINDOWS_GUI` — the one field this whole file exists to set.
  *
@@ -228,6 +244,88 @@ const CREATE_ALWAYS = 2;
 const FILE_ATTRIBUTE_NORMAL = 0x80;
 /** Capacities in WCHARs. `cmdBuf` holds the whole assembled command line. */
 const BUFFERS = { sysBuf: 264, selfBuf: 520, tmpBuf: 264, logBuf: 600, cmdBuf: 4096 };
+/** `IMAGE_DIRECTORY_ENTRY_RESOURCE` — the data directory slot the `.rsrc` section is named in. */
+export const PE_DIRECTORY_RESOURCE = 2;
+/**
+ * The language every resource is filed under: `en-US`, 0x0409, which is what
+ * `rc.exe` and `windres` emit when a script names none. Icon lookup does not
+ * depend on it — `FindResource` falls back through neutral to the first language
+ * present — so one language is enough and it is the conventional one.
+ */
+export const RESOURCE_LANGUAGE = 0x0409;
+/**
+ * The `.rsrc` section: the resource tree, its data entries, and the payloads.
+ *
+ * ONE FIXED SHAPE, laid out top to bottom so every offset is arithmetic:
+ *
+ *     root directory      2 entries: RT_ICON (3), RT_GROUP_ICON (14) — ascending
+ *     RT_ICON directory   n entries: ids 1..n
+ *     n language dirs     1 entry each: 0x0409 → a data entry
+ *     RT_GROUP_ICON dir   1 entry: id 1
+ *     1 language dir      1 entry: 0x0409 → a data entry
+ *     n + 1 data entries  OffsetToData is an RVA into this section's payloads
+ *     payloads            the n PNGs, then the group, each 8-aligned
+ *
+ * `sectionRva` is what turns a payload's position into the RVA the data entry
+ * needs; every other offset in the tree is relative to the section start, with
+ * the high bit set on an entry that points at a subdirectory. Both conventions
+ * are the format's and both are exercised by `verify-program-dir.py`, which walks
+ * this tree with CPython and reassembles the `.ico`.
+ */
+function buildResourceSection(icon, sectionRva) {
+    const n = icon.icons.length;
+    const DIRECTORY = 16;
+    const ENTRY = 8;
+    const DATA_ENTRY = 16;
+    const SUBDIRECTORY = 0x80000000;
+    const rootAt = 0;
+    const iconDirAt = rootAt + DIRECTORY + 2 * ENTRY;
+    const iconLangAt = (index) => iconDirAt + DIRECTORY + n * ENTRY + index * (DIRECTORY + ENTRY);
+    const groupDirAt = iconLangAt(n);
+    const groupLangAt = groupDirAt + DIRECTORY + ENTRY;
+    const dataEntriesAt = groupLangAt + DIRECTORY + ENTRY;
+    const dataEntryAt = (index) => dataEntriesAt + index * DATA_ENTRY;
+    let payloadAt = align(dataEntryAt(n + 1), 8);
+    const payloads = [];
+    for (const bytes of [...icon.icons, icon.group]) {
+        payloads.push({ at: payloadAt, bytes });
+        payloadAt = align(payloadAt + bytes.length, 8);
+    }
+    const section = Buffer.alloc(payloadAt);
+    const directory = (at, count) => {
+        // Characteristics, TimeDateStamp, Major/MinorVersion: all zero; then the
+        // named-entry count (none here) and the id-entry count.
+        section.writeUInt16LE(0, at + 12);
+        section.writeUInt16LE(count, at + 14);
+    };
+    const entry = (at, id, target, subdirectory) => {
+        section.writeUInt32LE(id, at);
+        section.writeUInt32LE(subdirectory ? (SUBDIRECTORY | target) >>> 0 : target, at + 4);
+    };
+    const dataEntry = (index, payload) => {
+        section.writeUInt32LE(sectionRva + payload.at, dataEntryAt(index)); // an RVA, not a file offset
+        section.writeUInt32LE(payload.bytes.length, dataEntryAt(index) + 4);
+        // CodePage and Reserved stay zero.
+    };
+    directory(rootAt, 2);
+    entry(rootAt + DIRECTORY, RT_ICON, iconDirAt, true);
+    entry(rootAt + DIRECTORY + ENTRY, RT_GROUP_ICON, groupDirAt, true);
+    directory(iconDirAt, n);
+    for (let index = 0; index < n; index++) {
+        entry(iconDirAt + DIRECTORY + index * ENTRY, index + 1, iconLangAt(index), true);
+        directory(iconLangAt(index), 1);
+        entry(iconLangAt(index) + DIRECTORY, RESOURCE_LANGUAGE, dataEntryAt(index), false);
+        dataEntry(index, payloads[index]);
+    }
+    directory(groupDirAt, 1);
+    entry(groupDirAt + DIRECTORY, 1, groupLangAt, true);
+    directory(groupLangAt, 1);
+    entry(groupLangAt + DIRECTORY, RESOURCE_LANGUAGE, dataEntryAt(n), false);
+    dataEntry(n, payloads[n]);
+    for (const payload of payloads)
+        section.set(payload.bytes, payload.at);
+    return new Uint8Array(section);
+}
 /**
  * The stub's instruction stream.
  *
@@ -601,7 +699,18 @@ export function buildGuiLauncher(input) {
     const headerSize = FILE_ALIGNMENT;
     const textOffset = headerSize;
     const dataOffset = textOffset + textRaw;
-    const image = Buffer.alloc(dataOffset + dataRaw);
+    // The icon's section, APPENDED after `.data` so no existing RVA or file
+    // offset moves — inserting it would mean re-resolving every RIP-relative
+    // fixup for a file the code never touches.
+    const rsrcRva = dataRva + align(dataSize, SECTION_ALIGNMENT);
+    const rsrc = input.icon === undefined ? undefined : buildResourceSection(input.icon, rsrcRva);
+    const rsrcRaw = rsrc === undefined ? 0 : align(rsrc.length, FILE_ALIGNMENT);
+    const rsrcOffset = dataOffset + dataRaw;
+    const sectionCount = rsrc === undefined ? 2 : 3;
+    const lastRva = rsrc === undefined
+        ? dataRva + align(dataSize, SECTION_ALIGNMENT)
+        : rsrcRva + align(rsrc.length, SECTION_ALIGNMENT);
+    const image = Buffer.alloc(rsrcOffset + rsrcRaw);
     // ── DOS header ───────────────────────────────────────────────────────────
     image.write('MZ', 0, 'ascii');
     image.write('This program cannot be run in DOS mode.\r\r\n$', 0x40, 'ascii');
@@ -610,7 +719,7 @@ export function buildGuiLauncher(input) {
     image.write('PE\0\0', PE_OFFSET, 'ascii');
     const coff = PE_OFFSET + 4;
     image.writeUInt16LE(MACHINE_AMD64, coff);
-    image.writeUInt16LE(2, coff + 2); // NumberOfSections
+    image.writeUInt16LE(sectionCount, coff + 2); // NumberOfSections
     image.writeUInt32LE(0, coff + 4); // TimeDateStamp — zero, so the image is reproducible
     image.writeUInt16LE(240, coff + 16); // SizeOfOptionalHeader (112 + 16 * 8)
     // EXECUTABLE_IMAGE | LARGE_ADDRESS_AWARE | RELOCS_STRIPPED. The stub is
@@ -622,7 +731,7 @@ export function buildGuiLauncher(input) {
     image.writeUInt16LE(0x20b, opt); // PE32+
     image.writeUInt8(14, opt + 2); // MajorLinkerVersion — cosmetic
     image.writeUInt32LE(textRaw, opt + 4); // SizeOfCode
-    image.writeUInt32LE(dataRaw, opt + 8); // SizeOfInitializedData
+    image.writeUInt32LE(dataRaw + rsrcRaw, opt + 8); // SizeOfInitializedData — `.data` and `.rsrc` are both
     image.writeUInt32LE(textRva, opt + 16); // AddressOfEntryPoint
     image.writeUInt32LE(textRva, opt + 20); // BaseOfCode
     image.writeBigUInt64LE(IMAGE_BASE, opt + 24);
@@ -630,7 +739,7 @@ export function buildGuiLauncher(input) {
     image.writeUInt32LE(FILE_ALIGNMENT, opt + 36);
     image.writeUInt16LE(6, opt + 40); // MajorOperatingSystemVersion
     image.writeUInt16LE(6, opt + 48); // MajorSubsystemVersion
-    image.writeUInt32LE(dataRva + align(dataSize, SECTION_ALIGNMENT), opt + 56); // SizeOfImage
+    image.writeUInt32LE(lastRva, opt + 56); // SizeOfImage — through the last section, whichever that is
     image.writeUInt32LE(headerSize, opt + 60); // SizeOfHeaders
     image.writeUInt16LE(PE_SUBSYSTEM_GUI, opt + 68);
     image.writeUInt16LE(0x0100 | 0x8000, opt + 70); // NX_COMPAT | TERMINAL_SERVER_AWARE
@@ -644,6 +753,12 @@ export function buildGuiLauncher(input) {
     image.writeUInt32LE(40, directories + 1 * 8 + 4);
     image.writeUInt32LE(rvaOf('iat.GetModuleFileNameW'), directories + 12 * 8); // IAT
     image.writeUInt32LE((IMPORTS.length + 1) * 8, directories + 12 * 8 + 4);
+    if (rsrc !== undefined) {
+        // RESOURCE: the whole section, RVA and byte size. Without this slot the
+        // section is bytes the loader maps and the shell never looks at.
+        image.writeUInt32LE(rsrcRva, directories + PE_DIRECTORY_RESOURCE * 8);
+        image.writeUInt32LE(rsrc.length, directories + PE_DIRECTORY_RESOURCE * 8 + 4);
+    }
     // ── section table ────────────────────────────────────────────────────────
     const sections = directories + 16 * 8;
     const writeSection = (index, name, rva, virtualSize, raw, rawSize, characteristics) => {
@@ -657,7 +772,13 @@ export function buildGuiLauncher(input) {
     };
     writeSection(0, '.text', textRva, codeSize, textOffset, textRaw, 0x60000020);
     writeSection(1, '.data', dataRva, dataSize, dataOffset, dataRaw, 0xc0000040);
+    // INITIALIZED_DATA | MEM_READ and nothing else: resources are read by the
+    // shell and the loader, never written and never executed.
+    if (rsrc !== undefined)
+        writeSection(2, '.rsrc', rsrcRva, rsrc.length, rsrcOffset, rsrcRaw, 0x40000040);
     image.set(text, textOffset);
     image.set(data, dataOffset);
+    if (rsrc !== undefined)
+        image.set(rsrc, rsrcOffset);
     return new Uint8Array(image);
 }

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

@@ -66,40 +66,7 @@ export declare function planOverlay(settings: ShipSettings, format: FormatDescri
  * version can no longer reach it.
  */
 export declare function assertOverlayIsLicensed(formatId: FormatId, binaryName: string, overlay: readonly StagedFile[]): void;
-/**
- * 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;
+export { iconThemeDir, isSymbolicIcon } from './icons.js';
 /**
  * A native module inside the payload has to keep its executable bit.
  *

package/lib/utils/ship/plan.js

@@ -4,6 +4,7 @@
 // its own inputs can only be tested by building a real project.
 import { renderDebianChangelog } from './changelog.js';
 import { gzipDeterministic, POLICY_MAX_COMPRESSION } from './gzip.js';
+import { iconThemeDir, isSymbolicIcon } from './icons.js';
 import { renderMimePackage } from './mime.js';
 import { SHARE } from './share-dirs.js';
 import { basename, extname, posix } from 'node:path';
@@ -267,62 +268,12 @@ function planIcons(settings) {
     }
     return out;
 }
-/**
- * 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 function isSymbolicIcon(iconPath) {
-    if (extname(iconPath).toLowerCase() !== '.svg')
-        return false;
-    if (/(?:^|[\\/])symbolic[\\/]/.test(iconPath))
-        return true;
-    return basename(iconPath, extname(iconPath)).endsWith('-symbolic');
-}
-/**
- * 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 function iconThemeDir(iconPath) {
-    if (isSymbolicIcon(iconPath))
-        return 'symbolic';
-    if (extname(iconPath).toLowerCase() === '.svg')
-        return 'scalable';
-    const square = /(?:^|[\\/])(\d{1,4})x\1(?:[\\/]|$)/.exec(iconPath);
-    if (square)
-        return `${square[1]}x${square[1]}`;
-    const tokens = basename(iconPath, extname(iconPath)).split(/[-_.]/);
-    for (let i = tokens.length - 1; i >= 0; i--) {
-        const token = tokens[i];
-        if (token !== undefined && /^\d{1,4}$/.test(token))
-            return `${token}x${token}`;
-    }
-    throw new Error(`gjsify ship: cannot tell what size ${iconPath} is. ` +
-        'Put it in a `<size>x<size>/` directory, end its name with the size (`icon-128.png`), or ship an SVG.');
-}
+// The two icon questions the plan asks — symbolic or sized, and which theme
+// directory — are answered by `icons.ts` since the icon became a CONVERTED
+// artifact on two of the three layouts, and re-exported here so the plan's
+// readers keep one import. One definition: a copy here would be the one that
+// stages `symbolic/` under a size the day the other changes.
+export { iconThemeDir, isSymbolicIcon } from './icons.js';
 /** A staged path must stay under the prefix — no absolute paths, no `..`. */
 function assertInsidePrefix(dest) {
     const normalised = posix.normalize(dest);