crossbind 2.0.0-beta.63 → 2.0.0-beta.65

package/src/program.js

@@ -0,0 +1,169 @@
+import fs from 'node:fs';
+import { Command, Option } from 'commander';
+
+import {
+    deleteAccount as deleteCloudAccount, fetchUsage, login as loginToCloud, logout as logoutOfCloud, usageLines,
+} from './actions/cloudCommands.js';
+import { cloudUrl } from './utils/cloudAccount.js';
+import flattenConfigForTable from './utils/flattenConfigForTable.js';
+import loadSystemConfig, { systemConfigPath } from './utils/systemConfig.js';
+import systemKeys from './utils/systemKeys.js';
+import writeJson from './utils/writeJson.js';
+
+const packageJSON = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url)));
+
+// Build failures bubble up as exceptions with a `cause` chain (see actions/run.js);
+// show the operator a single line — DEBUG=1 for the full stack — and exit non-zero.
+export const handleFatal = (e) => {
+    if (process.env.DEBUG) {
+        console.error(e);
+    } else {
+        let message = e?.message || String(e);
+        if (e?.cause?.message) message += `\n  caused by: ${e.cause.message.split('\n')[0]}`;
+        console.error(message);
+    }
+    process.exit(1);
+};
+
+export const createProgram = () => new Command()
+    .name('crossbind')
+    .description('Compile C++ files to WebAssembly and native platforms.')
+    .version(packageJSON.version)
+    .showHelpAfterError();
+
+export function addSystemCommands(program) {
+    program.command('login')
+        .description('sign in to crossbind cloud with your GitHub account')
+        .action(async () => {
+            const url = cloudUrl(loadSystemConfig());
+            const { login } = await loginToCloud({ url });
+            console.log(`crossbind: signed in to ${url} as ${login}.`);
+        });
+
+    program.command('logout')
+        .description('sign out of crossbind cloud on this machine')
+        .option('--all', 'sign out every machine signed in to this account')
+        .action(async (options) => {
+            const url = cloudUrl(loadSystemConfig());
+            const result = await logoutOfCloud({ url, all: Boolean(options.all) });
+            if (!result) {
+                console.log(`crossbind: not signed in to ${url}.`);
+            } else if (result.revoked) {
+                console.log(`crossbind: signed ${result.login} out${options.all ? ' on every machine' : ''}.`);
+            } else {
+                console.warn(`crossbind: signed out here, but crossbind cloud did not revoke the token (${result.reason.replace(/^crossbind: /, '')}). Sign in again and run crossbind logout --all to revoke it.`);
+            }
+        });
+
+    program.command('usage')
+        .description('show what you used of crossbind cloud this month and what is left')
+        .action(async () => {
+            usageLines(await fetchUsage({ url: cloudUrl(loadSystemConfig()) })).forEach((line) => console.log(line));
+        });
+
+    program.command('account')
+        .description('manage your crossbind cloud account')
+        .command('delete')
+        .description('delete your crossbind cloud account, with the sign-in of every machine (https://crossbind.dev/privacy/)')
+        .option('--yes', 'delete it; without this, nothing is deleted')
+        .action(async (options) => {
+            const url = cloudUrl(loadSystemConfig());
+            if (!options.yes) {
+                throw new Error(`crossbind: this deletes your crossbind cloud account at ${url}, with the sign-in of every machine. Run crossbind account delete --yes to go ahead.`);
+            }
+            const { login } = await deleteCloudAccount({ url });
+            console.log(`crossbind: deleted the crossbind cloud account of ${login}.`);
+        });
+
+    const commandConfig = program.command('config')
+        .description('manage the crossbind configuration files');
+
+    commandConfig.command('get')
+        .description('get the crossbind system configuration')
+        .argument('<key>', 'configuration key to read')
+        .action((key) => getSystemConfig(key));
+
+    commandConfig.command('set')
+        .description('set the crossbind system configuration')
+        .argument('<key>', 'configuration key to set')
+        .argument('<value>', 'value to assign')
+        .action((key, value) => setSystemConfig(key, value));
+
+    commandConfig.command('delete')
+        .description('delete the crossbind system configuration')
+        .argument('<key>', 'configuration key to remove')
+        .action((key) => deleteSystemConfig(key));
+
+    commandConfig.command('list')
+        .description('list the crossbind configurations')
+        .addOption(new Option('-t, --type <type>', 'config type').default('system').choices(['all', 'system', 'project']))
+        .action((options) => listSystemConfig(options.type));
+
+    commandConfig.command('keys')
+        .description('list all available system configuration keys for crossbind')
+        .action(() => listSystemKeys());
+}
+
+function listSystemKeys() {
+    console.info('Available configurations:');
+    console.table(systemKeys);
+}
+
+async function getSystemConfig(systemKey) {
+    if (!systemKey) {
+        await listSystemConfig('system');
+        return;
+    }
+    const system = loadSystemConfig();
+    const key = systemKey.toUpperCase();
+    const output = {};
+    if (key in system) {
+        output[key] = { value: system[key] || 'undefined', default: systemKeys[key].default };
+    }
+    Object.keys(systemKeys).filter((k) => k.includes(key)).forEach((k) => {
+        if (k in system) {
+            output[k] = { value: system[k] || 'undefined', default: systemKeys[k].default };
+        }
+    });
+
+    console.table(output);
+}
+
+function setSystemConfig(key, value) {
+    if (!systemKeys[key]) {
+        throw new Error(`Configuration ${key} is not available. Please choose from the following available configurations: ${Object.keys(systemKeys).join(', ')}`);
+    }
+    if (systemKeys[key].options && !systemKeys[key].options.includes(value)) {
+        throw new Error(`Value ${value} is not available. Please choose from the following available values: ${systemKeys[key].options.join(', ')}`);
+    }
+
+    writeJson(systemConfigPath(), { ...loadSystemConfig(), [key]: value });
+}
+
+function deleteSystemConfig(key) {
+    if (!systemKeys[key]) {
+        throw new Error(`Configuration ${key} is not available. Please choose from the following available configurations: ${Object.keys(systemKeys).join(', ')}`);
+    }
+    const { [key]: deleted, ...system } = loadSystemConfig();
+    writeJson(systemConfigPath(), system);
+}
+
+async function listSystemConfig(type) {
+    // Importing the state loads the project, which fails outside one, so only a listing of the project does.
+    const { system: systemConfig, ...projectConfig } = type === 'system'
+        ? { system: loadSystemConfig() }
+        : (await import('./state/index.js')).default.config;
+    if (type === 'all' || type === 'system') {
+        console.log('System Configuration');
+        console.table(systemConfig);
+    }
+
+    if (type === 'all') {
+        console.log('');
+    }
+
+    if (type === 'all' || type === 'project') {
+        console.log(`Project Configuration (paths relative to ${projectConfig.paths.base})`);
+        console.table(flattenConfigForTable(projectConfig, { base: projectConfig.paths.base }));
+    }
+}

package/src/state/index.js

@@ -1,7 +1,9 @@
 import fs from 'node:fs';
 import loadJson from '../utils/loadJson.js';
 import writeJson from '../utils/writeJson.js';
-import { TARGETS, targetPathOf, nodeAddonNamesOf, nativeCommandNamesOf } from '../utils/targets.js';
+import {
+    TARGETS, targetPathOf, nodeAddonNamesOf, nativeCommandNamesOf, wasiNamesOf, appNamesOf,
+} from '../utils/targets.js';
 import { findCargoModuleImportsIn, writeCargoMarker } from '../utils/cargoImport.js';
 import { exportWasiSdkPath } from '../utils/wasiToolchain.js';
 import loadConfig, { assertBinarySelection } from './loadConfig.js';
@@ -33,6 +35,7 @@ async function initProcessState() {
         DOCKER_REGISTRY_MIRROR: 'CROSSBIND_REGISTRY_MIRROR',
         DOCKER_IMAGE_WEB: 'CROSSBIND_IMAGE_WEB',
         DOCKER_IMAGE_ANDROID: 'CROSSBIND_IMAGE_ANDROID',
+        DOCKER_IMAGE_ANDROID_APP: 'CROSSBIND_IMAGE_ANDROID_APP',
         DOCKER_IMAGE_LINUX: 'CROSSBIND_IMAGE_LINUX',
         DOCKER_IMAGE_WINDOWS: 'CROSSBIND_IMAGE_WINDOWS',
     }).forEach(([key, envKey]) => {
@@ -52,8 +55,7 @@ async function initProcessState() {
             target.dataTxtName = `${state.config.general.name}-${target.path}.${target.runtimeEnv}.data.txt`;
         }
         if (target.platform === 'wasi') {
-            // A wasi build is a single command module - no JS glue, no preload.
-            target.wasmName = `${state.config.general.name}-${target.path}.wasm`;
+            Object.assign(target, wasiNamesOf(target, state.config.general.name));
         }
         if (target.runtimeEnv === 'node' && target.platform !== 'wasm') {
             Object.assign(target, nodeAddonNamesOf(target, state.config.general.name));
@@ -61,6 +63,9 @@ async function initProcessState() {
         if (target.runtimeEnv === 'native') {
             Object.assign(target, nativeCommandNamesOf(target, state.config.general.name));
         }
+        if (target.runtimeEnv === 'app') {
+            Object.assign(target, appNamesOf(target, state.config.general.name));
+        }
     });
 
     setAllDependecyPaths();

package/src/state/loadConfig.js

@@ -1,6 +1,5 @@
-import os from 'node:os';
 import fs from 'node:fs';
-import systemKeys from '../utils/systemKeys.js';
+import loadSystemConfig, { systemConfigPath } from '../utils/systemConfig.js';
 import loadJs from '../utils/loadJs.js';
 import {
     resolveDependencyOverride, resolveDependencyReplace, restampIdentity, resolveExcludedNames, getOverrideKey,
@@ -32,7 +31,7 @@ export function assertBinarySelection(config) {
 export default async function loadConfig(configDir = process.cwd(), configName = 'crossbind.config') {
     const config = await loadJs(configDir, configName) || {};
     if (config.excludedDependencies?.length) {
-        logger.info('crossbind: `excludedDependencies` in crossbind.config.js is no longer read — declare exclusions in crossbind.overrides.js as { <name>: false }.');
+        logger.info('crossbind: `excludedDependencies` in crossbind.config.js is no longer read — declare exclusions in crossbind.overrides.js as { <name>: { exclude: true } }.');
     }
     const overrides = await loadJs(configDir, 'crossbind.overrides');
     const exclude = resolveExcludedNames(overrides);
@@ -83,14 +82,8 @@ export default async function loadConfig(configDir = process.cwd(), configName =
         }
     });
 
-    output.paths.systemConfig = `${os.homedir()}/.crossbind.json`;
-    output.system = loadJson(output.paths.systemConfig) || {};
-
-    Object.entries(systemKeys).forEach(([key, value]) => {
-        if (!(key in output.system)) {
-            output.system[key] = value.default;
-        }
-    });
+    output.paths.systemConfig = systemConfigPath();
+    output.system = loadSystemConfig();
 
     return output;
 }
@@ -140,6 +133,8 @@ export function getFilledConfig(config, options = { isDepend: false }) {
         targetSpecs: config.targetSpecs || [],
         build: config.build || {},
         target: config.target || {},
+        // An app's identity: its bundle id, and on iOS the Apple team that signs it.
+        app: config.app || {},
         extensions: config.extensions || [],
         package: null,
         functions: config.functions || {},

package/src/utils/appRustCrates.js

@@ -1,5 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import state from '../state/index.js';
+import { followCargoLock, recordCargoLock } from './cargoLock.js';
 import { cargoTripleFor } from './cargoTarget.js';
 import { isMtWasm, assertMtRustToolchain, cargoTargetDirFor, cargoBuildInvocation } from './rustMt.js';
 import runCargo from './runCargo.js';
@@ -78,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]',
@@ -110,6 +114,7 @@ export default function buildAppRustCrates(target, cacheDir, cargoDependencies =
         manifestPath: `${superDir}/Cargo.toml`,
         sysroot,
     });
+    followCargoLock(state.config.paths.project, superDir);
     const build = runCargo(args, {
         rustflags, panic, allowUnstable, target,
     });
@@ -118,5 +123,6 @@ export default function buildAppRustCrates(target, cacheDir, cargoDependencies =
     }
     const libFile = `${targetDir}/${triple}/release/libcrossbind_app_super.a`;
     if (!fs.existsSync(libFile)) throw new Error(`crossbind: expected cargo output ${libFile} not found`);
+    recordCargoLock(state.config.paths.project, superDir);
     return [libFile];
 }

package/src/utils/bridgeExtras.js

@@ -4,14 +4,16 @@ import { parseMacroDump, stripComments, declaresAtFileScope } from './swigInterf
 // SWIG binds no function-like macro, variadic function or mutable global. crossbind binds them for the names an app
 // imports by name: a function-like macro takes the parameter types of the one function it calls, a macro naming a
 // function binds that function under its own name, a variadic function takes its extra arguments by their JavaScript
-// type, and a mutable global binds as a handle to its address. A macro binds only through a function SWIG bound, the
-// one place that proves the name is a single declared function.
+// type, a mutable global binds as a handle to its address, and a constant SWIG drops for a cast in its value binds as
+// the number the compiler makes of it. A macro binds only through a function SWIG bound, the one place that proves the
+// name is a single declared function.
 
 const C_IDENTIFIER = /^[A-Za-z_]\w*$/;
 const MACRO_LINE = /^\/\/ crossbind:macro ([A-Za-z_]\w*) (#define .*)$/gm;
 const ALIAS_LINE = /^\/\/ crossbind:alias ([A-Za-z_]\w*) ([A-Za-z_]\w*)$/gm;
+const CONSTANT_LINE = /^\/\/ crossbind:constant ([A-Za-z_]\w*)$/gm;
 const NOTE_MARKER = '// crossbind:note ';
-const EXTRA_LINES = /^(?:\/\/ crossbind:(?:macro|alias|note) .*\n)+\n/m;
+const EXTRA_LINES = /^(?:\/\/ crossbind:(?:macro|alias|constant|note) .*\n)+\n/m;
 // The arguments one call may add to a variadic function: each registration count dispatches over 2^n argument kinds.
 const MAX_VARIADIC_ARGUMENTS = 6;
 const VARIADIC_WARNING = /^Variable length arguments are not supported by embind, (\S+) skipped\.$/;
@@ -90,9 +92,66 @@ export function macroCall(macro) {
 // The identifier an object-like macro stands for, as in `#define iconv_open libiconv_open`.
 const identifierOf = (macro) => (macro && !macro.params && C_IDENTIFIER.test(macro.body) ? macro.body : null);
 
+const NUMBER_TYPE_WORDS = new Set(['unsigned', 'signed', 'short', 'long', 'int', 'char', 'float', 'double', 'bool', '_Bool']);
+const NUMBER_TYPEDEFS = new Set([
+    'size_t', 'ssize_t', 'ptrdiff_t', 'intptr_t', 'uintptr_t', 'intmax_t', 'uintmax_t', 'off_t', 'wchar_t',
+    'int8_t', 'uint8_t', 'int16_t', 'uint16_t', 'int32_t', 'uint32_t', 'int64_t', 'uint64_t',
+]);
+const VALUE_TOKEN = /0[xX][\dA-Fa-f]+[uUlL]*|\d+(?:\.\d*)?(?:[eE][-+]?\d+)?[uUlLfF]*|'(?:\\.|[^'\\])+'|[A-Za-z_]\w*|<<|>>|\S/g;
+const OPERATOR = /^(?:<<|>>|[-+*/%&|^~!()<>=?:])$/;
+const LITERAL = /^(?:\d|')/;
+const CAST_OPERAND = /^(?:\d|'|[-+~!(])/;
+
+// A type named by number words, a standard number typedef, or a typedef of one that the header declares.
+function isNumberType(words, headerText, depth = 0) {
+    if (words.every((word) => NUMBER_TYPE_WORDS.has(word))) return true;
+    if (words.length !== 1 || depth > 3) return false;
+    if (NUMBER_TYPEDEFS.has(words[0])) return true;
+    const declared = stripComments(headerText).match(new RegExp(`\\btypedef\\s+([A-Za-z_][\\w\\s]*?)\\s+${words[0]}\\s*;`));
+    return Boolean(declared) && isNumberType(declared[1].trim().split(/\s+/), headerText, depth + 1);
+}
+
+// The tokens of an object-like macro's value with the object-like macros in it spelled out; null for anything else.
+function expandedTokens(name, macros, depth = 0) {
+    const macro = macros.get(name);
+    if (!macro || macro.params || depth > 16) return null;
+    const tokens = [];
+    for (const token of macro.body.match(VALUE_TOKEN) ?? []) {
+        if (!C_IDENTIFIER.test(token) || !macros.has(token)) {
+            tokens.push(token);
+            continue;
+        }
+        const inner = expandedTokens(token, macros, depth + 1);
+        if (!inner) return null;
+        tokens.push('(', ...inner, ')');
+    }
+    return tokens;
+}
+
+// SWIG drops a #define whose value holds a name, so every cast. A value of numbers, operators and casts binds through
+// the compiler when every cast is to a number type: { numbers }, or null for a value with no cast or with other names.
+function castConstant(name, macros, headerText) {
+    const tokens = expandedTokens(name, macros);
+    if (!tokens) return null;
+    let casts = 0;
+    let numbers = true;
+    for (let at = 0; at < tokens.length; at += 1) {
+        if (LITERAL.test(tokens[at]) || OPERATOR.test(tokens[at])) continue;
+        const close = tokens.indexOf(')', at);
+        const words = tokens.slice(at, close);
+        const isCast = tokens[at - 1] === '(' && close > at && CAST_OPERAND.test(tokens[close + 1] ?? '')
+            && words.every((word) => word === '*' || C_IDENTIFIER.test(word));
+        if (!isCast) return null;
+        casts += 1;
+        numbers &&= !words.includes('*') && isNumberType(words, headerText);
+        at = close;
+    }
+    return casts ? { numbers } : null;
+}
+
 // What the interface carries for the names an app imports by name, read by the bridge once SWIG has run: their
 // function-like macros and their macros naming a function, and the functions they reach, which SWIG has to bind.
-export function interfaceExtras(names, macros) {
+export function interfaceExtras(names, macros, headerText = '') {
     if (names === ALL_NAMES || !names.length) return { lines: [], functions: [] };
     const lines = [];
     const functions = [];
@@ -104,6 +163,10 @@ export function interfaceExtras(names, macros) {
             if (target && target !== name && !macros.has(target) && !C_KEYWORDS.has(target)) {
                 lines.push(`// crossbind:alias ${name} ${target}`);
                 functions.push(target);
+            } else {
+                const constant = castConstant(name, macros, headerText);
+                if (constant?.numbers) lines.push(`// crossbind:constant ${name}`);
+                else if (constant) lines.push(`${NOTE_MARKER}${name}: a constant whose value has a cast binds only when every cast is to a number type the header declares; skipped.`);
             }
             continue;
         }
@@ -168,7 +231,8 @@ export function bridgeExtras({ interfaceText = '', named = [], bridgeText = '',
     const globalWarnings = warningsAbout(warnings, GLOBAL_WARNING, imported);
     const globals = [...globalWarnings.keys()].filter((name) => declaresAtFileScope(headerText, name));
     const answered = new Set([...variadics.map((name) => variadicWarnings.get(name)), ...globals.map((name) => globalWarnings.get(name))]);
-    if (!macros.length && !aliases.length && !variadics.length && !globals.length) return { code: '', exports: [], answered, notes };
+    const constants = [...interfaceText.matchAll(CONSTANT_LINE)].map(([, name]) => name).filter((name) => !bridgeText.includes(`bindConstant("${name}"`));
+    if (!macros.length && !aliases.length && !variadics.length && !globals.length && !constants.length) return { code: '', exports: [], answered, notes };
 
     // The macros register ahead of the fallbacks below, which would make a function a variadic shares its name with an
     // overload set.
@@ -184,10 +248,13 @@ export function bridgeExtras({ interfaceText = '', named = [], bridgeText = '',
         `EMSCRIPTEN_BINDINGS(CrossbindExtras_${module}) {`,
         ...variadics.map((name) => `  { using F = decltype(crossbind::variadicType(&${name}, 0)); crossbind::bindVariadic<F, static_cast<F>(&${name}), ${MAX_VARIADIC_ARGUMENTS}>("${name}"); }`),
         ...globals.map((name) => `  crossbind::bindGlobal("${name}", &${name});`),
+        ...constants.map((name) => `  crossbind::bindConstant("${name}", ${name});`),
         '}',
         '',
     ].join('\n');
-    const exports = [...macros.map(({ name }) => name), ...aliases.map(({ name }) => name), ...variadics, ...globals, ...(variadics.length ? ['vaDouble'] : [])];
+    const exports = [
+        ...macros.map(({ name }) => name), ...aliases.map(({ name }) => name), ...variadics, ...globals, ...constants, ...(variadics.length ? ['vaDouble'] : []),
+    ];
     return { code, exports, answered, notes };
 }
 
@@ -261,6 +328,7 @@ template<typename R> constexpr bool isJsResult = std::is_void_v<R> || isJsArgume
 template<typename T> auto argumentFromJs(const emscripten::val &value) {
   using U = std::remove_cv_t<T>;
   if constexpr (std::is_same_v<U, const char *>) return fromJsCString<const char>(value);
+  else if constexpr (isFunctionPointer<U>) return fromJsCallback<U>(value);
   else if constexpr (std::is_pointer_v<U>) return fieldFromJs<U>(value);
   else if constexpr (std::is_same_v<U, bool>) {
     double number = 0;

package/src/utils/cargoLock.js

@@ -0,0 +1,19 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import writeIfChanged from './writeIfChanged.js';
+
+// The versions of every crate the app's Rust links, next to crossbind.config.js and committed like conan.lock, since
+// the manifests cargo resolves are generated under the cache. Not Cargo.lock: a package whose crate sits at the
+// project root already has one.
+const lockOf = (projectDir) => path.join(projectDir, 'crossbind.cargo.lock');
+
+// Before cargo resolves a generated manifest, so it keeps every version the project pins.
+export function followCargoLock(projectDir, manifestDir) {
+    const lock = lockOf(projectDir);
+    if (fs.existsSync(lock)) writeIfChanged(path.join(manifestDir, 'Cargo.lock'), fs.readFileSync(lock, 'utf8'));
+}
+
+// After a build: what cargo resolved, a crate the lock did not list yet included.
+export function recordCargoLock(projectDir, manifestDir) {
+    writeIfChanged(lockOf(projectDir), fs.readFileSync(path.join(manifestDir, 'Cargo.lock'), 'utf8'));
+}

package/src/utils/cppDts.js

@@ -225,6 +225,8 @@ export function emitCppDts(model, exportNames, mode = 'sync') {
         for (const method of cls.methods) {
             out.push(`    ${method.isStatic ? 'static ' : ''}${method.name}(${method.args.map((a) => `${a.name}: ${a.type}`).join(', ')}): ${wrap(method.ret)};`);
         }
+        // Frees the object now instead of when the garbage collector reclaims the handle (lifecycle-and-types.md).
+        out.push(`    delete(): ${wrap('void')};`);
         out.push('}');
     }
     for (const name of exportNames) {

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/embindObjectLifetime.js

@@ -0,0 +1,35 @@
+// embind frees an object when JavaScript's handle to it is collected only behind a smart pointer. A value a call
+// returns, which embind copied for JavaScript, and an object JavaScript made through a raw constructor (a vector, a
+// Rust class) were freed by .delete() alone, though they are as much JavaScript's own. This rewrite marks both on the
+// count a handle shares with its clones and gives them the same finalizer. A copy is known only where its converter
+// makes the handle, since embind then types the handle as a pointer to the object's own class. A raw pointer stays
+// its library's. The debug glue's leak warning goes: a collected handle is freed by design. Without
+// FinalizationRegistry (Hermes) nothing is registered, as before.
+
+// The release glue spells each on one line, the debug glue one statement per line with comments.
+const FINALIZER = /if\s*\(hasSmartPtr\)\s*\{[\s\S]*?finalizationRegistry\.register\(handle,\s*info,\s*handle\);?/;
+const OWNED_FINALIZER = 'if(hasSmartPtr||$$.count.owned){finalizationRegistry.register(handle,{$$},handle);';
+const LEAK_WARNING = /console\.warn\(info\.leakWarning\);?\s*/;
+const FROM_WIRE = /function RegisteredPointer_fromWireType\(ptr\)\s*\{/g;
+const OWN_FROM_WIRE = 'function crossbindOwnHandle(handle){var $$=handle.$$;if(!$$.smartPtr&&!$$.count.owned){$$.count.owned=true;'
+    + 'if(finalizationRegistry)finalizationRegistry.register(handle,{$$},handle)}return handle}'
+    + 'function RegisteredPointer_fromWireType(ptr){var handle=crossbindHandleFromWire.call(this,ptr);'
+    + 'return this.isReference&&handle?crossbindOwnHandle(handle):handle}'
+    + 'function crossbindHandleFromWire(ptr){';
+const CONSTRUCTED = /return body\.apply\(this,\s*args\);?/g;
+const OWN_CONSTRUCTED = 'return crossbindOwnHandle(body.apply(this,args));';
+
+const count = (text, pattern) => text.match(pattern)?.length ?? 0;
+
+// Returns the rewritten glue and whether it holds embind classes this rewrite does not recognise.
+export function releaseOwnedHandles(glue) {
+    if (!glue.includes('attachFinalizer')) return { text: glue, missed: false };
+    const recognised = count(glue, FROM_WIRE) === 1 && count(glue, CONSTRUCTED) === 1;
+    // Functions, not strings: `$$` in a replacement string is a lone `$`.
+    const text = glue
+        .replace(FINALIZER, () => OWNED_FINALIZER)
+        .replace(LEAK_WARNING, '')
+        .replace(FROM_WIRE, () => OWN_FROM_WIRE)
+        .replace(CONSTRUCTED, () => OWN_CONSTRUCTED);
+    return { text, missed: !recognised || !text.includes(OWNED_FINALIZER) };
+}

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',
+};