create-mithril-lynx 0.1.1 → 2.0.0

package/README.md

@@ -1,8 +1,10 @@
 # create-mithril-lynx
 
-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.
+Scaffolds a new [`mithril-lynx`](https://github.com/carlos-sweb/mithril-lynx) app. Three templates, matching the "Hello World" / "Blank" / "Basic Activity" naming most native app scaffolds already use.
 
-It can also generate the **native Android host** — the whole Gradle project that wraps the bundle into an installable APK — so you never hand-write the ~20 Kotlin/Gradle/XML files that takes. That path automates [`mithril-lynx`'s ANDROID_APK_GUIDE.md](https://github.com/carlos-sweb/mithril-lynx/blob/main/ANDROID_APK_GUIDE.md).
+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.
+
+> **Note:** this is a complete rewrite of the previous `create-mithril-lynx`, matching [`mithril-lynx`'s own rewrite](https://github.com/carlos-sweb/mithril-lynx). The old tool's **Basic Activity** template used `mithril-lynx/navigation` (a stack-based, in-memory navigator) — that module doesn't exist in the new `mithril-lynx`, so this template was rewritten from scratch around [`mithril-lynx/route`](https://github.com/carlos-sweb/mithril-lynx/blob/main/ROUTE.md) instead. Everything else (Hello World, Blank, the Android host) ports over unchanged, since none of it depended on the part of the framework that got rewritten.
 
 ## Usage
 
@@ -10,20 +12,20 @@ It can also generate the **native Android host** — the whole Gradle project th
 npm create mithril-lynx@latest
 ```
 
-Prompts for a project name, a template, and a variant (TypeScript or JavaScript), scaffolds it, and offers to install dependencies for you.
+Prompts for a project name and a template, scaffolds it, and offers to install dependencies for you.
 
 ### Non-interactive
 
 ```bash
-npx create-mithril-lynx my-app --hello-world --ts
-npx create-mithril-lynx my-app --basic-activity --js --no-install
+npx create-mithril-lynx my-app --hello-world
+npx create-mithril-lynx my-app --basic-activity --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
+npx create-mithril-lynx my-app --blank --android
 
 cd my-app
 npm install
@@ -42,13 +44,12 @@ Every flag, in one table — `npx create-mithril-lynx --help` prints the same li
 |---|---|
 | `<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). |
+| `--with-font <file.ttf>` | Copy the font into the host's assets, generate `AssetFontFaceLoader.kt`, and wire the cold-start `prefetchFont()` hack. |
 | `--font-family <name>` | Override the family name derived from the font's file name. Only meaningful with `--with-font`. |
 
 Anything not listed — in particular the four Android flags — requires `--android`
@@ -56,11 +57,11 @@ Anything not listed — in particular the four Android flags — requires `--and
 
 ### 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 sibling `<name>-android/` project is a complete, no-Android-Studio Gradle CLI project, including:
 
-- the Gradle wrapper (`gradlew`, `gradlew.bat`, `gradle-wrapper.jar`), so nothing needs to be installed besides a JDK 17 and the Android SDK;
+- 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` (log service registered), `MainActivity` (async `AssetTemplateProvider`, splash screen, `XElementBehaviors`), and the font loader when `--with-font` is used;
+- the Kotlin host: the `Application`, `MainActivity` (async `AssetTemplateProvider`, splash screen), 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`.
 
@@ -74,20 +75,15 @@ npm run android:sync       # build + sync bundle into app/src/main/assets/, no G
 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.
+
 ## 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`. |
+| **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. |
 
 ## Package structure
 
@@ -97,31 +93,33 @@ create-mithril-lynx/
   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
+      ts/                    lynx.config.ts, tsconfig*, package.json, main-thread.ts,
+                              background.ts (single-view mount) — shared by every
+                              template that doesn't override background.ts itself
     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
+      ts/src/{app-bar.ts, background.ts, screens/{home,detail}.ts}
     android/                 only used with --android
       host/                  the Gradle project -> <name>-android/
       font/AssetFontFaceLoader.kt   copied only when --with-font is used
       app-scripts/android.mjs       the bridge -> <name>/scripts/android.mjs
 ```
 
-`src/index.js` copies, in order, `templates/_shared/common` → `templates/_shared/<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`.
+`src/index.js` copies, in order, `templates/_shared/common` → `templates/_shared/ts` → `templates/<template>/common` → `templates/<template>/ts` into the target directory — later copies overwrite same-named files from earlier ones, which is exactly how **Basic Activity**'s own routing-based `src/background.ts` replaces `_shared/ts`'s generic single-view one (Hello World and Blank don't ship their own, so they keep the shared file). It then renames `gitignore` to `.gitignore` (npm doesn't publish dotfiles reliably otherwise) and replaces `{{PROJECT_NAME}}`/`{{MITHRIL_LYNX_VERSION}}` placeholders in `package.json` and `README.md`.
 
 With `--android` it then copies `templates/android/host` into a sibling `<name>-android/` (renaming `package-path` to the real package directory and `App.kt` to the Application class), substitutes `{{PACKAGE_NAME}}`, `{{APP_CLASS}}`, `{{APP_NAME}}`, `{{ANDROID_DIR}}` and `{{SDK_DIR}}` across the tree, and fills in the four font-hack hooks (`{{FONT_LOADER_IMPORT}}`, `{{FONT_LOADER_REGISTRATION}}`, `{{FONT_IMPORT}}`, `{{FONT_PREFETCH}}`) with either the real code or nothing at all. Binary files (the Gradle wrapper jar, the `.ttf`) are never text-substituted.
 
-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.
+**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.
+
+## Testing
+
+All three templates are verified end to end: scaffolded non-interactively, `npm install`ed against the real published `mithril-lynx`/`mithril-runtime` packages, and type-checked with `tsc -b` — not just copied and assumed correct.
 
 ## License
 

package/package.json

@@ -1,17 +1,9 @@
 {
   "name": "create-mithril-lynx",
-  "version": "0.1.1",
-  "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.",
+  "version": "2.0.0",
+  "description": "Scaffolds a new mithril-lynx app (and, optionally, its Android host).",
   "license": "MIT",
   "type": "module",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/carlos-sweb/create-mithril-lynx.git"
-  },
-  "homepage": "https://github.com/carlos-sweb/create-mithril-lynx#readme",
-  "bugs": {
-    "url": "https://github.com/carlos-sweb/create-mithril-lynx/issues"
-  },
   "bin": {
     "create-mithril-lynx": "src/index.js"
   },
@@ -19,10 +11,10 @@
     "src",
     "templates"
   ],
-  "engines": {
-    "node": "^20.19.0 || >=22.12.0"
-  },
   "dependencies": {
     "@clack/prompts": "^1.8.0"
+  },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
   }
 }

package/src/index.js

@@ -10,19 +10,14 @@ 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.
-//
-// This used to be "0.0.2" (what was needed when the "basic-activity" template
-// was added, since that one needs mithril-lynx/navigation). It now tracks the
-// current release: a fresh scaffold shouldn't start five releases behind.
-// Verified by generating with --ts --blank and --js --basic-activity,
-// installing, and building the APK (debug and release).
+// The mithril-lynx version pinned in the generated package.json — tracks
+// the current release, same policy as this tool's own v1.
 const MITHRIL_LYNX_VERSION = "latest";
 
 const TEMPLATES = [
 	{ value: "hello-world", label: "Hello World", hint: "recommended" },
 	{ value: "blank", label: "Blank" },
-	{ value: "basic-activity", label: "Basic Activity", hint: "multi-screen navigation" },
+	{ value: "basic-activity", label: "Basic Activity", hint: "multi-screen routing" },
 ];
 const TEMPLATE_VALUES = TEMPLATES.map((t) => t.value);
 
@@ -74,11 +69,10 @@ function replaceInFile(filePath, replacements) {
 }
 
 /** Applies substitutions across a whole tree, skipping binaries. */
-function replaceInTree(dir, replacements, { onlyExtensions } = {}) {
+function replaceInTree(dir, replacements) {
 	for (const file of walkFiles(dir)) {
 		const ext = path.extname(file).toLowerCase();
 		if (BINARY_EXTENSIONS.has(ext)) continue;
-		if (onlyExtensions && !onlyExtensions.has(path.basename(file)) && !onlyExtensions.has(ext)) continue;
 		replaceInFile(file, replacements);
 	}
 }
@@ -157,7 +151,7 @@ function findAndroidSdk() {
 }
 
 // ---------------------------------------------------------------------------
-// Parseo de argumentos
+// Argument parsing
 // ---------------------------------------------------------------------------
 
 function readOption(args, name) {
@@ -303,8 +297,8 @@ function scaffoldAndroid({ targetDir, rawName, options }) {
 		// best-effort
 	}
 
-	// 2. The .ttf (Part D of the guide) is opt-in: without it neither the
-	//    loader nor the prefetch is generated, so no dead code is left behind.
+	// 2. The .ttf is opt-in: without it neither the loader nor the prefetch is
+	//    generated, so no dead code is left behind.
 	if (font != null) {
 		const fontsDir = path.join(androidDir, "app", "src", "main", "assets", "fonts");
 		fs.mkdirSync(fontsDir, { recursive: true });
@@ -357,8 +351,7 @@ function scaffoldAndroid({ targetDir, rawName, options }) {
 						"// renderTemplateUrl() gives the bundle's CSS a chance to resolve",
 						"// @font-face during the first layout. FontFaceManager caches by the",
 						"// exact src string, so this URI has to be identical to the",
-						'// url("...") of the @font-face in src/style.css — see Part D of',
-						"// ANDROID_APK_GUIDE.md.",
+						'// url("...") of the @font-face in src/style.css.',
 						"FontFaceManager.getInstance().prefetchFont(",
 						"    lynxView.lynxContext,",
 						`    "${sourceUri}",`,
@@ -417,8 +410,8 @@ function patchJsProject({ targetDir, android }) {
 	if (android.font != null) {
 		const cssPath = path.join(targetDir, "src", "style.css");
 		const block = [
-			"/* Part D of ANDROID_APK_GUIDE.md: the font lives in the Android host's",
-			"   assets (app/src/main/assets/fonts/), not in the bundle. The asset:///",
+			"/* The font lives in the Android host's assets",
+			"   (app/src/main/assets/fonts/), not in the bundle. The asset:///",
 			"   string has to be identical to the one in MainActivity.kt's prefetchFont()",
 			"   or Lynx won't find the warmed Typeface. */",
 			"@font-face {",
@@ -453,12 +446,9 @@ function patchJsProject({ targetDir, android }) {
 			`- Application ID: \`${android.androidId}\``,
 			`- Application class: \`${android.appClass}\` · Activity: \`MainActivity\``,
 			...(android.font != null
-				? [`- Font \`${android.font.family}\` prefetched from \`asset:///fonts/${android.font.file}\` (the cold-start hack, Part D of the guide).`]
+				? [`- Font \`${android.font.family}\` prefetched from \`asset:///fonts/${android.font.file}\` (the cold-start hack).`]
 				: []),
 			"",
-			"The full procedure — including why each Gradle dependency is there and how to measure",
-			"cold start — is in [`mithril-lynx`'s ANDROID_APK_GUIDE.md](https://github.com/carlos-sweb/mithril-lynx/blob/main/ANDROID_APK_GUIDE.md).",
-			"",
 		].join("\n");
 		fs.appendFileSync(readmePath, section);
 	}
@@ -471,15 +461,12 @@ 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> --ts --blank --android
+  npx create-mithril-lynx <name> --blank --android
 
 Template (prompted for if omitted):
   --hello-world | --blank | --basic-activity
 
-Variant:
-  --ts | --js
-
-Android host (see mithril-lynx's ANDROID_APK_GUIDE.md):
+Android host:
   --android, --target android, target=android
                             scaffold the sibling Gradle project <name>-android/
   --android-id <id>         applicationId / namespace (default com.example.<name>)
@@ -496,10 +483,10 @@ Other:
 
 async function main() {
 	// Non-interactive escape hatch for scripting/CI:
-	//   create-mithril-lynx my-app --ts --hello-world
-	//   create-mithril-lynx my-app --js --basic-activity --no-install
-	//   create-mithril-lynx my-app --ts --blank --android --android-id com.acme.miapp
-	//   create-mithril-lynx my-app --ts --blank --with-font ./UbuntuMono-Regular.ttf
+	//   create-mithril-lynx my-app --hello-world
+	//   create-mithril-lynx my-app --basic-activity --no-install
+	//   create-mithril-lynx my-app --blank --android --android-id com.acme.miapp
+	//   create-mithril-lynx my-app --blank --with-font ./UbuntuMono-Regular.ttf
 	const args = process.argv.slice(2);
 
 	if (args.includes("--help") || args.includes("-h")) {
@@ -508,10 +495,9 @@ async function main() {
 	}
 
 	const positional = findPositional(args);
-	const variantFlag = args.includes("--ts") ? "ts" : args.includes("--js") ? "js" : undefined;
 	const templateFlag = TEMPLATE_VALUES.find((t) => args.includes(`--${t}`));
 	const noInstall = args.includes("--no-install");
-	const nonInteractive = positional != null && variantFlag != null && templateFlag != null;
+	const nonInteractive = positional != null && templateFlag != null;
 	const android = parseAndroidArgs(args);
 
 	// --with-font/--font-family only make sense with an Android host: imply it
@@ -554,18 +540,6 @@ async function main() {
 		if (isCancel(template)) return bail();
 	}
 
-	let variant = variantFlag;
-	if (variant == null) {
-		variant = await select({
-			message: "Select a variant",
-			options: [
-				{ value: "ts", label: "TypeScript", hint: "recommended" },
-				{ value: "js", label: "JavaScript" },
-			],
-		});
-		if (isCancel(variant)) return bail();
-	}
-
 	let withAndroid = android.requested;
 	if (!withAndroid && !nonInteractive) {
 		withAndroid = await confirm({
@@ -585,12 +559,15 @@ async function main() {
 	fs.mkdirSync(targetDir, { recursive: true });
 
 	// Layered copy: shared build plumbing (gitignore/README, then
-	// lynx.config/tsconfig/main-thread for the chosen variant), then the
-	// chosen template's own app content (style.css/assets, then src/index).
+	// lynx.config/tsconfig/main-thread/background), then the chosen
+	// template's own app content (style.css/assets, then src). A template's
+	// own src/background.ts (basic-activity's — routing-based) overwrites
+	// the shared single-view one; hello-world/blank don't ship one, so the
+	// shared file is what they get.
 	copyDir(path.join(packageRoot, "templates/_shared/common"), targetDir);
-	copyDir(path.join(packageRoot, "templates/_shared", variant), targetDir);
+	copyDir(path.join(packageRoot, "templates/_shared/ts"), targetDir);
 	copyDir(path.join(packageRoot, "templates", template, "common"), targetDir);
-	copyDir(path.join(packageRoot, "templates", template, variant), targetDir);
+	copyDir(path.join(packageRoot, "templates", template, "ts"), targetDir);
 
 	const gitignorePath = path.join(targetDir, "gitignore");
 	if (fs.existsSync(gitignorePath)) {

package/templates/_shared/common/README.md

@@ -6,12 +6,12 @@ A [Lynx](https://lynxjs.org) app built with [Mithril.js](https://mithril.js.org)
 
 ```bash
 npm install
-npm run dev      # scan the printed QR code with LynxExplorer
-npm run build     # production bundle, in dist/
+npm run dev      # scan the printed QR code with LynxExplorer, or open it in Lynx Go
+npm run build    # production bundle, in dist/
 ```
 
 ## Learn more
 
-- `src/main-thread.{js,ts}` wires the app up using **main-thread-owned mode**, the simplest of `mithril-lynx`'s three rendering modes.
-- `src/index.{js,ts}` is the app itself — plain Mithril hyperscript, no JSX, no virtual DOM beyond what Mithril already does.
-- Everything about the framework — the three rendering modes, refs, gestures, list virtualization, cross-thread calls — is documented in [`mithril-lynx`'s own README](https://github.com/carlos-sweb/mithril-lynx#readme).
+- `src/main-thread.ts` starts the main-thread patch-replay runtime (`setupRenderer()`) — mithril-lynx has exactly one rendering mode, so no app code lives here.
+- `src/background.ts` is where the app actually mounts (`renderApp()`), running the real Mithril view tree in the background thread.
+- Everything about the framework — the three reload modes, routing, networking — is documented in [`mithril-lynx`'s own README](https://github.com/carlos-sweb/mithril-lynx#readme).

package/templates/_shared/ts/lynx.config.ts

@@ -27,7 +27,13 @@ export default defineConfig({
   },
   plugins: [
     pluginMithrilLynx(),
-    pluginLynxConfig({}),
+    // enableNewGesture: the native gesture arena (mithril-lynx/gesture, once
+    // it exists, needs this on — off by default, and __SetGestureDetector
+    // calls are silently inert without it).
+    // enableCSSRule: CSS selector rules beyond a single class/type match —
+    // confirmed needed for a plain `:root { ... }` rule (used by every
+    // template's style.css) to actually apply on a real device.
+    pluginLynxConfig({ enableNewGesture: true, enableCSSRule: true }),
     pluginQRCode({
       schema(url) {
         // Opens the page in LynxExplorer in full screen mode.

package/templates/_shared/ts/package.json

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

package/templates/_shared/ts/src/background.ts

@@ -0,0 +1,35 @@
+// src/background.ts
+//
+// The stable-host pattern: `host` never changes identity across a
+// hot-update, so Mithril never unmounts/remounts it; `currentView` is a
+// live binding re-pointed by `module.hot.accept`. This is what lets
+// editing `index.ts` hot-reload in place without losing an `<input>`'s
+// focus or in-progress text.
+
+import m from "mithril-runtime";
+import { renderApp } from "mithril-lynx/background";
+import * as indexModule from "./index.js";
+
+let currentView: typeof indexModule = indexModule;
+
+const host: m.Component = {
+	view() {
+		return currentView.view();
+	},
+};
+
+const app = renderApp({ root: () => m(host) });
+
+declare const module: {
+	hot?: {
+		accept(path: string, callback: () => void): void;
+	};
+};
+declare const require: (id: string) => typeof indexModule;
+
+if (module.hot) {
+	module.hot.accept("./index.js", () => {
+		currentView = require("./index.js");
+		app.redraw();
+	});
+}

package/templates/_shared/ts/src/main-thread.ts

@@ -1,20 +1,9 @@
-import shim from "mithril-lynx";
-import app from "./index.js";
+// src/main-thread.ts
+//
+// No app code here — mithril-lynx has exactly one rendering mode: all
+// view logic runs in background.ts, this just starts the main-thread
+// patch-replay runtime.
 
-// The native engine unconditionally invokes a global processData(initData)
-// hook on every __RenderPage/__UpdatePage — install a pass-through default.
-// (mithril-lynx/main-thread's setupApp() does this for you in data-channel
-// mode; this bare main-thread-owned pattern doesn't go through that module.)
-Object.assign(globalThis, {
-  processData: (data: unknown) => data,
-});
+import { setupRenderer } from "mithril-lynx/main-thread";
 
-// Main-thread-owned mode — the simplest of mithril-lynx's three rendering
-// modes: no background.ts, no dual-bundle build. The app renders directly
-// on the main thread, synchronously, on first paint; every later update
-// flows through shim.redraw(), called from event handlers bound via
-// Mithril's own on* attrs (see src/index.ts).
-lynx.getEngine().addEventListener("__RenderPage", () => {
-  const page = __CreatePage("0", 0);
-  shim.renderToPage(page, app.root);
-});
+setupRenderer();

package/templates/_shared/ts/src/mithril-runtime.d.ts

@@ -0,0 +1,10 @@
+// "mithril-runtime" (https://github.com/carlos-sweb/mithril-runtime) has no
+// types of its own yet — it's a same-shaped subset of real Mithril (m.route/
+// m.trust/m.request removed, see that repo's README and tests). Reusing
+// @types/mithril here is a deliberate approximation: it still types
+// m.route/m.trust/m.request as present, which mithril-runtime doesn't have
+// — don't reference those from app code; nothing in this app does.
+declare module "mithril-runtime" {
+	import m from "mithril";
+	export = m;
+}

package/templates/_shared/ts/tsconfig.json

@@ -7,9 +7,6 @@
     "esModuleInterop": true,
     "skipLibCheck": true,
 
-    // Explicit, not left to the TS-version-dependent default (which can be
-    // as old as ES3 and lacks e.g. Object.assign) — confirmed necessary
-    // by a real build failure with a newer/older typescript version.
     "target": "ES2022",
     "lib": ["ES2023"]
   },

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

@@ -0,0 +1,13 @@
+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.
+export function AppBar(title: string, onBack?: () => void) {
+	return m("view", { class: "AppBar" }, [
+		onBack != null ? m("text", { class: "AppBar-back", ontap: onBack }, "←") : null,
+		m("text", { class: "AppBar-title" }, title),
+	]);
+}

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

@@ -0,0 +1,40 @@
+// src/background.ts
+//
+// A stable-host wrapper PER SCREEN, so a hot-update never unmounts/
+// remounts either screen — `current*` is a live binding re-pointed by
+// `module.hot.accept`, read fresh on every redraw. route(...) (mithril-lynx/
+// route) is what actually mounts the app — it calls renderApp() internally
+// the first time a route resolves, so this file never calls it directly.
+
+import route from "mithril-lynx/route";
+import * as homeModule from "./screens/home.js";
+import * as detailModule from "./screens/detail.js";
+
+let currentHome: typeof homeModule = homeModule;
+let currentDetail: typeof detailModule = detailModule;
+
+const HomeHost = { view: () => currentHome.view() };
+const DetailHost = { view: () => currentDetail.view() };
+
+route("/", {
+	"/": HomeHost,
+	"/detail": DetailHost,
+});
+
+declare const module: {
+	hot?: {
+		accept(path: string, callback: () => void): void;
+	};
+};
+declare const require: (id: string) => unknown;
+
+if (module.hot) {
+	module.hot.accept("./screens/home.js", () => {
+		currentHome = require("./screens/home.js") as typeof homeModule;
+		route.set(route.get() ?? "/", null, { replace: true });
+	});
+	module.hot.accept("./screens/detail.js", () => {
+		currentDetail = require("./screens/detail.js") as typeof detailModule;
+		route.set(route.get() ?? "/", null, { replace: true });
+	});
+}

package/templates/basic-activity/ts/src/screens/detail.ts

@@ -0,0 +1,12 @@
+import m from "mithril-runtime";
+import route from "mithril-lynx/route";
+import { AppBar } from "../app-bar.js";
+
+export function view() {
+	return m("view", { class: "Page" }, [
+		AppBar("Details", () => route.back()),
+		m("view", { class: "Content" }, [
+			m("text", { class: "Description" }, String(route.param("message") ?? "")),
+		]),
+	]);
+}

package/templates/basic-activity/ts/src/screens/home.ts

@@ -0,0 +1,17 @@
+import m from "mithril-runtime";
+import route from "mithril-lynx/route";
+import { AppBar } from "../app-bar.js";
+
+export function view() {
+	return m("view", { class: "Page" }, [
+		AppBar("Basic Activity"),
+		m("view", { class: "Content" }, [
+			m("text", { class: "Description" }, "This is the main screen."),
+			m(
+				route.Link,
+				{ href: "/detail", params: { message: "Hello from the main screen!" }, selector: "view", class: "Button" },
+				[m("text", { class: "Button-label" }, "Next")],
+			),
+		]),
+	]);
+}

package/templates/blank/ts/src/index.ts

@@ -1,11 +1,7 @@
-import m from "mithril";
+import m from "mithril-runtime";
 
-const App: m.Component = {
-  view() {
-    return m("view", { class: "Page" }, [
-      m("text", { class: "Title" }, "Hello, mithril-lynx!"),
-    ]);
-  },
-};
-
-export default { App, root: m(App) };
+export function view() {
+	return m("view", { class: "Page" }, [
+		m("text", { class: "Title" }, "Hello, mithril-lynx!"),
+	]);
+}

package/templates/hello-world/ts/src/index.ts

@@ -1,5 +1,4 @@
-import shim from "mithril-lynx";
-import m from "mithril";
+import m from "mithril-runtime";
 
 import lynxLogo from "./assets/lynx-logo.png";
 import mithrilLogo from "./assets/mithril-logo.png";
@@ -7,41 +6,36 @@ import arrow from "./assets/arrow.png";
 
 let alterLogo = false;
 
-const App: m.Component = {
-  view() {
-    return [
-      m("view", { class: "Background" }),
-      m("view", { class: "App" }, [
-        m("view", { class: "Banner" }, [
-          m("view", {
-            class: "Logo",
-            // shim.redraw() — NOT mithril's own m.redraw(), which is a
-            // no-op in this shim-based architecture.
-            ontap: () => {
-              alterLogo = !alterLogo;
-              shim.redraw();
-            },
-          }, [
-            alterLogo
-              ? m("image", { src: mithrilLogo, class: "Logo--mithril" })
-              : m("image", { src: lynxLogo, class: "Logo--lynx" }),
-          ]),
-          m("text", { class: "Title" }, "Mithril"),
-          m("text", { class: "Subtitle" }, "on Lynx"),
-        ]),
-        m("view", { class: "Content" }, [
-          m("image", { src: arrow, class: "Arrow" }),
-          m("text", { class: "Description" }, "Tap the logo and have fun!"),
-          m("text", { class: "Hint" }, [
-            "Edit ",
-            m("text", { style: { fontStyle: "italic", color: "rgba(255, 255, 255, 0.85)" } }, "src/index.ts"),
-            " to see updates!",
-          ]),
-        ]),
-        m("view", { style: { flex: 1 } }),
-      ]),
-    ];
-  },
-};
-
-export default { App, root: m(App) };
+export function view() {
+	return [
+		m("view", { class: "Background" }),
+		m("view", { class: "App" }, [
+			m("view", { class: "Banner" }, [
+				m("view", {
+					class: "Logo",
+					// No explicit redraw() call here — mithril-lynx repaints
+					// automatically after any event, so mutating state is enough.
+					ontap: () => {
+						alterLogo = !alterLogo;
+					},
+				}, [
+					alterLogo
+						? m("image", { src: mithrilLogo, class: "Logo--mithril" })
+						: m("image", { src: lynxLogo, class: "Logo--lynx" }),
+				]),
+				m("text", { class: "Title" }, "Mithril"),
+				m("text", { class: "Subtitle" }, "on Lynx"),
+			]),
+			m("view", { class: "Content" }, [
+				m("image", { src: arrow, class: "Arrow" }),
+				m("text", { class: "Description" }, "Tap the logo and have fun!"),
+				m("text", { class: "Hint" }, [
+					"Edit ",
+					m("text", { style: { fontStyle: "italic", color: "rgba(255, 255, 255, 0.85)" } }, "src/index.ts"),
+					" to see updates!",
+				]),
+			]),
+			m("view", { style: { flex: 1 } }),
+		]),
+	];
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 carlos-sweb
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/templates/_shared/js/lynx.config.js

@@ -1,37 +0,0 @@
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-
-import { pluginLynxConfig } from "@lynx-js/config-rsbuild-plugin";
-import { pluginQRCode } from "@lynx-js/qrcode-rsbuild-plugin";
-import { defineConfig } from "@lynx-js/rspeedy";
-
-import { pluginMithrilLynx } from "mithril-lynx/plugin";
-
-const projectRoot = path.dirname(fileURLToPath(import.meta.url));
-
-export default defineConfig({
-  source: {
-    entry: {
-      "main-thread": path.join(projectRoot, "src/main-thread.js"),
-    },
-  },
-  output: {
-    distPath: {
-      root: path.join(projectRoot, "dist"),
-    },
-    filename: "[name].bundle",
-    // Lynx bundles are self-contained — image imports must be inlined as
-    // data URIs rather than left as separate file references.
-    dataUriLimit: Infinity,
-  },
-  plugins: [
-    pluginMithrilLynx(),
-    pluginLynxConfig({}),
-    pluginQRCode({
-      schema(url) {
-        // Opens the page in LynxExplorer in full screen mode.
-        return `${url}?fullscreen=true`;
-      },
-    }),
-  ],
-});

package/templates/_shared/js/package.json

@@ -1,26 +0,0 @@
-{
-  "name": "{{PROJECT_NAME}}",
-  "version": "0.0.1",
-  "private": true,
-  "type": "module",
-  "scripts": {
-    "dev": "rspeedy dev",
-    "build": "rspeedy build",
-    "preview": "rspeedy preview"
-  },
-  "dependencies": {
-    "mithril": "2.3.8",
-    "mithril-lynx": "{{MITHRIL_LYNX_VERSION}}"
-  },
-  "devDependencies": {
-    "@lynx-js/config-rsbuild-plugin": "^0.2.0",
-    "@lynx-js/qrcode-rsbuild-plugin": "^0.7.0",
-    "@lynx-js/rspeedy": "^0.17.0",
-    "@lynx-js/template-webpack-plugin": "^0.16.0",
-    "@lynx-js/type-element-api": "0.0.9",
-    "@lynx-js/types": "4.1.0"
-  },
-  "engines": {
-    "node": "^20.19.0 || >=22.12.0"
-  }
-}

package/templates/_shared/js/src/main-thread.js

@@ -1,20 +0,0 @@
-import shim from "mithril-lynx";
-import app from "./index.js";
-
-// The native engine unconditionally invokes a global processData(initData)
-// hook on every __RenderPage/__UpdatePage — install a pass-through default.
-// (mithril-lynx/main-thread's setupApp() does this for you in data-channel
-// mode; this bare main-thread-owned pattern doesn't go through that module.)
-Object.assign(globalThis, {
-  processData: (data) => data,
-});
-
-// Main-thread-owned mode — the simplest of mithril-lynx's three rendering
-// modes: no background.js, no dual-bundle build. The app renders directly
-// on the main thread, synchronously, on first paint; every later update
-// flows through shim.redraw(), called from event handlers bound via
-// Mithril's own on* attrs (see src/index.js).
-lynx.getEngine().addEventListener("__RenderPage", () => {
-  const page = __CreatePage("0", 0);
-  shim.renderToPage(page, app.root);
-});

package/templates/basic-activity/js/src/index.js

@@ -1,43 +0,0 @@
-import m from "mithril";
-import { createNavigator } from "mithril-lynx/navigation";
-
-// A reusable app bar: a title, plus a back affordance when `onBack` is
-// given. No m.route involved anywhere in this file — see
-// mithril-lynx/navigation's own docs for why (Lynx pages have no URL to
-// route to). Navigation here is a plain in-memory stack.
-function AppBar(title, onBack) {
-  return m("view", { class: "AppBar" }, [
-    onBack != null ? m("text", { class: "AppBar-back", ontap: onBack }, "←") : null,
-    m("text", { class: "AppBar-title" }, title),
-  ]);
-}
-
-const MainScreen = {
-  view(vnode) {
-    return m("view", { class: "Page" }, [
-      AppBar("Basic Activity"),
-      m("view", { class: "Content" }, [
-        m("text", { class: "Description" }, "This is the main screen."),
-        m("view", {
-          class: "Button",
-          ontap: () => vnode.attrs.nav.push(DetailsScreen, { message: "Hello from MainScreen!" }),
-        }, [m("text", { class: "Button-label" }, "Next")]),
-      ]),
-    ]);
-  },
-};
-
-const DetailsScreen = {
-  view(vnode) {
-    return m("view", { class: "Page" }, [
-      AppBar("Details", () => vnode.attrs.nav.pop()),
-      m("view", { class: "Content" }, [
-        m("text", { class: "Description" }, vnode.attrs.message),
-      ]),
-    ]);
-  },
-};
-
-const nav = createNavigator({ initial: MainScreen });
-
-export default { root: m(nav.Navigator) };

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

@@ -1,48 +0,0 @@
-import m from "mithril";
-import { createNavigator, type Nav } from "mithril-lynx/navigation";
-
-interface DetailsAttrs {
-  nav: Nav;
-  message: string;
-}
-
-// A reusable app bar: a title, plus a back affordance when `onBack` is
-// given. No m.route involved anywhere in this file — see
-// mithril-lynx/navigation's own docs for why (Lynx pages have no URL to
-// route to). Navigation here is a plain in-memory stack.
-function AppBar(title: string, onBack?: () => void) {
-  return m("view", { class: "AppBar" }, [
-    onBack != null ? m("text", { class: "AppBar-back", ontap: onBack }, "←") : null,
-    m("text", { class: "AppBar-title" }, title),
-  ]);
-}
-
-const MainScreen: m.Component<{ nav: Nav }> = {
-  view(vnode) {
-    return m("view", { class: "Page" }, [
-      AppBar("Basic Activity"),
-      m("view", { class: "Content" }, [
-        m("text", { class: "Description" }, "This is the main screen."),
-        m("view", {
-          class: "Button",
-          ontap: () => vnode.attrs.nav.push(DetailsScreen, { message: "Hello from MainScreen!" }),
-        }, [m("text", { class: "Button-label" }, "Next")]),
-      ]),
-    ]);
-  },
-};
-
-const DetailsScreen: m.Component<DetailsAttrs> = {
-  view(vnode) {
-    return m("view", { class: "Page" }, [
-      AppBar("Details", () => vnode.attrs.nav.pop()),
-      m("view", { class: "Content" }, [
-        m("text", { class: "Description" }, vnode.attrs.message),
-      ]),
-    ]);
-  },
-};
-
-const nav = createNavigator({ initial: MainScreen });
-
-export default { root: m(nav.Navigator) };

package/templates/blank/js/src/index.js

@@ -1,11 +0,0 @@
-import m from "mithril";
-
-const App = {
-  view() {
-    return m("view", { class: "Page" }, [
-      m("text", { class: "Title" }, "Hello, mithril-lynx!"),
-    ]);
-  },
-};
-
-export default { App, root: m(App) };

package/templates/hello-world/js/src/index.js

@@ -1,47 +0,0 @@
-import shim from "mithril-lynx";
-import m from "mithril";
-
-import lynxLogo from "./assets/lynx-logo.png";
-import mithrilLogo from "./assets/mithril-logo.png";
-import arrow from "./assets/arrow.png";
-
-let alterLogo = false;
-
-const App = {
-  view() {
-    return [
-      m("view", { class: "Background" }),
-      m("view", { class: "App" }, [
-        m("view", { class: "Banner" }, [
-          m("view", {
-            class: "Logo",
-            // shim.redraw() — NOT mithril's own m.redraw(), which is a
-            // no-op in this shim-based architecture.
-            ontap: () => {
-              alterLogo = !alterLogo;
-              shim.redraw();
-            },
-          }, [
-            alterLogo
-              ? m("image", { src: mithrilLogo, class: "Logo--mithril" })
-              : m("image", { src: lynxLogo, class: "Logo--lynx" }),
-          ]),
-          m("text", { class: "Title" }, "Mithril"),
-          m("text", { class: "Subtitle" }, "on Lynx"),
-        ]),
-        m("view", { class: "Content" }, [
-          m("image", { src: arrow, class: "Arrow" }),
-          m("text", { class: "Description" }, "Tap the logo and have fun!"),
-          m("text", { class: "Hint" }, [
-            "Edit ",
-            m("text", { style: { fontStyle: "italic", color: "rgba(255, 255, 255, 0.85)" } }, "src/index.js"),
-            " to see updates!",
-          ]),
-        ]),
-        m("view", { style: { flex: 1 } }),
-      ]),
-    ];
-  },
-};
-
-export default { App, root: m(App) };