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

package/src/actions/xcodeTargets.js

@@ -0,0 +1,122 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { xmlPlist } from '../utils/plist.js';
+import { PRIVACY_CATEGORIES } from '../utils/appOptions.js';
+import { isHeader, targetFrameworks, targetModule, targetPlist, widgetsWithoutBackground } from '../utils/appTargets.js';
+
+const APP_GROUPS = 'com.apple.security.application-groups';
+// The kind of each file Xcode compiles or copies into a target, by its ending: a folder is copied as it is, and an asset
+// catalog compiled.
+const FILE_TYPES = {
+    '.swift': 'sourcecode.swift', '.m': 'sourcecode.c.objc', '.mm': 'sourcecode.cpp.objcpp', '.c': 'sourcecode.c.c', '.cpp': 'sourcecode.cpp.cpp',
+    '.cc': 'sourcecode.cpp.cpp', '.cxx': 'sourcecode.cpp.cpp', '.h': 'sourcecode.c.h', '.hpp': 'sourcecode.cpp.h', '.xcassets': 'folder.assetcatalog',
+    '.storyboard': 'file.storyboard', '.xib': 'file.xib', '.strings': 'text.plist.strings', '.xcstrings': 'text.json.xcstrings', '.png': 'image.png',
+    '.json': 'text.json',
+};
+
+// The privacy manifest of these reasons for Apple's required reason API, which App Store Connect asks of each bundle that
+// calls one.
+export const privacyManifest = (privacy) => xmlPlist({
+    NSPrivacyAccessedAPITypes: Object.entries(privacy).map(([name, reasons]) => ({
+        NSPrivacyAccessedAPIType: PRIVACY_CATEGORIES[name].type,
+        NSPrivacyAccessedAPITypeReasons: reasons,
+    })),
+});
+
+// Xcode names its objects by 24 hex digits: each target's go by its place among them, apart from the app's own.
+const idOf = (target, index) => `CE${target.toString(16).toUpperCase().padStart(4, '0')}${index.toString(16).toUpperCase().padStart(18, '0')}`;
+
+// Writes a target's folder beside the app's project, targets/<name>/: its sources and resources in files/, where they are
+// in their extension, its Info.plist, and its entitlements, the App Group among them where it asks for it, and its
+// privacy manifest where it has them.
+function writeTargetFiles(to, target, { label, appGroup }) {
+    const dir = `targets/${target.name}`;
+    fs.mkdirSync(`${to}/${dir}/files`, { recursive: true });
+    [...target.sources, ...(target.resources ?? [])].forEach((file) => fs.cpSync(path.join(target.root, file), `${to}/${dir}/files/${file}`, { recursive: true }));
+    fs.writeFileSync(`${to}/${dir}/Info.plist`, xmlPlist(targetPlist(target, label, appGroup)));
+    const own = target.entitlements ?? {};
+    const entitlements = target.appGroup ? { ...own, [APP_GROUPS]: [...new Set([...(own[APP_GROUPS] ?? []), appGroup])] } : own;
+    const hasEntitlements = Object.keys(entitlements).length > 0;
+    if (hasEntitlements) fs.writeFileSync(`${to}/${dir}/${target.name}.entitlements`, xmlPlist(entitlements));
+    const hasPrivacy = Object.keys(target.privacy ?? {}).length > 0;
+    if (hasPrivacy) fs.writeFileSync(`${to}/${dir}/PrivacyInfo.xcprivacy`, privacyManifest(target.privacy));
+    return { dir, hasEntitlements, hasPrivacy };
+}
+
+const linkedFrameworks = (frameworks) => (frameworks.length > 0 ? { OTHER_LDFLAGS: ['$(inherited)', ...frameworks.flatMap((name) => ['-framework', name])] } : {});
+
+// A target's build settings: its bundle, of the app's id and its name, signed as the app is, with the app's version and
+// build, and its own deployment target and frameworks.
+const targetSettings = (target, { dir, hasEntitlements }, { identity, version, build }) => ({
+    PRODUCT_NAME: target.name,
+    PRODUCT_MODULE_NAME: targetModule(target.name),
+    PRODUCT_BUNDLE_IDENTIFIER: `${identity.id}.${target.name}`,
+    DEVELOPMENT_TEAM: identity.team,
+    CODE_SIGN_STYLE: 'Automatic',
+    ...(hasEntitlements ? { CODE_SIGN_ENTITLEMENTS: `${dir}/${target.name}.entitlements` } : {}),
+    INFOPLIST_FILE: `${dir}/Info.plist`,
+    MARKETING_VERSION: version,
+    CURRENT_PROJECT_VERSION: build,
+    SKIP_INSTALL: 'YES',
+    APPLICATION_EXTENSION_API_ONLY: 'YES',
+    // Objective-C's @import, and the frameworks it links of itself.
+    CLANG_ENABLE_MODULES: 'YES',
+    LD_RUNPATH_SEARCH_PATHS: ['$(inherited)', '@executable_path/Frameworks', '@executable_path/../../Frameworks'],
+    ...(target.sources.some((file) => file.endsWith('.swift')) ? { SWIFT_VERSION: '5.0' } : {}),
+    ...(target.deploymentTarget ? { IPHONEOS_DEPLOYMENT_TARGET: target.deploymentTarget } : {}),
+    ...linkedFrameworks(targetFrameworks(target)),
+});
+
+// The project's objects of one target, by ids of its place among them: its files, build phases, configurations and the
+// target, with what the app's target takes of it, a dependency on it and the copy of its product into the app's PlugIns.
+function targetObjects(target, place, written, options) {
+    const objects = {};
+    let count = 0;
+    const add = (object) => {
+        count += 1;
+        objects[idOf(place, count)] = object;
+        return idOf(place, count);
+    };
+    const reference = (file, type) => add({ isa: 'PBXFileReference', lastKnownFileType: type, path: file, sourceTree: '<group>' });
+    const typeOf = (file) => FILE_TYPES[path.extname(file)] ?? (fs.statSync(path.join(target.root, file)).isDirectory() ? 'folder' : 'file');
+    const phase = (isa, files) => add({ isa, buildActionMask: 2147483647, files: files.map((fileRef) => add({ isa: 'PBXBuildFile', fileRef })), runOnlyForDeploymentPostprocessing: 0 });
+    // Its headers are in its group, which its sources import from beside them, and compile with them.
+    const headers = target.sources.filter(isHeader).map((file) => reference(`files/${file}`, typeOf(file)));
+    const sources = target.sources.filter((file) => !isHeader(file)).map((file) => reference(`files/${file}`, typeOf(file)));
+    const resources = [...(target.resources ?? []).map((file) => reference(`files/${file}`, typeOf(file))),
+        ...(written.hasPrivacy ? [reference('PrivacyInfo.xcprivacy', 'text.xml')] : [])];
+    const info = reference('Info.plist', 'text.plist.xml');
+    const signed = written.hasEntitlements ? [reference(`${target.name}.entitlements`, 'text.plist.entitlements')] : [];
+    const product = add({ isa: 'PBXFileReference', explicitFileType: 'wrapper.app-extension', includeInIndex: 0, path: `${target.name}.appex`, sourceTree: 'BUILT_PRODUCTS_DIR' });
+    const group = add({ isa: 'PBXGroup', children: [info, ...signed, ...headers, ...sources, ...resources], path: written.dir, sourceTree: '<group>' });
+    const phases = [phase('PBXSourcesBuildPhase', sources), phase('PBXFrameworksBuildPhase', []), phase('PBXResourcesBuildPhase', resources)];
+    const buildSettings = targetSettings(target, written, options);
+    const configurations = ['Debug', 'Release'].map((name) => add({ isa: 'XCBuildConfiguration', buildSettings, name }));
+    const list = add({ isa: 'XCConfigurationList', buildConfigurations: configurations, defaultConfigurationIsVisible: 0, defaultConfigurationName: 'Release' });
+    const native = add({
+        isa: 'PBXNativeTarget', buildConfigurationList: list, buildPhases: phases, buildRules: [], dependencies: [], name: target.name,
+        productName: target.name, productReference: product, productType: 'com.apple.product-type.app-extension',
+    });
+    const proxy = add({ isa: 'PBXContainerItemProxy', containerPortal: options.project, proxyType: 1, remoteGlobalIDString: native, remoteInfo: target.name });
+    const dependency = add({ isa: 'PBXTargetDependency', target: native, targetProxy: proxy });
+    const embedded = add({ isa: 'PBXBuildFile', fileRef: product, settings: { ATTRIBUTES: ['RemoveHeadersOnCopy'] } });
+    return { objects, group, product, native, dependency, embedded };
+}
+
+// Writes the folder of each target of Apple's app extensions the app's extensions add, and gives the project's objects
+// for them: each a target whose bundle is the app's id and its name, which the app builds first and embeds in its PlugIns.
+export function writeTargets(to, targets, options) {
+    widgetsWithoutBackground(targets, (target, file) => fs.readFileSync(path.join(target.root, file), 'utf8')).forEach((name) => {
+        console.warn(`crossbind: the widget target ${name} names no containerBackground in its Swift, which iOS 17 asks of a widget's view: a debug build `
+            + 'draws "Please adopt containerBackground API" in its place. Its view gives its background with .containerBackground(.background, for: .widget).');
+    });
+    const made = targets.map((target, place) => targetObjects(target, place, writeTargetFiles(to, target, options), options));
+    return {
+        objects: Object.assign({}, ...made.map(({ objects }) => objects)),
+        groups: made.map(({ group }) => group),
+        products: made.map(({ product }) => product),
+        dependencies: made.map(({ dependency }) => dependency),
+        targets: made.map(({ native }) => native),
+        embedded: made.map(({ embedded }) => embedded),
+    };
+}

package/src/actions/xcodebuild.js

@@ -0,0 +1,65 @@
+import fs from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { EXEC_MAX_BUFFER } from './run.js';
+
+const DEVELOPER_ACCOUNT = 'https://developer.apple.com/account';
+// The lines of a failed xcodebuild's output that say why; its log has the rest.
+const REASON_LINES = 15;
+
+// What a failed build, archive or upload means where xcodebuild's own words leave it unclear: what the user mends in
+// Xcode or on Apple's sites, and the page where. A cause may need another build, as one in what was built does.
+const CAUSES = [
+    {
+        pattern: /login details for account .* were rejected|No Accounts?\b|No Account for Team/i,
+        hint: ({ team }) => `Xcode is signed in to no account of team ${team}, or its sign-in has lapsed: sign in again in Xcode, under Settings › Accounts.`,
+    },
+    {
+        pattern: /PLA Update available|Program License Agreement/i,
+        hint: () => `Apple has a new Program License Agreement, which the team's Account Holder accepts at ${DEVELOPER_ACCOUNT}.`,
+        page: DEVELOPER_ACCOUNT,
+    },
+    {
+        pattern: /Cloud signing permission error/i,
+        hint: () => "the API key may not sign in the cloud, which takes its Admin role: use an Admin key, make an Apple Distribution certificate once in Xcode, under Settings › Accounts › Manage Certificates, or unset CROSSBIND_APPLE_API_KEY to upload with Xcode's account.",
+    },
+    {
+        pattern: /cannot be registered to your development team because it is not available/i,
+        hint: ({ id }) => `another team registered the bundle id ${id} with Apple first: set app.id in crossbind.config.js to an id of your own, as one under a domain you own.`,
+        // The id is in what was built, so the same step tried again fails the same way.
+        needsRebuild: true,
+    },
+];
+
+// Runs xcodebuild with its output in `log`, which it returns. Its failure names the lines that say why, and what to do
+// where those leave it unclear, from crossbind's causes first, then those the caller adds: the error says whether the
+// user can mend it and try again, the page where, and the cause it found.
+export function xcodebuild(what, args, { log, facts = {}, causes = [] }) {
+    const out = fs.openSync(log, 'w');
+    let result;
+    try {
+        result = spawnSync('xcodebuild', args, { stdio: ['ignore', out, out] });
+    } finally {
+        fs.closeSync(out);
+    }
+    if (result.error) throw new Error(`crossbind: cannot run xcodebuild, which comes with Xcode: ${result.error.message}`, { cause: result.error });
+    if (result.signal) throw new Error(`crossbind: ${what} stopped on ${result.signal}.`);
+    const output = fs.readFileSync(log, 'utf8');
+    if (result.status === 0) return output;
+    const reasons = [...new Set(output.split('\n').map((line) => line.trim()).filter((line) => /\berror\b|ITMS-/i.test(line)))].slice(-REASON_LINES);
+    const cause = [...CAUSES, ...causes].find(({ pattern }) => pattern.test(output));
+    const lines = [`crossbind: ${what} failed; xcodebuild's log is ${log}.`, ...reasons.map((line) => `  ${line}`), ...(cause ? [`crossbind: ${cause.hint(facts)}`] : [])];
+    throw Object.assign(new Error(lines.join('\n')), { isMendable: Boolean(cause) && !cause.needsRebuild, page: cause?.page ?? null, reason: cause ?? null });
+}
+
+// The teams of the accounts signed in to Xcode that upload to App Store Connect, which a free personal team does not,
+// from Xcode's settings; `withPersonal` adds those free teams, which sign for their own devices.
+export function xcodeTeams({ withPersonal = false } = {}) {
+    const settings = spawnSync('defaults', ['export', 'com.apple.dt.Xcode', '-'], { maxBuffer: EXEC_MAX_BUFFER });
+    if (settings.status !== 0) return [];
+    const teams = spawnSync('plutil', ['-extract', 'IDEProvisioningTeamByIdentifier', 'json', '-o', '-', '-'], {
+        input: settings.stdout, encoding: 'utf8', maxBuffer: EXEC_MAX_BUFFER,
+    });
+    if (teams.status !== 0) return [];
+    const signing = Object.values(JSON.parse(teams.stdout)).flat().filter((team) => withPersonal || !team.isFreeProvisioningTeam);
+    return [...new Map(signing.map((team) => [team.teamID, { id: team.teamID, name: team.teamName }])).values()];
+}

package/src/app/index.d.ts

@@ -1,171 +1,183 @@
-// What an app's host does for its page (target.runtimeEnv: 'app'); in any other build every call rejects.
+// What an app's host does for its page (target.runtimeEnv: 'app'): crossbind/app/core alone, which crossbind/app has with
+// what crossbind's own extensions give the page. A TypeScript app has their types with
+// /// <reference types="@crossbind/core-app-host/app" />.
 
-/** 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. */
+/** The app's own folders, made when first asked for: what it keeps, what it can lose, and its logs; and the read-only one of the files app.files lists, each in the place it had in the project. */
 export interface AppPaths {
     data: string;
     cache: string;
     logs: string;
+    resources: string;
+    /** An iOS app's App Group's folder, which the targets of its extensions' that ask for it with appGroup: true share; '' elsewhere. */
+    group: 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>;
-    /** A file or folder moved to the system's trash, where its user can take it back: one in the app's folders, not one of them itself, or one a dialog picked during this run. Where the system has no trash, nothing moves and it rejects. */
-    trash(path: string): Promise<void>;
-};
-
 export declare const app: {
     paths(): Promise<AppPaths>;
     /** Ends the app as closing its window does. */
     quit(): Promise<void>;
+    /** Asks the app's extensions, as its user's Quit does, then ends the app as quit() does, unless one keeps it running. It resolves once it has asked the host, before the answer. */
+    requestQuit(): Promise<void>;
     /** Ends the app as quit() does, then opens it again, with no link. */
     relaunch(): 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[]>;
+    /** The launch that started a desktop app. A phone's has no arguments, and no folder. */
+    launchArgs(): Promise<Launch>;
 };
 
-/** 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;
+/** Where the app runs, as its host tells the page before the page's own scripts run; the same through the app's run. */
+export interface Device {
+    /** The platform the app is built for. */
+    readonly platform: 'macos' | 'windows' | 'linux' | 'ios' | 'android';
+    /** The arch the app's process runs as. */
+    readonly arch: 'arm64' | 'x64';
+    /** What the device is to its user as the app starts: a phone; a tablet, an iPad or an Android device whose screen's shorter side has 600dp; or a desktop, a computer, a Chromebook or a Mac that runs an iOS app. */
+    readonly formFactor: 'phone' | 'tablet' | 'desktop';
+    /** The system's name and version, as its maker numbers it: iOS or iPadOS 18.4, Android 15 with its API level, macOS 26.1, Windows 10.0.26100, or a Linux distribution's, as Ubuntu 24.04, else its kernel's release. */
+    readonly os: { readonly name: string; readonly version: string; readonly apiLevel?: number };
+    /** Whether the iOS Simulator or an Android emulator runs the app. */
+    readonly isVirtual: 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>;
-};
+/** Where the app runs, read at once, as the page starts; reading it outside an app throws. */
+export declare const device: Device;
 
-/** An item of the tray's menu: one the page handles, by its id, a submenu or a separator. */
-export type TrayItem =
-    | { label: string; id?: string; enabled?: boolean; checked?: boolean }
-    | { label: string; items: TrayItem[] }
-    | { type: 'separator' };
-
-export interface TrayOptions {
-    /** What the icon shows when the pointer rests on it. */
-    tooltip?: string;
-    /** The menu a click of the icon opens: a click on macOS, a right click on Windows, and on Linux the one its desktop takes. */
-    menu?: TrayItem[];
+/** What windows.set() changes of an open window: sizes and places in logical pixels, a page's size without the frame, and x and y the frame's place from the top left of the main screen, given together. A limit of 0 takes it away. */
+export interface WindowChanges {
+    title?: string;
+    width?: number;
+    height?: number;
+    x?: number;
+    y?: number;
+    /** Moves the window to the middle of its screen. */
+    center?: boolean;
+    minWidth?: number;
+    minHeight?: number;
+    maxWidth?: number;
+    maxHeight?: number;
+    resizable?: boolean;
+    /** Keeps the window above the other apps' windows. */
+    alwaysOnTop?: boolean;
+    fullscreen?: boolean;
 }
 
-export declare const tray: {
-    /** The app's icon in the macOS menu bar, the Windows notification area or a Linux desktop's status tray. A click of an item with an id is the event menu, with a MenuClick, and a click of the icon the event tray where it opens no menu. Set again, it changes the icon that shows. */
-    set(options?: TrayOptions): Promise<void>;
-    /** Takes the icon away. */
-    remove(): Promise<void>;
-};
+/** What a window opens with: app.window's options, beside the page it loads and its name. Without x and y it opens in the middle of the screen. */
+export interface WindowOptions extends Omit<WindowChanges, 'center' | 'minWidth' | 'minHeight' | 'maxWidth' | 'maxHeight'> {
+    /** The app's own page, as /settings.html?tab=2: '/' by default. */
+    path?: string;
+    /** A name of the app's own: a window of a name already open comes to the front, and no other opens. */
+    name?: string;
+    minWidth?: number;
+    minHeight?: number;
+    maxWidth?: number;
+    maxHeight?: number;
+    /** What the window shows until the page paints, as #rrggbb: app.window's by default. */
+    backgroundColor?: string;
+    /** false opens a window without a title bar and its buttons, which the page moves with data-crossbind-drag or windows.startDrag(). */
+    frame?: boolean;
+    /** 'hidden' lays a macOS window's page under its title bar, whose buttons stay at its top left, as app.window.titleBar does; Windows and Linux keep their title bar and list it in ignored. */
+    titleBar?: 'visible' | 'hidden';
+    /** The id of the window it stays above, and closes with. */
+    parent?: number;
+    /** With a parent: a sheet of the parent's on macOS, and on Windows and Linux a window the parent takes no input under until it closes. */
+    modal?: boolean;
+}
 
-export interface NotificationOptions {
+/** An open window, as windows.list() tells of it. */
+export interface WindowState {
+    id: number;
+    name: string | null;
     title: string;
-    body?: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    isMaximized: boolean;
+    isMinimized: boolean;
+    isFullscreen: boolean;
+    isFocused: boolean;
+}
+
+/** What windows.open() and windows.set() answer: the window's id, and the options the platform could not honour, which it did without, as Wayland's x and y. */
+export interface WindowOpened {
+    id: number;
+    ignored: string[];
+}
+
+/** What the events window-opened and window-closed carry. */
+export interface WindowEvent {
+    id: number;
+    name: string | null;
 }
 
-export declare const notification: {
-    /** A notification of the system's; a click on it is the event notification. macOS asks its user first. */
-    show(options: NotificationOptions): Promise<void>;
+export declare const windows: {
+    /** Opens a window of the app's own page, in front, on the desktop and an iPad whose app.ios.multipleWindows is true; an iPhone and Android reject. */
+    open(options?: WindowOptions): Promise<WindowOpened>;
+    /** Changes the window of this id, or the page's own without one. */
+    set(changes: WindowChanges): Promise<{ ignored: string[] }>;
+    set(id: number, changes: WindowChanges): Promise<{ ignored: string[] }>;
+    /** Closes the window of this id, or the page's own without one, as its user does: an extension may keep it open. The app quits as its last window closes. */
+    close(id?: number): Promise<void>;
+    /** Brings the window of this id, or the page's own without one, to the front, restored if it was minimized. */
+    focus(id?: number): Promise<void>;
+    minimize(id?: number): Promise<void>;
+    toggleMaximize(id?: number): Promise<void>;
+    /** Moves the page's window with the pointer, as its title bar does, from a mousedown of the primary button. */
+    startDrag(): Promise<void>;
+    /** The open windows, the oldest first. */
+    list(): Promise<WindowState[]>;
+    /** The page's own window. */
+    current(): Promise<WindowState>;
 };
 
-/** 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 {
+/** A launch of a desktop app: its arguments, the program's own and its links left out, which reach the owners of their schemes, the page those of app.urlSchemes as the event open-url; and the folder it was launched in. */
+export interface Launch {
     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;
+/** What each event a page's listeners get gives them, by the event's name: the host's own here, and those an extension's types add. */
+export interface AppEvents {
+    /** Calls listener as the app becomes the active one on the desktop, or comes to a phone's foreground, until the function it returns is called. A Linux app's is its window's focus. */
+    'active': void;
+    /** Calls listener as another app takes the app's place on the desktop, or a phone's is interrupted, as by a call, a system alert or another app's picker, or goes to the background, until the function it returns is called. */
+    'inactive': void;
+    /** Calls listener as each window of the app's opens, until the function it returns is called. */
+    'window-opened': WindowEvent;
+    /** Calls listener as each window of the app's closes, until the function it returns is called. */
+    'window-closed': WindowEvent;
 }
 
+/** What each event the host holds for the page gives, by the event's name, which an extension's types add. */
+export interface HeldEvents {}
+
 export declare const events: {
-    /** Calls listener with each click of an item with an id in the menus menu.set sets or in the tray's menu, 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 as the system of a desktop app goes to sleep, which it may do before the page has run, until the function it returns is called. */
-    on(name: 'suspend', listener: () => void): () => void;
-    /** Calls listener as the system of a desktop app wakes from sleep, until the function it returns is called. */
-    on(name: 'resume', listener: () => void): () => void;
-    /** Calls listener with each left or right click of the tray's icon that opens no menu, until the function it returns is called. */
-    on(name: 'tray', listener: () => void): () => void;
-    /** Calls listener with each click on a notification the app's notification.show showed while it runs, until the function it returns is called. */
-    on(name: 'notification', listener: () => void): () => void;
+    on<Name extends keyof AppEvents>(name: Name, listener: (value: AppEvents[Name]) => 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;
+    held<Name extends keyof HeldEvents>(name: Name): Promise<HeldEvents[Name][]>;
+    /** The values of the events of this name the app's native code held for the page with holdEvent(), which came before the page asked for them since it loaded; later ones come as the events while it listens, so listening first, then asking, misses none. */
+    held(name: string): Promise<unknown[]>;
 };
 
-/** A newer version of the app, which app.updater.url in crossbind.config.js offers. */
-export interface Update {
-    version: string;
+/** What an option of a page's function is, beside what typeof tells: how it is checked, and what it is called. */
+export interface OptionKind {
+    isFitting(value: unknown): boolean;
+    name: 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>;
-};
+/** The options as the host takes them, so a misspelt or mistyped one fails here, saying which. */
+export declare function checkedOptions<T>(name: string, options: T, kinds: Record<string, string | OptionKind>): T;
+
+/** What invoke takes beside a function's options. */
+export interface InvokeOptions<M = unknown> {
+    /** Gets each message the function sends before it answers, in the order it sent them, all of them before invoke resolves. */
+    onMessage?: (message: M) => void;
+    /** Cancels the call: invoke rejects with the signal's reason, and the function hears of it. A new page cancels each call of the one before. */
+    signal?: AbortSignal;
+}
+
+/** A function of one of the app's extensions, by its name, as clipboard.readText, with options of JSON values and bytes, a typed array, a DataView or an ArrayBuffer, whose result's bytes come back as a Uint8Array; an extension's own package calls it so. */
+export declare function invoke<T = unknown, M = unknown>(name: string, options?: Record<string, unknown>, call?: InvokeOptions<M>): Promise<T>;
+
+/** The URL of a path an extension's route serves, as "/clips/intro.mp4" or "/thumb/42?size=256", for the page's <img>, <video> or fetch(): crossbind://app/ext/<extension><path>, and https://appassets.androidplatform.net/ext/<extension><path> on Android. The path is as a URL holds it, escaped where it must be, without a part "." or ".."; the route gets it decoded. */
+export declare function routeUrl(extension: string, path: string): string;