@blotch/angular-lynx-native 22.2.4 → 22.2.6

package/dist/ios/run.js

@@ -0,0 +1,176 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { NativeBuildError, capture, run } from "../process.js";
+/**
+ * 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 const pickSimulator = (list, device) => {
+    const runtimes = list.runtimes
+        .filter((runtime) => runtime.isAvailable &&
+        (runtime.platform
+            ? runtime.platform === 'iOS'
+            : runtime.identifier.includes('.iOS-')))
+        .sort((a, b) => compareVersions(b.version, a.version));
+    if (runtimes.length === 0) {
+        throw new NativeBuildError("No iOS Simulator runtime is installed. Install one with `xcodebuild -downloadPlatform iOS`, or in Xcode's settings under Components.");
+    }
+    // Newest runtime first, as `runtimes` is.
+    const simulators = runtimes.flatMap((runtime) => (list.devices[runtime.identifier] ?? [])
+        .filter((candidate) => candidate.isAvailable)
+        .map((candidate) => ({
+        udid: candidate.udid,
+        name: candidate.name,
+        deviceTypeIdentifier: candidate.deviceTypeIdentifier,
+        runtime,
+        // `bootstatus` waits for one that's still booting.
+        booted: candidate.state === 'Booted' || candidate.state === 'Booting',
+        lastUsedAt: candidate.lastUsedAt,
+    })));
+    if (device) {
+        const wanted = device.toLowerCase();
+        const matches = simulators.filter((simulator) => simulator.udid.toLowerCase() === wanted ||
+            simulator.name.toLowerCase() === wanted);
+        const match = matches.find((simulator) => simulator.booted) ?? matches[0];
+        if (!match) {
+            const names = [...new Set(simulators.map((simulator) => simulator.name))];
+            throw new NativeBuildError(`There's no iOS simulator named "${device}". Pass the name or UDID of one of these: ${names.join(', ')}. Or create one in Xcode's DeviceHub.`);
+        }
+        return match;
+    }
+    const booted = simulators
+        .filter((simulator) => simulator.booted)
+        .sort((a, b) => (b.lastUsedAt ?? '').localeCompare(a.lastUsedAt ?? ''));
+    if (booted[0]) {
+        return booted[0];
+    }
+    for (const runtime of runtimes) {
+        for (const type of iPhonesOf(runtime)) {
+            const ofType = simulators.filter((simulator) => simulator.runtime === runtime &&
+                simulator.deviceTypeIdentifier === type.identifier);
+            const existing = ofType.find((simulator) => simulator.name === type.name) ?? ofType[0];
+            if (existing) {
+                return existing;
+            }
+        }
+    }
+    for (const runtime of runtimes) {
+        const [newest] = iPhonesOf(runtime);
+        if (newest) {
+            return {
+                name: newest.name,
+                deviceTypeIdentifier: newest.identifier,
+                runtime,
+                booted: false,
+            };
+        }
+    }
+    throw new NativeBuildError(`No installed iOS runtime runs an iPhone simulator (${runtimes.map((runtime) => runtime.name).join(', ')}).`);
+};
+const iPhonesOf = (runtime) => runtime.supportedDeviceTypes?.filter((type) => type.productFamily === 'iPhone') ?? [];
+/**
+ * Orders runtime versions number by number: `27.0` > `26.4` > `26.0.1`.
+ */
+const compareVersions = (a, b) => {
+    const left = a.split('.').map(Number);
+    const right = b.split('.').map(Number);
+    for (let i = 0; i < Math.max(left.length, right.length); i++) {
+        const difference = (left[i] ?? 0) - (right[i] ?? 0);
+        if (difference !== 0) {
+            return difference;
+        }
+    }
+    return 0;
+};
+/**
+ * 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 const startIosSimulator = async ({ device, logFile, log, }) => {
+    const output = await capture('xcrun', [
+        'simctl',
+        'list',
+        '--json',
+        'devices',
+        'runtimes',
+    ]);
+    if (output === undefined) {
+        throw new NativeBuildError("Couldn't list the iOS simulators with `xcrun simctl`. Install Xcode and open it once, so it installs its command-line tools and the iOS platform.");
+    }
+    const simulator = pickSimulator(JSON.parse(output), device);
+    const xcrun = (args) => run('xcrun', args, { cwd: process.cwd(), logFile });
+    const label = `${simulator.name} (${simulator.runtime.name})`;
+    log(simulator.booted
+        ? `Running the app on the ${label} simulator`
+        : `Starting the ${label} simulator`);
+    const udid = simulator.udid ??
+        (await xcrun([
+            'simctl',
+            'create',
+            simulator.name,
+            simulator.deviceTypeIdentifier,
+            simulator.runtime.identifier,
+        ])).trim();
+    // Boots the simulator if it isn't, and waits until it is. Awaited only
+    // after the build; the empty catch keeps a failed boot from being an
+    // unhandled rejection while xcodebuild runs, and the await still throws it.
+    const booted = xcrun(['simctl', 'bootstatus', udid, '-b']);
+    booted.catch(() => { });
+    return {
+        launch: async (binary, app) => {
+            await booted;
+            await showSimulator(udid, logFile, log);
+            log(`Installing the app on ${simulator.name}`);
+            await xcrun(['simctl', 'install', udid, binary]);
+            // Replaces the copy a previous `--run` left open, which would otherwise
+            // stay in front, still running the old build.
+            await xcrun([
+                'simctl',
+                'launch',
+                '--terminate-running-process',
+                udid,
+                app.id,
+            ]);
+            log(`Opened ${app.name} on ${simulator.name}`);
+        },
+    };
+};
+/**
+ * Shows the simulator's screen. `simctl` boots a simulator without a
+ * window, and where the window comes from depends on Xcode's version:
+ *
+ * - Xcode 27.1 and later have no Simulator app. Its replacement, DeviceHub,
+ *   opens to a list of devices and doesn't show a simulator because it
+ *   booted, but its `devices://device/open?id=<UDID>` URL opens that
+ *   simulator in a window of its own, launching DeviceHub if it isn't
+ *   running. With its "Stop simulators on quit" setting on, quitting
+ *   DeviceHub shuts this simulator down too, though `simctl` booted it; the
+ *   next `--run` boots it again.
+ * - Earlier versions show every booted simulator in the Simulator app.
+ *   `-CurrentDeviceUDID` picks the one it shows first when it isn't open yet.
+ *
+ * Both are looked up in the Xcode that `xcode-select` (or DEVELOPER_DIR)
+ * selects, the one that built the app. The app runs whether the window opens
+ * or not, so a failure here is only reported.
+ */
+const showSimulator = async (udid, logFile, log) => {
+    const developerDir = (await capture('xcode-select', ['-p']))?.trim() ?? '';
+    const deviceHub = path.join(developerDir, '../Applications/DeviceHub.app');
+    const simulatorApp = path.join(developerDir, 'Applications/Simulator.app');
+    const args = developerDir && existsSync(deviceHub)
+        ? ['-a', deviceHub, `devices://device/open?id=${udid}`]
+        : developerDir && existsSync(simulatorApp)
+            ? ['-a', simulatorApp, '--args', '-CurrentDeviceUDID', udid]
+            : undefined;
+    if (!args) {
+        log("Couldn't find Xcode's DeviceHub or Simulator app to show the simulator. The app runs on it anyway.");
+        return;
+    }
+    await run('open', args, { cwd: process.cwd(), logFile }).catch((error) => log(`Couldn't show the simulator's window: ${error.message}`));
+};

package/dist/process.d.ts

@@ -6,12 +6,15 @@ export declare class NativeBuildError extends Error {
  * 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.
+ *
+ * Resolves with the tool's stdout, for the short commands whose answer is
+ * there, such as `simctl create` printing the new simulator's UDID.
  */
 export declare const run: (command: string, args: readonly string[], options: {
     readonly cwd: string;
     readonly logFile: string;
     readonly env?: NodeJS.ProcessEnv;
-}) => Promise<void>;
+}) => Promise<string>;
 /** 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

@@ -1 +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"}
+{"version":3,"file":"process.d.ts","sourceRoot":"","sources":["../src/process.ts"],"names":[],"mappings":"AAIA,8EAA8E;AAC9E,qBAAa,gBAAiB,SAAQ,KAAK;CAAG;AAQ9C;;;;;;;;GAQG;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,MAAM,CAyDhB,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

@@ -14,6 +14,9 @@ const ERROR_LINE = /(^|:\d+(:\d+)?:\s|^\s*e:\s)error:|^error:|^e: /;
  * 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.
+ *
+ * Resolves with the tool's stdout, for the short commands whose answer is
+ * there, such as `simctl create` printing the new simulator's UDID.
  */
 export const run = (command, args, options) => {
     mkdirSync(path.dirname(options.logFile), { recursive: true });
@@ -26,6 +29,7 @@ export const run = (command, args, options) => {
         });
         const recent = [];
         const errors = new Set();
+        let stdout = '';
         let partial = '';
         const record = (chunk) => {
             appendFileSync(options.logFile, chunk);
@@ -42,12 +46,15 @@ export const run = (command, args, options) => {
             recent.push(...lines);
             recent.splice(0, Math.max(0, recent.length - TAIL_LINES));
         };
-        child.stdout.on('data', record);
+        child.stdout.on('data', (chunk) => {
+            stdout += chunk.toString();
+            record(chunk);
+        });
         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();
+                resolve(stdout);
                 return;
             }
             const detail = errors.size > 0

package/dist/run.d.ts

@@ -0,0 +1,21 @@
+import type { ResolvedApp } from './options.ts';
+/** `ng build --platform <platform> --run`'s options. */
+export type RunOptions = {
+    /**
+     * Where to open the app. On iOS, a simulator's name or UDID; on Android, a
+     * virtual device's name or an adb serial. When it's left out, a running
+     * simulator, emulator or phone, or else the newest iPhone simulator or the
+     * first virtual device.
+     */
+    readonly device?: string;
+};
+/**
+ * A simulator, emulator or phone picked for `--run`. Picking it and starting
+ * it come before the native build, so a device that doesn't exist fails in
+ * seconds, and a simulator or emulator boots while Xcode or Gradle compiles.
+ */
+export type RunTarget = {
+    /** Waits for the device to finish starting, then installs and opens the app. */
+    readonly launch: (binary: string, app: ResolvedApp) => Promise<void>;
+};
+//# sourceMappingURL=run.d.ts.map

package/dist/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD,wDAAwD;AACxD,MAAM,MAAM,UAAU,GAAG;IACvB;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,gFAAgF;IAChF,QAAQ,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACtE,CAAC"}

package/dist/run.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blotch/angular-lynx-native",
-  "version": "22.2.4",
+  "version": "22.2.6",
   "description": "Builds AngularLynx apps into iOS and Android binaries",
   "homepage": "https://github.com/Blotch-Smart-Frames/AngularLynx#readme",
   "bugs": {

package/templates/android/README.md

@@ -34,11 +34,24 @@ Build commands and outputs (no flavors, so the names are fixed):
 
 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)`, and off again on the first screen (`LynxBackButton` in `packages/runtime/src/lib/router/lynx-back-button.ts`, which `provideRouter()` starts; the call goes through the background thread, where `NativeModules` lives). While it's on, a back press sends the global event `angularLynxBack` instead, which the runtime turns into `Location.back()`. 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). Layer 6's `native/back-button.yaml` checks both ends.
 
+## Web sign-in
+
+`NativeModules.AngularLynxWebAuth.start(request, callback)` (`WebAuthModule.kt`, behind the runtime's `LynxWebAuthSession`) opens `request.url` in a Custom Tab (`androidx.browser`). The page's redirect to `request.callbackScheme` comes back as a deep link: the activity is `singleTask`, so the intent reaches the open one in `onNewIntent`, which hands the URL to the callback, and starting it closes the Custom Tab above it. That's why the scheme has to be in the app's `deepLinkSchemes`. Android says nothing when a Custom Tab is closed, so the activity resuming with a session still open, after having gone behind the tab, means the person canceled. iOS's `WebAuthModule.swift` reports the same results through `ASWebAuthenticationSession`.
+
+## Global props
+
+`MainActivity.globalProps()` sends what the runtime reads and Lynx has no API for (see the package README), again on every configuration change and accessibility setting change.
+
+- **Dynamic color.** On Android 12 and later, `dynamicColors` carries the wallpaper's colors as Material 3's color roles, light and dark, as hex colors such as `#6750a4` (`DynamicColors.kt`, read by `LynxTheme.dynamicColors`). Android 14 has a color resource for most roles, which follows its contrast setting; on Android 12 and 13 each role takes its tone from the five tonal palettes, as Material Components does (a palette's own shade, or tone 40 moved to the tone with `ColorStateList.withLStar`). On the Android 14 emulator the two agree to within a few levels on the surfaces and exactly elsewhere.
+- **A new wallpaper doesn't restart the activity.** Android applies the new colors as a configuration change, which `onConfigurationChanged` handles like a dark mode switch, so the running app restyles with its state intact.
+- **The window follows dark mode by hand.** `configChanges` keeps the activity through a dark mode switch, so the window keeps the theme it started with. `onConfigurationChanged` sets its background (`@color/window_background`, which shows behind the system bars) and the bars' icons (`enableEdgeToEdge()`) again.
+
 ## 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.
+- `androidx.browser` 1.8.0, for the Custom Tabs `WebAuthModule` opens sign-in pages in.
 - Lynx's XElement 4.1.0 (`<input>`, `<textarea>`, `<overlay>`, `<svg>`, `<blur-view>`, `<viewpager>`, `<refresh>`, the `<scroll-coordinator>` family, `<webview>`, `<video>`), without its AnimaX and Markdown modules, which the runtime doesn't support. `MainActivity` registers the elements with `XElementBehaviors`. XElement depends on appcompat and material 1.0.0, whose vectordrawable libraries share a namespace that AGP 9 rejects, so appcompat 1.7.1 and material 1.12.0 are pinned.
 - 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/app/build.gradle.kts

@@ -118,6 +118,8 @@ android {
 dependencies {
     implementation("androidx.activity:activity-ktx:1.10.1")
     implementation("androidx.core:core-ktx:1.16.0")
+    // Custom Tabs, which WebAuthModule opens sign-in pages in.
+    implementation("androidx.browser:browser:1.8.0")
 
     // The Lynx engine, its JavaScript runtime (PrimJS) and its JS SDK.
     implementation("org.lynxsdk.lynx:lynx:$lynxVersion")

package/templates/android/app/src/main/java/dev/angularlynx/shell/DynamicColors.kt

@@ -0,0 +1,165 @@
+package dev.angularlynx.shell
+
+import android.content.Context
+import android.content.res.ColorStateList
+import android.os.Build
+import androidx.annotation.RequiresApi
+
+/**
+ * The colors Android 12 and later take from the user's wallpaper (Material
+ * You's dynamic color), for the `dynamicColors` global prop, which the
+ * runtime's `LynxTheme.dynamicColors` reads: Material 3's color roles, by
+ * their names in Material (`primary`, `onSurfaceVariant`), as hex colors such
+ * as `#6750a4`. Both the light and the dark scheme are sent, since an app can
+ * keep its own light or dark theme rather than follow the phone's.
+ *
+ * Android 14 has a color for most roles (`system_primary_light` and so on),
+ * which also follow its contrast setting. Android 12 and 13 have only the five
+ * tonal palettes the roles come from, at 13 tones each, so each role takes its
+ * tone from its palette as Material Components does on those versions (its
+ * `m3_sys_color_dynamic_*` colors): the palette's own color at that tone, or,
+ * for a tone in between, its tone 40 moved there with `withLStar`, which keeps
+ * the hue and chroma.
+ */
+object DynamicColors {
+    /** The `dynamicColors` global prop, or null before Android 12. */
+    fun read(context: Context): Map<String, Any>? {
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.S) return null
+        return mapOf(
+            "light" to scheme(context, light = true),
+            "dark" to scheme(context, light = false),
+        )
+    }
+
+    @RequiresApi(Build.VERSION_CODES.S)
+    private fun scheme(context: Context, light: Boolean): Map<String, String> =
+        ROLES.associate { role ->
+            val systemColor = if (light) role.lightColor else role.darkColor
+            val color = if (systemColor != null && Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
+                context.getColor(systemColor)
+            } else {
+                (if (light) role.lightTone else role.darkTone).color(context)
+            }
+            role.name to "#%06x".format(color and 0xffffff)
+        }
+
+    private enum class Palette(vararg val shades: Int) {
+        PRIMARY(
+            android.R.color.system_accent1_0, android.R.color.system_accent1_10,
+            android.R.color.system_accent1_50, android.R.color.system_accent1_100,
+            android.R.color.system_accent1_200, android.R.color.system_accent1_300,
+            android.R.color.system_accent1_400, android.R.color.system_accent1_500,
+            android.R.color.system_accent1_600, android.R.color.system_accent1_700,
+            android.R.color.system_accent1_800, android.R.color.system_accent1_900,
+            android.R.color.system_accent1_1000,
+        ),
+        SECONDARY(
+            android.R.color.system_accent2_0, android.R.color.system_accent2_10,
+            android.R.color.system_accent2_50, android.R.color.system_accent2_100,
+            android.R.color.system_accent2_200, android.R.color.system_accent2_300,
+            android.R.color.system_accent2_400, android.R.color.system_accent2_500,
+            android.R.color.system_accent2_600, android.R.color.system_accent2_700,
+            android.R.color.system_accent2_800, android.R.color.system_accent2_900,
+            android.R.color.system_accent2_1000,
+        ),
+        TERTIARY(
+            android.R.color.system_accent3_0, android.R.color.system_accent3_10,
+            android.R.color.system_accent3_50, android.R.color.system_accent3_100,
+            android.R.color.system_accent3_200, android.R.color.system_accent3_300,
+            android.R.color.system_accent3_400, android.R.color.system_accent3_500,
+            android.R.color.system_accent3_600, android.R.color.system_accent3_700,
+            android.R.color.system_accent3_800, android.R.color.system_accent3_900,
+            android.R.color.system_accent3_1000,
+        ),
+        NEUTRAL(
+            android.R.color.system_neutral1_0, android.R.color.system_neutral1_10,
+            android.R.color.system_neutral1_50, android.R.color.system_neutral1_100,
+            android.R.color.system_neutral1_200, android.R.color.system_neutral1_300,
+            android.R.color.system_neutral1_400, android.R.color.system_neutral1_500,
+            android.R.color.system_neutral1_600, android.R.color.system_neutral1_700,
+            android.R.color.system_neutral1_800, android.R.color.system_neutral1_900,
+            android.R.color.system_neutral1_1000,
+        ),
+        NEUTRAL_VARIANT(
+            android.R.color.system_neutral2_0, android.R.color.system_neutral2_10,
+            android.R.color.system_neutral2_50, android.R.color.system_neutral2_100,
+            android.R.color.system_neutral2_200, android.R.color.system_neutral2_300,
+            android.R.color.system_neutral2_400, android.R.color.system_neutral2_500,
+            android.R.color.system_neutral2_600, android.R.color.system_neutral2_700,
+            android.R.color.system_neutral2_800, android.R.color.system_neutral2_900,
+            android.R.color.system_neutral2_1000,
+        ),
+    }
+
+    /** The tone of each of a palette's shades (`system_accent1_0` is 100). */
+    private val SHADE_TONES = intArrayOf(100, 99, 95, 90, 80, 70, 60, 50, 40, 30, 20, 10, 0)
+
+    private class Tone(val palette: Palette, val tone: Int) {
+        @RequiresApi(Build.VERSION_CODES.S)
+        fun color(context: Context): Int {
+            val shade = SHADE_TONES.indexOf(tone)
+            if (shade >= 0) return context.getColor(palette.shades[shade])
+            val base = context.getColor(palette.shades[SHADE_TONES.indexOf(40)])
+            return ColorStateList.valueOf(base).withLStar(tone.toFloat()).defaultColor
+        }
+    }
+
+    /** A role, and its color on Android 14, where it has one. */
+    private class Role(
+        val name: String,
+        val lightTone: Tone,
+        val darkTone: Tone,
+        val lightColor: Int?,
+        val darkColor: Int?,
+    )
+
+    private fun role(
+        name: String,
+        palette: Palette,
+        lightTone: Int,
+        darkTone: Int,
+        lightColor: Int?,
+        darkColor: Int?,
+    ) = Role(name, Tone(palette, lightTone), Tone(palette, darkTone), lightColor, darkColor)
+
+    // Each role's palette and tones are Material Components' (1.12) for
+    // Android 12 and 13, and its colors Android 14's. Material Components
+    // makes the surfaces from the neutral variant palette. Android 14 has no
+    // inverse roles: the inverse primary is the other scheme's primary, and
+    // the inverse surfaces come from the palette on every version, at
+    // Material's tones. (Material Components gives them the other scheme's
+    // surface, tone 6 or 98, which is further from the surface than Material
+    // has them.)
+    private val ROLES = listOf(
+        role("primary", Palette.PRIMARY, 40, 80, android.R.color.system_primary_light, android.R.color.system_primary_dark),
+        role("onPrimary", Palette.PRIMARY, 100, 20, android.R.color.system_on_primary_light, android.R.color.system_on_primary_dark),
+        role("primaryContainer", Palette.PRIMARY, 90, 30, android.R.color.system_primary_container_light, android.R.color.system_primary_container_dark),
+        role("onPrimaryContainer", Palette.PRIMARY, 10, 90, android.R.color.system_on_primary_container_light, android.R.color.system_on_primary_container_dark),
+        role("inversePrimary", Palette.PRIMARY, 80, 40, android.R.color.system_primary_dark, android.R.color.system_primary_light),
+        role("secondary", Palette.SECONDARY, 40, 80, android.R.color.system_secondary_light, android.R.color.system_secondary_dark),
+        role("onSecondary", Palette.SECONDARY, 100, 20, android.R.color.system_on_secondary_light, android.R.color.system_on_secondary_dark),
+        role("secondaryContainer", Palette.SECONDARY, 90, 30, android.R.color.system_secondary_container_light, android.R.color.system_secondary_container_dark),
+        role("onSecondaryContainer", Palette.SECONDARY, 10, 90, android.R.color.system_on_secondary_container_light, android.R.color.system_on_secondary_container_dark),
+        role("tertiary", Palette.TERTIARY, 40, 80, android.R.color.system_tertiary_light, android.R.color.system_tertiary_dark),
+        role("onTertiary", Palette.TERTIARY, 100, 20, android.R.color.system_on_tertiary_light, android.R.color.system_on_tertiary_dark),
+        role("tertiaryContainer", Palette.TERTIARY, 90, 30, android.R.color.system_tertiary_container_light, android.R.color.system_tertiary_container_dark),
+        role("onTertiaryContainer", Palette.TERTIARY, 10, 90, android.R.color.system_on_tertiary_container_light, android.R.color.system_on_tertiary_container_dark),
+        role("background", Palette.NEUTRAL_VARIANT, 98, 6, android.R.color.system_background_light, android.R.color.system_background_dark),
+        role("onBackground", Palette.NEUTRAL, 10, 90, android.R.color.system_on_background_light, android.R.color.system_on_background_dark),
+        role("surface", Palette.NEUTRAL_VARIANT, 98, 6, android.R.color.system_surface_light, android.R.color.system_surface_dark),
+        role("onSurface", Palette.NEUTRAL, 10, 90, android.R.color.system_on_surface_light, android.R.color.system_on_surface_dark),
+        role("surfaceVariant", Palette.NEUTRAL_VARIANT, 90, 30, android.R.color.system_surface_variant_light, android.R.color.system_surface_variant_dark),
+        role("onSurfaceVariant", Palette.NEUTRAL_VARIANT, 30, 80, android.R.color.system_on_surface_variant_light, android.R.color.system_on_surface_variant_dark),
+        role("surfaceDim", Palette.NEUTRAL_VARIANT, 87, 6, android.R.color.system_surface_dim_light, android.R.color.system_surface_dim_dark),
+        role("surfaceBright", Palette.NEUTRAL_VARIANT, 98, 24, android.R.color.system_surface_bright_light, android.R.color.system_surface_bright_dark),
+        role("surfaceContainerLowest", Palette.NEUTRAL_VARIANT, 100, 4, android.R.color.system_surface_container_lowest_light, android.R.color.system_surface_container_lowest_dark),
+        role("surfaceContainerLow", Palette.NEUTRAL_VARIANT, 96, 10, android.R.color.system_surface_container_low_light, android.R.color.system_surface_container_low_dark),
+        role("surfaceContainer", Palette.NEUTRAL_VARIANT, 94, 12, android.R.color.system_surface_container_light, android.R.color.system_surface_container_dark),
+        role("surfaceContainerHigh", Palette.NEUTRAL_VARIANT, 92, 17, android.R.color.system_surface_container_high_light, android.R.color.system_surface_container_high_dark),
+        role("surfaceContainerHighest", Palette.NEUTRAL_VARIANT, 90, 22, android.R.color.system_surface_container_highest_light, android.R.color.system_surface_container_highest_dark),
+        role("inverseSurface", Palette.NEUTRAL, 20, 90, null, null),
+        role("inverseOnSurface", Palette.NEUTRAL, 95, 20, null, null),
+        role("outline", Palette.NEUTRAL_VARIANT, 50, 60, android.R.color.system_outline_light, android.R.color.system_outline_dark),
+        role("outlineVariant", Palette.NEUTRAL_VARIANT, 80, 30, android.R.color.system_outline_variant_light, android.R.color.system_outline_variant_dark),
+    )
+}

package/templates/android/app/src/main/java/dev/angularlynx/shell/MainActivity.kt

@@ -1,8 +1,12 @@
 package dev.angularlynx.shell
 
 import android.app.UiModeManager
+import android.content.ActivityNotFoundException
+import android.content.Intent
 import android.content.res.Configuration
 import android.database.ContentObserver
+import android.graphics.drawable.ColorDrawable
+import android.net.Uri
 import android.os.Build
 import android.os.Bundle
 import android.os.Handler
@@ -14,6 +18,7 @@ import android.widget.FrameLayout
 import androidx.activity.ComponentActivity
 import androidx.activity.OnBackPressedCallback
 import androidx.activity.enableEdgeToEdge
+import androidx.browser.customtabs.CustomTabsIntent
 import androidx.core.graphics.Insets
 import androidx.core.os.ConfigurationCompat
 import androidx.core.view.ViewCompat
@@ -30,7 +35,7 @@ import com.lynx.xelement.XElementBehaviors
  * The whole app: one full-screen LynxView running the Angular app. Angular
  * Router navigates inside it, so there is no native navigation stack.
  */
-class MainActivity : ComponentActivity(), ShellModule.Host {
+class MainActivity : ComponentActivity(), ShellModule.Host, WebAuthModule.Host {
     private lateinit var lynxView: LynxView
 
     // The system bar and cutout insets, and whether the screen has a cutout,
@@ -56,6 +61,13 @@ class MainActivity : ComponentActivity(), ShellModule.Host {
         }
     }
 
+    // The open sign-in (see WebAuthModule): the scheme its page returns to,
+    // who to tell, and whether the app has gone behind the Custom Tab yet.
+    private class WebAuthSession(val scheme: String, val done: (WebAuthModule.Result) -> Unit) {
+        var opened = false
+    }
+    private var webAuthSession: WebAuthSession? = null
+
     override fun onCreate(savedInstanceState: Bundle?) {
         // Android 15+ always draws apps edge to edge; opting in on older
         // versions too keeps the layout the same everywhere.
@@ -69,6 +81,7 @@ class MainActivity : ComponentActivity(), ShellModule.Host {
             setEnableGenericResourceFetcher(LynxBooleanOption.TRUE)
             setGenericResourceFetcher(AssetGenericResourceFetcher(this@MainActivity))
             registerModule(ShellModule.NAME, ShellModule::class.java, this@MainActivity)
+            registerModule(WebAuthModule.NAME, WebAuthModule::class.java, this@MainActivity)
             // Lynx's core has no <input>, <overlay>, <svg>, <blur-view> etc.;
             // these come from XElement (see app/build.gradle.kts). Lynx
             // Explorer registers them the same way.
@@ -135,15 +148,53 @@ class MainActivity : ComponentActivity(), ShellModule.Host {
         backHandler.isEnabled = enabled
     }
 
+    override fun startWebAuthSession(url: Uri, callbackScheme: String, done: (WebAuthModule.Result) -> Unit) {
+        if (webAuthSession != null) {
+            done(WebAuthModule.Result.Failed("A sign-in is already open."))
+            return
+        }
+        val session = WebAuthSession(callbackScheme.lowercase(), done)
+        webAuthSession = session
+        try {
+            CustomTabsIntent.Builder().build().launchUrl(this, url)
+        } catch (_: ActivityNotFoundException) {
+            webAuthSession = null
+            done(WebAuthModule.Result.Failed("No browser can open the sign-in page."))
+        }
+    }
+
+    // The page's redirect to the callback scheme. The activity is singleTask,
+    // so the deep link comes back to this one, which closes the Custom Tab
+    // above it. It arrives before onResume, which then finds no session open.
+    override fun onNewIntent(intent: Intent) {
+        super.onNewIntent(intent)
+        val url = intent.data ?: return
+        val session = webAuthSession ?: return
+        if (url.scheme?.lowercase() != session.scheme) return
+        webAuthSession = null
+        session.done(WebAuthModule.Result.Returned(url.toString()))
+    }
+
     // The manifest's configChanges keeps the activity, and the running app,
     // through a dark mode switch, so the new theme is sent from here. A
     // language change still restarts the activity, which sends the new
-    // appLocale: Angular reads LOCALE_ID only once.
+    // appLocale: Angular reads LOCALE_ID only once. A new wallpaper arrives
+    // here too, without a restart, and globalProps() reads its colors again.
     override fun onConfigurationChanged(newConfig: Configuration) {
         super.onConfigurationChanged(newConfig)
+        updateWindowAppearance()
         lynxView.updateGlobalProps(globalProps(newConfig))
     }
 
+    // Kept through a dark mode switch, the window keeps the theme it started
+    // with: its background, which shows behind the system bars, and the
+    // bars' icons, which enableEdgeToEdge() picked for the old mode. Both are
+    // set again for the new one, from the same resources.
+    private fun updateWindowAppearance() {
+        window.setBackgroundDrawable(ColorDrawable(getColor(R.color.window_background)))
+        enableEdgeToEdge()
+    }
+
     private fun sendGlobalProps() {
         lynxView.updateGlobalProps(globalProps(resources.configuration))
     }
@@ -153,7 +204,9 @@ class MainActivity : ComponentActivity(), ShellModule.Host {
      * (LynxSafeArea), `appLocale` (LynxLocale), the accessibility settings
      * (LynxAccessibilitySettings) and `osVersion` (LynxSystemInfo), plus the
      * safe-area insets in dp. The iOS shell sends the same keys, and Lynx
-     * Explorer sends theme and isNotchScreen too.
+     * Explorer sends theme and isNotchScreen too. Android 12 and later also
+     * send the wallpaper's colors, `dynamicColors` (LynxTheme.dynamicColors),
+     * which iOS has no equivalent of.
      */
     private fun globalProps(config: Configuration): Map<String, Any> {
         val density = resources.displayMetrics.density
@@ -175,6 +228,7 @@ class MainActivity : ComponentActivity(), ShellModule.Host {
         )
         // The user's language as a BCP 47 tag, such as "fr-FR".
         ConfigurationCompat.getLocales(config)[0]?.let { props["appLocale"] = it.toLanguageTag() }
+        DynamicColors.read(this)?.let { props["dynamicColors"] = it }
         return props
     }
 
@@ -197,10 +251,17 @@ class MainActivity : ComponentActivity(), ShellModule.Host {
     override fun onResume() {
         super.onResume()
         lynxView.onEnterForeground()
+        // Back from a Custom Tab without its redirect: the person closed it.
+        // Android says nothing else when a Custom Tab closes.
+        webAuthSession?.takeIf { it.opened }?.let {
+            webAuthSession = null
+            it.done(WebAuthModule.Result.Canceled)
+        }
     }
 
     override fun onPause() {
         lynxView.onEnterBackground()
+        webAuthSession?.opened = true
         super.onPause()
     }