create-mithril-lynx 2.4.0 → 2.5.0

package/README.md

@@ -124,8 +124,8 @@ The sibling `<name>-android/` project is a complete, no-Android-Studio Gradle CL
 
 - the Gradle wrapper (`gradlew`, `gradlew.bat`, `gradle-wrapper.jar`), so nothing needs to be installed besides a JDK and the Android SDK;
 - `local.properties` with `sdk.dir` auto-detected from `ANDROID_HOME`/`ANDROID_SDK_ROOT` (with a written warning if it can't be found);
-- the Kotlin host: the `Application` (registers `AssetFontFaceLoader`), `MainActivity` (async `AssetTemplateProvider`, splash screen, `NoopGenericResourceFetcher` for the fast `data:` font path — [lynx#9431](https://github.com/lynx-family/lynx/issues/9431));
-- resource files that compile as-is (theme, splash theme, adaptive launcher icon);
+- 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;
 - 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,10 +135,11 @@ 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
 npm run android:keystore   # generate release.keystore + keystore.properties (KEYSTORE_PASSWORD=...)
 ```
 
-This part of the tool is framework-agnostic — it just wraps whatever bundle `rspeedy build` produces into a native host — so it needed no changes for the `mithril-lynx` rewrite beyond what's inherited automatically through the generated JS project.
+The packaging path still wraps whatever bundle `rspeedy build` produces. Its one framework-aware convenience is the predefined, otherwise dormant system Back bridge used by `mithril-lynx/route`; the Basic Activity template connects it automatically.
 
 ## Templates
 
@@ -146,7 +147,7 @@ This part of the tool is framework-agnostic — it just wraps whatever bundle `r
 |---|---|
 | **Hello World** (recommended) | The Mithril.js analog of Lynx's official React hello-world ([`lynx-examples/examples/hello-world`](https://github.com/lynx-family/lynx-examples/tree/main/examples/hello-world)) — same layout, same "tap the logo" interaction, running through Mithril hyperscript instead of JSX. |
 | **Blank** | A single centered line of text. Nothing else — the starting point when you don't want any of Hello World's styling/assets in your way. |
-| **Basic Activity** | Two screens (Main → Details) wired with [`mithril-lynx/route`](https://github.com/carlos-sweb/mithril-lynx/blob/main/ROUTE.md) — an in-memory router (`m.route`, reimplemented for an environment with no URL bar). Includes a reusable app-bar-with-back-button pattern, using `route.back()` since Lynx has no hardware back button for a route to hook into automatically. |
+| **Basic Activity** | Two screens (Main → Details) wired with [`mithril-lynx/route`](https://github.com/carlos-sweb/mithril-lynx/blob/main/ROUTE.md) — an in-memory router (`m.route`, reimplemented for an environment with no URL bar). Includes a reusable app-bar back affordance and, with `--android`, predefined system Back/predictive Back integration through `route.listenBackButton()`. |
 
 ## Package structure
 
@@ -172,15 +173,17 @@ create-mithril-lynx/
       ts/src/{app-bar.ts, background.ts, screens/{home,detail}.ts}
     android/                 only used with --android
       host/                  the Gradle project -> <name>-android/
-                             (includes AssetFontFaceLoader +
-                             NoopGenericResourceFetcher for lynx#9431)
-      app-scripts/android.mjs       the bridge -> <name>/scripts/android.mjs
-                             (syncs bundle + src/assets/fonts/ → assets/fonts/)
+                             (includes AssetFontFaceLoader,
+                             NoopGenericResourceFetcher for lynx#9431, and the
+                             MithrilLynxNavigationModule system-Back bridge)
+      app-scripts/{android,android-prepare}.mjs
+                             bridges in <name>/scripts/ (syncs bundle/fonts;
+                             prepares <name>/android/*.xml into the host)
 ```
 
 `src/index.js` copies, in order, `templates/_shared/common` → `templates/_shared/ts` → `templates/<template>/common` → `templates/<template>/ts` into the target directory — later copies overwrite same-named files from earlier ones, which is exactly how **Basic Activity**'s own routing-based `src/background.ts` replaces `_shared/ts`'s generic single-view one (Hello World and Blank don't ship their own, so they keep the shared file). It then renames `gitignore` to `.gitignore` (npm doesn't publish dotfiles reliably otherwise) and replaces `{{PROJECT_NAME}}`/`{{MITHRIL_LYNX_VERSION}}` placeholders in `package.json` and `README.md`.
 
-With `--android` it then copies `templates/android/host` into a sibling `<name>-android/` (renaming `package-path` to the real package directory and `App.kt` to the Application class) and substitutes `{{PACKAGE_NAME}}`, `{{APP_CLASS}}`, `{{APP_NAME}}`, `{{ANDROID_DIR}}` and `{{SDK_DIR}}` across the tree. Binary files (the Gradle wrapper jar, a `--with-font` `.ttf`) are never text-substituted. With `--with-font`, 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`.
+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`.
 
 **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.4.0",
+  "version": "2.5.0",
   "description": "Scaffolds a new mithril-lynx app (and, optionally, its Android host).",
   "license": "MIT",
   "type": "module",

package/src/index.js

@@ -137,6 +137,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))
@@ -641,10 +661,16 @@ 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 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,6 +680,7 @@ 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 };
 }
@@ -662,12 +689,18 @@ function patchJsProject({ targetDir, android }) {
 	// package.json: the Android scripts.
 	const pkgPath = path.join(targetDir, "package.json");
 	const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+	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 +734,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 +743,8 @@ 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.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)).`,

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

@@ -1,3 +1,12 @@
 /// <reference types="@lynx-js/rspeedy/client" />
 /// <reference types="@lynx-js/types" />
 /// <reference types="@lynx-js/type-element-api" />
+
+declare module "@lynx-js/types" {
+	interface NativeModules {
+		/** Android host bridge used by mithril-lynx/route.listenBackButton(). */
+		MithrilLynxNavigationModule?: {
+			setCanGoBack(canGoBack: boolean): void;
+		};
+	}
+}

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

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+/**
+ * Copies the Android resources kept beside the JS source into the sibling
+ * Gradle host. Edit <project>/android/*.xml, then run:
+ *
+ *   bun run android:prepare
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const projectRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const sourceDir = path.join(projectRoot, "android");
+const androidDir = path.resolve(projectRoot, "{{ANDROID_REL_DIR}}");
+
+const files = [
+	["AndroidManifest.xml", ["app", "src", "main", "AndroidManifest.xml"]],
+	["strings.xml", ["app", "src", "main", "res", "values", "strings.xml"]],
+	["styles.xml", ["app", "src", "main", "res", "values", "styles.xml"]],
+	["config.xml", ["app", "src", "main", "res", "xml", "config.xml"]],
+	["network_security_config.xml", ["app", "src", "main", "res", "xml", "network_security_config.xml"]],
+	["file_paths.xml", ["app", "src", "main", "res", "xml", "file_paths.xml"]],
+];
+
+function fail(message) {
+	console.error(`\n  ✖ ${message}\n`);
+	process.exit(1);
+}
+
+if (!fs.existsSync(path.join(androidDir, "settings.gradle.kts"))) {
+	fail(`Can't find the Android host at ${androidDir}.`);
+}
+
+for (const [name, destination] of files) {
+	const source = path.join(sourceDir, name);
+	if (!fs.existsSync(source)) {
+		fail(`Missing ${path.relative(projectRoot, source)}. Restore it before preparing the Android host.`);
+	}
+	const target = path.join(androidDir, ...destination);
+	fs.mkdirSync(path.dirname(target), { recursive: true });
+	fs.copyFileSync(source, target);
+	console.log(`  → ${path.relative(projectRoot, target)}`);
+}
+
+console.log("\n  ✔ Android resources prepared.\n");

package/templates/android/host/app/src/main/AndroidManifest.xml

@@ -11,6 +11,7 @@
         android:roundIcon="@mipmap/ic_launcher_round"
         android:hardwareAccelerated="true"
         android:usesCleartextTraffic="true"
+        android:networkSecurityConfig="@xml/network_security_config"
         android:theme="@style/AppTheme">
 
         <activity

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

@@ -1,14 +1,18 @@
 package {{PACKAGE_NAME}}
 
 import android.os.Bundle
+import androidx.activity.OnBackPressedCallback
 import androidx.appcompat.app.AppCompatActivity
 import androidx.core.splashscreen.SplashScreen.Companion.installSplashScreen
+import com.lynx.react.bridge.JavaOnlyArray
 import com.lynx.tasm.LynxBooleanOption
 import com.lynx.tasm.LynxViewBuilder
 import com.lynx.tasm.ThreadStrategyForRendering
 import com.lynx.xelement.XElementBehaviors
 
 class MainActivity : AppCompatActivity() {
+    private var backCallback: OnBackPressedCallback? = null
+
     override fun onCreate(savedInstanceState: Bundle?) {
         // Must run BEFORE super.onCreate() — a Splash Screen API requirement.
         installSplashScreen()
@@ -20,6 +24,9 @@ class MainActivity : AppCompatActivity() {
         // keyboard. Remove this line (and the xelement dependencies) if you
         // don't use them.
         builder.addBehaviors(XElementBehaviors().create())
+        // 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)
         // lynx-family/lynx's own explorer/android registers a
         // GenericResourceFetcher unconditionally (LynxViewShellActivity —
         // "used inside LynxEngine for resource loading capabilities of
@@ -37,9 +44,29 @@ class MainActivity : AppCompatActivity() {
         val lynxView = builder.build(this)
         setContentView(lynxView)
 
+        // Disabled until route.listenBackButton() reports that JS has an
+        // in-app history entry. When disabled, Android's normal Back behavior
+        // remains in charge and closes the activity from the first screen.
+        val callback = object : OnBackPressedCallback(false) {
+            override fun handleOnBackPressed() {
+                lynxView.sendGlobalEvent("mithrilLynx:back", JavaOnlyArray())
+            }
+        }
+        onBackPressedDispatcher.addCallback(this, callback)
+        backCallback = callback
+
         // The bundle lives in app/src/main/assets/main-thread.bundle, copied
         // there by `npm run android` (scripts/android.mjs) from the JS
         // project's dist/. The name has to match exactly.
         lynxView.renderTemplateUrl("main-thread.bundle", "")
     }
+
+    fun setCanGoBack(canGoBack: Boolean) {
+        backCallback?.isEnabled = canGoBack
+    }
+
+    override fun onDestroy() {
+        backCallback = null
+        super.onDestroy()
+    }
 }

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

@@ -0,0 +1,28 @@
+package {{PACKAGE_NAME}}
+
+import android.content.Context
+import android.os.Handler
+import android.os.Looper
+import com.lynx.jsbridge.LynxMethod
+import com.lynx.jsbridge.LynxModule
+import com.lynx.tasm.behavior.LynxContext
+
+/**
+ * JS -> Android half of mithril-lynx/route's system Back integration.
+ *
+ * MainActivity supplies the Android -> JS half with sendGlobalEvent(). Keeping
+ * the callback disabled when the route history is empty preserves Android's
+ * default behavior on the app's first screen, including predictive Back.
+ */
+class MithrilLynxNavigationModule(context: Context) : LynxModule(context) {
+    private val activity = (context as? LynxContext)?.activity as? MainActivity
+
+    @LynxMethod
+    fun setCanGoBack(canGoBack: Boolean) {
+        // Lynx invokes native modules from its JS thread; Android's callback
+        // belongs to the main thread.
+        Handler(Looper.getMainLooper()).post {
+            activity?.setCanGoBack(canGoBack)
+        }
+    }
+}

package/templates/android/host/app/src/main/res/xml/config.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+  Project-owned Android configuration entry point. Android does not consume a
+  generic config.xml by itself; use it for XML metadata that a manifest entry
+  or a native integration needs, keeping that configuration beside the other
+  editable Android files in <project>/android/.
+-->
+<config />

package/templates/android/host/app/src/main/res/xml/file_paths.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+  Ready for an androidx.core.content.FileProvider declaration in
+  AndroidManifest.xml when the app needs to share a file with another app.
+-->
+<paths>
+    <files-path name="files" path="." />
+    <cache-path name="cache" path="." />
+    <external-files-path name="external_files" path="." />
+</paths>

package/templates/android/host/app/src/main/res/xml/network_security_config.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+  The generated manifest references this resource. It deliberately matches the
+  previous host default (cleartext allowed) so existing local HTTP workflows do
+  not change. Restrict this before a production release when possible.
+-->
+<network-security-config>
+    <base-config cleartextTrafficPermitted="true" />
+</network-security-config>

package/templates/basic-activity/ts/src/app-bar.ts

@@ -1,10 +1,9 @@
 import m from "mithril-runtime";
 
 // A reusable app bar: a title, plus a back affordance when `onBack` is
-// given. No m.route.Link involved for the back button — see
-// mithril-lynx/route.js's README section on route.back(): Lynx has no
-// hardware back button, so a screen's own back affordance has to call
-// route.back() explicitly.
+// given. No m.route.Link involved for this on-screen affordance: it calls
+// route.back() explicitly. The generated Android host's system Back bridge
+// reaches the same history separately through route.listenBackButton().
 export function AppBar(title: string, onBack?: () => void) {
 	return m("view", { class: "AppBar" }, [
 		onBack != null ? m("text", { class: "AppBar-back", ontap: onBack }, "←") : null,

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

@@ -21,6 +21,14 @@ route("/", {
 	"/detail": DetailHost,
 });
 
+// The host generated by --android forwards the system Back button through a
+// Lynx global event. The module is optional so this template still runs in
+// LynxExplorer, or when generated without its native Android host.
+route.listenBackButton({
+	onCanGoBackChange: (canGoBack) =>
+		NativeModules.MithrilLynxNavigationModule?.setCanGoBack(canGoBack),
+});
+
 declare const module: {
 	hot?: {
 		accept(path: string, callback: () => void): void;