create-mithril-lynx 2.5.0 → 2.5.2

package/README.md

@@ -32,29 +32,146 @@ npm install
 npm run android          # bundle -> assets -> installDebug -> launch on the device
 ```
 
+### With Android connectors
+
+Android projects can opt into the published
+[`lynx-android-plugins`](https://github.com/carlos-sweb/lynx-android-plugins)
+artifacts at scaffold time. The generator adds the selected Maven libraries,
+their JavaScript facade packages, manifest contributions, native-module
+registrations, and the Activity callbacks required for camera and geolocation.
+
+```bash
+npx create-mithril-lynx my-app --blank --android \
+  --android-plugins battery,geolocation,network
+```
+
+Available connector names are `battery`, `camera`, `device`, `geolocation`,
+`network`, `vibration`, `maps`, `sqlite`, and `all`. The interactive Android flow offers the
+same selection. `all` deliberately includes every manifest contribution;
+prefer individual names for production apps.
+
+The generated Android host declares Maven Central dependencies at version
+`0.4.0`, including `io.github.carlos-sweb:lynx-android-plugins:0.4.0` for `all`
+and the individual connector artifacts when selecting specific names.
+Adding or removing connectors also upgrades managed dependencies from the
+previous template versions (`0.2.0`, or `0.3.0` for SQLite and `all`).
+
+The generated project receives the `lynx-android-plugins` JavaScript package
+with a small typed API for each selected feature. For example,
+`import { gps } from "lynx-android-plugins/geolocation"`
+followed by `await gps.get({ highAccuracy: true })` returns one location.
+See the [JavaScript facades](https://github.com/carlos-sweb/lynx-android-plugins#javascript-facades)
+for the complete API.
+
+For offline maps, select `--android-plugins maps` (or add `maps` after
+scaffolding). This creates `android/maps.json`. Supply the HTTPS URL, SHA-256,
+and version of a Chile PMTiles archive there. Every build runs
+`android:prepare` first and copies that config into the Android host. Import
+`Maps` from `lynx-android-plugins/maps` and render it inside a sized parent:
+
+```ts
+import { Maps } from "lynx-android-plugins/maps";
+m(Maps, { latitude: -33.532290, longitude: -71.584904, variant: "full" });
+```
+
+The map is downloaded only when the user taps the native download button.
+Afterward it renders offline. The archive must be hosted by the app developer;
+this project does not offer a public map-tile service. The Maps module is
+prepared for Maven/npm version `0.2.0` and is not usable from the published
+`0.1.0` artifacts.
+
+For app-private SQLite storage, select `sqlite` and import
+`sqlite` from `lynx-android-plugins/sqlite`. Calls are asynchronous and run in
+the generated Android host; they do not run in stock Lynx Go. See the
+[SQLite connector guide](https://github.com/carlos-sweb/lynx-android-plugins/blob/main/docs/sqlite.md)
+for SQL parameters, migrations, transactions, and result types. The generated
+host uses Maven version `0.4.0` for SQLite and `all`, and installs the JavaScript
+facade from the latest npm release of `lynx-android-plugins`.
+
+### Add connectors after scaffolding
+
+Projects generated with this version can update their selected connectors
+without recreating the app:
+
+```bash
+cd my-app
+npx create-mithril-lynx add-android-plugin battery,geolocation
+npx create-mithril-lynx remove-android-plugin battery
+npx create-mithril-lynx list-android-plugins
+```
+
+The generator stores its selection in `android/connectors.json` and updates its
+own Gradle dependency block, connector registry, and marked connector sections
+of `MainActivity.kt`. It generates permission and activity callbacks only for
+connectors that need them; with no connectors, it removes the generated
+registry. It also adds or removes the `lynx-android-plugins` dependency in
+`package.json` and runs the detected package manager's install command when
+that dependency changes. Existing managed hosts are migrated when their old
+generated connector code is unchanged. A custom facade version, a modified
+managed block, or an older host without `android/connectors.json` causes the
+command to stop before replacing those edits.
+Use `--no-install` after an add/remove command to update configuration without
+running the package manager immediately.
+To refresh an existing host without changing its selection, add an already
+enabled connector again (for example, `add-android-plugin battery --no-install`).
+
 The interactive prompt offers it too, and the literal `target=android` form works as well:
 
 ```bash
 npm create mithril-lynx@latest my-app target=android
 ```
 
-Every flag, in one table — `npx create-mithril-lynx --help` prints the same list:
+### CLI reference
+
+These are the project-creation flags. Run `npx create-mithril-lynx --help` to
+see them together with the post-scaffold commands below.
 
 | Flag | Effect |
 |---|---|
 | `<name>` (positional) | Project name, and the directory to create. Omit it and you're prompted. |
 | `--hello-world` / `--blank` / `--basic-activity` | Template to scaffold. Omit it and you're prompted. |
-| `--no-install` | Don't install dependencies (also skips that prompt). |
+| `--no-install` | Skip dependency installation after scaffolding; also skips the install prompt. For connector commands, prevents the package manager from running. |
 | `-h`, `--help` | Print usage and exit. |
+| `--with-ui` | Add `mithril-lynx-ui` and import its stylesheet. Offered during interactive setup; works independently of `--android`. |
 | `--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). |
+| `--android-plugins <list>` | Android connectors to include: comma-separated `battery`, `camera`, `device`, `geolocation`, `network`, `vibration`, `maps`, `sqlite`, or `all`. Implies `--android`. |
 | `--with-font <file.ttf>` | Bundle the font into `src/assets/fonts/` and register it with `lynx.addFont()` in a loop. **DEV** (`npm run dev` / Lynx Go): `require()` inlines a `data:` URI so the font shows up in Explorer. **PROD** (`npm run build` / APK): `asset:///fonts/<file>` resolved by `AssetFontFaceLoader` on the host (keeps the bundle small — embedding `data:` URIs in the APK re-introduces the cold-start cost tracked in [lynx#9431](https://github.com/lynx-family/lynx/issues/9431)). Comma-separate for more than one file. |
 | `--find-font <term>` | Search [Fontsource](https://fontsource.org)'s catalog for `<term>`, prompt you to pick a family and one or more weights/styles, download each `.ttf`, and bundle them exactly like `--with-font`. Needs a real terminal (the picking is inherently interactive — use `--with-font <file.ttf>` in scripts/CI). Mutually exclusive with `--with-font`. Comma-separate terms for more than one — quote the whole thing if any term has a space. |
 | `--font-family <name>` | Override the family name derived from the font's file name (or from Fontsource, with `--find-font`). Only valid with exactly one font. |
 
-Anything not listed — in particular the four Android flags — requires `--android`
-(or one of its aliases); `--with-font`/`--find-font` imply it on their own.
+`--android-id` and `--app-name` configure the host when one is generated.
+`--android-plugins` and the font flags imply `--android`; `--with-ui` works
+with or without the Android host.
+
+During interactive Android setup, the CLI asks whether to add fonts. If you
+choose yes, search Fontsource, select a family and its variants, then choose
+whether to add another font. The setup continues after you answer no. The
+`--find-font` flag remains available for scripted scaffolding.
+
+### Commands for an existing project
+
+Run these from the generated app directory. Connector commands require an
+Android host created by this tool and manage only the generated connector
+configuration.
+
+| Command | Arguments and options | Effect |
+|---|---|---|
+| `add-font` | `--with-font <file.ttf>` or `--find-font <term>`; optional `--font-family <name>` | Add fonts to the existing app and wire up the generated font registration and CSS. Font options are the same as during scaffolding. |
+| `add-android-plugin` | `<list>`; optional `--no-install` | Add comma-separated Android connectors (the same names as `--android-plugins`) and update dependencies. `--no-install` leaves dependency installation to you. |
+| `remove-android-plugin` | `<list>`; optional `--no-install` | Remove managed connectors and update dependencies. If `all` is enabled, remove `all` as a whole. |
+| `list-android-plugins` | — | Show the connectors currently enabled for the Android host. |
+
+### UI components
+
+Add `mithril-lynx-ui` to a new app and import its stylesheet with:
+
+```bash
+npx create-mithril-lynx my-app --blank --with-ui
+```
+
+For component APIs and styling, see the [`mithril-lynx-ui` documentation](https://github.com/carlos-sweb/mithril-lynx-ui#readme).
 
 ### More than one font
 
@@ -126,6 +243,7 @@ The sibling `<name>-android/` project is a complete, no-Android-Studio Gradle CL
 - `local.properties` with `sdk.dir` auto-detected from `ANDROID_HOME`/`ANDROID_SDK_ROOT` (with a written warning if it can't be found);
 - the Kotlin host: the `Application` (registers `AssetFontFaceLoader`), `MainActivity` (async `AssetTemplateProvider`, splash screen, `NoopGenericResourceFetcher` for the fast `data:` font path — [lynx#9431](https://github.com/lynx-family/lynx/issues/9431)), and a predefined native bridge for `mithril-lynx/route`'s Android system Back support;
 - a project-local `android/` folder with editable `AndroidManifest.xml`, `strings.xml`, `styles.xml`, `config.xml`, `network_security_config.xml`, and `file_paths.xml`, plus `bun run android:prepare` to copy them into the Gradle host;
+- opt-in Maven Central connectors for battery, camera, device, geolocation, network, vibration, maps, and SQLite, each registered only when selected with `--android-plugins`;
 - an opt-in release signing setup driven by a gitignored `keystore.properties`.
 
 And in the JS project, a `scripts/android.mjs` bridge plus npm scripts:
@@ -135,7 +253,7 @@ npm run android            # build + sync + installDebug + launch, printing Tota
 npm run android:apk        # build + sync + assembleDebug
 npm run android:release    # build + sync + assembleRelease (signed if keystore.properties exists)
 npm run android:sync       # build + sync bundle into app/src/main/assets/, no Gradle
-bun run android:prepare    # manually sync android/*.xml -> sibling Android host
+bun run android:prepare    # manually sync android/*.xml and maps.json -> sibling Android host
 npm run android:keystore   # generate release.keystore + keystore.properties (KEYSTORE_PASSWORD=...)
 ```
 
@@ -183,7 +301,25 @@ create-mithril-lynx/
 
 `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. It also seeds the generated project's `android/` folder with `AndroidManifest.xml`, `strings.xml`, `styles.xml`, `config.xml`, `network_security_config.xml`, and `file_paths.xml`. `bun run build` (and the Android build commands that invoke it) automatically synchronizes those local copies to the Gradle host first; use `bun run android:prepare` (or `npm run android:prepare`) when you only want that synchronization. Binary files (the Gradle wrapper jar, a `--with-font` `.ttf`) are never text-substituted. With `--with-font`, each font is copied into the JS project (`src/assets/fonts/`) *and* seeded into the Android host's `assets/fonts/`, wired up with a `FONTS` loop + `lynx.addFont()` in `src/background.ts` plus a generated `src/fonts.css` (`text { font-family }` for the first font, one class per font when there are several) imported from `src/style.css`. `scripts/android.mjs` keeps `assets/fonts/` in sync on every `npm run android` / `android:sync`.
+Scaffolding handles the Android host and fonts as follows:
+
+1. **Android host (`--android`)**
+   - Copies `templates/android/host` into a sibling `<name>-android/` project.
+   - Renames `package-path` to the generated package directory and `App.kt` to the application class.
+   - Replaces `{{PACKAGE_NAME}}`, `{{APP_CLASS}}`, `{{APP_NAME}}`, `{{ANDROID_DIR}}` and `{{SDK_DIR}}` placeholders.
+   - Seeds the app's editable `android/` folder with `AndroidManifest.xml`, `strings.xml`, `styles.xml`, `config.xml`, `network_security_config.xml` and `file_paths.xml`.
+
+2. **Android preparation**
+   - `bun run build` and Android build commands run `android:prepare` before building, copying the editable config files into the Gradle host.
+   - To copy the files without building, run `bun run android:prepare` (or `npm run android:prepare`).
+
+3. **Fonts (`--with-font`)**
+   - Copies each `.ttf` into `src/assets/fonts/` and registers it from `src/background.ts` with a generated `FONTS` loop and `lynx.addFont()`.
+   - Generates `src/fonts.css`, imported by `src/style.css`; it sets the first font as the default `text` font and creates a class for each font variant.
+   - When an Android host exists, also copies fonts into its `assets/fonts/`. `scripts/android.mjs` syncs that folder during `npm run android` and `npm run android:sync`.
+
+4. **Binary files**
+   - The Gradle wrapper JAR and font `.ttf` files are copied as binary assets; placeholder substitution does not modify them.
 
 **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.5.0",
+  "version": "2.5.2",
   "description": "Scaffolds a new mithril-lynx app (and, optionally, its Android host).",
   "license": "MIT",
   "type": "module",

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"]);
@@ -175,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/. */
@@ -235,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"),
 	};
 }
 
@@ -247,6 +834,7 @@ const OPTIONS_WITH_VALUE = new Set([
 	"--with-font",
 	"--font-family",
 	"--find-font",
+	"--android-plugins",
 ]);
 
 function findPositional(args) {
@@ -389,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
 // ---------------------------------------------------------------------------
@@ -432,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 };
 }
 
 /**
@@ -604,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);
@@ -636,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, [
@@ -643,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
@@ -666,7 +1317,14 @@ function scaffoldAndroid({ targetDir, rawName, options }) {
 	// these exact files back into their Android resource locations.
 	seedAndroidDevelopmentFiles(targetDir, androidDir);
 
-	// 6. The scripts that join the two halves, inside the JS project.
+	// 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"));
@@ -682,13 +1340,14 @@ function scaffoldAndroid({ targetDir, rawName, options }) {
 	]);
 	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,
@@ -745,6 +1404,9 @@ function patchJsProject({ targetDir, android }) {
 			`- 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)).`,
@@ -755,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 = `
@@ -763,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).
@@ -796,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();
 
@@ -820,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;
 	}
 
@@ -867,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({
@@ -907,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 });

package/templates/_shared/ts/package.json

@@ -9,7 +9,7 @@
     "preview": "rspeedy preview"
   },
   "dependencies": {
-    "mithril-runtime": "^1.1.0",
+    "mithril-runtime": "latest",
     "mithril-lynx": "{{MITHRIL_LYNX_VERSION}}"
   },
   "devDependencies": {

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

@@ -8,5 +8,14 @@ declare module "@lynx-js/types" {
 		MithrilLynxNavigationModule?: {
 			setCanGoBack(canGoBack: boolean): void;
 		};
+		LynxBatteryPlugin?: { getStatus(requestId: string): void };
+		LynxCameraPlugin?: { takePhoto(requestId: string): void };
+		LynxDevicePlugin?: { getInfo(requestId: string): void };
+		LynxGeolocationPlugin?: { getCurrentPosition(requestId: string, highAccuracy: boolean): void };
+		LynxNetworkPlugin?: { getInfo(requestId: string): void };
+		LynxVibrationPlugin?: {
+			vibrate(requestId: string, durationMs: number): void;
+			cancel(requestId: string): void;
+		};
 	}
 }

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

@@ -42,4 +42,12 @@ for (const [name, destination] of files) {
 	console.log(`  → ${path.relative(projectRoot, target)}`);
 }
 
+const mapsConfig = path.join(sourceDir, "maps.json");
+if (fs.existsSync(mapsConfig)) {
+	const mapsTarget = path.join(androidDir, "app", "src", "main", "assets", "lynx_maps", "config.json");
+	fs.mkdirSync(path.dirname(mapsTarget), { recursive: true });
+	fs.copyFileSync(mapsConfig, mapsTarget);
+	console.log(`  → ${path.relative(projectRoot, mapsTarget)}`);
+}
+
 console.log("\n  ✔ Android resources prepared.\n");

package/templates/android/host/app/build.gradle.kts

@@ -98,6 +98,10 @@ dependencies {
     // gesture then never works).
     implementation("androidx.viewpager2:viewpager2:1.1.0")
 
+    // <create-mithril-lynx:android-connectors>
+{{ANDROID_PLUGIN_DEPENDENCIES}}
+    // </create-mithril-lynx:android-connectors>
+
     implementation("androidx.appcompat:appcompat:1.7.0")
     implementation("androidx.core:core-splashscreen:1.0.1")
 }

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

@@ -1,6 +1,8 @@
 package {{PACKAGE_NAME}}
 
 import android.os.Bundle
+// <create-mithril-lynx:connector-imports>
+// </create-mithril-lynx:connector-imports>
 import androidx.activity.OnBackPressedCallback
 import androidx.appcompat.app.AppCompatActivity
 import androidx.core.splashscreen.SplashScreen.Companion.installSplashScreen
@@ -27,6 +29,8 @@ class MainActivity : AppCompatActivity() {
         // Lets mithril-lynx/route tell Android when its in-memory history can
         // handle Back. See MithrilLynxNavigationModule and the callback below.
         builder.registerModule("MithrilLynxNavigationModule", MithrilLynxNavigationModule::class.java)
+        // <create-mithril-lynx:connector-registration>
+        // </create-mithril-lynx:connector-registration>
         // lynx-family/lynx's own explorer/android registers a
         // GenericResourceFetcher unconditionally (LynxViewShellActivity —
         // "used inside LynxEngine for resource loading capabilities of
@@ -65,6 +69,9 @@ class MainActivity : AppCompatActivity() {
         backCallback?.isEnabled = canGoBack
     }
 
+    // <create-mithril-lynx:connector-callbacks>
+    // </create-mithril-lynx:connector-callbacks>
+
     override fun onDestroy() {
         backCallback = null
         super.onDestroy()

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

@@ -34,7 +34,11 @@ declare const module: {
 		accept(path: string, callback: () => void): void;
 	};
 };
-declare const require: (id: string) => unknown;
+// Overloads: HMR reloads the two screen modules; DEV font registration
+// prepended by --with-font/--find-font requires .ttf paths as string URLs.
+declare function require(id: "./screens/home.js"): typeof homeModule;
+declare function require(id: "./screens/detail.js"): typeof detailModule;
+declare function require(id: string): string;
 
 if (module.hot) {
 	module.hot.accept("./screens/home.js", () => {