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

package/src/app/index.js

@@ -0,0 +1,184 @@
+// What an app's host does for its page: the dialogs that pick files or show a message, opening an address or a file
+// outside the app, the app's folders, quitting, its menus, the events of the app's native code and a desktop app's
+// updates. Each call goes to the host of an app (target.runtimeEnv: 'app'); in any other build it rejects, or events.on
+// throws. The app's native code calls the same through <crossbind/app.h>, but for the menus and events.on.
+
+const OPEN = { title: 'string', defaultPath: 'string', filters: 'filters', directory: 'boolean', multiple: 'boolean' };
+const SAVE = { title: 'string', defaultPath: 'string', defaultName: 'string', filters: 'filters' };
+const MESSAGE = { message: 'string', detail: 'string', kind: 'string', buttons: 'buttons' };
+const MESSAGE_KINDS = ['info', 'warning', 'error'];
+// Android's dialogs take three buttons at most.
+const MAX_BUTTONS = 3;
+
+// The app's crossbind.js, which initNative() loads, hands the calls to the host.
+function hostOf(member, name) {
+    const host = globalThis.Crossbind?.[member];
+    if (host) return host;
+    if (globalThis.Crossbind) throw new Error(`crossbind: this app's host is older than crossbind/app; update @crossbind/core-app-host to call ${name}`);
+    if (globalThis.__crossbind_token) throw new Error(`crossbind: ${name} works once the page has called initNative()`);
+    throw new Error(`crossbind: ${name} works in an app alone, whose crossbind.config.js sets target.runtimeEnv: 'app'`);
+}
+
+const call = (name, options) => hostOf('app', name)(name, options);
+
+const isFilters = (value) => Array.isArray(value) && value.every((filter) => typeof filter?.name === 'string'
+    && Array.isArray(filter.extensions) && filter.extensions.every((extension) => typeof extension === 'string'));
+
+// Spread reads a hole as undefined, which every() skips.
+const isButtons = (value) => Array.isArray(value) && value.length >= 1 && value.length <= MAX_BUTTONS
+    && [...value].every((label) => typeof label === 'string' && label !== '');
+
+// The lists an option may be, beside what typeof tells: how each is checked, and what it is called.
+const LISTS = {
+    filters: { isFitting: isFilters, name: 'list of { name, extensions }' },
+    buttons: { isFitting: isButtons, name: 'list of one to three labels' },
+};
+
+// The options as the host takes them, so a misspelt or mistyped one fails here, saying which.
+function checked(name, options, kinds) {
+    const keys = Object.keys(kinds).join(', ');
+    if (options === null || typeof options !== 'object' || Array.isArray(options)) {
+        throw new TypeError(`crossbind: ${name} takes an object of ${keys}.`);
+    }
+    for (const [key, value] of Object.entries(options)) {
+        if (!Object.hasOwn(kinds, key)) throw new TypeError(`crossbind: ${name} takes ${keys}; ${key} is none of them.`);
+        const list = LISTS[kinds[key]];
+        if (value !== undefined && !(list ? list.isFitting(value) : typeof value === kinds[key])) {
+            throw new TypeError(`crossbind: ${name}'s ${key} is no ${list ? list.name : kinds[key]}.`);
+        }
+    }
+    return options;
+}
+
+function checkedMessage(options) {
+    checked('dialog.message', options, MESSAGE);
+    if (!options.message) throw new TypeError('crossbind: dialog.message takes a message.');
+    if (options.kind !== undefined && !MESSAGE_KINDS.includes(options.kind)) {
+        throw new TypeError(`crossbind: dialog.message's kind is info, warning or error, not ${JSON.stringify(options.kind)}.`);
+    }
+    return options;
+}
+
+function checkedPath(name, path) {
+    if (typeof path !== 'string' || !path) throw new TypeError(`crossbind: ${name} takes a path.`);
+    return { path };
+}
+
+// A menu of the bar is { label, items } or a standard one by its role. An item is { label, id, accelerator, enabled,
+// checked }, a submenu { label, items }, { type: 'separator' }, or a standard item by its role, which a label may
+// rename and, but for an editing one, which keeps the platform's keys, an accelerator change.
+const MENU_ROLES = ['editMenu', 'windowMenu'];
+const EDITING_ROLES = ['undo', 'redo', 'cut', 'copy', 'paste', 'selectAll'];
+const ITEM_ROLES = [...EDITING_ROLES, 'minimize', 'close', 'quit'];
+const ITEM_KINDS = {
+    label: 'string', id: 'string', accelerator: 'string', enabled: 'boolean', checked: 'boolean', items: 'list', role: 'string', type: 'string',
+};
+const MODIFIERS = ['CmdOrCtrl', 'Ctrl', 'Alt', 'Shift'];
+const KEY = /^([A-Z0-9]|F([1-9]|1[0-2])|Enter|Escape|Tab|Space|Backspace|Delete|Up|Down|Left|Right|Home|End|PageUp|PageDown|Plus|Minus|Comma|Period)$/;
+
+// Typing uses neither a key with CmdOrCtrl, Ctrl or Alt nor a function key.
+function checkAccelerator(accelerator, where) {
+    const modifiers = accelerator.split('+');
+    const key = modifiers.pop();
+    const isKnown = KEY.test(key) && modifiers.every((modifier) => MODIFIERS.includes(modifier)) && new Set(modifiers).size === modifiers.length;
+    if (!isKnown || !(/^F\d+$/.test(key) || modifiers.some((modifier) => modifier !== 'Shift'))) {
+        throw new TypeError(`crossbind: menu.set's ${where}.accelerator ${JSON.stringify(accelerator)} is none, which is a key with CmdOrCtrl, Ctrl or Alt and maybe Shift, joined by +, as CmdOrCtrl+Shift+O is, or F1 to F12, alone or with any of them.`);
+    }
+}
+
+function checkMenuItem(item, where, isMenu) {
+    if (item === null || typeof item !== 'object' || Array.isArray(item)) throw new TypeError(`crossbind: menu.set's ${where} is no object.`);
+    for (const [key, value] of Object.entries(item)) {
+        if (!Object.hasOwn(ITEM_KINDS, key)) throw new TypeError(`crossbind: menu.set's ${where} takes ${Object.keys(ITEM_KINDS).join(', ')}; ${key} is none of them.`);
+        const kind = ITEM_KINDS[key];
+        if (value !== undefined && !(kind === 'list' ? Array.isArray(value) : typeof value === kind)) {
+            throw new TypeError(`crossbind: menu.set's ${where}.${key} is no ${kind}.`);
+        }
+    }
+    const has = (...keys) => keys.filter((key) => item[key] !== undefined);
+    const refuse = (what) => {
+        throw new TypeError(`crossbind: menu.set's ${where} ${what}.`);
+    };
+    if (item.type !== undefined) {
+        if (item.type !== 'separator' || isMenu || has(...Object.keys(ITEM_KINDS)).length > 1) refuse("is no separator, which is { type: 'separator' } alone, inside a menu");
+    } else if (item.role !== undefined) {
+        const roles = isMenu ? MENU_ROLES : [...ITEM_ROLES, ...MENU_ROLES];
+        if (!roles.includes(item.role)) refuse(`has no role ${JSON.stringify(item.role)}, which is one of ${roles.join(', ')}`);
+        if (MENU_ROLES.includes(item.role) && has('id', 'accelerator', 'enabled', 'checked', 'items').length > 0) refuse('is a standard menu, which takes a label alone');
+        if (EDITING_ROLES.includes(item.role) && item.accelerator !== undefined) refuse("is an editing item, which keeps the platform's keys and takes a label alone");
+        if (has('id', 'enabled', 'checked', 'items').length > 0) refuse('has a role, which takes a label and an accelerator alone');
+    } else if (!item.label) {
+        refuse('has no label');
+    } else if (item.items !== undefined) {
+        if (has('id', 'accelerator', 'enabled', 'checked').length > 0) refuse('is a menu, which takes a label and items alone');
+        // entries() reads a hole as undefined, which forEach skips.
+        for (const [index, child] of item.items.entries()) checkMenuItem(child, `${where}.items[${index}]`, false);
+    } else if (isMenu) {
+        refuse('is a menu, which takes a label and items, or the role editMenu or windowMenu');
+    }
+    if (item.accelerator !== undefined) checkAccelerator(item.accelerator, where);
+}
+
+function checkedMenus(menus) {
+    if (!Array.isArray(menus)) throw new TypeError('crossbind: menu.set takes a list of menus.');
+    for (const [index, item] of menus.entries()) checkMenuItem(item, `menus[${index}]`, true);
+    return { menus };
+}
+
+export const dialog = {
+    // The paths of the files or folders the user picked, or null when they cancelled.
+    open: async (options = {}) => call('dialog.open', checked('dialog.open', options, OPEN)),
+    // The path the user chose to save to, or null when they cancelled.
+    save: async (options = {}) => call('dialog.save', checked('dialog.save', options, SAVE)),
+    // The index of the button the user clicked: Return gives the first, and Escape or closing the dialog the last.
+    message: async (options) => call('dialog.message', checkedMessage(options)),
+};
+
+export const shell = {
+    // An http, https or mailto address in the default browser or mail app.
+    openExternal: async (url) => {
+        if (typeof url !== 'string' && !(url instanceof URL)) throw new TypeError('crossbind: shell.openExternal takes an address.');
+        return call('shell.openExternal', { url: String(url) });
+    },
+    // A file in the app the system opens its kind with. Opening a program runs it, and a script in the page could ask for
+    // any path, so the host opens files where app.openPath in crossbind.config.js lets it alone; native code opens any.
+    openPath: async (path) => call('shell.openPath', checkedPath('shell.openPath', path)),
+    // A file, selected, in the system's file manager: one in the app's folders, or one a dialog picked during this run.
+    revealInFolder: async (path) => call('shell.revealInFolder', checkedPath('shell.revealInFolder', path)),
+};
+
+export const app = {
+    // The app's own folders, made when first asked for: { data, cache, logs }.
+    paths: async () => call('app.paths', {}),
+    // Ends the app as closing its window does.
+    quit: async () => call('app.quit', {}),
+    // The links of app.urlSchemes that opened the app and have not reached the page yet, the one it was launched with
+    // among them; later ones come as the event open-url. Listening first, then asking, misses none.
+    launchUrls: async () => call('app.launchUrls', {}),
+};
+
+export const menu = {
+    // Sets the app's menus: on macOS after its app menu, which the app keeps, and on Windows and Linux in a bar of its
+    // window. A click of an item with an id is an event, menu, of { id }, and of { id, checked } for an item it checked
+    // or unchecked; a standard item does what its role says.
+    set: async (menus) => call('menu.set', checkedMenus(menus)),
+};
+
+export const events = {
+    // Calls listener with the value of each event of this name the app's native code emits from now on, until the
+    // function it returns is called.
+    on: (name, listener) => {
+        if (typeof name !== 'string' || !name) throw new TypeError('crossbind: events.on takes the name of an event.');
+        if (typeof listener !== 'function') throw new TypeError('crossbind: events.on takes a function to call.');
+        return hostOf('on', 'events.on')(name, listener);
+    },
+};
+
+// One check or install runs at a time, and another rejects meanwhile.
+export const updater = {
+    // The version app.updater.url in crossbind.config.js offers when it is newer than the app's, as { version }, or null.
+    check: async () => call('updater.check', {}),
+    // Downloads that version, checks that the key of app.updater.publicKey signed it and installs it in place of the app,
+    // which then quits and opens the new version. It rejects when that fails.
+    install: async () => call('updater.install', {}),
+};

package/src/assets/js-runtime/adapters/worker-comlink.js

@@ -41,8 +41,12 @@ const ownsObject = (obj) => {
     return Boolean($$ && ($$.smartPtr || $$.count?.owned));
 };
 
+// The module's own objects, its globals above all, live as long as the module, so letting go of a handle to one
+// frees nothing.
+const moduleObjects = new WeakSet();
+
 const freeIfOwned = (obj) => {
-    if (ownsObject(obj) && !obj.isDeleted()) obj.delete();
+    if (ownsObject(obj) && !moduleObjects.has(obj) && !obj.isDeleted()) obj.delete();
 };
 
 // The worker side of a handle the main thread no longer reaches: its id goes, and the object with the last id.
@@ -297,6 +301,9 @@ export function moduleRoot(m) {
         configurable: true,
     });
     Object.defineProperty(m, RELEASE, { value: releaseEmbindObjects, configurable: true });
+    Object.values(m).forEach((value) => {
+        if (value !== null && typeof value === 'object') moduleObjects.add(value);
+    });
     return wrapWithVectorCoercion(m);
 }
 

package/src/assets/toolchain-digests.json

@@ -1,49 +1,55 @@
 {
-    "version": "1.0.13",
+    "version": "1.0.16",
     "registry": "ghcr.io/crossbind",
     "toolchains": {
         "rust": "1.99.1"
     },
     "images": {
         "rust-sysroot": {
-            "index": "sha256:c545ea396bd8919f7a671617dbbdf184bd0d6eb904d3170dd120d6671db3e0a9",
+            "index": "sha256:b0745e62b7bc2d07acebf8dce8edef2e24a5f82f55bf37f51bacdbb67c393339",
             "platforms": {
-                "linux/arm64": "sha256:c53ee0a31c52fdc6eba175e479218ddbff0c071654b5e93a08ae768cdbbfe35a",
-                "linux/amd64": "sha256:1427255e619c3f5dcd3fa7fd284d15afbe00eef1a0798e08a9b50ebbb86c5234"
+                "linux/amd64": "sha256:42e71c9f4b349e116fb25cf1fc357cb070ae9e294a6087bb111dad2346256594",
+                "linux/arm64": "sha256:7144a83fa33d2beaad105e88c0067fb6a44d9b9620e576f226758872962cca44"
             }
         },
         "base": {
-            "index": "sha256:5f5d133504cb2c81ee67a93ca5795698423277522caac742478510d6158ed559",
+            "index": "sha256:d1f2fee78a0238aebb70a2aaed3753212f8151afe0430144b4dfb522f1ccf2ac",
             "platforms": {
-                "linux/arm64": "sha256:df1c82f4b7e00a4ab33e2423f6d5bbaa66dd67bc45b96e5498e3391ec5f55fae",
-                "linux/amd64": "sha256:ffc0a178bc821e56975d9348b7e44d8081b9c6fb9351bc168b38d5063d9864ea"
+                "linux/arm64": "sha256:7faf80e5692ae636f4bc25af0849711c442275b2405b3d52f9e1943ed8089aa2",
+                "linux/amd64": "sha256:7d31882ed442c0425746fa1cbadf4bf1f6a5f035b2222cb907ad5006ef1af24d"
             }
         },
         "web": {
-            "index": "sha256:b5ee271886c316404cae103c5412bc02d811ad48fd36a919fdf3a82af14fe688",
+            "index": "sha256:97d873ae67dac443a88d0dede3fee2893177f167e08e8c9096c29aebd95a3d0f",
             "platforms": {
-                "linux/arm64": "sha256:91d35c9eac65f479f5139ba476b3daa3b517aab6f21f5206070af610cec5b62c",
-                "linux/amd64": "sha256:f308cb1702f308d69d9f21eb99aa109cdbf62e655549b483580476d8f01fb07b"
+                "linux/arm64": "sha256:a274755f6d2cc1702ff7681b75e44b5d1146b73b45ac2dab5e4b543554ad4b19",
+                "linux/amd64": "sha256:23414220cfd4839005d3a5c1e3b83cff4760a3e6eb23687c2a71a1187d0cd211"
             }
         },
         "android": {
-            "index": "sha256:a01ddeaed550091f45e720d09bd559978d4c46e396c4553b3fc4544b90033fd1",
+            "index": "sha256:5cae71358e7619d5958dab6f38b5dad9582792dc3a49c07fdf8dbdbf157ab5bd",
             "platforms": {
-                "linux/amd64": "sha256:3bafd0a3f80bf7370a19522a3b75cb58a977d1b1b28940ed02b87db1058a8fd6"
+                "linux/amd64": "sha256:96ff7fa364b8fb109fd3f0257f591c3dc6315e2b1a810511bb129807940895bc"
+            }
+        },
+        "android-app": {
+            "index": "sha256:b225a3d04d771916c7a2cc0261990f09b71f6c8b5ae63bc0f3869c7cb5a00fb9",
+            "platforms": {
+                "linux/amd64": "sha256:e18361ed3cee022767312cd9f63471f4fe4bf41fccb9c7dd53dafec2da67adc0"
             }
         },
         "linux": {
-            "index": "sha256:c1d7f9672edb6eeea86172d8ba8cc8ba824f6c53134587ea247ea5dc126d6c43",
+            "index": "sha256:6a642147d344f804f42241fc80c21b07bfe1eb40a9a364250959c3715a60700a",
             "platforms": {
-                "linux/amd64": "sha256:0ff9ee1d5c139eb97934919f7b9535af0eb2c3bebd9c1974fa95cfb143e3ccf7",
-                "linux/arm64": "sha256:f476e4a95635c04aca741937c2174a1915731c52c9d182b247e17d4ca4163b33"
+                "linux/arm64": "sha256:2582d7cf143f876ad4a324174ccb0a1097c4ca2ce775c0216756415ca797cb93",
+                "linux/amd64": "sha256:a10f0efc028e8ba63a7a45dda475eb669d8a078bf1e2830ac0a8c026277afe92"
             }
         },
         "windows": {
-            "index": "sha256:53b08c8918a84023ea90c6420fff783564aced0ec711fa0e7b71a09578643a32",
+            "index": "sha256:c4c436763d559a5346f96369b444b79006d4298c5dfce78c15c06089cfdaaa33",
             "platforms": {
-                "linux/arm64": "sha256:402f115c8eed9e6418cf9e47a6bcad2d456d15d032c9b2baaa54a5005f00c8ba",
-                "linux/amd64": "sha256:50f359882015ca93c8b356a01bf03ce4cb098307f72c30122c7b6ad123eae339"
+                "linux/arm64": "sha256:6030741b223fcaccf301e165fb6dace4053dafaba966b067d48c376b7aedb290",
+                "linux/amd64": "sha256:b314de43f2ad7dec0e97e4f0d5033a8c53795118034d13220eb05c9ab885c7a5"
             }
         }
     }

package/src/bin.js

@@ -1,17 +1,22 @@
 #!/usr/bin/env node
 
 import fs from 'node:fs';
-import { execFileSync } from 'node:child_process';
+import os from 'node:os';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { execFileSync, spawn } from 'node:child_process';
 import { Option } from 'commander';
 
 import { state } from './index.js';
 import { addSystemCommands, createProgram, handleFatal } from './program.js';
-import createBridgeFile from './actions/createInterface.js';
 import createLib from './actions/createLib.js';
 import buildWasm from './actions/buildWasm.js';
 import buildWasiCommand from './actions/buildWasiCommand.js';
 import buildNode, { addonsInPackages, bundleNodeLoader, publishNodeData } from './actions/buildNode.js';
 import buildNativeCommand from './actions/buildNativeCommand.js';
+import buildApp, { appOutputPath, assertAppRunner, publishApp } from './actions/buildApp.js';
+import { releaseSigning } from './actions/androidGradle.js';
+import { UPDATER_KEY, newUpdaterKey } from './actions/appUpdate.js';
 import buildExternal from './actions/buildExternal.js';
 import buildPackageTypes from './actions/buildTypes.js';
 import buildLib from './actions/buildLib.js';
@@ -19,8 +24,7 @@ import buildDependencies from './actions/buildDependencies.js';
 import writeRuntimeEntry, { removeImportHooks, writeImportHooks, writeImportManifest } from './actions/writeRuntimeEntry.js';
 import { bindsAppImports, createImportedBridges, findAppNativeImports } from './actions/createImportedBridges.js';
 import { nativeExtensions } from './utils/nativeImports.js';
-import getDependFilePath from './integration/getDependFilePath.js';
-import { boundHeaderSpecifiers, bridgeTargets, nodeBridgeTarget, resolveBoundHeaders } from './utils/boundHeaders.js';
+import { createBridges, createNativeBridges } from './actions/nativeBridges.js';
 import { ENTRY_RUNTIMES } from './utils/runtimeEntries.js';
 import { publishNativeCommand, publishNodeAddon, publishWasiCommand } from './actions/publishBinary.js';
 import runCrossbindApp from './actions/run.js';
@@ -84,7 +88,8 @@ program.command('build')
         if (state.config.build.withBuildConfig) {
             buildExternal(targetParams);
         } else {
-            build(targetParams, rebuildDeps, binaryRuntimeEnvs, { bindImports });
+            // An app builds only for the platforms -p names, so a plain build keeps making the archives alone.
+            build(targetParams, rebuildDeps, binaryRuntimeEnvs, { bindImports }, rest.platform ?? []);
         }
     });
 
@@ -99,13 +104,58 @@ function declaredSbomPath(projectDir) {
     }
 }
 
+// An app's page is the project's Vite build, which @crossbind/plugin-vite makes into the app of the platform named.
+const APP_PLATFORMS = ['android', 'ios', 'linux', 'macos', 'windows'];
+
+function projectVite() {
+    try {
+        const manifest = createRequire(`${state.config.paths.project}/package.json`).resolve('vite/package.json');
+        return path.join(path.dirname(manifest), JSON.parse(fs.readFileSync(manifest, 'utf8')).bin.vite);
+    } catch {
+        throw new Error("crossbind: crossbind app builds the app's page with the project's Vite, which the project does not have. Add vite and @crossbind/plugin-vite to it, as the desktop-app template has them.");
+    }
+}
+
+const commandApp = program.command('app').description('build the project as an app, or open it on the dev server');
+[
+    ['dev', 'open the app on the dev server, and open it anew as its native code changes'],
+    ['build', 'build the app with its page: for Android also its APK, and with an upload key its bundle'],
+].forEach(([name, description]) => commandApp.command(name).description(description)
+    .addOption(new Option('-p, --platform <platform>', "the app's platform (default: CROSSBIND_APP_PLATFORM, else this machine's)").choices(APP_PLATFORMS))
+    // Vite's own options, as --port or --mode, go on to Vite.
+    .allowUnknownOption()
+    .allowExcessArguments()
+    .action(({ platform }, command) => {
+        if (state.config.target.runtimeEnv !== 'app') {
+            throw new Error("crossbind: crossbind app builds an app, which this project is not: set target: { runtimeEnv: 'app' } in crossbind.config.js, as the desktop-app template does.");
+        }
+        // An Android build checks its upload key before the native build, not after it.
+        if (name === 'build' && (platform ?? process.env.CROSSBIND_APP_PLATFORM) === 'android') releaseSigning();
+        const vite = spawn(process.execPath, [projectVite(), ...(name === 'build' ? ['build'] : []), ...command.args], {
+            stdio: 'inherit',
+            cwd: state.config.paths.project,
+            env: platform ? { ...process.env, CROSSBIND_APP_PLATFORM: platform } : process.env,
+        });
+        // A signal sent to crossbind alone reaches Vite too, which ends through its exit hooks; Ctrl-C reaches both.
+        ['SIGINT', 'SIGTERM', 'SIGHUP'].forEach((signal) => process.prependListener(signal, () => vite.kill(signal)));
+        vite.on('exit', (code, signal) => process.exit(code ?? 128 + os.constants.signals[signal]));
+    }));
+
+commandApp.command('updater-key')
+    .description("make the key pair that signs a desktop app's updates")
+    .action(() => {
+        const { publicKey, privateKey } = newUpdaterKey();
+        console.log(`crossbind: app.updater.publicKey in crossbind.config.js: ${publicKey}`);
+        console.log(`crossbind: ${UPDATER_KEY}, kept secret where the app is built: ${privateKey}`);
+    });
+
 program.command('licenses')
     .description('list bundled native dependencies with SPDX license, versions and source URL')
     .option('--notices [file]', 'write a THIRD-PARTY-NOTICES markdown file (default: THIRD-PARTY-NOTICES.md)')
     .option('--sbom [file]', 'write a CycloneDX SBOM json file (default: sbom.cdx.json)')
     .option('--check', 'exit non-zero when a license field is missing or not valid SPDX')
     .option('--platform <platform>', "also list what this platform's artifact statically links beyond the package graph (vendored copies, toolchain runtime)")
-    .addOption(new Option('-e, --runtime-env <runtimeEnv>', 'also list the crossbind runtime an addon of --platform compiles in, or without --platform the one its loader bundles').choices(['node']))
+    .addOption(new Option('-e, --runtime-env <runtimeEnv>', "also list the crossbind runtime an addon of --platform compiles in (without --platform the one its loader bundles), or what an app's host carries").choices(['node', 'app']))
     .option('--json [file]', 'write the rows, license texts included, as JSON (default: licenses.json)')
     .option('--package', "write this Node-API package's LICENSE, sbom.cdx.json and package.json license field (with -e node)")
     .action(async (options) => {
@@ -175,7 +225,7 @@ program.command('clean-deps')
     });
 
 // A container belongs to one image: the web container carries no NDK, and android runs a forced platform.
-const IMAGE_ROLES = ['web', 'android', 'linux', 'windows'];
+const IMAGE_ROLES = ['web', 'android', 'android-app', 'linux', 'windows'];
 const dockerContainerName = (role) => {
     if (!IMAGE_ROLES.includes(role)) {
         console.error(`crossbind: unknown image "${role}" - expected one of ${IMAGE_ROLES.join(', ')}.`);
@@ -205,8 +255,8 @@ const imageArgument = (command) => command.argument('[image]', `image to act on
 
 imageArgument(commandDocker.command('create').description('create docker container'))
     .action((image) => {
-        // Google ships the linux NDK for x86_64 only, so an android container is always amd64.
-        const platform = image === 'android' ? 'linux/amd64' : undefined;
+        // Google ships the linux NDK for x86_64 only, so an android or android-app container is always amd64.
+        const platform = ['android', 'android-app'].includes(image) ? 'linux/amd64' : undefined;
         // Docker on Linux makes a missing mount source owned by root, which the user's builds cannot write.
         [cargoHome(), conanRoot()].forEach((dir) => fs.mkdirSync(dir, { recursive: true }));
         dockerExec([
@@ -306,11 +356,12 @@ function onlyLoadsPackagedAddons(binaryParams) {
     return targets.every((target) => target.runtimeEnv === 'node' && target.platform !== 'wasm') && addonsInPackages();
 }
 
-async function build(targetParams, rebuildOption, binaryRuntimeEnvs, wasmOptions = {}) {
+async function build(targetParams, rebuildOption, binaryRuntimeEnvs, wasmOptions = {}, appPlatforms = []) {
     await buildDependencies({ targetParams, rebuildOption });
     const binaryParams = { ...targetParams, runtimeEnv: binaryRuntimeEnvs };
     if (!onlyLoadsPackagedAddons(binaryParams)) {
-        buildLib(targetParams);
+        // An app links its archives into itself, so it publishes no xcframework or podspec of them.
+        buildLib(targetParams, { skipXcframework: binaryRuntimeEnvs.includes('app') });
     }
     if (binaryRuntimeEnvs.length === 0) {
         logger.info(`crossbind: no runtime environment was selected, so only the archives were built - pass -e (${runtimeEnvs.join(', ')}) for a binary.`);
@@ -318,6 +369,7 @@ async function build(targetParams, rebuildOption, binaryRuntimeEnvs, wasmOptions
         await createWasmJs(binaryParams, wasmOptions);
         await createNodeAddons(binaryParams);
         await createNativeCommands(binaryParams);
+        await createApps({ ...binaryParams, platform: appPlatforms });
         await createWasiCommands(binaryParams);
     }
     buildPackageTypes();
@@ -336,6 +388,26 @@ async function createNativeCommands(targetParams) {
     }
 }
 
+// An app built without a bundler has no page; the Vite plugin puts one in.
+async function createApps(targetParams) {
+    const targets = getBuildTargets(targetParams).filter((target) => target.runtimeEnv === 'app');
+    if (targets.length === 0) {
+        return;
+    }
+    targets.forEach(assertAppRunner);
+    const bridges = createNativeBridges(targets).headers.flatMap((header) => header.bridge ?? []);
+    // An iOS or Android app is one project for all its SDKs or ABIs, written once they are built, and every time, as it
+    // also takes the app's identity and the host package's template.
+    const projects = new Map();
+    for (const target of targets) {
+        const isProject = ['ios', 'android'].includes(target.platform);
+        const built = await buildApp(target, { bridges, force: !isProject && !fs.existsSync(appOutputPath(target)) });
+        if (isProject) projects.set(appOutputPath(target), target);
+        else if (built) publishApp(target);
+    }
+    projects.forEach((target) => publishApp(target));
+}
+
 async function createWasiCommands(targetParams) {
     const targets = getFilteredBuildTargets(targetParams, { platform: 'wasi' });
     if (targets.length === 0) {
@@ -351,23 +423,6 @@ async function createWasiCommands(targetParams) {
     }
 }
 
-function createBridges(target) {
-    let headers = [];
-    state.config.paths.header.forEach((headerPath) => {
-        headers.push(findFiles('**/*.h', { cwd: headerPath }));
-    });
-    headers = headers.filter((path) => !!path.toString()).flat();
-
-    return headers.map((header) => ({ file: header, bridge: createBridgeFile(header, target) }));
-}
-
-// The dependency headers the config binds whole, each read where one of the targets' packages ships it.
-function createBoundBridges(targets) {
-    const headers = resolveBoundHeaders(boundHeaderSpecifiers(state.config), bridgeTargets(targets, state.targets), getDependFilePath);
-    const wholeHeaders = headers.map((header) => header.file);
-    return headers.map((header) => ({ ...header, bridge: createBridgeFile(header.file, header.target, { wholeHeaders }) }));
-}
-
 // A package whose platform packages link its addons ships what loads them: the loader and the data.
 async function publishLoaders(targets) {
     fs.mkdirSync(state.config.paths.output, { recursive: true });
@@ -389,10 +444,7 @@ async function createNodeAddons(targetParams) {
         `${resolveEmbindJsiRoot()}/cpp/src`,
         `${resolveEmbindNapiRoot()}/third_party/node-api-jsi/jsi`,
     ];
-    const boundHeaders = createBoundBridges(targets);
-    const ownHeaders = [...createBridges(nodeBridgeTarget(targets)), ...boundHeaders];
-    const imports = findAppNativeImports(bridgeTargets(targets, state.targets));
-    const headers = [...ownHeaders, ...createImportedBridges(ownHeaders, imports)];
+    const { headers, imports } = createNativeBridges(targets);
     const opt = {
         buildSource: false,
         nativeGlob: [

package/src/index.js

@@ -3,6 +3,13 @@ export { default as getParentPath } from './utils/getParentPath.js';
 export { default as createLib } from './actions/createLib.js';
 export { default as createBridgeFile } from './actions/createInterface.js';
 export { default as buildWasm } from './actions/buildWasm.js';
+export {
+    default as buildApp, buildProjectApp, publishApp, appLayout, appOutputName, appTargetParams,
+} from './actions/buildApp.js';
+export { checkInstaller } from './actions/appInstaller.js';
+export { default as openInSimulator, buildForSimulator } from './actions/iosSimulator.js';
+export { default as openOnDevice, adbPath } from './actions/androidDevice.js';
+export { buildApk } from './actions/androidGradle.js';
 export { default as isSourceNewer } from './actions/isSourceNewer.js';
 export { default as getData } from './actions/getData.js';
 export { default as getCmakeParameters } from './actions/getCmakeParameters.js';

package/src/integration/getCrossbindScript.js

@@ -112,7 +112,9 @@ function buildScript(target, symbols, base) {
         throw new Error('The target is not available!');
     }
     const env = JSON.stringify(getEnv(target));
-    const getPlatformScript = target.platform === 'wasm' ? getWebScript : getReactNativeScript;
+    let getPlatformScript = getReactNativeScript;
+    if (target.platform === 'wasm') getPlatformScript = getWebScript;
+    else if (target.runtimeEnv === 'app') getPlatformScript = getAppScript;
 
     let symbolExportDefineString = '';
     let symbolExportAssignString = '';
@@ -200,6 +202,18 @@ function getReactNativeScript(env) {
     `;
 }
 
+// An app's page loads the runtime the app serves as crossbind.js, which asks the app's host for the module. The build's
+// env is the host's own, so the page passes on only what initNative() is given.
+function getAppScript(env, base) {
+    return `
+        function __crossbindBoot(config) {
+            const base = new URL((typeof __webpack_public_path__ === 'string' ? __webpack_public_path__ : ${JSON.stringify(base)}) || './', document.baseURI).href;
+            return import(/* webpackIgnore: true */ /* @vite-ignore */ base + 'crossbind.js')
+                .then(() => window.Crossbind.initNative(config));
+        }
+    `;
+}
+
 function getWebScript(env, base) {
     const params = `{
         path: base,

package/src/state/index.js

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import loadJson from '../utils/loadJson.js';
 import writeJson from '../utils/writeJson.js';
 import {
-    TARGETS, targetPathOf, nodeAddonNamesOf, nativeCommandNamesOf, wasiNamesOf,
+    TARGETS, targetPathOf, nodeAddonNamesOf, nativeCommandNamesOf, wasiNamesOf, appNamesOf,
 } from '../utils/targets.js';
 import { findCargoModuleImportsIn, writeCargoMarker } from '../utils/cargoImport.js';
 import { exportWasiSdkPath } from '../utils/wasiToolchain.js';
@@ -35,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]) => {
@@ -62,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

@@ -133,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, on iOS the Apple team that signs it, the name it shows and its desktop window.
+        app: config.app || {},
         extensions: config.extensions || [],
         package: null,
         functions: config.functions || {},

package/src/utils/appApiHeader.js

@@ -0,0 +1,29 @@
+// <crossbind/app.h>, which an app's own code includes for the host's functions (docs/api/app.md).
+
+import fs from 'node:fs';
+import state from '../state/index.js';
+import resolveAppHostRoot from './resolveAppHost.js';
+import { runtimeEnvsOf } from './targets.js';
+
+// An app project's native code compiles against the header, with CROSSBIND_APP defined, on every platform an app runs
+// on, and in every flavour of that platform's archives, which share one build. A library and an app's web build get
+// neither.
+export function compilesAsApp(target) {
+    return state.config.target?.runtimeEnv === 'app' && runtimeEnvsOf(target.platform).includes('app');
+}
+
+export function appApiHeader() {
+    const header = `${resolveAppHostRoot()}/cpp/include/crossbind/app.h`;
+    if (!fs.existsSync(header)) {
+        throw new Error('crossbind: this @crossbind/core-app-host has no <crossbind/app.h>; update it to the version of crossbind.');
+    }
+    return header;
+}
+
+// The app host can lie outside the docker mount, so the header is copied into the build tree first; returns the
+// include dir.
+export function stageAppApiInclude(dir) {
+    fs.mkdirSync(`${dir}/include/crossbind`, { recursive: true });
+    fs.copyFileSync(appApiHeader(), `${dir}/include/crossbind/app.h`);
+    return `${dir}/include`;
+}