mithril-lynx 0.0.2 → 0.0.4

package/README.md

@@ -2,6 +2,14 @@
 
 Mithril.js rendered through [Lynx](https://lynxjs.org)'s Element PAPI — the core runtime layer of a Mithril-based alternative to [`@lynx-js/react`](https://lynxjs.org/react/).
 
+## Getting started
+
+```bash
+npm create mithril-lynx@latest
+```
+
+Scaffolds a new app via [`create-mithril-lynx`](https://github.com/carlos-sweb/create-mithril-lynx) — pick **Hello World** (a tap-to-animate logo demo, the Mithril analog of Lynx's own React hello-world), **Blank** (a single line of text, nothing else), or **Basic Activity** (two screens wired with `mithril-lynx/navigation`, confirmed working end to end on a real device), in TypeScript or JavaScript. That's the fastest way to a running app; the rest of this README documents the framework itself for once you're inside one.
+
 ## What this package is
 
 `src/lynx-mithril-shim.js` is a contract-complete, line-by-line port of `mithril/render/render.js@2.3.8`: the exact same diff algorithm (`createNode`/`updateNodes`/`updateNode`/keyed-diff-with-LIS/etc.) as upstream Mithril, with every DOM call it makes redirected onto Lynx's Element PAPI (`__CreateView`, `__AppendElement`, `__SetAttribute`, `__SetInlineStyles`, `__AddEventListener`, ...) instead of the browser DOM. See `CONTRACT.md` for the exhaustive, reverse-engineered spec of exactly which DOM surface Mithril's renderer touches — that document is the reference this shim is built and validated against.
@@ -35,7 +43,7 @@ engine.addEventListener("__RenderPage", () => {
 });
 ```
 
-Subsequent UI updates flow through `shim.redraw()` (called automatically by event handlers bound via Mithril's own `on*` attrs, since the shim ports Mithril's `EventDict`/redraw machinery verbatim) — **never plain `m.redraw()`**, which is a no-op in this shim-based architecture.
+Subsequent UI updates flow through `shim.redraw()` — **never plain `m.redraw()`**, which is a no-op in this shim-based architecture, and **never automatically after an `on*` handler either**: every event the shim hands to a handler is normalized with `redraw: false` on purpose (confirmed on real hardware 2026-09-10 — an `ontap` handler that only mutates local main-thread state, with no round trip through a data-channel/renderer-mode push, silently doesn't repaint until `shim.redraw()` is called from inside the handler itself; no error is thrown, since Mithril's own `EventDict.handleEvent` just skips the auto-redraw when `ev.redraw === false`). This is deliberate — a real DOM redraws cheaply enough that auto-redraw-per-event is a reasonable default there; a full Lynx PAPI diff pass on every touch event is not something to default to. `mithril-lynx/navigation`'s `push`/`pop`/`replace` already do this internally (see its source), which is why call sites using only that module never need to think about it.
 
 ## Usage — data-channel mode
 
@@ -235,6 +243,32 @@ Built on `shim.redraw()` alone, so it works unmodified in all three rendering mo
 
 **Deliberately out of scope for v1**: screen transition animations (left entirely to the app's own CSS/styling on whatever wraps `nav.Navigator`), and hardware back-button integration (no documented Lynx PAPI hook for it was found — wire a screen's own back-affordance to `nav.pop()` instead, as in the example above).
 
+## Custom fonts
+
+Use a plain CSS `@font-face` rule — not `lynx.addFont()`. That JS API (background-thread-only) is for loading a font dynamically *after* mount, matching [`lynx-family/lynx-examples`](https://github.com/lynx-family/lynx-examples)'s own `examples/text/src/custom_font`, which calls it from `componentDidMount` and re-renders via `setState` once its callback fires. For a font known at build time (the common case), `examples/text/src/font_face` is the pattern to copy — a declarative `@font-face`, no JS:
+
+```css
+@font-face {
+  font-family: "Ubuntu Mono";
+  src: url("./assets/fonts/ubuntu-mono-400.ttf");
+}
+
+@font-face {
+  font-family: "Ubuntu Mono";
+  font-weight: 700;
+  src: url("./assets/fonts/ubuntu-mono-700.ttf");
+}
+
+:root {
+  font-family: "Ubuntu Mono"; /* needs enableCSSInheritance, see below */
+}
+```
+
+Two gotchas, both confirmed on real hardware 2026-09-10:
+
+- **The font file must be `.ttf`, not `.woff2`.** A `.woff2` `@font-face` compiles fine — a valid `url('data:font/woff2;base64,...')` lands in the bundle, no build error, no runtime error — but the native text renderer silently never applies it, even with a maximally-distinctive test font (swapping the default sans-serif for a cursive/marker-style face produced zero visual change). Re-pointing the exact same rule at a `.ttf` of the same font worked immediately, no other change needed. Fontsource-distributed packages only ship woff/woff2; get a `.ttf` from the font's original source instead (e.g. [`google/fonts`](https://github.com/google/fonts) for anything Google-Fonts-hosted).
+- **`font-family` set on `:root` (or any ancestor) does not cascade to descendants by default.** `@lynx-js/config-rsbuild-plugin`'s `pluginLynxConfig()` has an `enableCSSInheritance` option that's off unless set explicitly; without it, only the exact element the property is set on gets it — confirmed by setting `font-family: serif` on `:root` and seeing zero change anywhere in the tree. Turn it on (`pluginLynxConfig({ enableCSSInheritance: true })` in `lynx.config.ts`) to use a single `:root` declaration instead of repeating `font-family` on every class.
+
 ## Known permanent gaps
 
 - `m.trust` / innerHTML vnodes — no Lynx PAPI equivalent to raw innerHTML injection.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mithril-lynx",
-  "version": "0.0.2",
-  "description": "Mithril.js rendered through Lynx's Element PAPI — a contract-complete port of mithril/render/render.js@2.3.8 to the Lynx main thread, packaged as a reusable framework.",
+  "version": "0.0.4",
+  "description": "Mithril.js rendered through Lynx's Element PAPI \u2014 a contract-complete port of mithril/render/render.js@2.3.8 to the Lynx main thread, packaged as a reusable framework.",
   "license": "MIT",
   "type": "module",
   "repository": {

package/plugin.js

@@ -35,6 +35,28 @@ function findSibling(dir, candidates) {
 	return null;
 }
 
+/**
+ * Walks up from a resolved file to the root of the package that owns it,
+ * verified by name rather than assumed from the layout — this package's
+ * exports map deliberately doesn't expose ./package.json, so the usual
+ * require.resolve("<pkg>/package.json") trick isn't available here.
+ */
+function packageRootOf(resolvedFile) {
+	let dir = path.dirname(resolvedFile);
+	for (let i = 0; i < 10; i++) {
+		try {
+			const pkg = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8"));
+			if (pkg.name === "mithril-lynx") return dir;
+		} catch {
+			// keep walking
+		}
+		const parent = path.dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	return null;
+}
+
 export function pluginMithrilLynx(options = {}) {
 	const targetSdkVersion = options.targetSdkVersion ?? "3.5";
 
@@ -69,6 +91,34 @@ export function pluginMithrilLynx(options = {}) {
 					// leave resolution as-is rather than guessing.
 				}
 
+				// Same class of problem, worse symptom: mithril-lynx itself keeps
+				// per-app state in module-level variables — the shim's rootWrapper/
+				// redraw/runRender, main-thread.js's latestData and its cross-thread
+				// handler maps, background.js's mirror of those. Two physical copies
+				// means two disconnected renderers: the app renders through one, and
+				// any LIBRARY that depends on mithril-lynx (a component library, say,
+				// resolving its own nested copy once linked) calls shim.redraw() on
+				// the other — whose `redraw` is still null. That's a silent no-op:
+				// no error, nothing logged, components simply never update. Confirmed
+				// on real hardware 2026-09-11 while building mithril-lynx-ui, where
+				// it read as "the animation just doesn't run".
+				try {
+					const appRequire = createRequire(path.join(process.cwd(), "package.json"));
+					const selfDir = packageRootOf(appRequire.resolve("mithril-lynx"));
+					if (selfDir != null) {
+						// The bare specifier has to point at the entry FILE: aliasing it
+						// to the directory would bypass this package's own exports map
+						// (which has no "main" to fall back on) and fail to resolve.
+						// The prefix alias then keeps subpaths — "mithril-lynx/main-thread"
+						// and friends, which hold state of their own — on that same copy.
+						chain.resolve.alias.set("mithril-lynx$", path.join(selfDir, "src", "lynx-mithril-shim.js"));
+						chain.resolve.alias.set("mithril-lynx", selfDir);
+					}
+				} catch {
+					// App doesn't resolve mithril-lynx from its own root (it's being
+					// consumed some other way) — leave resolution alone.
+				}
+
 				const rawEntries = Object.entries(chain.entryPoints.entries() ?? {});
 				chain.entryPoints.clear();