create-mithril-lynx 2.2.0 → 2.4.0

package/README.md

@@ -49,8 +49,8 @@ Every flag, in one table — `npx create-mithril-lynx --help` prints the same li
 | `--android` / `--target android` / `--target=android` / `target=android` | Also scaffold the sibling `<name>-android/` Gradle project. |
 | `--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()`. No native code: the import is inlined as a `data:` URI (`dataUriLimit: Infinity` in `lynx.config.ts`), which resolves the same way on every host — the real APK, LynxExplorer, or Lynx Go. Confirmed on device: no cold-start cost either (~730ms with the font vs. ~770ms without, on the same device). 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. |
+| `--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 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`
@@ -65,18 +65,41 @@ monospace one for code, for example:
 npx create-mithril-lynx my-app --blank --android --find-font "Inter,JetBrains Mono"
 ```
 
-Each font gets its own `import`/`lynx.addFont()` call in `src/background.ts`.
-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.:
+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).
+
+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
+cd my-app
+npx create-mithril-lynx add-font --with-font ./Another.ttf
+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. `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
 
 Fontsource's own API (`api.fontsource.org`) has no free-text search — only
@@ -84,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
 ```
@@ -99,7 +124,7 @@ 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`, `MainActivity` (async `AssetTemplateProvider`, splash screen) — no font-specific code needed, `--with-font` is entirely JS-side;
+- 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);
 - an opt-in release signing setup driven by a gitignored `keystore.properties`.
 
@@ -127,8 +152,9 @@ This part of the tool is framework-agnostic — it just wraps whatever bundle `r
 
 ```
 create-mithril-lynx/
-  src/index.js              the CLI itself
+  src/index.js              the CLI itself (+ add-font subcommand)
   src/fontsource.js         --find-font: local search over Fontsource's catalog
+  src/fonts-wire.js         FONTS block builder + stock-template detect/patch
   templates/
     _shared/
       common/                gitignore, project README — shared by every template
@@ -146,12 +172,15 @@ 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/)
 ```
 
 `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`, the font itself is copied into the *JS* project (`src/assets/fonts/`) and wired up with `lynx.addFont()` in `src/background.ts` plus a `text { font-family: ... }` rule in `src/style.css` — the Android host needs no font-specific code at all (see the `--with-font` row above).
+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 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.2.0",
+  "version": "2.4.0",
   "description": "Scaffolds a new mithril-lynx app (and, optionally, its Android host).",
   "license": "MIT",
   "type": "module",

package/src/fonts-wire.js

@@ -0,0 +1,318 @@
+/**
+ * Font registration wiring shared by scaffold (`--with-font` / `--find-font`)
+ * and the post-init `add-font` subcommand.
+ *
+ * Strategy for patching an existing project (add-font):
+ *   1. Always copy .ttf/.otf/.ttc into src/assets/fonts/ (and the Android
+ *      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. 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";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.join(scriptDir, "..");
+
+const FONT_EXT = /\.(ttf|otf|ttc)$/i;
+
+/** Normalize for equality checks (EOL + trailing whitespace per line). */
+export function normalizeSource(text) {
+	return (
+		text
+			.replace(/\r\n/g, "\n")
+			.split("\n")
+			.map((line) => line.replace(/\s+$/u, ""))
+			.join("\n")
+			.replace(/\n+$/u, "") + "\n"
+	);
+}
+
+export function buildFontBlock(fonts) {
+	const defaultFamily = fonts[0].family;
+	const requireEntries = fonts
+		.map(
+			({ family, file }) =>
+				`\t\t{ family: "${family}", file: "${file}", url: require("./assets/fonts/${file}") },`,
+		)
+		.join("\n");
+	const assetEntries = fonts
+		.map(
+			({ family, file }) =>
+				`\t\t{ family: "${family}", file: "${file}", url: "asset:///fonts/${file}" },`,
+		)
+		.join("\n");
+
+	return [
+		fonts.length === 1
+			? `// Font: "${defaultFamily}", from src/assets/fonts/${fonts[0].file}.`
+			: `// Fonts: ${fonts.map((f) => `"${f.family}"`).join(", ")}, from src/assets/fonts/.`,
+		"// Registered in a loop via lynx.addFont(). Split by build mode:",
+		"//   • 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).",
+		"// 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? [",
+		requireEntries,
+		"\t  ]",
+		"\t: [",
+		assetEntries,
+		"\t  ];",
+		"for (const { family, url } of FONTS) {",
+		'\tlynx.addFont({ "font-family": family, src: `url("${url}")` }, () => {});',
+		"}",
+		"",
+		"",
+	].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). */
+const FONT_BLOCK_RE =
+	/^(?:\/\/ Font[^\n]*\n)(?:\/\/[^\n]*\n)*type FontEntry = \{ family: string; file: string; url: string \};\nconst FONTS: FontEntry\[\] = import\.meta\.env\.DEV\n\t\? \[[\s\S]*?\t  \]\n\t: \[[\s\S]*?\t  \];\nfor \(const \{ family, url \} of FONTS\) \{\n\tlynx\.addFont\(\{ "font-family": family, src: `url\("\$\{url\}"\)` \}, \(\) => \{\}\);\n\}\n\n/;
+
+const CSS_FONT_RE = /^text \{\n  font-family: "[^"]+", sans-serif;\n\}\n\n?/;
+
+export function stripFontBlock(backgroundSource) {
+	const normalized = normalizeSource(backgroundSource);
+	const match = normalized.match(FONT_BLOCK_RE);
+	if (!match) return { block: null, rest: normalized, fonts: [] };
+	return {
+		block: match[0],
+		rest: normalized.slice(match[0].length),
+		fonts: parseFontsFromBlock(match[0]),
+	};
+}
+
+export function parseFontsFromBlock(block) {
+	const fonts = [];
+	const seen = new Set();
+	for (const match of block.matchAll(/\{\s*family:\s*"([^"]+)",\s*file:\s*"([^"]+)"/g)) {
+		const [, family, file] = match;
+		if (seen.has(file)) continue;
+		seen.add(file);
+		fonts.push({ family, file });
+	}
+	return fonts;
+}
+
+export function stripCssFontBlock(cssSource) {
+	const normalized = normalizeSource(cssSource);
+	const match = normalized.match(CSS_FONT_RE);
+	if (!match) return { block: null, rest: normalized, family: null };
+	const familyMatch = match[0].match(/font-family: "([^"]+)"/);
+	return {
+		block: match[0],
+		rest: normalized.slice(match[0].length),
+		family: familyMatch ? familyMatch[1] : null,
+	};
+}
+
+function loadBaseBackgrounds() {
+	return [
+		normalizeSource(fs.readFileSync(path.join(packageRoot, "templates/_shared/ts/src/background.ts"), "utf8")),
+		normalizeSource(
+			fs.readFileSync(path.join(packageRoot, "templates/basic-activity/ts/src/background.ts"), "utf8"),
+		),
+	];
+}
+
+export function isStockBackground(restSource) {
+	const normalized = normalizeSource(restSource);
+	return loadBaseBackgrounds().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 / fonts.css.
+ */
+export function copyFontFiles({ projectRoot, fonts, androidDir = null }) {
+	const jsFontsDir = path.join(projectRoot, "src", "assets", "fonts");
+	fs.mkdirSync(jsFontsDir, { recursive: true });
+	const copied = [];
+
+	for (const font of fonts) {
+		const dest = path.join(jsFontsDir, font.file);
+		fs.copyFileSync(font.sourcePath, dest);
+		copied.push({ role: "js", path: dest });
+	}
+
+	if (androidDir != null) {
+		const androidFontsDir = path.join(androidDir, "app", "src", "main", "assets", "fonts");
+		fs.mkdirSync(androidFontsDir, { recursive: true });
+		for (const font of fonts) {
+			const dest = path.join(androidFontsDir, font.file);
+			fs.copyFileSync(font.sourcePath, dest);
+			copied.push({ role: "android", path: dest });
+		}
+	}
+
+	return copied;
+}
+
+/**
+ * Merge newly requested fonts with ones already registered in background.ts
+ * (or already sitting in src/assets/fonts/). `dedupeFontFiles` mutates `.file`.
+ */
+export function mergeFontLists(existing, incoming, dedupeFontFiles) {
+	const merged = [];
+	const byFile = new Set();
+	for (const font of existing) {
+		if (byFile.has(font.file)) continue;
+		byFile.add(font.file);
+		merged.push({ ...font });
+	}
+	for (const font of incoming) {
+		merged.push({
+			sourcePath: font.sourcePath,
+			file: font.file,
+			family: font.family,
+		});
+	}
+	dedupeFontFiles(merged);
+	return merged;
+}
+
+/**
+ * Try to rewrite background.ts. Returns { ok, reason?, manualBlock? }.
+ */
+export function applyBackgroundFonts(projectRoot, fonts) {
+	const bgPath = path.join(projectRoot, "src", "background.ts");
+	if (!fs.existsSync(bgPath)) {
+		return {
+			ok: false,
+			reason: "src/background.ts not found",
+			manualBlock: buildFontBlock(fonts),
+		};
+	}
+	const raw = fs.readFileSync(bgPath, "utf8");
+	const { rest } = stripFontBlock(raw);
+	if (!isStockBackground(rest)) {
+		return {
+			ok: false,
+			reason: "src/background.ts no longer matches the stock template",
+			manualBlock: buildFontBlock(fonts),
+		};
+	}
+	fs.writeFileSync(bgPath, `${buildFontBlock(fonts)}${rest}`);
+	return { ok: true };
+}
+
+/**
+ * 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 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: `${FONTS_CSS_IMPORT}\n` };
+	}
+	const raw = fs.readFileSync(cssPath, "utf8");
+	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 };
+	}
+	// @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 };
+}
+
+/** Resolve sibling Android host: scripts/android.mjs ANDROID_DIR, or <name>-android/. */
+export function findAndroidDir(projectRoot) {
+	const scriptPath = path.join(projectRoot, "scripts", "android.mjs");
+	if (fs.existsSync(scriptPath)) {
+		const src = fs.readFileSync(scriptPath, "utf8");
+		const match = src.match(/path\.resolve\(projectRoot,\s*"([^"]+)"\)/);
+		if (match) {
+			const resolved = path.resolve(projectRoot, match[1]);
+			if (fs.existsSync(path.join(resolved, "settings.gradle.kts"))) return resolved;
+		}
+	}
+	const parent = path.dirname(projectRoot);
+	const guess = path.join(parent, `${path.basename(projectRoot)}-android`);
+	if (fs.existsSync(path.join(guess, "settings.gradle.kts"))) return guess;
+	return null;
+}
+
+/** Walk up from cwd looking for a mithril-lynx app (lynx.config.ts + src/). */
+export function findProjectRoot(startDir) {
+	let dir = path.resolve(startDir);
+	for (;;) {
+		if (
+			fs.existsSync(path.join(dir, "lynx.config.ts")) &&
+			fs.existsSync(path.join(dir, "src", "background.ts"))
+		) {
+			return dir;
+		}
+		const parent = path.dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}
+
+export function listFontsOnDisk(projectRoot) {
+	const fontsDir = path.join(projectRoot, "src", "assets", "fonts");
+	if (!fs.existsSync(fontsDir)) return [];
+	return fs
+		.readdirSync(fontsDir)
+		.filter((name) => FONT_EXT.test(name))
+		.map((file) => ({
+			file,
+			family: file
+				.replace(FONT_EXT, "")
+				.split(/[_\-.]+/)
+				.filter(Boolean)
+				.map((word) => word[0].toUpperCase() + word.slice(1))
+				.join(" "),
+			sourcePath: path.join(fontsDir, file),
+		}));
+}
+
+export { FONT_EXT };

package/src/index.js

@@ -5,9 +5,20 @@ 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,
+	applyFontsCss,
+	buildFontBlock,
+	cssClassName,
+	copyFontFiles,
+	findAndroidDir,
+	findProjectRoot,
+	mergeFontLists,
+	stripFontBlock,
+} from "./fonts-wire.js";
 
 const scriptDir = path.dirname(fileURLToPath(import.meta.url));
 const packageRoot = path.join(scriptDir, "..");
@@ -162,16 +173,6 @@ function dedupeFontFiles(fonts) {
 	}
 }
 
-/** A valid JS identifier (camelCase, "Font" suffix) for a font-family string. */
-function jsIdentifierFor(family) {
-	const words = family.split(/[^a-zA-Z0-9]+/).filter(Boolean);
-	const camel = words
-		.map((word, i) => (i === 0 ? word[0].toLowerCase() + word.slice(1) : word[0].toUpperCase() + word.slice(1)))
-		.join("");
-	const safe = /^[0-9]/.test(camel) ? `f${camel}` : camel;
-	return `${safe || "font"}Font`;
-}
-
 function xmlEscape(value) {
 	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
 }
@@ -254,6 +255,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" : "";
@@ -263,8 +270,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.
  */
@@ -321,33 +328,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;
 }
 
 // ---------------------------------------------------------------------------
@@ -393,38 +412,67 @@ async function resolveAndroidOptions(android, { rawName, projectName, canPrompt
 	}
 	appName = appName ?? path.basename(rawName);
 
+	const fonts = await resolveFontsFromFlags(android, { baseDir: cwd, requireFonts: false });
+	if (fonts == null) return null;
+
+	return { androidId, appName, fonts };
+}
+
+/**
+ * Shared by scaffold and `add-font`: resolve --with-font / --find-font /
+ * --font-family into `{ sourcePath, file, family }[]`. Returns null if the
+ * interactive --find-font flow was cancelled; exits on hard errors.
+ * When `requireFonts` is false (scaffold without --with-font), returns [].
+ */
+async function resolveFontsFromFlags(android, { baseDir, requireFonts }) {
 	if (android.fontPath != null && android.findFontTerm != null) {
 		cancel("--with-font and --find-font are mutually exclusive — pick one.");
 		process.exit(1);
 	}
 
-	// Both flags accept a comma-separated list, so more than one font (e.g.
-	// a body font and a monospace one for code) can be bundled in one run.
 	const fontPaths = android.fontPath != null ? splitList(android.fontPath) : [];
 	const findFontTerms = android.findFontTerm != null ? splitList(android.findFontTerm) : [];
 	const fontCount = fontPaths.length + findFontTerms.length;
 
 	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.");
+		cancel(
+			"--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);
 	}
 	if (android.fontFamily != null && fontCount === 0) {
 		cancel("--font-family only makes sense together with --with-font or --find-font.");
 		process.exit(1);
 	}
+	if (fontCount === 0) {
+		if (requireFonts) {
+			cancel("Pass --with-font <file.ttf> or --find-font <term> (comma-separate for more than one).");
+			process.exit(1);
+		}
+		return [];
+	}
 
 	const fonts = [];
 	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(cwd, rawPath);
+		const resolved = path.resolve(baseDir, rawPath);
 		if (!fs.existsSync(resolved)) {
 			cancel(`Font file not found: ${rawPath}`);
 			process.exit(1);
@@ -440,8 +488,99 @@ async function resolveAndroidOptions(android, { rawName, projectName, canPrompt
 		});
 	}
 	dedupeFontFiles(fonts);
+	return fonts;
+}
 
-	return { androidId, appName, fonts };
+function printManualBlock(title, block) {
+	console.log("");
+	console.log(`  ${title}`);
+	console.log("  ────────────────────────────────────────");
+	for (const line of block.replace(/\n$/, "").split("\n")) {
+		console.log(`  ${line}`);
+	}
+	console.log("  ────────────────────────────────────────");
+	console.log("");
+}
+
+/**
+ * Post-init: add one or more fonts to an existing mithril-lynx project.
+ * Always copies the files; patches background.ts / style.css only when they
+ * still match the stock template (optionally with our FONTS block on top).
+ */
+async function runAddFont(args) {
+	intro("create-mithril-lynx add-font");
+
+	const android = parseAndroidArgs(args);
+	if (android.fontPath == null && android.findFontTerm == null) {
+		cancel("Pass --with-font <file.ttf> or --find-font <term>.");
+		process.exit(1);
+	}
+
+	const projectRoot = findProjectRoot(cwd);
+	if (projectRoot == null) {
+		cancel(
+			"No mithril-lynx project found here (need lynx.config.ts + src/background.ts).\n" +
+				"    cd into the app directory and try again.",
+		);
+		process.exit(1);
+	}
+
+	const incoming = await resolveFontsFromFlags(android, { baseDir: cwd, requireFonts: true });
+	if (incoming == null) return;
+
+	const bgPath = path.join(projectRoot, "src", "background.ts");
+	const { fonts: existingInBg } = stripFontBlock(
+		fs.existsSync(bgPath) ? fs.readFileSync(bgPath, "utf8") : "",
+	);
+	const merged = mergeFontLists(existingInBg, incoming, dedupeFontFiles);
+
+	const androidDir = findAndroidDir(projectRoot);
+	const copied = copyFontFiles({
+		projectRoot,
+		fonts: incoming,
+		androidDir,
+	});
+
+	for (const item of copied) {
+		const rel = path.relative(cwd, item.path);
+		console.log(`  → ${rel}${item.role === "android" ? " (android host)" : ""}`);
+	}
+	if (androidDir == null) {
+		console.log(
+			"  ℹ No Android host found next to this app — fonts were only copied into src/assets/fonts/.\n" +
+				"    (PROD asset:/// registration needs the host's AssetFontFaceLoader.)",
+		);
+	}
+
+	const bgResult = applyBackgroundFonts(projectRoot, merged);
+	if (bgResult.ok) {
+		console.log("  ✔ Updated src/background.ts");
+	} else {
+		console.log(`  ✖ Could not auto-edit src/background.ts (${bgResult.reason}).`);
+		console.log("    Paste this block at the top of src/background.ts:");
+		printManualBlock("src/background.ts", bgResult.manualBlock);
+	}
+
+	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);
+	}
+
+	if (merged.length > 1) {
+		console.log(
+			`  · Use the classes in src/fonts.css: ${merged.map((f) => "." + cssClassName(f.family)).join(", ")}`,
+		);
+	}
+
+	outro(
+		`Done. Font${merged.length > 1 ? "s" : ""} ${merged.map((f) => `"${f.family}"`).join(", ")} ` +
+			(bgResult.ok ? "registered." : "copied — finish registration with the lines above."),
+	);
 }
 
 function scaffoldAndroid({ targetDir, rawName, options }) {
@@ -470,15 +609,11 @@ function scaffoldAndroid({ targetDir, rawName, options }) {
 		// best-effort
 	}
 
-	// 2. Fonts need no native code at all: lynx.config.ts's dataUriLimit:
-	//    Infinity (see templates/_shared/ts/lynx.config.ts) already inlines
-	//    any imported .ttf as a data: URI, and lynx.addFont() resolves a
-	//    data: URI on every host with no registration — confirmed on device
-	//    (a stock generated Android host, with no custom Loader/fetcher of
-	//    any kind, renders the font correctly) and with no cold-start cost
-	//    (three-run A/B on the same device: 724-745ms with the font vs.
-	//    715-826ms without — indistinguishable). See patchJsProject() for
-	//    where the font actually gets wired up (entirely JS-side).
+	// 2. Fonts: the host always ships AssetFontFaceLoader +
+	//    NoopGenericResourceFetcher (lynx#9431 workaround). Production
+	//    bundles register fonts as asset:///fonts/<file>; Lynx Go / dev
+	//    uses inlined data: URIs. See patchJsProject() for the JS wiring
+	//    and templates/android/host/.../NoopGenericResourceFetcher.kt.
 	const sdkDir = findAndroidSdk();
 
 	// 3. Text substitutions across the whole Android host (skipping the
@@ -496,7 +631,17 @@ function scaffoldAndroid({ targetDir, rawName, options }) {
 		],
 	]);
 
-	// 4. The script that joins the two halves, inside the JS project.
+	// 4. Seed assets/fonts/ so the first APK build works even before
+	//    scripts/android.mjs syncs (it also keeps them in sync later).
+	if (fonts.length > 0) {
+		const androidFontsDir = path.join(androidDir, "app", "src", "main", "assets", "fonts");
+		fs.mkdirSync(androidFontsDir, { recursive: true });
+		for (const { sourcePath, file } of fonts) {
+			fs.copyFileSync(sourcePath, path.join(androidFontsDir, file));
+		}
+	}
+
+	// 5. The script that joins 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"));
@@ -527,76 +672,20 @@ function patchJsProject({ targetDir, android }) {
 	};
 	fs.writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
 
-	// The font: entirely JS-side, no native code, no @font-face.
-	//
-	// - The .ttf goes into the JS project itself (src/assets/fonts/), so the
-	//   bundler can import it. templates/_shared/ts/lynx.config.ts already
-	//   sets `dataUriLimit: Infinity`, which inlines that import as a
-	//   `data:font/ttf;base64,...` URI directly in the bundle — no separate
-	//   file, no asset-path puzzle to solve for a packaged native host.
-	// - lynx.addFont() (not @font-face) registers it, called from
-	//   background.ts. A data: URI resolves the same way on every host —
-	//   confirmed on a real device with a stock generated Android host (no
-	//   AssetFontFaceLoader, no custom resource fetcher) and with LynxExplorer/
-	//   Lynx Go, with no cold-start cost (a three-run A/B on the same device
-	//   measured 724-745ms with the font vs. 715-826ms without —
-	//   indistinguishable; the old +1-2s regression was specific to
-	//   @font-face's forced synchronous resolution, which doesn't apply here).
+	// Fonts: copy + register via lynx.addFont() loop (DEV data: / PROD
+	// asset:///) — see src/fonts-wire.js and the Android host's
+	// AssetFontFaceLoader / NoopGenericResourceFetcher (lynx#9431).
 	if (android.fonts.length > 0) {
-		const fontsDir = path.join(targetDir, "src", "assets", "fonts");
-		fs.mkdirSync(fontsDir, { recursive: true });
-
-		const usedVarNames = new Set();
-		const importLines = [];
-		const addFontLines = [];
-		for (const { family, sourcePath, file } of android.fonts) {
-			fs.copyFileSync(sourcePath, path.join(fontsDir, file));
-
-			let varName = jsIdentifierFor(family);
-			while (usedVarNames.has(varName)) varName = `${varName}2`;
-			usedVarNames.add(varName);
-
-			importLines.push(`import ${varName} from "./assets/fonts/${file}";`);
-			addFontLines.push(
-				`lynx.addFont({ "font-family": "${family}", src: \`url("\${${varName}}")\` }, () => {});`,
-			);
-		}
-
-		// Only the first font gets an automatic CSS rule (the app-wide
-		// default, matching --with-font's single-font behavior exactly) —
-		// with more than one, there's no way to guess which elements should
-		// use which, so the rest are just registered via lynx.addFont() and
-		// left for you to assign in your own CSS classes.
-		const defaultFamily = android.fonts[0].family;
-		const extraFamilies = android.fonts.slice(1).map((f) => f.family);
-
+		copyFontFiles({
+			projectRoot: targetDir,
+			fonts: android.fonts,
+			androidDir: android.androidDir,
+		});
 		const bgPath = path.join(targetDir, "src", "background.ts");
-		const fontBlock = [
-			android.fonts.length === 1
-				? `// Font: "${defaultFamily}", bundled from src/assets/fonts/${android.fonts[0].file}. lynx.addFont()`
-				: `// Fonts: ${android.fonts.map((f) => `"${f.family}"`).join(", ")}, bundled from src/assets/fonts/. lynx.addFont()`,
-			"// registers each directly — dataUriLimit: Infinity (lynx.config.ts) inlines",
-			"// every import as a data: URI, which resolves the same way on every host,",
-			"// no native code needed.",
-			...(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] + "\"; }`.",
-					]
-				: []),
-			...importLines,
-			...addFontLines,
-			"",
-			"",
-		].join("\n");
 		const existingBg = fs.existsSync(bgPath) ? fs.readFileSync(bgPath, "utf8") : "";
-		fs.writeFileSync(bgPath, `${fontBlock}${existingBg}`);
+		fs.writeFileSync(bgPath, `${buildFontBlock(android.fonts)}${existingBg}`);
 
-		const cssPath = path.join(targetDir, "src", "style.css");
-		const cssBlock = [`text {`, `  font-family: "${defaultFamily}", sans-serif;`, `}`, ""].join("\n");
-		const existingCss = fs.existsSync(cssPath) ? fs.readFileSync(cssPath, "utf8") : "";
-		fs.writeFileSync(cssPath, `${cssBlock}\n${existingCss}`);
+		applyFontsCss(targetDir, android.fonts);
 	}
 
 	// README: how the two halves are used together.
@@ -622,7 +711,7 @@ function patchJsProject({ targetDir, android }) {
 			`- Application class: \`${android.appClass}\` · Activity: \`MainActivity\``,
 			...android.fonts.map(
 				(f) =>
-					`- Font \`${f.family}\` loaded via \`lynx.addFont()\` from \`src/assets/fonts/${f.file}\` (bundled as a data: URI — no native code involved).`,
+					`- 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)).`,
 			),
 			"",
 		].join("\n");
@@ -638,6 +727,8 @@ create-mithril-lynx — scaffold a mithril-lynx app (and, optionally, its Androi
 Usage:
   npm create mithril-lynx@latest [name] [options]
   npx create-mithril-lynx <name> --blank --android
+  npx create-mithril-lynx add-font --with-font ./Foo.ttf
+  npx create-mithril-lynx add-font --find-font Inter
 
 Template (prompted for if omitted):
   --hello-world | --blank | --basic-activity
@@ -648,9 +739,10 @@ Android host:
   --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 the JS project and register it
-                            with lynx.addFont() (works on every host, no native
-                            code — see README). Comma-separate for more than
-                            one, e.g. --with-font a.ttf,b.ttf
+                            with lynx.addFont() (DEV: data: URI for Lynx Go;
+                            PROD: asset:/// + AssetFontFaceLoader — see README).
+                            Comma-separate for more than one,
+                            e.g. --with-font a.ttf,b.ttf
   --find-font <term>        search Fontsource (fontsource.org) for a font,
                             pick a family and a weight/style interactively,
                             and bundle it the same way as --with-font.
@@ -660,6 +752,15 @@ Android host:
   --font-family <name>      override the family name derived from the file
                             name (only valid with exactly one font)
 
+Post-init (run inside an existing app directory):
+  add-font                  copy font file(s) into src/assets/fonts/ (and the
+                            Android host's assets/fonts/ when present). If
+                            background.ts / style.css still match the stock
+                            template, wire them up automatically; otherwise
+                            print the lines to paste by hand.
+                            Same --with-font / --find-font / --font-family
+                            flags as above.
+
 Other:
   --no-install              don't install dependencies
   -h, --help                print this
@@ -671,6 +772,7 @@ async function main() {
 	//   create-mithril-lynx my-app --basic-activity --no-install
 	//   create-mithril-lynx my-app --blank --android --android-id com.acme.miapp
 	//   create-mithril-lynx my-app --blank --with-font ./UbuntuMono-Regular.ttf
+	//   create-mithril-lynx add-font --with-font ./Extra.ttf
 	const args = process.argv.slice(2);
 
 	if (args.includes("--help") || args.includes("-h")) {
@@ -678,6 +780,11 @@ async function main() {
 		return;
 	}
 
+	if (args[0] === "add-font") {
+		await runAddFont(args.slice(1));
+		return;
+	}
+
 	const positional = findPositional(args);
 	const templateFlag = TEMPLATE_VALUES.find((t) => args.includes(`--${t}`));
 	const noInstall = args.includes("--no-install");
@@ -810,7 +917,7 @@ async function main() {
 					`${androidDirName}/local.properties (sdk.dir=...).`
 				: `Android SDK found at ${sdkDir}.`,
 			fonts.length > 0
-				? `Font${fonts.length > 1 ? "s" : ""} ${fonts.map((f) => `"${f.family}"`).join(", ")} bundled and registered via lynx.addFont() — works on every host.`
+				? `Font${fonts.length > 1 ? "s" : ""} ${fonts.map((f) => `"${f.family}"`).join(", ")} registered via lynx.addFont() — Lynx Go (data:) and the APK (asset:///) both covered.`
 				: "No custom font — pass --with-font <file.ttf> (or --find-font <term>) to bundle one.",
 		];
 		outro(`Done! Next steps:\n\n  ${steps.join("\n  ")}\n\n${notes.join("\n")}`);

package/templates/_shared/ts/src/background.ts

@@ -25,7 +25,11 @@ declare const module: {
 		accept(path: string, callback: () => void): void;
 	};
 };
-declare const require: (id: string) => typeof indexModule;
+// Overloads: HMR reloads index.js; DEV font registration (prepended by
+// create-mithril-lynx when --with-font/--find-font is used) requires .ttf
+// paths as string URLs.
+declare function require(id: "./index.js"): typeof indexModule;
+declare function require(id: string): string;
 
 if (module.hot) {
 	module.hot.accept("./index.js", () => {

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

@@ -34,6 +34,13 @@ const BUNDLE_NAME = "main-thread.bundle";
 const BUNDLE_SRC = path.join(projectRoot, "dist", BUNDLE_NAME);
 const BUNDLE_DEST = path.join(ANDROID_DIR, "app", "src", "main", "assets", BUNDLE_NAME);
 
+// Custom fonts (src/assets/fonts/*.ttf) — production bundles resolve them via
+// asset:///fonts/<file> (AssetFontFaceLoader in the Android host). Keep the
+// host's assets/fonts/ in sync with the JS project on every android sync.
+const FONTS_SRC = path.join(projectRoot, "src", "assets", "fonts");
+const FONTS_DEST = path.join(ANDROID_DIR, "app", "src", "main", "assets", "fonts");
+const FONT_EXT = /\.(ttf|otf|ttc)$/i;
+
 const USAGE = `
 Usage: npm run android -- [flags] [-- gradle-args]
 
@@ -97,6 +104,19 @@ function requireAndroidDir() {
 	}
 }
 
+function syncFonts() {
+	if (!fs.existsSync(FONTS_SRC)) return;
+	const files = fs.readdirSync(FONTS_SRC).filter((name) => FONT_EXT.test(name));
+	if (files.length === 0) return;
+	fs.mkdirSync(FONTS_DEST, { recursive: true });
+	for (const name of files) {
+		const dest = path.join(FONTS_DEST, name);
+		fs.copyFileSync(path.join(FONTS_SRC, name), dest);
+		const kb = (fs.statSync(dest).size / 1024).toFixed(1);
+		console.log(`  → ${path.relative(projectRoot, dest)} (${kb} kB)`);
+	}
+}
+
 function syncBundle() {
 	if (!fs.existsSync(BUNDLE_SRC)) {
 		fail(`${path.relative(projectRoot, BUNDLE_SRC)} doesn't exist. Run "npm run build" first (or drop --no-build).`);
@@ -106,6 +126,7 @@ function syncBundle() {
 	fs.copyFileSync(BUNDLE_SRC, BUNDLE_DEST);
 	const kb = (fs.statSync(BUNDLE_DEST).size / 1024).toFixed(1);
 	console.log(`  → ${path.relative(projectRoot, BUNDLE_DEST)} (${kb} kB)`);
+	syncFonts();
 }
 
 function generateKeystore() {

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

@@ -3,6 +3,7 @@ package {{PACKAGE_NAME}}
 import android.app.Application
 import com.lynx.service.log.LynxLogService
 import com.lynx.tasm.LynxEnv
+import com.lynx.tasm.loader.LynxFontFaceLoader
 import com.lynx.tasm.service.LynxServiceCenter
 
 class {{APP_CLASS}} : Application() {
@@ -16,6 +17,12 @@ class {{APP_CLASS}} : Application() {
         LynxServiceCenter.inst().registerService(LynxLogService)
         LynxLogService.switchLogToSystem(true)
 
+        // Lets FontFaceManager resolve "asset:///" (production fonts under
+        // assets/fonts/) — see AssetFontFaceLoader. Pairs with
+        // NoopGenericResourceFetcher in MainActivity for the fast @font-face
+        // path (https://github.com/lynx-family/lynx/issues/9431).
+        LynxFontFaceLoader.setLoader(AssetFontFaceLoader)
+
         LynxEnv.inst().init(this, null, null, null)
     }
 }

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

@@ -0,0 +1,34 @@
+package {{PACKAGE_NAME}}
+
+import android.graphics.Typeface
+import com.lynx.tasm.behavior.LynxContext
+import com.lynx.tasm.fontface.FontFace
+import com.lynx.tasm.loader.LynxFontFaceLoader
+
+// Public Lynx extension point (com.lynx.tasm.loader.LynxFontFaceLoader, in the
+// core `lynx` artifact) for resolving custom @font-face / addFont src schemes.
+// Without a registered Loader, Lynx's default never resolves "asset:///" —
+// FontFaceManager only handles asset:/// inline when a "FONT"
+// LynxResourceProvider is registered (we don't), and prefetchFont()'s
+// non-http/non-data: branch goes ONLY through this Loader.
+//
+// Production builds register fonts as asset:///fonts/<file> (see the generated
+// background.ts) so the APK stays small and cold-start stays fast; Lynx Go /
+// `rspeedy dev` still uses inlined data: URIs via NoopGenericResourceFetcher.
+// See https://github.com/lynx-family/lynx/issues/9431
+object AssetFontFaceLoader : LynxFontFaceLoader.Loader() {
+    private const val ASSET_PREFIX = "asset:///"
+
+    override fun onLoadFontFace(
+        context: LynxContext,
+        type: FontFace.TYPE,
+        src: String,
+    ): Typeface? {
+        if (!src.startsWith(ASSET_PREFIX)) return null
+        return try {
+            Typeface.createFromAsset(context.context.assets, src.removePrefix(ASSET_PREFIX))
+        } catch (e: Exception) {
+            null
+        }
+    }
+}

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

@@ -3,6 +3,7 @@ package {{PACKAGE_NAME}}
 import android.os.Bundle
 import androidx.appcompat.app.AppCompatActivity
 import androidx.core.splashscreen.SplashScreen.Companion.installSplashScreen
+import com.lynx.tasm.LynxBooleanOption
 import com.lynx.tasm.LynxViewBuilder
 import com.lynx.tasm.ThreadStrategyForRendering
 import com.lynx.xelement.XElementBehaviors
@@ -19,6 +20,15 @@ class MainActivity : AppCompatActivity() {
         // keyboard. Remove this line (and the xelement dependencies) if you
         // don't use them.
         builder.addBehaviors(XElementBehaviors().create())
+        // lynx-family/lynx's own explorer/android registers a
+        // GenericResourceFetcher unconditionally (LynxViewShellActivity —
+        // "used inside LynxEngine for resource loading capabilities of
+        // components such as Text"). Without one, @font-face / addFont
+        // data: URIs fall back to a ~1.4-1.5s legacy path — see
+        // NoopGenericResourceFetcher and
+        // https://github.com/lynx-family/lynx/issues/9431
+        builder.setEnableGenericResourceFetcher(LynxBooleanOption.TRUE)
+        builder.setGenericResourceFetcher(NoopGenericResourceFetcher())
         builder.setThreadStrategyForRendering(ThreadStrategyForRendering.ALL_ON_UI)
         // Reads the bundle from assets on a separate thread — see
         // AssetTemplateProvider's comment: reading it synchronously here cost

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

@@ -0,0 +1,47 @@
+package {{PACKAGE_NAME}}
+
+import android.util.Base64
+import com.lynx.tasm.resourceprovider.LynxResourceCallback
+import com.lynx.tasm.resourceprovider.LynxResourceRequest
+import com.lynx.tasm.resourceprovider.LynxResourceResponse
+import com.lynx.tasm.resourceprovider.generic.LynxGenericResourceFetcher
+
+/**
+ * Decodes `data:` URIs for @font-face / lynx.addFont() src resolution —
+ * nothing else (this host never fetches real remote resources this way).
+ *
+ * Root cause of the ~1.4-1.5s cold-start cost custom fonts added, found by
+ * diffing LynxExplorer's logcat while it loaded a @font-face-heavy bundle
+ * fast (2026-09-10): it logs `FontFaceManager: Try to loadTypeface with
+ * GenericLynxResourceFetcher` → success in ~13ms. @font-face src resolution
+ * — even for a `data:` URI — routes through
+ * LynxGenericResourceFetcher.fetchResource(); WITHOUT one registered, that
+ * fast path fails and the engine falls back to a much slower legacy
+ * font-loading path (~1.4-1.5s fixed cost).
+ *
+ * Tracked upstream: https://github.com/lynx-family/lynx/issues/9431
+ */
+class NoopGenericResourceFetcher : LynxGenericResourceFetcher() {
+    @Suppress("UNCHECKED_CAST")
+    override fun fetchResource(request: LynxResourceRequest, callback: LynxResourceCallback<ByteArray>) {
+        val url = request.url
+        val commaIndex = url.indexOf(',')
+        if (url.startsWith("data:") && commaIndex != -1) {
+            try {
+                val bytes = Base64.decode(url.substring(commaIndex + 1), Base64.DEFAULT)
+                callback.onResponse(LynxResourceResponse.onSuccess(bytes))
+                return
+            } catch (e: IllegalArgumentException) {
+                // fall through to failure below
+            }
+        }
+        val response = LynxResourceResponse.onFailed(Throwable("not supported: $url")) as LynxResourceResponse<ByteArray>
+        callback.onResponse(response)
+    }
+
+    @Suppress("UNCHECKED_CAST")
+    override fun fetchResourcePath(request: LynxResourceRequest, callback: LynxResourceCallback<String>) {
+        val response = LynxResourceResponse.onFailed(Throwable("not supported")) as LynxResourceResponse<String>
+        callback.onResponse(response)
+    }
+}