create-mithril-lynx 0.0.1 → 0.1.0

package/README.md

@@ -1,6 +1,8 @@
 # create-mithril-lynx
 
-Scaffolds a new [`mithril-lynx`](https://github.com/carlos-sweb/mithril-lynx) app — the Mithril.js analog of Lynx's official React hello-world template ([`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.
+Scaffolds a new [`mithril-lynx`](https://github.com/carlos-sweb/mithril-lynx) app. Three templates, matching the "Hello World" / "Blank" / "Basic Activity" naming most native app scaffolds already use, each available in TypeScript or JavaScript.
+
+It can also generate the **native Android host** — the whole Gradle project that wraps the bundle into an installable APK — so you never hand-write the ~20 Kotlin/Gradle/XML files that takes. That path automates [`mithril-lynx`'s ANDROID_APK_GUIDE.md](https://github.com/carlos-sweb/mithril-lynx/blob/main/ANDROID_APK_GUIDE.md).
 
 ## Usage
 
@@ -8,35 +10,118 @@ Scaffolds a new [`mithril-lynx`](https://github.com/carlos-sweb/mithril-lynx) ap
 npm create mithril-lynx@latest
 ```
 
-Prompts for a project name and a variant (TypeScript or JavaScript), scaffolds it, and offers to install dependencies for you.
+Prompts for a project name, a template, and a variant (TypeScript or JavaScript), scaffolds it, and offers to install dependencies for you.
 
 ### Non-interactive
 
 ```bash
-npx create-mithril-lynx my-app --ts
-npx create-mithril-lynx my-app --js --no-install
+npx create-mithril-lynx my-app --hello-world --ts
+npx create-mithril-lynx my-app --basic-activity --js --no-install
+```
+
+### With the Android host
+
+```bash
+# Scaffold the JS app plus a sibling my-app-android/ Gradle project:
+npx create-mithril-lynx my-app --ts --blank --android
+
+cd my-app
+npm install
+npm run android          # bundle -> assets -> installDebug -> launch on the device
+```
+
+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
 ```
 
-## What it scaffolds
+Every flag, in one table — `npx create-mithril-lynx --help` prints the same list:
+
+| 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. |
+| `--ts` / `--js` | TypeScript or JavaScript variant. Omit it and you're prompted. |
+| `--no-install` | Don't install dependencies (also skips that prompt). |
+| `-h`, `--help` | Print usage and exit. |
+| `--android` / `--target android` / `--target=android` / `target=android` | Also scaffold the sibling `<name>-android/` Gradle project. |
+| `--android-id <id>` | `applicationId` / `namespace` (default `com.example.<name>`). |
+| `--app-name <name>` | Launcher label (default: the project name). |
+| `--with-font <file.ttf>` | Copy the font into the host's assets, generate `AssetFontFaceLoader.kt`, and wire the cold-start `prefetchFont()` hack (Part D of the guide). |
+| `--font-family <name>` | Override the family name derived from the font's file name. Only meaningful with `--with-font`. |
+
+Anything not listed — in particular the four Android flags — requires `--android`
+(or one of its aliases); `--with-font` implies it on its own.
+
+### What the generated Android host gives you
+
+The sibling `<name>-android/` project is a complete, no-Android-Studio Gradle CLI project pinned to the versions in the guide (AGP 8.5.2, Kotlin 1.9.24, Gradle 8.14.2, Lynx `4.1.0`, `compileSdk`/`targetSdk` 34, `minSdk` 24), including:
+
+- the Gradle wrapper (`gradlew`, `gradlew.bat`, `gradle-wrapper.jar`), so nothing needs to be installed besides a JDK 17 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` (log service registered), `MainActivity` (async `AssetTemplateProvider`, splash screen, `XElementBehaviors`), and the font loader when `--with-font` is used;
+- resource files that compile as-is (theme, splash theme, adaptive launcher icon);
+- 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:
+
+```bash
+npm run android            # build + sync + installDebug + launch, printing TotalTime
+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
+npm run android:keystore   # generate release.keystore + keystore.properties (KEYSTORE_PASSWORD=...)
+```
+
+## Templates
+
+| Template | What it is |
+|---|---|
+| **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/navigation`](https://github.com/carlos-sweb/mithril-lynx#navigation) — a stack-based, in-memory navigator (deliberately not `m.route`; see that package's README for why Lynx pages can't use URL-based routing). Includes a reusable app-bar-with-back-button pattern. Confirmed working end to end on a real device: `push()` with data, the back button, and `pop()` all round-trip correctly. |
+
+## Variants
 
 | Variant | Adds over the base template |
 |---|---|
 | **TypeScript** (recommended) | `.ts` source files, `tsconfig.json` (project references, matching `@lynx-js/rspeedy`'s own generated config), `@rsbuild/plugin-type-check`, `@types/mithril` for real editor autocomplete on `m()` calls. |
 | **JavaScript** | Same app, plain `.js` with ES module `import`/`export` — no type-checking, no `tsconfig.json`. |
 
-Both variants share `template-common/`: the logo/arrow image assets, `style.css`, `.gitignore`, and the project's own `README.md`.
-
 ## Package structure
 
 ```
 create-mithril-lynx/
-  src/index.js        the CLI itself
-  template-common/    shared across both variants
-  template-js/        JavaScript-only files
-  template-ts/        TypeScript-only files
+  src/index.js              the CLI itself
+  templates/
+    _shared/
+      common/                gitignore, project README — shared by every template
+      js/                    lynx.config.js, package.json, main-thread.js — shared by every JS variant
+      ts/                    lynx.config.ts, tsconfig*, package.json, main-thread.ts — shared by every TS variant
+    hello-world/
+      common/src/            logo/arrow assets, style.css
+      js/src/index.js
+      ts/src/index.ts
+    blank/
+      common/src/style.css
+      js/src/index.js
+      ts/src/index.ts
+    basic-activity/
+      common/src/style.css
+      js/src/index.js
+      ts/src/index.ts
+    android/                 only used with --android
+      host/                  the Gradle project -> <name>-android/
+      font/AssetFontFaceLoader.kt   copied only when --with-font is used
+      app-scripts/android.mjs       the bridge -> <name>/scripts/android.mjs
 ```
 
-`src/index.js` copies `template-common/` then `template-<variant>/` into the target directory, 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`.
+`src/index.js` copies, in order, `templates/_shared/common` → `templates/_shared/<variant>` → `templates/<template>/common` → `templates/<template>/<variant>` into the target directory (later copies never need to overwrite earlier ones — each layer contributes different files), renames `gitignore` to `.gitignore` (npm doesn't publish dotfiles reliably otherwise), and replaces `{{PROJECT_NAME}}`/`{{MITHRIL_LYNX_VERSION}}` placeholders in `package.json` and `README.md`.
+
+With `--android` it then copies `templates/android/host` into a sibling `<name>-android/` (renaming `package-path` to the real package directory and `App.kt` to the Application class), substitutes `{{PACKAGE_NAME}}`, `{{APP_CLASS}}`, `{{APP_NAME}}`, `{{ANDROID_DIR}}` and `{{SDK_DIR}}` across the tree, and fills in the four font-hack hooks (`{{FONT_LOADER_IMPORT}}`, `{{FONT_LOADER_REGISTRATION}}`, `{{FONT_IMPORT}}`, `{{FONT_PREFETCH}}`) with either the real code or nothing at all. Binary files (the Gradle wrapper jar, the `.ttf`) are never text-substituted.
+
+Every template's `src/index.{js,ts}` exports the same shape (`{ root }`), so `_shared/{js,ts}/src/main-thread.{js,ts}` — the actual `__RenderPage` wiring — is 100% shared and never duplicated per template.
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-mithril-lynx",
-  "version": "0.0.1",
-  "description": "Scaffolds a new mithril-lynx app — the Mithril.js analog of Lynx's official React hello-world template.",
+  "version": "0.1.0",
+  "description": "Scaffolds a new mithril-lynx app — Hello World, Blank, or Basic Activity (with navigation), in JavaScript or TypeScript — and optionally the native Android host that packages it into an APK.",
   "license": "MIT",
   "type": "module",
   "repository": {
@@ -17,9 +17,7 @@
   },
   "files": [
     "src",
-    "template-common",
-    "template-js",
-    "template-ts"
+    "templates"
   ],
   "engines": {
     "node": "^20.19.0 || >=22.12.0"