crossbind 2.0.0-beta.68 → 2.0.0-beta.72

package/src/utils/appOptions.js

@@ -1,16 +1,17 @@
 // The app section of crossbind.config.js: what a user sees of an app, its name and, on the desktop, its window, and where
 // its page opens files.
+import { carriedPath } from './appFiles.js';
 
-const WINDOW_DEFAULTS = { width: 1024, height: 768, minWidth: 0, minHeight: 0, maxWidth: 0, maxHeight: 0, resizable: true, fullscreen: false, backgroundColor: null };
+const WINDOW_DEFAULTS = { width: 1024, height: 768, minWidth: 0, minHeight: 0, maxWidth: 0, maxHeight: 0, resizable: true, fullscreen: false, backgroundColor: null, titleBar: 'visible' };
+const TITLE_BARS = ['visible', 'hidden'];
 // Larger than any display, and far within the int a host takes a size as.
 const MAX_WINDOW_SIZE = 16384;
 // Windows keeps each of a file version's four numbers in 16 bits.
 const MAX_VERSION_NUMBER = 65535;
 // Up to four numbers, then a semver prerelease or build part; none of its characters needs escaping in C or RC.
 const WINDOWS_VERSION = /^(\d+(?:\.\d+){0,3})(?:[-+][0-9A-Za-z.+-]*)?$/;
-// What app.openPath can let the page's shell.openPath open: the app's folders as app.paths() names them, and what a
-// dialog picked during this run.
-const OPEN_PATH_PLACES = ['data', 'cache', 'logs', 'picked'];
+// The platforms whose apps have a window of their own, and updates.
+const DESKTOP = ['darwin', 'linux', 'win32'];
 // Apple's app categories, which macOS shows an app under, each with the main categories of the freedesktop menu
 // specification a Linux menu shows it under. An audio or a video app is in AudioVideo as well, as the specification asks.
 const GAMES = ['', 'action-', 'adventure-', 'arcade-', 'board-', 'card-', 'casino-', 'dice-', 'educational-', 'family-', 'kids-', 'music-', 'puzzle-',
@@ -32,6 +33,18 @@ export function appId(config) {
     return id;
 }
 
+// An Android application id: dot-separated parts of letters, digits and underscores that each start with a letter.
+const ANDROID_APP_ID = /^[A-Za-z][A-Za-z0-9_]*(\.[A-Za-z][A-Za-z0-9_]*)+$/;
+
+// An Android app's id: the project's app.id, else one made from the project's name.
+export function androidAppId(config) {
+    const id = config.app.id ?? `dev.crossbind.${config.general.name.replace(/[^A-Za-z0-9.]/g, '_')}`;
+    if (!ANDROID_APP_ID.test(id)) {
+        throw new Error(`crossbind: ${JSON.stringify(id)} (app.id, else made from the project's name) is no Android application id, which takes dot-separated parts of letters, digits and underscores that each start with a letter, as com.example.app does. Set app.id in crossbind.config.js.`);
+    }
+    return id;
+}
+
 // The name the app shows: its window's title, its macOS menus, its Windows file description and the label under its
 // icon. The project's name, without app.name.
 export function appDisplayName(config) {
@@ -70,8 +83,9 @@ export function appCategory(config) {
     return { darwin: `public.app-category.${category}`, linux: APP_CATEGORIES[category] };
 }
 
-// The desktop window: the size of its page, the least it shrinks to and the most it grows to, whether it resizes and
-// whether it opens full screen. Its backgroundColor, which a phone takes as well, is appBackgroundColor's.
+// The desktop window: the size of its page, the least it shrinks to and the most it grows to, whether it resizes,
+// whether it opens full screen and whether a macOS page lies under its title bar. Its backgroundColor, which a phone
+// takes as well, is appBackgroundColor's.
 export function appWindow(config) {
     const window = config.app.window ?? {};
     const keys = Object.keys(WINDOW_DEFAULTS).join(', ');
@@ -90,6 +104,9 @@ export function appWindow(config) {
     ['resizable', 'fullscreen'].forEach((key) => {
         if (typeof options[key] !== 'boolean') throw new Error(`crossbind: app.window.${key} ${JSON.stringify(options[key])} is no boolean: set it to true or false.`);
     });
+    if (!TITLE_BARS.includes(options.titleBar)) {
+        throw new Error(`crossbind: app.window.titleBar ${JSON.stringify(options.titleBar)} is neither 'visible' nor 'hidden': 'hidden' lays a macOS app's page under its title bar, whose buttons stay.`);
+    }
     if (!options.resizable && (options.minWidth || options.minHeight || options.maxWidth || options.maxHeight)) {
         throw new Error('crossbind: app.window.minWidth, minHeight, maxWidth and maxHeight limit a window that resizes: drop them, or set app.window.resizable to true.');
     }
@@ -105,16 +122,29 @@ export function appWindow(config) {
     return options;
 }
 
-// The color an app shows until its page paints, and behind a page without a background of its own, on iOS and Android as
-// well: app.window.backgroundColor, else null, which leaves the system's.
-export function appBackgroundColor(config) {
+const COLOR = /^#[0-9A-Fa-f]{6}$/;
+
+// The colors an app shows until its page paints, and behind a page without a background of its own, on iOS and Android as
+// well: app.window.backgroundColor, one color, or { light, dark }, the one while the system is light and the one while
+// it is dark, which a phone follows; else null, which leaves the system's.
+function backgroundColors(config) {
     const color = config.app.window?.backgroundColor ?? null;
-    if (color !== null && (typeof color !== 'string' || !/^#[0-9A-Fa-f]{6}$/.test(color))) {
-        throw new Error(`crossbind: app.window.backgroundColor ${JSON.stringify(color)} is no color of the form #rrggbb, as #1e1e1e is.`);
+    if (color === null) return null;
+    if (typeof color === 'string' && COLOR.test(color)) return { light: color, dark: null };
+    const isPair = typeof color === 'object' && !Array.isArray(color) && Object.keys(color).sort().join() === 'dark,light'
+        && [color.light, color.dark].every((one) => typeof one === 'string' && COLOR.test(one));
+    if (!isPair) {
+        throw new Error(`crossbind: app.window.backgroundColor ${JSON.stringify(color)} is no color of the form #rrggbb, as #1e1e1e is, nor { light, dark } of two, as { light: '#f2f2f2', dark: '#1e1e1e' } is.`);
     }
     return color;
 }
 
+// The color, or the light one of the two, which a desktop shows whatever its system's appearance.
+export const appBackgroundColor = (config) => backgroundColors(config)?.light ?? null;
+
+// The color an iOS or Android app shows while its system is dark, where app.window.backgroundColor gives one.
+export const appDarkBackgroundColor = (config) => backgroundColors(config)?.dark ?? null;
+
 const PERMISSIONS = ['camera', 'microphone', 'location'];
 
 // The devices the page may use, each with the reason for it, which macOS and iOS read from the Info.plist:
@@ -158,18 +188,20 @@ export const PRIVACY_CATEGORIES = {
 
 // The reasons an iOS app's privacy manifest gives for the required reason API it calls: app.privacy, each category with
 // Apple's reasons that fit, as { fileTimestamp: ['C617.1'] }.
-export function appPrivacy(config) {
-    const privacy = config.app.privacy ?? {};
+export const appPrivacy = (config) => checkedPrivacy(config.app.privacy ?? {}, 'app.privacy');
+
+// Reasons for Apple's required reason API, as app.privacy gives them and an extension's ios.privacy does.
+export function checkedPrivacy(privacy, where) {
     const names = Object.keys(PRIVACY_CATEGORIES).join(', ');
     if (typeof privacy !== 'object' || privacy === null || Array.isArray(privacy)) {
-        throw new Error(`crossbind: app.privacy ${JSON.stringify(privacy)} is no object of ${names}, each with Apple's reasons for it, as { fileTimestamp: ['C617.1'] } is.`);
+        throw new Error(`crossbind: ${where} ${JSON.stringify(privacy)} is no object of ${names}, each with Apple's reasons for it, as { fileTimestamp: ['C617.1'] } is.`);
     }
     const unknown = Object.keys(privacy).filter((name) => !Object.hasOwn(PRIVACY_CATEGORIES, name));
-    if (unknown.length > 0) throw new Error(`crossbind: app.privacy takes ${names}; ${unknown.join(', ')} is none of them.`);
+    if (unknown.length > 0) throw new Error(`crossbind: ${where} takes ${names}; ${unknown.join(', ')} is none of them.`);
     Object.entries(privacy).forEach(([name, reasons]) => {
         const allowed = PRIVACY_CATEGORIES[name].reasons;
         if (!Array.isArray(reasons) || reasons.length === 0 || reasons.some((reason) => !allowed.includes(reason))) {
-            throw new Error(`crossbind: app.privacy.${name} ${JSON.stringify(reasons)} is no list of Apple's reasons for it, which are ${allowed.join(', ')}; Apple's "Describing use of required reason API" says what each covers.`);
+            throw new Error(`crossbind: ${where}.${name} ${JSON.stringify(reasons)} is no list of Apple's reasons for it, which are ${allowed.join(', ')}; Apple's "Describing use of required reason API" says what each covers.`);
         }
     });
     return privacy;
@@ -186,6 +218,40 @@ export function appEncryption(config) {
     return encryption;
 }
 
+const IOS_OPTIONS = ['multipleWindows', 'appGroup'];
+// An App Group of iOS's: group. and a bundle id's dot-separated parts.
+const APP_GROUP = /^group(\.[A-Za-z0-9-]+)+$/;
+
+function iosOptions(config) {
+    const ios = config.app.ios ?? {};
+    if (typeof ios !== 'object' || Array.isArray(ios)) {
+        throw new Error(`crossbind: app.ios ${JSON.stringify(ios)} is no object of multipleWindows and appGroup, as { multipleWindows: true } is.`);
+    }
+    const unknown = Object.keys(ios).filter((key) => !IOS_OPTIONS.includes(key));
+    if (unknown.length > 0) throw new Error(`crossbind: app.ios takes multipleWindows and appGroup; ${unknown.join(', ')} is none of them.`);
+    return ios;
+}
+
+// Whether an iPad app's user, and its page, open more windows of it, as app.ios.multipleWindows says: iOS shows an
+// iPhone's one window alone.
+export function iosMultipleWindows(config) {
+    const { multipleWindows = false } = iosOptions(config);
+    if (typeof multipleWindows !== 'boolean') {
+        throw new Error(`crossbind: app.ios.multipleWindows ${JSON.stringify(multipleWindows)} is no boolean: set it to true for an iPad app's windows, or leave it out.`);
+    }
+    return multipleWindows;
+}
+
+// The App Group an iOS app shares with the targets its extensions add, as app.ios.appGroup names it, else group. and the
+// app's id.
+export function iosAppGroup(config) {
+    const { appGroup = `group.${appId(config)}` } = iosOptions(config);
+    if (typeof appGroup !== 'string' || !APP_GROUP.test(appGroup)) {
+        throw new Error(`crossbind: app.ios.appGroup ${JSON.stringify(appGroup)} is no App Group, which is group. and a bundle id's parts, as group.com.example.notes is.`);
+    }
+    return appGroup;
+}
+
 // The version a Windows app's executable carries: package.json's, whose numbers are its file version.
 function windowsVersion(config) {
     const version = config.package?.version ?? '1.0.0';
@@ -197,17 +263,13 @@ function windowsVersion(config) {
     return { text: version, numbers: [...numbers, 0, 0, 0].slice(0, 4).join(',') };
 }
 
-// Where the page's shell.openPath opens a file: nowhere unless app.openPath lists it, as opening a program runs it.
-function appOpenPath(config) {
-    const places = config.app.openPath ?? [];
-    if (!Array.isArray(places)) {
-        throw new Error(`crossbind: app.openPath ${JSON.stringify(places)} is no list of ${OPEN_PATH_PLACES.join(', ')}, as ['logs', 'picked'] is.`);
-    }
-    const unknown = places.filter((place) => !OPEN_PATH_PLACES.includes(place));
-    if (unknown.length > 0) {
-        throw new Error(`crossbind: app.openPath takes ${OPEN_PATH_PLACES.join(', ')}; ${unknown.map((place) => JSON.stringify(place)).join(', ')} is none of them.`);
-    }
-    return places;
+// The files and folders of the project the app carries for its own native code, as app.files lists them: inside the
+// project's folder, which keep their places in the app's files/.
+export function appFiles(config) {
+    const files = config.app.files ?? [];
+    if (!Array.isArray(files)) throw new Error(`crossbind: app.files ${JSON.stringify(files)} is no list of the project's files and folders, as ['seed.sqlite'] is.`);
+    const root = config.paths.project;
+    return files.map((file) => carriedPath('app.files', root, file, "project's"));
 }
 
 // Schemes the web, the system or crossbind owns, which no app takes, and the keys of Windows' own classes, whose name a
@@ -218,79 +280,59 @@ const RESERVED_SCHEMES = [
     'wow6432node',
 ];
 
-// The schemes whose links open the app, as myapp://… does: lowercase, which is how Android matches them, and of two
-// characters at least, as one would take a Windows path's drive for a scheme.
-export function appUrlSchemes(config) {
-    const schemes = config.app.urlSchemes ?? [];
+// The schemes of a list whose links open the app, as myapp://… does: lowercase, which is how Android matches them, and
+// of two characters at least, as one would take a Windows path's drive for a scheme.
+export function checkedUrlSchemes(schemes, where) {
     if (!Array.isArray(schemes)) {
-        throw new Error(`crossbind: app.urlSchemes ${JSON.stringify(schemes)} is no list of schemes, as ['myapp'] is.`);
+        throw new Error(`crossbind: ${where} ${JSON.stringify(schemes)} is no list of schemes, as ['myapp'] is.`);
     }
     for (const scheme of schemes) {
         if (typeof scheme !== 'string' || !/^[a-z][a-z0-9+.-]+$/.test(scheme)) {
-            throw new Error(`crossbind: app.urlSchemes takes schemes of a lowercase letter, then one or more lowercase letters, digits, +, - and ., as myapp is; ${JSON.stringify(scheme)} is none.`);
+            throw new Error(`crossbind: ${where} takes schemes of a lowercase letter, then one or more lowercase letters, digits, +, - and ., as myapp is; ${JSON.stringify(scheme)} is none.`);
         }
         if (RESERVED_SCHEMES.includes(scheme)) {
-            throw new Error(`crossbind: app.urlSchemes cannot take ${scheme}, which the web or the system owns: pick a scheme of the app's own.`);
+            throw new Error(`crossbind: ${where} cannot take ${scheme}, which the web or the system owns: pick a scheme of the app's own.`);
         }
     }
-    if (new Set(schemes).size !== schemes.length) throw new Error(`crossbind: app.urlSchemes lists a scheme twice: ${JSON.stringify(schemes)}.`);
+    if (new Set(schemes).size !== schemes.length) throw new Error(`crossbind: ${where} lists a scheme twice: ${JSON.stringify(schemes)}.`);
     return schemes;
 }
 
-// Semver's version: three numbers, then a prerelease and build metadata of dot-separated identifiers.
-const SEMVER = /^\d+\.\d+\.\d+(-[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?(\+[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?$/;
-// What an update's files are named after: characters an address carries as they are, and no leading dot.
-const UPDATE_NAME = /^[A-Za-z0-9_~-][A-Za-z0-9._~-]*$/;
-// The Ed25519 public keys of the points of small order, whatever the sign of x, whose signatures anyone can forge: the
-// list libsodium's ge25519_has_small_order checks.
-const SMALL_ORDER_KEYS = [
-    '0000000000000000000000000000000000000000000000000000000000000000',
-    '0100000000000000000000000000000000000000000000000000000000000000',
-    '26e8958fc2b227b045c3f489f2ef98f0d5dfac05d3c63339b13802886d53fc05',
-    'c7176a703d4dd84fba3c0b760d10670f2a2053fa2c39ccc64ec7fd7792ac037a',
-    'ecffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff7f',
-    'edffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff7f',
-    'eeffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff7f',
-].map((hex) => Buffer.from(hex, 'hex'));
-
-const isSmallOrder = (key) => SMALL_ORDER_KEYS.some((point) => key.subarray(0, 31).equals(point.subarray(0, 31)) && (key[31] & 0x7f) === point[31]);
-
-// Where a desktop app finds its updates, the key their signatures are checked with, and the version they are newer than:
-// package.json's, which semver orders. Null without app.updater.
-export function appUpdater(config) {
-    const updater = config.app.updater;
-    if (updater === undefined) return null;
-    const keys = 'url and publicKey';
-    if (updater === null || typeof updater !== 'object' || Array.isArray(updater)) {
-        throw new Error(`crossbind: app.updater ${JSON.stringify(updater)} is no object of ${keys}, as { url: 'https://example.com/updates/<name>-{platform}-{arch}.update.json', publicKey: '…' } is.`);
-    }
-    const unknown = Object.keys(updater).filter((key) => !['url', 'publicKey'].includes(key));
-    if (unknown.length > 0) throw new Error(`crossbind: app.updater takes ${keys}; ${unknown.join(', ')} is none of them.`);
-    const url = URL.canParse(updater.url) ? new URL(updater.url) : null;
-    const isLocal = url?.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
-    // The host takes the address as a C string, as it is written, and the update's file from beside the manifest.
-    if (!url || !(url.protocol === 'https:' || isLocal) || /[^\x21-\x7e]|["\\]/.test(updater.url) || url.pathname.endsWith('/')) {
-        throw new Error(`crossbind: app.updater.url ${JSON.stringify(updater.url)} is no https address of a manifest, as https://example.com/updates/<name>-{platform}-{arch}.update.json is; http serves localhost alone.`);
-    }
-    const publicKey = Buffer.from(typeof updater.publicKey === 'string' ? updater.publicKey : '', 'base64');
-    if (publicKey.length !== 32 || publicKey.toString('base64') !== updater.publicKey) {
-        throw new Error(`crossbind: app.updater.publicKey ${JSON.stringify(updater.publicKey)} is no Ed25519 public key, which \`crossbind app updater-key\` prints.`);
-    }
-    if (isSmallOrder(publicKey)) {
-        throw new Error(`crossbind: app.updater.publicKey ${JSON.stringify(updater.publicKey)} is a key anyone can forge signatures for, which no key pair has. Use the one \`crossbind app updater-key\` prints.`);
-    }
-    const version = config.package?.version ?? '1.0.0';
-    if (typeof version !== 'string' || !SEMVER.test(version)) {
-        throw new Error(`crossbind: package.json's version ${JSON.stringify(version)} is no semver version, as 1.2.3 and 1.2.3-beta.1 are, which an app that updates needs to tell a newer one.`);
-    }
-    if (!UPDATE_NAME.test(config.general.name)) {
-        throw new Error(`crossbind: general.name ${JSON.stringify(config.general.name)} names an app's update files, which an app fetches by name: letters, digits, and . _ ~ - alone, not starting with a dot. Change general.name in crossbind.config.js.`);
+const ownerName = (extension) => (extension === null ? 'app.urlSchemes' : `the extension ${extension}`);
+
+// The schemes whose links open the app, each with the extension that declared it, whose native code gets its links, or
+// null for those of app.urlSchemes, whose links the host's links hands the page. Two owners of one scheme stop the build,
+// naming both.
+export function urlSchemeOwners(config) {
+    const owned = [
+        ...checkedUrlSchemes(config.app.urlSchemes ?? [], 'app.urlSchemes').map((scheme) => ({ scheme, extension: null })),
+        ...(config.extensions ?? []).flatMap(({ name, app }) => (app.urlSchemes ?? []).map((scheme) => ({ scheme, extension: name }))),
+    ];
+    owned.forEach(({ scheme, extension }, index) => {
+        const first = owned.findIndex((other) => other.scheme === scheme);
+        if (first !== index) {
+            throw new Error(`crossbind: ${ownerName(owned[first].extension)} and ${ownerName(extension)} both claim the scheme ${scheme}, whose links one alone gets.`);
+        }
+    });
+    return owned;
+}
+
+// The schemes whose links open the app: app.urlSchemes's, then its extensions'.
+export const appUrlSchemes = (config) => urlSchemeOwners(config).map(({ scheme }) => scheme);
+
+// The installers app.installers names, which alone of each desktop platform's make what installs its app; null without
+// it, when every one does.
+export function appInstallers(config) {
+    const { installers } = config.app;
+    if (installers === undefined) return null;
+    if (!Array.isArray(installers) || !installers.every((name) => typeof name === 'string') || new Set(installers).size !== installers.length) {
+        throw new Error(`crossbind: app.installers ${JSON.stringify(installers)} is no list of installers' names, each once.`);
     }
-    return { url: updater.url, publicKey, version };
+    return installers;
 }
 
-// A desktop host's window: its page's size and limits, whether it resizes and whether it opens full screen. A maximum of
-// one side alone leaves the other as large as any display.
+// A desktop host's window: its page's size and limits, whether it resizes, whether it opens full screen and whether its
+// page lies under its title bar. A maximum of one side alone leaves the other as large as any display.
 function windowDefines(window) {
     const most = window.maxWidth || window.maxHeight ? [
         `#define CROSSBIND_APP_WINDOW_MAX_WIDTH ${window.maxWidth || MAX_WINDOW_SIZE}`,
@@ -304,52 +346,40 @@ function windowDefines(window) {
         `#define CROSSBIND_APP_WINDOW_RESIZABLE ${window.resizable ? 1 : 0}`,
         ...most,
         ...(window.fullscreen ? ['#define CROSSBIND_APP_WINDOW_FULLSCREEN 1'] : []),
+        ...(window.titleBar === 'hidden' ? ['#define CROSSBIND_APP_WINDOW_TITLE_BAR_HIDDEN 1'] : []),
     ];
 }
 
-// The header an app's host compiles where its page opens files from, an iOS or desktop host the color it shows until
-// its page paints and the devices the page may use, a desktop host its title, window, whether it keeps one instance and
-// its updates, and a Windows host its version resource.
-export function appHeader(config, platform) {
+// The header an app's host compiles its id and name with, an iOS or desktop host the color it shows until its page paints
+// and the devices the page may use, an iOS host the App Group of its extensions' targets, a desktop host its window, and a
+// Windows host its version resource.
+export function appHeader(config, platform, appGroup = null) {
     const comment = '// crossbind writes this file from crossbind.config.js and package.json.';
-    const openPath = `#define CROSSBIND_APP_OPEN_PATH {${appOpenPath(config).map((place) => `"${place}"`).join(', ')}}`;
+    const id = `#define CROSSBIND_APP_ID "${platform === 'android' ? androidAppId(config) : appId(config)}"`;
+    const name = `#define CROSSBIND_APP_NAME "${appDisplayName(config)}"`;
     const color = appBackgroundColor(config);
+    const dark = platform === 'ios' ? appDarkBackgroundColor(config) : null;
     const permissions = appPermissions(config);
     // An Android app's activity takes the color and the permissions from its Gradle project.
     const page = platform === 'android' ? [] : [
         ...(color ? [`#define CROSSBIND_APP_BACKGROUND_COLOR 0x${color.slice(1).toLowerCase()}`] : []),
+        ...(dark ? [`#define CROSSBIND_APP_BACKGROUND_COLOR_DARK 0x${dark.slice(1).toLowerCase()}`] : []),
         ...PERMISSIONS.map((name) => `#define CROSSBIND_APP_PERMISSION_${name.toUpperCase()} ${name in permissions ? 1 : 0}`),
     ];
-    if (!['darwin', 'linux', 'win32'].includes(platform)) return [comment, openPath, ...page, ''].join('\n');
+    const windows = platform === 'ios' && iosMultipleWindows(config) ? ['#define CROSSBIND_APP_IOS_MULTIPLE_WINDOWS 1'] : [];
+    const group = platform === 'ios' && appGroup ? [`#define CROSSBIND_APP_GROUP "${appGroup}"`] : [];
+    if (!DESKTOP.includes(platform)) return [comment, ...page, ...windows, ...group, id, name, ''].join('\n');
     // The category goes to the Info.plist and the desktop entry, which the build writes later; any desktop refuses a
     // wrong one here.
     const copyright = appCopyright(config);
     appCategory(config);
     const lines = [
         comment,
-        openPath,
         ...page,
-        `#define CROSSBIND_APP_ID "${appId(config)}"`,
-        `#define CROSSBIND_APP_NAME "${appDisplayName(config)}"`,
+        id,
+        name,
         ...windowDefines(appWindow(config)),
     ];
-    const urlSchemes = appUrlSchemes(config);
-    if (urlSchemes.length > 0) lines.push(`#define CROSSBIND_APP_URL_SCHEMES {${urlSchemes.map((scheme) => `"${scheme}"`).join(', ')}}`);
-    // A link the system opens a Windows or Linux app with starts it again, which reaches the app that runs this way; macOS
-    // hands the link to the app that runs.
-    const singleInstance = config.app.singleInstance ?? (urlSchemes.length > 0 && platform !== 'darwin');
-    if (typeof singleInstance !== 'boolean') {
-        throw new Error(`crossbind: app.singleInstance ${JSON.stringify(singleInstance)} is no boolean: set it to true to keep a desktop app to one instance, or to false to let each launch run.`);
-    }
-    if (singleInstance) lines.push('#define CROSSBIND_APP_SINGLE_INSTANCE 1');
-    const updater = appUpdater(config);
-    if (updater) {
-        lines.push(
-            `#define CROSSBIND_APP_UPDATER_URL "${updater.url}"`,
-            `#define CROSSBIND_APP_UPDATER_KEY {${[...updater.publicKey].map((byte) => `0x${byte.toString(16).padStart(2, '0')}`).join(', ')}}`,
-            `#define CROSSBIND_APP_UPDATER_VERSION "${updater.version}"`,
-        );
-    }
     if (platform === 'win32') {
         const version = windowsVersion(config);
         lines.push(`#define CROSSBIND_APP_VERSION "${version.text}"`, `#define CROSSBIND_APP_VERSION_NUMBERS ${version.numbers}`);

package/src/utils/appRustCrates.js

@@ -23,9 +23,9 @@ export default function buildAppRustCrates(target, cacheDir, cargoDependencies =
         .map((e) => e.name);
 
     // Prune bridges whose source of truth is gone. An app-local surface whose .rs was deleted
-    // breaks cargo on the missing #[path] target; a crate_ bridge whose cargoDependencies entry
+    // breaks cargo on the missing #[path] target; a crate_ bridge whose packages.cargo entry
     // was removed silently keeps dead registrations in every later binary. crate_ pruning only
-    // runs when the caller passes the current cargoDependencies - null means "don't judge".
+    // runs when the caller passes the crates declared now - null means "don't judge".
     crates = crates.filter((name) => {
         const dir = `${root}/${name}`;
         const libRs = `${dir}/src/lib.rs`;

package/src/utils/appTargets.js

@@ -0,0 +1,168 @@
+import { IOS_DEPLOYMENT_TARGET } from './iosToolchain.js';
+
+// Apple's app extensions an iOS app's extensions add, each a target of the app's Xcode project of its own, by their
+// kinds: the extension point each runs at, which an other target names itself, the options it needs or may give, and
+// the frameworks iOS starts it with, which its code may name nothing of, so that the linker would leave them out.
+const KINDS = {
+    widget: { point: 'com.apple.widgetkit-extension', needs: [], takes: [] },
+    share: { point: 'com.apple.share-services', needs: ['principalClass', 'activation'], takes: [] },
+    'notification-service': { point: 'com.apple.usernotifications.service', needs: ['principalClass'], takes: [] },
+    'notification-content': {
+        point: 'com.apple.usernotifications.content-extension', needs: ['principalClass', 'categories'], takes: [], frameworks: ['UserNotifications', 'UserNotificationsUI'],
+    },
+    other: { point: null, needs: ['extensionPoint'], takes: ['principalClass'] },
+};
+
+// The frameworks a target links: its kind's, and its own.
+export const targetFrameworks = (target) => [...new Set([...(KINDS[target.kind].frameworks ?? []), ...(target.frameworks ?? [])])];
+
+// The widget targets whose Swift names no containerBackground, through which iOS 17 asks a widget's view for its
+// background: a debug build draws "Please adopt containerBackground API" in place of one without it. read(target, file)
+// gives a source's text.
+export const widgetsWithoutBackground = (targets, read) => targets
+    .filter((target) => target.kind === 'widget')
+    .filter((target) => !target.sources.some((file) => file.endsWith('.swift') && read(target, file).includes('containerBackground')))
+    .map((target) => target.name);
+const KIND_KEYS = ['principalClass', 'activation', 'categories', 'extensionPoint'];
+const TARGET_KEYS = ['name', 'kind', 'sources', 'resources', 'displayName', 'plist', 'entitlements', 'frameworks', 'privacy', 'appGroup',
+    'deploymentTarget', ...KIND_KEYS, 'attributes'];
+const NEEDED = {
+    principalClass: 'the class iOS makes as it starts the target',
+    activation: "what of the share sheet's items it takes, as { images: 10 }",
+    categories: 'the notification categories it shows',
+    extensionPoint: 'the extension point iOS runs it at, as com.apple.keyboard-service',
+};
+// What of the share sheet's items a share extension takes, by the keys of Apple's activation rule: a count of each kind,
+// and text or none.
+const ACTIVATION = {
+    attachments: 'NSExtensionActivationSupportsAttachmentsWithMaxCount',
+    files: 'NSExtensionActivationSupportsFileWithMaxCount',
+    images: 'NSExtensionActivationSupportsImageWithMaxCount',
+    movies: 'NSExtensionActivationSupportsMovieWithMaxCount',
+    text: 'NSExtensionActivationSupportsText',
+    urls: 'NSExtensionActivationSupportsWebURLWithMaxCount',
+    webPages: 'NSExtensionActivationSupportsWebPageWithMaxCount',
+};
+// The attributes crossbind writes from a target's options, and the Info.plist keys it writes for every target, the App
+// Group, which the target's code reads, of one that asks for it.
+const WRITTEN_ATTRIBUTES = { NSExtensionActivationRule: 'activation', UNNotificationExtensionCategory: 'categories' };
+const APP_GROUP_KEY = 'CrossbindAppGroup';
+const WRITTEN_KEYS = ['CFBundleDevelopmentRegion', 'CFBundleDisplayName', 'CFBundleExecutable', 'CFBundleIdentifier', 'CFBundleInfoDictionaryVersion',
+    'CFBundleName', 'CFBundlePackageType', 'CFBundleShortVersionString', 'CFBundleVersion', 'NSExtension', APP_GROUP_KEY];
+
+const NAME = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+const CLASS = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const EXTENSION_POINT = /^[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)+$/;
+const VERSION = /^\d+\.\d+$/;
+// ExtensionKit's points, whose extensions are of another product, in the app's Extensions, which crossbind makes none of.
+const EXTENSION_KIT_POINTS = ['com.apple.appintents-extension'];
+// What a target compiles apart from its headers, and the sources of Objective-C, beside which a class goes by its own name.
+export const isHeader = (file) => /\.(h|hpp)$/.test(file);
+const isObjectiveC = (file) => /\.(m|mm)$/.test(file);
+const kindOf = (kind) => `${/^[aeiou]/.test(kind) ? 'an' : 'a'} ${kind} target`;
+
+const isBelow = (version, floor) => {
+    const [major, minor] = version.split('.').map(Number);
+    const [floorMajor, floorMinor] = floor.split('.').map(Number);
+    return major < floorMajor || (major === floorMajor && minor < floorMinor);
+};
+
+// A target's name and kind, of the keys a target takes alone.
+export function checkedTargetKind(at, target) {
+    const unknown = Object.keys(target).find((key) => !TARGET_KEYS.includes(key));
+    if (unknown) throw new Error(`crossbind: ${at} takes ${TARGET_KEYS.join(', ')}; ${unknown} is none of them.`);
+    if (typeof target.name !== 'string' || !NAME.test(target.name)) {
+        throw new Error(`crossbind: ${at}.name ${JSON.stringify(target.name)} is no name of lowercase letters and digits, which dashes may join.`);
+    }
+    if (!Object.hasOwn(KINDS, target.kind)) throw new Error(`crossbind: ${at}.kind ${JSON.stringify(target.kind)} is none of ${Object.keys(KINDS).join(', ')}.`);
+}
+
+function checkedActivation(at, activation) {
+    const isTaken = (key, value) => Object.hasOwn(ACTIVATION, key) && (key === 'text' ? value === true : Number.isInteger(value) && value >= 1);
+    if (activation === null || typeof activation !== 'object' || Array.isArray(activation) || Object.keys(activation).length === 0
+        || !Object.entries(activation).every(([key, value]) => isTaken(key, value))) {
+        throw new Error(`crossbind: ${at}.activation is no object of ${Object.keys(ACTIVATION).join(', ')}, each a count from 1 and text true, as { images: 10, urls: 1 } is.`);
+    }
+}
+
+// What a target's kind takes and the rest of its own keys, once its sources and the values every part takes are checked.
+export function checkedTargetOptions(at, target, sources) {
+    const { kind } = target;
+    for (const key of KIND_KEYS) {
+        const isGiven = target[key] !== undefined;
+        if (isGiven && !KINDS[kind].needs.includes(key) && !KINDS[kind].takes.includes(key)) throw new Error(`crossbind: ${at}, ${kindOf(kind)}, takes no ${key}.`);
+        if (!isGiven && KINDS[kind].needs.includes(key)) throw new Error(`crossbind: ${at}, ${kindOf(kind)}, has no ${key}: ${NEEDED[key]}.`);
+    }
+    if (kind === 'widget' && !sources.some((file) => file.endsWith('.swift'))) {
+        throw new Error(`crossbind: ${at} is a widget, whose SwiftUI needs a Swift source among its sources.`);
+    }
+    if (target.principalClass !== undefined && (typeof target.principalClass !== 'string' || !CLASS.test(target.principalClass))) {
+        throw new Error(`crossbind: ${at}.principalClass ${JSON.stringify(target.principalClass)} is no class name.`);
+    }
+    if (target.activation !== undefined) checkedActivation(at, target.activation);
+    if (target.categories !== undefined
+        && (!Array.isArray(target.categories) || target.categories.length === 0 || !target.categories.every((id) => typeof id === 'string' && id !== ''))) {
+        throw new Error(`crossbind: ${at}.categories is no list of the notification categories the target shows.`);
+    }
+    if (target.extensionPoint !== undefined && (typeof target.extensionPoint !== 'string' || !EXTENSION_POINT.test(target.extensionPoint))) {
+        throw new Error(`crossbind: ${at}.extensionPoint ${JSON.stringify(target.extensionPoint)} is no extension point, as com.apple.keyboard-service is.`);
+    }
+    if (EXTENSION_KIT_POINTS.includes(target.extensionPoint)) {
+        throw new Error(`crossbind: ${at}.extensionPoint ${target.extensionPoint} is ExtensionKit's, whose extensions crossbind makes none of yet.`);
+    }
+    // The attributes of an option its kind takes, which an other target gives itself.
+    const written = Object.keys(target.attributes ?? {}).find((key) => Object.hasOwn(WRITTEN_ATTRIBUTES, key) && KINDS[kind].needs.includes(WRITTEN_ATTRIBUTES[key]));
+    if (written) throw new Error(`crossbind: ${at}.attributes gives ${written}, which crossbind writes from the target's ${WRITTEN_ATTRIBUTES[written]}.`);
+    const own = Object.keys(target.plist ?? {}).find((key) => WRITTEN_KEYS.includes(key));
+    if (own) throw new Error(`crossbind: ${at}.plist gives ${own}, which crossbind writes for each target.`);
+    const files = ['Info.plist', ...(target.privacy ? ['PrivacyInfo.xcprivacy'] : [])];
+    const resource = (target.resources ?? []).find((file) => files.includes(file.split('/').at(-1)));
+    if (resource) throw new Error(`crossbind: ${at}.resources names ${resource}, a file crossbind writes into the target's bundle.`);
+    const version = target.deploymentTarget;
+    if (version !== undefined && (typeof version !== 'string' || !VERSION.test(version))) {
+        throw new Error(`crossbind: ${at}.deploymentTarget ${JSON.stringify(version)} is no iOS version, as '17.0' is.`);
+    }
+    if (version !== undefined && isBelow(version, IOS_DEPLOYMENT_TARGET)) {
+        throw new Error(`crossbind: ${at}.deploymentTarget ${version} is below the app's iOS ${IOS_DEPLOYMENT_TARGET}, which each of its targets runs on as well.`);
+    }
+    if (target.appGroup !== undefined && typeof target.appGroup !== 'boolean') throw new Error(`crossbind: ${at}.appGroup is no boolean.`);
+    if (target.displayName !== undefined && (typeof target.displayName !== 'string' || target.displayName.trim() === '')) {
+        throw new Error(`crossbind: ${at}.displayName is no name the system shows.`);
+    }
+}
+
+// The Swift module a target's sources make, whose name takes no dash.
+export const targetModule = (name) => name.replace(/-/g, '_');
+
+// A target's Info.plist, as crossbind writes it, with the target's own keys: its bundle, by Xcode's settings, its
+// extension point, principal class and attributes, and the App Group it asks for. The principal class of a target
+// without Objective-C is Swift's, in its module, as Xcode's templates name it; one beside Objective-C goes by the name its
+// runtime knows.
+export function targetPlist(target, label, appGroup) {
+    const hasObjectiveC = target.sources.some(isObjectiveC);
+    const attributes = {
+        ...(target.kind === 'notification-content' ? { UNNotificationExtensionInitialContentSizeRatio: 1 } : {}),
+        ...target.attributes,
+        ...(target.activation ? { NSExtensionActivationRule: Object.fromEntries(Object.entries(target.activation).map(([key, value]) => [ACTIVATION[key], value])) } : {}),
+        ...(target.categories ? { UNNotificationExtensionCategory: target.categories.length === 1 ? target.categories[0] : target.categories } : {}),
+    };
+    const principal = target.principalClass && (hasObjectiveC ? target.principalClass : `$(PRODUCT_MODULE_NAME).${target.principalClass}`);
+    return {
+        CFBundleDevelopmentRegion: 'en',
+        CFBundleDisplayName: target.displayName ?? label,
+        CFBundleExecutable: '$(EXECUTABLE_NAME)',
+        CFBundleIdentifier: '$(PRODUCT_BUNDLE_IDENTIFIER)',
+        CFBundleInfoDictionaryVersion: '6.0',
+        CFBundleName: '$(PRODUCT_NAME)',
+        CFBundlePackageType: '$(PRODUCT_BUNDLE_PACKAGE_TYPE)',
+        CFBundleShortVersionString: '$(MARKETING_VERSION)',
+        CFBundleVersion: '$(CURRENT_PROJECT_VERSION)',
+        NSExtension: {
+            NSExtensionPointIdentifier: target.extensionPoint ?? KINDS[target.kind].point,
+            ...(principal ? { NSExtensionPrincipalClass: principal } : {}),
+            ...(Object.keys(attributes).length > 0 ? { NSExtensionAttributes: attributes } : {}),
+        },
+        ...(target.appGroup ? { [APP_GROUP_KEY]: appGroup } : {}),
+        ...target.plist,
+    };
+}