create-mithril-lynx 2.0.0 → 2.1.0

package/README.md

@@ -2,7 +2,7 @@
 
 Scaffolds a new [`mithril-lynx`](https://github.com/carlos-sweb/mithril-lynx) app. Three templates, matching the "Hello World" / "Blank" / "Basic Activity" naming most native app scaffolds already use.
 
-It can also generate the **native Android host** — the whole Gradle project that wraps the bundle into an installable APK — so you never hand-write the ~20 Kotlin/Gradle/XML files that takes.
+It can also generate the **native Android host** — the whole Gradle project that wraps the bundle into an installable APK — so you never hand-write the ~20 Kotlin/Gradle/XML files that takes. That path automates [`mithril-lynx`'s ANDROID_APK_GUIDE.md](https://github.com/carlos-sweb/mithril-lynx/blob/main/ANDROID_APK_GUIDE.md).
 
 > **Note:** this is a complete rewrite of the previous `create-mithril-lynx`, matching [`mithril-lynx`'s own rewrite](https://github.com/carlos-sweb/mithril-lynx). The old tool's **Basic Activity** template used `mithril-lynx/navigation` (a stack-based, in-memory navigator) — that module doesn't exist in the new `mithril-lynx`, so this template was rewritten from scratch around [`mithril-lynx/route`](https://github.com/carlos-sweb/mithril-lynx/blob/main/ROUTE.md) instead. Everything else (Hello World, Blank, the Android host) ports over unchanged, since none of it depended on the part of the framework that got rewritten.
 
@@ -49,11 +49,28 @@ 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>` | Copy the font into the host's assets, generate `AssetFontFaceLoader.kt`, and wire the cold-start `prefetchFont()` hack. |
-| `--font-family <name>` | Override the family name derived from the font's file name. Only meaningful with `--with-font`. |
+| `--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`. |
 
 Anything not listed — in particular the four Android flags — requires `--android`
-(or one of its aliases); `--with-font` implies it on its own.
+(or one of its aliases); `--with-font`/`--find-font` imply it on their own.
+
+### `--find-font`, in more detail
+
+Fontsource's own API (`api.fontsource.org`) has no free-text search — only
+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
+`--with-font <file>` uses — there's no separate font-loading mechanism to
+maintain.
+
+```bash
+npx create-mithril-lynx my-app --blank --android --find-font Inter
+```
 
 ### What the generated Android host gives you
 
@@ -61,7 +78,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), and the font loader when `--with-font` is used;
+- the Kotlin host: the `Application`, `MainActivity` (async `AssetTemplateProvider`, splash screen) — no font-specific code needed, `--with-font` is entirely JS-side;
 - resource files that compile as-is (theme, splash theme, adaptive launcher icon);
 - an opt-in release signing setup driven by a gitignored `keystore.properties`.
 
@@ -90,6 +107,7 @@ This part of the tool is framework-agnostic — it just wraps whatever bundle `r
 ```
 create-mithril-lynx/
   src/index.js              the CLI itself
+  src/fontsource.js         --find-font: local search over Fontsource's catalog
   templates/
     _shared/
       common/                gitignore, project README — shared by every template
@@ -107,13 +125,12 @@ 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/
-      font/AssetFontFaceLoader.kt   copied only when --with-font is used
       app-scripts/android.mjs       the bridge -> <name>/scripts/android.mjs
 ```
 
 `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), substitutes `{{PACKAGE_NAME}}`, `{{APP_CLASS}}`, `{{APP_NAME}}`, `{{ANDROID_DIR}}` and `{{SDK_DIR}}` across the tree, and fills in the four font-hack hooks (`{{FONT_LOADER_IMPORT}}`, `{{FONT_LOADER_REGISTRATION}}`, `{{FONT_IMPORT}}`, `{{FONT_PREFETCH}}`) with either the real code or nothing at all. Binary files (the Gradle wrapper jar, the `.ttf`) are never text-substituted.
+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).
 
 **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.0.0",
+  "version": "2.1.0",
   "description": "Scaffolds a new mithril-lynx app (and, optionally, its Android host).",
   "license": "MIT",
   "type": "module",

package/src/fontsource.js

@@ -0,0 +1,102 @@
+// src/fontsource.js
+//
+// Local search over Fontsource's font catalog (https://fontsource.org). The
+// public API (https://api.fontsource.org/v1/fonts) has no free-text search —
+// only exact `id`/`family` filters (confirmed against its own docs) — so
+// this fetches the whole list once (~2100 fonts, ~540KB as of 2026-09) and
+// filters client-side. Cached to disk (24h TTL) so repeated searches in one
+// session, or across nearby `npx`/`bunx` invocations, don't re-download it
+// every time.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const FONTS_LIST_URL = "https://api.fontsource.org/v1/fonts";
+const FONT_DETAIL_URL = (id) => `https://api.fontsource.org/v1/fonts/${id}`;
+const CACHE_PATH = path.join(os.tmpdir(), "create-mithril-lynx-fontsource-cache.json");
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * @returns {Promise<Array<{id: string, family: string, category: string,
+ *   variable: boolean, license: string, weights: number[], styles: string[]}>>}
+ */
+export async function fetchFontList({ forceRefresh = false } = {}) {
+	if (!forceRefresh) {
+		try {
+			const stat = fs.statSync(CACHE_PATH);
+			if (Date.now() - stat.mtimeMs < CACHE_TTL_MS) {
+				return JSON.parse(fs.readFileSync(CACHE_PATH, "utf8"));
+			}
+		} catch {
+			// No cache yet, or unreadable — fetch fresh below.
+		}
+	}
+
+	const response = await fetch(FONTS_LIST_URL);
+	if (!response.ok) {
+		throw new Error(`Fontsource API returned ${response.status} fetching the font list.`);
+	}
+	const list = await response.json();
+
+	try {
+		fs.writeFileSync(CACHE_PATH, JSON.stringify(list));
+	} catch {
+		// Best-effort — a failed cache write just means the next call re-fetches.
+	}
+
+	return list;
+}
+
+/**
+ * Case-insensitive substring match on `family` (primarily) and `id`.
+ * Exact matches sort first, then alphabetically by family.
+ */
+export function searchFonts(list, query) {
+	const q = query.trim().toLowerCase();
+	if (q === "") return [];
+
+	const matches = list.filter(
+		(font) => font.family.toLowerCase().includes(q) || font.id.toLowerCase().includes(q),
+	);
+
+	return matches.sort((a, b) => {
+		const aExact = a.family.toLowerCase() === q ? 0 : 1;
+		const bExact = b.family.toLowerCase() === q ? 0 : 1;
+		if (aExact !== bExact) return aExact - bExact;
+		return a.family.localeCompare(b.family);
+	});
+}
+
+/**
+ * Full detail for one font — includes `variants[weight][style][subset]`,
+ * each holding `{ url: { woff2, woff, ttf } }`. Confirmed against Fontsource's
+ * own docs (https://fontsource.org/docs/api/font-id) and a real fetch.
+ */
+export async function fetchFontDetail(id) {
+	const response = await fetch(FONT_DETAIL_URL(id));
+	if (!response.ok) {
+		throw new Error(`Fontsource API returned ${response.status} fetching "${id}".`);
+	}
+	return response.json();
+}
+
+/** Flattens a font's `variants` object into a flat, pickable list. */
+export function listVariants(detail) {
+	const out = [];
+	for (const [weight, byStyle] of Object.entries(detail.variants ?? {})) {
+		for (const [style, bySubset] of Object.entries(byStyle)) {
+			for (const [subset, files] of Object.entries(bySubset)) {
+				if (files?.url?.ttf) {
+					out.push({ weight: Number(weight), style, subset, url: files.url.ttf });
+				}
+			}
+		}
+	}
+	// Latin first (most common default), then by weight, then style.
+	return out.sort((a, b) => {
+		if (a.subset !== b.subset) return a.subset === "latin" ? -1 : b.subset === "latin" ? 1 : a.subset.localeCompare(b.subset);
+		if (a.weight !== b.weight) return a.weight - b.weight;
+		return a.style.localeCompare(b.style);
+	});
+}

package/src/index.js

@@ -1,10 +1,13 @@
 #!/usr/bin/env node
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { execSync } from "node:child_process";
 
-import { cancel, confirm, intro, isCancel, outro, select, text } from "@clack/prompts";
+import { cancel, confirm, intro, isCancel, outro, select, spinner, text } from "@clack/prompts";
+
+import { fetchFontDetail, fetchFontList, listVariants, searchFonts } from "./fontsource.js";
 
 const scriptDir = path.dirname(fileURLToPath(import.meta.url));
 const packageRoot = path.join(scriptDir, "..");
@@ -132,6 +135,16 @@ 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`;
+}
+
 function xmlEscape(value) {
 	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
 }
@@ -173,12 +186,20 @@ function parseAndroidArgs(args) {
 		appName: readOption(args, "app-name"),
 		fontPath: readOption(args, "with-font"),
 		fontFamily: readOption(args, "font-family"),
+		findFontTerm: readOption(args, "find-font"),
 	};
 }
 
 // Options that consume the following argument, so that value is never mistaken
 // for the project name (e.g. `--with-font ./UbuntuMono.ttf`).
-const OPTIONS_WITH_VALUE = new Set(["--target", "--android-id", "--app-name", "--with-font", "--font-family"]);
+const OPTIONS_WITH_VALUE = new Set([
+	"--target",
+	"--android-id",
+	"--app-name",
+	"--with-font",
+	"--font-family",
+	"--find-font",
+]);
 
 function findPositional(args) {
 	for (let i = 0; i < args.length; i++) {
@@ -188,19 +209,118 @@ function findPositional(args) {
 			continue;
 		}
 		if (arg === "target=android") continue;
-		if (/^(?:target|android-id|app-name|with-font|font-family)=/.test(arg)) continue;
+		if (/^(?:target|android-id|app-name|with-font|font-family|find-font)=/.test(arg)) continue;
 		return arg;
 	}
 	return undefined;
 }
 
-/** Indents every non-empty line of a generated block. */
-function indent(block, spaces) {
-	const pad = " ".repeat(spaces);
-	return block
-		.split("\n")
-		.map((line) => (line === "" ? line : pad + line))
-		.join("\n");
+const WEIGHT_NAMES = {
+	100: "Thin",
+	200: "Extra Light",
+	300: "Light",
+	400: "Regular",
+	500: "Medium",
+	600: "Semi Bold",
+	700: "Bold",
+	800: "Extra Bold",
+	900: "Black",
+};
+
+function variantLabel(variant) {
+	const weightName = WEIGHT_NAMES[variant.weight] ?? String(variant.weight);
+	const style = variant.style === "italic" ? " Italic" : "";
+	return `${weightName}${style} (${variant.weight} ${variant.style})`;
+}
+
+/**
+ * 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
+ * `--with-font <file>` expects, so the rest of the pipeline (entirely
+ * JS-side — see patchJsProject()) doesn't need to know which path was used.
+ */
+async function findFontInteractively(term) {
+	// Unlike the other prompts in this file, this one isn't skippable by
+	// supplying enough flags up front — picking a family and a variant out
+	// of a search result is inherently interactive. Gate on the terminal
+	// itself, not on whether name/template were also given.
+	if (!process.stdin.isTTY) {
+		cancel("--find-font needs an interactive terminal to pick a family and variant — use --with-font <file.ttf> in scripts/CI.");
+		process.exit(1);
+	}
+
+	const s = spinner();
+	s.start(`Searching Fontsource for "${term}"…`);
+	let list;
+	try {
+		list = await fetchFontList();
+	} catch (error) {
+		s.stop("Search failed.");
+		cancel(error instanceof Error ? error.message : String(error));
+		process.exit(1);
+	}
+	const matches = searchFonts(list, term);
+	s.stop(`${matches.length} match(es) for "${term}".`);
+
+	if (matches.length === 0) {
+		cancel(`No Fontsource font matches "${term}". Try a different search, or use --with-font <file.ttf> for a font you already have.`);
+		process.exit(1);
+	}
+
+	const chosenId = await select({
+		message: "Which font?",
+		options: matches.map((f) => ({
+			value: f.id,
+			label: f.family,
+			hint: `${f.category}${f.variable ? ", variable" : ""} · ${f.license}`,
+		})),
+	});
+	if (isCancel(chosenId)) return null;
+
+	const s2 = spinner();
+	s2.start("Fetching variants…");
+	let detail;
+	try {
+		detail = await fetchFontDetail(chosenId);
+	} catch (error) {
+		s2.stop("Failed.");
+		cancel(error instanceof Error ? error.message : String(error));
+		process.exit(1);
+	}
+	const allVariants = listVariants(detail);
+	const variants = allVariants.filter((v) => v.subset === "latin");
+	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],
+		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`,
+	);
+	fs.writeFileSync(tempFile, bytes);
+	s3.stop(`Downloaded ${(bytes.length / 1024).toFixed(1)} kB.`);
+
+	return { sourcePath: tempFile, family: detail.family };
 }
 
 // ---------------------------------------------------------------------------
@@ -246,8 +366,21 @@ async function resolveAndroidOptions(android, { rawName, projectName, canPrompt
 	}
 	appName = appName ?? path.basename(rawName);
 
+	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.fontPath != null) {
+	if (android.findFontTerm != null) {
+		const found = await findFontInteractively(android.findFontTerm);
+		if (found == null) return null;
+		font = {
+			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);
 		if (!fs.existsSync(resolved)) {
 			cancel(`Font file not found: ${android.fontPath}`);
@@ -263,7 +396,7 @@ async function resolveAndroidOptions(android, { rawName, projectName, canPrompt
 			family: android.fontFamily ?? fontFamilyFor(resolved),
 		};
 	} else if (android.fontFamily != null) {
-		cancel("--font-family only makes sense together with --with-font.");
+		cancel("--font-family only makes sense together with --with-font or --find-font.");
 		process.exit(1);
 	}
 
@@ -277,7 +410,6 @@ function scaffoldAndroid({ targetDir, rawName, options }) {
 	const androidDir = path.join(path.dirname(targetDir), androidDirName);
 	const appClass = appClassNameFor(rawName);
 	const packagePath = androidId.split(".").join(path.sep);
-	const packageDir = path.join(androidDir, "app", "src", "main", "java", packagePath);
 
 	// 1. Copy the Gradle skeleton and the Kotlin app. `package-path` expands to
 	//    the real package path, and App.kt is renamed after its class.
@@ -297,19 +429,15 @@ function scaffoldAndroid({ targetDir, rawName, options }) {
 		// best-effort
 	}
 
-	// 2. The .ttf is opt-in: without it neither the loader nor the prefetch is
-	//    generated, so no dead code is left behind.
-	if (font != null) {
-		const fontsDir = path.join(androidDir, "app", "src", "main", "assets", "fonts");
-		fs.mkdirSync(fontsDir, { recursive: true });
-		fs.copyFileSync(font.sourcePath, path.join(fontsDir, font.file));
-
-		fs.copyFileSync(
-			path.join(ANDROID_TEMPLATE_ROOT, "font", "AssetFontFaceLoader.kt"),
-			path.join(packageDir, "AssetFontFaceLoader.kt"),
-		);
-	}
-
+	// 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).
 	const sdkDir = findAndroidSdk();
 
 	// 3. Text substitutions across the whole Android host (skipping the
@@ -327,54 +455,7 @@ function scaffoldAndroid({ targetDir, rawName, options }) {
 		],
 	]);
 
-	// 4. The four font-hack hooks: either the real code, or nothing at all.
-	const sourceUri = font != null ? `asset:///fonts/${font.file}` : undefined;
-	const fontLoaderImport = font != null ? "import com.lynx.tasm.loader.LynxFontFaceLoader\n" : "";
-	const fontLoaderRegistration =
-		font != null
-			? `${indent(
-					[
-						"// Must run BEFORE LynxEnv.inst().init(): this is what makes",
-						'// "asset:///" resolvable, both for prefetchFont() and for the',
-						"// real @font-face resolution during the first layout.",
-						"LynxFontFaceLoader.setLoader(AssetFontFaceLoader)",
-					].join("\n"),
-					8,
-				)}\n\n`
-			: "";
-	const fontImport = font != null ? "import com.lynx.tasm.fontface.FontFaceManager\n" : "";
-	const fontPrefetch =
-		font != null
-			? `${indent(
-					[
-						"// Warms the Typeface on Lynx's own IO thread pool, before",
-						"// renderTemplateUrl() gives the bundle's CSS a chance to resolve",
-						"// @font-face during the first layout. FontFaceManager caches by the",
-						"// exact src string, so this URI has to be identical to the",
-						'// url("...") of the @font-face in src/style.css.',
-						"FontFaceManager.getInstance().prefetchFont(",
-						"    lynxView.lynxContext,",
-						`    "${sourceUri}",`,
-						"    null,",
-						"    object : FontFaceManager.FontFacePrefetchListener {",
-						"        override fun onComplete(code: Int, msg: String) {}",
-						"    },",
-						")",
-					].join("\n"),
-					8,
-				)}\n\n`
-			: "";
-
-	for (const kt of walkFiles(packageDir)) {
-		replaceInFile(kt, [
-			["// {{FONT_LOADER_IMPORT}}\n", fontLoaderImport],
-			["        // {{FONT_LOADER_REGISTRATION}}\n", fontLoaderRegistration],
-			["// {{FONT_IMPORT}}\n", fontImport],
-			["        // {{FONT_PREFETCH}}\n", fontPrefetch],
-		]);
-	}
-
-	// 5. The script that joins the two halves, inside the JS project.
+	// 4. 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"));
@@ -405,23 +486,46 @@ function patchJsProject({ targetDir, android }) {
 	};
 	fs.writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
 
-	// style.css: the @font-face that has to match the Android host's
-	// prefetchFont() byte for byte.
+	// 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 cssPath = path.join(targetDir, "src", "style.css");
-		const block = [
-			"/* The font lives in the Android host's assets",
-			"   (app/src/main/assets/fonts/), not in the bundle. The asset:///",
-			"   string has to be identical to the one in MainActivity.kt's prefetchFont()",
-			"   or Lynx won't find the warmed Typeface. */",
-			"@font-face {",
-			`  font-family: "${android.font.family}";`,
-			`  src: url("asset:///fonts/${android.font.file}");`,
-			"}",
+		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);
+		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 existing = fs.existsSync(cssPath) ? fs.readFileSync(cssPath, "utf8") : "";
-		fs.writeFileSync(cssPath, `${block}\n${existing}`);
+		const existingBg = fs.existsSync(bgPath) ? fs.readFileSync(bgPath, "utf8") : "";
+		fs.writeFileSync(bgPath, `${fontBlock}${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}`);
 	}
 
 	// README: how the two halves are used together.
@@ -446,7 +550,7 @@ function patchJsProject({ targetDir, android }) {
 			`- Application ID: \`${android.androidId}\``,
 			`- Application class: \`${android.appClass}\` · Activity: \`MainActivity\``,
 			...(android.font != null
-				? [`- Font \`${android.font.family}\` prefetched from \`asset:///fonts/${android.font.file}\` (the cold-start hack).`]
+				? [`- Font \`${android.font.family}\` loaded via \`lynx.addFont()\` from \`src/assets/fonts/${android.font.file}\` (bundled as a data: URI — no native code involved).`]
 				: []),
 			"",
 		].join("\n");
@@ -471,9 +575,12 @@ Android host:
                             scaffold the sibling Gradle project <name>-android/
   --android-id <id>         applicationId / namespace (default com.example.<name>)
   --app-name <name>         launcher label (default: the project name)
-  --with-font <file.ttf>    copy the font into the host's assets, generate
-                            AssetFontFaceLoader.kt, and wire up the prefetchFont()
-                            call that avoids the slow cold start
+  --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)
+  --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
 
 Other:
@@ -500,9 +607,9 @@ async function main() {
 	const nonInteractive = positional != null && templateFlag != null;
 	const android = parseAndroidArgs(args);
 
-	// --with-font/--font-family only make sense with an Android host: imply it
-	// rather than ignoring them silently.
-	if (android.fontPath != null || android.fontFamily != null) {
+	// --with-font/--find-font/--font-family only make sense with an Android
+	// host: imply it rather than ignoring them silently.
+	if (android.fontPath != null || android.findFontTerm != null || android.fontFamily != null) {
 		android.requested = true;
 	}
 
@@ -626,8 +733,8 @@ async function main() {
 					`${androidDirName}/local.properties (sdk.dir=...).`
 				: `Android SDK found at ${sdkDir}.`,
 			font != null
-				? `Font "${font.family}" prefetched from asset:///fonts/${font.file} (the cold-start hack).`
-				: "No custom font — pass --with-font <file.ttf> to include the prefetch hack.",
+				? `Font "${font.family}" bundled and registered via lynx.addFont() — works on every host.`
+				: "No custom font — pass --with-font <file.ttf> to bundle one.",
 		];
 		outro(`Done! Next steps:\n\n  ${steps.join("\n  ")}\n\n${notes.join("\n")}`);
 		return;

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

@@ -3,7 +3,6 @@ package {{PACKAGE_NAME}}
 import android.app.Application
 import com.lynx.service.log.LynxLogService
 import com.lynx.tasm.LynxEnv
-// {{FONT_LOADER_IMPORT}}
 import com.lynx.tasm.service.LynxServiceCenter
 
 class {{APP_CLASS}} : Application() {
@@ -17,7 +16,6 @@ class {{APP_CLASS}} : Application() {
         LynxServiceCenter.inst().registerService(LynxLogService)
         LynxLogService.switchLogToSystem(true)
 
-        // {{FONT_LOADER_REGISTRATION}}
         LynxEnv.inst().init(this, null, null, null)
     }
 }

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

@@ -5,7 +5,6 @@ import androidx.appcompat.app.AppCompatActivity
 import androidx.core.splashscreen.SplashScreen.Companion.installSplashScreen
 import com.lynx.tasm.LynxViewBuilder
 import com.lynx.tasm.ThreadStrategyForRendering
-// {{FONT_IMPORT}}
 import com.lynx.xelement.XElementBehaviors
 
 class MainActivity : AppCompatActivity() {
@@ -28,7 +27,6 @@ class MainActivity : AppCompatActivity() {
         val lynxView = builder.build(this)
         setContentView(lynxView)
 
-        // {{FONT_PREFETCH}}
         // The bundle lives in app/src/main/assets/main-thread.bundle, copied
         // there by `npm run android` (scripts/android.mjs) from the JS
         // project's dist/. The name has to match exactly.

package/templates/android/font/AssetFontFaceLoader.kt

@@ -1,39 +0,0 @@
-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
-
-/**
- * Resolves `asset:///` in `@font-face`, both for the prefetch and for the real
- * lookup.
- *
- * Lynx's default loader (LynxFontFaceLoader$1, decompiled from
- * lynx-4.1.0.aar) is a no-op that never resolves `asset:///`: in
- * FontFaceManager that scheme is only handled inline inside loadTypeface()
- * when a FONT-type LynxResourceProvider is registered, and the non-http/
- * non-data: branch of prefetchFont() (prefetchFontWithLoader) goes through this
- * Loader only, with no fallback of its own. Without registering this,
- * `asset:///` resolves no way at all.
- *
- * Trade-off to keep in mind: FontFaceManager/LynxFontFaceLoader are public
- * classes (not @RestrictTo) but are not documented for this specific use —
- * they could change without notice in a major Lynx SDK release.
- */
-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
-        }
-    }
-}