@blotch/angular-lynx-native 22.2.4 → 22.2.5

package/README.md

@@ -9,6 +9,7 @@ User documentation: [Publishing your App](../website/docs/guide/building-for-pro
 1. **Generates** the native project from `templates/ios` or `templates/android` into the project's folder in Angular's build cache (`.angular/cache/<Angular version>/<project>/lynx-native/<platform>`, which `ng new` already gitignores and `ng cache clean` clears), writing the app options from `angular.json` into the few files the templates mark for it. It regenerates only when a hash of its inputs changes (this package's version, the template, the options, the icon), so Xcode and Gradle keep their incremental state.
 2. **Copies** `dist/` (without the web bundle) into the project.
 3. **Builds** it with `xcodebuild` or Gradle and copies the binaries to `dist/<platform>/`.
+4. **Runs** it, with `--run` (`src/ios/run.ts`, `src/android/run.ts`): picks a simulator, emulator or phone (`--device`, else a running one, else the newest iPhone simulator or the first AVD) and starts it before step 3, so it boots while the app compiles; then installs the app and opens it. iOS uses `simctl` and shows the simulator in DeviceHub (`devices://device/open?id=<UDID>`) or, before Xcode 27.1, the Simulator app. Android uses the SDK's `adb` and `emulator` and opens the launcher activity by component.
 
 An ejected project (`ios/` or `android/` with a `.angular-lynx-ejected` marker, written by `ng generate @blotch/angular-lynx:eject`) is built as it is and never regenerated.
 
@@ -16,9 +17,9 @@ An ejected project (`ios/` or `android/` with a `.angular-lynx-ejected` marker,
 
 Both are one full-screen `LynxView` running `main.lynx.bundle`; Angular Router does all navigation inside it. Bundles and assets load from inside the app, so RSpeedy's default asset prefix (`/static/...`) works with no configuration. The `LynxView` sits inside the safe area, so CSS `env(safe-area-inset-*)` is 0 in it.
 
-Both send the same global props, which the runtime's services read: `platform`, `theme` (again whenever the phone switches between light and dark), `appLocale` (the phone's language as a BCP 47 tag), `isNotchScreen`, the safe-area insets `safeAreaTop`, `safeAreaBottom`, `safeAreaLeft` and `safeAreaRight`, `osVersion` (which Lynx leaves out of the main thread's `SystemInfo`), and the accessibility settings `reduceMotion`, `reduceTransparency` (iOS only) and `increaseContrast`, again whenever the user changes one. Lynx Explorer sends `theme` and `isNotchScreen` too, but no `appLocale`, `osVersion` or accessibility settings. See [`templates/android/README.md`](templates/android/README.md) for the Android shell's details.
+Both send the same global props, which the runtime's services read: `platform`, `theme` (again whenever the phone switches between light and dark), `appLocale` (the phone's language as a BCP 47 tag), `isNotchScreen`, the safe-area insets `safeAreaTop`, `safeAreaBottom`, `safeAreaLeft` and `safeAreaRight`, `osVersion` (which Lynx leaves out of the main thread's `SystemInfo`), and the accessibility settings `reduceMotion`, `reduceTransparency` (iOS only) and `increaseContrast`, again whenever the user changes one. Android 12 and later also send `dynamicColors`, the wallpaper's Material 3 color roles in light and dark (`DynamicColors.kt`), again when the user changes their wallpaper or colors. Lynx Explorer sends `theme` and `isNotchScreen` too, but no `appLocale`, `osVersion` or accessibility settings. See [`templates/android/README.md`](templates/android/README.md) for the Android shell's details.
 
-Both link Lynx's XElement library, which holds `<input>`, `<textarea>`, `<overlay>`, `<svg>`, `<blur-view>`, `<viewpager>`, `<refresh>`, the `<scroll-coordinator>` family, `<webview>` and `<video>`. Lynx's core doesn't include these, and a host that doesn't register them renders nothing for those tags (on Android, nothing after them either). XElement's AnimaX and Markdown elements are left out: the runtime doesn't support them.
+Both link Lynx's XElement library, which holds `<input>`, `<textarea>`, `<overlay>`, `<svg>`, `<blur-view>`, `<viewpager>`, `<refresh>`, the `<scroll-coordinator>` family, `<webview>` and `<video>`. Lynx's core doesn't include these, and a host that doesn't register them renders nothing for those tags (on Android, nothing after them either). XElement's AnimaX and Markdown elements are left out: the runtime doesn't support them. On iOS, `<blur-view>` is XElement's with more of UIKit in it (`App/BlurView.swift`): a `blur-material` attribute for UIKit's adaptive blur materials, which the glass components draw their design before iOS 26 on (Lynx's blur-view has only the styles from before iOS 13); Liquid Glass that materializes, dissolves and eases between effects inside a `glass-container`, where Lynx's sets its effect at once; and a `glass-effect-id` attribute that pairs two glass shapes across a change so one morphs into the other (`App/GlassTransitions.swift`).
 
 |                  | iOS                                                  | Android                                                  |
 | ---------------- | ---------------------------------------------------- | -------------------------------------------------------- |

package/dist/android/run.d.ts

@@ -0,0 +1,61 @@
+import type { RunTarget } from '../run.ts';
+/**
+ * The activity the shell template declares: its manifest names `.MainActivity`
+ * in the `dev.angularlynx.shell` namespace, whatever the app's ID is.
+ */
+export declare const SHELL_ACTIVITY = "dev.angularlynx.shell.MainActivity";
+export type AdbDevice = {
+    readonly serial: string;
+    /** `device` when it's ready; also `offline`, `unauthorized`, ... */
+    readonly state: string;
+    /** The phone's model from `adb devices -l`, with spaces for its underscores. */
+    readonly model?: string;
+};
+/**
+ * Parses `adb devices -l`: a header, then one line per emulator or phone,
+ * e.g. `1A2B3C  device usb:1-2 product:husky model:Pixel_8 ...`.
+ */
+export declare const parseAdbDevices: (output: string) => AdbDevice[];
+/** Where `--run` opens the app: a running device, or a virtual device to start. */
+export type AndroidChoice = {
+    readonly serial: string;
+    readonly label: string;
+} | {
+    readonly avd: string;
+    readonly label: string;
+};
+/**
+ * Chooses the device `ng build --platform android --run` opens the app on.
+ *
+ * With `--device`, the running emulator or phone with that adb serial, the
+ * running emulator of that virtual device, or else that virtual device,
+ * started. Otherwise the first running emulator or connected phone (one
+ * that's still booting counts), or else the first virtual device, started.
+ */
+export declare const pickAndroidDevice: (devices: readonly AdbDevice[], device: string | undefined, { avdName, listVirtualDevices, }: {
+    /** The virtual device a running emulator runs, from its console. */
+    readonly avdName: (serial: string) => Promise<string | undefined>;
+    readonly listVirtualDevices: () => Promise<readonly string[]>;
+}) => Promise<AndroidChoice>;
+/** How long `--run` waits for an emulator to boot, and how often it checks. */
+declare const TIMING: {
+    pollMs: number;
+    timeoutMs: number;
+};
+/**
+ * Picks the device for `--run` and, when it's a virtual device that isn't
+ * running, starts its emulator, so it boots while Gradle builds. The returned
+ * target installs and opens the app once it's built.
+ *
+ * adb and the emulator are run from the SDK the build already found, so
+ * nobody has to put the SDK's folders on their PATH.
+ */
+export declare const startAndroidDevice: ({ device, logFile, log, env, timing, }: {
+    readonly device: string | undefined;
+    readonly logFile: string;
+    readonly log: (message: string) => void;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly timing?: typeof TIMING;
+}) => Promise<RunTarget>;
+export {};
+//# sourceMappingURL=run.d.ts.map

package/dist/android/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/android/run.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAG3C;;;GAGG;AACH,eAAO,MAAM,cAAc,uCAAuC,CAAC;AAEnE,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,gFAAgF;IAChF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,eAAe,GAAI,QAAQ,MAAM,KAAG,SAAS,EAQtD,CAAC;AAIL,mFAAmF;AACnF,MAAM,MAAM,aAAa,GACrB;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAErD;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,GAC5B,SAAS,SAAS,SAAS,EAAE,EAC7B,QAAQ,MAAM,GAAG,SAAS,EAC1B,kCAGG;IACD,oEAAoE;IACpE,QAAQ,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAClE,QAAQ,CAAC,kBAAkB,EAAE,MAAM,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAAC;CAC/D,KACA,OAAO,CAAC,aAAa,CAsEvB,CAAC;AAEF,+EAA+E;AAC/E,QAAA,MAAM,MAAM;;;CAA0C,CAAC;AAEvD;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,GAAU,wCAMtC;IACD,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,MAAM,CAAC;CACjC,KAAG,OAAO,CAAC,SAAS,CAsJpB,CAAC"}

package/dist/android/run.js

@@ -0,0 +1,241 @@
+import { spawn } from 'node:child_process';
+import { closeSync, existsSync, openSync } from 'node:fs';
+import path from 'node:path';
+import { NativeBuildError, capture, run } from "../process.js";
+import { findAndroidSdk } from "./project.js";
+/**
+ * The activity the shell template declares: its manifest names `.MainActivity`
+ * in the `dev.angularlynx.shell` namespace, whatever the app's ID is.
+ */
+export const SHELL_ACTIVITY = 'dev.angularlynx.shell.MainActivity';
+/**
+ * Parses `adb devices -l`: a header, then one line per emulator or phone,
+ * e.g. `1A2B3C  device usb:1-2 product:husky model:Pixel_8 ...`.
+ */
+export const parseAdbDevices = (output) => output.split('\n').flatMap((line) => {
+    const match = /^(\S+)\s+(\S+)(.*)$/.exec(line.trim());
+    if (!match || line.startsWith('List of devices') || line.startsWith('*')) {
+        return [];
+    }
+    const model = /\bmodel:(\S+)/.exec(match[3])?.[1]?.replace(/_/g, ' ');
+    return [{ serial: match[1], state: match[2], ...(model && { model }) }];
+});
+const isEmulator = (device) => device.serial.startsWith('emulator-');
+/**
+ * Chooses the device `ng build --platform android --run` opens the app on.
+ *
+ * With `--device`, the running emulator or phone with that adb serial, the
+ * running emulator of that virtual device, or else that virtual device,
+ * started. Otherwise the first running emulator or connected phone (one
+ * that's still booting counts), or else the first virtual device, started.
+ */
+export const pickAndroidDevice = async (devices, device, { avdName, listVirtualDevices, }) => {
+    const running = async (candidate) => {
+        if (candidate.state === 'unauthorized') {
+            throw new NativeBuildError(`${candidate.model ?? candidate.serial} hasn't allowed USB debugging from this computer. Unlock it, accept the prompt, and build again.`);
+        }
+        const avd = isEmulator(candidate)
+            ? await avdName(candidate.serial)
+            : undefined;
+        return {
+            serial: candidate.serial,
+            label: avd
+                ? `the ${avd} emulator`
+                : isEmulator(candidate)
+                    ? `the emulator ${candidate.serial}`
+                    : (candidate.model ?? candidate.serial),
+        };
+    };
+    const usable = devices.filter((candidate) => candidate.state === 'device' ||
+        candidate.state === 'unauthorized' ||
+        // An emulator that's still booting: launch() waits for it.
+        (isEmulator(candidate) && candidate.state === 'offline'));
+    if (device) {
+        const bySerial = usable.find((candidate) => candidate.serial === device);
+        if (bySerial) {
+            return running(bySerial);
+        }
+        for (const candidate of usable.filter(isEmulator)) {
+            if ((await avdName(candidate.serial)) === device) {
+                return running(candidate);
+            }
+        }
+        const virtualDevices = await listVirtualDevices();
+        if (virtualDevices.includes(device)) {
+            return { avd: device, label: `the ${device} emulator` };
+        }
+        const known = [
+            ...usable.map((candidate) => candidate.serial),
+            ...virtualDevices,
+        ];
+        throw new NativeBuildError(`There's no running emulator, connected phone or virtual device named "${device}". ${known.length > 0
+            ? `Pass one of these: ${known.join(', ')}.`
+            : "Create a virtual device in Android Studio's Device Manager."}`);
+    }
+    // A ready one before one that's booting, and before a phone that hasn't
+    // allowed debugging yet, which only gets a message saying so.
+    const first = usable.find((candidate) => candidate.state === 'device') ??
+        usable.find((candidate) => candidate.state === 'offline') ??
+        usable[0];
+    if (first) {
+        return running(first);
+    }
+    const [avd] = await listVirtualDevices();
+    if (avd) {
+        return { avd, label: `the ${avd} emulator` };
+    }
+    throw new NativeBuildError("No emulator is running, no phone is connected, and there's no virtual device to start. Create one in Android Studio's Device Manager, or connect a phone with USB debugging turned on.");
+};
+/** How long `--run` waits for an emulator to boot, and how often it checks. */
+const TIMING = { pollMs: 1000, timeoutMs: 5 * 60_000 };
+/**
+ * Picks the device for `--run` and, when it's a virtual device that isn't
+ * running, starts its emulator, so it boots while Gradle builds. The returned
+ * target installs and opens the app once it's built.
+ *
+ * adb and the emulator are run from the SDK the build already found, so
+ * nobody has to put the SDK's folders on their PATH.
+ */
+export const startAndroidDevice = async ({ device, logFile, log, env = process.env, timing = TIMING, }) => {
+    const sdk = findAndroidSdk(env);
+    if (!sdk) {
+        throw new NativeBuildError('The Android SDK was not found. Install Android Studio (which installs the SDK), or set ANDROID_HOME to an existing SDK.');
+    }
+    const exe = process.platform === 'win32' ? '.exe' : '';
+    const adbPath = path.join(sdk, 'platform-tools', `adb${exe}`);
+    const emulatorPath = path.join(sdk, 'emulator', `emulator${exe}`);
+    if (!existsSync(adbPath)) {
+        throw new NativeBuildError(`adb isn't in ${sdk}. Install Android SDK Platform-Tools in Android Studio's SDK Manager, under SDK Tools.`);
+    }
+    const adb = (args) => run(adbPath, args, { cwd: process.cwd(), logFile });
+    const listDevices = async () => {
+        const output = await capture(adbPath, ['devices', '-l']);
+        if (output === undefined) {
+            throw new NativeBuildError(`\`${adbPath} devices\` failed. Run it yourself to see why.`);
+        }
+        return parseAdbDevices(output);
+    };
+    const before = await listDevices();
+    const choice = await pickAndroidDevice(before, device, {
+        avdName: async (serial) => (await capture(adbPath, ['-s', serial, 'emu', 'avd', 'name']))
+            ?.split('\n')[0]
+            ?.trim(),
+        listVirtualDevices: async () => existsSync(emulatorPath)
+            ? ((await capture(emulatorPath, ['-list-avds'])) ?? '')
+                .split('\n')
+                .map((line) => line.trim())
+                // AVD names are letters, digits, dots, dashes and underscores;
+                // this drops the INFO lines some emulator versions print.
+                .filter((line) => /^[\w.-]+$/.test(line))
+            : [],
+    });
+    let emulator;
+    if ('avd' in choice) {
+        log(`Starting ${choice.label}`);
+        emulator = startEmulator(emulatorPath, choice.avd, logFile);
+    }
+    else {
+        log(`Running the app on ${choice.label}`);
+    }
+    const emulatorLog = emulatorLogFile(logFile);
+    return {
+        launch: async (binary, app) => {
+            const serials = new Set(before.map((candidate) => candidate.serial));
+            let serial = 'serial' in choice ? choice.serial : undefined;
+            // An emulator shows up in `adb devices` a few seconds after it starts,
+            // and answers `sys.boot_completed` once Android has started, which
+            // takes from seconds (from a snapshot) to minutes (a cold boot).
+            const deadline = Date.now() + timing.timeoutMs;
+            for (;;) {
+                const stopped = emulator?.stopped();
+                if (stopped) {
+                    throw new NativeBuildError(`The emulator stopped while starting (${stopped}). Its output is in ${emulatorLog}.`);
+                }
+                serial ??= (await listDevices()).find((candidate) => isEmulator(candidate) && !serials.has(candidate.serial))?.serial;
+                const bootCompleted = serial &&
+                    (await capture(adbPath, [
+                        '-s',
+                        serial,
+                        'shell',
+                        'getprop',
+                        'sys.boot_completed',
+                    ]));
+                if (bootCompleted && bootCompleted.trim() === '1') {
+                    break;
+                }
+                if (Date.now() > deadline) {
+                    throw new NativeBuildError(`${capitalize(choice.label)} didn't finish starting within ${timing.timeoutMs / 60_000} minutes.${emulator ? ` The emulator's output is in ${emulatorLog}.` : ''}`);
+                }
+                await new Promise((resolve) => setTimeout(resolve, timing.pollMs));
+            }
+            log(`Installing the app on ${choice.label}`);
+            await adb(['-s', serial, 'install', '-r', binary]).catch((error) => {
+                throw error.message.includes('INSTALL_FAILED_UPDATE_INCOMPATIBLE')
+                    ? new NativeBuildError(`${capitalize(choice.label)} has a copy of ${app.id} signed with a different key, e.g. from before you set up signing. Uninstall it from the device, then build again.`)
+                    : error;
+            });
+            // By component, because neither `monkey -p` nor an `am start` by
+            // package opened the shell on an API 34 emulator. The launcher
+            // activity is looked up rather than assumed, for an ejected project
+            // whose activity was renamed.
+            const resolved = await capture(adbPath, [
+                '-s',
+                serial,
+                'shell',
+                'cmd',
+                'package',
+                'resolve-activity',
+                '--brief',
+                '-a',
+                'android.intent.action.MAIN',
+                '-c',
+                'android.intent.category.LAUNCHER',
+                app.id,
+            ]);
+            const component = resolved?.trim().split('\n').at(-1)?.trim();
+            // -S stops the copy a previous `--run` left open first, as iOS's
+            // --terminate-running-process does.
+            const output = await adb([
+                '-s',
+                serial,
+                'shell',
+                'am',
+                'start',
+                '-S',
+                '-W',
+                '-n',
+                component?.includes('/') ? component : `${app.id}/${SHELL_ACTIVITY}`,
+            ]);
+            // `am start` exits with 0 even when it fails, and says why on stdout,
+            // last: `Error type 3`, then `Error: Activity class ... does not exist.`
+            const failure = output
+                .split('\n')
+                .filter((line) => line.startsWith('Error'))
+                .at(-1);
+            if (failure) {
+                throw new NativeBuildError(`Couldn't open the app: ${failure.replace(/^Error:\s*/, '').trim()} The full log is ${logFile}.`);
+            }
+            log(`Opened ${app.name} on ${choice.label}`);
+        },
+    };
+};
+const capitalize = (text) => text[0].toUpperCase() + text.slice(1);
+const emulatorLogFile = (logFile) => path.join(path.dirname(logFile), 'emulator.log');
+/**
+ * Starts the emulator in the background, detached, so it keeps running after
+ * `ng build` exits and Ctrl+C in the terminal doesn't close it. Its output
+ * goes to a log file next to the build's, read if it stops while starting.
+ */
+const startEmulator = (emulatorPath, avd, logFile) => {
+    const output = openSync(emulatorLogFile(logFile), 'w');
+    const child = spawn(emulatorPath, ['-avd', avd], {
+        detached: true,
+        stdio: ['ignore', output, output],
+    });
+    closeSync(output);
+    let stopped;
+    child.on('error', (error) => (stopped = error.message));
+    child.on('exit', (code, signal) => (stopped = `exit code ${code ?? signal}`));
+    child.unref();
+    return { stopped: () => stopped };
+};

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { type Platform } from './generate.ts';
 import { type NativeAppOptions } from './options.ts';
+import type { RunOptions } from './run.ts';
 export type { Platform } from './generate.ts';
 export { EJECT_MARKER, copyBundle, prepareProject } from './generate.ts';
 export { renderEjectedProject } from './eject.ts';
@@ -7,6 +8,7 @@ export { LYNX_IOS, FRAMEWORKS_ENV } from './ios/frameworks.ts';
 export type { AndroidOptions, IosOptions, NativeAppOptions, Orientation, Permission, ResolvedApp, } from './options.ts';
 export { NativeConfigError, resolveAppOptions } from './options.ts';
 export { NativeBuildError } from './process.ts';
+export type { RunOptions } from './run.ts';
 export declare const PACKAGE_VERSION: string;
 export type BuildNativeAppOptions = {
     readonly platform: Platform;
@@ -24,14 +26,20 @@ export type BuildNativeAppOptions = {
     readonly packageVersion?: string;
     /** The rspeedy output folder holding main.lynx.bundle. */
     readonly bundleDir: string;
-    /** Where the binaries go, e.g. dist/ios. */
+    /** Where the binaries go, e.g. dist/ios. Emptied before they're written. */
     readonly outputDir: string;
     readonly app: NativeAppOptions;
+    /**
+     * Install the app on a simulator, emulator or phone and open it once it's
+     * built: `ng build --platform <platform> --run`.
+     */
+    readonly run?: RunOptions;
     readonly log: (message: string) => void;
 };
 /**
  * Turns a built Lynx bundle into native binaries: generates (or reuses) the
- * shell project, copies the bundle in, and runs xcodebuild or Gradle.
+ * shell project, copies the bundle in, and runs xcodebuild or Gradle. With
+ * `run`, then installs the app on a device and opens it.
  * Returns the paths of the binaries it wrote to `outputDir`.
  */
 export declare const buildNativeApp: (options: BuildNativeAppOptions) => Promise<{

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,EACL,KAAK,QAAQ,EAGd,MAAM,eAAe,CAAC;AAIvB,OAAO,EAAE,KAAK,gBAAgB,EAAqB,MAAM,cAAc,CAAC;AAExE,YAAY,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACzE,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC/D,YAAY,EACV,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,WAAW,EACX,UAAU,EACV,WAAW,GACZ,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD,eAAO,MAAM,eAAe,EAAE,MAErB,CAAC;AAEV,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,mEAAmE;IACnE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,8CAA8C;IAC9C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,mEAAmE;IACnE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,0DAA0D;IAC1D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,4CAA4C;IAC5C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,GAAG,EAAE,gBAAgB,CAAC;IAC/B,QAAQ,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACzC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,cAAc,GACzB,SAAS,qBAAqB,KAC7B,OAAO,CAAC;IACT,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B,CA4DA,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,KAAK,QAAQ,EAGd,MAAM,eAAe,CAAC;AAKvB,OAAO,EAAE,KAAK,gBAAgB,EAAqB,MAAM,cAAc,CAAC;AACxE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C,YAAY,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACzE,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC/D,YAAY,EACV,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,WAAW,EACX,UAAU,EACV,WAAW,GACZ,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,YAAY,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C,eAAO,MAAM,eAAe,EAAE,MAErB,CAAC;AAEV,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,mEAAmE;IACnE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,8CAA8C;IAC9C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,mEAAmE;IACnE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,0DAA0D;IAC1D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,GAAG,EAAE,gBAAgB,CAAC;IAC/B;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACzC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GACzB,SAAS,qBAAqB,KAC7B,OAAO,CAAC;IACT,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B,CA+EA,CAAC"}

package/dist/index.js

@@ -1,11 +1,13 @@
-import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { androidGenerator } from "./android/project.js";
 import { buildAndroid, resolveAndroidSigning } from "./android/build.js";
+import { startAndroidDevice } from "./android/run.js";
 import { prepareProject, removeLegacyWorkDir, } from "./generate.js";
 import { buildIos, resolveIosSigning } from "./ios/build.js";
 import { resolveLynxFrameworks } from "./ios/frameworks.js";
 import { iosGenerator } from "./ios/project.js";
+import { startIosSimulator } from "./ios/run.js";
 import { resolveAppOptions } from "./options.js";
 export { EJECT_MARKER, copyBundle, prepareProject } from "./generate.js";
 export { renderEjectedProject } from "./eject.js";
@@ -15,7 +17,8 @@ export { NativeBuildError } from "./process.js";
 export const PACKAGE_VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
 /**
  * Turns a built Lynx bundle into native binaries: generates (or reuses) the
- * shell project, copies the bundle in, and runs xcodebuild or Gradle.
+ * shell project, copies the bundle in, and runs xcodebuild or Gradle. With
+ * `run`, then installs the app on a device and opens it.
  * Returns the paths of the binaries it wrote to `outputDir`.
  */
 export const buildNativeApp = async (options) => {
@@ -35,6 +38,11 @@ export const buildNativeApp = async (options) => {
     const logFile = path.join(workDir, 'logs', `${platform}.log`);
     mkdirSync(path.dirname(logFile), { recursive: true });
     writeFileSync(logFile, '');
+    const target = !options.run
+        ? undefined
+        : platform === 'ios'
+            ? await startIosSimulator({ device: options.run.device, logFile, log })
+            : await startAndroidDevice({ device: options.run.device, logFile, log });
     const project = prepareProject({
         platform,
         generator: platform === 'ios' ? iosGenerator : androidGenerator,
@@ -49,6 +57,11 @@ export const buildNativeApp = async (options) => {
         : project.regenerated
             ? `Generated the ${platform} project`
             : `Reusing the generated ${platform} project (no config changes)`);
+    // rspeedy's clean leaves dist/ios and dist/android alone, so building one
+    // platform doesn't delete the other's app. Emptying this platform's folder
+    // here keeps what an earlier build wrote from outliving it: an .ipa from a
+    // signed build, or the app under its old name after a rename.
+    rmSync(options.outputDir, { recursive: true, force: true });
     const artifacts = platform === 'ios'
         ? await buildIos({
             project,
@@ -68,5 +81,8 @@ export const buildNativeApp = async (options) => {
             log,
             signing: androidSigning,
         });
+    await target?.launch(
+    // The simulator .app or the .apk, not the .ipa or .aab for the stores.
+    artifacts.find((artifact) => artifact.endsWith(platform === 'ios' ? '.app' : '.apk')), app);
     return { artifacts, projectDir: project.dir };
 };

package/dist/ios/run.d.ts

@@ -0,0 +1,61 @@
+import type { RunTarget } from '../run.ts';
+/** What `xcrun simctl list --json devices runtimes` prints, as far as it's read here. */
+export type SimctlList = {
+    readonly devices: Readonly<Record<string, readonly SimctlDevice[]>>;
+    readonly runtimes: readonly SimctlRuntime[];
+};
+type SimctlDevice = {
+    readonly name: string;
+    readonly udid: string;
+    /** `Shutdown`, `Booting`, `Booted` or `Shutting Down`. */
+    readonly state: string;
+    readonly isAvailable: boolean;
+    readonly deviceTypeIdentifier: string;
+    readonly lastUsedAt?: string;
+};
+type SimctlRuntime = {
+    readonly identifier: string;
+    /** e.g. `iOS 27.0`. */
+    readonly name: string;
+    readonly version: string;
+    readonly platform?: string;
+    readonly isAvailable: boolean;
+    /** Newest first. */
+    readonly supportedDeviceTypes?: readonly {
+        readonly identifier: string;
+        readonly name: string;
+        readonly productFamily?: string;
+    }[];
+};
+/** The simulator to run on: an existing one, or one to create. */
+export type Simulator = {
+    /** Undefined when the simulator has to be created first. */
+    readonly udid?: string;
+    readonly name: string;
+    readonly deviceTypeIdentifier: string;
+    readonly runtime: SimctlRuntime;
+    readonly booted: boolean;
+    readonly lastUsedAt?: string;
+};
+/**
+ * Chooses the simulator `ng build --platform ios --run` opens the app on.
+ *
+ * With `--device`, the simulator of that name or UDID. Otherwise one that's
+ * already started, so the app opens where the developer is looking, and the
+ * most recently used one if several are. Otherwise the newest iPhone on the
+ * newest iOS runtime, preferring a simulator that exists (Xcode creates one
+ * of each iPhone) over creating one.
+ */
+export declare const pickSimulator: (list: SimctlList, device: string | undefined) => Simulator;
+/**
+ * Picks the simulator for `--run` and starts booting it, so it boots while
+ * xcodebuild compiles. The returned target installs and opens the app once
+ * it's built.
+ */
+export declare const startIosSimulator: ({ device, logFile, log, }: {
+    readonly device: string | undefined;
+    readonly logFile: string;
+    readonly log: (message: string) => void;
+}) => Promise<RunTarget>;
+export {};
+//# sourceMappingURL=run.d.ts.map

package/dist/ios/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/ios/run.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAE3C,yFAAyF;AACzF,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,CAAC,CAAC,CAAC;IACpE,QAAQ,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAC;CAC7C,CAAC;AAEF,KAAK,YAAY,GAAG;IAClB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B,CAAC;AAEF,KAAK,aAAa,GAAG;IACnB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,uBAAuB;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,oBAAoB;IACpB,QAAQ,CAAC,oBAAoB,CAAC,EAAE,SAAS;QACvC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;KACjC,EAAE,CAAC;CACL,CAAC;AAEF,kEAAkE;AAClE,MAAM,MAAM,SAAS,GAAG;IACtB,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,GACxB,MAAM,UAAU,EAChB,QAAQ,MAAM,GAAG,SAAS,KACzB,SAkFF,CAAC;AAsBF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAAU,2BAIrC;IACD,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACzC,KAAG,OAAO,CAAC,SAAS,CA0DpB,CAAC"}