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

package/dist/options.js

@@ -0,0 +1,112 @@
+export class NativeConfigError extends Error {
+}
+/**
+ * Letters and digits in dot-separated segments that each start with a letter:
+ * the intersection of what iOS (no underscores) and Android (no hyphens)
+ * accept, so one ID works on both.
+ */
+const APP_ID = /^[A-Za-z][A-Za-z0-9]*(\.[A-Za-z][A-Za-z0-9]*)+$/;
+/** Up to three period-separated integers, as App Store Connect requires. */
+const VERSION = /^\d+(\.\d+){0,2}$/;
+const SCHEME = /^[A-Za-z][A-Za-z0-9+.-]*$/;
+/** Google Play's maximum versionCode. */
+const MAX_BUILD_NUMBER = 2_100_000_000;
+const PERMISSIONS = [
+    'camera',
+    'microphone',
+    'location',
+    'photos',
+    'contacts',
+    'notifications',
+];
+/**
+ * Applies defaults and validates the options, so the generators never see a
+ * value that would produce a project Xcode or Gradle rejects later with a
+ * less helpful message.
+ */
+export const resolveAppOptions = (rawOptions, defaults) => {
+    const options = (compact(rawOptions) ?? {});
+    const name = (options.appName ?? defaults.projectName).trim();
+    if (!name) {
+        throw new NativeConfigError('appName must not be empty.');
+    }
+    const id = options.appId ?? `com.example.${toIdSegment(defaults.projectName)}`;
+    if (!APP_ID.test(id)) {
+        throw new NativeConfigError(`appId "${id}" is not valid. Use letters and digits in at least two dot-separated parts, each starting with a letter (e.g. com.example.myapp). iOS rejects underscores and Android rejects hyphens.`);
+    }
+    const packageVersion = defaults.packageVersion && VERSION.test(defaults.packageVersion)
+        ? defaults.packageVersion
+        : undefined;
+    // `ng new` sets 0.0.0, which App Store Connect rejects.
+    const version = options.version ??
+        (packageVersion && packageVersion !== '0.0.0' ? packageVersion : '1.0.0');
+    if (!VERSION.test(version)) {
+        throw new NativeConfigError(`version "${version}" is not valid. Use up to three period-separated numbers, e.g. 1.2.0.`);
+    }
+    const buildNumber = options.buildNumber ?? 1;
+    if (!Number.isInteger(buildNumber) ||
+        buildNumber < 1 ||
+        buildNumber > MAX_BUILD_NUMBER) {
+        throw new NativeConfigError(`buildNumber ${buildNumber} is not valid. Use a whole number from 1 to ${MAX_BUILD_NUMBER}.`);
+    }
+    const permissions = options.permissions ?? {};
+    for (const [permission, reason] of Object.entries(permissions)) {
+        if (!PERMISSIONS.includes(permission)) {
+            throw new NativeConfigError(`Unknown permission "${permission}". Supported: ${PERMISSIONS.join(', ')}.`);
+        }
+        if (typeof reason !== 'string' || !reason.trim()) {
+            throw new NativeConfigError(`permissions.${permission} needs the reason shown to the user, e.g. "Scan receipts".`);
+        }
+    }
+    const deepLinkSchemes = options.deepLinkSchemes ?? [];
+    for (const scheme of deepLinkSchemes) {
+        if (!SCHEME.test(scheme)) {
+            throw new NativeConfigError(`deepLinkSchemes entry "${scheme}" is not a valid URL scheme.`);
+        }
+    }
+    const productName = name.replace(/[^A-Za-z0-9]/g, '') || 'App';
+    const artifactName = name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '') || 'app';
+    return {
+        name,
+        id,
+        version,
+        buildNumber,
+        orientation: options.orientation ?? 'portrait',
+        permissions,
+        deepLinkSchemes,
+        icon: options.icon,
+        productName,
+        artifactName,
+        ios: options.ios ?? {},
+        android: options.android ?? {},
+    };
+};
+/**
+ * `my-app` → `myapp`: a project name as one app ID segment.
+ */
+const toIdSegment = (projectName) => {
+    const segment = projectName.toLowerCase().replace(/[^a-z0-9]/g, '');
+    return /^[a-z]/.test(segment) ? segment : `app${segment}`;
+};
+/**
+ * Drops `undefined` values and the objects left empty by that. Angular CLI
+ * fills in every property its schema declares for a nested option object,
+ * as `undefined` when the user didn't set it, so `ios: {}` arrives as
+ * `{ teamId: undefined, signing: { keyIdEnv: undefined, ... } }`, which
+ * would read as "signing configured, but incomplete".
+ */
+export const compact = (value) => {
+    if (Array.isArray(value)) {
+        return value.map(compact);
+    }
+    if (!value || typeof value !== 'object') {
+        return value;
+    }
+    const entries = Object.entries(value)
+        .map(([key, entry]) => [key, compact(entry)])
+        .filter(([, entry]) => entry !== undefined);
+    return entries.length === 0 ? undefined : Object.fromEntries(entries);
+};

package/dist/permissions.d.ts

@@ -0,0 +1,17 @@
+import type { Permission } from './options.ts';
+/**
+ * What each cross-platform permission becomes on each OS. iOS asks the user
+ * with the app's own reason string (an Info.plist usage description); Android
+ * declares manifest permissions and shows a system message instead.
+ */
+export declare const PERMISSION_MAP: Record<Permission, {
+    readonly ios: readonly string[];
+    readonly android: readonly string[];
+    /**
+     * Hardware the Android permission implies. Declared as not required, or
+     * Google Play hides the app from devices without it (a tablet without a
+     * camera, say), which a permission alone silently causes.
+     */
+    readonly androidFeatures?: readonly string[];
+}>;
+//# sourceMappingURL=permissions.d.ts.map

package/dist/permissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../src/permissions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C;;;;GAIG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,CACjC,UAAU,EACV;IACE,QAAQ,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC;;;;OAIG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9C,CAiCF,CAAC"}

package/dist/permissions.js

@@ -0,0 +1,38 @@
+/**
+ * What each cross-platform permission becomes on each OS. iOS asks the user
+ * with the app's own reason string (an Info.plist usage description); Android
+ * declares manifest permissions and shows a system message instead.
+ */
+export const PERMISSION_MAP = {
+    camera: {
+        ios: ['NSCameraUsageDescription'],
+        android: ['android.permission.CAMERA'],
+        androidFeatures: ['android.hardware.camera'],
+    },
+    microphone: {
+        ios: ['NSMicrophoneUsageDescription'],
+        android: ['android.permission.RECORD_AUDIO'],
+        androidFeatures: ['android.hardware.microphone'],
+    },
+    location: {
+        ios: ['NSLocationWhenInUseUsageDescription'],
+        android: [
+            'android.permission.ACCESS_COARSE_LOCATION',
+            'android.permission.ACCESS_FINE_LOCATION',
+        ],
+        androidFeatures: ['android.hardware.location'],
+    },
+    photos: {
+        ios: ['NSPhotoLibraryUsageDescription'],
+        android: ['android.permission.READ_MEDIA_IMAGES'],
+    },
+    contacts: {
+        ios: ['NSContactsUsageDescription'],
+        android: ['android.permission.READ_CONTACTS'],
+    },
+    // iOS asks for notification permission at runtime without a usage string.
+    notifications: {
+        ios: [],
+        android: ['android.permission.POST_NOTIFICATIONS'],
+    },
+};

package/dist/png.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Reads a PNG's dimensions from its header, without decoding it. Enough to
+ * reject an icon of the wrong size before Xcode's asset compiler does, with a
+ * clearer message.
+ */
+export declare const readPngSize: (file: string) => {
+    readonly width: number;
+    readonly height: number;
+};
+//# sourceMappingURL=png.d.ts.map

package/dist/png.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"png.d.ts","sourceRoot":"","sources":["../src/png.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,eAAO,MAAM,WAAW,GACtB,MAAM,MAAM,KACX;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAiBnD,CAAC"}

package/dist/png.js

@@ -0,0 +1,24 @@
+import { closeSync, openSync, readSync } from 'node:fs';
+const SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+/**
+ * Reads a PNG's dimensions from its header, without decoding it. Enough to
+ * reject an icon of the wrong size before Xcode's asset compiler does, with a
+ * clearer message.
+ */
+export const readPngSize = (file) => {
+    const header = Buffer.alloc(24);
+    const fd = openSync(file, 'r');
+    try {
+        readSync(fd, header, 0, header.length, 0);
+    }
+    finally {
+        closeSync(fd);
+    }
+    // The IHDR chunk always comes first: 8-byte signature, 4-byte length,
+    // "IHDR", then width and height.
+    if (!header.subarray(0, 8).equals(SIGNATURE) ||
+        header.toString('ascii', 12, 16) !== 'IHDR') {
+        throw new Error(`${file} is not a PNG file.`);
+    }
+    return { width: header.readUInt32BE(16), height: header.readUInt32BE(20) };
+};

package/dist/process.d.ts

@@ -0,0 +1,17 @@
+/** A native build step failed. The message ends with the log's last lines. */
+export declare class NativeBuildError extends Error {
+}
+/**
+ * Runs a native tool with its output going to `logFile` rather than the
+ * terminal. xcodebuild and Gradle print thousands of lines on success, which
+ * would bury the builder's own progress; on failure, the end of the log is
+ * almost always the error, so that's what the thrown error quotes.
+ */
+export declare const run: (command: string, args: readonly string[], options: {
+    readonly cwd: string;
+    readonly logFile: string;
+    readonly env?: NodeJS.ProcessEnv;
+}) => Promise<void>;
+/** Runs a command and returns its stdout, or undefined if it fails. */
+export declare const capture: (command: string, args: readonly string[]) => Promise<string | undefined>;
+//# sourceMappingURL=process.d.ts.map

package/dist/process.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process.d.ts","sourceRoot":"","sources":["../src/process.ts"],"names":[],"mappings":"AAIA,8EAA8E;AAC9E,qBAAa,gBAAiB,SAAQ,KAAK;CAAG;AAQ9C;;;;;GAKG;AACH,eAAO,MAAM,GAAG,GACd,SAAS,MAAM,EACf,MAAM,SAAS,MAAM,EAAE,EACvB,SAAS;IACP,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CAClC,KACA,OAAO,CAAC,IAAI,CAqDd,CAAC;AAEF,uEAAuE;AACvE,eAAO,MAAM,OAAO,GAClB,SAAS,MAAM,EACf,MAAM,SAAS,MAAM,EAAE,KACtB,OAAO,CAAC,MAAM,GAAG,SAAS,CAOzB,CAAC"}

package/dist/process.js

@@ -0,0 +1,67 @@
+import { spawn } from 'node:child_process';
+import { appendFileSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+/** A native build step failed. The message ends with the log's last lines. */
+export class NativeBuildError extends Error {
+}
+/** How many log lines a failure message quotes. */
+const TAIL_LINES = 40;
+const MAX_ERROR_LINES = 20;
+/** clang/swiftc/javac/kotlinc diagnostics and xcodebuild's own errors. */
+const ERROR_LINE = /(^|:\d+(:\d+)?:\s|^\s*e:\s)error:|^error:|^e: /;
+/**
+ * Runs a native tool with its output going to `logFile` rather than the
+ * terminal. xcodebuild and Gradle print thousands of lines on success, which
+ * would bury the builder's own progress; on failure, the end of the log is
+ * almost always the error, so that's what the thrown error quotes.
+ */
+export const run = (command, args, options) => {
+    mkdirSync(path.dirname(options.logFile), { recursive: true });
+    appendFileSync(options.logFile, `\n$ ${[command, ...args].join(' ')}\n  (in ${options.cwd})\n`);
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            cwd: options.cwd,
+            env: options.env ?? process.env,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        const recent = [];
+        const errors = new Set();
+        let partial = '';
+        const record = (chunk) => {
+            appendFileSync(options.logFile, chunk);
+            const lines = (partial + chunk.toString()).split('\n');
+            partial = lines.pop();
+            for (const line of lines) {
+                // Compiler diagnostics ("file.swift:12:8: error: ...") say what went
+                // wrong far better than the end of the log, which for xcodebuild is
+                // usually a multi-kilobyte command line.
+                if (ERROR_LINE.test(line) && errors.size < MAX_ERROR_LINES) {
+                    errors.add(line.trim());
+                }
+            }
+            recent.push(...lines);
+            recent.splice(0, Math.max(0, recent.length - TAIL_LINES));
+        };
+        child.stdout.on('data', record);
+        child.stderr.on('data', record);
+        child.on('error', (error) => reject(new NativeBuildError(`Could not run ${command}: ${error.message}`)));
+        child.on('close', (code) => {
+            if (code === 0) {
+                resolve();
+                return;
+            }
+            const detail = errors.size > 0
+                ? `The errors:\n\n${[...errors].join('\n')}`
+                : `Its last lines:\n\n${[...recent, partial].join('\n').trim()}`;
+            reject(new NativeBuildError(`${command} ${args[0] ?? ''} failed (exit code ${code}). The full log is ${options.logFile}. ${detail}`));
+        });
+    });
+};
+/** Runs a command and returns its stdout, or undefined if it fails. */
+export const capture = (command, args) => new Promise((resolve) => {
+    const child = spawn(command, args, { stdio: ['ignore', 'pipe', 'ignore'] });
+    let output = '';
+    child.stdout.on('data', (chunk) => (output += chunk.toString()));
+    child.on('error', () => resolve(undefined));
+    child.on('close', (code) => resolve(code === 0 ? output : undefined));
+});

package/dist/xml.d.ts

@@ -0,0 +1,10 @@
+/** Escapes text for an XML element or attribute (plists, manifests). */
+export declare const escapeXml: (text: string) => string;
+/**
+ * Replaces the text between `<!-- angular-lynx:<name> -->` and
+ * `<!-- /angular-lynx:<name> -->` (or, when the template has a single marker
+ * with no closing one, the marker itself). Templates mark the few places the
+ * generator writes to, so everything else in them stays plain native code.
+ */
+export declare const replaceMarker: (source: string, name: string, content: string) => string;
+//# sourceMappingURL=xml.d.ts.map

package/dist/xml.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xml.d.ts","sourceRoot":"","sources":["../src/xml.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,eAAO,MAAM,SAAS,GAAI,MAAM,MAAM,KAAG,MAMb,CAAC;AAE7B;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GACxB,QAAQ,MAAM,EACd,MAAM,MAAM,EACZ,SAAS,MAAM,KACd,MAkBF,CAAC"}

package/dist/xml.js

@@ -0,0 +1,32 @@
+/** Escapes text for an XML element or attribute (plists, manifests). */
+export const escapeXml = (text) => text
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+/**
+ * Replaces the text between `<!-- angular-lynx:<name> -->` and
+ * `<!-- /angular-lynx:<name> -->` (or, when the template has a single marker
+ * with no closing one, the marker itself). Templates mark the few places the
+ * generator writes to, so everything else in them stays plain native code.
+ */
+export const replaceMarker = (source, name, content) => {
+    const open = `<!-- angular-lynx:${name} -->`;
+    const close = `<!-- /angular-lynx:${name} -->`;
+    const start = source.indexOf(open);
+    if (start === -1) {
+        throw new Error(`The template has no ${open} marker.`);
+    }
+    const closeAt = source.indexOf(close, start);
+    const end = closeAt === -1 ? start + open.length : closeAt + close.length;
+    // Indent inserted lines (and the closing marker) like the opening marker.
+    const indent = /[ \t]*$/.exec(source.slice(0, start))[0];
+    const lines = content
+        .split('\n')
+        .filter((line) => line.trim())
+        .map((line) => `\n${indent}${line}`)
+        .join('');
+    const closing = closeAt === -1 ? '' : `\n${indent}${close}`;
+    return `${source.slice(0, start)}${open}${lines}${closing}${source.slice(end)}`;
+};

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@blotch/angular-lynx-native",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "22.2.2",
+  "description": "Builds AngularLynx apps into iOS and Android binaries",
+  "homepage": "https://github.com/Blotch-Smart-Frames/AngularLynx#readme",
+  "bugs": {
+    "url": "https://github.com/Blotch-Smart-Frames/AngularLynx/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Blotch-Smart-Frames/AngularLynx.git",
+    "directory": "packages/native"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && vite build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:ci:coverage": "vitest run --coverage",
+    "lint": "oxlint .",
+    "lint:fix": "oxlint --fix .",
+    "format": "oxfmt --write .",
+    "format:check": "oxfmt --check .",
+    "cspell": "cspell .",
+    "generate:ios-project": "vite build",
+    "build:lynx-ios-frameworks": "scripts/build-lynx-ios-frameworks.sh",
+    "publish:local": "yalc publish --push"
+  },
+  "devDependencies": {
+    "@bacons/xcode": "1.0.0-alpha.33",
+    "@types/node": "^22.0.0",
+    "typescript": "~6.0.0"
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "ng-update": {
+    "packageGroup": [
+      "@blotch/angular-lynx",
+      "@blotch/angular-lynx-build",
+      "@blotch/angular-lynx-testing-library",
+      "@blotch/rsbuild-plugin-angular-lynx",
+      "@blotch/angular-lynx-native"
+    ]
+  }
+}

package/templates/android/README.md

@@ -0,0 +1,42 @@
+# Android shell template
+
+The Android app that `ng build --platform android` builds. The generator copies this folder into `.angular/cache/<Angular version>/<project>/lynx-native/android`, fills in the few files below, and runs Gradle. Everything else is static: it's code we own and test, not something users edit (they can `eject` to get a copy they own).
+
+The app is one activity holding one full-screen `LynxView` that runs `main.lynx.bundle`. Angular Router does all navigation inside it.
+
+## What the generator changes
+
+| What            | Where                                                         | Notes                                                                                                                                                                                                                                                                                                                                               |
+| --------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| The bundle      | `app/src/main/assets/`                                        | The whole `dist/` folder (`main.lynx.bundle`, `static/…`), copied after emptying the folder. Bundled files are read from here.                                                                                                                                                                                                                      |
+| App identity    | `angular-lynx.properties`                                     | Keys: `applicationId`, `versionName`, `versionCode`, `appName`, `screenOrientation` (`portrait`, `sensorLandscape` or `unspecified`). Read by `app/build.gradle.kts`. The committed file holds defaults.                                                                                                                                            |
+| Permissions     | `AndroidManifest.xml`, at `<!-- angular-lynx:permissions -->` | `<uses-permission>` lines. `INTERNET` is always declared.                                                                                                                                                                                                                                                                                           |
+| Deep links      | `AndroidManifest.xml`, at `<!-- angular-lynx:deep-links -->`  | `<intent-filter>`s inside the main activity.                                                                                                                                                                                                                                                                                                        |
+| SDK location    | `local.properties`                                            | `sdk.dir=…`, unless `ANDROID_HOME` is set.                                                                                                                                                                                                                                                                                                          |
+| Release signing | Gradle properties, from the environment                       | `ORG_GRADLE_PROJECT_angularLynxStoreFile`, `…StorePassword`, `…KeyAlias`, `…KeyPassword` (no dots: dash, `/bin/sh` on Debian and Ubuntu, drops variables whose names aren't shell identifiers before `gradlew` starts Gradle). Never written to disk. Without all four, release builds are signed with the debug key (installable, not uploadable). |
+
+Build commands and outputs (no flavors, so the names are fixed):
+
+```sh
+./gradlew :app:assembleDebug                      # app/build/outputs/apk/debug/app-debug.apk
+./gradlew :app:assembleRelease :app:bundleRelease # app/build/outputs/apk/release/app-release.apk
+                                                  # app/build/outputs/bundle/release/app-release.aab
+```
+
+## How the shell loads the app
+
+- **Bundles** come from `assets/` (`ResourceFetchers.kt`, `BundleAssets.kt`). A URL without a scheme (`/static/…`, `static/…`), `asset:///…` and `file:///android_asset/…` all mean "the file at that path in `assets/`", so the bundle works with Rspeedy's default asset prefix (`/`) and doesn't need a platform-specific one. Absolute `http(s)` URLs are fetched with OkHttp.
+- **Images** are loaded by Fresco. The media fetcher rewrites bundled image URLs to `asset:///…`, which Fresco reads from the APK.
+- **Lazy routes** need nothing extra: the build plugin keeps each lazy chunk inside `main.lynx.bundle` (see `split-chunks.ts` in the build plugin). Bundles requested by URL at runtime still go through the template resource fetcher.
+
+## Back button
+
+Back is off by default, so it leaves the app like any root screen. The runtime turns it on while the Router has history by calling `NativeModules.AngularLynxShell.setBackHandlerEnabled(true)` (from the background thread, where `NativeModules` lives). While it's on, a back press sends the global event `angularLynxBack` instead, which the runtime turns into a Router back navigation. The app has to say beforehand because Android decides synchronously, at the start of the gesture, whether an app handles back (predictive back animates differently).
+
+## Versions
+
+Pinned in `app/build.gradle.kts`, `build.gradle.kts` and `gradle/wrapper/gradle-wrapper.properties`:
+
+- Lynx 4.1.0 and PrimJS 4.1.1 (Maven Central), Fresco 2.3.0 (the version Lynx's image service is built against), OkHttp 4.12.
+- AGP 9.4.1 with its built-in Kotlin, Gradle 9.6.1 (AGP 9.4's minimum), JDK 17 or newer.
+- `compileSdk` and `targetSdk` 36, `minSdk` 24. Google Play raises its target API requirement every August; bump `targetSdk` with it.

package/templates/android/angular-lynx.properties

@@ -0,0 +1,7 @@
+# Written by the AngularLynx generator from angular.json. These defaults only
+# exist so the template builds on its own.
+applicationId=dev.angularlynx.shell
+versionName=1.0.0
+versionCode=1
+appName=AngularLynx
+screenOrientation=portrait

package/templates/android/app/build.gradle.kts

@@ -0,0 +1,140 @@
+import java.util.Properties
+
+plugins {
+    id("com.android.application")
+}
+
+// App identity comes from angular.json, which the generator writes into
+// angular-lynx.properties. The committed file has defaults so the template
+// also builds on its own.
+val appConfig = Properties().apply {
+    rootProject.file("angular-lynx.properties").inputStream().use { load(it) }
+}
+
+fun appConfig(key: String): String =
+    appConfig.getProperty(key) ?: error("angular-lynx.properties has no $key")
+
+// Release signing arrives as Gradle properties (the builder sets
+// ORG_GRADLE_PROJECT_angularLynxStoreFile etc. in the environment, which
+// keeps secrets out of command lines and logs) and is never written to disk,
+// so the generated project never holds secrets. The names have no dots:
+// gradlew is a /bin/sh script, and dash (Debian and Ubuntu's /bin/sh) drops
+// environment variables whose names aren't shell identifiers before Gradle
+// starts. Without them, release builds fall back to the debug key: still
+// installable on an emulator, but Google Play rejects them.
+val releaseSigning = listOf("StoreFile", "StorePassword", "KeyAlias", "KeyPassword")
+    .associateWith { providers.gradleProperty("angularLynx$it").orNull }
+val hasReleaseSigning = releaseSigning.values.all { !it.isNullOrEmpty() }
+
+// One place for the Lynx version, so a Lynx upgrade is a one-line change.
+val lynxVersion = "4.1.0"
+val primjsVersion = "4.1.1"
+// Lynx's image service is written against Fresco 2.3, and Lynx Explorer ships
+// the same version, so stay on it until Lynx moves.
+val frescoVersion = "2.3.0"
+
+android {
+    // The namespace is the package of the shell's own Kotlin code and R class.
+    // It's fixed; only the applicationId (the store identity) is configurable.
+    namespace = "dev.angularlynx.shell"
+    compileSdk = 36
+
+    defaultConfig {
+        applicationId = appConfig("applicationId")
+        // Lynx 4.1's AARs declare minSdk 16, but Lynx Explorer and Lynx's
+        // integration guide use 24, the oldest version Lynx tests on.
+        minSdk = 24
+        // Google Play requires new apps and updates to target a recent API
+        // level, raised every August. Bump this with each requirement.
+        targetSdk = 36
+        versionCode = appConfig("versionCode").toInt()
+        versionName = appConfig("versionName")
+        resValue("string", "app_name", appConfig("appName"))
+        // portrait, sensorLandscape or unspecified (follows the device).
+        manifestPlaceholders["screenOrientation"] =
+            appConfig.getProperty("screenOrientation") ?: "portrait"
+    }
+
+    signingConfigs {
+        if (hasReleaseSigning) {
+            create("release") {
+                storeFile = file(releaseSigning.getValue("StoreFile")!!)
+                storePassword = releaseSigning.getValue("StorePassword")
+                keyAlias = releaseSigning.getValue("KeyAlias")
+                keyPassword = releaseSigning.getValue("KeyPassword")
+            }
+        }
+    }
+
+    buildTypes {
+        release {
+            // R8 shrinking is off until the Lynx keep rules in
+            // proguard-rules.pro are verified against every AngularLynx
+            // feature; Lynx reaches much of its Java code through JNI and
+            // reflection, which R8 can't see.
+            isMinifyEnabled = false
+            proguardFiles(
+                getDefaultProguardFile("proguard-android-optimize.txt"),
+                "proguard-rules.pro",
+            )
+            signingConfig = if (hasReleaseSigning) {
+                signingConfigs.getByName("release")
+            } else {
+                signingConfigs.getByName("debug")
+            }
+        }
+    }
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+
+    buildFeatures {
+        resValues = true
+    }
+
+    androidResources {
+        // The bundle and lazy bundles are read with AssetManager.open(), which
+        // works on compressed assets too, but leaving them uncompressed lets
+        // the OS map them straight from the APK.
+        noCompress += listOf("bundle")
+    }
+
+    packaging {
+        jniLibs {
+            // Store native libraries uncompressed and page-aligned in the APK,
+            // which Android loads without extracting them first.
+            useLegacyPackaging = false
+            // Lynx's and Fresco's libraries ship already stripped. Without
+            // this, AGP tries to strip them again, which needs the NDK (and
+            // only warns when it's missing), so users would need the NDK for
+            // nothing.
+            keepDebugSymbols += "**/*.so"
+        }
+    }
+}
+
+dependencies {
+    implementation("androidx.activity:activity-ktx:1.10.1")
+    implementation("androidx.core:core-ktx:1.16.0")
+
+    // The Lynx engine, its JavaScript runtime (PrimJS) and its JS SDK.
+    implementation("org.lynxsdk.lynx:lynx:$lynxVersion")
+    implementation("org.lynxsdk.lynx:lynx-jssdk:$lynxVersion")
+    implementation("org.lynxsdk.lynx:lynx-trace:$lynxVersion")
+    implementation("org.lynxsdk.lynx:primjs:$primjsVersion")
+
+    // Lynx services: <image> (backed by Fresco), console logging, and
+    // fetch()/XMLHttpRequest (backed by OkHttp). The service AARs only
+    // compile against Fresco and OkHttp, so the app has to provide them.
+    implementation("org.lynxsdk.lynx:lynx-service-image:$lynxVersion")
+    implementation("org.lynxsdk.lynx:lynx-service-log:$lynxVersion")
+    implementation("org.lynxsdk.lynx:lynx-service-http:$lynxVersion")
+    implementation("com.facebook.fresco:fresco:$frescoVersion")
+    implementation("com.facebook.fresco:animated-gif:$frescoVersion")
+    implementation("com.facebook.fresco:animated-webp:$frescoVersion")
+    implementation("com.facebook.fresco:webpsupport:$frescoVersion")
+    implementation("com.facebook.fresco:animated-base:$frescoVersion")
+    implementation("com.squareup.okhttp3:okhttp:4.12.0")
+}