@gjsify/cli 0.45.0 → 0.47.0

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,32 @@ 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. 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.',
         launcherExt: '',
         root: appBundleDir,
         // Apple's, all four. `Contents/MacOS` holds executables, `Contents/Resources`
@@ -99,11 +148,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 +186,57 @@ 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, with one call ' +
+            "from the GTK host layer: `import { initFonts } from '@gjsify/gtk-host/fonts'`, then `initFonts()` " +
+            'before the first window — it reads GJSIFY_FONT_DIR itself, registers every face it holds, and ' +
+            'no-ops on the operating systems that already activated them. Without it 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 +246,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 +311,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 +495,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

package/lib/utils/ship/msi.js

@@ -21,7 +21,8 @@
 //   * lays the program directory `windows-dir` produces under
 //     `%ProgramFiles%\<App>`, overridable with `msiexec INSTALLDIR=…`;
 //   * gives the user something to start — one Start-Menu shortcut at the top
-//     level, aimed at the same `.cmd` launcher the zip's user double-clicks;
+//     level, aimed at the GUI-subsystem `.exe` launcher the zip's user
+//     double-clicks (see the last paragraph of this header);
 //   * comes off again: Add/Remove Programs gets its entry from the MSI's own
 //     `ProductName`/`ProductVersion`/`Manufacturer`, and `msiexec /x` removes
 //     every file the package installed. The `windows-dir-selfcontained` leg's
@@ -57,15 +58,20 @@
 //      bought for nothing. A directory whose id is a public property is settable
 //      from a command line either way.
 //
-// AND ONE THING IT DOES NOT FIX. `node.exe` is a CONSOLE-subsystem image and the
-// Node release ships no `nodew.exe` (`status/open-todos.md` carries the offsets),
-// so the shortcut this installer writes pops a console window behind the GUI
-// exactly as the `.cmd` does. Nothing here changes that, and no leg can observe
-// it — every Windows CI leg starts the app from a shell and already has one.
+// AND ONE THING IT USED NOT TO FIX. `node.exe` is a CONSOLE-subsystem image and
+// the Node release ships no `nodew.exe`, so a Start-Menu shortcut to the `.cmd`
+// popped a console window behind the GUI exactly as a double-click did. The
+// shortcut now points at the GUI-subsystem launcher the windows LAYOUT stages
+// (`utils/ship/pe-launcher.ts`), which runs the same `.cmd` with no window —
+// measured on `win11-gjsify` in session 1, where the `.cmd` produces two new
+// visible console-host windows and the `.exe` produces none. Still no CI leg can
+// observe it: every Windows job starts the app from a shell and already has a
+// console.
 import { createHash } from 'node:crypto';
 import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { join, posix } from 'node:path';
 import { describeExit, spawnToCompletion } from '../spawn.js';
+import { windowsGuiLauncherPath } from './layout.js';
 import { xmlEscape } from './xml.js';
 /**
  * The UUID namespace every GUID in a generated `.msi` is derived under.
@@ -236,7 +242,18 @@ export function renderWxs(input) {
     // `Name <email>` is `PackSettings.maintainer`'s shape; ARP shows `Publisher`
     // to a human, and an address in that field reads as a mistake.
     const manufacturer = settings.maintainer.replace(/\s*<[^>]*>\s*$/, '').trim() || settings.maintainer;
-    const launcher = `${settings.binaryName}.cmd`;
+    // THE SHORTCUT POINTS AT THE `.exe`, NOT THE `.cmd` — this installer's half of
+    // the console-window fix. A Start-Menu shortcut to a batch file starts
+    // `cmd.exe`, a console-subsystem image, so Windows allocates a console for it
+    // and a black window sits behind the app (ADR 0024 § M3). The GUI-subsystem
+    // launcher beside it — `utils/ship/pe-launcher.ts`, staged by the windows
+    // LAYOUT — runs the same `.cmd` and has no window of its own.
+    //
+    // Derived from `windowsGuiLauncherPath` and never spelled again here: the stub
+    // finds its `.cmd` by rewriting the last three characters of its own filename,
+    // so the two names are ONE decision, and a second literal is where they would
+    // come apart.
+    const launcher = windowsGuiLauncherPath(settings);
     const identifiers = new Map();
     const claim = (id, what) => {
         const previous = identifiers.get(id);

package/lib/utils/ship/payload.js

@@ -440,7 +440,15 @@ export function assertLauncherMatchesInterpreter(payload, layout, identity, inte
         '    An installed package that depends on one interpreter and runs another installs cleanly and ' +
         'fails\n' +
         "    at first launch, on the user's machine.\n" +
-        `    Either set \`gjsify.app\` to "${other}", or fix the launcher — if it comes from ` +
+        // THIS TARGET's key, and not `gjsify.app`. Since #1486 the runtime is
+        // resolved per target, so sending the reader to the project field to
+        // fix ONE layout's launcher moves every other layout's `Depends:` with
+        // it — the defect § A22 exists to close, reintroduced by the message
+        // that reports it. Named as a project edit because `--from-stage`
+        // reaches here too, and that host has no config to change.
+        `    Either set \`gjsify.ship.app.${layout.os}\` to "${other}" in the project this was staged ` +
+        'from — it overrides\n' +
+        '    `gjsify.app` for that target alone — or fix the launcher: if it comes from ' +
         '`gjsify.ship.extraFiles`,\n' +
         '    that override is what decides which interpreter runs and it must match the declaration.');
 }
@@ -488,19 +496,30 @@ const SHARE_VERDICTS = [
 /**
  * Paths that survive the trip, so the rule below can be an INVERSE one.
  *
- * Two entries and they are different SHAPES, which is why the check below tests
+ * Three entries and they are different SHAPES, which is why the check below tests
  * both containment and equality:
  *
  *  - `share/locale` is a DIRECTORY. A `.mo` is read straight off disk by
  *    `bindtextdomain`, with no install step anywhere, and the launcher hands the
  *    directory over on all three layouts.
+ *  - `share/fonts` is a directory too, and it is here for a NARROWER reason than
+ *    the one next to it (ADR 0038). What this list means is "no package install
+ *    step makes this correct", and that is true of a face on every layout: nothing
+ *    compiles it, nothing reindexes it, and on Linux fontconfig scans the
+ *    directory and caches lazily per user. What it deliberately does NOT claim is
+ *    that a face is FOUND on the other two — macOS reaches it through
+ *    `Info.plist`'s `ATSApplicationFontsPath` and Windows only through a call the
+ *    app makes itself. Those are `Layout.fontGap`, printed separately, because
+ *    they are facts about an OS rather than about a missing scriptlet, and folding
+ *    them in here would report the answer under a heading that names the wrong
+ *    question.
  *  - `gschemas.compiled` is one FILE, and it is here because it is not a cost —
  *    it is the thing that removes one. Reported under a warning headed "whose
  *    Linux correctness comes from a package install step" it would name the fix
  *    as if it were the problem, and it would be the sixth line of a five-line
  *    list nobody asked to grow.
  */
-const SHARE_PORTABLE = [SHARE.locale, SCHEMA_CACHE];
+const SHARE_PORTABLE = [SHARE.locale, SHARE.fonts, SCHEMA_CACHE];
 /**
  * Every `share/` entry a non-Linux layout carries, classified — including the
  * ones nothing here has a rule for.

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

@@ -0,0 +1,29 @@
+/**
+ * `IMAGE_SUBSYSTEM_WINDOWS_GUI` — the one field this whole file exists to set.
+ *
+ * The counterpart is 3, `_CUI`, which is what `node.exe` and `cmd.exe` are and
+ * what makes Windows allocate a console when there is none to inherit.
+ */
+export declare const PE_SUBSYSTEM_GUI = 2;
+/** Where `Subsystem` lands in the emitted image: `e_lfanew` + 4 + 20 + 68. */
+export declare const PE_SUBSYSTEM_OFFSET: number;
+export interface GuiLauncherInput {
+    /**
+     * The file the stub writes the child's output to under `%TEMP%`, when there
+     * is no console to inherit.
+     *
+     * A LEAF and not a path: `%TEMP%` is the one directory a program can write to
+     * on every Windows install, and the program directory is not — `C:\Program
+     * Files\<App>` is read-only for the user who runs the app.
+     */
+    logLeaf: string;
+}
+/**
+ * The GUI-subsystem launcher, as a complete PE32+ image.
+ *
+ * Deterministic: the same input always produces the same bytes, with no
+ * timestamp, no checksum and no build-host string anywhere in the file — which
+ * is what lets `tests/e2e/ship-windows` compare two runs and what keeps the
+ * artifact reproducible for anyone who repacks a stage (ADR 0024 § A2).
+ */
+export declare function buildGuiLauncher(input: GuiLauncherInput): Uint8Array;