crossbind 2.0.0-beta.65 → 2.0.0-beta.66

package/src/actions/createLib.js

@@ -11,6 +11,7 @@ import state from '../state/index.js';
 import logger from '../utils/logger.js';
 import { WASI_EMULATION_LIBS, WASI_LINK_LIBS, wasiCFlags, wasiCxxFlags } from '../utils/wasiToolchain.js';
 import { stageWasiHttpInclude, wasiHttpHeader } from '../utils/wasiHttp.js';
+import { appApiHeader, compilesAsApp, stageAppApiInclude } from '../utils/appApiHeader.js';
 import { getFilesFingerprint, getContentHash } from '../utils/hash.js';
 import { withDependencyBridges } from '../utils/dependencyBridges.js';
 import { targetArchiveFlags } from '../utils/archiveFlags.js';
@@ -65,7 +66,9 @@ export default function createLib(target, fileType, options = {}) {
         : null;
     // An Android app links the project's archives from the build where React Native's shared library comes from.
     const appArchives = target.platform === 'android' && target.runtimeEnv === 'app' ? 'archives' : null;
-    const extraKeys = [httpHeader, appArchives].filter(Boolean);
+    // An app's own code compiles against <crossbind/app.h>, with CROSSBIND_APP defined.
+    const appApi = compilesAsApp(target) ? getFilesFingerprint([appApiHeader()]) : null;
+    const extraKeys = [httpHeader, appArchives, appApi].filter(Boolean);
     const flagsFingerprint = getContentHash(JSON.stringify(extraKeys.length ? [keyInputs, ...extraKeys] : keyInputs));
     const flagsChanged = !fs.existsSync(flagsFingerprintFile)
         || fs.readFileSync(flagsFingerprintFile, { encoding: 'utf8' }) !== flagsFingerprint;
@@ -152,10 +155,12 @@ export default function createLib(target, fileType, options = {}) {
             buildEnv.params.push('-e', e);
         });
     } else {
-        // The source of an http build includes <crossbind/http.h>.
-        const headerDirs = target.platform === 'wasi'
-            ? [...(options.headerDirs ?? []), stageWasiHttpInclude(state.config.paths.cli, `${buildPath}/crossbind-wasi-http`)]
-            : options.headerDirs;
+        // The source of an http build includes <crossbind/http.h>, and an app's own code <crossbind/app.h>.
+        const headerDirs = [
+            ...(options.headerDirs ?? []),
+            ...(target.platform === 'wasi' ? [stageWasiHttpInclude(state.config.paths.cli, `${buildPath}/crossbind-wasi-http`)] : []),
+            ...(compilesAsApp(target) ? [stageAppApiInclude(`${buildPath}/crossbind-app`)] : []),
+        ];
         buildParams = getCmakeParameters(target, { ...options, nativeGlob, headerDirs });
 
         triggerExtensions('createLib', 'setFlagWithoutBuildConfig', [buildEnv]);

package/src/actions/getCmakeParameters.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import state from '../state/index.js';
 import getData from './getData.js';
+import { compilesAsApp } from '../utils/appApiHeader.js';
 
 export default function getCmakeParameters(target, options = {}) {
     if (!options || typeof options !== 'object' || Array.isArray(options)) {
@@ -37,7 +38,9 @@ export default function getCmakeParameters(target, options = {}) {
     const buildType = sharedPlatforms.includes(target.platform) && target.runtimeEnv !== 'app' ? 'SHARED' : 'STATIC';
     const otherBuildType = buildType === 'STATIC' ? 'SHARED' : 'STATIC';
 
-    const cmakeCompileOptions = [...new Set(getData('cmake', target)?.compileOptions || [])];
+    // An app's own code can tell it is one, to reach <crossbind/app.h>.
+    const appOptions = compilesAsApp(target) ? ['-DCROSSBIND_APP'] : [];
+    const cmakeCompileOptions = [...new Set([...(getData('cmake', target)?.compileOptions || []), ...appOptions])];
 
     params.push(...[
         `-DPROJECT_NAME=${options.name || state.config.general.name}`,

package/src/actions/gradleProject.js

@@ -14,7 +14,50 @@ export const ANDROIDX_WEBKIT = '1.17.1';
 
 const groovyString = (text) => `'${text.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
 
-const buildGradle = ({ id, label, version, abis }) => `// crossbind writes this project anew on every build: the module comes prebuilt in src/main/jniLibs/, and the app's
+// The launcher shapes an adaptive icon: the app's icon in the middle of a white square.
+const ADAPTIVE_ICON = `<?xml version="1.0" encoding="utf-8"?>
+<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
+    <background android:drawable="@android:color/white" />
+    <foreground android:drawable="@mipmap/ic_launcher_foreground" />
+</adaptive-icon>
+`;
+
+const DAY_NIGHT = '@android:style/Theme.DeviceDefault.DayNight';
+// The activity's theme shows app.window.backgroundColor until the page paints, and the activity puts it behind the page,
+// whose WebView would be white; transparent, which the activity takes for none, without it.
+const backgroundValues = (color) => `<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <color name="crossbind_background">${color ?? '#00000000'}</color>
+    <style name="CrossbindBackground" parent="${DAY_NIGHT}">
+        <item name="android:windowBackground">@color/crossbind_background</item>
+    </style>
+</resources>
+`;
+
+// The Android permissions behind each of app.permissions, after the one every app asks for; the activity asks its user
+// for them when the page first uses the device.
+const INTERNET = '    <uses-permission android:name="android.permission.INTERNET" />';
+const ANDROID_PERMISSIONS = {
+    camera: ['CAMERA'],
+    microphone: ['RECORD_AUDIO', 'MODIFY_AUDIO_SETTINGS'],
+    location: ['ACCESS_COARSE_LOCATION', 'ACCESS_FINE_LOCATION'],
+};
+const usesPermissions = (permissions) => permissions
+    .flatMap((name) => ANDROID_PERMISSIONS[name])
+    .map((permission) => `    <uses-permission android:name="android.permission.${permission}" />`);
+
+// The links of app.urlSchemes the activity opens, from a browser as well, before the end of the activity's element.
+const ACTIVITY_END = '        </activity>';
+const urlFilter = (schemes) => [
+    '            <intent-filter>',
+    '                <action android:name="android.intent.action.VIEW" />',
+    '                <category android:name="android.intent.category.DEFAULT" />',
+    '                <category android:name="android.intent.category.BROWSABLE" />',
+    ...schemes.map((scheme) => `                <data android:scheme="${scheme}" />`),
+    '            </intent-filter>',
+].join('\n');
+
+const buildGradle = ({ id, label, version, abis, icon, launchMode, theme }) => `// crossbind writes this project anew on every build: the module comes prebuilt in src/main/jniLibs/, and the app's
 // files are in src/main/assets/app/.
 plugins {
     id 'com.android.application'
@@ -31,7 +74,7 @@ android {
         targetSdk ${TARGET_SDK}
         versionCode ${version.code}
         versionName ${groovyString(version.name)}
-        manifestPlaceholders = [appName: ${groovyString(label)}]
+        manifestPlaceholders = [appName: ${groovyString(label)}, appIcon: ${groovyString(icon)}, launchMode: ${groovyString(launchMode)}, appTheme: ${groovyString(theme)}]
         ndk {
             abiFilters ${abis.map(groovyString).join(', ')}
         }
@@ -95,16 +138,34 @@ dependencies {
 
 // An Android app as a Gradle project, written anew from the parts its ABI targets built: each brings its libraries,
 // the first also the app's files. Gradle adds Hermes and androidx.webkit from Maven, and makes the APK or the bundle.
-export default function writeGradleProject(to, { parts, id, version }) {
+// The icons given are the files of the app's launcher icon under res/; without them it has the system's.
+export default function writeGradleProject(to, { parts, id, label, version, icons = null, urlSchemes = [], background = null, permissions = [] }) {
     const { name } = state.config.general;
     if (parts.length === 0) throw new Error(`crossbind: no part of the Android app ${name} is built, so there is no Gradle project to write.`);
     fs.rmSync(to, { recursive: true, force: true });
     fs.cpSync(path.join(resolveAppHostRoot(), 'android'), to, { recursive: true });
     const main = path.join(to, 'app', 'src', 'main');
+    const manifest = path.join(main, 'AndroidManifest.xml');
+    const text = fs.readFileSync(manifest, 'utf8');
+    if (!text.includes(ACTIVITY_END) || !text.includes(INTERNET)) {
+        throw new Error(`crossbind: ${manifest}, from the app host, has no activity or permissions to give app.urlSchemes and app.permissions: update @crossbind/core-app-host to match crossbind.`);
+    }
+    fs.writeFileSync(manifest, text
+        .replace(INTERNET, [INTERNET, ...usesPermissions(permissions)].join('\n'))
+        .replace(ACTIVITY_END, urlSchemes.length > 0 ? `${urlFilter(urlSchemes)}\n${ACTIVITY_END}` : ACTIVITY_END));
     parts.forEach(({ arch, dir }) => fs.cpSync(path.join(dir, 'lib'), path.join(main, 'jniLibs', arch), { recursive: true }));
     fs.cpSync(path.join(parts[0].dir, 'app'), path.join(main, 'assets', 'app'), { recursive: true });
+    if (icons) {
+        Object.entries({ ...icons, 'mipmap-anydpi/ic_launcher.xml': ADAPTIVE_ICON }).forEach(([file, content]) => {
+            fs.mkdirSync(path.dirname(path.join(main, 'res', file)), { recursive: true });
+            fs.writeFileSync(path.join(main, 'res', file), content);
+        });
+    }
+    fs.mkdirSync(path.join(main, 'res', 'values'), { recursive: true });
+    fs.writeFileSync(path.join(main, 'res', 'values', 'background.xml'), backgroundValues(background));
     fs.writeFileSync(path.join(to, 'app', 'build.gradle'), buildGradle({
-        id, label: name, version, abis: parts.map(({ arch }) => arch),
+        id, label, version, abis: parts.map(({ arch }) => arch), icon: icons ? '@mipmap/ic_launcher' : '@android:drawable/sym_def_app_icon',
+        launchMode: urlSchemes.length > 0 ? 'singleTask' : 'standard', theme: background ? '@style/CrossbindBackground' : DAY_NIGHT,
     }));
     return to;
 }

package/src/actions/licenses.js

@@ -214,6 +214,7 @@ function nodeRuntimeRows({ isAddon }) {
 const WEBVIEW = { version: 'cbbdee44afff22867de9fd88a9fc8350d9bdd399', sha256: '10e972a2327b5681474f4aa4499e505eaa4ff659aa995380386f08fd6fc1b763' };
 const WEBVIEW2_SDK = { version: '1.0.4258.31', sha256: '56f7f4b8bf9aee4b8efefbbdd4f67d5f74ebd1b100ed0806da71bf76af481aa9' };
 const JSI_SHA256 = 'cb6274a22abc93ecc970066539815e716d3e47716e8f93a9971cf4eb5918ffc1';
+const MONOCYPHER = { version: '4.0.3', sha256: '8cc9bc341a66249016db9bd70e9142d8d0aef9945973744b1ac05dbc55d8ee66' };
 // The fbjni the Hermes release for Android depends on.
 const FBJNI_VERSION = '0.7.0';
 
@@ -272,8 +273,8 @@ function androidAppRows() {
     ];
 }
 
-// The WebView2 SDK headers a Windows host compiles against. webview/webview loads the WebView2 Runtime itself, without
-// the SDK's loader.
+// The WebView2 SDK headers a Windows host compiles against, and the NSIS its setup program carries. webview/webview
+// loads the WebView2 Runtime itself, without the SDK's loader.
 function windowsAppRows(hostRoot) {
     const license = 'BSD-3-Clause';
     return [{
@@ -289,6 +290,19 @@ function windowsAppRows(hostRoot) {
         sourceUrl: `https://api.nuget.org/v3-flatcontainer/microsoft.web.webview2/${WEBVIEW2_SDK.version}/microsoft.web.webview2.${WEBVIEW2_SDK.version}.nupkg`,
         licenseNotes: "the WebView2 SDK's headers from the windows toolchain image, whose interface IDs the host compiles in",
         licenseText: textOf(path.join(hostRoot, 'third_party', 'webview2', 'LICENSE')),
+    }, {
+        npmName: '@crossbind/core-app-host',
+        name: 'nsis',
+        version: '3.11',
+        nativeVersion: '3.11',
+        sha256: null,
+        license: 'Zlib AND MIT',
+        licenseDeclared: 'Zlib AND MIT',
+        licenseSelected: null,
+        isCopyleft: false,
+        sourceUrl: 'https://sources.debian.org/src/nsis/3.11-1/',
+        licenseNotes: "the installer stub and plugins the app's setup program carries, from Debian's nsis in the windows toolchain image: zlib/libpng, but for the System plugin's Call.S, MIT",
+        licenseText: textOf(path.join(hostRoot, 'third_party', 'nsis', 'LICENSE')),
     }];
 }
 
@@ -336,6 +350,21 @@ function appRuntimeRows(platform) {
             licenseNotes: 'webview/webview, with the local patch @crossbind/core-app-host lists',
             licenseText: textOf(path.join(hostRoot, 'third_party', 'webview', 'LICENSE')),
         }]),
+        // A desktop host checks its updates with Monocypher, which the linker leaves out of one without app.updater.
+        ...(['ios', 'android'].includes(platform) || state.config.app?.updater === undefined ? [] : [{
+            npmName: '@crossbind/core-app-host',
+            name: 'monocypher',
+            version: MONOCYPHER.version,
+            nativeVersion: MONOCYPHER.version,
+            sha256: MONOCYPHER.sha256,
+            license: 'BSD-2-Clause OR CC0-1.0',
+            licenseDeclared: 'BSD-2-Clause OR CC0-1.0',
+            licenseSelected: null,
+            isCopyleft: false,
+            sourceUrl: `https://monocypher.org/download/monocypher-${MONOCYPHER.version}.tar.gz`,
+            licenseNotes: "Monocypher's Ed25519 and SHA-512, compiled into the host, which check the app's updates",
+            licenseText: textOf(path.join(hostRoot, 'third_party', 'monocypher', 'LICENCE.md')),
+        }]),
     ];
 }
 

package/src/actions/windowsSigning.js

@@ -0,0 +1,96 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import state from '../state/index.js';
+import getOsUserAndGroupId from '../utils/getOsUserAndGroupId.js';
+import pullDockerImage, { getDockerImage } from '../utils/pullDockerImage.js';
+import replaceBasePathForDocker, { DOCKER_BASE } from '../utils/replaceBasePathForDocker.js';
+import { DOCKER_RUN_SECURITY_ARGS } from '../utils/dockerSecurity.js';
+import resolveAppHostRoot from '../utils/resolveAppHost.js';
+
+// The key that signs a Windows app and its setup program, named by the environment alone so that no secret reaches a
+// file or a command line: jsign's own options, which the windows image's jsign takes through the host's jsign.sh.
+export const WINDOWS_SIGNING = {
+    storetype: 'CROSSBIND_WINDOWS_SIGNING_STORETYPE',
+    keystore: 'CROSSBIND_WINDOWS_SIGNING_KEYSTORE',
+    alias: 'CROSSBIND_WINDOWS_SIGNING_ALIAS',
+    storepass: 'CROSSBIND_WINDOWS_SIGNING_STOREPASS',
+    keypass: 'CROSSBIND_WINDOWS_SIGNING_KEYPASS',
+    certfile: 'CROSSBIND_WINDOWS_SIGNING_CERTFILE',
+    tsaurl: 'CROSSBIND_WINDOWS_SIGNING_TSAURL',
+};
+// The store types of the image's jsign 7.6: files, which the container reads mounted, cloud key services, and hardware
+// tokens, which it does not reach.
+const FILE_STORES = ['PKCS12', 'JKS', 'JCEKS'];
+const CLOUDS = ['AWS', 'AZUREKEYVAULT', 'DIGICERTONE', 'ESIGNER', 'GARASIGN', 'GOOGLECLOUD', 'HASHICORPVAULT', 'ORACLECLOUD', 'SIGNPATH', 'SIGNSERVER', 'TRUSTEDSIGNING'];
+const TOKENS = ['PKCS11', 'CRYPTOCERTUM', 'ETOKEN', 'NITROKEY', 'OPENPGP', 'OPENSC', 'PIV', 'YUBIKEY'];
+// Where the container reads the files the variables name.
+const FILES = '/run/crossbind/signing';
+const OUTPUT_LIMIT = 64 * 1024 * 1024;
+const FAILURE_LINES = 40;
+
+const listed = (names) => `${names.join(' and ')} ${names.length > 1 ? 'are' : 'is'}`;
+
+function existingFile(name, env) {
+    const file = path.resolve(env[name] ?? '');
+    if (!env[name] || !fs.statSync(file, { throwIfNoEntry: false })?.isFile()) {
+        throw new Error(`crossbind: ${name} names ${env[name] ? file : 'nothing'}, which is no file.`);
+    }
+    return file;
+}
+
+// The key a Windows app is signed with, or null without CROSSBIND_WINDOWS_SIGNING_STORETYPE: the app and its setup
+// program are then not signed.
+export function windowsSigning(env = process.env) {
+    const set = Object.values(WINDOWS_SIGNING).filter((name) => env[name]);
+    const storetype = env[WINDOWS_SIGNING.storetype]?.toUpperCase();
+    if (!storetype) {
+        if (set.length) throw new Error(`crossbind: ${listed(set)} set without ${WINDOWS_SIGNING.storetype}, the kind of key jsign signs a Windows app with.`);
+        return null;
+    }
+    if (TOKENS.includes(storetype)) {
+        throw new Error(`crossbind: ${WINDOWS_SIGNING.storetype} ${storetype} is a hardware token, which crossbind's windows container does not reach. Sign with a cloud's key service, as Azure Trusted Signing (TRUSTEDSIGNING) or Azure Key Vault (AZUREKEYVAULT), or with a PKCS#12 file.`);
+    }
+    if (![...FILE_STORES, ...CLOUDS].includes(storetype)) {
+        throw new Error(`crossbind: ${WINDOWS_SIGNING.storetype} ${storetype} is no store type jsign takes: ${[...FILE_STORES, ...CLOUDS].join(', ')}.`);
+    }
+    const files = {};
+    if (FILE_STORES.includes(storetype)) files.keystore = existingFile(WINDOWS_SIGNING.keystore, env);
+    if (env[WINDOWS_SIGNING.certfile]) files.certfile = existingFile(WINDOWS_SIGNING.certfile, env);
+    return { names: set, files };
+}
+
+// A command in crossbind's windows image, which sees the project's base, with the signing key's files mounted
+// read-only under their own names and its other variables passed by name, so that their values stay off the command
+// line. A failure names the tool it was, as the label.
+export function inWindowsImage(command, workdir, signing = null, label = command[0]) {
+    const { base } = state.config.paths;
+    pullDockerImage('windows');
+    const files = Object.entries(signing?.files ?? {});
+    const mounted = files.map(([key]) => WINDOWS_SIGNING[key]);
+    const args = [
+        'run', '--rm', ...DOCKER_RUN_SECURITY_ARGS, '--user', getOsUserAndGroupId(), '-v', `${base}:${DOCKER_BASE}`,
+        ...files.flatMap(([key, file]) => ['-v', `${file}:${FILES}/${key}:ro`, '-e', `${WINDOWS_SIGNING[key]}=${FILES}/${key}`]),
+        ...(signing?.names ?? []).filter((name) => !mounted.includes(name)).flatMap((name) => ['-e', name]),
+        // makensis reads its arguments in the locale's encoding, which the image leaves unset.
+        '-e', 'LC_ALL=C.UTF-8',
+        '-w', replaceBasePathForDocker(workdir, base),
+        getDockerImage('windows'),
+        ...replaceBasePathForDocker(command, base),
+    ];
+    const result = spawnSync('docker', args, { encoding: 'utf8', maxBuffer: OUTPUT_LIMIT });
+    if (result.error) throw new Error(`crossbind: cannot run docker for ${label}: ${result.error.message}`, { cause: result.error });
+    if (result.status !== 0) {
+        const output = `${result.stdout ?? ''}${result.stderr ?? ''}`.trim().split('\n').slice(-FAILURE_LINES).join('\n');
+        const end = result.signal ? `on ${result.signal}` : `with exit code ${result.status}`;
+        throw new Error(`crossbind: ${label} failed in the windows image ${end}:\n${output}`);
+    }
+}
+
+// The script the windows image signs a file with, which a setup program's build runs too.
+export const jsignScript = () => `${resolveAppHostRoot()}/windows/jsign.sh`;
+
+// Signs Windows executables in place with the key the environment names.
+export function signWindows(files, signing) {
+    inWindowsImage(['sh', jsignScript(), ...files], path.dirname(files[0]), signing, 'jsign');
+}

package/src/actions/xcodeProject.js

@@ -18,7 +18,7 @@ int main(int argc, char *argv[]) { return crossbind_app_main(argc, argv); }
 
 const OBJECT_NAMES = ['project', 'mainGroup', 'products', 'target', 'product', 'main', 'info', 'app', 'hermes', 'mainBuild',
     'appBuild', 'hermesLink', 'hermesEmbed', 'sources', 'frameworks', 'resources', 'embed', 'projectDebug', 'projectRelease',
-    'targetDebug', 'targetRelease', 'projectConfigs', 'targetConfigs'];
+    'targetDebug', 'targetRelease', 'projectConfigs', 'targetConfigs', 'assets', 'assetsBuild'];
 // Xcode names its objects by 24 hex digits. Fixed ones leave the project unchanged while what it holds is.
 const ID = Object.fromEntries(OBJECT_NAMES.map((name, index) => [name, `CB${(index + 1).toString(16).toUpperCase().padStart(22, '0')}`]));
 
@@ -36,7 +36,10 @@ const PROJECT_SETTINGS = {
 
 const ORIENTATIONS = ['UIInterfaceOrientationPortrait', 'UIInterfaceOrientationLandscapeLeft', 'UIInterfaceOrientationLandscapeRight'];
 
-const infoPlist = (name) => xmlPlist({
+// The color set of app.window.backgroundColor, which the launch screen shows.
+const LAUNCH_COLOR = 'LaunchBackground';
+
+const infoPlist = (name, urlSchemes, hasBackground, usage) => xmlPlist({
     CFBundleDevelopmentRegion: 'en',
     CFBundleDisplayName: name,
     CFBundleExecutable: '$(EXECUTABLE_NAME)',
@@ -45,22 +48,31 @@ const infoPlist = (name) => xmlPlist({
     CFBundleName: '$(PRODUCT_NAME)',
     CFBundlePackageType: 'APPL',
     CFBundleShortVersionString: '$(MARKETING_VERSION)',
+    ...(urlSchemes.length > 0 ? { CFBundleURLTypes: [{ CFBundleURLName: '$(PRODUCT_BUNDLE_IDENTIFIER)', CFBundleURLSchemes: urlSchemes }] } : {}),
     CFBundleVersion: '$(CURRENT_PROJECT_VERSION)',
     LSRequiresIPhoneOS: true,
     UIApplicationSceneManifest: { UIApplicationSupportsMultipleScenes: false },
-    UILaunchScreen: {},
+    UILaunchScreen: hasBackground ? { UIColorName: LAUNCH_COLOR } : {},
     UISupportedInterfaceOrientations: ORIENTATIONS,
     'UISupportedInterfaceOrientations~ipad': [...ORIENTATIONS, 'UIInterfaceOrientationPortraitUpsideDown'],
+    // The reasons of app.permissions, without which iOS lets the app use none of those devices.
+    ...usage,
 });
 
-function objects(name, targetSettings) {
+function objects(name, targetSettings, hasAssets) {
     const file = (path, type) => ({ isa: 'PBXFileReference', lastKnownFileType: type, path, sourceTree: '<group>' });
     const phase = (isa, files, extra = {}) => ({ isa, buildActionMask: 2147483647, files, runOnlyForDeploymentPostprocessing: 0, ...extra });
     const configuration = (configurationName, buildSettings) => ({ isa: 'XCBuildConfiguration', buildSettings, name: configurationName });
     const configurations = (debug, release) => ({
         isa: 'XCConfigurationList', buildConfigurations: [debug, release], defaultConfigurationIsVisible: 0, defaultConfigurationName: 'Release',
     });
+    // The app's icon and launch screen color, in an asset catalog.
+    const assets = hasAssets ? {
+        [ID.assets]: file('Assets.xcassets', 'folder.assetcatalog'),
+        [ID.assetsBuild]: { isa: 'PBXBuildFile', fileRef: ID.assets },
+    } : {};
     return {
+        ...assets,
         [ID.main]: file('main.m', 'sourcecode.c.objc'),
         [ID.info]: file('Info.plist', 'text.plist.xml'),
         [ID.app]: file('app', 'folder'),
@@ -74,9 +86,11 @@ function objects(name, targetSettings) {
         [ID.hermesEmbed]: { isa: 'PBXBuildFile', fileRef: ID.hermes, settings: { ATTRIBUTES: ['CodeSignOnCopy', 'RemoveHeadersOnCopy'] } },
         [ID.sources]: phase('PBXSourcesBuildPhase', [ID.mainBuild]),
         [ID.frameworks]: phase('PBXFrameworksBuildPhase', [ID.hermesLink]),
-        [ID.resources]: phase('PBXResourcesBuildPhase', [ID.appBuild]),
+        [ID.resources]: phase('PBXResourcesBuildPhase', [ID.appBuild, ...(hasAssets ? [ID.assetsBuild] : [])]),
         [ID.embed]: phase('PBXCopyFilesBuildPhase', [ID.hermesEmbed], { dstPath: '', dstSubfolderSpec: 10, name: 'Embed Frameworks' }),
-        [ID.mainGroup]: { isa: 'PBXGroup', children: [ID.main, ID.info, ID.app, ID.hermes, ID.products], sourceTree: '<group>' },
+        [ID.mainGroup]: {
+            isa: 'PBXGroup', children: [ID.main, ID.info, ID.app, ...(hasAssets ? [ID.assets] : []), ID.hermes, ID.products], sourceTree: '<group>',
+        },
         [ID.products]: { isa: 'PBXGroup', children: [ID.product], name: 'Products', sourceTree: '<group>' },
         [ID.target]: {
             isa: 'PBXNativeTarget',
@@ -111,10 +125,28 @@ function objects(name, targetSettings) {
     };
 }
 
+// The asset catalog: the app's icon, from which Xcode makes every size, and the launch screen's color.
+function writeAssets(catalog, icon, background) {
+    const info = { author: 'xcode', version: 1 };
+    const assetSet = (set, contents) => {
+        fs.mkdirSync(`${catalog}/${set}`, { recursive: true });
+        fs.writeFileSync(`${catalog}/Contents.json`, JSON.stringify({ info }, null, 2));
+        fs.writeFileSync(`${catalog}/${set}/Contents.json`, JSON.stringify({ ...contents, info }, null, 2));
+    };
+    if (icon) {
+        assetSet('AppIcon.appiconset', { images: [{ filename: 'icon.png', idiom: 'universal', platform: 'ios', size: '1024x1024' }] });
+        fs.writeFileSync(`${catalog}/AppIcon.appiconset/icon.png`, icon);
+    }
+    if (background) {
+        const [red, green, blue] = [1, 3, 5].map((at) => `0x${background.slice(at, at + 2).toUpperCase()}`);
+        assetSet(`${LAUNCH_COLOR}.colorset`, { colors: [{ color: { 'color-space': 'srgb', components: { alpha: '1.000', red, green, blue } }, idiom: 'universal' }] });
+    }
+}
+
 // An iOS app as an Xcode project, written anew from the parts its SDK targets built: each brings its archives and
 // their link line, and its slice of Hermes; the first also the app's files. Xcode signs the app and runs it, in the
-// Simulator or on a device.
-export default function writeXcodeProject(to, { parts, identity, version }) {
+// Simulator or on a device, and makes every size of its icon from the one PNG given.
+export default function writeXcodeProject(to, { parts, identity, label, version, icon = null, urlSchemes = [], background = null, usage = {} }) {
     const { name } = state.config.general;
     if (parts.length === 0) throw new Error(`crossbind: no part of the iOS app ${name} is built, so there is no Xcode project to write.`);
     fs.rmSync(to, { recursive: true, force: true });
@@ -133,8 +165,10 @@ export default function writeXcodeProject(to, { parts, identity, version }) {
     if (result.status !== 0) throw new Error(`crossbind: cannot make Hermes' xcframework for ${to}: ${result.stderr || result.error?.message}`);
 
     fs.writeFileSync(`${to}/main.m`, MAIN);
-    fs.writeFileSync(`${to}/Info.plist`, infoPlist(name));
+    fs.writeFileSync(`${to}/Info.plist`, infoPlist(label, urlSchemes, Boolean(background), usage));
+    writeAssets(`${to}/Assets.xcassets`, icon, background);
     const targetSettings = {
+        ...(icon ? { ASSETCATALOG_COMPILER_APPICON_NAME: 'AppIcon' } : {}),
         PRODUCT_NAME: name,
         PRODUCT_BUNDLE_IDENTIFIER: identity.id,
         DEVELOPMENT_TEAM: identity.team,
@@ -146,7 +180,7 @@ export default function writeXcodeProject(to, { parts, identity, version }) {
         ...linkFlags,
     };
     fs.writeFileSync(`${to}/${name}.xcodeproj/project.pbxproj`, textPlist({
-        archiveVersion: 1, classes: {}, objectVersion: 56, objects: objects(name, targetSettings), rootObject: ID.project,
+        archiveVersion: 1, classes: {}, objectVersion: 56, objects: objects(name, targetSettings, Boolean(icon || background)), rootObject: ID.project,
     }));
     return to;
 }

package/src/app/index.d.ts

@@ -0,0 +1,129 @@
+// What an app's host does for its page (target.runtimeEnv: 'app'); in any other build every call rejects.
+
+/** A kind of file a dialog offers: its name, and the extensions, with or without the dot, that make it; "*" is any file. */
+export interface FileFilter {
+    name: string;
+    extensions: string[];
+}
+
+export interface OpenOptions {
+    title?: string;
+    /** The folder the dialog shows first. */
+    defaultPath?: string;
+    filters?: FileFilter[];
+    /** Folders instead of files. */
+    directory?: boolean;
+    multiple?: boolean;
+}
+
+export interface SaveOptions {
+    title?: string;
+    /** The folder the dialog shows first. */
+    defaultPath?: string;
+    defaultName?: string;
+    filters?: FileFilter[];
+}
+
+export interface MessageOptions {
+    message: string;
+    /** Smaller text under the message. */
+    detail?: string;
+    /** info by default. Windows shows its icon for each, and macOS a caution sign for error; Linux, iOS and Android show none. */
+    kind?: 'info' | 'warning' | 'error';
+    /** One to three labels, the first the default; without them OK. */
+    buttons?: string[];
+}
+
+/** The app's own folders, made when first asked for: what it keeps, what it can lose, and its logs. */
+export interface AppPaths {
+    data: string;
+    cache: string;
+    logs: string;
+}
+
+export declare const dialog: {
+    /** The paths of the files or folders the user picked, or null when they cancelled. */
+    open(options?: OpenOptions): Promise<string[] | null>;
+    /** The path the user chose to save to, or null when they cancelled. */
+    save(options?: SaveOptions): Promise<string | null>;
+    /** The index of the button the user clicked: Return gives the first, and Escape or closing the dialog the last. */
+    message(options: MessageOptions): Promise<number>;
+};
+
+export declare const shell: {
+    /** An http, https or mailto address in the default browser or mail app. */
+    openExternal(url: string | URL): Promise<void>;
+    /** A file in the app the system opens its kind with, where app.openPath in crossbind.config.js lets the page: nowhere without it. */
+    openPath(path: string): Promise<void>;
+    /** A file, selected, in the system's file manager: one in the app's folders, or one a dialog picked during this run. */
+    revealInFolder(path: string): Promise<void>;
+};
+
+export declare const app: {
+    paths(): Promise<AppPaths>;
+    /** Ends the app as closing its window does. */
+    quit(): Promise<void>;
+    /** The links of app.urlSchemes in crossbind.config.js that opened the app and have not reached the page yet, the one it was launched with among them. Once the page has asked, each later link comes as the event open-url while it listens, so listening first, then asking, misses none. */
+    launchUrls(): Promise<string[]>;
+};
+
+/** A key with CmdOrCtrl, Ctrl or Alt and maybe Shift, joined by +, as CmdOrCtrl+Shift+O is, or F1–F12, alone or with any of them. The key is A–Z, 0–9, F1–F12, Enter, Escape, Tab, Space, Backspace, Delete, Up, Down, Left, Right, Home, End, PageUp, PageDown, Plus, Minus, Comma or Period. */
+export type Accelerator = string;
+
+/** An item of a menu: one the page handles, by its id, a submenu, a separator, or a standard one by its role. */
+export type MenuItem =
+    | { label: string; id?: string; accelerator?: Accelerator; enabled?: boolean; checked?: boolean }
+    | { label: string; items: MenuItem[] }
+    | { type: 'separator' }
+    | { role: 'undo' | 'redo' | 'cut' | 'copy' | 'paste' | 'selectAll'; label?: string; accelerator?: never }
+    | { role: 'minimize' | 'close' | 'quit'; label?: string; accelerator?: Accelerator }
+    | { role: 'editMenu' | 'windowMenu'; label?: string };
+
+/** A menu of the bar, by its items, or a standard one by its role. */
+export type Menu = { label: string; items: MenuItem[] } | { role: 'editMenu' | 'windowMenu'; label?: string };
+
+/** What the event menu carries: the id of the item clicked, and for one with checked whether it now is. */
+export interface MenuClick {
+    id: string;
+    checked?: boolean;
+}
+
+export declare 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, with a MenuClick. */
+    set(menus: Menu[]): Promise<void>;
+};
+
+/** What the event second-instance carries: a later launch's arguments, the program's own left out, and the folder it was launched in. */
+export interface SecondInstance {
+    args: string[];
+    cwd: string;
+}
+
+/** What the event open-url carries: a link of one of app.urlSchemes that the system opened the app with. */
+export interface OpenUrl {
+    url: string;
+}
+
+export declare const events: {
+    /** Calls listener with each click of an item with an id in the menus menu.set sets, until the function it returns is called. */
+    on(name: 'menu', listener: (click: MenuClick) => void): () => void;
+    /** Calls listener with each link of app.urlSchemes the system opens the app with once the page has called app.launchUrls(), until the function it returns is called. */
+    on(name: 'open-url', listener: (open: OpenUrl) => void): () => void;
+    /** Calls listener with each later launch of a desktop app that app.singleInstance keeps to one instance, which brings its window to the front as far as the system lets it, until the function it returns is called. */
+    on(name: 'second-instance', listener: (launch: SecondInstance) => void): () => void;
+    /** 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: string, listener: (value: unknown) => void): () => void;
+};
+
+/** A newer version of the app, which app.updater.url in crossbind.config.js offers. */
+export interface Update {
+    version: string;
+}
+
+/** One check or install runs at a time, and another rejects meanwhile. */
+export declare const updater: {
+    /** The version app.updater.url offers when it is newer than the app's, or null. */
+    check(): Promise<Update | null>;
+    /** 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(): Promise<void>;
+};