@gjsify/cli 0.45.0 → 0.46.0

package/lib/utils/ship/discover.js

@@ -8,6 +8,30 @@ import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { dirname, isAbsolute, join, posix, relative, resolve, sep } from 'node:path';
 import { LICENSE_FILE_NAMES } from './settings.js';
 const ICON_EXTENSIONS = ['.svg', '.png'];
+/**
+ * The face formats every FreeType opens, with no build option deciding it.
+ *
+ * TrueType, OpenType and their collections. Deliberately short: the point of the
+ * set is that a file in it resolves inside the app's OWN runtime closure as well
+ * as it does on the machine that packaged it.
+ */
+const FONT_EXTENSIONS = ['.ttf', '.otf', '.ttc', '.otc'];
+/**
+ * Web-font wrappers, refused BY NAME rather than filtered away.
+ *
+ * They are the mistake worth a diagnostic. An `OFL.txt` beside the faces is
+ * ignored the way a stray file in an icon directory is; a `.woff2` is a font
+ * somebody put there on purpose, and dropping it silently costs the same as
+ * staging it — the app ships without the family and Pango substitutes, at exit 0.
+ *
+ * Measured in BOTH directions, which is why this is a refusal rather than a
+ * warning: `fc-query` reads a `.woff2`'s family fine on Fedora 44 (fontconfig
+ * 2.17.0, FreeType built with brotli), and that support is
+ * `FT_CONFIG_OPTION_USE_BROTLI` — a property of whichever FreeType the shipped
+ * artifact loads, which for a `.app` or a Windows program directory is the one
+ * inside `@gjsify/gtk-runtime-<target>` and not this host's.
+ */
+const WEB_FONT_EXTENSIONS = ['.woff', '.woff2', '.eot'];
 export function discoverPayload(input) {
     const { projectDir, ship } = input;
     const bundlePath = resolveBundle(input);
@@ -29,6 +53,7 @@ export function discoverPayload(input) {
         schemaFiles: discoverSchemas(projectDir, ship.schemas),
         typelibFiles: discoverTypelibs(projectDir, ship.bundledTypelibs),
         localeFiles,
+        fontFiles: discoverFonts(projectDir, ship.fonts),
         licenseFile: discoverLicense(projectDir, ship.licenseFile),
     };
 }
@@ -186,6 +211,66 @@ function listIcons(dir) {
         .map((rel) => join(dir, rel.split('/').join(sep)))
         .sort();
 }
+/**
+ * Font faces the application SHIPS (`gjsify.ship.fonts`), or the GNOME-shaped
+ * default `data/fonts` when it exists.
+ *
+ * A FILE or a DIRECTORY, like `icon`, and a directory is walked rather than
+ * globbed because a family arrives as several faces and often with its licence
+ * beside them.
+ *
+ * The refusals are the interesting half, and both cover the same failure: a font
+ * that installs and is never found. Pango does not report a missing family — it
+ * substitutes, so the app renders in the wrong typeface with no error, no exit
+ * code and nothing for CI to see. That is why a configured path holding no usable
+ * face fails here rather than staging an empty directory, and why a web-font
+ * wrapper is named rather than filtered (see {@link WEB_FONT_EXTENSIONS}).
+ */
+function discoverFonts(projectDir, configured) {
+    const declared = configured ?? 'data/fonts';
+    const root = configured === undefined ? join(projectDir, 'data', 'fonts') : resolve(projectDir, configured);
+    if (!existsSync(root)) {
+        if (configured === undefined)
+            return [];
+        throw new Error(`gjsify ship: the configured font path ${configured} does not exist.`);
+    }
+    if (!statSync(root).isDirectory()) {
+        assertNotWebFont(root, declared);
+        if (!FONT_EXTENSIONS.some((ext) => root.toLowerCase().endsWith(ext))) {
+            throw new Error(`gjsify ship: \`gjsify.ship.fonts\` names ${configured}, which is not a font face ` +
+                `fontconfig will open (${FONT_EXTENSIONS.join(', ')}). ` +
+                'A file it cannot read installs and is never found, and Pango substitutes a fallback ' +
+                'family rather than reporting anything.');
+        }
+        return [root];
+    }
+    const out = [];
+    for (const rel of listFilesRecursive(root)) {
+        assertNotWebFont(rel, declared);
+        if (FONT_EXTENSIONS.some((ext) => rel.toLowerCase().endsWith(ext))) {
+            out.push(join(root, rel.split('/').join(sep)));
+        }
+    }
+    if (out.length === 0 && configured !== undefined) {
+        throw new Error(`gjsify ship: \`gjsify.ship.fonts\` (${configured}) holds no font face ` +
+            `(${FONT_EXTENSIONS.join(', ')}). Declaring fonts that ship nothing is a promise the ` +
+            'package does not keep — and its symptom is a substituted family, not an error.');
+    }
+    return out.sort();
+}
+/** A `.woff`/`.woff2`/`.eot` is named, never dropped — {@link WEB_FONT_EXTENSIONS} carries the reason. */
+function assertNotWebFont(path, where) {
+    const lower = path.toLowerCase();
+    const wrapper = WEB_FONT_EXTENSIONS.find((ext) => lower.endsWith(ext));
+    if (wrapper === undefined)
+        return;
+    throw new Error(`gjsify ship: \`gjsify.ship.fonts\` (${where}) carries ${path}, and \`${wrapper}\` is a web-font ` +
+        'wrapper whose support is a FreeType BUILD option — brotli for woff2, zlib for woff. Whether it ' +
+        'opens is therefore a property of the FreeType the SHIPPED artifact loads (inside ' +
+        '`@gjsify/gtk-runtime-<target>` for a `.app` or a Windows program directory), not of the machine ' +
+        `that packaged it. Ship the desktop face instead (${FONT_EXTENSIONS.join(', ')}); a font that ` +
+        'fails to open is not an error, it is Pango quietly substituting a different typeface.');
+}
 function discoverSchemas(projectDir, configured) {
     const roots = configured !== undefined ? [resolve(projectDir, configured)] : [join(projectDir, 'data')];
     for (const root of roots) {

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

@@ -116,3 +116,26 @@ export declare function configuredFormats(raw: readonly string[], layout: Layout
     formats: FormatDescriptor[];
     dropped: FormatId[];
 };
+/**
+ * Can this format's container hold a notarisation ticket?
+ *
+ * A SWITCH WITH A `never` GUARD and not a field, deliberately — the difference
+ * from `FormatDescriptor.host` is who owns the fact. Where a format can be PACKED
+ * is a property of this project's toolchain and belongs on the descriptor; whether
+ * `stapler` will write a ticket into it is Apple's list, unchanged by anything
+ * here, and six of the nine rows are only "no" because notarisation is a macOS
+ * concept they have nothing to do with. Putting it in a `switch` keeps the answer
+ * beside its citation and still makes a tenth format a compile error.
+ *
+ * `stapler(1)`: *"stapler works only with UDIF disk images, signed \"flat\"
+ * installer packages, and certain code-signed executable bundles such as
+ * \".app\"."* And Apple's notarisation guide for the exception that decides the
+ * zip: *"While you can notarize a ZIP archive, you can't staple to it directly.
+ * Instead, run stapler against each item that you added to the archive. Then
+ * create a new ZIP file containing the stapled items for distribution."*
+ *
+ * `macos-app` is `true` here even though `notarytool` cannot SUBMIT a directory:
+ * the two questions are separate, and a `.app` is precisely the item Apple's
+ * remedy above tells you to staple after submitting the archive around it.
+ */
+export declare function canCarryTicket(id: FormatId): boolean;

package/lib/utils/ship/formats.js

@@ -947,3 +947,47 @@ export function configuredFormats(raw, layout) {
         dropped: named.filter((name) => FORMATS[name].layoutOs !== layout.os),
     };
 }
+/**
+ * Can this format's container hold a notarisation ticket?
+ *
+ * A SWITCH WITH A `never` GUARD and not a field, deliberately — the difference
+ * from `FormatDescriptor.host` is who owns the fact. Where a format can be PACKED
+ * is a property of this project's toolchain and belongs on the descriptor; whether
+ * `stapler` will write a ticket into it is Apple's list, unchanged by anything
+ * here, and six of the nine rows are only "no" because notarisation is a macOS
+ * concept they have nothing to do with. Putting it in a `switch` keeps the answer
+ * beside its citation and still makes a tenth format a compile error.
+ *
+ * `stapler(1)`: *"stapler works only with UDIF disk images, signed \"flat\"
+ * installer packages, and certain code-signed executable bundles such as
+ * \".app\"."* And Apple's notarisation guide for the exception that decides the
+ * zip: *"While you can notarize a ZIP archive, you can't staple to it directly.
+ * Instead, run stapler against each item that you added to the archive. Then
+ * create a new ZIP file containing the stapled items for distribution."*
+ *
+ * `macos-app` is `true` here even though `notarytool` cannot SUBMIT a directory:
+ * the two questions are separate, and a `.app` is precisely the item Apple's
+ * remedy above tells you to staple after submitting the archive around it.
+ */
+export function canCarryTicket(id) {
+    switch (id) {
+        case 'macos-app':
+        case 'macos-app-dmg':
+            return true;
+        case 'macos-app-zip':
+        // Nothing outside darwin has a ticket to carry: `stapler` is Apple's tool
+        // and no other OS pre-clears an artifact at all (§ A5 — Windows SmartScreen
+        // accrues reputation per file hash instead).
+        case 'deb':
+        case 'rpm':
+        case 'flatpak':
+        case 'windows-dir':
+        case 'windows-dir-zip':
+        case 'msi':
+            return false;
+        default: {
+            const unhandled = id;
+            throw new Error(`gjsify ship: no ticket answer for format "${String(unhandled)}".`);
+        }
+    }
+}

package/lib/utils/ship/launcher.js

@@ -25,6 +25,16 @@
 // the tree was installed. Getting that from the launcher rather than from the app
 // keeps the app free of install-layout knowledge.
 //
+// IT ALSO CARRIES THE FONTS, and that reader is not GLib (ADR 0038). fontconfig
+// expands the stock `fonts.conf`'s `<dir prefix="xdg">fonts</dir>` over
+// `XDG_DATA_DIRS` as well as `XDG_DATA_HOME`, so this one export is the whole
+// mechanism behind `gjsify.ship.fonts` outside a `/usr` prefix and is what
+// reaches `/app/share/fonts` in a Flatpak. `fonts-conf(5)` documents only
+// `XDG_DATA_HOME`: the behaviour is NOT re-derivable from the manual, so do not
+// narrow this line to the GLib readers on the strength of what the man page
+// says. Measured across fontconfig 2.14.1 → 2.18.3 — ADR 0038 § What was
+// measured has the versions and the control.
+//
 // THREE FORMS, because neither other OS runs this file. macOS runs a `/bin/sh`
 // script too but cannot use `readlink -f` and must not be handed a `DYLD_*`;
 // Windows runs `cmd.exe`, which shares no syntax with either. What they DO share
@@ -33,6 +43,20 @@
 // dispatch is a `switch` with a `never` guard, the same closed-vocabulary
 // discipline `packOne` uses for the packers.
 import { posix } from 'node:path';
+import { SHARE } from './share-dirs.js';
+/**
+ * `<the layout's data dir>/fonts/<appId>` — the staged face directory (ADR 0038).
+ *
+ * ONE spelling, and the leaf comes off `SHARE.fonts` rather than being typed out,
+ * because all three forms below want a path `planFonts` decides. A literal in each
+ * would keep naming the old directory the day that constant moves, and the suites
+ * would then pass PAST each other rather than fail: the launcher tests read this
+ * string, the payload test reads the plan, and neither can see that the two
+ * disagree.
+ */
+function stagedFontDir(dataDir, appId) {
+    return `${dataDir}/${posix.basename(SHARE.fonts)}/${appId}`;
+}
 /** POSIX-shell single-quote: the only escape inside `'…'` is `'\''`. */
 function shellQuote(value) {
     return `'${value.replace(/'/g, `'\\''`)}'`;
@@ -128,6 +152,15 @@ function renderPrefixLauncher(settings, bundleRelPath, layout) {
     if (settings.localeFiles.length > 0) {
         lines.push(`GJSIFY_LOCALE_DIR="$prefix"/${dirs.data}/locale`, 'export GJSIFY_LOCALE_DIR');
     }
+    // Where the faces landed, handed over for the same reason and in the same
+    // shape as the catalogue directory above (ADR 0038) — and REDUNDANT on this
+    // OS, where fontconfig has already found them through XDG_DATA_DIRS. Exported
+    // anyway, because the one thing a consumer must not have to write is an OS
+    // branch around a path this command chose; `Layout.fontGap` says where the
+    // variable is the mechanism instead of a courtesy.
+    if (settings.fontFiles.length > 0) {
+        lines.push(`GJSIFY_FONT_DIR="$prefix"/${stagedFontDir(dirs.data, settings.appId)}`, 'export GJSIFY_FONT_DIR');
+    }
     lines.push(`exec ${execLine(layout, `"$prefix"/${dirs.bundle}/${bundleRelPath}`, settings)} "$@"`, '');
     return lines.join('\n');
 }
@@ -241,6 +274,15 @@ function renderAppBundleLauncher(settings, bundleRelPath, layout, runtime) {
     if (settings.localeFiles.length > 0) {
         lines.push(`GJSIFY_LOCALE_DIR="$contents/${under(dirs.data)}/locale"`, 'export GJSIFY_LOCALE_DIR');
     }
+    // The face directory, for the same reason as above — and on THIS OS it is
+    // informational rather than the mechanism: `Info.plist`'s
+    // `ATSApplicationFontsPath` has already had macOS activate the same directory
+    // before this script's interpreter started (ADR 0038). Exported all the same,
+    // so a consumer that wants to name a bundled family has one spelling on three
+    // operating systems instead of an OS branch.
+    if (settings.fontFiles.length > 0) {
+        lines.push(`GJSIFY_FONT_DIR="$contents/${stagedFontDir(under(dirs.data), settings.appId)}"`, 'export GJSIFY_FONT_DIR');
+    }
     // `"$here/node"`, not `node`. The bare name is true of a developer's machine
     // and false of a `.app` a stranger downloads, and the difference is not a
     // degraded experience: macOS ships no Node at all, so the launcher's first act
@@ -324,6 +366,16 @@ function renderWindowsLauncher(settings, bundleRelPath, layout, runtime) {
     if (settings.localeFiles.length > 0) {
         lines.push(`set "GJSIFY_LOCALE_DIR=${at(dirs.data)}\\locale"`);
     }
+    // THE ONE OS WHERE THIS VARIABLE IS THE WHOLE HANDOVER (ADR 0038), because
+    // Windows has no declarative font activation at all and the app must call
+    // `PangoCairo.FontMap.get_default().add_font_file()` itself. This line is how
+    // it is told where. Do NOT drop it as redundant with XDG_DATA_DIRS above —
+    // that one reaches no face here. Which three mechanisms look like they would
+    // and do not is `LAYOUTS.windows.fontGap` in `layout.ts`, beside the string
+    // the command prints.
+    if (settings.fontFiles.length > 0) {
+        lines.push(`set "GJSIFY_FONT_DIR=${at(stagedFontDir(dirs.data, settings.appId))}"`);
+    }
     // `"%HERE%node.exe"`, not `node`. The bare name is true of a developer's
     // machine and false of a program directory a stranger unzips: Windows ships no
     // Node at all, so the launcher's first act would be `'node' is not recognized
@@ -364,6 +416,11 @@ function windowsPath(rel) {
  * interpreter that can read the payload is the one the payload was BUILT for,
  * and that is `settings.app` on all three.
  *
+ * Since #1486 `settings.app` is itself resolved per target (`resolveShipApp`), so
+ * "NOT the layout" keeps meaning exactly what it meant: the layout does not DERIVE
+ * the runtime, an author STATES it per OS. Deriving it here would still stage
+ * `exec node` in front of a GJS bundle for everyone who said nothing.
+ *
  * `Layout.runtimeGap` is where the honest half of that lives: it says, per OS,
  * why the staged launcher does not yet name what § 4 derives, and `gjsify ship`
  * prints it.

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

@@ -38,6 +38,17 @@ export interface LayoutMetadataInput extends LayoutIdentity {
     version: string;
     /** Packaging revision within one upstream version — the second half of `CFBundleVersion`. */
     release: string;
+    /**
+     * `process.arch` the payload is LABELLED for — what `--arch` names.
+     *
+     * Here because a layout can own a PROGRAM and not only a manifest, and a
+     * program has an architecture: the windows row emits an x86-64 GUI launcher,
+     * and staging it into a tree labelled `arm64` would make
+     * `assertPayloadMatchesArch` refuse a stage over a file the author never
+     * named. `Layout.arches` already says the windows layout has no other
+     * architecture; this is the same fact where the file is written.
+     */
+    arch: string;
 }
 /** The four places a payload file can belong, as stage-relative directories. */
 export interface LayoutDirs {
@@ -84,7 +95,7 @@ export interface Layout {
      * M1 may honestly claim. A layout with no packer produces no installable
      * artifact, so writing `exec node` into a stage assembled from a `--app gjs`
      * bundle would put a runtime that cannot read the payload in front of it —
-     * the exact defect `assertShippableTarget` exists to prevent, produced by the
+     * the exact defect `resolveShipApp`'s refusal exists to prevent, produced by the
      * code meant to prevent it. Measured before this was data: `gjsify ship
      * darwin --stage` on a project with no `gjsify.app` key exited 0 and staged
      * `exec node "$contents/Resources/lib/gjs.js"` in front of a bundle whose
@@ -100,6 +111,28 @@ export interface Layout {
      * know, and it is the same fact that retires this field when M0 lands.
      */
     runtimeGap?: string;
+    /**
+     * Why a face in the payload's `share/fonts` may not be REACHED on this OS, or
+     * absent where nothing stands in its way.
+     *
+     * Optional, mirroring {@link runtimeGap} rather than {@link metadata}'s
+     * required-and-empty shape, because it asks the same kind of question: is there
+     * something true about this OS that the staged tree cannot show? Linux answers
+     * by having none.
+     *
+     * THE GAP IS NOT THE PATH (ADR 0038). The faces are STAGED identically on all
+     * three layouts and `planStage` emits one plan for them; what differs is what
+     * READS the directory. On Linux fontconfig does, expanding
+     * `<dir prefix="xdg">fonts</dir>` over the `XDG_DATA_DIRS` every launcher
+     * already exports — measured in eight independent fontconfigs — so that row has
+     * nothing to report. On the other two the reader is a property of
+     * `@gjsify/gtk-runtime-<target>` rather than of this payload, and it is not
+     * fontconfig in either: CoreText on macOS, DirectWrite on Windows, the latter
+     * measured on hardware (`LAYOUTS.windows.fontGap` carries the numbers).
+     * `gjsify ship` prints this only when the payload actually carries a face, so a
+     * project shipping none is told nothing.
+     */
+    fontGap?: string;
     /** Suffix the launcher's filename carries, `''` where the OS needs none. */
     launcherExt: string;
     /**
@@ -136,8 +169,17 @@ export interface Layout {
      * The result is placed by `placeStage`, which applies the SAME uniqueness check
      * it applies to mapped files: an `extraFiles` destination that lands on
      * `Contents/Info.plist` is refused rather than silently replacing it.
+     *
+     * IT TAKES THE PAYLOAD, in the prefix-relative shape, because a manifest is a
+     * statement ABOUT a tree and one key already has to be (ADR 0038):
+     * `ATSApplicationFontsPath` names the directory the bundle's faces are in, and
+     * emitting it over a bundle that carries none would point macOS at a path that
+     * is not there. That is also the seam `CFBundleDocumentTypes` will need, which
+     * is ADR 0024 stages 4 and 5 — so the parameter is the payload rather than a
+     * `hasFonts` flag: the next key to need it will need a different question
+     * answered about the same tree.
      */
-    metadata: (input: LayoutMetadataInput) => StagedFile[];
+    metadata: (input: LayoutMetadataInput, payload: readonly StagedFile[]) => StagedFile[];
     /**
      * The `process.arch` values this layout can be assembled for, or `null` when
      * it imposes no limit of its own.
@@ -182,6 +224,26 @@ export declare const LAYOUTS: Record<LayoutName, Layout>;
 export declare const LAYOUT_NAMES: LayoutName[];
 /** Stage-relative path of the launcher this layout puts in front of the app. */
 export declare function launcherPath(layout: Layout, identity: LayoutIdentity): string;
+/**
+ * Stage-relative path of the windows layout's GUI launcher.
+ *
+ * IT MUST BE `<launcherPath minus `.cmd`>.exe` AND THE STUB DEPENDS ON IT:
+ * `buildGuiLauncher` finds its `.cmd` by overwriting the last three characters of
+ * its own module filename, which is a three-character store instead of a path
+ * search only because the two names differ in exactly those bytes. Deriving both
+ * from `LAYOUTS.windows.launcherExt` here is what keeps that true — renaming the
+ * batch launcher to `.bat` would otherwise leave a stub looking for a file that
+ * is not there, at exit 0, with a window that never appears.
+ */
+export declare function windowsGuiLauncherPath(identity: LayoutIdentity): string;
+/**
+ * What the windows GUI launcher calls the file it writes under `%TEMP%`.
+ *
+ * Named after the binary rather than the display name: `%TEMP%` is shared by
+ * every application on the machine, and `binaryName` is the one identifier this
+ * project already refuses to let collide.
+ */
+export declare function windowsLaunchLogLeaf(identity: LayoutIdentity): string;
 /**
  * The layout for one `process.platform` token, refusing every alias.
  *

package/lib/utils/ship/layout.js

@@ -21,7 +21,9 @@
 // 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 { buildGuiLauncher } from './pe-launcher.js';
 import { BUNDLE_INFO_PLIST, BUNDLE_PKGINFO, renderInfoPlist, renderPkgInfo } from './plist.js';
+import { SHARE } from './share-dirs.js';
 /**
  * Characters a `<App>.app` directory name may not contain.
  *
@@ -31,6 +33,27 @@ import { BUNDLE_INFO_PLIST, BUNDLE_PKGINFO, renderInfoPlist, renderPkgInfo } fro
  * `hdiutil` time, which is three milestones away and on another host.
  */
 const BUNDLE_NAME_FORBIDDEN = /[/:\\]/;
+/**
+ * The value `ATSApplicationFontsPath` takes for this bundle, or nothing when the
+ * payload carries no face (ADR 0038).
+ *
+ * DERIVED THROUGH `place()`, over a file the payload actually holds, rather than
+ * written out as `share/fonts/<appId>`. The key is documented as a path relative
+ * to `Contents/Resources`, which is this layout's `dirs.other` — so running the
+ * real map on a real entry and taking the Resources prefix back off is the one
+ * spelling that cannot come apart from where the faces were staged. A literal
+ * would keep pointing at the old directory the day `dirs` changes, and macOS
+ * reports an empty font directory the way it reports everything else here: not at
+ * all.
+ */
+function darwinFontsPath(identity, payload) {
+    const dir = `${SHARE.fonts}/${identity.appId}`;
+    const face = payload.find((file) => file.path.startsWith(`${dir}/`));
+    if (face === undefined)
+        return undefined;
+    const dirs = LAYOUTS.darwin.dirs(identity);
+    return posix.relative(dirs.other, posix.dirname(place(LAYOUTS.darwin, identity, face.path)));
+}
 function appBundleDir(identity) {
     if (BUNDLE_NAME_FORBIDDEN.test(identity.name)) {
         throw new Error(`gjsify ship: the macOS layout would put this app in "${identity.name}.app", and a bundle ` +
@@ -79,6 +102,30 @@ 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`
+        // 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
+        // GTK-side fontconfig. `XDG_DATA_DIRS` still carries the icons and the schemas
+        // here; 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
+        // beats a runtime call rather than merely being tidier:
+        // `pango_core_text_font_map_changed()` only bumps a serial, there is no
+        // `kCTFontManagerRegisteredFontsChangedNotification` observer and no re-scan
+        // 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.
+        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.',
         launcherExt: '',
         root: appBundleDir,
         // Apple's, all four. `Contents/MacOS` holds executables, `Contents/Resources`
@@ -99,11 +146,11 @@ 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) => [
+        metadata: (input, payload) => [
             {
                 path: `${appBundleDir(input)}/${BUNDLE_INFO_PLIST}`,
                 mode: 0o644,
-                source: { kind: 'text', text: renderInfoPlist(input) },
+                source: { kind: 'text', text: renderInfoPlist(input, darwinFontsPath(input, payload)) },
             },
             {
                 path: `${appBundleDir(input)}/${BUNDLE_PKGINFO}`,
@@ -137,6 +184,55 @@ export const LAYOUTS = {
             'cannot assume — Windows ships neither, and there is NO GJS host on Windows at all ' +
             '(ADR 0024 § 4), so § 4 derives Node here. A self-contained directory needs ' +
             '`@gjsify/node-runtime-win32-x64` and a `--app node` payload (#1354 M3).',
+        // THE ONE LAYOUT WITH NO DECLARATIVE ANSWER AT ALL, and the three obvious
+        // candidates are each dead for a different reason — written down because each
+        // one looks right until it is read. The first is now dead by MEASUREMENT
+        // rather than by reading (ADR 0038 § W1-W3, Windows 11 / GTK 4.22.4).
+        //
+        //  * FONTCONFIG. gvsbuild does build it and pango links it
+        //    (`-Dfontconfig=enabled`), but `pangocairo-fontmap.c` picks the first
+        //    backend COMPILED IN, in the order coretext → win32 → fc, and cairo's
+        //    meson adds `cairo-win32` unconditionally on a Windows host. So the fc
+        //    font map is built and never selected, and the whole `etc/fonts` +
+        //    `FONTCONFIG_PATH` arrangement `@gjsify/gtk-runtime-win32-x64` ships is
+        //    inert. `APPSHAREFONTDIR` even resolves to exactly this layout
+        //    (`<exe dir>\..\share\fonts`) and feeds the map nothing reads. RUN: with
+        //    a `FONTCONFIG_FILE` naming the face's directory beside WINDOWSFONTDIR
+        //    the default map stays at 82 families without it — and stays at 82 when
+        //    that directory is the ONLY one configured, which is the row that shows
+        //    the map is not reading a misconfigured fontconfig but no fontconfig.
+        //    The control that makes that a finding: a `PangoFT2.FontMap` from the
+        //    SAME config in the SAME process goes 76 → 77 WITH the face, and to 5
+        //    families exclusively. The bundle also ships no `fc-cache.exe`.
+        //  * XDG_DATA_DIRS, which carries the faces on Linux. `FcConfigXdgDataDirs()`
+        //    splits on a HARDCODED colon (its own comment says the spec asks for one),
+        //    while `FC_SEARCH_PATH_SEPARATOR` is `;` here — so `C:\App\share` splits
+        //    into `C` and `\App\share`. The Linux measurement does not carry over.
+        //  * `AddFontResourceEx(..., FR_PRIVATE)`. It registers with GDI, and
+        //    `pango_win32_font_map_init()` has exactly one population call —
+        //    `pango_win32_dwrite_font_map_populate()` — with no `EnumFontFamilies` and
+        //    no `AddFontResource` anywhere in the backend. A GDI-private font cannot
+        //    reach GTK4 text.
+        //
+        // What is left is a runtime call, which a packaging command has no business
+        // making inside somebody's application — so the launcher hands over the
+        // directory (`GJSIFY_FONT_DIR`) and this string names the call. That the call
+        // WORKS is measured too, and on GTK's own map rather than a loose Pango
+        // object: `label.get_pango_context().get_font_map()` IS the default map
+        // there, `add_font_file` on it answers true, families go 82 → 83 and the
+        // family then loads. With the discriminator that keeps "resolved" honest — an
+        // invented family renders as Tahoma at different metrics with a Pango
+        // 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 ' +
+            '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 ' +
+            'Gtk.Label renders through does register the family. So register them at startup: ' +
+            '`PangoCairo.FontMap.get_default().add_font_file(path)` (Pango 1.56+, in the typelib), or the ' +
+            'app renders in a substituted family with no error.',
         // `.cmd`, not `.bat`: the two differ in whether a failing built-in (`set`,
         // `path`, `append`) sets ERRORLEVEL, and `.cmd` is the one where it does.
         launcherExt: '.cmd',
@@ -146,15 +242,41 @@ export const LAYOUTS = {
         // has no rpath — a DLL is found on `PATH`, in the directory of the image
         // that loaded it, or not at all.
         dirs: () => ({ launcher: '', bundle: 'app', native: 'lib', data: 'share', other: '' }),
-        // Nothing, and this is the row that shows the field is not a macOS detail
-        // wearing a general name: a Windows installer's metadata lives in the
-        // `.msi`'s own tables, not in a file inside the program directory. THREE
-        // format rows wrap this layout now, and the installer — the one that could
-        // have needed a file here — did not: `msi.ts` puts every such fact in the
-        // `Product`/`Package` attributes of the document it renders. So the answer
-        // held rather than the question going unasked, and if a fourth row ever
-        // needs a file, THIS is where it goes — not a branch in the stager.
-        metadata: () => [],
+        // NO METADATA, and one PROGRAM. A Windows installer's metadata lives in the
+        // `.msi`'s own tables, not in a file inside the program directory —
+        // `msi.ts` puts every such fact in the `Product`/`Package` attributes of the
+        // document it renders — so this row still owns no manifest, and the field is
+        // not a macOS detail wearing a general name.
+        //
+        // What it DOES own is the GUI-subsystem launcher beside the `.cmd`, and it
+        // arrives through this seam rather than through a branch in the stager,
+        // which is exactly what the field's contract says a fourth row should do.
+        //
+        // A SECOND LAUNCHER, NOT A REPLACEMENT. The `.cmd` makes every environment
+        // decision, is what `assertLauncherMatchesInterpreter` and
+        // `.github/ship-oracle/verify-program-dir.py` read back, and is the right
+        // entry point in a terminal. The `.exe` is the entry point for a
+        // double-click and for the shortcut an `.msi` writes — the two launches
+        // Windows gives a console window today, because `cmd.exe` is a
+        // console-subsystem image (ADR 0024 § M3). It RUNS the `.cmd`.
+        //
+        // AND ONLY FOR THE ARCHITECTURE IT IS. The stub is x86-64 machine code, so
+        // staging it into a tree labelled `arm64` would have
+        // `assertPayloadMatchesArch` refuse the STAGE over a file the author never
+        // named — turning "this layout has no arm64 runtime" (a warning, with
+        // `Layout.arches.why` to act on) into "your payload is mislabelled" (a
+        // 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) }) },
+                },
+            ]
+            : [],
         // 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
@@ -185,6 +307,36 @@ const BY_OS = new Map(LAYOUT_NAMES.map((name) => [LAYOUTS[name].os, LAYOUTS[name
 export function launcherPath(layout, identity) {
     return posix.join(layout.dirs(identity).launcher, `${identity.binaryName}${layout.launcherExt}`);
 }
+/**
+ * Stage-relative path of the windows layout's GUI launcher.
+ *
+ * IT MUST BE `<launcherPath minus `.cmd`>.exe` AND THE STUB DEPENDS ON IT:
+ * `buildGuiLauncher` finds its `.cmd` by overwriting the last three characters of
+ * its own module filename, which is a three-character store instead of a path
+ * search only because the two names differ in exactly those bytes. Deriving both
+ * from `LAYOUTS.windows.launcherExt` here is what keeps that true — renaming the
+ * batch launcher to `.bat` would otherwise leave a stub looking for a file that
+ * is not there, at exit 0, with a window that never appears.
+ */
+export function windowsGuiLauncherPath(identity) {
+    const layout = LAYOUTS.windows;
+    if (layout.launcherExt.length !== 4) {
+        throw new Error(`gjsify ship: the windows launcher extension is "${layout.launcherExt}" and the GUI stub can only ` +
+            'reach a four-character one — it rewrites the last three characters of its own filename rather ' +
+            'than searching for a path (`utils/ship/pe-launcher.ts`).');
+    }
+    return posix.join(layout.dirs(identity).launcher, `${identity.binaryName}.exe`);
+}
+/**
+ * What the windows GUI launcher calls the file it writes under `%TEMP%`.
+ *
+ * Named after the binary rather than the display name: `%TEMP%` is shared by
+ * every application on the machine, and `binaryName` is the one identifier this
+ * project already refuses to let collide.
+ */
+export function windowsLaunchLogLeaf(identity) {
+    return `${identity.binaryName}.launch.log`;
+}
 /**
  * The layout for one `process.platform` token, refusing every alias.
  *
@@ -339,8 +491,9 @@ export function placeStage(layout, identity, files, carried = []) {
     // prefix-relative plan, so there is nothing to map. `<layout> metadata` rather
     // than a path as the origin label, because a collision message naming
     // `Contents/Info.plist` as both sides would say nothing.
-    for (const file of layout.metadata(identity))
+    for (const file of layout.metadata(identity, files)) {
         claim(file.path, `the ${layout.name} layout's own metadata`, file);
+    }
     // A THIRD source, and stage-relative like the second: the runtime the bundle
     // CARRIES (`utils/ship/app-runtime.ts`). It goes through `claim` for the reason
     // the metadata does — an `extraFiles` destination landing on a staged dylib