crossbind 2.0.0-beta.64 → 2.0.0-beta.66

package/src/utils/appIcon.js

@@ -0,0 +1,174 @@
+// An app's icon: app.icon in crossbind.config.js, one square PNG the build makes each platform's icons from. Every size
+// is resampled with a three-lobed Lanczos filter on premultiplied colors, as Tauri resizes icons.
+import fs from 'node:fs';
+import path from 'node:path';
+import { PNG } from 'pngjs';
+import { getContentHash } from './hash.js';
+
+// A macOS .icns: each kind of entry and the size of the PNG it holds.
+const ICNS_ENTRIES = [['icp4', 16], ['icp5', 32], ['ic11', 32], ['ic12', 64], ['ic07', 128], ['ic13', 256], ['ic08', 256],
+    ['ic14', 512], ['ic09', 512], ['ic10', 1024]];
+// A Windows .ico's sizes, each a PNG.
+const ICO_SIZES = [16, 24, 32, 48, 64, 256];
+const LINUX_SIZE = 512;
+// Xcode makes an iOS app's every size from this one.
+const IOS_SIZE = 1024;
+// An Android launcher icon's foreground at each density is 108 dp, of which the launcher's mask shows the middle 72.
+const ANDROID_FOREGROUNDS = { mdpi: 108, hdpi: 162, xhdpi: 216, xxhdpi: 324, xxxhdpi: 432 };
+const ANDROID_SHOWN = 72 / 108;
+const WHITE = { red: 255, green: 255, blue: 255 };
+
+// The app's icon, read and checked; none without app.icon.
+export function readAppIcon(config) {
+    const { icon } = config.app;
+    if (icon === undefined) return null;
+    if (typeof icon !== 'string' || !icon) {
+        throw new Error(`crossbind: app.icon ${JSON.stringify(icon)} is no path to a PNG file, as 'icon.png' is.`);
+    }
+    const file = path.resolve(config.paths.project, icon);
+    if (!fs.existsSync(file)) throw new Error(`crossbind: app.icon names ${file}, which does not exist.`);
+    let bytes;
+    let image;
+    try {
+        bytes = fs.readFileSync(file);
+        image = PNG.sync.read(bytes);
+    } catch (error) {
+        throw new Error(`crossbind: app.icon ${file} is no PNG image: ${error.message}.`, { cause: error });
+    }
+    if (image.width !== image.height) {
+        throw new Error(`crossbind: app.icon ${file} is ${image.width} × ${image.height} pixels; an app's icon is square, at best 1024 × 1024.`);
+    }
+    return { file, hash: getContentHash(bytes), image: { width: image.width, height: image.height, data: image.data } };
+}
+
+function lanczos3(x) {
+    if (x === 0) return 1;
+    if (x <= -3 || x >= 3) return 0;
+    const px = Math.PI * x;
+    return (3 * Math.sin(px) * Math.sin(px / 3)) / (px * px);
+}
+
+// For each pixel along one axis of the resized image, the first pixel of the original it takes and their weights.
+function contributions(from, to) {
+    const scale = from / to;
+    // Shrinking widens the filter, so every pixel of the original counts.
+    const stretch = Math.max(scale, 1);
+    return Array.from({ length: to }, (_, index) => {
+        const center = (index + 0.5) * scale;
+        const first = Math.max(0, Math.ceil(center - 3 * stretch - 0.5));
+        const last = Math.min(from - 1, Math.floor(center + 3 * stretch - 0.5));
+        const weights = Array.from({ length: last - first + 1 }, (__, k) => lanczos3((first + k + 0.5 - center) / stretch));
+        const total = weights.reduce((sum, weight) => sum + weight, 0);
+        return { first, weights: weights.map((weight) => weight / total) };
+    });
+}
+
+// One pass along x: each row of `width` pixels becomes `size` pixels, written to the output transposed, so the second
+// pass along y is the same pass again.
+function pass(source, width, height, size) {
+    const out = new Float32Array(size * height * 4);
+    contributions(width, size).forEach(({ first, weights }, x) => {
+        for (let y = 0; y < height; y++) {
+            const row = y * width;
+            const at = (x * height + y) * 4;
+            for (let k = 0; k < weights.length; k++) {
+                const from = (row + first + k) * 4;
+                out[at] += weights[k] * source[from];
+                out[at + 1] += weights[k] * source[from + 1];
+                out[at + 2] += weights[k] * source[from + 2];
+                out[at + 3] += weights[k] * source[from + 3];
+            }
+        }
+    });
+    return out;
+}
+
+export function resize(image, size) {
+    if (image.width === size) return image;
+    const { width, height, data } = image;
+    // Premultiplied, so the color of a transparent pixel does not bleed into its neighbors.
+    const source = new Float32Array(width * height * 4);
+    for (let i = 0; i < data.length; i += 4) {
+        const alpha = data[i + 3] / 255;
+        source[i] = data[i] * alpha;
+        source[i + 1] = data[i + 1] * alpha;
+        source[i + 2] = data[i + 2] * alpha;
+        source[i + 3] = data[i + 3];
+    }
+    const resized = pass(pass(source, width, height, size), height, size, size);
+    const out = Buffer.alloc(size * size * 4);
+    const clamp = (value) => Math.min(255, Math.max(0, Math.round(value)));
+    for (let i = 0; i < out.length; i += 4) {
+        // The filter overshoots now and then; the colors divide by what it gave, the alpha is clamped.
+        const alpha = resized[i + 3];
+        out[i + 3] = clamp(alpha);
+        if (out[i + 3] === 0) continue;
+        out[i] = clamp((resized[i] * 255) / alpha);
+        out[i + 1] = clamp((resized[i + 1] * 255) / alpha);
+        out[i + 2] = clamp((resized[i + 2] * 255) / alpha);
+    }
+    return { width: size, height: size, data: out };
+}
+
+// The image at `size` in the middle of a transparent square of `canvas`.
+function centered(image, canvas, size) {
+    const inner = resize(image, size);
+    const out = Buffer.alloc(canvas * canvas * 4);
+    const offset = Math.floor((canvas - size) / 2);
+    for (let y = 0; y < size; y++) inner.data.copy(out, ((y + offset) * canvas + offset) * 4, y * size * 4, (y + 1) * size * 4);
+    return { width: canvas, height: canvas, data: out };
+}
+
+const png = (image, options) => PNG.sync.write(image, options);
+
+// A macOS app's icon file, which its Info.plist names.
+export function macIcon(icon) {
+    const pngs = new Map();
+    const entries = ICNS_ENTRIES.map(([type, size]) => {
+        if (!pngs.has(size)) pngs.set(size, png(resize(icon.image, size)));
+        return chunk(type, pngs.get(size));
+    });
+    return chunk('icns', Buffer.concat(entries));
+}
+
+// An .icns chunk: its type, its length with these eight bytes, and what it holds.
+function chunk(type, data) {
+    const header = Buffer.alloc(8);
+    header.write(type, 0, 'latin1');
+    header.writeUInt32BE(data.length + 8, 4);
+    return Buffer.concat([header, data]);
+}
+
+// A Windows app's icon, which its executable carries.
+export function windowsIcon(icon) {
+    const images = ICO_SIZES.map((size) => png(resize(icon.image, size)));
+    const header = Buffer.alloc(6 + 16 * images.length);
+    header.writeUInt16LE(1, 2);
+    header.writeUInt16LE(images.length, 4);
+    let offset = header.length;
+    images.forEach((image, index) => {
+        const at = 6 + 16 * index;
+        // A width and height of 0 stand for 256.
+        header.writeUInt8(ICO_SIZES[index] % 256, at);
+        header.writeUInt8(ICO_SIZES[index] % 256, at + 1);
+        header.writeUInt16LE(1, at + 4);
+        header.writeUInt16LE(32, at + 6);
+        header.writeUInt32LE(image.length, at + 8);
+        header.writeUInt32LE(offset, at + 12);
+        offset += image.length;
+    });
+    return Buffer.concat([header, ...images]);
+}
+
+// A Linux app's window icon.
+export const linuxIcon = (icon) => png(resize(icon.image, LINUX_SIZE));
+
+// The one image an iOS app's asset catalog holds, on white and without an alpha channel, which the App Store refuses
+// even when every pixel is opaque.
+export const iosIcon = (icon) => png(resize(icon.image, IOS_SIZE), { colorType: 2, bgColor: WHITE });
+
+// An Android app's adaptive icon: its foreground at each density, with the whole icon in what the mask shows; its
+// background is white.
+export const androidIcons = (icon) => Object.fromEntries(Object.entries(ANDROID_FOREGROUNDS).map(([density, size]) => [
+    `mipmap-${density}/ic_launcher_foreground.png`, png(centered(icon.image, size, Math.round(size * ANDROID_SHOWN))),
+]));

package/src/utils/appOptions.js

@@ -0,0 +1,284 @@
+// The app section of crossbind.config.js: what a user sees of an app, its name and, on the desktop, its window, and where
+// its page opens files.
+
+const WINDOW_DEFAULTS = { width: 1024, height: 768, minWidth: 0, minHeight: 0, maxWidth: 0, maxHeight: 0, resizable: true, fullscreen: false, backgroundColor: null };
+// Larger than any display, and far within the int a host takes a size as.
+const MAX_WINDOW_SIZE = 16384;
+// Windows keeps each of a file version's four numbers in 16 bits.
+const MAX_VERSION_NUMBER = 65535;
+// Up to four numbers, then a semver prerelease or build part; none of its characters needs escaping in C or RC.
+const WINDOWS_VERSION = /^(\d+(?:\.\d+){0,3})(?:[-+][0-9A-Za-z.+-]*)?$/;
+// What app.openPath can let the page's shell.openPath open: the app's folders as app.paths() names them, and what a
+// dialog picked during this run.
+const OPEN_PATH_PLACES = ['data', 'cache', 'logs', 'picked'];
+
+// An app's bundle id, which also names its folders on the desktop: app.id, else one made from the project's name.
+export function appId(config) {
+    const id = config.app.id ?? `dev.crossbind.${config.general.name.replace(/[^A-Za-z0-9.-]/g, '-')}`;
+    // An empty part would let "." or ".." name the folder above the app's own.
+    if (typeof id !== 'string' || !/^[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)*$/.test(id)) {
+        throw new Error(`crossbind: app.id ${JSON.stringify(id)} is no bundle id, which takes dot-separated parts of letters, digits and hyphens, as com.example.app does.`);
+    }
+    return id;
+}
+
+// The name the app shows: its window's title, its macOS menus, its Windows file description and the label under its
+// icon. The project's name, without app.name.
+export function appDisplayName(config) {
+    const isOwn = config.app.name !== undefined;
+    const name = isOwn ? config.app.name : config.general.name;
+    // The host takes it as a C string and a Windows resource string, which hold none of these as they are, and Android
+    // reads a label that starts with @ or ? as a resource.
+    if (typeof name !== 'string' || !name.trim() || /["\\\p{Cc}]/u.test(name) || /^[@?]/.test(name)) {
+        const rule = 'which is text without a quotation mark, a backslash or a control character, starting with neither @ nor ?';
+        throw new Error(isOwn
+            ? `crossbind: app.name ${JSON.stringify(name)} is no name an app can show, ${rule}. Change it, or drop app.name to show general.name.`
+            : `crossbind: general.name ${JSON.stringify(name)}, which an app shows without app.name, is no name it can show, ${rule}. Set app.name in crossbind.config.js.`);
+    }
+    return name;
+}
+
+// The desktop window: the size of its page, the least it shrinks to and the most it grows to, whether it resizes and
+// whether it opens full screen. Its backgroundColor, which a phone takes as well, is appBackgroundColor's.
+export function appWindow(config) {
+    const window = config.app.window ?? {};
+    const keys = Object.keys(WINDOW_DEFAULTS).join(', ');
+    if (typeof window !== 'object' || Array.isArray(window)) {
+        throw new Error(`crossbind: app.window ${JSON.stringify(window)} is no object of ${keys}, as { width: 1024, height: 768 } is.`);
+    }
+    const unknown = Object.keys(window).filter((key) => !(key in WINDOW_DEFAULTS));
+    if (unknown.length > 0) throw new Error(`crossbind: app.window takes ${keys}; ${unknown.join(', ')} is none of them.`);
+    const options = { ...WINDOW_DEFAULTS, ...window };
+    ['width', 'height', 'minWidth', 'minHeight', 'maxWidth', 'maxHeight'].forEach((key) => {
+        const least = /^(min|max)/.test(key) ? 0 : 1;
+        if (!Number.isInteger(options[key]) || options[key] < least || options[key] > MAX_WINDOW_SIZE) {
+            throw new Error(`crossbind: app.window.${key} ${JSON.stringify(options[key])} is no size, which is a whole number of pixels from ${least} to ${MAX_WINDOW_SIZE}.`);
+        }
+    });
+    ['resizable', 'fullscreen'].forEach((key) => {
+        if (typeof options[key] !== 'boolean') throw new Error(`crossbind: app.window.${key} ${JSON.stringify(options[key])} is no boolean: set it to true or false.`);
+    });
+    if (!options.resizable && (options.minWidth || options.minHeight || options.maxWidth || options.maxHeight)) {
+        throw new Error('crossbind: app.window.minWidth, minHeight, maxWidth and maxHeight limit a window that resizes: drop them, or set app.window.resizable to true.');
+    }
+    [['width', 'Width'], ['height', 'Height']].forEach(([size, side]) => {
+        const [least, most] = [options[`min${side}`], options[`max${side}`]];
+        if (least > options[size]) {
+            throw new Error(`crossbind: app.window.min${side} ${least} is above the ${size} the window opens with, ${options[size]}: lower it, or raise app.window.${size}.`);
+        }
+        if (most && most < options[size]) {
+            throw new Error(`crossbind: app.window.max${side} ${most} is below the ${size} the window opens with, ${options[size]}: raise it, or lower app.window.${size}.`);
+        }
+    });
+    return options;
+}
+
+// The color an app shows until its page paints, and behind a page without a background of its own, on iOS and Android as
+// well: app.window.backgroundColor, else null, which leaves the system's.
+export function appBackgroundColor(config) {
+    const color = config.app.window?.backgroundColor ?? null;
+    if (color !== null && (typeof color !== 'string' || !/^#[0-9A-Fa-f]{6}$/.test(color))) {
+        throw new Error(`crossbind: app.window.backgroundColor ${JSON.stringify(color)} is no color of the form #rrggbb, as #1e1e1e is.`);
+    }
+    return color;
+}
+
+const PERMISSIONS = ['camera', 'microphone', 'location'];
+
+// The devices the page may use, each with the reason for it, which macOS and iOS read from the Info.plist:
+// app.permissions.
+export function appPermissions(config) {
+    const permissions = config.app.permissions ?? {};
+    const names = PERMISSIONS.join(', ');
+    if (typeof permissions !== 'object' || Array.isArray(permissions)) {
+        throw new Error(`crossbind: app.permissions ${JSON.stringify(permissions)} is no object of ${names}, each with the reason the app uses it, as { camera: 'To scan barcodes' } is.`);
+    }
+    const unknown = Object.keys(permissions).filter((name) => !PERMISSIONS.includes(name));
+    if (unknown.length > 0) throw new Error(`crossbind: app.permissions takes ${names}; ${unknown.join(', ')} is none of them.`);
+    Object.entries(permissions).forEach(([name, reason]) => {
+        if (typeof reason !== 'string' || !reason.trim() || /\p{Cc}/u.test(reason)) {
+            throw new Error(`crossbind: app.permissions.${name} ${JSON.stringify(reason)} is no reason, which is text without control characters that the app's user reads when it asks for the ${name}, as 'To scan barcodes' is.`);
+        }
+    });
+    return permissions;
+}
+
+// The reasons of app.permissions under the Info.plist keys macOS or iOS reads them from; macOS reads location's older
+// key as well.
+export function usageDescriptions(config, platform) {
+    const keys = {
+        camera: ['NSCameraUsageDescription'],
+        microphone: ['NSMicrophoneUsageDescription'],
+        location: ['NSLocationWhenInUseUsageDescription', ...(platform === 'darwin' ? ['NSLocationUsageDescription'] : [])],
+    };
+    return Object.fromEntries(Object.entries(appPermissions(config)).flatMap(([name, reason]) => keys[name].map((key) => [key, reason])));
+}
+
+// The version a Windows app's executable carries: package.json's, whose numbers are its file version.
+function windowsVersion(config) {
+    const version = config.package?.version ?? '1.0.0';
+    const match = typeof version === 'string' ? WINDOWS_VERSION.exec(version) : null;
+    const numbers = match ? match[1].split('.').map(Number) : [];
+    if (!match || numbers.some((number) => number > MAX_VERSION_NUMBER)) {
+        throw new Error(`crossbind: package.json's version ${JSON.stringify(version)} is no version a Windows app can carry, which is up to four numbers from 0 to ${MAX_VERSION_NUMBER}, as 1.2.3 and 1.2.3-beta.1 are.`);
+    }
+    return { text: version, numbers: [...numbers, 0, 0, 0].slice(0, 4).join(',') };
+}
+
+// Where the page's shell.openPath opens a file: nowhere unless app.openPath lists it, as opening a program runs it.
+function appOpenPath(config) {
+    const places = config.app.openPath ?? [];
+    if (!Array.isArray(places)) {
+        throw new Error(`crossbind: app.openPath ${JSON.stringify(places)} is no list of ${OPEN_PATH_PLACES.join(', ')}, as ['logs', 'picked'] is.`);
+    }
+    const unknown = places.filter((place) => !OPEN_PATH_PLACES.includes(place));
+    if (unknown.length > 0) {
+        throw new Error(`crossbind: app.openPath takes ${OPEN_PATH_PLACES.join(', ')}; ${unknown.map((place) => JSON.stringify(place)).join(', ')} is none of them.`);
+    }
+    return places;
+}
+
+// Schemes the web, the system or crossbind owns, which no app takes, and the keys of Windows' own classes, whose name a
+// scheme's registry key would take.
+const RESERVED_SCHEMES = [
+    'about', 'blob', 'content', 'crossbind', 'data', 'file', 'ftp', 'http', 'https', 'intent', 'javascript', 'mailto', 'sms', 'tel', 'ws', 'wss',
+    'appid', 'applications', 'clsid', 'directory', 'drive', 'folder', 'interface', 'mime', 'protocols', 'systemfileassociations', 'typelib', 'unknown',
+    'wow6432node',
+];
+
+// The schemes whose links open the app, as myapp://… does: lowercase, which is how Android matches them, and of two
+// characters at least, as one would take a Windows path's drive for a scheme.
+export function appUrlSchemes(config) {
+    const schemes = config.app.urlSchemes ?? [];
+    if (!Array.isArray(schemes)) {
+        throw new Error(`crossbind: app.urlSchemes ${JSON.stringify(schemes)} is no list of schemes, as ['myapp'] is.`);
+    }
+    for (const scheme of schemes) {
+        if (typeof scheme !== 'string' || !/^[a-z][a-z0-9+.-]+$/.test(scheme)) {
+            throw new Error(`crossbind: app.urlSchemes takes schemes of a lowercase letter, then one or more lowercase letters, digits, +, - and ., as myapp is; ${JSON.stringify(scheme)} is none.`);
+        }
+        if (RESERVED_SCHEMES.includes(scheme)) {
+            throw new Error(`crossbind: app.urlSchemes cannot take ${scheme}, which the web or the system owns: pick a scheme of the app's own.`);
+        }
+    }
+    if (new Set(schemes).size !== schemes.length) throw new Error(`crossbind: app.urlSchemes lists a scheme twice: ${JSON.stringify(schemes)}.`);
+    return schemes;
+}
+
+// Semver's version: three numbers, then a prerelease and build metadata of dot-separated identifiers.
+const SEMVER = /^\d+\.\d+\.\d+(-[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?(\+[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?$/;
+// What an update's files are named after: characters an address carries as they are, and no leading dot.
+const UPDATE_NAME = /^[A-Za-z0-9_~-][A-Za-z0-9._~-]*$/;
+// The Ed25519 public keys of the points of small order, whatever the sign of x, whose signatures anyone can forge: the
+// list libsodium's ge25519_has_small_order checks.
+const SMALL_ORDER_KEYS = [
+    '0000000000000000000000000000000000000000000000000000000000000000',
+    '0100000000000000000000000000000000000000000000000000000000000000',
+    '26e8958fc2b227b045c3f489f2ef98f0d5dfac05d3c63339b13802886d53fc05',
+    'c7176a703d4dd84fba3c0b760d10670f2a2053fa2c39ccc64ec7fd7792ac037a',
+    'ecffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff7f',
+    'edffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff7f',
+    'eeffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff7f',
+].map((hex) => Buffer.from(hex, 'hex'));
+
+const isSmallOrder = (key) => SMALL_ORDER_KEYS.some((point) => key.subarray(0, 31).equals(point.subarray(0, 31)) && (key[31] & 0x7f) === point[31]);
+
+// Where a desktop app finds its updates, the key their signatures are checked with, and the version they are newer than:
+// package.json's, which semver orders. Null without app.updater.
+export function appUpdater(config) {
+    const updater = config.app.updater;
+    if (updater === undefined) return null;
+    const keys = 'url and publicKey';
+    if (updater === null || typeof updater !== 'object' || Array.isArray(updater)) {
+        throw new Error(`crossbind: app.updater ${JSON.stringify(updater)} is no object of ${keys}, as { url: 'https://example.com/updates/<name>-{platform}-{arch}.update.json', publicKey: '…' } is.`);
+    }
+    const unknown = Object.keys(updater).filter((key) => !['url', 'publicKey'].includes(key));
+    if (unknown.length > 0) throw new Error(`crossbind: app.updater takes ${keys}; ${unknown.join(', ')} is none of them.`);
+    const url = URL.canParse(updater.url) ? new URL(updater.url) : null;
+    const isLocal = url?.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+    // The host takes the address as a C string, as it is written, and the update's file from beside the manifest.
+    if (!url || !(url.protocol === 'https:' || isLocal) || /[^\x21-\x7e]|["\\]/.test(updater.url) || url.pathname.endsWith('/')) {
+        throw new Error(`crossbind: app.updater.url ${JSON.stringify(updater.url)} is no https address of a manifest, as https://example.com/updates/<name>-{platform}-{arch}.update.json is; http serves localhost alone.`);
+    }
+    const publicKey = Buffer.from(typeof updater.publicKey === 'string' ? updater.publicKey : '', 'base64');
+    if (publicKey.length !== 32 || publicKey.toString('base64') !== updater.publicKey) {
+        throw new Error(`crossbind: app.updater.publicKey ${JSON.stringify(updater.publicKey)} is no Ed25519 public key, which \`crossbind app updater-key\` prints.`);
+    }
+    if (isSmallOrder(publicKey)) {
+        throw new Error(`crossbind: app.updater.publicKey ${JSON.stringify(updater.publicKey)} is a key anyone can forge signatures for, which no key pair has. Use the one \`crossbind app updater-key\` prints.`);
+    }
+    const version = config.package?.version ?? '1.0.0';
+    if (typeof version !== 'string' || !SEMVER.test(version)) {
+        throw new Error(`crossbind: package.json's version ${JSON.stringify(version)} is no semver version, as 1.2.3 and 1.2.3-beta.1 are, which an app that updates needs to tell a newer one.`);
+    }
+    if (!UPDATE_NAME.test(config.general.name)) {
+        throw new Error(`crossbind: general.name ${JSON.stringify(config.general.name)} names an app's update files, which an app fetches by name: letters, digits, and . _ ~ - alone, not starting with a dot. Change general.name in crossbind.config.js.`);
+    }
+    return { url: updater.url, publicKey, version };
+}
+
+// A desktop host's window: its page's size and limits, whether it resizes and whether it opens full screen. A maximum of
+// one side alone leaves the other as large as any display.
+function windowDefines(window) {
+    const most = window.maxWidth || window.maxHeight ? [
+        `#define CROSSBIND_APP_WINDOW_MAX_WIDTH ${window.maxWidth || MAX_WINDOW_SIZE}`,
+        `#define CROSSBIND_APP_WINDOW_MAX_HEIGHT ${window.maxHeight || MAX_WINDOW_SIZE}`,
+    ] : [];
+    return [
+        `#define CROSSBIND_APP_WINDOW_WIDTH ${window.width}`,
+        `#define CROSSBIND_APP_WINDOW_HEIGHT ${window.height}`,
+        `#define CROSSBIND_APP_WINDOW_MIN_WIDTH ${window.minWidth}`,
+        `#define CROSSBIND_APP_WINDOW_MIN_HEIGHT ${window.minHeight}`,
+        `#define CROSSBIND_APP_WINDOW_RESIZABLE ${window.resizable ? 1 : 0}`,
+        ...most,
+        ...(window.fullscreen ? ['#define CROSSBIND_APP_WINDOW_FULLSCREEN 1'] : []),
+    ];
+}
+
+// The header an app's host compiles where its page opens files from, an iOS or desktop host the color it shows until
+// its page paints and the devices the page may use, a desktop host its title, window, whether it keeps one instance and
+// its updates, and a Windows host its version resource.
+export function appHeader(config, platform) {
+    const comment = '// crossbind writes this file from crossbind.config.js and package.json.';
+    const openPath = `#define CROSSBIND_APP_OPEN_PATH {${appOpenPath(config).map((place) => `"${place}"`).join(', ')}}`;
+    const color = appBackgroundColor(config);
+    const permissions = appPermissions(config);
+    // An Android app's activity takes the color and the permissions from its Gradle project.
+    const page = platform === 'android' ? [] : [
+        ...(color ? [`#define CROSSBIND_APP_BACKGROUND_COLOR 0x${color.slice(1).toLowerCase()}`] : []),
+        ...PERMISSIONS.map((name) => `#define CROSSBIND_APP_PERMISSION_${name.toUpperCase()} ${name in permissions ? 1 : 0}`),
+    ];
+    if (!['darwin', 'linux', 'win32'].includes(platform)) return [comment, openPath, ...page, ''].join('\n');
+    const lines = [
+        comment,
+        openPath,
+        ...page,
+        `#define CROSSBIND_APP_ID "${appId(config)}"`,
+        `#define CROSSBIND_APP_NAME "${appDisplayName(config)}"`,
+        ...windowDefines(appWindow(config)),
+    ];
+    const urlSchemes = appUrlSchemes(config);
+    if (urlSchemes.length > 0) lines.push(`#define CROSSBIND_APP_URL_SCHEMES {${urlSchemes.map((scheme) => `"${scheme}"`).join(', ')}}`);
+    // A link the system opens a Windows or Linux app with starts it again, which reaches the app that runs this way; macOS
+    // hands the link to the app that runs.
+    const singleInstance = config.app.singleInstance ?? (urlSchemes.length > 0 && platform !== 'darwin');
+    if (typeof singleInstance !== 'boolean') {
+        throw new Error(`crossbind: app.singleInstance ${JSON.stringify(singleInstance)} is no boolean: set it to true to keep a desktop app to one instance, or to false to let each launch run.`);
+    }
+    if (singleInstance) lines.push('#define CROSSBIND_APP_SINGLE_INSTANCE 1');
+    const updater = appUpdater(config);
+    if (updater) {
+        lines.push(
+            `#define CROSSBIND_APP_UPDATER_URL "${updater.url}"`,
+            `#define CROSSBIND_APP_UPDATER_KEY {${[...updater.publicKey].map((byte) => `0x${byte.toString(16).padStart(2, '0')}`).join(', ')}}`,
+            `#define CROSSBIND_APP_UPDATER_VERSION "${updater.version}"`,
+        );
+    }
+    if (platform === 'win32') {
+        const version = windowsVersion(config);
+        lines.push(`#define CROSSBIND_APP_VERSION "${version.text}"`, `#define CROSSBIND_APP_VERSION_NUMBERS ${version.numbers}`);
+        // The build writes the icon beside this header.
+        if (config.app.icon !== undefined) lines.push('#define CROSSBIND_APP_ICON 1');
+    }
+    return [...lines, ''].join('\n');
+}

package/src/utils/appRustCrates.js

@@ -80,7 +80,9 @@ export default function buildAppRustCrates(target, cacheDir, cargoDependencies =
         ...crates.map((c) => `${c.replaceAll('_', '-')}-crossbind-app = { path = "${relPath(superDir, `${root}/${c}`)}" }`),
         '',
         '[profile.release]',
-        'panic = "abort"',
+        // Unwinding, as in a package's bridge, whose shims raise a panic as a JS exception: an abort runtime here could
+        // end the process on a panic in any crate. wasm still aborts, as its std does.
+        'panic = "unwind"',
         '',
         ...crates.flatMap((c) => [`[profile.release.package.${c.replaceAll('_', '-')}-crossbind-app]`, 'codegen-units = 1', '']),
         '[workspace]',

package/src/utils/downloadAndExtractFile.js

@@ -14,19 +14,45 @@ const RETRYABLE_STATUS = new Set([408, 429]);
 const sleep = (ms) => new Promise((resolve) => { setTimeout(resolve, ms); });
 const retryable = (error) => Object.assign(error, { retryable: true });
 
-export default async function downloadAndExtractFile(url, output, sha256, options = {}) {
-    const archive = path.basename(url);
+// A recipe names its source with getURL and may name mirrors that serve the same archive under the same pin.
+export function sourcesOf({ getURL, getMirrors }, version) {
+    return [getURL(version), ...(getMirrors?.(version) ?? [])];
+}
+
+// `urls` is one URL or a list of them: the first names the archive, the others are mirrors of it.
+export default async function downloadAndExtractFile(urls, output, sha256, options = {}) {
+    const sources = [urls].flat();
+    const archive = path.basename(sources[0]);
     if (fs.existsSync(`${output}/source`) && sourceCameFrom(output, archive)) {
         return false;
     }
+    sources.forEach((url) => assertHttps(url));
     fs.rmSync(`${output}/source`, { recursive: true, force: true });
-    const filePath = await downloadFile(url, output, options);
-    verifyIntegrity(filePath, url, sha256);
+    const { filePath, url } = await downloadFromAny(sources, output, sha256, { ...options, name: archive });
     extractArchive(filePath, url, output);
     fs.writeFileSync(`${output}/source.archive`, archive);
     return true;
 }
 
+// A source that cannot serve the archive, or serves bytes the pin does not match, hands over to the next one.
+async function downloadFromAny(sources, output, sha256, options) {
+    const failures = [];
+    for (const url of sources) {
+        try {
+            const filePath = await downloadFile(url, output, options);
+            verifyIntegrity(filePath, url, sha256);
+            return { filePath, url };
+        } catch (err) {
+            failures.push(err);
+        }
+    }
+    if (failures.length === 1) throw failures[0];
+    throw new Error(
+        `crossbind: no source of ${options.name} could be used:\n${failures.map((err) => `  - ${err.message}`).join('\n')}`,
+        { cause: failures.at(-1) },
+    );
+}
+
 // A cached source tree only counts when it came from the archive the recipe names now, or a
 // nativeVersion bump would keep compiling the old tree. Trees from before the marker are judged
 // by the archive that was downloaded next to them.
@@ -37,20 +63,22 @@ function sourceCameFrom(output, archive) {
 }
 
 // Extraction runs through the system tar (GNU tar and bsdtar both detect gzip/bzip2/xz, and
-// every platform the engine builds on ships one). Extracting into a scratch directory keeps
-// the archive from choosing where its files land, and gives the upstream root folder - which
-// recipes address as build/source - one place to be renamed from.
+// every platform the engine builds on ships one), and a zip archive, which GNU tar cannot read,
+// through unzip. Extracting into a scratch directory keeps the archive from choosing where its
+// files land, and gives the upstream root folder - which recipes address as build/source - one
+// place to be renamed from.
 function extractArchive(filePath, url, output) {
     const work = `${output}/.extract`;
     fs.rmSync(work, { recursive: true, force: true });
     mkdirSync(work, { recursive: true });
     try {
-        const tar = spawnSync('tar', ['-xf', filePath, '-C', work], { encoding: 'utf8' });
-        if (tar.error) {
-            throw new Error(`crossbind: cannot run tar to extract ${filePath}: ${tar.error.message}`);
+        const [tool, args] = /\.(zip|aar)$/.test(filePath) ? ['unzip', ['-q', filePath, '-d', work]] : ['tar', ['-xf', filePath, '-C', work]];
+        const extracted = spawnSync(tool, args, { encoding: 'utf8' });
+        if (extracted.error) {
+            throw new Error(`crossbind: cannot run ${tool} to extract ${filePath}: ${extracted.error.message}`);
         }
-        if (tar.status !== 0) {
-            throw new Error(`crossbind: extracting ${filePath} (from ${url}) failed: ${(tar.stderr || '').trim() || `tar exited ${tar.status}`}`);
+        if (extracted.status !== 0) {
+            throw new Error(`crossbind: extracting ${filePath} (from ${url}) failed: ${(extracted.stderr || '').trim() || `${tool} exited ${extracted.status}`}`);
         }
         const entries = fs.readdirSync(work, { withFileTypes: true });
         if (entries.length === 0) {
@@ -95,9 +123,9 @@ export function assertHttps(target, context = target) {
 
 // fetch follows redirects itself, which release downloads rely on (github and the osgeo
 // mirrors both bounce), so the download needs no redirect library of its own.
-export async function downloadFile(url, folder, { retryDelaysMs = RETRY_DELAYS_MS } = {}) {
+export async function downloadFile(url, folder, { retryDelaysMs = RETRY_DELAYS_MS, name = path.basename(url) } = {}) {
     mkdirSync(folder, { recursive: true });
-    const dest = `${folder}/${path.basename(url)}`;
+    const dest = `${folder}/${name}`;
     if (fs.existsSync(dest)) return dest;
 
     assertHttps(url);

package/src/utils/embindRsFingerprint.js

@@ -1,18 +1,25 @@
 import fs from 'node:fs';
+import { createRequire } from 'node:module';
 import path from 'node:path';
 import { getContentHash, getFileHash } from './hash.js';
 import { collectRustSources } from './inputStamp.js';
 import resolveEmbindRustRoot from './resolveEmbindRust.js';
+import { HOST_BUILT_PLATFORMS } from './targets.js';
+
+const { toolchains } = createRequire(import.meta.url)('../assets/toolchain-digests.json');
 
 // Every cargo staticlib bundles the embind-rs it was built from. An archive from another one links stale glue, and next
 // to an archive built after it every embind_rs symbol is defined twice, so a prebuilt records the one it came from.
 export const EMBIND_RS_FINGERPRINT_FILE = 'crossbind-embind-rs.fingerprint';
 
-// Paths count relative to the crate, so an archive built from the same embind-rs elsewhere matches.
-export function getEmbindRsFingerprint() {
+// Paths count relative to the crate, so an archive built from the same embind-rs elsewhere matches. An archive an image
+// built carries that image's Rust std too, whose second copy from another rustc lld refuses, so the image's rustc
+// counts as well; Apple's linker takes the mix, and the host's own rustc builds those.
+export function getEmbindRsFingerprint(target) {
     const crate = `${resolveEmbindRustRoot()}/crate`;
     const files = [...collectRustSources([crate]), `${crate}/Cargo.toml`];
-    return getContentHash(files.map((file) => `${path.relative(crate, file)}:${getFileHash(file)}`).sort().join('\n'));
+    const embindRs = getContentHash(files.map((file) => `${path.relative(crate, file)}:${getFileHash(file)}`).sort().join('\n'));
+    return !target || HOST_BUILT_PLATFORMS.includes(target.platform) ? embindRs : getContentHash(`${embindRs}\nrustc ${toolchains.rust}`);
 }
 
 export function isEmbindRsFingerprintStale(prebuiltDir, fingerprint) {

package/src/utils/hermes.js

@@ -0,0 +1,40 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import withDirLock from './dirLock.js';
+import downloadAndExtractFile from './downloadAndExtractFile.js';
+
+// The Hermes React Native publishes on Maven Central for Apple platforms: the macOS framework, the iOS xcframework,
+// hermesc and the headers. A new version also moves third_party/jsi of @crossbind/core-app-host to its tag, and the
+// Hermes of crossbind's android-app, linux and windows images.
+export const HERMES = {
+    version: '250829098.0.17',
+    sha256: '2967ee51b41bd433b3027dda875e96194354e2b4d715f9f186fd0c04ccef309d',
+    license: 'MIT',
+};
+
+export const hermesUrl = (version) => `https://repo1.maven.org/maven2/com/facebook/hermes/hermes-ios/${version}/hermes-ios-${version}-hermes-ios-release.tar.gz`;
+
+export const hermesDir = () => path.join(os.homedir(), '.crossbind', 'hermes', HERMES.version);
+
+// The release's destroot, downloaded once and checked against the pinned sha256.
+export default async function resolveHermes() {
+    const dir = hermesDir();
+    fs.mkdirSync(path.dirname(dir), { recursive: true });
+    await withDirLock(`${dir}.lock`, () => downloadAndExtractFile(hermesUrl(HERMES.version), dir, HERMES.sha256));
+    return `${dir}/source/destroot`;
+}
+
+// Linux and Windows have no published Hermes, so crossbind's linux and windows images build the release's source, with
+// their static libc++: JSI hands std types across, and the host and the project's archives build there too.
+export const HERMES_SOURCE = {
+    url: `https://github.com/facebook/hermes/archive/refs/tags/hermes-v${HERMES.version}.tar.gz`,
+    sha256: '37e91915c67ce0c457f69b2de00fcaf28fcf755ab7de6e4f33f1d6ee9efcffed',
+};
+
+// Android's Hermes is React Native's AAR, which an app's Gradle build takes for the libraries it packages, and which
+// crossbind's android-app image holds, with its headers and hermesc, for the app's host.
+export const HERMES_ANDROID = {
+    url: `https://repo1.maven.org/maven2/com/facebook/hermes/hermes-android/${HERMES.version}/hermes-android-${HERMES.version}-release.aar`,
+    sha256: '6fb440b29aadb5925bed1109338da61623c54c3508020bb2cecebcaaa80e53b8',
+};