create-mithril-lynx 2.4.0 → 2.5.2

package/src/index.js

@@ -3,7 +3,7 @@ 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 { execFileSync, execSync } from "node:child_process";
 
 import { cancel, confirm, intro, isCancel, multiselect, outro, select, spinner, text } from "@clack/prompts";
 
@@ -17,6 +17,7 @@ import {
 	findAndroidDir,
 	findProjectRoot,
 	mergeFontLists,
+	normalizeSource,
 	stripFontBlock,
 } from "./fonts-wire.js";
 
@@ -24,9 +25,10 @@ const scriptDir = path.dirname(fileURLToPath(import.meta.url));
 const packageRoot = path.join(scriptDir, "..");
 const cwd = process.cwd();
 
-// The mithril-lynx version pinned in the generated package.json — tracks
-// the current release, same policy as this tool's own v1.
+// Resolve the newest compatible framework packages when a project is scaffolded.
 const MITHRIL_LYNX_VERSION = "latest";
+const MITHRIL_LYNX_UI_VERSION = "latest";
+const MITHRIL_LYNX_UI_STYLES_IMPORT = '@import "mithril-lynx-ui/styles.css";';
 
 const TEMPLATES = [
 	{ value: "hello-world", label: "Hello World", hint: "recommended" },
@@ -36,6 +38,101 @@ const TEMPLATES = [
 const TEMPLATE_VALUES = TEMPLATES.map((t) => t.value);
 
 const ANDROID_TEMPLATE_ROOT = path.join(packageRoot, "templates", "android");
+const LYNX_ANDROID_PLUGINS_VERSION = "0.4.0";
+const LYNX_ANDROID_LEGACY_VERSIONS = [
+	{ plugins: "0.2.0", sqlite: "0.3.0", aggregate: "0.3.0" },
+	{ plugins: "0.2.0", sqlite: "0.3.0", aggregate: "0.2.0" },
+];
+const LYNX_ANDROID_JS_VERSION = "latest";
+const LYNX_ANDROID_JS_LEGACY_VERSIONS = new Set(["^0.2.0"]);
+
+const ANDROID_PLUGINS = [
+	{
+		id: "battery",
+		label: "Battery",
+		hint: "level and charging state · no permission",
+		artifact: "lynx-android-battery",
+		kotlinImport: "dev.lynx.android.plugins.battery.LynxBatteryPlugin",
+		registry: "LynxBatteryPlugin",
+	},
+	{
+		id: "camera",
+		label: "Camera",
+		hint: "external photo capture · FileProvider",
+		artifact: "lynx-android-camera",
+		kotlinImport: "dev.lynx.android.plugins.camera.LynxCameraPlugin",
+		registry: "LynxCameraPlugin",
+		activityResult: true,
+	},
+	{
+		id: "device",
+		label: "Device",
+		hint: "non-identifying device information · no permission",
+		artifact: "lynx-android-device",
+		kotlinImport: "dev.lynx.android.plugins.device.LynxDevicePlugin",
+		registry: "LynxDevicePlugin",
+	},
+	{
+		id: "geolocation",
+		label: "Geolocation",
+		hint: "one-shot foreground location · runtime permission",
+		artifact: "lynx-android-geolocation",
+		kotlinImport: "dev.lynx.android.plugins.geolocation.LynxGeolocationPlugin",
+		registry: "LynxGeolocationPlugin",
+		permissionResult: true,
+	},
+	{
+		id: "network",
+		label: "Network",
+		hint: "network snapshot · no permission",
+		artifact: "lynx-android-network",
+		kotlinImport: "dev.lynx.android.plugins.network.LynxNetworkPlugin",
+		registry: "LynxNetworkPlugin",
+	},
+	{
+		id: "vibration",
+		label: "Vibration",
+		hint: "bounded vibration · VIBRATE permission",
+		artifact: "lynx-android-vibration",
+		kotlinImport: "dev.lynx.android.plugins.vibration.LynxVibrationPlugin",
+		registry: "LynxVibrationPlugin",
+	},
+	{
+		id: "maps",
+		label: "Maps",
+		hint: "native maps · offline packages · optional foreground location",
+		artifact: "lynx-android-maps",
+		kotlinImport: "dev.lynx.android.plugins.maps.LynxMapsPlugin",
+		registry: "LynxMapsPlugin",
+		permissionResult: true,
+	},
+	{
+		id: "sqlite",
+		label: "SQLite",
+		hint: "app-private SQL database · no permission",
+		artifact: "lynx-android-sqlite",
+		kotlinImport: "dev.lynx.android.plugins.sqlite.LynxSqlitePlugin",
+		registry: "LynxSqlitePlugin",
+	},
+];
+const ANDROID_PLUGIN_BY_ID = new Map(ANDROID_PLUGINS.map((plugin) => [plugin.id, plugin]));
+const CONNECTOR_CONFIG_RELATIVE_PATH = path.join("android", "connectors.json");
+const CONNECTOR_DEPENDENCY_START = "    // <create-mithril-lynx:android-connectors>";
+const CONNECTOR_DEPENDENCY_END = "    // </create-mithril-lynx:android-connectors>";
+const MAIN_ACTIVITY_CONNECTOR_MARKERS = {
+	imports: {
+		start: "// <create-mithril-lynx:connector-imports>",
+		end: "// </create-mithril-lynx:connector-imports>",
+	},
+	registration: {
+		start: "        // <create-mithril-lynx:connector-registration>",
+		end: "        // </create-mithril-lynx:connector-registration>",
+	},
+	callbacks: {
+		start: "    // <create-mithril-lynx:connector-callbacks>",
+		end: "    // </create-mithril-lynx:connector-callbacks>",
+	},
+};
 
 // Files that text substitution must never touch (binaries).
 const BINARY_EXTENSIONS = new Set([".jar", ".png", ".jpg", ".jpeg", ".webp", ".gif", ".ttf", ".otf", ".ttc", ".keystore", ".jks", ".so"]);
@@ -137,6 +234,26 @@ function appClassNameFor(rawName) {
 	return name === "MainActivity" ? `${name}App` : name;
 }
 
+/** Android files users edit from the JS project, before syncing them into the
+ * sibling Gradle host with `bun run android:prepare`. */
+const ANDROID_DEVELOPMENT_FILES = [
+	["AndroidManifest.xml", ["AndroidManifest.xml"]],
+	["strings.xml", ["res", "values", "strings.xml"]],
+	["styles.xml", ["res", "values", "styles.xml"]],
+	["config.xml", ["res", "xml", "config.xml"]],
+	["network_security_config.xml", ["res", "xml", "network_security_config.xml"]],
+	["file_paths.xml", ["res", "xml", "file_paths.xml"]],
+];
+
+function seedAndroidDevelopmentFiles(targetDir, androidDir) {
+	const sourceRoot = path.join(androidDir, "app", "src", "main");
+	const destinationRoot = path.join(targetDir, "android");
+	fs.mkdirSync(destinationRoot, { recursive: true });
+	for (const [name, sourceParts] of ANDROID_DEVELOPMENT_FILES) {
+		fs.copyFileSync(path.join(sourceRoot, ...sourceParts), path.join(destinationRoot, name));
+	}
+}
+
 function fontFamilyFor(filePath) {
 	return path
 		.basename(filePath, path.extname(filePath))
@@ -155,6 +272,495 @@ function splitList(value) {
 		.filter(Boolean);
 }
 
+function normalizeAndroidPlugins(ids) {
+	const selected = [...new Set(ids)];
+	const unknown = selected.filter((id) => id !== "all" && !ANDROID_PLUGIN_BY_ID.has(id));
+	if (unknown.length > 0) {
+		cancel(`Unknown Android plugin${unknown.length > 1 ? "s" : ""}: ${unknown.join(", ")}. ` +
+			`Choose from ${ANDROID_PLUGINS.map((plugin) => plugin.id).join(", ")}, or all.`);
+		process.exit(1);
+	}
+	if (selected.includes("all") && selected.length > 1) {
+		cancel('"all" cannot be combined with individual Android plugins.');
+		process.exit(1);
+	}
+	return selected;
+}
+
+function connectorNpmPackages(pluginIds) {
+	return pluginIds.length === 0 ? [] : ["lynx-android-plugins"];
+}
+
+function mapsConfigurationUpdate(projectRoot, pluginIds) {
+	if (!pluginIds.includes("maps") && !pluginIds.includes("all")) return [];
+	const configPath = path.join(projectRoot, "android", "maps.json");
+	if (fs.existsSync(configPath)) return [];
+	return [{ path: configPath, previous: null, next: `${JSON.stringify({ url: "", sha256: "", version: "" }, null, 2)}\n` }];
+}
+
+function updatedConnectorPackageJson(projectRoot, currentIds, nextIds) {
+	const packagePath = path.join(projectRoot, "package.json");
+	const originalSource = fs.readFileSync(packagePath, "utf8");
+	const pkg = JSON.parse(originalSource);
+	if (pkg.dependencies == null || typeof pkg.dependencies !== "object" || Array.isArray(pkg.dependencies)) {
+		throw new Error("package.json dependencies cannot be managed. No files were changed.");
+	}
+	const current = new Set(connectorNpmPackages(currentIds));
+	const next = new Set(connectorNpmPackages(nextIds));
+	let changed = false;
+	for (const name of new Set([...current, ...next])) {
+		if (name in (pkg.devDependencies ?? {})) {
+			throw new Error(`${name} is in devDependencies. Move it to dependencies before managing connectors.`);
+		}
+		const version = pkg.dependencies[name];
+		const isManagedVersion = version === LYNX_ANDROID_JS_VERSION || LYNX_ANDROID_JS_LEGACY_VERSIONS.has(version);
+		if (version != null && !isManagedVersion) {
+			throw new Error(`${name} has a custom version. No files were changed.`);
+		}
+		if (next.has(name) && version !== LYNX_ANDROID_JS_VERSION) {
+			pkg.dependencies[name] = LYNX_ANDROID_JS_VERSION;
+			changed = true;
+		} else if (!next.has(name) && isManagedVersion) {
+			delete pkg.dependencies[name];
+			changed = true;
+		}
+	}
+	return { packagePath, source: changed ? `${JSON.stringify(pkg, null, 2)}\n` : originalSource };
+}
+
+function projectPackageManager(projectRoot) {
+	for (const [lock, manager] of [
+		["bun.lock", "bun"], ["bun.lockb", "bun"], ["pnpm-lock.yaml", "pnpm"],
+		["yarn.lock", "yarn"], ["package-lock.json", "npm"],
+	]) {
+		if (fs.existsSync(path.join(projectRoot, lock))) return manager;
+	}
+	return detectPackageManager();
+}
+
+function androidPluginHostConfiguration(pluginIds, versions = {
+	plugins: LYNX_ANDROID_PLUGINS_VERSION,
+	sqlite: LYNX_ANDROID_PLUGINS_VERSION,
+	aggregate: LYNX_ANDROID_PLUGINS_VERSION,
+}) {
+	const useAggregate = pluginIds.includes("all");
+	const plugins = useAggregate ? ANDROID_PLUGINS : pluginIds.map((id) => ANDROID_PLUGIN_BY_ID.get(id));
+	const gradleDependencies = useAggregate
+		? `    implementation("io.github.carlos-sweb:lynx-android-plugins:${versions.aggregate}")`
+		: plugins.map((plugin) =>
+			`    implementation("io.github.carlos-sweb:${plugin.artifact}:${plugin.id === "sqlite" ? versions.sqlite : versions.plugins}")`,
+		).join("\n");
+	const imports = useAggregate
+		? ["import dev.lynx.android.plugins.LynxAndroidPlugins"]
+		: plugins.map((plugin) => `import ${plugin.kotlinImport}`);
+	const registrations = useAggregate
+		? "        LynxAndroidPlugins.register(builder)"
+		: plugins.map((plugin) => `        ${plugin.registry}.register(builder)`).join("\n");
+	const handlesPermission = useAggregate || plugins.some((plugin) => plugin.permissionResult);
+	const handlesActivity = useAggregate || plugins.some((plugin) => plugin.activityResult);
+	const permissionHandler = useAggregate
+		? "LynxAndroidPlugins.onRequestPermissionsResult(requestCode, permissions, grantResults)"
+		: plugins.filter((plugin) => plugin.permissionResult).map((plugin) =>
+			`${plugin.registry}.onRequestPermissionsResult(requestCode, permissions, grantResults)`,
+		).join(" || ");
+	const activityRegistry = useAggregate ? "LynxAndroidPlugins" : "LynxCameraPlugin";
+
+	return {
+		pluginIds,
+		handlesPermission,
+		handlesActivity,
+		gradleDependencies: gradleDependencies || "    // No Lynx Android connector selected.",
+		imports: imports.join("\n"),
+		registrations: registrations || "        // No Lynx Android connector selected.",
+		permissionHandler: handlesPermission
+			? permissionHandler
+			: "false",
+		activityHandler: handlesActivity
+			? `${activityRegistry}.onActivityResult(requestCode, resultCode, data)`
+			: "false",
+	};
+}
+
+function buildAndroidConnectorRegistry(packageName, pluginIds) {
+	if (pluginIds.length === 0) return null;
+	const configuration = androidPluginHostConfiguration(pluginIds);
+	return [
+		"// GENERATED by create-mithril-lynx. Manage with add-android-plugin/remove-android-plugin.",
+		`package ${packageName}`,
+		"",
+		...(configuration.handlesActivity ? ["import android.content.Intent"] : []),
+		"import com.lynx.tasm.LynxViewBuilder",
+		configuration.imports,
+		"",
+		"object LynxAndroidConnectorRegistry {",
+		"    fun register(builder: LynxViewBuilder) {",
+		configuration.registrations,
+		"    }",
+		...(configuration.handlesPermission ? [
+			"",
+			"    fun onRequestPermissionsResult(requestCode: Int, permissions: Array<out String>, grantResults: IntArray): Boolean =",
+			`        ${configuration.permissionHandler}`,
+		] : []),
+		...(configuration.handlesActivity ? [
+			"",
+			"    fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?): Boolean =",
+			`        ${configuration.activityHandler}`,
+		] : []),
+		"}",
+		"",
+	].join("\n");
+}
+
+// The previous generated format is accepted only for a one-time, exact migration.
+function buildLegacyAndroidConnectorRegistry(packageName, pluginIds) {
+	const configuration = androidPluginHostConfiguration(pluginIds);
+	return [
+		"// GENERATED by create-mithril-lynx. Manage with add-android-plugin/remove-android-plugin.",
+		`package ${packageName}`,
+		"",
+		"import android.content.Intent",
+		"import com.lynx.tasm.LynxViewBuilder",
+		configuration.imports,
+		"",
+		"object LynxAndroidConnectorRegistry {",
+		"    fun register(builder: LynxViewBuilder) {",
+		configuration.registrations,
+		"    }",
+		"",
+		"    fun onRequestPermissionsResult(requestCode: Int, permissions: Array<out String>, grantResults: IntArray): Boolean =",
+		`        ${configuration.permissionHandler}`,
+		"",
+		"    fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?): Boolean =",
+		`        ${configuration.activityHandler}`,
+		"}",
+		"",
+	].filter((line, index, lines) => line !== "" || lines[index - 1] !== "").join("\n");
+}
+
+function mainActivityConnectorSections(pluginIds) {
+	const configuration = androidPluginHostConfiguration(pluginIds);
+	const callbacks = [];
+	if (configuration.handlesPermission) {
+		callbacks.push([
+			"    override fun onRequestPermissionsResult(requestCode: Int, permissions: Array<out String>, grantResults: IntArray) {",
+			"        if (LynxAndroidConnectorRegistry.onRequestPermissionsResult(requestCode, permissions, grantResults)) return",
+			"        super.onRequestPermissionsResult(requestCode, permissions, grantResults)",
+			"    }",
+		].join("\n"));
+	}
+	if (configuration.handlesActivity) {
+		callbacks.push([
+			'    @Deprecated("Needed for the external camera intent result")',
+			"    override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {",
+			"        if (LynxAndroidConnectorRegistry.onActivityResult(requestCode, resultCode, data)) return",
+			"        super.onActivityResult(requestCode, resultCode, data)",
+			"    }",
+		].join("\n"));
+	}
+	return {
+		imports: configuration.handlesActivity ? "import android.content.Intent\n" : "",
+		registration: pluginIds.length > 0 ? "        LynxAndroidConnectorRegistry.register(builder)\n" : "",
+		callbacks: callbacks.length > 0 ? `${callbacks.join("\n\n")}\n` : "",
+	};
+}
+
+function managedMainActivityBlock(source, name) {
+	const { start, end } = MAIN_ACTIVITY_CONNECTOR_MARKERS[name];
+	const startIndex = source.indexOf(start);
+	const endIndex = source.indexOf(end);
+	if (startIndex === -1 || endIndex === -1 || endIndex <= startIndex ||
+		source.indexOf(start, startIndex + start.length) !== -1 || source.indexOf(end, endIndex + end.length) !== -1) {
+		throw new Error(`MainActivity.kt has missing or duplicate connector ${name} markers. No files were changed.`);
+	}
+	const startLineBegin = source.lastIndexOf("\n", startIndex - 1) + 1;
+	const startLineEnd = source.indexOf("\n", startIndex);
+	const endLineBegin = source.lastIndexOf("\n", endIndex - 1) + 1;
+	const endLineEnd = source.indexOf("\n", endIndex);
+	if (startLineEnd === -1 || endLineEnd === -1 || endLineBegin <= startLineEnd ||
+		source.slice(startLineBegin, startLineEnd) !== start || source.slice(endLineBegin, endLineEnd) !== end) {
+		throw new Error(`MainActivity.kt has modified connector ${name} markers. No files were changed.`);
+	}
+	return { from: startLineEnd + 1, to: endLineBegin, body: source.slice(startLineEnd + 1, endLineBegin) };
+}
+
+function replaceManagedMainActivitySections(source, sections) {
+	let result = source;
+	for (const name of Object.keys(MAIN_ACTIVITY_CONNECTOR_MARKERS)) {
+		const block = managedMainActivityBlock(result, name);
+		result = `${result.slice(0, block.from)}${sections[name]}${result.slice(block.to)}`;
+	}
+	return result;
+}
+
+function replaceLegacyMainActivityFragment(source, fragment, replacement) {
+	if (source.split(fragment).length !== 2) {
+		throw new Error("MainActivity.kt has customized legacy connector code. No files were changed.");
+	}
+	return source.replace(fragment, replacement);
+}
+
+function markLegacyMainActivity(source) {
+	let result = source.replace(/\r\n/g, "\n");
+	const old = mainActivityConnectorSections(["all"]);
+	for (const name of Object.keys(MAIN_ACTIVITY_CONNECTOR_MARKERS)) {
+		const { start, end } = MAIN_ACTIVITY_CONNECTOR_MARKERS[name];
+		result = replaceLegacyMainActivityFragment(result, old[name], `${start}\n${old[name]}${end}\n`);
+	}
+	return result;
+}
+
+function prepareMainActivity(source, currentPluginIds) {
+	const hasMarkers = Object.values(MAIN_ACTIVITY_CONNECTOR_MARKERS)
+		.some(({ start, end }) => source.includes(start) || source.includes(end));
+	if (!hasMarkers) {
+		if (currentPluginIds == null) {
+			throw new Error("MainActivity.kt is missing managed connector markers. No files were changed.");
+		}
+		return { source: markLegacyMainActivity(source), legacy: true };
+	}
+	const expected = mainActivityConnectorSections(currentPluginIds ?? []);
+	for (const name of Object.keys(MAIN_ACTIVITY_CONNECTOR_MARKERS)) {
+		if (normalizeSource(managedMainActivityBlock(source, name).body) !== normalizeSource(expected[name])) {
+			throw new Error(`MainActivity.kt connector ${name} block was customized. No files were changed.`);
+		}
+	}
+	return { source, legacy: false };
+}
+
+function mainActivityOutsideConnectorBlocks(source) {
+	return replaceManagedMainActivitySections(source, { imports: "", registration: "", callbacks: "" });
+}
+
+function connectorConfigPath(projectRoot) {
+	return path.join(projectRoot, CONNECTOR_CONFIG_RELATIVE_PATH);
+}
+
+function connectorRegistryPath(androidDir, androidId) {
+	return path.join(androidDir, "app", "src", "main", "java", ...androidId.split("."), "LynxAndroidConnectorRegistry.kt");
+}
+
+function connectorDependencyBlock(pluginIds, versions) {
+	return [
+		CONNECTOR_DEPENDENCY_START,
+		androidPluginHostConfiguration(pluginIds, versions).gradleDependencies,
+		CONNECTOR_DEPENDENCY_END,
+	].join("\n");
+}
+
+function atomicWrite(filePath, contents) {
+	const temporaryPath = `${filePath}.tmp-${process.pid}`;
+	fs.writeFileSync(temporaryPath, contents);
+	fs.renameSync(temporaryPath, filePath);
+}
+
+function connectorStateUpdates({ projectRoot, androidDir, androidId, pluginIds }) {
+	const configPath = connectorConfigPath(projectRoot);
+	const registryPath = connectorRegistryPath(androidDir, androidId);
+	const mainActivityPath = path.join(path.dirname(registryPath), "MainActivity.kt");
+	const gradlePath = path.join(androidDir, "app", "build.gradle.kts");
+	const gradleSource = fs.readFileSync(gradlePath, "utf8");
+	const start = gradleSource.indexOf(CONNECTOR_DEPENDENCY_START);
+	const end = gradleSource.indexOf(CONNECTOR_DEPENDENCY_END);
+	if (start === -1 || end === -1 || end < start || gradleSource.indexOf(CONNECTOR_DEPENDENCY_START, start + 1) !== -1) {
+		throw new Error("The Android connector dependency block is missing or was modified. No files were changed.");
+	}
+	const currentRegistry = fs.existsSync(registryPath) ? fs.readFileSync(registryPath, "utf8") : null;
+	const currentConfig = fs.existsSync(configPath) ? readConnectorConfig(configPath) : null;
+	const currentConfigSource = currentConfig == null ? null : fs.readFileSync(configPath, "utf8");
+	const mainActivitySource = fs.readFileSync(mainActivityPath, "utf8");
+	const mainActivityEol = mainActivitySource.includes("\r\n") ? "\r\n" : "\n";
+	const preparedMainActivity = prepareMainActivity(mainActivitySource.replace(/\r\n/g, "\n"), currentConfig?.plugins ?? null);
+	const currentDependencyBlock = gradleSource.slice(start, end + CONNECTOR_DEPENDENCY_END.length);
+	const managedDependencyBlocks = currentConfig == null ? [] : [
+		connectorDependencyBlock(currentConfig.plugins),
+		...LYNX_ANDROID_LEGACY_VERSIONS.map((versions) => connectorDependencyBlock(currentConfig.plugins, versions)),
+	];
+	if (currentConfig != null && !managedDependencyBlocks.some((block) =>
+		normalizeSource(currentDependencyBlock) === normalizeSource(block))) {
+		throw new Error("The Android connector dependency block was modified outside the generator. No files were changed.");
+	}
+	const expectedRegistry = currentConfig == null ? null : preparedMainActivity.legacy
+		? buildLegacyAndroidConnectorRegistry(androidId, currentConfig.plugins)
+		: buildAndroidConnectorRegistry(androidId, currentConfig.plugins);
+	if ((currentRegistry == null) !== (expectedRegistry == null) ||
+		(currentRegistry != null && normalizeSource(currentRegistry) !== normalizeSource(expectedRegistry))) {
+		throw new Error("LynxAndroidConnectorRegistry.kt was modified outside the generator. No files were changed.");
+	}
+
+	const nextConfiguration = androidPluginHostConfiguration(pluginIds);
+	const outsideMainActivity = mainActivityOutsideConnectorBlocks(preparedMainActivity.source);
+	const externalIntentImport = /^import android\.content\.Intent\s*$/m.test(outsideMainActivity);
+	const outsideWithoutIntentImport = outsideMainActivity.replace(/^import android\.content\.Intent\s*$/gm, "");
+	if (nextConfiguration.handlesActivity && externalIntentImport) {
+		throw new Error("MainActivity.kt already imports Intent outside the managed connector block. No files were changed.");
+	}
+	if (!nextConfiguration.handlesActivity &&
+		managedMainActivityBlock(preparedMainActivity.source, "imports").body.includes("import android.content.Intent") &&
+		/\bIntent\b/.test(outsideWithoutIntentImport) && !externalIntentImport) {
+		throw new Error("MainActivity.kt uses the managed Intent import outside connector callbacks. No files were changed.");
+	}
+	const nextRegistry = buildAndroidConnectorRegistry(androidId, pluginIds);
+	if (nextRegistry == null) {
+		if (/\bLynxAndroidConnectorRegistry\b/.test(outsideMainActivity)) {
+			throw new Error("MainActivity.kt references the connector registry outside the managed block. No files were changed.");
+		}
+		const javaRoot = path.join(androidDir, "app", "src", "main", "java");
+		for (const file of walkFiles(javaRoot)) {
+			if (file === registryPath || file === mainActivityPath || !/\.(kt|java)$/.test(file)) continue;
+			if (fs.readFileSync(file, "utf8").includes("LynxAndroidConnectorRegistry")) {
+				throw new Error(`${path.basename(file)} references the connector registry. No files were changed.`);
+			}
+		}
+	}
+	const nextMainActivity = replaceManagedMainActivitySections(
+		preparedMainActivity.source,
+		mainActivityConnectorSections(pluginIds),
+	).replace(/\n/g, mainActivityEol);
+	const updatedGradle = `${gradleSource.slice(0, start)}${connectorDependencyBlock(pluginIds)}${gradleSource.slice(end + CONNECTOR_DEPENDENCY_END.length)}`;
+	return [
+		{ path: gradlePath, previous: gradleSource, next: updatedGradle },
+		{ path: mainActivityPath, previous: mainActivitySource, next: nextMainActivity },
+		{ path: registryPath, previous: currentRegistry, next: nextRegistry },
+		{ path: configPath, previous: currentConfigSource, next: `${JSON.stringify({ version: 1, plugins: pluginIds }, null, 2)}\n` },
+	];
+}
+
+function applyManagedUpdates(updates) {
+	const changed = updates.filter(({ previous, next }) => previous !== next);
+	for (const update of changed) {
+		const present = fs.existsSync(update.path);
+		if ((update.previous == null) !== !present ||
+			(present && fs.readFileSync(update.path, "utf8") !== update.previous)) {
+			throw new Error(`${path.basename(update.path)} changed during connector preparation. No files were changed.`);
+		}
+	}
+	const applied = [];
+	try {
+		for (const update of changed) {
+			if (update.next == null) {
+				fs.unlinkSync(update.path);
+			} else {
+				fs.mkdirSync(path.dirname(update.path), { recursive: true });
+				atomicWrite(update.path, update.next);
+			}
+			applied.push(update);
+		}
+	} catch (error) {
+		const rollbackErrors = [];
+		for (const update of applied.reverse()) {
+			try {
+				if (update.previous == null) fs.unlinkSync(update.path);
+				else atomicWrite(update.path, update.previous);
+			} catch (rollbackError) {
+				rollbackErrors.push(`${path.basename(update.path)}: ${rollbackError instanceof Error ? rollbackError.message : String(rollbackError)}`);
+			}
+		}
+		if (rollbackErrors.length > 0) {
+			throw new Error(`${error instanceof Error ? error.message : String(error)}. Rollback failed for ${rollbackErrors.join(", ")}.`);
+		}
+		throw error;
+	}
+}
+
+function readConnectorConfig(configPath) {
+	let config;
+	try {
+		config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+	} catch {
+		throw new Error("android/connectors.json is not valid JSON. No files were changed.");
+	}
+	if (config?.version !== 1 || !Array.isArray(config.plugins) || config.plugins.some((id) => typeof id !== "string")) {
+		throw new Error("android/connectors.json has an unsupported shape. No files were changed.");
+	}
+	return { plugins: normalizeAndroidPlugins(config.plugins) };
+}
+
+function requireManagedConnectorProject() {
+	const projectRoot = findProjectRoot(cwd);
+	if (projectRoot == null) throw new Error("No mithril-lynx project found here.");
+	const androidDir = findAndroidDir(projectRoot);
+	if (androidDir == null) throw new Error("No sibling Android host found for this project.");
+	const configPath = connectorConfigPath(projectRoot);
+	if (!fs.existsSync(configPath)) {
+		throw new Error(
+			"This Android host predates managed connectors or was customized. " +
+				"It is intentionally not patched automatically.",
+		);
+	}
+	const namespaceMatch = fs.readFileSync(path.join(androidDir, "app", "build.gradle.kts"), "utf8").match(/namespace\s*=\s*"([^"]+)"/);
+	if (namespaceMatch == null) throw new Error("Could not determine the Android namespace. No files were changed.");
+	return { projectRoot, androidDir, androidId: namespaceMatch[1], config: readConnectorConfig(configPath) };
+}
+
+async function runAndroidPluginCommand(command, args) {
+	intro(`create-mithril-lynx ${command}`);
+	let managed;
+	try {
+		managed = requireManagedConnectorProject();
+	} catch (error) {
+		cancel(error instanceof Error ? error.message : String(error));
+		process.exit(1);
+	}
+
+	if (command === "list-android-plugins") {
+		outro(
+			managed.config.plugins.length === 0
+				? "No Android connectors are enabled."
+				: `Enabled Android connectors: ${managed.config.plugins.join(", ")}`,
+		);
+		return;
+	}
+
+	const rawPlugins = args[0];
+	if (rawPlugins == null) {
+		cancel(`Pass a comma-separated connector list, e.g. ${command} battery,geolocation.`);
+		process.exit(1);
+	}
+	const requested = normalizeAndroidPlugins(splitList(rawPlugins));
+	const skipInstall = args.includes("--no-install");
+	let next;
+	if (command === "add-android-plugin") {
+		next = managed.config.plugins.includes("all") || requested.includes("all")
+			? ["all"]
+			: normalizeAndroidPlugins([...managed.config.plugins, ...requested]);
+	} else {
+		if (managed.config.plugins.includes("all") && !requested.includes("all")) {
+			cancel('The aggregate "all" connector must be removed as a whole.');
+			process.exit(1);
+		}
+		next = managed.config.plugins.filter((plugin) => !requested.includes(plugin));
+	}
+
+	let dependenciesChanged = false;
+	try {
+		const npm = updatedConnectorPackageJson(managed.projectRoot, managed.config.plugins, next);
+		const previousPackageSource = fs.readFileSync(npm.packagePath, "utf8");
+		dependenciesChanged = npm.source !== previousPackageSource;
+		applyManagedUpdates([
+			...connectorStateUpdates({ ...managed, pluginIds: next }),
+			...mapsConfigurationUpdate(managed.projectRoot, next),
+			{ path: npm.packagePath, previous: previousPackageSource, next: npm.source },
+		]);
+		if (dependenciesChanged) {
+			if (!skipInstall) {
+				const manager = projectPackageManager(managed.projectRoot);
+				try {
+					execFileSync(manager, ["install"], { cwd: managed.projectRoot, stdio: "inherit" });
+				} catch {
+					throw new Error(`Connector configuration was updated, but ${manager} install failed. Run it in the project to finish installation.`);
+				}
+			}
+		}
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		cancel(message);
+		process.exitCode = 1;
+		return;
+	}
+	outro((next.length === 0 ? "No Android connectors are enabled." : `Enabled Android connectors: ${next.join(", ")}.`) +
+		(skipInstall && dependenciesChanged ? `\nRun ${projectPackageManager(managed.projectRoot)} install to update dependencies.` : ""));
+}
+
 /** 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/. */
@@ -215,6 +821,7 @@ function parseAndroidArgs(args) {
 		fontPath: readOption(args, "with-font"),
 		fontFamily: readOption(args, "font-family"),
 		findFontTerm: readOption(args, "find-font"),
+		plugins: readOption(args, "android-plugins"),
 	};
 }
 
@@ -227,6 +834,7 @@ const OPTIONS_WITH_VALUE = new Set([
 	"--with-font",
 	"--font-family",
 	"--find-font",
+	"--android-plugins",
 ]);
 
 function findPositional(args) {
@@ -369,6 +977,46 @@ async function findFontInteractively(term) {
 	return results;
 }
 
+/** Prompt for any number of Fontsource families during interactive scaffolding. */
+async function addFontsInteractively() {
+	const fonts = [];
+	let addAnother = await confirm({
+		message: "Would you like to add fonts?",
+		initialValue: false,
+	});
+	if (isCancel(addAnother)) return null;
+
+	while (addAnother) {
+		const term = await text({
+			message: "Search for a font",
+			placeholder: "e.g. Inter",
+			validate(value) {
+				if (!value?.trim()) return "Enter a font name to search.";
+			},
+		});
+		if (isCancel(term)) return null;
+
+		const selected = await findFontInteractively(term.trim());
+		if (selected == null) return null;
+		fonts.push(
+			...selected.map((font) => ({
+				sourcePath: font.sourcePath,
+				file: path.basename(font.sourcePath),
+				family: font.family,
+			})),
+		);
+		dedupeFontFiles(fonts);
+
+		addAnother = await confirm({
+			message: "Would you like to add another font?",
+			initialValue: false,
+		});
+		if (isCancel(addAnother)) return null;
+	}
+
+	return fonts;
+}
+
 // ---------------------------------------------------------------------------
 // Android host scaffolding
 // ---------------------------------------------------------------------------
@@ -412,10 +1060,30 @@ async function resolveAndroidOptions(android, { rawName, projectName, canPrompt
 	}
 	appName = appName ?? path.basename(rawName);
 
+	let plugins = android.plugins == null ? [] : normalizeAndroidPlugins(splitList(android.plugins));
+	if (android.plugins == null && canPrompt) {
+		plugins = await multiselect({
+			message: "Which Lynx Android connectors should the host include?",
+			initialValues: [],
+			options: [
+				...ANDROID_PLUGINS.map((plugin) => ({ value: plugin.id, label: plugin.label, hint: plugin.hint })),
+				{ value: "all", label: "All connectors", hint: "convenience aggregate; includes every manifest contribution" },
+			],
+		});
+		if (isCancel(plugins)) return null;
+		plugins = normalizeAndroidPlugins(plugins);
+	}
+
 	const fonts = await resolveFontsFromFlags(android, { baseDir: cwd, requireFonts: false });
 	if (fonts == null) return null;
+	if (canPrompt && android.fontPath == null && android.findFontTerm == null) {
+		const interactiveFonts = await addFontsInteractively();
+		if (interactiveFonts == null) return null;
+		fonts.push(...interactiveFonts);
+		dedupeFontFiles(fonts);
+	}
 
-	return { androidId, appName, fonts };
+	return { androidId, appName, fonts, plugins };
 }
 
 /**
@@ -584,7 +1252,7 @@ async function runAddFont(args) {
 }
 
 function scaffoldAndroid({ targetDir, rawName, options }) {
-	const { androidId, appName, fonts } = options;
+	const { androidId, appName, fonts, plugins } = options;
 
 	const androidDirName = `${path.basename(rawName.replace(/^@[^/]+\//, ""))}-android`;
 	const androidDir = path.join(path.dirname(targetDir), androidDirName);
@@ -616,6 +1284,8 @@ function scaffoldAndroid({ targetDir, rawName, options }) {
 	//    and templates/android/host/.../NoopGenericResourceFetcher.kt.
 	const sdkDir = findAndroidSdk();
 
+	const pluginHost = androidPluginHostConfiguration(plugins);
+
 	// 3. Text substitutions across the whole Android host (skipping the
 	//    gradle-wrapper.jar, the .ttf and any other binary).
 	replaceInTree(androidDir, [
@@ -623,6 +1293,7 @@ function scaffoldAndroid({ targetDir, rawName, options }) {
 		["{{APP_CLASS}}", appClass],
 		["{{APP_NAME}}", xmlEscape(appName)],
 		["{{ANDROID_DIR}}", androidDirName],
+		["{{ANDROID_PLUGIN_DEPENDENCIES}}", pluginHost.gradleDependencies],
 		[
 			"{{SDK_DIR}}",
 			sdkDir != null
@@ -641,10 +1312,23 @@ function scaffoldAndroid({ targetDir, rawName, options }) {
 		}
 	}
 
-	// 5. The script that joins the two halves, inside the JS project.
+	// 5. Give app developers editable Android XML in their project, instead of
+	// making them traverse into the sibling Gradle host. android:prepare copies
+	// these exact files back into their Android resource locations.
+	seedAndroidDevelopmentFiles(targetDir, androidDir);
+
+	// 6. The managed MainActivity sections, registry, and Gradle dependency block
+	// are rendered together so post-install connector changes stay consistent.
+	applyManagedUpdates([
+		...connectorStateUpdates({ projectRoot: targetDir, androidDir, androidId, pluginIds: plugins }),
+		...mapsConfigurationUpdate(targetDir, plugins),
+	]);
+
+	// 7. The scripts that join the two halves, inside the JS project.
 	const scriptsDir = path.join(targetDir, "scripts");
 	fs.mkdirSync(scriptsDir, { recursive: true });
 	fs.copyFileSync(path.join(ANDROID_TEMPLATE_ROOT, "app-scripts", "android.mjs"), path.join(scriptsDir, "android.mjs"));
+	fs.copyFileSync(path.join(ANDROID_TEMPLATE_ROOT, "app-scripts", "android-prepare.mjs"), path.join(scriptsDir, "android-prepare.mjs"));
 
 	const androidRelDir = path.relative(targetDir, androidDir).split(path.sep).join("/");
 	replaceInFile(path.join(scriptsDir, "android.mjs"), [
@@ -654,20 +1338,28 @@ function scaffoldAndroid({ targetDir, rawName, options }) {
 		// A name with quotes would break keytool's -dname=CN=...
 		["{{APP_NAME}}", appName.replace(/["\\]/g, "")],
 	]);
+	replaceInFile(path.join(scriptsDir, "android-prepare.mjs"), [["{{ANDROID_REL_DIR}}", androidRelDir]]);
 
-	return { androidDir, androidDirName, androidRelDir, androidId, appName, appClass, fonts, sdkDir };
+	return { androidDir, androidDirName, androidRelDir, androidId, appName, appClass, fonts, plugins: pluginHost.pluginIds, sdkDir };
 }
 
 function patchJsProject({ targetDir, android }) {
 	// package.json: the Android scripts.
 	const pkgPath = path.join(targetDir, "package.json");
 	const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+	for (const name of connectorNpmPackages(android.plugins)) pkg.dependencies[name] = LYNX_ANDROID_JS_VERSION;
+	const buildCommand = pkg.scripts.build;
 	pkg.scripts = {
 		...pkg.scripts,
+		// Keep project-owned Android XML authoritative for every build path:
+		// `bun run build`, `npm run build`, and android.mjs's package-manager
+		// invocation all execute this command before rspeedy starts.
+		build: "node scripts/android-prepare.mjs && " + buildCommand,
 		android: "node scripts/android.mjs",
 		"android:apk": "node scripts/android.mjs --apk",
 		"android:release": "node scripts/android.mjs --release",
 		"android:sync": "node scripts/android.mjs --sync-only",
+		"android:prepare": "node scripts/android-prepare.mjs",
 		"android:keystore": "node scripts/android.mjs --keystore",
 	};
 	fs.writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
@@ -701,6 +1393,7 @@ function patchJsProject({ targetDir, android }) {
 			"npm run android          # build the bundle, copy it to assets, install and launch on the device",
 			"npm run android:apk      # build the debug APK only",
 			"npm run android:sync     # bundle -> assets only, no Gradle",
+			"bun run android:prepare  # android/*.xml -> sibling Android host",
 			"",
 			"# Signed release APK (generate the keystore once):",
 			"KEYSTORE_PASSWORD='...' npm run android:keystore",
@@ -709,6 +1402,11 @@ function patchJsProject({ targetDir, android }) {
 			"",
 			`- Application ID: \`${android.androidId}\``,
 			`- Application class: \`${android.appClass}\` · Activity: \`MainActivity\``,
+			"- Android XML: edit `android/*.xml`; every `bun run build` synchronizes those files to the sibling host before bundling. Run `bun run android:prepare` when you only need the synchronization.",
+			"- Android system Back bridge: the host pre-registers `MithrilLynxNavigationModule`; connect a `mithril-lynx/route` app with `route.listenBackButton({ onCanGoBackChange: (value) => NativeModules.MithrilLynxNavigationModule?.setCanGoBack(value) })`. The Basic Activity template is already connected.",
+			android.plugins.length > 0
+				? `- Android connectors: ${android.plugins.join(", ")}. The host registers the native modules and package.json includes their typed JavaScript facades. See [lynx-android-plugins](https://github.com/carlos-sweb/lynx-android-plugins#javascript-facades).`
+				: "- Android connectors: none selected. Run `npx create-mithril-lynx add-android-plugin <name>` from this app directory to opt into one.",
 			...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)).`,
@@ -719,6 +1417,79 @@ function patchJsProject({ targetDir, android }) {
 	}
 }
 
+function addUiThemeClass(source, rootClass, themeClass, sourcePath) {
+	const themedClass = `class: "${rootClass} ${themeClass}"`;
+	if (source.includes(themedClass)) return source;
+
+	const currentClass = `class: "${rootClass}"`;
+	const index = source.indexOf(currentClass);
+	if (index === -1) {
+		throw new Error(`Cannot configure mithril-lynx-ui: expected root class ${JSON.stringify(rootClass)} in ${sourcePath}.`);
+	}
+	return `${source.slice(0, index)}${themedClass}${source.slice(index + currentClass.length)}`;
+}
+
+function patchUiProject({ targetDir, template }) {
+	const templateUi = {
+		"hello-world": {
+			themeClass: "luna-dark",
+			roots: [{ file: "src/index.ts", className: "App" }],
+		},
+		blank: {
+			themeClass: "luna-light",
+			roots: [{ file: "src/index.ts", className: "Page" }],
+		},
+		"basic-activity": {
+			themeClass: "luna-light",
+			roots: ["home", "detail"].map((screen) => ({
+				file: `src/screens/${screen}.ts`,
+				className: "Page",
+			})),
+		},
+	}[template];
+	if (templateUi == null) throw new Error(`Cannot configure mithril-lynx-ui for unknown template "${template}".`);
+
+	const packagePath = path.join(targetDir, "package.json");
+	const packageJson = JSON.parse(fs.readFileSync(packagePath, "utf8"));
+	packageJson.dependencies ??= {};
+	packageJson.dependencies["mithril-lynx-ui"] = MITHRIL_LYNX_UI_VERSION;
+
+	const stylesheetPath = path.join(targetDir, "src", "style.css");
+	const stylesheet = fs.readFileSync(stylesheetPath, "utf8");
+	const updatedStylesheet = stylesheet.includes(MITHRIL_LYNX_UI_STYLES_IMPORT)
+		? stylesheet
+		: `${MITHRIL_LYNX_UI_STYLES_IMPORT}\n\n${stylesheet}`;
+
+	const themedSources = templateUi.roots.map(({ file, className }) => {
+		const sourcePath = path.join(targetDir, file);
+		const source = fs.readFileSync(sourcePath, "utf8");
+		return [sourcePath, addUiThemeClass(source, className, templateUi.themeClass, file)];
+	});
+
+	fs.writeFileSync(packagePath, `${JSON.stringify(packageJson, null, 2)}\n`);
+	if (updatedStylesheet !== stylesheet) fs.writeFileSync(stylesheetPath, updatedStylesheet);
+	for (const [sourcePath, source] of themedSources) fs.writeFileSync(sourcePath, source);
+
+	const readmePath = path.join(targetDir, "README.md");
+	if (fs.existsSync(readmePath)) {
+		const readme = fs.readFileSync(readmePath, "utf8");
+		if (!readme.includes("## UI components")) {
+			const section = [
+				"",
+				"## UI components",
+				"",
+				`This project was scaffolded with \`mithril-lynx-ui\`. Its stylesheet is imported from \`src/style.css\`, and the app root uses the \`${templateUi.themeClass}\` Luna theme.`,
+				"",
+				"Import components from their package entry points, for example `import { Button } from \"mithril-lynx-ui/button\";`. Components are headless by default; add their documented `ui-*` classes to opt into the supplied styles.",
+				"",
+				"See the [mithril-lynx-ui documentation](https://github.com/carlos-sweb/mithril-lynx-ui#readme) for component APIs and styling details.",
+				"",
+			].join("\n");
+			fs.appendFileSync(readmePath, section);
+		}
+	}
+}
+
 // ---------------------------------------------------------------------------
 
 const USAGE = `
@@ -727,17 +1498,27 @@ 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 <name> --blank --with-ui
   npx create-mithril-lynx add-font --with-font ./Foo.ttf
   npx create-mithril-lynx add-font --find-font Inter
+  npx create-mithril-lynx add-android-plugin battery,geolocation
 
 Template (prompted for if omitted):
   --hello-world | --blank | --basic-activity
 
+UI components:
+  --with-ui                 add mithril-lynx-ui and import its stylesheet;
+                            offered during interactive setup
+
 Android host:
-  --android, --target android, target=android
+  --android, --target android, --target=android, target=android
                             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)
+  --android-plugins <list>  native connectors to include: battery, camera,
+                            device, geolocation, network, vibration, maps,
+                            sqlite, or all.
+                            Comma-separate individual connectors.
   --with-font <file.ttf>    bundle the font into the JS project and register it
                             with lynx.addFont() (DEV: data: URI for Lynx Go;
                             PROD: asset:/// + AssetFontFaceLoader — see README).
@@ -760,9 +1541,14 @@ Post-init (run inside an existing app directory):
                             print the lines to paste by hand.
                             Same --with-font / --find-font / --font-family
                             flags as above.
+  add-android-plugin <list> add managed Android connector(s)
+  remove-android-plugin <list>
+                            remove managed Android connector(s)
+  list-android-plugins      show managed Android connectors
 
 Other:
-  --no-install              don't install dependencies
+  --no-install              don't install dependencies during scaffold or
+                            post-init connector changes
   -h, --help                print this
 `.trim();
 
@@ -784,16 +1570,20 @@ async function main() {
 		await runAddFont(args.slice(1));
 		return;
 	}
+	if (["add-android-plugin", "remove-android-plugin", "list-android-plugins"].includes(args[0])) {
+		await runAndroidPluginCommand(args[0], args.slice(1));
+		return;
+	}
 
 	const positional = findPositional(args);
 	const templateFlag = TEMPLATE_VALUES.find((t) => args.includes(`--${t}`));
 	const noInstall = args.includes("--no-install");
+	let withUi = args.includes("--with-ui");
 	const nonInteractive = positional != null && templateFlag != null;
 	const android = parseAndroidArgs(args);
 
-	// --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-only options imply the host rather than being silently ignored.
+	if (android.fontPath != null || android.findFontTerm != null || android.fontFamily != null || android.plugins != null) {
 		android.requested = true;
 	}
 
@@ -831,6 +1621,14 @@ async function main() {
 		if (isCancel(template)) return bail();
 	}
 
+	if (!withUi && !nonInteractive) {
+		withUi = await confirm({
+			message: "Include mithril-lynx-ui components?",
+			initialValue: false,
+		});
+		if (isCancel(withUi)) return bail();
+	}
+
 	let withAndroid = android.requested;
 	if (!withAndroid && !nonInteractive) {
 		withAndroid = await confirm({
@@ -871,6 +1669,8 @@ async function main() {
 	]);
 	replaceInFile(path.join(targetDir, "README.md"), [["{{PROJECT_NAME}}", projectName]]);
 
+	if (withUi) patchUiProject({ targetDir, template });
+
 	let androidResult = null;
 	if (withAndroid) {
 		androidResult = scaffoldAndroid({ targetDir, rawName, options: androidOptions });