crossbind 2.0.0-beta.67 → 2.0.0-beta.69

package/README.md

@@ -6,9 +6,9 @@
   <h1>crossbind</h1>
 
   <p>
-    <strong>Import C++ and Rust like JavaScript modules.</strong><br>
+    <strong>Build and ship JS apps. Add C++ and Rust as needed.</strong><br>
     Build, package, and run native libraries across browsers, Node.js, edge
-    runtimes, iOS, Android, and WASI.
+    runtimes, iOS, Android, and WASI, or ship them in a desktop or mobile app.
   </p>
 
   <p>
@@ -28,10 +28,12 @@
 </div>
 
 crossbind makes native libraries as easy to distribute and consume as
-JavaScript packages. A C++ header, an app-local Rust file, or a declared Cargo
-crate becomes an importable module; crossbind generates the binding layer,
-resolves the transitive native dependency graph, and selects the right artifact
-for every target.
+JavaScript packages. A C++ header, an app-local Rust file, a declared Cargo
+crate, or a ConanCenter package becomes an importable module; crossbind
+generates the binding layer, resolves the transitive native dependency graph,
+and selects the right artifact for every target. It also builds a web page and
+the native code it imports into an app for macOS, Linux, Windows, iOS, and
+Android.
 
 > **Note** — crossbind 2.0 is currently published on the npm `beta` channel.
 > The commands below use `@beta` deliberately.
@@ -133,11 +135,13 @@ native call:
 import { initNative, hello } from './native/hello.h';
 
 await initNative();
-console.log(hello('crossbind'));
+console.log(await hello('crossbind'));
 ```
 
 `initNative()` is exported by every generated native module. One call starts
-the runtime and binds all native modules imported by the application.
+the runtime and binds all native modules imported by the application. In a
+browser the module runs in a Web Worker by default, so each call returns a
+promise.
 
 ## Add crossbind to an existing Vite app
 
@@ -177,8 +181,8 @@ or start from the closest project in [`examples/`](https://github.com/crossbind/
 ## How it works
 
 ```text
-  C++ / Rust source                        header, .rs, or
-  or prebuilt port                         cargo: import
+  C++ / Rust source                        header, .rs, cargo:
+  or prebuilt port                         or conan: import
           |                                       |
           v                                       |
   versioned native package graph                  |
@@ -191,11 +195,13 @@ or start from the closest project in [`examples/`](https://github.com/crossbind/
                     + binding generation
                    + native build and link
                               |
-        +---------------------+---------------------+
-        |                     |                     |
-        v                     v                     v
-  browser / Node / edge   iOS / Android            WASI
-  JavaScript + Wasm       native library + JSI     command component
+                              v
+  browser, Node.js, edge     JavaScript + Wasm
+  Node.js, Electron          Node-API addon
+  iOS, Android               native library + JSI
+  desktop and mobile apps    your page + native host
+  macOS, Linux, Windows      native executable
+  WASI runtimes              command component
 ```
 
 There are two configuration surfaces:
@@ -212,18 +218,21 @@ contract.
 
 ## Runtimes
 
-| Runtime      | Output                                | Important behavior                                                                    |
-| ------------ | ------------------------------------- | ------------------------------------------------------------------------------------- |
-| Browser      | JavaScript loader + WebAssembly       | Single-threaded by default; multithreaded builds need COOP/COEP headers in production |
-| Node.js      | JavaScript loader + WebAssembly       | Supports CommonJS or ESM and reads the host filesystem                                |
-| Edge         | JavaScript loader + WebAssembly       | Single-threaded, memory-backed, with no OPFS or nested worker mode                    |
-| React Native | Native iOS/Android libraries over JSI | No WebAssembly or browser isolation headers                                           |
-| WASI         | One `wasm32-wasip3` command component | No JavaScript host; run with a compatible WASI runtime such as wasmtime 47+           |
+| Runtime      | Output                                               | Important behavior                                                                      |
+| ------------ | ---------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| Browser      | JavaScript loader + WebAssembly                      | Single-threaded by default; multithreaded builds need COOP/COEP headers in production   |
+| Node.js      | JavaScript loader + WebAssembly, or a Node-API addon | Supports CommonJS or ESM and reads the host filesystem; the addon loads in Electron too |
+| Edge         | JavaScript loader + WebAssembly                      | Single-threaded, memory-backed, with no OPFS or nested worker mode                      |
+| React Native | Native iOS/Android libraries over JSI                | No WebAssembly or browser isolation headers                                             |
+| Apps         | An app for macOS, Linux, Windows, iOS, and Android   | The page runs in the system webview, native code in the app's own process; no Node.js   |
+| Executables  | Native programs for macOS, Linux, and Windows        | No JavaScript host                                                                      |
+| WASI         | One `wasm32-wasip3` command component                | No JavaScript host; run with a compatible WASI runtime such as wasmtime 47+             |
 
 Threading and worker execution are independent choices:
 
 - `target.runtime: 'mt'` enables a multithreaded build.
-- `initNative({ useWorker: true })` moves the module into a browser Web Worker.
+- Browsers run the module in a Web Worker by default;
+  `initNative({ useWorker: false })` keeps it on the page thread.
 - Browser OPFS persistence requires `useWorker: true`.
 - Browser `mt` builds require COOP/COEP response headers in production.
 
@@ -304,7 +313,7 @@ for the supported type surface and configuration.
 ## Documentation
 
 - [Guide](https://crossbind.dev/guide/) — product concepts, quick start,
-  runtimes, bundlers, bindings, packages, and troubleshooting.
+  runtimes, apps, bundlers, bindings, packages, and troubleshooting.
 - [Runtime and configuration API](https://github.com/crossbind/crossbind/blob/main/docs/api/README.md)
   — canonical build-time and runtime behavior.
 - [Integration playbooks](https://github.com/crossbind/crossbind/blob/main/docs/playbooks/integration/README.md)

package/package.json

@@ -1,62 +1,72 @@
 {
-    "name": "crossbind",
-    "version": "2.0.0-beta.67",
-    "license": "MIT",
-    "homepage": "https://crossbind.dev",
-    "repository": "https://github.com/crossbind/crossbind.git",
-    "description": "Bind C++ to JavaScript without extra code. crossbind supports WebAssembly and React Native for cross-platform compatibility.",
-    "type": "module",
-    "engines": {
-        "node": ">=24"
+  "name": "crossbind",
+  "version": "2.0.0-beta.69",
+  "license": "MIT",
+  "homepage": "https://crossbind.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/crossbind/crossbind.git"
+  },
+  "description": "Bind C++ to JavaScript without extra code. crossbind supports WebAssembly and React Native for cross-platform compatibility.",
+  "type": "module",
+  "engines": {
+    "node": ">=26"
+  },
+  "bin": {
+    "crossbind": "./src/cli.js"
+  },
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./node/dev": "./src/node/dev.mjs",
+    "./app": {
+      "types": "./src/app/index.d.ts",
+      "default": "./src/app/index.js"
     },
-    "bin": {
-        "crossbind": "./src/cli.js"
+    "./app/core": {
+      "types": "./src/app/index.d.ts",
+      "default": "./src/app/index.js"
     },
-    "main": "src/index.js",
-    "exports": {
-        ".": "./src/index.js",
-        "./node/dev": "./src/node/dev.mjs",
-        "./app": {
-            "types": "./src/app/index.d.ts",
-            "default": "./src/app/index.js"
-        },
-        "./*": "./*"
-    },
-    "scripts": {
-        "test": "vitest run",
-        "test:watch": "vitest",
-        "test:coverage": "vitest run --coverage"
-    },
-    "devDependencies": {
-        "@vitest/coverage-v8": "^5.0.1",
-        "vitest": "^5.0.1"
-    },
-    "dependencies": {
-        "@rollup/plugin-commonjs": "^29.0.3",
-        "@rollup/plugin-json": "^6.1.0",
-        "@rollup/plugin-node-resolve": "^16.0.3",
-        "@rollup/plugin-virtual": "^3.0.2",
-        "comlink": "^4.4.2",
-        "commander": "^15.0.0",
-        "glob": "^13.0.6",
-        "log-update": "^8.0.0",
-        "picocolors": "^1.1.1",
-        "pngjs": "^7.0.0",
-        "replace": "^1.2.2",
-        "rollup": "^4.63.4",
-        "spdx-expression-parse": "^5.0.0",
-        "upath": "^3.0.8"
-    },
-    "keywords": [
-        "webassembly",
-        "react-native",
-        "bind",
-        "c++",
-        "emscripten",
-        "embind",
-        "swig",
-        "android",
-        "ios",
-        "mobile"
-    ]
-}
+    "./*": "./*"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^5.0.1",
+    "vitest": "^5.0.1"
+  },
+  "dependencies": {
+    "@rollup/plugin-commonjs": "^29.0.3",
+    "@rollup/plugin-json": "^6.1.0",
+    "@rollup/plugin-node-resolve": "^16.0.3",
+    "@rollup/plugin-virtual": "^3.0.2",
+    "comlink": "^4.4.2",
+    "commander": "^15.0.0",
+    "glob": "^14.0.3",
+    "log-update": "^8.0.0",
+    "picocolors": "^1.1.1",
+    "pngjs": "^7.0.0",
+    "replace": "^1.2.2",
+    "rollup": "^4.63.4",
+    "spdx-expression-parse": "^5.0.0",
+    "upath": "^3.0.8"
+  },
+  "optionalDependencies": {
+    "@crossbind/bridge-tools": "2.0.0-beta.69"
+  },
+  "keywords": [
+    "webassembly",
+    "react-native",
+    "bind",
+    "c++",
+    "emscripten",
+    "embind",
+    "swig",
+    "android",
+    "ios",
+    "mobile"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  }
+}

package/src/actions/addExtension.js

@@ -0,0 +1,191 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { configFileOf, writeExtension } from '../utils/configWriter.js';
+import { isUnderBase } from '../utils/replaceBasePathForDocker.js';
+import { ownPackages } from '../utils/appExtensions.js';
+import resolveAppHostRoot from '../utils/resolveAppHost.js';
+
+// The lockfiles by which a project names the package manager it is installed with.
+const LOCKFILES = [
+    ['pnpm-lock.yaml', 'pnpm'], ['yarn.lock', 'yarn'], ['bun.lock', 'bun'], ['bun.lockb', 'bun'],
+    ['package-lock.json', 'npm'], ['npm-shrinkwrap.json', 'npm'],
+];
+const MANAGERS = ['npm', 'pnpm', 'yarn', 'bun'];
+// A package as a registry names it, with a version, tag or range after an @; a tarball's file name is none.
+const REGISTRY_SPEC = /^((?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*)(?:@.+)?$/;
+const TARBALL = /\.(tgz|tar|tar\.gz)$/;
+// What a package may be given as on Windows, which runs npm, pnpm and yarn in a shell: nothing the shell reads more into.
+const WINDOWS_SPEC = /^[\w@/\\.~:+=#-]+$/;
+// What a package's crossbind.extension may name: a module of its own, as ./crossbind.extension.js.
+const EXTENSION_ENTRY = /^\.\/(?:[\w-][\w.-]*\/)*[\w-][\w.-]*\.m?js$/;
+
+// Whether a package's exports let another import a module of its by its subpath, as Node resolves one: a package
+// without exports gives every file, and one whose exports name no subpath gives its main module alone.
+function isExported(exports, entry) {
+    if (exports === undefined) return true;
+    if (exports === null || typeof exports !== 'object' || Array.isArray(exports)) return false;
+    if (Object.hasOwn(exports, entry)) return exports[entry] !== null;
+    const pattern = Object.keys(exports).filter((key) => key.startsWith('./') && key.includes('*'))
+        .sort((a, b) => b.length - a.length)
+        .find((key) => {
+            const [head, tail] = key.split('*');
+            return entry.length >= head.length + tail.length && entry.startsWith(head) && entry.endsWith(tail);
+        });
+    return pattern !== undefined && exports[pattern] !== null;
+}
+const DEPENDENCY_FIELDS = ['dependencies', 'devDependencies', 'optionalDependencies'];
+// The words module code keeps, which can name no import.
+const RESERVED = new Set(('arguments await break case catch class const continue debugger default delete do else enum eval '
+    + 'export extends false finally for function if implements import in instanceof interface let new null package private '
+    + 'protected public return static super switch this throw true try typeof var void while with yield').split(' '));
+
+const foldersUp = (dir) => (path.dirname(dir) === dir ? [dir] : [dir, ...foldersUp(path.dirname(dir))]);
+
+// The package manager a project is installed with: the one its nearest lockfile names, else the one that runs
+// crossbind, else npm.
+export function packageManagerOf(project, userAgent) {
+    for (const dir of foldersUp(project)) {
+        const lockfile = LOCKFILES.find(([file]) => fs.existsSync(path.join(dir, file)));
+        if (lockfile) return lockfile[1];
+    }
+    const launcher = userAgent?.split('/')[0];
+    return MANAGERS.includes(launcher) ? launcher : 'npm';
+}
+
+// The package a spec names on a registry, or null where it is a path, a tarball or a repository.
+export function registryName(spec) {
+    return TARBALL.test(spec) ? null : (REGISTRY_SPEC.exec(spec)?.[1] ?? null);
+}
+
+// The name a config imports an extension under: its package's, without the scope and an extension- prefix, in
+// camelCase, with Extension after a word module code keeps.
+export function importNameOf(packageName) {
+    const words = packageName.replace(/^@[^/]+\//, '').replace(/^(crossbind-)?extension-/, '').split(/[^a-zA-Z0-9]+/).filter(Boolean);
+    const camel = words.map((word, i) => (i === 0 ? word : `${word[0].toUpperCase()}${word.slice(1)}`)).join('');
+    if (!/^[a-zA-Z]/.test(camel)) return `extension${camel}`;
+    return RESERVED.has(camel) ? `${camel}Extension` : camel;
+}
+
+const dependencyNames = (manifest) => {
+    const pkg = JSON.parse(fs.readFileSync(manifest, 'utf8'));
+    return new Set(DEPENDENCY_FIELDS.flatMap((field) => Object.keys(pkg[field] ?? {})));
+};
+
+// The folder of an installed package, as Node finds it from the project: in the nearest node_modules that has it.
+const packageDir = (project, name) => foldersUp(project).map((dir) => path.join(dir, 'node_modules', name))
+    .find((dir) => fs.existsSync(path.join(dir, 'package.json')));
+
+const commonFolder = (a, b) => {
+    const [partsA, partsB] = [a.split(path.sep), b.split(path.sep)];
+    const length = partsA.findIndex((part, i) => part !== partsB[i]);
+    return partsA.slice(0, length === -1 ? partsA.length : length).join(path.sep) || path.sep;
+};
+
+// Installs the spec into the project with its package manager, as its owner would at a terminal.
+function install(manager, spec, project, platform, spawn) {
+    const args = [manager === 'npm' ? 'install' : 'add', spec];
+    const command = [manager, ...args].join(' ');
+    console.log(`crossbind: ${command}`);
+    // On Windows npm, pnpm and yarn are .cmd files, which a shell alone runs; WINDOWS_SPEC keeps what it reads out of the
+    // spec.
+    const result = platform === 'win32'
+        ? spawn(command, { cwd: project, stdio: 'inherit', shell: true })
+        : spawn(manager, args, { cwd: project, stdio: 'inherit' });
+    if (result.error) {
+        throw new Error(`crossbind: ${manager} did not start (${result.error.message}): install it, or install ${spec} with the package manager you use and run crossbind add with its name.`);
+    }
+    if (result.status !== 0) {
+        throw new Error(`crossbind: ${command} failed, so crossbind.config.js lists nothing new: install ${spec} yourself, then run crossbind add with its name.`);
+    }
+}
+
+// The spec as a package manager would take it, or why not: a spec that opens with a dash is an option to it.
+function assertSpec(spec, platform) {
+    if (spec.startsWith('-')) throw new Error(`crossbind: crossbind add takes a package, and ${spec} is an option to a package manager.`);
+    if (platform === 'win32' && !WINDOWS_SPEC.test(spec)) {
+        throw new Error(`crossbind: on Windows crossbind add takes a package's name, with a version or tag after an @, or its path, without spaces, quotes or ^&|<>%!() for the shell its package manager runs in to read: install ${spec} yourself, then run crossbind add with its name.`);
+    }
+}
+
+// An extension an app has by having the host is none to add. A project without a host yet has none of them.
+function assertNotOwn(spec) {
+    const name = registryName(spec);
+    let root;
+    try {
+        root = resolveAppHostRoot();
+    } catch {
+        return;
+    }
+    if (ownPackages(root).includes(name)) {
+        throw new Error(`crossbind: an app has ${name} by having @crossbind/core-app-host, which brings it, so there is nothing to add; an extension takes its place with replaces, as extensions.md says.`);
+    }
+}
+
+// The installed package the spec named: the one the install added to package.json, as a spec's own text names no package
+// for every package manager, else the one a registry spec names, which package.json had already.
+function installedName(spec, before, after, manifest) {
+    const added = [...after].filter((name) => !before.has(name));
+    const registry = registryName(spec);
+    const name = added.length === 1 ? added[0] : (added.length === 0 && after.has(registry) && registry);
+    if (!name) {
+        throw new Error(`crossbind: crossbind add cannot tell which package ${spec} is, as ${manifest} gained ${added.length === 0 ? 'none' : 'more than one'}: run crossbind add with its name once this project's package.json lists it.`);
+    }
+    return { name, isAdded: added.length === 1 };
+}
+
+// Installs an extension's package into an app and lists it in crossbind.config.js's extensions; a package that
+// package.json has already, given by its name alone, is listed without installing it again.
+export default function addExtension(spec, {
+    config, env = process.env, platform = process.platform, spawn = spawnSync,
+}) {
+    if (config.target.runtimeEnv !== 'app') {
+        throw new Error("crossbind: an extension builds into an app, which this project is not: set target: { runtimeEnv: 'app' } in crossbind.config.js, as the desktop-app template does.");
+    }
+    assertSpec(spec, platform);
+    assertNotOwn(spec);
+    const { project, base } = config.paths;
+    const manifest = path.join(project, 'package.json');
+    if (!fs.existsSync(manifest)) throw new Error(`crossbind: crossbind add installs into the project's package.json, which ${project} has none of.`);
+    const manager = packageManagerOf(project, env.npm_config_user_agent);
+    const before = dependencyNames(manifest);
+    if (registryName(spec) === spec && before.has(spec)) console.log(`crossbind: package.json has ${spec} already.`);
+    else install(manager, spec, project, platform, spawn);
+    const { name, isAdded } = installedName(spec, before, dependencyNames(manifest), manifest);
+    const dir = packageDir(project, name);
+    if (!dir) throw new Error(`crossbind: ${name} is in package.json, but not installed: run ${manager} install.`);
+    const removal = isAdded ? ` ${manager} ${manager === 'npm' ? 'uninstall' : 'remove'} ${name} removes it.` : '';
+    const own = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+    const entry = own.crossbind?.extension;
+    if (typeof entry !== 'string') {
+        throw new Error(`crossbind: ${name} is installed, but it is no crossbind extension: its package.json has no crossbind.extension.${removal}`);
+    }
+    if (!EXTENSION_ENTRY.test(entry)) {
+        throw new Error(`crossbind: ${name}'s crossbind.extension, ${JSON.stringify(entry)}, is no module of its own as ./crossbind.extension.js is, so crossbind.config.js lists nothing new.${removal}`);
+    }
+    if (!fs.statSync(path.join(dir, entry), { throwIfNoEntry: false })?.isFile()) {
+        throw new Error(`crossbind: ${name}'s crossbind.extension names ${entry}, which its package has not, so crossbind.config.js lists nothing new.${removal}`);
+    }
+    if (!isExported(own.exports, entry)) {
+        throw new Error(`crossbind: ${name}'s package.json exports no ${entry}, which crossbind.config.js would import, so it lists nothing new: its exports has to give it, as "./crossbind.extension.js": "./crossbind.extension.js" does.${removal}`);
+    }
+    // A build sees paths.base alone, and an extension's root is where its files are, links followed.
+    const real = fs.realpathSync(dir);
+    if (!isUnderBase(real, base)) {
+        // A Windows project's path comes with forward slashes, its real path with backslashes.
+        const home = path.resolve(project);
+        const above = path.relative(home, commonFolder(home, real)).split(path.sep).join('/') || '.';
+        throw new Error(`crossbind: ${name} is in ${real}, outside paths.base, ${base}, which is all a build sees, so crossbind.config.js lists nothing new: set paths: { base: '${above}' } in it, a folder above both, and run crossbind add ${name} again.`);
+    }
+    const specifier = `${name}/${entry.slice(2)}`;
+    const identifier = importNameOf(name);
+    const written = writeExtension(project, specifier, identifier);
+    if (!written) {
+        throw new Error(`crossbind: ${name} is installed, but ${path.basename(configFileOf(project) ?? 'crossbind.config.js')} is no config crossbind can list it in safely: write import ${identifier} from '${specifier}' and extensions: [${identifier}()] into it yourself.`);
+    }
+    const file = path.basename(written.file);
+    console.log(written.isListed
+        ? `crossbind: ${file} lists ${name} already, as ${written.identifier}().`
+        : `crossbind: listed ${name} in ${file} as ${written.identifier}(), which crossbind app build builds in.`);
+    return { name, ...written };
+}

package/src/actions/androidGradle.js

@@ -8,11 +8,15 @@ import pullDockerImage, { getDockerImage } from '../utils/pullDockerImage.js';
 import { DOCKER_BASE, isUnderBase } from '../utils/replaceBasePathForDocker.js';
 import { DOCKER_RUN_SECURITY_ARGS } from '../utils/dockerSecurity.js';
 import { getContentHash } from '../utils/hash.js';
+import { readSecret } from '../utils/keychain.js';
+import { secretFile } from '../utils/secretFile.js';
 
 const ROLE = 'android-app';
 const PLATFORM = 'linux/amd64';
 const KEYSTORE = '/tmp/crossbind/keystore';
-const GRADLE = ['gradle', '--offline', '--no-watch-fs', '--console=plain', '-q'];
+// An extension's Kotlin compiles inside Gradle's own process: with the container's home /, the Kotlin daemon's client
+// walked files for hours looking for a daemon to use.
+const GRADLE = ['gradle', '--offline', '--no-watch-fs', '--console=plain', '-q', '-Pkotlin.compiler.execution.strategy=in-process'];
 const OUTPUT_LIMIT = 64 * 1024 * 1024;
 const FAILURE_LINES = 40;
 
@@ -25,8 +29,12 @@ export const SIGNING = {
 };
 
 const listed = (names) => `${names.join(' and ')} ${names.length > 1 ? 'are' : 'is'}`;
+// A keystore's base64 text, as CI's secrets give it, in place of its file's path: no path runs to a hundred of base64's
+// letters alone.
+const KEYSTORE_TEXT = /^[A-Za-z0-9+/=\s]{100,}$/;
 
-// The keystore of the upload key, or null for none: a release is then signed with the debug key.
+// The keystore of the upload key, or null for none: a release is then signed with the debug key. The keystore is its
+// file, or its base64 text, which goes to a file for the image to mount.
 export function releaseSigning(env = process.env) {
     if (!env[SIGNING.keystore]) {
         const stray = [SIGNING.alias, SIGNING.password, SIGNING.keyPassword].filter((name) => env[name]);
@@ -35,11 +43,32 @@ export function releaseSigning(env = process.env) {
     }
     const missing = [SIGNING.alias, SIGNING.password].filter((name) => !env[name]);
     if (missing.length) throw new Error(`crossbind: ${SIGNING.keystore} is set, but ${listed(missing)} not.`);
-    const file = path.resolve(env[SIGNING.keystore]);
+    const given = env[SIGNING.keystore];
+    const isText = !fs.existsSync(given) && KEYSTORE_TEXT.test(given);
+    const file = isText ? secretFile('upload.keystore', Buffer.from(given.replace(/\s/g, ''), 'base64')) : path.resolve(given);
     if (!fs.statSync(file, { throwIfNoEntry: false })?.isFile()) throw new Error(`crossbind: ${SIGNING.keystore} names ${file}, which is no file.`);
     return { file, names: [SIGNING.alias, SIGNING.password, SIGNING.keyPassword].filter((name) => env[name]) };
 }
 
+// This machine's upload key, which ~/.crossbind.json names, for a build whose environment names none: its file and alias,
+// and its password from the environment, else the keychain, else none yet.
+export function machineUploadKey(env = process.env, system = state.config.system ?? {}) {
+    if (env[SIGNING.keystore] || !system.ANDROID_KEYSTORE) return null;
+    return {
+        keystore: system.ANDROID_KEYSTORE,
+        alias: env[SIGNING.alias] || system.ANDROID_KEY_ALIAS || 'upload',
+        password: env[SIGNING.password] || readSecret(path.resolve(system.ANDROID_KEYSTORE)),
+    };
+}
+
+// The environment a build signs with this machine's upload key in.
+export function uploadKeyEnv({ keystore, alias, password }) {
+    if (!password) {
+        throw new Error(`crossbind: this machine's upload key, ${keystore}, needs its password: set ${SIGNING.password}, or build on a terminal, which asks for it.`);
+    }
+    return { [SIGNING.keystore]: keystore, [SIGNING.alias]: alias, [SIGNING.password]: password };
+}
+
 // Gradle's caches and the Android tools' home outlive a container; the second keeps the debug key, which a new one would
 // replace, so that a later build still installs over the last.
 function homes() {
@@ -47,11 +76,16 @@ function homes() {
     return [[path.join(root, 'gradle'), '/var/cache/crossbind/gradle'], [path.join(root, 'home'), '/var/cache/crossbind/android']];
 }
 
-// A container of crossbind's android-app image, with no network: the project under the build's base, the homes, and
-// the keystore read-only, its passwords passed by name from this environment.
-function containerArgs(signing) {
+// A project whose extensions ask Maven for libraries carries the verification metadata of every file it resolves, and
+// resolves what the image's cache lacks online; any other builds offline against the cache alone.
+const isOnline = (project) => fs.existsSync(path.join(project, 'gradle', 'verification-metadata.xml'));
+const gradleOf = (project) => (isOnline(project) ? GRADLE.filter((arg) => arg !== '--offline') : GRADLE);
+
+// A container of crossbind's android-app image, with no network but for an online project: the project under the
+// build's base, the homes, and the keystore read-only, its passwords passed by name from this environment.
+function containerArgs(signing, isNetworked = false) {
     return [
-        ...DOCKER_RUN_SECURITY_ARGS, '--network', 'none', '--platform', PLATFORM, '--user', getOsUserAndGroupId(),
+        ...DOCKER_RUN_SECURITY_ARGS, ...(isNetworked ? [] : ['--network', 'none']), '--platform', PLATFORM, '--user', getOsUserAndGroupId(),
         '-v', `${state.config.paths.base}:${DOCKER_BASE}`,
         ...homes().flatMap(([host, container]) => {
             fs.mkdirSync(host, { recursive: true });
@@ -61,8 +95,8 @@ function containerArgs(signing) {
     ];
 }
 
-function docker(args, what) {
-    const result = spawnSync('docker', args, { encoding: 'utf8', maxBuffer: OUTPUT_LIMIT });
+function docker(args, what, env = process.env) {
+    const result = spawnSync('docker', args, { encoding: 'utf8', maxBuffer: OUTPUT_LIMIT, env });
     if (result.error) throw new Error(`crossbind: cannot run docker for ${what}: ${result.error.message}`, { cause: result.error });
     if (result.status !== 0) {
         const output = `${result.stdout ?? ''}${result.stderr ?? ''}`.trim().split('\n').slice(-FAILURE_LINES).join('\n');
@@ -79,43 +113,53 @@ function inContainer(project) {
     return path.posix.join(DOCKER_BASE, ...path.relative(state.config.paths.base, dir).split(path.sep));
 }
 
-// An Android app as the files it ships: its release APK, and with an upload key also the bundle Google Play takes, beside
-// the Gradle project as <project>.apk and <project>.aab.
+// An Android app as the files it ships: its release APK, and with an upload key, the environment's or this machine's,
+// also the bundle Google Play takes, beside the Gradle project as <project>.apk and <project>.aab.
 export function packageAndroidRelease(project) {
-    const signing = releaseSigning();
+    const key = machineUploadKey();
+    const env = key ? { ...process.env, ...uploadKeyEnv(key) } : process.env;
+    const signing = releaseSigning(env);
     pullDockerImage(ROLE, PLATFORM);
-    docker(['run', '--rm', ...containerArgs(signing), '-w', inContainer(project), getDockerImage(ROLE, PLATFORM),
-        ...GRADLE, '--no-daemon', 'assembleRelease', ...(signing ? ['bundleRelease'] : [])], `packaging ${path.basename(project)}`);
+    docker(['run', '--rm', ...containerArgs(signing, isOnline(project)), '-w', inContainer(project), getDockerImage(ROLE, PLATFORM),
+        ...gradleOf(project), '--no-daemon', 'assembleRelease', ...(signing ? ['bundleRelease'] : [])], `packaging ${path.basename(project)}`, env);
     const outputs = `${project}/app/build/outputs`;
     fs.copyFileSync(`${outputs}/apk/release/app-release.apk`, `${project}.apk`);
     fs.rmSync(`${project}.aab`, { force: true });
+    // The zip of native debug symbols Google Play takes, each ABI's libraries at its root, which the image's JDK makes.
+    fs.rmSync(`${project}-symbols.zip`, { force: true });
+    if (fs.existsSync(`${project}/symbols`)) {
+        docker(['run', '--rm', ...containerArgs(null), '-w', inContainer(project), getDockerImage(ROLE, PLATFORM),
+            'jar', '--create', '--no-manifest', '--file', `../${path.basename(project)}-symbols.zip`, '-C', 'symbols', '.'], `zipping the symbols of ${path.basename(project)}`);
+    }
     if (signing) {
         fs.copyFileSync(`${outputs}/bundle/release/app-release.aab`, `${project}.aab`);
     } else {
-        console.warn(`crossbind: ${path.basename(project)}.apk is signed with this machine's debug key: it installs for testing, and Google Play takes no app signed so. Set ${SIGNING.keystore}, ${SIGNING.alias} and ${SIGNING.password} to sign it with your upload key and make the bundle too.`);
+        console.warn(`crossbind: ${path.basename(project)}.apk is signed with this machine's debug key: it installs for testing, and Google Play takes no app signed so. crossbind app upload-key makes an upload key, which signs it and makes the bundle too; or set ${SIGNING.keystore}, ${SIGNING.alias} and ${SIGNING.password} to sign it with yours.`);
     }
 }
 
 // During development one container per project, whose Gradle daemon stays warm from one build to the next; it goes with
-// the process.
+// the process, and comes anew when the project comes to need the network, or no longer does.
 let devContainer = null;
 
-function startDevContainer() {
+function startDevContainer(isNetworked) {
     const name = `crossbind-android-app-${getContentHash(state.config.paths.project).slice(0, 12)}`;
     pullDockerImage(ROLE, PLATFORM);
-    // One a crashed session left behind holds the name.
+    // One a crashed session, or the project's need of the network before, left behind holds the name.
     spawnSync('docker', ['rm', '--force', name], { stdio: 'ignore' });
-    docker(['run', '--detach', '--rm', '--init', '--name', name, ...containerArgs(null), getDockerImage(ROLE, PLATFORM), 'sleep', 'infinity'],
+    docker(['run', '--detach', '--rm', '--init', '--name', name, ...containerArgs(null, isNetworked), getDockerImage(ROLE, PLATFORM), 'sleep', 'infinity'],
         'starting the development container');
-    process.once('exit', () => spawnSync('docker', ['rm', '--force', name], { stdio: 'ignore' }));
-    // A closed terminal ends the session through its exit hooks, as Ctrl-C does.
-    process.once('SIGHUP', () => process.exit(129));
-    return name;
+    if (!devContainer) {
+        process.once('exit', () => spawnSync('docker', ['rm', '--force', name], { stdio: 'ignore' }));
+        // A closed terminal ends the session through its exit hooks, as Ctrl-C does.
+        process.once('SIGHUP', () => process.exit(129));
+    }
+    return { name, isNetworked };
 }
 
 // Builds an Android app's Gradle project as a debug APK, signed with the debug key the homes keep, and returns the APK.
 export function buildApk(project) {
-    devContainer ??= startDevContainer();
-    docker(['exec', '-w', inContainer(project), devContainer, ...GRADLE, 'assembleDebug'], `building ${path.basename(project)}`);
+    if (devContainer?.isNetworked !== isOnline(project)) devContainer = startDevContainer(isOnline(project));
+    docker(['exec', '-w', inContainer(project), devContainer.name, ...gradleOf(project), 'assembleDebug'], `building ${path.basename(project)}`);
     return path.join(project, 'app', 'build', 'outputs', 'apk', 'debug', 'app-debug.apk');
 }