@gjsify/cli 0.51.1 → 0.53.0

package/lib/utils/runtimes.js

@@ -6,13 +6,14 @@
 // runtime→build-target mapping and `availableRuntimes()` live in ONE place instead
 // of a per-example copy.
 //
-// Intentionally PURE (only `node:child_process` and the side-effect-free
-// `@gjsify/rolldown-plugin-gjsify/runtime` host detector, no `gi://` or native
-// imports) so an external example can deep-import it from the installed CLI
-// (`@gjsify/cli/lib/utils/runtimes.js`) without pulling in the whole bundler — the
-// same deep-import precedent as `@gjsify/cli/lib/utils/run-gjs.js`.
-import { execFileSync } from 'node:child_process';
+// Intentionally PURE (only `node:child_process`, `./spawn.js`'s Windows command
+// rewrite and the side-effect-free `@gjsify/rolldown-plugin-gjsify/runtime` host
+// detector, no `gi://` or native imports) so an external example can deep-import
+// it from the installed CLI (`@gjsify/cli/lib/utils/runtimes.js`) without pulling
+// in the whole bundler — the same deep-import precedent as `@gjsify/cli/lib/utils/run-gjs.js`.
+import { spawnSync } from 'node:child_process';
 import { hostRuntime } from '@gjsify/rolldown-plugin-gjsify/runtime';
+import { toSpawnable } from './spawn.js';
 /** All runtimes, in canonical order (gjs first — it is the reference). */
 export const EXAMPLE_RUNTIMES = ['gjs', 'node', 'bun', 'deno'];
 /**
@@ -57,13 +58,13 @@ export function requiresGjsSystemDeps(runtime) {
 }
 /** Whether `<probe> --version` succeeds (i.e. the runtime binary is on PATH). */
 export function isRuntimeOnPath(probe) {
-    try {
-        execFileSync(probe, ['--version'], { stdio: 'ignore', timeout: 15000 });
-        return true;
-    }
-    catch {
-        return false;
-    }
+    const inv = toSpawnable(probe, ['--version']);
+    const r = spawnSync(inv.cmd, inv.args, {
+        stdio: 'ignore',
+        timeout: 15000,
+        windowsVerbatimArguments: inv.windowsVerbatimArguments,
+    });
+    return !r.error && r.status === 0;
 }
 /**
  * Whether a specific runtime is runnable here. The HOST runtime needs no PATH probe

package/lib/utils/ship/gzip.js

@@ -26,7 +26,7 @@
 //     asked for only where a reader demands it (see below) and not blanket-applied
 //     to the payload tarballs.
 //
-// Ledgered in `status/open-todos.md`; closing it means pinning ONE deflate
+// Ledgered in `status/open-todos/README.md`; closing it means pinning ONE deflate
 // implementation, which is a larger decision than this file.
 import { gzip } from '@gjsify/tar';
 /**

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

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

package/lib/utils/ship/icns.js

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

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

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

package/lib/utils/ship/ico.js

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

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

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