create-mithril-lynx 2.1.0 → 2.3.0

package/README.md

@@ -49,13 +49,51 @@ 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). |
-| `--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`. |
-| `--font-family <name>` | Override the family name derived from the font's file name (or from Fontsource, with `--find-font`). Only meaningful with `--with-font`/`--find-font`. |
+| `--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. |
+| `--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`
 (or one of its aliases); `--with-font`/`--find-font` imply it on their own.
 
+### More than one font
+
+Both flags take a comma-separated list — useful for a body font plus a
+monospace one for code, for example:
+
+```bash
+npx create-mithril-lynx my-app --blank --android --find-font "Inter,JetBrains Mono"
+```
+
+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.:
+
+```css
+.code {
+  font-family: "JetBrains Mono", monospace;
+}
+```
+
+### 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. 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.
+
 ### `--find-font`, in more detail
 
 Fontsource's own API (`api.fontsource.org`) has no free-text search — only
@@ -78,7 +116,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`.
 
@@ -106,8 +144,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
@@ -125,12 +164,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 `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`.
 
 **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.1.0",
+  "version": "2.3.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. Same idea for src/style.css's automatic `text { font-family }` rule.
+ *   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 extraFamilies = fonts.slice(1).map((f) => f.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).",
+		...(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] + '"; }`.',
+				]
+			: []),
+		"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");
+}
+
+export function buildCssFontBlock(family) {
+	return [`text {`, `  font-family: "${family}", sans-serif;`, `}`, "", ""].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"),
+		),
+	];
+}
+
+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.
+ */
+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 };
+}
+
+/**
+ * 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? }.
+ */
+export function applyCssDefaultFont(projectRoot, defaultFamily, { hadExistingFonts }) {
+	const cssPath = path.join(projectRoot, "src", "style.css");
+	if (!fs.existsSync(cssPath)) {
+		return {
+			ok: false,
+			reason: "src/style.css not found",
+			manualBlock: buildCssFontBlock(defaultFamily),
+		};
+	}
+	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) {
+		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}`);
+	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

@@ -8,6 +8,17 @@ import { execSync } from "node:child_process";
 import { cancel, confirm, intro, isCancel, outro, select, spinner, text } from "@clack/prompts";
 
 import { fetchFontDetail, fetchFontList, listVariants, searchFonts } from "./fontsource.js";
+import {
+	applyBackgroundFonts,
+	applyCssDefaultFont,
+	buildCssFontBlock,
+	buildFontBlock,
+	copyFontFiles,
+	findAndroidDir,
+	findProjectRoot,
+	mergeFontLists,
+	stripFontBlock,
+} from "./fonts-wire.js";
 
 const scriptDir = path.dirname(fileURLToPath(import.meta.url));
 const packageRoot = path.join(scriptDir, "..");
@@ -135,14 +146,31 @@ function fontFamilyFor(filePath) {
 		.join(" ");
 }
 
-/** 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`;
+/** `--with-font`/`--find-font` accept a comma-separated list, for bundling
+ * more than one font (e.g. a body font and a monospace one for code). */
+function splitList(value) {
+	return value
+		.split(",")
+		.map((v) => v.trim())
+		.filter(Boolean);
+}
+
+/** Renames `file` on any font past the first with the same basename, so
+ * e.g. two different "Inter" downloads (different weights) don't collide
+ * once copied into src/assets/fonts/. */
+function dedupeFontFiles(fonts) {
+	const seen = new Set();
+	for (const font of fonts) {
+		let file = font.file;
+		let n = 2;
+		while (seen.has(file)) {
+			const ext = path.extname(font.file);
+			file = `${path.basename(font.file, ext)}-${n}${ext}`;
+			n += 1;
+		}
+		seen.add(file);
+		font.file = file;
+	}
 }
 
 function xmlEscape(value) {
@@ -366,45 +394,182 @@ 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);
 	}
 
-	let font = null;
-	if (android.findFontTerm != null) {
-		const found = await findFontInteractively(android.findFontTerm);
+	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.",
+		);
+		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;
-		font = {
+		fonts.push({
 			sourcePath: found.sourcePath,
 			file: path.basename(found.sourcePath),
 			family: android.fontFamily ?? found.family,
-		};
-	} else if (android.fontPath != null) {
-		const resolved = path.resolve(cwd, android.fontPath);
+		});
+	}
+	for (const rawPath of fontPaths) {
+		const resolved = path.resolve(baseDir, rawPath);
 		if (!fs.existsSync(resolved)) {
-			cancel(`Font file not found: ${android.fontPath}`);
+			cancel(`Font file not found: ${rawPath}`);
 			process.exit(1);
 		}
 		if (![".ttf", ".otf", ".ttc"].includes(path.extname(resolved).toLowerCase())) {
-			cancel(`"${android.fontPath}" does not look like a font (.ttf/.otf/.ttc).`);
+			cancel(`"${rawPath}" does not look like a font (.ttf/.otf/.ttc).`);
 			process.exit(1);
 		}
-		font = {
+		fonts.push({
 			sourcePath: resolved,
 			file: path.basename(resolved),
 			family: android.fontFamily ?? fontFamilyFor(resolved),
-		};
-	} else if (android.fontFamily != null) {
-		cancel("--font-family only makes sense together with --with-font or --find-font.");
+		});
+	}
+	dedupeFontFiles(fonts);
+	return 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);
 	}
 
-	return { androidId, appName, font };
+	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 hadExistingFonts = existingInBg.length > 0;
+	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 = 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):");
+		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) {
+		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.`,
+		);
+	}
+
+	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 }) {
-	const { androidId, appName, font } = options;
+	const { androidId, appName, fonts } = options;
 
 	const androidDirName = `${path.basename(rawName.replace(/^@[^/]+\//, ""))}-android`;
 	const androidDir = path.join(path.dirname(targetDir), androidDirName);
@@ -429,15 +594,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
@@ -455,7 +616,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"));
@@ -469,7 +640,7 @@ function scaffoldAndroid({ targetDir, rawName, options }) {
 		["{{APP_NAME}}", appName.replace(/["\\]/g, "")],
 	]);
 
-	return { androidDir, androidDirName, androidRelDir, androidId, appName, appClass, font, sdkDir };
+	return { androidDir, androidDirName, androidRelDir, androidId, appName, appClass, fonts, sdkDir };
 }
 
 function patchJsProject({ targetDir, android }) {
@@ -486,46 +657,22 @@ 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).
-	if (android.font != null) {
-		const { family, sourcePath, file } = android.font;
-		const fontsDir = path.join(targetDir, "src", "assets", "fonts");
-		fs.mkdirSync(fontsDir, { recursive: true });
-		fs.copyFileSync(sourcePath, path.join(fontsDir, file));
-
-		const varName = jsIdentifierFor(family);
+	// 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) {
+		copyFontFiles({
+			projectRoot: targetDir,
+			fonts: android.fonts,
+			androidDir: android.androidDir,
+		});
 		const bgPath = path.join(targetDir, "src", "background.ts");
-		const fontBlock = [
-			`// Font: "${family}", bundled from src/assets/fonts/${file}. lynx.addFont()`,
-			"// registers it directly — dataUriLimit: Infinity (lynx.config.ts) inlines",
-			"// the import as a data: URI, which resolves the same way on every host,",
-			"// no native code needed.",
-			`import ${varName} from "./assets/fonts/${file}";`,
-			`lynx.addFont({ "font-family": "${family}", src: \`url("\${${varName}}")\` }, () => {});`,
-			"",
-			"",
-		].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: "${family}", sans-serif;`, `}`, ""].join("\n");
 		const existingCss = fs.existsSync(cssPath) ? fs.readFileSync(cssPath, "utf8") : "";
-		fs.writeFileSync(cssPath, `${cssBlock}\n${existingCss}`);
+		fs.writeFileSync(cssPath, `${buildCssFontBlock(android.fonts[0].family)}${existingCss}`);
 	}
 
 	// README: how the two halves are used together.
@@ -549,9 +696,10 @@ function patchJsProject({ targetDir, android }) {
 			"",
 			`- Application ID: \`${android.androidId}\``,
 			`- Application class: \`${android.appClass}\` · Activity: \`MainActivity\``,
-			...(android.font != null
-				? [`- Font \`${android.font.family}\` loaded via \`lynx.addFont()\` from \`src/assets/fonts/${android.font.file}\` (bundled as a data: URI — no native code involved).`]
-				: []),
+			...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)).`,
+			),
 			"",
 		].join("\n");
 		fs.appendFileSync(readmePath, section);
@@ -566,6 +714,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
@@ -576,12 +726,27 @@ 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)
+                            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
-  --font-family <name>      override the family name derived from the file name
+                            and bundle it the same way as --with-font.
+                            Comma-separate terms for more than one — quote
+                            the whole thing if any term has a space, e.g.
+                            --find-font "Inter,JetBrains Mono"
+  --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
@@ -594,6 +759,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")) {
@@ -601,6 +767,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");
@@ -720,7 +891,7 @@ async function main() {
 	];
 
 	if (androidResult != null) {
-		const { androidDirName, sdkDir, font } = androidResult;
+		const { androidDirName, sdkDir, fonts } = androidResult;
 		const notes = [
 			`Android host generated in ${androidDirName}/ (Application ID ${androidOptions.androidId}).`,
 			"",
@@ -732,9 +903,9 @@ async function main() {
 				? "⚠ Android SDK not found: export ANDROID_HOME and edit " +
 					`${androidDirName}/local.properties (sdk.dir=...).`
 				: `Android SDK found at ${sdkDir}.`,
-			font != null
-				? `Font "${font.family}" bundled and registered via lynx.addFont() — works on every host.`
-				: "No custom font — pass --with-font <file.ttf> to bundle one.",
+			fonts.length > 0
+				? `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")}`);
 		return;

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)
+    }
+}