@blotch/angular-lynx-native 0.0.0-stage → 22.2.3

package/README.md

@@ -1,3 +1,45 @@
-# Temporary Holding Version
+# @blotch/angular-lynx-native
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Builds AngularLynx apps into iOS and Android binaries. You don't call it directly: `ng build --platform ios|android|all` (the `@blotch/angular-lynx-build:application` builder) loads it after building the Lynx bundle. It's a dependency of [`@blotch/angular-lynx-build`](../build), which `ng add @blotch/angular-lynx` installs.
+
+User documentation: [Publishing your App](../website/docs/guide/building-for-production.mdx). The design and its reasoning: [`investigations/native-app-builds.md`](../../investigations/native-app-builds.md).
+
+## What it does
+
+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>/`.
+
+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.
+
+## The shells
+
+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`, and the safe-area insets `safeAreaTop`, `safeAreaBottom`, `safeAreaLeft` and `safeAreaRight`. Lynx Explorer sends `theme` and `isNotchScreen` too, but no `appLocale`. 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.
+
+|                  | iOS                                                  | Android                                                  |
+| ---------------- | ---------------------------------------------------- | -------------------------------------------------------- |
+| Language         | Swift, scene lifecycle                               | Kotlin                                                   |
+| Lynx             | 4.1.0, prebuilt XCFrameworks (below)                 | 4.1.0 AARs from Maven Central                            |
+| XElement         | Linked and registered (`App/XElementRegistry.swift`) | Linked and registered (`XElementBehaviors`)              |
+| Toolchain        | Xcode 27, iOS 15+                                    | AGP 9.4, Gradle 9.6, JDK 17+, SDK 36, minSdk 24          |
+| Generated config | `Config/App.xcconfig`, `App/Info.plist` markers      | `angular-lynx.properties`, `AndroidManifest.xml` markers |
+
+## Lynx for iOS
+
+Lynx publishes iOS only as source pods, which take minutes to compile and need CocoaPods (and so Ruby). `scripts/build-lynx-ios-frameworks.sh` compiles them once into XCFrameworks (about 26 MB zipped, with debug symbols in a separate zip): Lynx, PrimJS, XElement and their dependencies. The builder downloads the zip pinned in `src/ios/frameworks.ts` (URL and SHA-256) on first use and caches it in `~/.cache/angular-lynx/lynx-ios/<version>-<build>`.
+
+The zip for Lynx 4.1.0 is the [`lynx-ios-4.1.0-2` release](https://github.com/Blotch-Smart-Frames/AngularLynx/releases/tag/lynx-ios-4.1.0-2). The build number counts rebuilds of one Lynx version whose frameworks changed (2 added XElement), and is part of the cache folder, so machines with an older zip download the new one. For a new Lynx version, bump the versions in the script and reset `BUILD` to 1; to change the frameworks of the same version, bump `BUILD` (in the script and in `LYNX_IOS`). Then run the **Lynx iOS frameworks** workflow with `publish` (or the script locally), and pin the new zip's URL and SHA-256. To test a locally built folder before publishing it:
+
+```sh
+npm run build:lynx-ios-frameworks -w packages/native   # needs Xcode, and Ruby >= 2.7 with Bundler for CocoaPods
+export ANGULAR_LYNX_IOS_FRAMEWORKS=$PWD/packages/native/.lynx-ios-build/out/LynxFrameworks
+```
+
+## Changing a template
+
+- **iOS:** `App/` is a synchronized folder, so adding or removing a Swift file needs no project change. For anything else (a build setting, a framework, a resource folder), edit `APP_PROJECT` in `scripts/generate-ios-project.ts`. `App.xcodeproj` isn't in git: the `iosTemplateProject` Vite plugin in `vite.config.ts` renders it with [`@bacons/xcode`](https://github.com/EvanBacon/xcode), which needs only Node, on every `npm run build` and `npm test`, and the npm package ships the result. Run `npm run generate:ios-project -w packages/native` to render it without the TypeScript build, e.g. to open the template in Xcode.
+- **Both:** run `npm run e2e -- --ios --shell` (and Layer 6 for Android, see the [E2E README](../e2e/README.md)) to build and tap through a fresh app on each platform.

package/dist/android/build.d.ts

@@ -0,0 +1,28 @@
+import type { PreparedProject } from '../generate.ts';
+import type { ResolvedApp } from '../options.ts';
+export type AndroidSigning = {
+    readonly storeFile: string;
+    readonly storePassword: string;
+    readonly keyAlias: string;
+    readonly keyPassword: string;
+};
+/**
+ * Reads the upload key from the environment variables the options name.
+ * Returns undefined when signing isn't configured, in which case the release
+ * build is signed with the debug key: installable for testing, but not
+ * accepted by Google Play.
+ */
+export declare const resolveAndroidSigning: (app: ResolvedApp, env?: NodeJS.ProcessEnv) => AndroidSigning | undefined;
+/**
+ * Builds the Android shell into a release `.apk` (for emulators and
+ * sideloading) and `.aab` (for Google Play). Returns the artifacts' paths.
+ */
+export declare const buildAndroid: ({ project, app, outputDir, logFile, log, signing, }: {
+    readonly project: PreparedProject;
+    readonly app: ResolvedApp;
+    readonly outputDir: string;
+    readonly logFile: string;
+    readonly log: (message: string) => void;
+    readonly signing: AndroidSigning | undefined;
+}) => Promise<string[]>;
+//# sourceMappingURL=build.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/android/build.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAIjD,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,GAChC,KAAK,WAAW,EAChB,MAAK,MAAM,CAAC,UAAwB,KACnC,cAAc,GAAG,SAgCnB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,YAAY,GAAU,qDAOhC;IACD,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,QAAQ,CAAC,OAAO,EAAE,cAAc,GAAG,SAAS,CAAC;CAC9C,KAAG,OAAO,CAAC,MAAM,EAAE,CAuDnB,CAAC"}

package/dist/android/build.js

@@ -0,0 +1,100 @@
+import { chmodSync, cpSync, existsSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+import { capture, run } from "../process.js";
+import { findAndroidSdk } from "./project.js";
+/**
+ * Reads the upload key from the environment variables the options name.
+ * Returns undefined when signing isn't configured, in which case the release
+ * build is signed with the debug key: installable for testing, but not
+ * accepted by Google Play.
+ */
+export const resolveAndroidSigning = (app, env = process.env) => {
+    const signing = app.android.signing;
+    if (!signing) {
+        return undefined;
+    }
+    const read = (option, name) => {
+        if (!name) {
+            throw new Error(`android.signing.${option} must name the environment variable that holds it.`);
+        }
+        const value = env[name];
+        if (!value) {
+            throw new Error(`android.signing.${option} names ${name}, which isn't set in the environment.`);
+        }
+        return value;
+    };
+    if (!signing.keyAlias) {
+        throw new Error('android.signing.keyAlias must be set.');
+    }
+    const storeFile = path.resolve(read('storeFileEnv', signing.storeFileEnv));
+    if (!existsSync(storeFile)) {
+        throw new Error(`The upload keystore ${storeFile} doesn't exist.`);
+    }
+    return {
+        storeFile,
+        storePassword: read('storePasswordEnv', signing.storePasswordEnv),
+        keyAlias: signing.keyAlias,
+        keyPassword: read('keyPasswordEnv', signing.keyPasswordEnv),
+    };
+};
+/**
+ * Builds the Android shell into a release `.apk` (for emulators and
+ * sideloading) and `.aab` (for Google Play). Returns the artifacts' paths.
+ */
+export const buildAndroid = async ({ project, app, outputDir, logFile, log, signing, }) => {
+    // Signing values reach Gradle as project properties through
+    // ORG_GRADLE_PROJECT_* environment variables: never on the command line,
+    // which the process list and our build log would show, and never in a file
+    // in the project.
+    // Gradle finds the SDK through ANDROID_HOME (or local.properties, which an
+    // ejected project may have). Passing it here keeps machine paths out of
+    // the project, so an ejected one can be committed and built anywhere.
+    const sdk = findAndroidSdk();
+    if (!sdk && !existsSync(path.join(project.dir, 'local.properties'))) {
+        throw new Error('The Android SDK was not found. Install Android Studio (which installs the SDK), or set ANDROID_HOME to an existing SDK.');
+    }
+    const env = {
+        ...process.env,
+        ...(sdk && { ANDROID_HOME: sdk }),
+        ...(await javaEnv()),
+        // Plain identifiers, no dots: gradlew is a /bin/sh script, and dash
+        // (/bin/sh on Debian and Ubuntu) silently drops environment variables
+        // whose names aren't valid shell identifiers, which would leave Linux
+        // builds signed with the debug key.
+        ...(signing && {
+            ORG_GRADLE_PROJECT_angularLynxStoreFile: signing.storeFile,
+            ORG_GRADLE_PROJECT_angularLynxStorePassword: signing.storePassword,
+            ORG_GRADLE_PROJECT_angularLynxKeyAlias: signing.keyAlias,
+            ORG_GRADLE_PROJECT_angularLynxKeyPassword: signing.keyPassword,
+        }),
+    };
+    if (!signing) {
+        log('Signing the release build with the debug key: set android.signing in angular.json for a Google Play upload.');
+    }
+    log('Building the Android app');
+    const gradlew = process.platform === 'win32' ? 'gradlew.bat' : './gradlew';
+    if (process.platform !== 'win32') {
+        // Angular schematics can't set file modes, so an ejected project's
+        // gradlew arrives without its executable bit.
+        chmodSync(path.join(project.dir, 'gradlew'), 0o755);
+    }
+    await run(gradlew, [':app:assembleRelease', ':app:bundleRelease', '--console=plain'], { cwd: project.dir, logFile, env });
+    mkdirSync(outputDir, { recursive: true });
+    const outputs = path.join(project.dir, 'app/build/outputs');
+    const apk = path.join(outputDir, `${app.artifactName}.apk`);
+    const aab = path.join(outputDir, `${app.artifactName}.aab`);
+    cpSync(path.join(outputs, 'apk/release/app-release.apk'), apk);
+    cpSync(path.join(outputs, 'bundle/release/app-release.aab'), aab);
+    return [apk, aab];
+};
+/**
+ * Android Gradle Plugin 8 needs JDK 17 or newer. When JAVA_HOME isn't set on
+ * macOS, ask java_home for one rather than whatever `java` is on the PATH.
+ */
+const javaEnv = async () => {
+    if (process.env['JAVA_HOME'] || process.platform !== 'darwin') {
+        return {};
+    }
+    const home = (await capture('/usr/libexec/java_home', ['-v', '17+']))?.trim();
+    return home ? { JAVA_HOME: home } : {};
+};

package/dist/android/project.d.ts

@@ -0,0 +1,20 @@
+import type { PlatformGenerator } from '../generate.ts';
+import type { ResolvedApp } from '../options.ts';
+/**
+ * Writes the app options into the Android template: identity goes in
+ * angular-lynx.properties (which app/build.gradle.kts reads), and permissions
+ * and deep links go between the manifest's `angular-lynx:*` markers.
+ */
+export declare const androidGenerator: PlatformGenerator;
+/**
+ * Escapes a value for a Java properties file. `Properties.load` reads the
+ * file as ISO-8859-1, so anything outside ASCII (an app named "Café" or
+ * "日記") must be written as `\uXXXX` or Gradle reads mojibake.
+ */
+export declare const propertyValue: (value: string) => string;
+export declare const properties: (app: ResolvedApp) => string;
+export declare const permissionEntries: (app: ResolvedApp) => string;
+export declare const deepLinkEntries: (app: ResolvedApp) => string;
+/** The Android SDK, from the environment or the Android Studio default. */
+export declare const findAndroidSdk: (env?: NodeJS.ProcessEnv) => string | undefined;
+//# sourceMappingURL=project.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../../src/android/project.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,KAAK,EAAe,WAAW,EAAE,MAAM,eAAe,CAAC;AAY9D;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,iBAc9B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,aAAa,GAAI,OAAO,MAAM,WAOtC,CAAC;AAEN,eAAO,MAAM,UAAU,GAAI,KAAK,WAAW,KAAG,MAWhC,CAAC;AAEf,eAAO,MAAM,iBAAiB,GAAI,KAAK,WAAW,KAAG,MAiBpD,CAAC;AAEF,eAAO,MAAM,eAAe,GAAI,KAAK,WAAW,KAAG,MAYjC,CAAC;AAEnB,2EAA2E;AAC3E,eAAO,MAAM,cAAc,GACzB,MAAK,MAAM,CAAC,UAAwB,KACnC,MAAM,GAAG,SAaX,CAAC"}

package/dist/android/project.js

@@ -0,0 +1,84 @@
+import { chmodSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { PERMISSION_MAP } from "../permissions.js";
+import { escapeXml, replaceMarker } from "../xml.js";
+const MANIFEST = 'app/src/main/AndroidManifest.xml';
+const SCREEN_ORIENTATIONS = {
+    portrait: 'portrait',
+    landscape: 'sensorLandscape',
+    all: 'unspecified',
+};
+/**
+ * Writes the app options into the Android template: identity goes in
+ * angular-lynx.properties (which app/build.gradle.kts reads), and permissions
+ * and deep links go between the manifest's `angular-lynx:*` markers.
+ */
+export const androidGenerator = {
+    configure: (dir, app) => {
+        // npm keeps file modes when it packs, but a copy through another tool
+        // (or a Windows checkout) may not, and Gradle can't start without it.
+        chmodSync(path.join(dir, 'gradlew'), 0o755);
+        writeFileSync(path.join(dir, 'angular-lynx.properties'), properties(app));
+        const manifestPath = path.join(dir, MANIFEST);
+        let manifest = readFileSync(manifestPath, 'utf8');
+        manifest = replaceMarker(manifest, 'permissions', permissionEntries(app));
+        manifest = replaceMarker(manifest, 'deep-links', deepLinkEntries(app));
+        writeFileSync(manifestPath, manifest);
+    },
+    bundleDir: (dir) => path.join(dir, 'app/src/main/assets'),
+};
+/**
+ * Escapes a value for a Java properties file. `Properties.load` reads the
+ * file as ISO-8859-1, so anything outside ASCII (an app named "Café" or
+ * "日記") must be written as `\uXXXX` or Gradle reads mojibake.
+ */
+export const propertyValue = (value) => value
+    .replace(/\\/g, '\\\\')
+    .replace(/\n/g, '\\n')
+    .replace(/[^\x20-\x7e]/g, (char) => `\\u${char.charCodeAt(0).toString(16).padStart(4, '0')}`);
+export const properties = (app) => [
+    '# Written by @blotch/angular-lynx-native from the builder options in',
+    '# angular.json on every build. Edits here are overwritten; change',
+    '# angular.json instead (or eject).',
+    `applicationId=${app.id}`,
+    `versionName=${app.version}`,
+    `versionCode=${app.buildNumber}`,
+    `appName=${propertyValue(app.name)}`,
+    `screenOrientation=${SCREEN_ORIENTATIONS[app.orientation]}`,
+    '',
+].join('\n');
+export const permissionEntries = (app) => {
+    const entries = Object.keys(app.permissions).map((permission) => PERMISSION_MAP[permission]);
+    const permissions = [...new Set(entries.flatMap((entry) => entry.android))];
+    const features = [
+        ...new Set(entries.flatMap((entry) => entry.androidFeatures ?? [])),
+    ];
+    return [
+        ...permissions.map((name) => `<uses-permission android:name="${escapeXml(name)}" />`),
+        ...features.map((name) => `<uses-feature android:name="${escapeXml(name)}" android:required="false" />`),
+    ].join('\n');
+};
+export const deepLinkEntries = (app) => app.deepLinkSchemes.length === 0
+    ? ''
+    : [
+        '<intent-filter>',
+        '    <action android:name="android.intent.action.VIEW" />',
+        '    <category android:name="android.intent.category.DEFAULT" />',
+        '    <category android:name="android.intent.category.BROWSABLE" />',
+        ...app.deepLinkSchemes.map((scheme) => `    <data android:scheme="${escapeXml(scheme)}" />`),
+        '</intent-filter>',
+    ].join('\n');
+/** The Android SDK, from the environment or the Android Studio default. */
+export const findAndroidSdk = (env = process.env) => {
+    const candidates = [
+        env['ANDROID_HOME'],
+        env['ANDROID_SDK_ROOT'],
+        process.platform === 'darwin'
+            ? path.join(os.homedir(), 'Library/Android/sdk')
+            : process.platform === 'win32'
+                ? path.join(env['LOCALAPPDATA'] ?? '', 'Android/Sdk')
+                : path.join(os.homedir(), 'Android/Sdk'),
+    ];
+    return candidates.find((candidate) => !!candidate && existsSync(candidate));
+};

package/dist/eject.d.ts

@@ -0,0 +1,18 @@
+import { type Platform } from './generate.ts';
+import { type NativeAppOptions } from './options.ts';
+/**
+ * Renders the native project a user takes ownership of with
+ * `ng generate @blotch/angular-lynx:eject`: the same project the builder
+ * generates, plus the marker that tells the builder to build it as it is.
+ * Returns its files (relative path → contents), for the schematic to write.
+ */
+export declare const renderEjectedProject: ({ platform, projectRoot, projectName, packageVersion, app, generatorVersion, }: {
+    readonly platform: Platform;
+    readonly projectRoot: string;
+    readonly projectName: string;
+    readonly packageVersion?: string;
+    readonly app: NativeAppOptions;
+    /** This package's version, recorded in the marker for later upgrades. */
+    readonly generatorVersion: string;
+}) => Map<string, Buffer>;
+//# sourceMappingURL=eject.d.ts.map

package/dist/eject.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eject.d.ts","sourceRoot":"","sources":["../src/eject.ts"],"names":[],"mappings":"AAYA,OAAO,EAAgB,KAAK,QAAQ,EAAiB,MAAM,eAAe,CAAC;AAE3E,OAAO,EAAE,KAAK,gBAAgB,EAAqB,MAAM,cAAc,CAAC;AA+BxE;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,GAAI,gFAOlC;IACD,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,GAAG,EAAE,gBAAgB,CAAC;IAC/B,yEAAyE;IACzE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CACnC,KAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CA8BrB,CAAC"}

package/dist/eject.js

@@ -0,0 +1,68 @@
+import { cpSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync, } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { androidGenerator } from "./android/project.js";
+import { EJECT_MARKER, TEMPLATES_DIR } from "./generate.js";
+import { iosGenerator } from "./ios/project.js";
+import { resolveAppOptions } from "./options.js";
+/**
+ * What an ejected project ignores. Written here because npm never packs
+ * `.gitignore` files, so the templates can't carry their own.
+ */
+const GITIGNORE = {
+    ios: [
+        '# Copied from dist/ on every `ng build --platform ios`.',
+        'LynxBundle/*',
+        '!LynxBundle/.gitkeep',
+        '# A link to the cached Lynx XCFrameworks, made on every build.',
+        'Frameworks',
+        'xcuserdata/',
+        '*.xcuserstate',
+        '',
+    ].join('\n'),
+    android: [
+        '# Copied from dist/ on every `ng build --platform android`.',
+        'app/src/main/assets/*',
+        '!app/src/main/assets/.gitkeep',
+        '.gradle/',
+        'build/',
+        'app/build/',
+        'local.properties',
+        '.idea/',
+        '*.iml',
+        '',
+    ].join('\n'),
+};
+/**
+ * Renders the native project a user takes ownership of with
+ * `ng generate @blotch/angular-lynx:eject`: the same project the builder
+ * generates, plus the marker that tells the builder to build it as it is.
+ * Returns its files (relative path → contents), for the schematic to write.
+ */
+export const renderEjectedProject = ({ platform, projectRoot, projectName, packageVersion, app, generatorVersion, }) => {
+    const resolved = resolveAppOptions(app, { projectName, packageVersion });
+    const dir = mkdtempSync(path.join(os.tmpdir(), `angular-lynx-eject-`));
+    try {
+        cpSync(path.join(TEMPLATES_DIR, platform), dir, { recursive: true });
+        (platform === 'ios' ? iosGenerator : androidGenerator).configure(dir, resolved, projectRoot);
+        writeFileSync(path.join(dir, '.gitignore'), GITIGNORE[platform]);
+        writeFileSync(path.join(dir, EJECT_MARKER), [
+            `Ejected from @blotch/angular-lynx-native ${generatorVersion}.`,
+            '',
+            `\`ng build --platform ${platform}\` builds this folder as it is and never`,
+            'regenerates it, so changes here are yours to keep. App options in',
+            'angular.json no longer apply to it, and Lynx, Xcode and Google Play',
+            'upgrades are now made here by hand. Delete this folder (and this file',
+            'with it) to go back to the generated project.',
+            '',
+        ].join('\n'));
+        return new Map(listFiles(dir).map((file) => [file, readFileSync(path.join(dir, file))]));
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+};
+const listFiles = (dir, prefix = '') => readdirSync(path.join(dir, prefix), { withFileTypes: true }).flatMap((entry) => {
+    const relative = path.posix.join(prefix, entry.name);
+    return entry.isDirectory() ? listFiles(dir, relative) : [relative];
+});

package/dist/generate.d.ts

@@ -0,0 +1,60 @@
+import type { ResolvedApp } from './options.ts';
+export type Platform = 'ios' | 'android';
+/** The shell templates shipped in this package. */
+export declare const TEMPLATES_DIR: string;
+/**
+ * Written into `ios/` or `android/` by eject. Its presence tells the builder
+ * the folder belongs to the user now: build it as it is, never regenerate it.
+ * A marker rather than the folder's mere existence, so an unrelated `ios/`
+ * folder isn't mistaken for an ejected project.
+ */
+export declare const EJECT_MARKER = ".angular-lynx-ejected";
+export type PlatformGenerator = {
+    /** Writes the config into a fresh copy of the template. */
+    readonly configure: (dir: string, app: ResolvedApp, projectRoot: string) => void;
+    /** Where the Lynx bundle and its assets go inside the native project. */
+    readonly bundleDir: (dir: string) => string;
+};
+export type PreparedProject = {
+    /** The native project to build. */
+    readonly dir: string;
+    /** True when the project is the user's ejected `ios/` or `android/`. */
+    readonly ejected: boolean;
+    /** False when the cached project matched the inputs and was reused. */
+    readonly regenerated: boolean;
+};
+/**
+ * Makes the native project for a platform ready to build: the generated one in
+ * `<workDir>/<platform>`, or the user's ejected folder.
+ *
+ * Generation is skipped when a hash of every input (this package's version,
+ * the template files, the app options and the icon) matches the last run, so
+ * Xcode and Gradle keep their incremental state between builds. The bundle is
+ * copied in on every build, because it changes on every build.
+ */
+export declare const prepareProject: ({ platform, generator, projectRoot, workDir, app, bundleDir, packageVersion, }: {
+    readonly platform: Platform;
+    readonly generator: PlatformGenerator;
+    readonly projectRoot: string;
+    /** Where generated projects go (see `BuildNativeAppOptions.workDir`). */
+    readonly workDir: string;
+    readonly app: ResolvedApp;
+    /** The rspeedy output folder (dist/). */
+    readonly bundleDir: string;
+    readonly packageVersion: string;
+}) => PreparedProject;
+/**
+ * Up to 22.2.2, native builds worked in `.angular-lynx/` at the project root.
+ * They now use Angular's cache, so delete the old folder rather than leave
+ * hundreds of megabytes of stale Xcode and Gradle state in the user's project. Only a
+ * folder with the `.gitignore` those versions wrote is ours to delete.
+ */
+export declare const removeLegacyWorkDir: (projectRoot: string, log: (message: string) => void) => void;
+/**
+ * Copies the native bundle and everything it references into the project,
+ * replacing the previous build's copy so deleted lazy bundles don't linger.
+ * Skips what rspeedy and this builder put in dist/ for other targets: the web
+ * bundle and the platform output folders.
+ */
+export declare const copyBundle: (from: string, to: string) => void;
+//# sourceMappingURL=generate.d.ts.map

package/dist/generate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../src/generate.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,SAAS,CAAC;AAEzC,mDAAmD;AACnD,eAAO,MAAM,aAAa,QAEzB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,YAAY,0BAA0B,CAAC;AAIpD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,2DAA2D;IAC3D,QAAQ,CAAC,SAAS,EAAE,CAClB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,WAAW,EAChB,WAAW,EAAE,MAAM,KAChB,IAAI,CAAC;IACV,yEAAyE;IACzE,QAAQ,CAAC,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;CAC7C,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,mCAAmC;IACnC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,uEAAuE;IACvE,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;CAC/B,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,GAAI,gFAQ5B;IACD,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;IACtC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC;IAC1B,yCAAyC;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC,KAAG,eA2BH,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAC9B,aAAa,MAAM,EACnB,KAAK,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,KAC7B,IAUF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,UAAU,GAAI,MAAM,MAAM,EAAE,IAAI,MAAM,KAAG,IAqBrD,CAAC"}

package/dist/generate.js

@@ -0,0 +1,111 @@
+import { createHash } from 'node:crypto';
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync, } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** The shell templates shipped in this package. */
+export const TEMPLATES_DIR = fileURLToPath(new URL('../templates/', import.meta.url));
+/**
+ * Written into `ios/` or `android/` by eject. Its presence tells the builder
+ * the folder belongs to the user now: build it as it is, never regenerate it.
+ * A marker rather than the folder's mere existence, so an unrelated `ios/`
+ * folder isn't mistaken for an ejected project.
+ */
+export const EJECT_MARKER = '.angular-lynx-ejected';
+const HASH_FILE = '.angular-lynx-hash';
+/**
+ * Makes the native project for a platform ready to build: the generated one in
+ * `<workDir>/<platform>`, or the user's ejected folder.
+ *
+ * Generation is skipped when a hash of every input (this package's version,
+ * the template files, the app options and the icon) matches the last run, so
+ * Xcode and Gradle keep their incremental state between builds. The bundle is
+ * copied in on every build, because it changes on every build.
+ */
+export const prepareProject = ({ platform, generator, projectRoot, workDir, app, bundleDir, packageVersion, }) => {
+    const ejectedDir = path.join(projectRoot, platform);
+    if (existsSync(path.join(ejectedDir, EJECT_MARKER))) {
+        copyBundle(bundleDir, generator.bundleDir(ejectedDir));
+        return { dir: ejectedDir, ejected: true, regenerated: false };
+    }
+    const dir = path.join(workDir, platform);
+    const hash = inputHash({ platform, app, projectRoot, packageVersion });
+    const hashFile = path.join(dir, HASH_FILE);
+    const upToDate = existsSync(hashFile) && readFileSync(hashFile, 'utf8') === hash;
+    if (!upToDate) {
+        rmSync(dir, { recursive: true, force: true });
+        mkdirSync(dir, { recursive: true });
+        cpSync(path.join(TEMPLATES_DIR, platform), dir, { recursive: true });
+        generator.configure(dir, app, projectRoot);
+        writeFileSync(hashFile, hash);
+    }
+    // Generated projects are build output. `ng new` already ignores Angular's
+    // cache, but a moved cache (`cli.cache.path`) or an edited .gitignore may
+    // not be: keep them out of the user's git without asking them to edit it.
+    writeFileSync(path.join(workDir, '.gitignore'), '*\n');
+    copyBundle(bundleDir, generator.bundleDir(dir));
+    return { dir, ejected: false, regenerated: !upToDate };
+};
+/**
+ * Up to 22.2.2, native builds worked in `.angular-lynx/` at the project root.
+ * They now use Angular's cache, so delete the old folder rather than leave
+ * hundreds of megabytes of stale Xcode and Gradle state in the user's project. Only a
+ * folder with the `.gitignore` those versions wrote is ours to delete.
+ */
+export const removeLegacyWorkDir = (projectRoot, log) => {
+    const legacy = path.join(projectRoot, '.angular-lynx');
+    const gitignore = path.join(legacy, '.gitignore');
+    if (!existsSync(gitignore) || readFileSync(gitignore, 'utf8') !== '*\n') {
+        return;
+    }
+    rmSync(legacy, { recursive: true, force: true });
+    log('Removed .angular-lynx/: native projects are now generated in the Angular cache');
+};
+/**
+ * Copies the native bundle and everything it references into the project,
+ * replacing the previous build's copy so deleted lazy bundles don't linger.
+ * Skips what rspeedy and this builder put in dist/ for other targets: the web
+ * bundle and the platform output folders.
+ */
+export const copyBundle = (from, to) => {
+    if (!existsSync(path.join(from, 'main.lynx.bundle'))) {
+        throw new Error(`${from} has no main.lynx.bundle. The Lynx environment of lynx.config.ts must build to this folder.`);
+    }
+    rmSync(to, { recursive: true, force: true });
+    mkdirSync(to, { recursive: true });
+    for (const entry of readdirSync(from, { withFileTypes: true })) {
+        if (entry.name === 'ios' ||
+            entry.name === 'android' ||
+            entry.name.startsWith('.') ||
+            entry.name.endsWith('.web.bundle')) {
+            continue;
+        }
+        cpSync(path.join(from, entry.name), path.join(to, entry.name), {
+            recursive: true,
+        });
+    }
+};
+const inputHash = ({ platform, app, projectRoot, packageVersion, }) => {
+    const hash = createHash('sha256');
+    hash.update(`${packageVersion}\n${platform}\n${JSON.stringify(app)}\n`);
+    for (const file of listFiles(path.join(TEMPLATES_DIR, platform))) {
+        hash.update(file.relative);
+        hash.update(readFileSync(file.absolute));
+    }
+    if (app.icon) {
+        const icon = path.resolve(projectRoot, app.icon);
+        hash.update(existsSync(icon) ? readFileSync(icon) : 'missing icon');
+    }
+    return hash.digest('hex');
+};
+/**
+ * Every file under `dir`, sorted, so the hash doesn't depend on fs order.
+ */
+const listFiles = (dir, prefix = '') => readdirSync(dir, { withFileTypes: true })
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .flatMap((entry) => {
+    const relative = path.posix.join(prefix, entry.name);
+    const absolute = path.join(dir, entry.name);
+    return entry.isDirectory()
+        ? listFiles(absolute, relative)
+        : [{ relative, absolute }];
+});

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+import { type Platform } from './generate.ts';
+import { type NativeAppOptions } from './options.ts';
+export type { Platform } from './generate.ts';
+export { EJECT_MARKER, copyBundle, prepareProject } from './generate.ts';
+export { renderEjectedProject } from './eject.ts';
+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 declare const PACKAGE_VERSION: string;
+export type BuildNativeAppOptions = {
+    readonly platform: Platform;
+    /** The Angular project's root folder (where lynx.config.ts is). */
+    readonly projectRoot: string;
+    /**
+     * Where the generated native projects, their build state and the build
+     * logs go. The builder passes the project's folder in Angular's cache, so
+     * nothing is added to the project root and `ng cache clean` clears it.
+     */
+    readonly workDir: string;
+    /** The project name, the default app name. */
+    readonly projectName: string;
+    /** The project's package.json version, the default app version. */
+    readonly packageVersion?: string;
+    /** The rspeedy output folder holding main.lynx.bundle. */
+    readonly bundleDir: string;
+    /** Where the binaries go, e.g. dist/ios. */
+    readonly outputDir: string;
+    readonly app: NativeAppOptions;
+    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.
+ * Returns the paths of the binaries it wrote to `outputDir`.
+ */
+export declare const buildNativeApp: (options: BuildNativeAppOptions) => Promise<{
+    readonly artifacts: readonly string[];
+    readonly projectDir: string;
+}>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +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"}