@gjsify/cli 0.45.0 → 0.46.0

package/lib/utils/ship/plan.js

@@ -93,11 +93,46 @@ export function planStage(settings, inputs) {
             source: { kind: 'file', path: locale.abs },
         });
     }
+    for (const font of planFonts(settings))
+        files.push(font);
     for (const [dest, source] of Object.entries(settings.extraFiles)) {
         files.push({ path: assertInsidePrefix(dest), mode: 0o644, source: { kind: 'file', path: source } });
     }
     return normalise(files);
 }
+/**
+ * Font faces, under a directory named after the app id (ADR 0038).
+ *
+ * `share/fonts` is shared with every other package on a `/usr` prefix, exactly as
+ * `share/glib-2.0/schemas` and `share/mime/packages` are — so the app id is what
+ * keeps a face called `Regular.ttf` from being one of two files claiming the same
+ * path, with install order deciding the winner. Unlike those two the collision is
+ * not refused by NAME: a font's filename is the foundry's and there is no
+ * convention to hold it to, so the directory carries the id and the basenames are
+ * left alone. fontconfig scans recursively, so nesting them costs nothing —
+ * measured across fontconfig 2.14.1 → 2.18.3.
+ *
+ * A basename appearing twice IS refused, for the reason `planIcons` refuses one:
+ * two source files installing as one path means one of them is silently not
+ * shipped, and a missing face is a substituted typeface rather than an error.
+ */
+function planFonts(settings) {
+    const out = [];
+    const seen = new Map();
+    for (const font of settings.fontFiles) {
+        const path = `${SHARE.fonts}/${settings.appId}/${basename(font)}`;
+        const previous = seen.get(path);
+        if (previous !== undefined) {
+            throw new Error(`gjsify ship: ${font} and ${previous} both install as ${path}. ` +
+                'Two faces cannot share one filename — one would silently not ship, and a missing face ' +
+                'is a substituted typeface rather than an error. Rename one, or point ' +
+                '`gjsify.ship.fonts` at a directory holding only the faces you mean to ship.');
+        }
+        seen.set(path, font);
+        out.push({ path, mode: 0o644, source: { kind: 'file', path: font } });
+    }
+    return out;
+}
 /**
  * The per-format additions. Only the licence differs today, and it differs in
  * BOTH place and shape: Debian policy wants a machine-readable `copyright` in

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

@@ -38,8 +38,32 @@ export declare const BUNDLE_PKGINFO = "Contents/PkgInfo";
  * which `flatpak.spec.ts` reds. The unblocker is an independent Linux ICNS reader
  * entering the CI image; until one does, the hicolor PNG/SVG the payload already
  * carries stays the only icon, unread on macOS.
+ *
+ * A TWELFTH KEY, `ATSApplicationFontsPath`, is emitted when the bundle carries
+ * faces, and it is the first one here NOT cited to `refs/` — so the exception is
+ * stated rather than left to be noticed (ADR 0038). The rule this module opens
+ * with exists against DECORATION: the five absent keys are cosmetic, nothing a
+ * reader here can open contains them, and emitting one would be a guess with no
+ * observable behind it. This key is a MECHANISM, and its citation is Apple's own
+ * *Information Property List Key Reference*, which states the scope in the terms
+ * this command needs: *"If present, macOS activates the fonts at the specified
+ * path for use by the bundled app. The fonts are activated only for the bundled
+ * app and not for the system as a whole."* The value is a path relative to
+ * `Contents/Resources`.
+ *
+ * It is also the only route there is. Pango on macOS is CoreText-backed, GTK is
+ * not built against fontconfig on that platform, and
+ * `pango_font_map_add_font_file()` answers `G_IO_ERROR_NOT_SUPPORTED` on the
+ * CoreText map — so the alternatives are this key or a `CTFontManager` call made
+ * from inside somebody else's application, which is not a packaging command's
+ * business.
+ *
+ * WHAT THE ORACLE CAN AND CANNOT SEE: `plistlib` reads the key back like any
+ * other, so the FILE is checked. That macOS activates the directory, and that
+ * Pango's CoreText map then holds the family, is unverified here — which is what
+ * `Layout.fontGap` says out loud rather than letting a green stage imply.
  */
-export declare function renderInfoPlist(input: LayoutMetadataInput): string;
+export declare function renderInfoPlist(input: LayoutMetadataInput, fontsPath?: string): string;
 /**
  * Render `Contents/PkgInfo`: the package type and the signature, eight bytes, no
  * newline.
@@ -56,3 +80,19 @@ export declare function renderInfoPlist(input: LayoutMetadataInput): string;
  * the same reason this function takes none — both values are constants here.
  */
 export declare function renderPkgInfo(): string;
+/**
+ * Render the entitlements plist `codesign --entitlements` takes.
+ *
+ * A SEPARATE FILE FROM `Info.plist` and a separate function, because it is a
+ * different document with a different reader: `Info.plist` describes the bundle
+ * to LaunchServices and ships inside it, while this one is an INPUT to the
+ * signature — `codesign` embeds the claims and the file itself is never staged.
+ *
+ * Every value is `<true/>`. An entitlement of this class is a boolean capability,
+ * and a `<false/>` entry is not "off", it is the same as absent — so a renderer
+ * taking values would offer a spelling with no meaning.
+ *
+ * WHICH KEYS, and why the set is not the reference's, is
+ * `utils/ship/signing.ts`'s decision; this function renders what it is given.
+ */
+export declare function renderEntitlements(keys: readonly string[]): string;

package/lib/utils/ship/plist.js

@@ -147,8 +147,32 @@ function arrayEntry(key, values) {
  * which `flatpak.spec.ts` reds. The unblocker is an independent Linux ICNS reader
  * entering the CI image; until one does, the hicolor PNG/SVG the payload already
  * carries stays the only icon, unread on macOS.
+ *
+ * A TWELFTH KEY, `ATSApplicationFontsPath`, is emitted when the bundle carries
+ * faces, and it is the first one here NOT cited to `refs/` — so the exception is
+ * stated rather than left to be noticed (ADR 0038). The rule this module opens
+ * with exists against DECORATION: the five absent keys are cosmetic, nothing a
+ * reader here can open contains them, and emitting one would be a guess with no
+ * observable behind it. This key is a MECHANISM, and its citation is Apple's own
+ * *Information Property List Key Reference*, which states the scope in the terms
+ * this command needs: *"If present, macOS activates the fonts at the specified
+ * path for use by the bundled app. The fonts are activated only for the bundled
+ * app and not for the system as a whole."* The value is a path relative to
+ * `Contents/Resources`.
+ *
+ * It is also the only route there is. Pango on macOS is CoreText-backed, GTK is
+ * not built against fontconfig on that platform, and
+ * `pango_font_map_add_font_file()` answers `G_IO_ERROR_NOT_SUPPORTED` on the
+ * CoreText map — so the alternatives are this key or a `CTFontManager` call made
+ * from inside somebody else's application, which is not a packaging command's
+ * business.
+ *
+ * WHAT THE ORACLE CAN AND CANNOT SEE: `plistlib` reads the key back like any
+ * other, so the FILE is checked. That macOS activates the directory, and that
+ * Pango's CoreText map then holds the family, is unverified here — which is what
+ * `Layout.fontGap` says out loud rather than letting a green stage imply.
  */
-export function renderInfoPlist(input) {
+export function renderInfoPlist(input, fontsPath) {
     const name = assertPlistText(input.name, 'CFBundleName', 'gjsify.ship.name');
     const executable = assertPlistText(input.binaryName, 'CFBundleExecutable', 'gjsify.ship.binaryName');
     const appId = assertPlistText(input.appId, 'CFBundleIdentifier', 'gjsify.ship.appId');
@@ -162,6 +186,12 @@ export function renderInfoPlist(input) {
         // → ShortVersionString → SupportedPlatforms → Version, and `v8/gni`'s
         // CFBundle keys sort the same way. Matching them keeps a diff against a
         // real bundle readable; no claim is made about what Xcode emits.
+        //
+        // `ATSApplicationFontsPath` sorts before every `CFBundle*` key, which is
+        // where alphabetical order puts it and also where a reader looks for it.
+        // Absent, not empty, when the bundle carries no face: an empty string is a
+        // path, and macOS would activate the Resources directory itself.
+        ...(fontsPath === undefined ? [] : [stringEntry('ATSApplicationFontsPath', fontsPath)]),
         stringEntry('CFBundleDevelopmentRegion', 'en'),
         stringEntry('CFBundleDisplayName', name),
         stringEntry('CFBundleExecutable', executable),
@@ -196,3 +226,31 @@ export function renderInfoPlist(input) {
 export function renderPkgInfo() {
     return `${PACKAGE_TYPE}${SIGNATURE}`;
 }
+/**
+ * Render the entitlements plist `codesign --entitlements` takes.
+ *
+ * A SEPARATE FILE FROM `Info.plist` and a separate function, because it is a
+ * different document with a different reader: `Info.plist` describes the bundle
+ * to LaunchServices and ships inside it, while this one is an INPUT to the
+ * signature — `codesign` embeds the claims and the file itself is never staged.
+ *
+ * Every value is `<true/>`. An entitlement of this class is a boolean capability,
+ * and a `<false/>` entry is not "off", it is the same as absent — so a renderer
+ * taking values would offer a spelling with no meaning.
+ *
+ * WHICH KEYS, and why the set is not the reference's, is
+ * `utils/ship/signing.ts`'s decision; this function renders what it is given.
+ */
+export function renderEntitlements(keys) {
+    const entries = keys.map((key) => `\t<key>${xmlText(key)}</key>\n\t<true/>`).join('\n');
+    return [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+        '<plist version="1.0">',
+        '<dict>',
+        entries,
+        '</dict>',
+        '</plist>',
+        '',
+    ].join('\n');
+}

package/lib/utils/ship/rpm.js

@@ -139,6 +139,13 @@ const SYSTEM_OWNED_DIRECTORIES = new Set([
     // directory the whole system's schemas live in. Verified with `rpm -qf`.
     '/usr/share/glib-2.0',
     `/usr/${SHARE.schemas}`,
+    // Owned by `fonts-filesystem` — measured, `rpm -qf /usr/share/fonts` →
+    // `fonts-filesystem-5.0.0-2.fc44`. DERIVED although it is a PARENT rather than a
+    // directory the planner stages into: `plan.ts` writes `share/fonts/<appId>`,
+    // which this package legitimately owns, and the parent happens to BE
+    // `SHARE.fonts` exactly — so deriving it costs nothing and cannot drift the way
+    // the two literal parents above can.
+    `/usr/${SHARE.fonts}`,
     '/etc',
     '/opt',
     '/var',

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

@@ -1,4 +1,4 @@
-import type { AppMetadata, ConfigDataFlatpak, ConfigDataShip, DescriptionBlock } from '../../types/config-data.js';
+import type { AppMetadata, ConfigDataFlatpak, ConfigDataShip, DescriptionBlock, ShipAppOptions } from '../../types/config-data.js';
 import type { HostOs, ShipSettings } from './types.js';
 /** The subset of `package.json` the resolver reads. */
 export interface ShipPackageManifest {
@@ -34,6 +34,8 @@ export interface DiscoveredPayload {
         rel: string;
         abs: string;
     }[];
+    /** Absolute paths of the font faces the application ships itself. */
+    fontFiles: string[];
     licenseFile?: string;
 }
 export interface SettingsInput {
@@ -59,13 +61,82 @@ export interface SettingsInput {
     };
     discovered: DiscoveredPayload;
     /**
-     * `gjsify.app` as DECLARED — `undefined` when the project declares nothing.
+     * THIS TARGET's runtime, as {@link resolveShipApp} resolved it — never the
+     * raw `gjsify.app`.
      *
-     * Deliberately the raw config value and not `Config.forBuild`'s resolved one:
-     * see where it is defaulted below.
+     * The TYPE is the enforcement: a caller handing the project field straight
+     * through no longer compiles. That is exactly the regression this field used
+     * to carry in silence, since every generator downstream reads `settings.app`.
      */
-    app?: string;
+    app: 'gjs' | 'node';
 }
+/** The runtime one ship target runs, and which key decided it. */
+export interface ResolvedShipApp {
+    /** What the launcher execs, what the package depends on, and which formats can wrap it. */
+    app: 'gjs' | 'node';
+    /** The config key the answer came from — named in the refusal and in the notice. */
+    key: string;
+    /** Whether a per-target key overrode the project default. */
+    overridden: boolean;
+}
+/**
+ * The ONE place a ship target's runtime is decided: `gjsify.app` as the DEFAULT,
+ * `gjsify.ship.app.<os>` as this target's override.
+ *
+ * WHY IT IS PER TARGET, measured on a GTK4 application rather than derived from
+ * the schema: with one field, `gjsify ship darwin` refused its formats until
+ * `gjsify.app` was `"node"` — and setting it turned the LINUX `.deb`'s
+ * `Depends: gjs (>= 1.86)` into `Depends: nodejs (>= 24)`, which apt refuses on
+ * trixie, Ubuntu 24.04 and Ubuntu 26.04. A macOS decision made the Linux package
+ * uninstallable, because every generator read the PROJECT field instead of the
+ * resolved runtime of its OWN target (#1486, ADR 0024 § A22). Nothing downstream
+ * reads either key; they all read `settings.app`, which is this result.
+ *
+ * NOT PER LAYOUT BY DEFAULT, and the first cut of the layout axis got this
+ * exactly backwards. Reading ADR § 4's runtime table as a per-layout
+ * REQUIREMENT refused `gjsify.app: "gjs"` for the macOS layout — the entire
+ * audience of that command — while a project with no `gjsify.app` key sailed
+ * through and staged a launcher naming `node` in front of a GJS bundle. § 4
+ * derives the runtime a shipped artifact CARRIES, which is
+ * `Layout.shippedRuntime`; what an artifact runs is what its author says, which
+ * is this. So an absent override means the project field and never the layout's
+ * derived answer.
+ *
+ * MUST NOT be fed `Config.forBuild`'s resolution, whose fallback is the HOST
+ * runtime. That fallback is right for a build (`gjsify build` under Node should
+ * produce a Node bundle by default) and catastrophic for a package: running this
+ * command under Node would silently turn every undeclared GJS project into one
+ * whose launcher execs `node`. An undeclared target is the common case for a GJS
+ * app, and it means GJS.
+ *
+ * TWO REFUSALS, and each is here because the alternative to refusing is SILENT.
+ * A `browser` or `nativescript` value has no artifact to be — no process to
+ * start, an APK/IPA through another pipeline (§ 4) — and would otherwise leave
+ * here as a `.deb` a stranger installs and cannot run, with no gate between here
+ * and their machine; `Layout.runtimeGap` only WARNS because what it describes is
+ * a staged tree rather than an artifact, and the per-FORMAT half of the question
+ * is `assertFormatCanRunInterpreter`, which asks what a container can EXECUTE.
+ * A key outside {@link SHIP_APP_OSES} — `windows`, the `gjsify ship <os>`
+ * POSITIONAL's spelling — would resolve to nothing and leave that target on the
+ * project-wide answer with every gate green, which is why the author who typed
+ * it reads the result as gjsify not supporting the split at all. Both refusals
+ * name the KEY that carried the value: with two keys, "this project declares" no
+ * longer locates it.
+ *
+ * `gjsify ship --from-stage` reads neither key and needs neither: the stage
+ * manifest records the RESOLVED value, so the packing host reads an answer
+ * rather than a default, and `assertLauncherMatchesInterpreter` still compares
+ * the staged `bin/<name>`'s own `exec` line against the dependency about to be
+ * written.
+ */
+export declare function resolveShipApp(input: {
+    /** `gjsify.app` as DECLARED — `undefined` when the project declares nothing. */
+    project?: string;
+    /** `gjsify.ship.app`, the per-layout override table. */
+    perTarget?: ShipAppOptions;
+    /** The layout this run assembles. */
+    layoutOs: HostOs;
+}): ResolvedShipApp;
 export interface ResolvedSettings {
     settings: ShipSettings;
     /** The merged metadata the renderers read. */

package/lib/utils/ship/settings.js

@@ -14,6 +14,90 @@ import { basename } from 'node:path';
 import { DEFAULT_GJS_FLOOR, DEFAULT_NODE_FLOOR } from './depends.js';
 import { resolveShipFlatpakSettings } from './flatpak-config.js';
 import { assertRelease, normaliseVersion } from './version.js';
+/**
+ * The OS keys `gjsify.ship.app` may carry — {@link HostOs}, the
+ * `process.platform` spelling.
+ *
+ * `satisfies Record<HostOs, true>` rather than a bare list: a fourth layout
+ * cannot arrive without this object failing to compile, so the accepted set
+ * stays total without a second place to remember to update.
+ */
+const SHIP_APP_OSES = { linux: true, darwin: true, win32: true };
+/**
+ * The ONE place a ship target's runtime is decided: `gjsify.app` as the DEFAULT,
+ * `gjsify.ship.app.<os>` as this target's override.
+ *
+ * WHY IT IS PER TARGET, measured on a GTK4 application rather than derived from
+ * the schema: with one field, `gjsify ship darwin` refused its formats until
+ * `gjsify.app` was `"node"` — and setting it turned the LINUX `.deb`'s
+ * `Depends: gjs (>= 1.86)` into `Depends: nodejs (>= 24)`, which apt refuses on
+ * trixie, Ubuntu 24.04 and Ubuntu 26.04. A macOS decision made the Linux package
+ * uninstallable, because every generator read the PROJECT field instead of the
+ * resolved runtime of its OWN target (#1486, ADR 0024 § A22). Nothing downstream
+ * reads either key; they all read `settings.app`, which is this result.
+ *
+ * NOT PER LAYOUT BY DEFAULT, and the first cut of the layout axis got this
+ * exactly backwards. Reading ADR § 4's runtime table as a per-layout
+ * REQUIREMENT refused `gjsify.app: "gjs"` for the macOS layout — the entire
+ * audience of that command — while a project with no `gjsify.app` key sailed
+ * through and staged a launcher naming `node` in front of a GJS bundle. § 4
+ * derives the runtime a shipped artifact CARRIES, which is
+ * `Layout.shippedRuntime`; what an artifact runs is what its author says, which
+ * is this. So an absent override means the project field and never the layout's
+ * derived answer.
+ *
+ * MUST NOT be fed `Config.forBuild`'s resolution, whose fallback is the HOST
+ * runtime. That fallback is right for a build (`gjsify build` under Node should
+ * produce a Node bundle by default) and catastrophic for a package: running this
+ * command under Node would silently turn every undeclared GJS project into one
+ * whose launcher execs `node`. An undeclared target is the common case for a GJS
+ * app, and it means GJS.
+ *
+ * TWO REFUSALS, and each is here because the alternative to refusing is SILENT.
+ * A `browser` or `nativescript` value has no artifact to be — no process to
+ * start, an APK/IPA through another pipeline (§ 4) — and would otherwise leave
+ * here as a `.deb` a stranger installs and cannot run, with no gate between here
+ * and their machine; `Layout.runtimeGap` only WARNS because what it describes is
+ * a staged tree rather than an artifact, and the per-FORMAT half of the question
+ * is `assertFormatCanRunInterpreter`, which asks what a container can EXECUTE.
+ * A key outside {@link SHIP_APP_OSES} — `windows`, the `gjsify ship <os>`
+ * POSITIONAL's spelling — would resolve to nothing and leave that target on the
+ * project-wide answer with every gate green, which is why the author who typed
+ * it reads the result as gjsify not supporting the split at all. Both refusals
+ * name the KEY that carried the value: with two keys, "this project declares" no
+ * longer locates it.
+ *
+ * `gjsify ship --from-stage` reads neither key and needs neither: the stage
+ * manifest records the RESOLVED value, so the packing host reads an answer
+ * rather than a default, and `assertLauncherMatchesInterpreter` still compares
+ * the staged `bin/<name>`'s own `exec` line against the dependency about to be
+ * written.
+ */
+export function resolveShipApp(input) {
+    const perTarget = input.perTarget ?? {};
+    // The WHOLE table, not only this run's key: a mis-keyed override is silent by
+    // construction, so `gjsify ship linux` is the run that has to say `windows` is
+    // not a key. Checking only the resolving key would leave the typo to be found
+    // by the `gjsify ship windows` that already reads as unsupported.
+    for (const os of Object.keys(perTarget)) {
+        if (Object.hasOwn(SHIP_APP_OSES, os))
+            continue;
+        throw new Error(`gjsify ship: \`gjsify.ship.app.${os}\` is not an OS this command assembles for. Known: ` +
+            `${Object.keys(SHIP_APP_OSES).join(', ')} — the \`process.platform\` spelling, not the ` +
+            "`gjsify ship <os>` positional's. A runtime under a key nothing reads leaves that target on " +
+            '`gjsify.app` with nothing to say so.');
+    }
+    const override = perTarget[input.layoutOs];
+    const overridden = override !== undefined;
+    const key = overridden ? `gjsify.ship.app.${input.layoutOs}` : 'gjsify.app';
+    const declared = overridden ? override : input.project;
+    if (declared !== undefined && declared !== 'gjs' && declared !== 'node') {
+        throw new Error(`gjsify ship: \`${key}\` is "${declared}", and only \`gjs\` and \`node\` can be ` +
+            'packaged. A browser bundle has no process to launch, and a NativeScript app ships as an APK/IPA ' +
+            'through a different pipeline. ADR 0024 § 4 has the runtime-per-OS table.');
+    }
+    return { app: declared === 'node' ? 'node' : 'gjs', key, overridden };
+}
 /** Freedesktop main category → deb `Section:` / rpm `Group:`. First match wins. */
 const CATEGORY_SECTIONS = [
     ['Development', { section: 'devel', group: 'Development/Tools' }],
@@ -49,14 +133,10 @@ export function resolveShipSettings(input) {
     const appId = ship.appId ?? flatpak.appId ?? reverseDnsOrThrow(pkg.name, binaryName);
     const name = metadata.name ?? titleCase(binaryName);
     const kind = metadata.kind ?? 'app';
-    // `gjsify.app`, defaulted HERE to `'gjs'` rather than taken from
-    // `Config.forBuild`'s resolution, which falls back to the HOST runtime. That
-    // fallback is right for a build (`gjsify build` under Node should produce a
-    // Node bundle by default) and catastrophic for a package: running this
-    // command under Node would silently turn every undeclared GJS project into
-    // one whose launcher execs `node`. An undeclared target is the common case
-    // for a GJS app, and it means GJS.
-    const app = input.app === 'node' ? 'node' : 'gjs';
+    // NOT resolved here: `resolveShipApp` already did, before the format list was
+    // decided from it. A second defaulting rule in this function would be the
+    // second path those two answers could come apart on.
+    const app = input.app;
     const rawVersion = ship.version ?? pkg.version;
     if (!rawVersion) {
         throw new Error('gjsify ship: no version — set `version` in package.json or `gjsify.ship.version`.');
@@ -110,6 +190,7 @@ export function resolveShipSettings(input) {
         schemaFiles: discovered.schemaFiles,
         typelibFiles: discovered.typelibFiles,
         localeFiles: discovered.localeFiles,
+        fontFiles: discovered.fontFiles,
         extraFiles: ship.extraFiles ?? {},
         execArgs: ship.execArgs ?? [],
         outDir: input.cli.outDir ?? ship.outDir ?? 'ship',

package/lib/utils/ship/share-dirs.d.ts

@@ -18,6 +18,36 @@ export declare const SHARE: {
     readonly metainfo: "share/metainfo";
     /** Compiled gettext catalogues, read directly — no install step. */
     readonly locale: "share/locale";
+    /**
+     * Font faces the application ships — ONE directory, and three different things
+     * reach it (ADR 0038). No install step on any of them.
+     *
+     * On LINUX fontconfig scans it, by two rules that are both the stock
+     * `fonts.conf`'s rather than ours: `<dir>/usr/share/fonts</dir>` unconditionally,
+     * which covers a `.deb`/`.rpm`, and `<dir prefix="xdg">fonts</dir>`, which
+     * fontconfig expands over `XDG_DATA_DIRS` as well as `XDG_DATA_HOME` — so the
+     * variable the launcher already exports covers `/app` in a Flatpak and any other
+     * prefix. `fonts-conf(5)` documents only `XDG_DATA_HOME` there; the expansion was
+     * measured in EIGHT independently built fontconfigs (2.14.1 through 2.18.3), in
+     * every list position, recursively, with a cold cache and a negative control.
+     * Behaviour, not documentation — which is why it is written here and in ADR 0038
+     * § *What was measured* rather than re-derived from the man page.
+     *
+     * On MACOS none of that applies and the directory is the same: Pango there is
+     * CoreText-backed and GTK is not built against fontconfig, so `Info.plist`'s
+     * `ATSApplicationFontsPath` points at this directory instead (`layout.ts`).
+     *
+     * On WINDOWS nothing reaches it by configuration at all — measured there, not
+     * inferred: the default font map does not read fontconfig even when the staged
+     * directory is the ONLY configuration it is given, while `add_font_file` on that
+     * same map does register the family. So the launcher's `GJSIFY_FONT_DIR` hands
+     * the directory to the app to register. `Layout.fontGap` carries the numbers and
+     * the three candidates that look like they would work and do not.
+     *
+     * That the PATH is one while the mechanisms are three is the point: `planStage`
+     * keeps emitting one payload, and every per-OS answer is a layout decision.
+     */
+    readonly fonts: "share/fonts";
 };
 /** Is `path` inside `dir`? Directory-boundary aware, so `share/mimetypes` is not inside `share/mime`. */
 export declare function isUnder(path: string, dir: string): boolean;

package/lib/utils/ship/share-dirs.js

@@ -39,6 +39,36 @@ export const SHARE = {
     metainfo: 'share/metainfo',
     /** Compiled gettext catalogues, read directly — no install step. */
     locale: 'share/locale',
+    /**
+     * Font faces the application ships — ONE directory, and three different things
+     * reach it (ADR 0038). No install step on any of them.
+     *
+     * On LINUX fontconfig scans it, by two rules that are both the stock
+     * `fonts.conf`'s rather than ours: `<dir>/usr/share/fonts</dir>` unconditionally,
+     * which covers a `.deb`/`.rpm`, and `<dir prefix="xdg">fonts</dir>`, which
+     * fontconfig expands over `XDG_DATA_DIRS` as well as `XDG_DATA_HOME` — so the
+     * variable the launcher already exports covers `/app` in a Flatpak and any other
+     * prefix. `fonts-conf(5)` documents only `XDG_DATA_HOME` there; the expansion was
+     * measured in EIGHT independently built fontconfigs (2.14.1 through 2.18.3), in
+     * every list position, recursively, with a cold cache and a negative control.
+     * Behaviour, not documentation — which is why it is written here and in ADR 0038
+     * § *What was measured* rather than re-derived from the man page.
+     *
+     * On MACOS none of that applies and the directory is the same: Pango there is
+     * CoreText-backed and GTK is not built against fontconfig, so `Info.plist`'s
+     * `ATSApplicationFontsPath` points at this directory instead (`layout.ts`).
+     *
+     * On WINDOWS nothing reaches it by configuration at all — measured there, not
+     * inferred: the default font map does not read fontconfig even when the staged
+     * directory is the ONLY configuration it is given, while `add_font_file` on that
+     * same map does register the family. So the launcher's `GJSIFY_FONT_DIR` hands
+     * the directory to the app to register. `Layout.fontGap` carries the numbers and
+     * the three candidates that look like they would work and do not.
+     *
+     * That the PATH is one while the mechanisms are three is the point: `planStage`
+     * keeps emitting one payload, and every per-OS answer is a layout decision.
+     */
+    fonts: 'share/fonts',
 };
 /** Is `path` inside `dir`? Directory-boundary aware, so `share/mimetypes` is not inside `share/mime`. */
 export function isUnder(path, dir) {

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

@@ -28,7 +28,34 @@ export interface SignerDescriptor {
      */
     signs: 'macho' | 'pe';
     /** argv after {@link tool}, for ONE file. */
-    args: (identity: string, file: string) => readonly string[];
+    args: (input: SignArgs) => readonly string[];
+    /**
+     * The entitlements this signer asks for, or `[]` where the OS has none.
+     *
+     * `[]` is an ANSWER and not an omission — the same rule `Layout.metadata`
+     * states. Windows has no equivalent concept at all, and a signer that granted
+     * nothing on macOS would be a different decision from one that has nothing to
+     * grant.
+     */
+    entitlements: readonly string[];
+    /**
+     * Does this signer seal the ARTIFACT ROOT after signing the images inside it?
+     *
+     * Only true where the OS has a bundle format, which is darwin alone. The root
+     * itself is not on the descriptor because it belongs to the LAYOUT
+     * (`Layout.root`), and a second copy here is where the two would come apart.
+     */
+    sealsBundle: boolean;
+    /**
+     * Payload paths a seal is allowed to ADD, given the artifact root.
+     *
+     * A PREFIX rather than a free hand: `codesign` on a bundle writes
+     * `Contents/_CodeSignature/{CodeResources,CodeDirectory,CodeRequirements,
+     * CodeRequirements-1,CodeSignature}` and nothing else, so anything appearing
+     * outside that directory is something else having run — which is exactly the
+     * class {@link signPayload}'s file-set check exists to catch.
+     */
+    sealAddPrefix: (bundleRoot: string) => string;
     /** The config key a project spells its default identity under. */
     configKey: string;
     /** What a signature from this signer does NOT yet cover — printed once per run. */
@@ -91,6 +118,42 @@ export declare function resolveSignPlan(input: {
  * knowable before anything is packed.
  */
 export declare function assertHostCanSign(signer: SignerDescriptor): void;
+/**
+ * What a signing run did to the payload's FILE SET, split three ways.
+ *
+ * PURE, and extracted from {@link signPayload} for one reason: it is the whole of
+ * the seal decision and the only half of it that can be checked without a macOS
+ * host. Everything else about a bundle seal needs `codesign`, which this
+ * repository has on exactly one CI leg; this function needs nothing.
+ *
+ * `sealPrefix` absent means "this signer seals nothing", and then EVERY addition
+ * is unexpected — which is what the file did before ADR 0040 and is still the
+ * right answer for `signtool`.
+ */
+export declare function partitionSignedFileSet(input: {
+    /** Paths found under the scratch directory after the tool ran. */
+    arrived: readonly string[];
+    /** Paths the payload had before it. */
+    planned: readonly string[];
+    /** Directory prefix the seal is allowed to write into, when there is one. */
+    sealPrefix?: string;
+}): {
+    sealed: string[];
+    unexpected: string[];
+    removed: string[];
+};
+/** What one invocation of a signing tool is given. */
+export interface SignArgs {
+    identity: string;
+    /** Absolute path of the file — or, for a bundle seal, of the bundle DIRECTORY. */
+    file: string;
+    /** Absolute path of the entitlements plist this run wrote, or absent when the signer grants none. */
+    entitlements?: string;
+    /** Is {@link identity} the reserved ad-hoc `-`? */
+    adhoc: boolean;
+}
+/** `codesign --sign -`: the one identity value that names no identity at all. */
+export declare const ADHOC_IDENTITY = "-";
 export interface SignPayloadInput {
     /** What `readStage` returned — the PRE-sign tree, already held against the manifest. */
     payload: readonly PayloadEntry[];
@@ -98,6 +161,22 @@ export interface SignPayloadInput {
     signer: SignerDescriptor;
     /** A scratch directory this function owns and WIPES. Never the arriving stage. */
     workDir: string;
+    /**
+     * `Layout.root` — the payload-relative directory that IS the artifact, or `''`.
+     *
+     * Read only by a signer that seals: it is what `codesign` is pointed at, and
+     * it comes from the layout rather than from this table because the layout is
+     * what decided the `<App>.app` name in the first place.
+     */
+    bundleRoot: string;
+    /**
+     * Where to write the entitlements plist, OUTSIDE {@link workDir}.
+     *
+     * Outside is not a preference: the file-set check below lists `workDir` and
+     * compares it with the payload, so an entitlements file written inside would
+     * read as a file the signer added.
+     */
+    entitlementsPath: string;
     /** Print every invocation. */
     verbose: boolean;
     log: (line: string) => void;
@@ -112,11 +191,16 @@ export interface SignPayloadInput {
  * same tree fail `readStage`'s size comparison (measured — see the header), and
  * `writeStage`'s wipe would delete the payload it was about to pack.
  *
- * THE FILE SET MAY NOT CHANGE, and that is asserted rather than assumed. Both
- * tools rewrite an image in place, so a payload that gained or lost a path here
- * means something else ran — a bundle seal writing `_CodeSignature/`, say, whose
- * files would then be dropped on the way back into the payload without anyone
- * noticing.
+ * TWO STEPS ON DARWIN, ONE EVERYWHERE ELSE: every Mach-O in the closure, then the
+ * bundle itself. The second is what `codesign --verify <App>.app` reads, and it
+ * writes five regular files into `Contents/_CodeSignature/` that the returned
+ * payload carries — so the seal reaches the `.zip` and the `.dmg` alike, which is
+ * the correction ADR 0040 makes to this file's previous claim that it could not.
+ *
+ * THE FILE SET MAY ONLY GROW WHERE THE SEAL WRITES, and that is asserted rather
+ * than assumed. Both tools rewrite an image in place, so a payload that gained a
+ * path outside `sealAddPrefix` — or lost one anywhere — means something else ran,
+ * and its files would be packed with no mode from the plan.
  */
 export declare function signPayload(input: SignPayloadInput): Promise<PayloadEntry[]>;
 /**
@@ -193,3 +277,35 @@ export declare function notarizeArtifact(input: {
     verbose: boolean;
     log: (line: string) => void;
 }): Promise<void>;
+/**
+ * Attach the notarisation ticket to an artifact that can hold one.
+ *
+ * WHY IT IS A SEPARATE CALL AND NOT THE TAIL OF {@link notarizeArtifact}: not
+ * every artifact the notary service ACCEPTS can carry a ticket, and the pair that
+ * comes apart is exactly the one this command produces. Apple:
+ * *"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."*
+ * `stapler(1)` gives the accepting side of the same list: *"stapler works only
+ * with UDIF disk images, signed \"flat\" installer packages, and certain
+ * code-signed executable bundles such as \".app\"."* So the `.dmg` is stapled
+ * here and the `.zip` is told, in the artifact log, what a person has to do
+ * instead — which is a fact about the CONTAINER and therefore lives on the format
+ * (`canCarryTicket`), not in a branch here.
+ *
+ * ⚠️ UNVERIFIED END TO END, for the same reason `notarizeArtifact` is: stapling
+ * needs a real notarisation, which needs an Apple account (ADR 0024 § A15, § A17).
+ * The argv is unit-tested and the invocation has never run in this repository.
+ *
+ * `stapler(1)` also states the constraint that decides the ORDER: *"Stapling does
+ * not invalidate the code signature and must be run after an executable or archive
+ * has been code-signed and notarized … Code-signing a supported file format
+ * invalidates any stapled tickets"* — so nothing may re-sign after this, and
+ * nothing in `packOne` does.
+ */
+export declare function stapleArtifact(input: {
+    notary: NotaryDescriptor;
+    artifact: string;
+    verbose: boolean;
+    log: (line: string) => void;
+}): Promise<void>;