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

package/src/actions/nativeBridges.js

@@ -0,0 +1,35 @@
+import createBridgeFile from './createInterface.js';
+import { createImportedBridges, findAppNativeImports } from './createImportedBridges.js';
+import getDependFilePath from '../integration/getDependFilePath.js';
+import state from '../state/index.js';
+import findFiles from '../utils/findFiles.js';
+import {
+    boundHeaderSpecifiers, bridgeTargets, nodeBridgeTarget, resolveBoundHeaders,
+} from '../utils/boundHeaders.js';
+
+// The project's own headers, each with its bridge.
+export 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.
+export 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 }) }));
+}
+
+// What a native binary binds, an addon or an app host: the project's headers, the dependency headers the config binds
+// whole, and the ones the app's sources import.
+export function createNativeBridges(targets) {
+    const boundHeaders = createBoundBridges(targets);
+    const ownHeaders = [...createBridges(nodeBridgeTarget(targets)), ...boundHeaders];
+    const imports = findAppNativeImports(bridgeTargets(targets, state.targets));
+    return { headers: [...ownHeaders, ...createImportedBridges(ownHeaders, imports)], imports };
+}

package/src/actions/run.js

@@ -22,7 +22,7 @@ import {
 } from '../utils/darwinToolchain.js';
 
 // Native builds can outrun Node's 1 MiB default pipe buffer; without a raised cap a successful build dies with ENOBUFS.
-const EXEC_MAX_BUFFER = 512 * 1024 * 1024;
+export const EXEC_MAX_BUFFER = 512 * 1024 * 1024;
 // Containers share the memory of Docker's VM, and one compile at full -j can take most of a desktop VM
 // (GDAL's bindings peak at 7.5 of 7.7 GiB), so the exclusive steps of parallel builds take turns.
 const DOCKER_COMPILE_LOCK = path.join(os.homedir(), '.crossbind', 'docker-compile.lock');
@@ -124,7 +124,7 @@ const iosParams = [
 
 // The C++ compiler of the image that runs SWIG for the target, so its -dM macro table matches that parse.
 export function cxxPreprocessorFor(target) {
-    if (imageRoleFor(target) !== 'android') return 'em++';
+    if (target?.platform !== 'android') return 'em++';
     return `${t}/${target.arch === 'x86_64' ? CROSSCOMPILER_x86_64 : CROSSCOMPILER_ARM64}-clang++`;
 }
 
@@ -196,7 +196,7 @@ export default function run(program, params = [], platformPrefix = null, target
             case 'android':
                 [dProgram, ...dParams] = params;
                 platformParams = target.arch === 'x86_64' ? androidParamsX86_64 : androidParamsArm64;
-                if (dProgram === 'cmake') {
+                if (dProgram === 'cmake' && dParams[0] !== '--build' && dParams[0] !== '--install') {
                     dParams = [
                         ...dParams,
                         `-DCMAKE_TOOLCHAIN_FILE=${ANDROID_NDK}/build/cmake/android.toolchain.cmake`,

package/src/actions/target.js

@@ -28,7 +28,8 @@ export function getTargetParams(givenTargetParams = {}, noParamCheck = false) {
 }
 
 export function getBuildTargets(targetParams) {
-    const { platform, arch, runtime, buildType, runtimeEnv } = targetParams;
+    // A lookup that names no runtime environment finds the targets that have none: the archives' alone.
+    const { platform, arch, runtime, buildType, runtimeEnv = [] } = targetParams;
     return state.targets.filter(t => (
         (!t.platform || platform.includes(t.platform))
         && (!t.arch || arch.includes(t.arch))

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

@@ -0,0 +1,186 @@
+import fs from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import state from '../state/index.js';
+import { IOS_DEPLOYMENT_TARGET } from '../utils/iosToolchain.js';
+import { textPlist, xmlPlist } from '../utils/plist.js';
+
+// The SDKs an iOS app builds for, one target each, and the slice of Hermes' release each takes.
+export const IOS_SDKS = ['iphoneos', 'iphonesimulator'];
+export const HERMES_SLICES = { iphoneos: 'ios-arm64', iphonesimulator: 'ios-arm64_x86_64-simulator' };
+// What the host's own code needs from the system: Xcode adds it only for the sources it compiles itself.
+const SYSTEM_LIBS = ['-framework', 'UIKit', '-framework', 'WebKit', '-framework', 'CoreGraphics', '-lc++'];
+
+const MAIN = `// crossbind writes this project anew on every build: the app comes prebuilt in lib/, and its files are in app/.
+int crossbind_app_main(int argc, char *argv[]);
+
+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', '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')}`]));
+
+const PROJECT_SETTINGS = {
+    SDKROOT: 'iphoneos',
+    SUPPORTED_PLATFORMS: 'iphoneos iphonesimulator',
+    IPHONEOS_DEPLOYMENT_TARGET: IOS_DEPLOYMENT_TARGET,
+    TARGETED_DEVICE_FAMILY: '1,2',
+    // crossbind's iOS archives are arm64 alone, for devices and the Simulator alike.
+    ARCHS: 'arm64',
+    ALWAYS_SEARCH_USER_PATHS: 'NO',
+    CLANG_ENABLE_OBJC_ARC: 'YES',
+    DEAD_CODE_STRIPPING: 'YES',
+};
+
+const ORIENTATIONS = ['UIInterfaceOrientationPortrait', 'UIInterfaceOrientationLandscapeLeft', 'UIInterfaceOrientationLandscapeRight'];
+
+// 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)',
+    CFBundleIdentifier: '$(PRODUCT_BUNDLE_IDENTIFIER)',
+    CFBundleInfoDictionaryVersion: '6.0',
+    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: 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, 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'),
+        [ID.hermes]: file('Frameworks/hermesvm.xcframework', 'wrapper.xcframework'),
+        [ID.product]: {
+            isa: 'PBXFileReference', explicitFileType: 'wrapper.application', includeInIndex: 0, path: `${name}.app`, sourceTree: 'BUILT_PRODUCTS_DIR',
+        },
+        [ID.mainBuild]: { isa: 'PBXBuildFile', fileRef: ID.main },
+        [ID.appBuild]: { isa: 'PBXBuildFile', fileRef: ID.app },
+        [ID.hermesLink]: { isa: 'PBXBuildFile', fileRef: ID.hermes },
+        [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, ...(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, ...(hasAssets ? [ID.assets] : []), ID.hermes, ID.products], sourceTree: '<group>',
+        },
+        [ID.products]: { isa: 'PBXGroup', children: [ID.product], name: 'Products', sourceTree: '<group>' },
+        [ID.target]: {
+            isa: 'PBXNativeTarget',
+            buildConfigurationList: ID.targetConfigs,
+            buildPhases: [ID.sources, ID.frameworks, ID.resources, ID.embed],
+            buildRules: [],
+            dependencies: [],
+            name,
+            productName: name,
+            productReference: ID.product,
+            productType: 'com.apple.product-type.application',
+        },
+        [ID.project]: {
+            isa: 'PBXProject',
+            buildConfigurationList: ID.projectConfigs,
+            compatibilityVersion: 'Xcode 14.0',
+            developmentRegion: 'en',
+            hasScannedForEncodings: 0,
+            knownRegions: ['en', 'Base'],
+            mainGroup: ID.mainGroup,
+            productRefGroup: ID.products,
+            projectDirPath: '',
+            projectRoot: '',
+            targets: [ID.target],
+        },
+        [ID.projectDebug]: configuration('Debug', PROJECT_SETTINGS),
+        [ID.projectRelease]: configuration('Release', PROJECT_SETTINGS),
+        [ID.targetDebug]: configuration('Debug', targetSettings),
+        [ID.targetRelease]: configuration('Release', targetSettings),
+        [ID.projectConfigs]: configurations(ID.projectDebug, ID.projectRelease),
+        [ID.targetConfigs]: configurations(ID.targetDebug, ID.targetRelease),
+    };
+}
+
+// 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, 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 });
+    fs.mkdirSync(`${to}/${name}.xcodeproj`, { recursive: true });
+    const linkFlags = {};
+    parts.forEach(({ sdk, dir }) => {
+        fs.cpSync(`${dir}/lib`, `${to}/lib/${sdk}`, { recursive: true });
+        // The quotes keep a project path with spaces in one argument.
+        const args = JSON.parse(fs.readFileSync(`${dir}/link.json`, 'utf8'))
+            .map((arg) => arg.replace(/\{lib\}\/(.+)$/, `"$(PROJECT_DIR)/lib/${sdk}/$1"`));
+        linkFlags[`OTHER_LDFLAGS[sdk=${sdk}*]`] = [...args, ...SYSTEM_LIBS];
+    });
+    fs.cpSync(`${parts[0].dir}/app`, `${to}/app`, { recursive: true });
+    const frameworks = parts.flatMap(({ dir }) => ['-framework', `${dir}/hermesvm.framework`]);
+    const result = spawnSync('xcodebuild', ['-create-xcframework', ...frameworks, '-output', `${to}/Frameworks/hermesvm.xcframework`], { encoding: 'utf8' });
+    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(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,
+        CODE_SIGN_STYLE: 'Automatic',
+        INFOPLIST_FILE: 'Info.plist',
+        MARKETING_VERSION: version,
+        CURRENT_PROJECT_VERSION: version,
+        LD_RUNPATH_SEARCH_PATHS: ['$(inherited)', '@executable_path/Frameworks'],
+        ...linkFlags,
+    };
+    fs.writeFileSync(`${to}/${name}.xcodeproj/project.pbxproj`, textPlist({
+        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>;
+};