create-mithril-lynx 2.3.0 → 2.5.0

package/README.md

@@ -50,7 +50,7 @@ Every flag, in one table — `npx create-mithril-lynx --help` prints the same li
 | `--android-id <id>` | `applicationId` / `namespace` (default `com.example.<name>`). |
 | `--app-name <name>` | Launcher label (default: the project name). |
 | `--with-font <file.ttf>` | Bundle the font into `src/assets/fonts/` and register it with `lynx.addFont()` in a loop. **DEV** (`npm run dev` / Lynx Go): `require()` inlines a `data:` URI so the font shows up in Explorer. **PROD** (`npm run build` / APK): `asset:///fonts/<file>` resolved by `AssetFontFaceLoader` on the host (keeps the bundle small — embedding `data:` URIs in the APK re-introduces the cold-start cost tracked in [lynx#9431](https://github.com/lynx-family/lynx/issues/9431)). Comma-separate for more than one file. |
-| `--find-font <term>` | Search [Fontsource](https://fontsource.org)'s catalog for `<term>`, prompt you to pick a family and a weight/style, download that one `.ttf`, and bundle it exactly like `--with-font`. Needs a real terminal (the picking is inherently interactive — use `--with-font <file.ttf>` in scripts/CI). Mutually exclusive with `--with-font`. Comma-separate terms for more than one — quote the whole thing if any term has a space. |
+| `--find-font <term>` | Search [Fontsource](https://fontsource.org)'s catalog for `<term>`, prompt you to pick a family and one or more weights/styles, download each `.ttf`, and bundle them exactly like `--with-font`. Needs a real terminal (the picking is inherently interactive — use `--with-font <file.ttf>` in scripts/CI). Mutually exclusive with `--with-font`. Comma-separate terms for more than one — quote the whole thing if any term has a space. |
 | `--font-family <name>` | Override the family name derived from the font's file name (or from Fontsource, with `--find-font`). Only valid with exactly one font. |
 
 Anything not listed — in particular the four Android flags — requires `--android`
@@ -67,18 +67,23 @@ npx create-mithril-lynx my-app --blank --android --find-font "Inter,JetBrains Mo
 
 Each font is one entry in a `FONTS` array in `src/background.ts`, registered
 with a single `for…of` + `lynx.addFont()` loop (DEV `require` / PROD
-`asset:///` — see the `--with-font` row above). Only the **first** one gets
-the automatic `text { font-family: ...; }` rule in `src/style.css` (there's
-no way for the CLI to guess which elements should use which font past that)
-— the rest are registered and ready to use, but you assign them to your own
-classes by hand, e.g.:
+`asset:///` — see the `--with-font` row above).
+
+The CSS side lives in a separate, **generated** file, `src/fonts.css`, which
+`src/style.css` pulls in with a single `@import "fonts.css";` line at the top.
+`fonts.css` holds `text { font-family: ...; }` for the **first** font and, when
+there is more than one font, one class per family/variant:
 
 ```css
-.code {
-  font-family: "JetBrains Mono", monospace;
-}
+.Ubuntu_Regular { font-family: "Ubuntu Regular", sans-serif; }
+.Ubuntu_Bold    { font-family: "Ubuntu Bold", sans-serif; }
+.Inter_Regular  { font-family: "Inter Regular", sans-serif; }
 ```
 
+`fonts.css` is owned by the tooling and rewritten from the full font list on
+every run (scaffold or `add-font`) — don't edit it by hand; put your own rules
+in `style.css`. (Unused classes can be pruned by a later PostCSS pass.)
+
 ### Adding fonts after the project exists
 
 ```bash
@@ -88,11 +93,12 @@ npx create-mithril-lynx add-font --find-font "Roboto Mono"
 ```
 
 Copying the `.ttf` into `src/assets/fonts/` (and the Android host's
-`assets/fonts/` when present) is always safe. Wiring `background.ts` /
-`style.css` is automatic **only while those files still match the stock
-template** (including a previously generated `FONTS` block on top of it). If
-you've edited them, the command prints the exact block to paste by hand and
-leaves your files untouched.
+`assets/fonts/` when present) is always safe. `src/fonts.css` is always
+regenerated, and `style.css` only ever gets the one `@import "fonts.css";`
+line (added if missing). Wiring `background.ts` is automatic **only while it
+still matches the stock template** (including a previously generated `FONTS`
+block on top of it); if you've edited it, the command prints the exact block
+to paste by hand and leaves your file untouched.
 
 ### `--find-font`, in more detail
 
@@ -101,11 +107,13 @@ exact `id`/`family` filters — so `--find-font` downloads the whole font list
 once (~2100 fonts, ~540KB as of 2026-09), caches it for 24h in the OS temp
 directory, and filters client-side on `family`/`id` substrings. Picking a
 family fetches that font's own detail (its real weight/style/subset `.ttf`
-URLs), lets you pick one variant (defaulting to 400/normal if available),
-downloads it to a temp file, and hands it to the same code path
+URLs), lets you pick one or more variants (space to toggle; defaulting to 400/normal if available),
+downloads each to a temp file, and hands them to the same code path
 `--with-font <file>` uses — there's no separate font-loading mechanism to
 maintain.
 
+Every picked variant is registered as `<Family> <Variant>` (`Inter Regular`, `Inter Bold`, `Inter Light Italic`…), with a matching class in `src/fonts.css` (`.Inter_Bold`). The first one (400/normal if picked) is the default `text` font.
+
 ```bash
 npx create-mithril-lynx my-app --blank --android --find-font Inter
 ```
@@ -116,8 +124,8 @@ The sibling `<name>-android/` project is a complete, no-Android-Studio Gradle CL
 
 - the Gradle wrapper (`gradlew`, `gradlew.bat`, `gradle-wrapper.jar`), so nothing needs to be installed besides a JDK and the Android SDK;
 - `local.properties` with `sdk.dir` auto-detected from `ANDROID_HOME`/`ANDROID_SDK_ROOT` (with a written warning if it can't be found);
-- the Kotlin host: the `Application` (registers `AssetFontFaceLoader`), `MainActivity` (async `AssetTemplateProvider`, splash screen, `NoopGenericResourceFetcher` for the fast `data:` font path — [lynx#9431](https://github.com/lynx-family/lynx/issues/9431));
-- resource files that compile as-is (theme, splash theme, adaptive launcher icon);
+- the Kotlin host: the `Application` (registers `AssetFontFaceLoader`), `MainActivity` (async `AssetTemplateProvider`, splash screen, `NoopGenericResourceFetcher` for the fast `data:` font path — [lynx#9431](https://github.com/lynx-family/lynx/issues/9431)), and a predefined native bridge for `mithril-lynx/route`'s Android system Back support;
+- a project-local `android/` folder with editable `AndroidManifest.xml`, `strings.xml`, `styles.xml`, `config.xml`, `network_security_config.xml`, and `file_paths.xml`, plus `bun run android:prepare` to copy them into the Gradle host;
 - an opt-in release signing setup driven by a gitignored `keystore.properties`.
 
 And in the JS project, a `scripts/android.mjs` bridge plus npm scripts:
@@ -127,10 +135,11 @@ npm run android            # build + sync + installDebug + launch, printing Tota
 npm run android:apk        # build + sync + assembleDebug
 npm run android:release    # build + sync + assembleRelease (signed if keystore.properties exists)
 npm run android:sync       # build + sync bundle into app/src/main/assets/, no Gradle
+bun run android:prepare    # manually sync android/*.xml -> sibling Android host
 npm run android:keystore   # generate release.keystore + keystore.properties (KEYSTORE_PASSWORD=...)
 ```
 
-This part of the tool is framework-agnostic — it just wraps whatever bundle `rspeedy build` produces into a native host — so it needed no changes for the `mithril-lynx` rewrite beyond what's inherited automatically through the generated JS project.
+The packaging path still wraps whatever bundle `rspeedy build` produces. Its one framework-aware convenience is the predefined, otherwise dormant system Back bridge used by `mithril-lynx/route`; the Basic Activity template connects it automatically.
 
 ## Templates
 
@@ -138,7 +147,7 @@ This part of the tool is framework-agnostic — it just wraps whatever bundle `r
 |---|---|
 | **Hello World** (recommended) | The Mithril.js analog of Lynx's official React hello-world ([`lynx-examples/examples/hello-world`](https://github.com/lynx-family/lynx-examples/tree/main/examples/hello-world)) — same layout, same "tap the logo" interaction, running through Mithril hyperscript instead of JSX. |
 | **Blank** | A single centered line of text. Nothing else — the starting point when you don't want any of Hello World's styling/assets in your way. |
-| **Basic Activity** | Two screens (Main → Details) wired with [`mithril-lynx/route`](https://github.com/carlos-sweb/mithril-lynx/blob/main/ROUTE.md) — an in-memory router (`m.route`, reimplemented for an environment with no URL bar). Includes a reusable app-bar-with-back-button pattern, using `route.back()` since Lynx has no hardware back button for a route to hook into automatically. |
+| **Basic Activity** | Two screens (Main → Details) wired with [`mithril-lynx/route`](https://github.com/carlos-sweb/mithril-lynx/blob/main/ROUTE.md) — an in-memory router (`m.route`, reimplemented for an environment with no URL bar). Includes a reusable app-bar back affordance and, with `--android`, predefined system Back/predictive Back integration through `route.listenBackButton()`. |
 
 ## Package structure
 
@@ -164,15 +173,17 @@ create-mithril-lynx/
       ts/src/{app-bar.ts, background.ts, screens/{home,detail}.ts}
     android/                 only used with --android
       host/                  the Gradle project -> <name>-android/
-                             (includes AssetFontFaceLoader +
-                             NoopGenericResourceFetcher for lynx#9431)
-      app-scripts/android.mjs       the bridge -> <name>/scripts/android.mjs
-                             (syncs bundle + src/assets/fonts/ → assets/fonts/)
+                             (includes AssetFontFaceLoader,
+                             NoopGenericResourceFetcher for lynx#9431, and the
+                             MithrilLynxNavigationModule system-Back bridge)
+      app-scripts/{android,android-prepare}.mjs
+                             bridges in <name>/scripts/ (syncs bundle/fonts;
+                             prepares <name>/android/*.xml into the host)
 ```
 
 `src/index.js` copies, in order, `templates/_shared/common` → `templates/_shared/ts` → `templates/<template>/common` → `templates/<template>/ts` into the target directory — later copies overwrite same-named files from earlier ones, which is exactly how **Basic Activity**'s own routing-based `src/background.ts` replaces `_shared/ts`'s generic single-view one (Hello World and Blank don't ship their own, so they keep the shared file). It then renames `gitignore` to `.gitignore` (npm doesn't publish dotfiles reliably otherwise) and replaces `{{PROJECT_NAME}}`/`{{MITHRIL_LYNX_VERSION}}` placeholders in `package.json` and `README.md`.
 
-With `--android` it then copies `templates/android/host` into a sibling `<name>-android/` (renaming `package-path` to the real package directory and `App.kt` to the Application class) and substitutes `{{PACKAGE_NAME}}`, `{{APP_CLASS}}`, `{{APP_NAME}}`, `{{ANDROID_DIR}}` and `{{SDK_DIR}}` across the tree. Binary files (the Gradle wrapper jar, a `--with-font` `.ttf`) are never text-substituted. With `--with-font`, each font is copied into the JS project (`src/assets/fonts/`) *and* seeded into the Android host's `assets/fonts/`, wired up with a `FONTS` loop + `lynx.addFont()` in `src/background.ts` plus a `text { font-family: ... }` rule in `src/style.css` for the first font. `scripts/android.mjs` keeps `assets/fonts/` in sync on every `npm run android` / `android:sync`.
+With `--android` it then copies `templates/android/host` into a sibling `<name>-android/` (renaming `package-path` to the real package directory and `App.kt` to the Application class) and substitutes `{{PACKAGE_NAME}}`, `{{APP_CLASS}}`, `{{APP_NAME}}`, `{{ANDROID_DIR}}` and `{{SDK_DIR}}` across the tree. It also seeds the generated project's `android/` folder with `AndroidManifest.xml`, `strings.xml`, `styles.xml`, `config.xml`, `network_security_config.xml`, and `file_paths.xml`. `bun run build` (and the Android build commands that invoke it) automatically synchronizes those local copies to the Gradle host first; use `bun run android:prepare` (or `npm run android:prepare`) when you only want that synchronization. Binary files (the Gradle wrapper jar, a `--with-font` `.ttf`) are never text-substituted. With `--with-font`, each font is copied into the JS project (`src/assets/fonts/`) *and* seeded into the Android host's `assets/fonts/`, wired up with a `FONTS` loop + `lynx.addFont()` in `src/background.ts` plus a generated `src/fonts.css` (`text { font-family }` for the first font, one class per font when there are several) imported from `src/style.css`. `scripts/android.mjs` keeps `assets/fonts/` in sync on every `npm run android` / `android:sync`.
 
 **Not carried over from v1 (yet)**: the JavaScript variant. The old tool generated either TypeScript or JavaScript for every template; this rewrite ships TypeScript only for now — doubling every template for a parallel JS copy wasn't part of this pass.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-mithril-lynx",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "description": "Scaffolds a new mithril-lynx app (and, optionally, its Android host).",
   "license": "MIT",
   "type": "module",

package/src/fonts-wire.js

@@ -7,7 +7,10 @@
  *      host's assets/fonts/ when present) — that part is always safe.
  *   2. If src/background.ts still matches a stock template (optionally with
  *      our generated FONTS block on top), rewrite the font block in place.
- *   3. Same idea for src/style.css's automatic `text { font-family }` rule.
+ *   3. Always (re)generate src/fonts.css — a system-owned file holding the
+ *      `text { font-family }` default and one class per family/variant — and
+ *      make sure src/style.css has `@import "fonts.css";`. Users never edit
+ *      fonts.css by hand; every add-font run rewrites it from the full list.
  *   4. Otherwise print the exact lines the user must paste by hand.
  */
 import fs from "node:fs";
@@ -33,7 +36,6 @@ export function normalizeSource(text) {
 
 export function buildFontBlock(fonts) {
 	const defaultFamily = fonts[0].family;
-	const extraFamilies = fonts.slice(1).map((f) => f.family);
 	const requireEntries = fonts
 		.map(
 			({ family, file }) =>
@@ -55,13 +57,8 @@ export function buildFontBlock(fonts) {
 		"//   • DEV  (Lynx Go / `npm run dev`): require() → data: URI inline",
 		"//   • PROD (Android APK / `npm run build`): asset:///fonts/<file>",
 		"//     resolved by AssetFontFaceLoader (lynx#9431 workaround).",
-		...(extraFamilies.length > 0
-			? [
-					`// Only "${defaultFamily}" got the automatic text { font-family: ... }`,
-					`// rule below — assign ${extraFamilies.map((f) => `"${f}"`).join(" / ")} to your own`,
-					'// classes in src/style.css, e.g. `.code { font-family: "' + extraFamilies[0] + '"; }`.',
-				]
-			: []),
+		"// The default `text { font-family }` and one .Family_Variant class per font",
+		"// live in src/fonts.css, which is generated — don't edit it by hand.",
 		"type FontEntry = { family: string; file: string; url: string };",
 		"const FONTS: FontEntry[] = import.meta.env.DEV",
 		"\t? [",
@@ -78,8 +75,35 @@ export function buildFontBlock(fonts) {
 	].join("\n");
 }
 
-export function buildCssFontBlock(family) {
-	return [`text {`, `  font-family: "${family}", sans-serif;`, `}`, "", ""].join("\n");
+/** `Ubuntu Light Italic` → `Ubuntu_Light_Italic` (usable as a CSS class name). */
+export function cssClassName(family) {
+	return family.trim().replace(/[^\w-]+/g, "_");
+}
+
+export const FONTS_CSS_FILE = "fonts.css";
+const FONTS_CSS_IMPORT = `@import "${FONTS_CSS_FILE}";`;
+
+/**
+ * Contents of src/fonts.css. With one font: just the `text` default. With
+ * more than one: also a `.Family_Variant { font-family }` class per font, so
+ * a later (postcss) pass can drop the classes the app never uses.
+ */
+export function buildFontsCss(fonts) {
+	const lines = [
+		"/* GENERATED by create-mithril-lynx (--with-font / --find-font / add-font).",
+		" * Owned by the tooling: it is rewritten from the full font list on every",
+		" * add-font run, so do not edit it by hand — put your own rules in style.css. */",
+		"text {",
+		`  font-family: "${fonts[0].family}", sans-serif;`,
+		"}",
+		"",
+	];
+	if (fonts.length > 1) {
+		for (const { family } of fonts) {
+			lines.push(`.${cssClassName(family)} {`, `  font-family: "${family}", sans-serif;`, "}", "");
+		}
+	}
+	return lines.join("\n");
 }
 
 /** Match our generated font block at the top of background.ts (if any). */
@@ -132,31 +156,14 @@ function loadBaseBackgrounds() {
 	];
 }
 
-function loadBaseStyles() {
-	const out = [];
-	for (const rel of [
-		"templates/blank/common/src/style.css",
-		"templates/hello-world/common/src/style.css",
-		"templates/basic-activity/common/src/style.css",
-	]) {
-		out.push(normalizeSource(fs.readFileSync(path.join(packageRoot, rel), "utf8")));
-	}
-	return out;
-}
-
 export function isStockBackground(restSource) {
 	const normalized = normalizeSource(restSource);
 	return loadBaseBackgrounds().some((base) => base === normalized);
 }
 
-export function isStockCss(restSource) {
-	const normalized = normalizeSource(restSource);
-	return loadBaseStyles().some((base) => base === normalized);
-}
-
 /**
  * Copy font files into the JS project (and Android host assets when found).
- * Always safe — does not touch background.ts / style.css.
+ * Always safe — does not touch background.ts / style.css / fonts.css.
  */
 export function copyFontFiles({ projectRoot, fonts, androidDir = null }) {
 	const jsFontsDir = path.join(projectRoot, "src", "assets", "fonts");
@@ -231,36 +238,29 @@ export function applyBackgroundFonts(projectRoot, fonts) {
 }
 
 /**
- * Try to ensure the automatic text { font-family } rule for `defaultFamily`.
- * Extra fonts are never written into CSS (same policy as scaffold).
- * Returns { ok, skipped?, reason?, manualBlock? }.
+ * Write src/fonts.css from the full font list and make sure src/style.css
+ * imports it. style.css is only ever touched to add the one `@import` line
+ * (and to drop the `text { font-family }` block older versions put there).
+ * Returns { ok, reason?, manualBlock? } — ok=false only when style.css
+ * couldn't be found to add the import.
  */
-export function applyCssDefaultFont(projectRoot, defaultFamily, { hadExistingFonts }) {
-	const cssPath = path.join(projectRoot, "src", "style.css");
+export function applyFontsCss(projectRoot, fonts) {
+	const srcDir = path.join(projectRoot, "src");
+	fs.mkdirSync(srcDir, { recursive: true });
+	fs.writeFileSync(path.join(srcDir, FONTS_CSS_FILE), buildFontsCss(fonts));
+
+	const cssPath = path.join(srcDir, "style.css");
 	if (!fs.existsSync(cssPath)) {
-		return {
-			ok: false,
-			reason: "src/style.css not found",
-			manualBlock: buildCssFontBlock(defaultFamily),
-		};
+		return { ok: false, reason: "src/style.css not found", manualBlock: `${FONTS_CSS_IMPORT}\n` };
 	}
 	const raw = fs.readFileSync(cssPath, "utf8");
-	const { rest, family: existingFamily } = stripCssFontBlock(raw);
-
-	// Already has our rule and we were only appending more fonts — leave it.
-	if (hadExistingFonts && existingFamily != null) {
+	const { block, rest } = stripCssFontBlock(raw);
+	if (/@import\s+(?:url\()?["']?(?:\.\/)?fonts\.css["']?\)?\s*;/.test(rest)) {
+		if (block != null) fs.writeFileSync(cssPath, rest);
 		return { ok: true, skipped: true };
 	}
-
-	if (!isStockCss(rest)) {
-		return {
-			ok: false,
-			reason: "src/style.css no longer matches the stock template",
-			manualBlock: buildCssFontBlock(defaultFamily),
-		};
-	}
-
-	fs.writeFileSync(cssPath, `${buildCssFontBlock(defaultFamily)}${rest}`);
+	// @import must come before any other rule, so it goes at the very top.
+	fs.writeFileSync(cssPath, `${FONTS_CSS_IMPORT}\n\n${rest}`);
 	return { ok: true };
 }
 

package/src/index.js

@@ -5,14 +5,14 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { execSync } from "node:child_process";
 
-import { cancel, confirm, intro, isCancel, outro, select, spinner, text } from "@clack/prompts";
+import { cancel, confirm, intro, isCancel, multiselect, outro, select, spinner, text } from "@clack/prompts";
 
 import { fetchFontDetail, fetchFontList, listVariants, searchFonts } from "./fontsource.js";
 import {
 	applyBackgroundFonts,
-	applyCssDefaultFont,
-	buildCssFontBlock,
+	applyFontsCss,
 	buildFontBlock,
+	cssClassName,
 	copyFontFiles,
 	findAndroidDir,
 	findProjectRoot,
@@ -137,6 +137,26 @@ function appClassNameFor(rawName) {
 	return name === "MainActivity" ? `${name}App` : name;
 }
 
+/** Android files users edit from the JS project, before syncing them into the
+ * sibling Gradle host with `bun run android:prepare`. */
+const ANDROID_DEVELOPMENT_FILES = [
+	["AndroidManifest.xml", ["AndroidManifest.xml"]],
+	["strings.xml", ["res", "values", "strings.xml"]],
+	["styles.xml", ["res", "values", "styles.xml"]],
+	["config.xml", ["res", "xml", "config.xml"]],
+	["network_security_config.xml", ["res", "xml", "network_security_config.xml"]],
+	["file_paths.xml", ["res", "xml", "file_paths.xml"]],
+];
+
+function seedAndroidDevelopmentFiles(targetDir, androidDir) {
+	const sourceRoot = path.join(androidDir, "app", "src", "main");
+	const destinationRoot = path.join(targetDir, "android");
+	fs.mkdirSync(destinationRoot, { recursive: true });
+	for (const [name, sourceParts] of ANDROID_DEVELOPMENT_FILES) {
+		fs.copyFileSync(path.join(sourceRoot, ...sourceParts), path.join(destinationRoot, name));
+	}
+}
+
 function fontFamilyFor(filePath) {
 	return path
 		.basename(filePath, path.extname(filePath))
@@ -255,6 +275,12 @@ const WEIGHT_NAMES = {
 	900: "Black",
 };
 
+/** "Bold", "Light Italic" — the part appended to the family name. */
+function variantName(variant) {
+	const weightName = WEIGHT_NAMES[variant.weight] ?? String(variant.weight);
+	return `${weightName}${variant.style === "italic" ? " Italic" : ""}`;
+}
+
 function variantLabel(variant) {
 	const weightName = WEIGHT_NAMES[variant.weight] ?? String(variant.weight);
 	const style = variant.style === "italic" ? " Italic" : "";
@@ -264,8 +290,8 @@ function variantLabel(variant) {
 /**
  * Interactive search-download flow for `--find-font <term>`: queries
  * Fontsource's catalog locally (see src/fontsource.js — the API itself has
- * no free-text search), lets the user pick a family and one weight/style,
- * downloads that .ttf to a temp file, and returns it in the same shape
+ * no free-text search), lets the user pick a family and one or more weights/styles,
+ * downloads each .ttf to a temp file, and returns them in the same shape
  * `--with-font <file>` expects, so the rest of the pipeline (entirely
  * JS-side — see patchJsProject()) doesn't need to know which path was used.
  */
@@ -322,33 +348,45 @@ async function findFontInteractively(term) {
 	s2.stop(`${variants.length || allVariants.length} variant(s) available.`);
 
 	const pickFrom = variants.length > 0 ? variants : allVariants;
-	const chosenVariant = await select({
-		message: "Which weight/style?",
-		initialValue: pickFrom.find((v) => v.weight === 400 && v.style === "normal") ?? pickFrom[0],
+	const defaultVariant = pickFrom.find((v) => v.weight === 400 && v.style === "normal") ?? pickFrom[0];
+	const chosenVariants = await multiselect({
+		message: "Which weights/styles? (space to toggle, enter to confirm)",
+		initialValues: [defaultVariant],
+		required: true,
 		options: pickFrom.map((v) => ({ value: v, label: variantLabel(v) })),
 	});
-	if (isCancel(chosenVariant)) return null;
-
-	const s3 = spinner();
-	s3.start(`Downloading ${detail.family} ${variantLabel(chosenVariant)}…`);
-	let bytes;
-	try {
-		const response = await fetch(chosenVariant.url);
-		if (!response.ok) throw new Error(`Download failed: HTTP ${response.status}`);
-		bytes = Buffer.from(await response.arrayBuffer());
-	} catch (error) {
-		s3.stop("Download failed.");
-		cancel(error instanceof Error ? error.message : String(error));
-		process.exit(1);
-	}
-	const tempFile = path.join(
-		os.tmpdir(),
-		`${chosenId}-${chosenVariant.weight}-${chosenVariant.style}-${chosenVariant.subset}.ttf`,
+	if (isCancel(chosenVariants)) return null;
+	// Regular first (it becomes the family's plain name), then by weight/style.
+	chosenVariants.sort(
+		(a, b) =>
+			(b === defaultVariant) - (a === defaultVariant) || a.weight - b.weight || a.style.localeCompare(b.style),
 	);
-	fs.writeFileSync(tempFile, bytes);
-	s3.stop(`Downloaded ${(bytes.length / 1024).toFixed(1)} kB.`);
 
-	return { sourcePath: tempFile, family: detail.family };
+	const results = [];
+	for (const [index, variant] of chosenVariants.entries()) {
+		const s3 = spinner();
+		s3.start(`Downloading ${detail.family} ${variantLabel(variant)}…`);
+		let bytes;
+		try {
+			const response = await fetch(variant.url);
+			if (!response.ok) throw new Error(`Download failed: HTTP ${response.status}`);
+			bytes = Buffer.from(await response.arrayBuffer());
+		} catch (error) {
+			s3.stop("Download failed.");
+			cancel(error instanceof Error ? error.message : String(error));
+			process.exit(1);
+		}
+		const tempFile = path.join(
+			os.tmpdir(),
+			`${chosenId}-${variant.weight}-${variant.style}-${variant.subset}.ttf`,
+		);
+		fs.writeFileSync(tempFile, bytes);
+		s3.stop(`Downloaded ${(bytes.length / 1024).toFixed(1)} kB.`);
+		// Each file is registered under its own family name (addFont has no
+		// weight/style axis here): "Ubuntu Regular", "Ubuntu Bold Italic"…
+		results.push({ sourcePath: tempFile, base: detail.family, family: `${detail.family} ${variantName(variant)}` });
+	}
+	return results;
 }
 
 // ---------------------------------------------------------------------------
@@ -418,7 +456,7 @@ async function resolveFontsFromFlags(android, { baseDir, requireFonts }) {
 
 	if (android.fontFamily != null && fontCount > 1) {
 		cancel(
-			"--font-family only makes sense with exactly one font — omit it when bundling more than one, or edit src/style.css/background.ts by hand afterwards.",
+			"--font-family only makes sense with exactly one font — omit it when bundling more than one, or use the classes in src/fonts.css.",
 		);
 		process.exit(1);
 	}
@@ -438,11 +476,20 @@ async function resolveFontsFromFlags(android, { baseDir, requireFonts }) {
 	for (const term of findFontTerms) {
 		const found = await findFontInteractively(term);
 		if (found == null) return null;
-		fonts.push({
-			sourcePath: found.sourcePath,
-			file: path.basename(found.sourcePath),
-			family: android.fontFamily ?? found.family,
-		});
+		for (const variant of found) {
+			fonts.push({
+				sourcePath: variant.sourcePath,
+				file: path.basename(variant.sourcePath),
+				// --font-family replaces the family part; the variant suffix stays
+				// unless there is only one variant.
+				family:
+					android.fontFamily == null
+						? variant.family
+						: found.length === 1
+							? android.fontFamily
+							: variant.family.replace(variant.base, android.fontFamily),
+			});
+		}
 	}
 	for (const rawPath of fontPaths) {
 		const resolved = path.resolve(baseDir, rawPath);
@@ -505,7 +552,6 @@ async function runAddFont(args) {
 	const { fonts: existingInBg } = stripFontBlock(
 		fs.existsSync(bgPath) ? fs.readFileSync(bgPath, "utf8") : "",
 	);
-	const hadExistingFonts = existingInBg.length > 0;
 	const merged = mergeFontLists(existingInBg, incoming, dedupeFontFiles);
 
 	const androidDir = findAndroidDir(projectRoot);
@@ -535,30 +581,19 @@ async function runAddFont(args) {
 		printManualBlock("src/background.ts", bgResult.manualBlock);
 	}
 
-	const cssResult = applyCssDefaultFont(projectRoot, merged[0].family, { hadExistingFonts });
-	if (cssResult.ok && cssResult.skipped) {
-		console.log(
-			`  · src/style.css already has text { font-family: … } — assign extra fonts in your own classes.`,
-		);
-	} else if (cssResult.ok) {
-		console.log("  ✔ Updated src/style.css");
-	} else {
-		console.log(`  ✖ Could not auto-edit src/style.css (${cssResult.reason}).`);
-		console.log("    Paste this at the top of src/style.css (or assign the family on your own classes):");
+	const cssResult = applyFontsCss(projectRoot, merged);
+	console.log("  ✔ Regenerated src/fonts.css (generated — don't edit it by hand)");
+	if (cssResult.ok && !cssResult.skipped) {
+		console.log('  ✔ Added @import "fonts.css"; to src/style.css');
+	} else if (!cssResult.ok) {
+		console.log(`  ✖ Could not add the import to src/style.css (${cssResult.reason}).`);
+		console.log("    Add this line at the very top of your stylesheet:");
 		printManualBlock("src/style.css", cssResult.manualBlock);
 	}
 
-	const extras = merged.slice(hadExistingFonts ? existingInBg.length : 1).map((f) => f.family);
-	// When we had no prior fonts, slice(1) are extras beyond the CSS default.
-	// When we had prior fonts, newly added ones after existingInBg.length need a note.
-	const newlyAddedFamilies = incoming.map((f) => f.family);
-	if (hadExistingFonts && newlyAddedFamilies.length > 0) {
+	if (merged.length > 1) {
 		console.log(
-			`  · New font${newlyAddedFamilies.length > 1 ? "s" : ""} ${newlyAddedFamilies.map((f) => `"${f}"`).join(", ")} — set font-family on your own CSS classes.`,
-		);
-	} else if (!hadExistingFonts && extras.length > 0) {
-		console.log(
-			`  · Extra font${extras.length > 1 ? "s" : ""} ${extras.map((f) => `"${f}"`).join(", ")} — set font-family on your own CSS classes.`,
+			`  · Use the classes in src/fonts.css: ${merged.map((f) => "." + cssClassName(f.family)).join(", ")}`,
 		);
 	}
 
@@ -626,10 +661,16 @@ function scaffoldAndroid({ targetDir, rawName, options }) {
 		}
 	}
 
-	// 5. The script that joins the two halves, inside the JS project.
+	// 5. Give app developers editable Android XML in their project, instead of
+	// making them traverse into the sibling Gradle host. android:prepare copies
+	// these exact files back into their Android resource locations.
+	seedAndroidDevelopmentFiles(targetDir, androidDir);
+
+	// 6. The scripts that join the two halves, inside the JS project.
 	const scriptsDir = path.join(targetDir, "scripts");
 	fs.mkdirSync(scriptsDir, { recursive: true });
 	fs.copyFileSync(path.join(ANDROID_TEMPLATE_ROOT, "app-scripts", "android.mjs"), path.join(scriptsDir, "android.mjs"));
+	fs.copyFileSync(path.join(ANDROID_TEMPLATE_ROOT, "app-scripts", "android-prepare.mjs"), path.join(scriptsDir, "android-prepare.mjs"));
 
 	const androidRelDir = path.relative(targetDir, androidDir).split(path.sep).join("/");
 	replaceInFile(path.join(scriptsDir, "android.mjs"), [
@@ -639,6 +680,7 @@ function scaffoldAndroid({ targetDir, rawName, options }) {
 		// A name with quotes would break keytool's -dname=CN=...
 		["{{APP_NAME}}", appName.replace(/["\\]/g, "")],
 	]);
+	replaceInFile(path.join(scriptsDir, "android-prepare.mjs"), [["{{ANDROID_REL_DIR}}", androidRelDir]]);
 
 	return { androidDir, androidDirName, androidRelDir, androidId, appName, appClass, fonts, sdkDir };
 }
@@ -647,12 +689,18 @@ function patchJsProject({ targetDir, android }) {
 	// package.json: the Android scripts.
 	const pkgPath = path.join(targetDir, "package.json");
 	const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+	const buildCommand = pkg.scripts.build;
 	pkg.scripts = {
 		...pkg.scripts,
+		// Keep project-owned Android XML authoritative for every build path:
+		// `bun run build`, `npm run build`, and android.mjs's package-manager
+		// invocation all execute this command before rspeedy starts.
+		build: "node scripts/android-prepare.mjs && " + buildCommand,
 		android: "node scripts/android.mjs",
 		"android:apk": "node scripts/android.mjs --apk",
 		"android:release": "node scripts/android.mjs --release",
 		"android:sync": "node scripts/android.mjs --sync-only",
+		"android:prepare": "node scripts/android-prepare.mjs",
 		"android:keystore": "node scripts/android.mjs --keystore",
 	};
 	fs.writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
@@ -670,9 +718,7 @@ function patchJsProject({ targetDir, android }) {
 		const existingBg = fs.existsSync(bgPath) ? fs.readFileSync(bgPath, "utf8") : "";
 		fs.writeFileSync(bgPath, `${buildFontBlock(android.fonts)}${existingBg}`);
 
-		const cssPath = path.join(targetDir, "src", "style.css");
-		const existingCss = fs.existsSync(cssPath) ? fs.readFileSync(cssPath, "utf8") : "";
-		fs.writeFileSync(cssPath, `${buildCssFontBlock(android.fonts[0].family)}${existingCss}`);
+		applyFontsCss(targetDir, android.fonts);
 	}
 
 	// README: how the two halves are used together.
@@ -688,6 +734,7 @@ function patchJsProject({ targetDir, android }) {
 			"npm run android          # build the bundle, copy it to assets, install and launch on the device",
 			"npm run android:apk      # build the debug APK only",
 			"npm run android:sync     # bundle -> assets only, no Gradle",
+			"bun run android:prepare  # android/*.xml -> sibling Android host",
 			"",
 			"# Signed release APK (generate the keystore once):",
 			"KEYSTORE_PASSWORD='...' npm run android:keystore",
@@ -696,6 +743,8 @@ function patchJsProject({ targetDir, android }) {
 			"",
 			`- Application ID: \`${android.androidId}\``,
 			`- Application class: \`${android.appClass}\` · Activity: \`MainActivity\``,
+			"- Android XML: edit `android/*.xml`; every `bun run build` synchronizes those files to the sibling host before bundling. Run `bun run android:prepare` when you only need the synchronization.",
+			"- Android system Back bridge: the host pre-registers `MithrilLynxNavigationModule`; connect a `mithril-lynx/route` app with `route.listenBackButton({ onCanGoBackChange: (value) => NativeModules.MithrilLynxNavigationModule?.setCanGoBack(value) })`. The Basic Activity template is already connected.",
 			...android.fonts.map(
 				(f) =>
 					`- Font \`${f.family}\` (\`src/assets/fonts/${f.file}\`): \`lynx.addFont()\` — DEV inlines a \`data:\` URI for Lynx Go; PROD uses \`asset:///fonts/${f.file}\` via \`AssetFontFaceLoader\` ([lynx#9431](https://github.com/lynx-family/lynx/issues/9431)).`,

package/templates/_shared/ts/src/rspeedy-env.d.ts

@@ -1,3 +1,12 @@
 /// <reference types="@lynx-js/rspeedy/client" />
 /// <reference types="@lynx-js/types" />
 /// <reference types="@lynx-js/type-element-api" />
+
+declare module "@lynx-js/types" {
+	interface NativeModules {
+		/** Android host bridge used by mithril-lynx/route.listenBackButton(). */
+		MithrilLynxNavigationModule?: {
+			setCanGoBack(canGoBack: boolean): void;
+		};
+	}
+}

package/templates/android/app-scripts/android-prepare.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+/**
+ * Copies the Android resources kept beside the JS source into the sibling
+ * Gradle host. Edit <project>/android/*.xml, then run:
+ *
+ *   bun run android:prepare
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const projectRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const sourceDir = path.join(projectRoot, "android");
+const androidDir = path.resolve(projectRoot, "{{ANDROID_REL_DIR}}");
+
+const files = [
+	["AndroidManifest.xml", ["app", "src", "main", "AndroidManifest.xml"]],
+	["strings.xml", ["app", "src", "main", "res", "values", "strings.xml"]],
+	["styles.xml", ["app", "src", "main", "res", "values", "styles.xml"]],
+	["config.xml", ["app", "src", "main", "res", "xml", "config.xml"]],
+	["network_security_config.xml", ["app", "src", "main", "res", "xml", "network_security_config.xml"]],
+	["file_paths.xml", ["app", "src", "main", "res", "xml", "file_paths.xml"]],
+];
+
+function fail(message) {
+	console.error(`\n  ✖ ${message}\n`);
+	process.exit(1);
+}
+
+if (!fs.existsSync(path.join(androidDir, "settings.gradle.kts"))) {
+	fail(`Can't find the Android host at ${androidDir}.`);
+}
+
+for (const [name, destination] of files) {
+	const source = path.join(sourceDir, name);
+	if (!fs.existsSync(source)) {
+		fail(`Missing ${path.relative(projectRoot, source)}. Restore it before preparing the Android host.`);
+	}
+	const target = path.join(androidDir, ...destination);
+	fs.mkdirSync(path.dirname(target), { recursive: true });
+	fs.copyFileSync(source, target);
+	console.log(`  → ${path.relative(projectRoot, target)}`);
+}
+
+console.log("\n  ✔ Android resources prepared.\n");

package/templates/android/host/app/src/main/AndroidManifest.xml

@@ -11,6 +11,7 @@
         android:roundIcon="@mipmap/ic_launcher_round"
         android:hardwareAccelerated="true"
         android:usesCleartextTraffic="true"
+        android:networkSecurityConfig="@xml/network_security_config"
         android:theme="@style/AppTheme">
 
         <activity

package/templates/android/host/app/src/main/java/package-path/MainActivity.kt

@@ -1,14 +1,18 @@
 package {{PACKAGE_NAME}}
 
 import android.os.Bundle
+import androidx.activity.OnBackPressedCallback
 import androidx.appcompat.app.AppCompatActivity
 import androidx.core.splashscreen.SplashScreen.Companion.installSplashScreen
+import com.lynx.react.bridge.JavaOnlyArray
 import com.lynx.tasm.LynxBooleanOption
 import com.lynx.tasm.LynxViewBuilder
 import com.lynx.tasm.ThreadStrategyForRendering
 import com.lynx.xelement.XElementBehaviors
 
 class MainActivity : AppCompatActivity() {
+    private var backCallback: OnBackPressedCallback? = null
+
     override fun onCreate(savedInstanceState: Bundle?) {
         // Must run BEFORE super.onCreate() — a Splash Screen API requirement.
         installSplashScreen()
@@ -20,6 +24,9 @@ class MainActivity : AppCompatActivity() {
         // keyboard. Remove this line (and the xelement dependencies) if you
         // don't use them.
         builder.addBehaviors(XElementBehaviors().create())
+        // Lets mithril-lynx/route tell Android when its in-memory history can
+        // handle Back. See MithrilLynxNavigationModule and the callback below.
+        builder.registerModule("MithrilLynxNavigationModule", MithrilLynxNavigationModule::class.java)
         // lynx-family/lynx's own explorer/android registers a
         // GenericResourceFetcher unconditionally (LynxViewShellActivity —
         // "used inside LynxEngine for resource loading capabilities of
@@ -37,9 +44,29 @@ class MainActivity : AppCompatActivity() {
         val lynxView = builder.build(this)
         setContentView(lynxView)
 
+        // Disabled until route.listenBackButton() reports that JS has an
+        // in-app history entry. When disabled, Android's normal Back behavior
+        // remains in charge and closes the activity from the first screen.
+        val callback = object : OnBackPressedCallback(false) {
+            override fun handleOnBackPressed() {
+                lynxView.sendGlobalEvent("mithrilLynx:back", JavaOnlyArray())
+            }
+        }
+        onBackPressedDispatcher.addCallback(this, callback)
+        backCallback = callback
+
         // The bundle lives in app/src/main/assets/main-thread.bundle, copied
         // there by `npm run android` (scripts/android.mjs) from the JS
         // project's dist/. The name has to match exactly.
         lynxView.renderTemplateUrl("main-thread.bundle", "")
     }
+
+    fun setCanGoBack(canGoBack: Boolean) {
+        backCallback?.isEnabled = canGoBack
+    }
+
+    override fun onDestroy() {
+        backCallback = null
+        super.onDestroy()
+    }
 }

package/templates/android/host/app/src/main/java/package-path/MithrilLynxNavigationModule.kt

@@ -0,0 +1,28 @@
+package {{PACKAGE_NAME}}
+
+import android.content.Context
+import android.os.Handler
+import android.os.Looper
+import com.lynx.jsbridge.LynxMethod
+import com.lynx.jsbridge.LynxModule
+import com.lynx.tasm.behavior.LynxContext
+
+/**
+ * JS -> Android half of mithril-lynx/route's system Back integration.
+ *
+ * MainActivity supplies the Android -> JS half with sendGlobalEvent(). Keeping
+ * the callback disabled when the route history is empty preserves Android's
+ * default behavior on the app's first screen, including predictive Back.
+ */
+class MithrilLynxNavigationModule(context: Context) : LynxModule(context) {
+    private val activity = (context as? LynxContext)?.activity as? MainActivity
+
+    @LynxMethod
+    fun setCanGoBack(canGoBack: Boolean) {
+        // Lynx invokes native modules from its JS thread; Android's callback
+        // belongs to the main thread.
+        Handler(Looper.getMainLooper()).post {
+            activity?.setCanGoBack(canGoBack)
+        }
+    }
+}

package/templates/android/host/app/src/main/res/xml/config.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+  Project-owned Android configuration entry point. Android does not consume a
+  generic config.xml by itself; use it for XML metadata that a manifest entry
+  or a native integration needs, keeping that configuration beside the other
+  editable Android files in <project>/android/.
+-->
+<config />

package/templates/android/host/app/src/main/res/xml/file_paths.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+  Ready for an androidx.core.content.FileProvider declaration in
+  AndroidManifest.xml when the app needs to share a file with another app.
+-->
+<paths>
+    <files-path name="files" path="." />
+    <cache-path name="cache" path="." />
+    <external-files-path name="external_files" path="." />
+</paths>

package/templates/android/host/app/src/main/res/xml/network_security_config.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+  The generated manifest references this resource. It deliberately matches the
+  previous host default (cleartext allowed) so existing local HTTP workflows do
+  not change. Restrict this before a production release when possible.
+-->
+<network-security-config>
+    <base-config cleartextTrafficPermitted="true" />
+</network-security-config>

package/templates/basic-activity/ts/src/app-bar.ts

@@ -1,10 +1,9 @@
 import m from "mithril-runtime";
 
 // A reusable app bar: a title, plus a back affordance when `onBack` is
-// given. No m.route.Link involved for the back button — see
-// mithril-lynx/route.js's README section on route.back(): Lynx has no
-// hardware back button, so a screen's own back affordance has to call
-// route.back() explicitly.
+// given. No m.route.Link involved for this on-screen affordance: it calls
+// route.back() explicitly. The generated Android host's system Back bridge
+// reaches the same history separately through route.listenBackButton().
 export function AppBar(title: string, onBack?: () => void) {
 	return m("view", { class: "AppBar" }, [
 		onBack != null ? m("text", { class: "AppBar-back", ontap: onBack }, "←") : null,

package/templates/basic-activity/ts/src/background.ts

@@ -21,6 +21,14 @@ route("/", {
 	"/detail": DetailHost,
 });
 
+// The host generated by --android forwards the system Back button through a
+// Lynx global event. The module is optional so this template still runs in
+// LynxExplorer, or when generated without its native Android host.
+route.listenBackButton({
+	onCanGoBackChange: (canGoBack) =>
+		NativeModules.MithrilLynxNavigationModule?.setCanGoBack(canGoBack),
+});
+
 declare const module: {
 	hot?: {
 		accept(path: string, callback: () => void): void;