mithril-lynx 0.0.5 → 0.0.7

package/README.md

@@ -264,10 +264,11 @@ Use a plain CSS `@font-face` rule — not `lynx.addFont()`. That JS API (backgro
 }
 ```
 
-Two gotchas, both confirmed on real hardware 2026-09-10:
+Three gotchas, all confirmed on real hardware:
 
-- **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.
+- **The font file must be `.ttf`, not `.woff2`** (2026-09-10). 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** (2026-09-10). `@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.
+- **A declarative `@font-face` resolves synchronously on the first native `__FlushElementTree()` call, and that cost scales with how many text nodes/CSS rules end up resolving it** (2026-09-10/11) — up to +2s of cold start observed on a mid/low-end device (Samsung Galaxy A07) applying a font broadly via a `text{}` type selector, root-caused via node-count bisection and a native-Android control app with zero Lynx dependencies (~30-100ms there for the same font on the same number of views). Filed upstream as [lynx-family/lynx#9431](https://github.com/lynx-family/lynx/issues/9431), which also documents a working native-side workaround (not a mithril-lynx-level fix — it lives in the consuming Android app, calling `FontFaceManager.getInstance().prefetchFont(...)` before `renderTemplateUrl()` to warm Lynx's typeface cache ahead of the JS bundle even starting): brought cold start down to ~750-800ms, indistinguishable from the fontless baseline, in `indicadores-android` (shipped there, not part of this package). Check that issue for upstream maintainer responses before re-investigating the same symptom.
 
 ## Known permanent gaps
 
@@ -286,6 +287,8 @@ Beyond hyperscript (`m(...)`) itself, only `m.fragment` and `m.censor` are used
 
 Mithril was never hooks-based, so — unlike React — there's no special rules-of-hooks compatibility story to build: `m.redraw()` after any state mutation already works with any plain-JS state library (a simple pub/sub store, streams, whatever). Nothing in this package needs to shim a specific state-management library for that reason; if something in the ecosystem doesn't work, it's not because of a hooks-equivalence gap.
 
+**The main-thread JS engine is QuickJS-based, not V8 or a browser engine** — don't assume full modern JS API coverage just because something works under `@lynx-js/testing-environment`'s jsdom polyfill (which runs on Node's V8) or in editor tooling. Confirmed missing on real hardware: `Array.prototype.at()` (ES2022) — calling it throws a generic `TypeError: not a function` with a near-useless native backtrace (no indication it's an API-support gap rather than a framework bug), and since it only fails once an array actually has content, the crash can look like a much bigger, unrelated regression than it is. This bit a consuming app (`mithril-lynx-ui`'s demo) hard enough to cost a full debugging session before being traced back to this. Use `arr[arr.length - 1]` instead; `.slice(-N)` (pre-ES2022, negative index) is fine. If you reach for a newer Array/Object/String method, verify it on a real device build before trusting it — the jsdom suite will not catch this class of gap.
+
 ## Testing
 
 ```bash
@@ -295,4 +298,12 @@ bun run test
 
 Tests run against `@lynx-js/testing-environment`'s jsdom-backed PAPI polyfill. The polyfill itself is published as `mithril-lynx/testing`'s `installTestingPolyfills()` (see `test/setup.ts` for the one-line setup) — consuming apps can use the exact same polyfill for their own tests instead of maintaining a duplicate copy; see `mithril-app/test/setup.ts` for a worked example.
 
-**Not provided**: Fast Refresh and a devtools/inspector bundle (project plan, Phase 9 / subsystem 12) are explicitly out of scope — they're deep, compiler-driven DX features in upstream ReactLynx with no zero-compiler equivalent worth building. `rspeedy dev`'s existing full-reload-on-file-change loop is the honest substitute.
+**Not provided**: Fast Refresh and a devtools/inspector bundle (project plan, Phase 9 / subsystem 12) are explicitly out of scope — they're deep, compiler-driven DX features in upstream ReactLynx with no zero-compiler equivalent worth building.
+
+In development, `pluginMithrilLynx()` adds a small background-thread client even
+when the app has no `background.ts`. After a successful rebuild it reloads the
+bundle through Lynx Go's `ExplorerModule.openSchema()`, rather than attempting
+module HMR (Mithril views run in the separate main-thread/Lepus bundle). This
+is intentionally a **Lynx Go viewer** convenience, not a portable SDK API: a
+different viewer or a final native host that does not provide `ExplorerModule`
+will log a warning and must be reloaded manually.

package/element.js

@@ -39,7 +39,11 @@ export function wrapElement(node) {
 		},
 
 		setAttribute(name, value) {
-			if (name === "class") __SetClasses(handle, value == null ? undefined : String(value));
+			// "" not undefined when clearing: real hardware's FiberSetClasses
+			// rejects a non-string argument ("FiberSetClasses param 1 should be
+			// String") — see lynx-mithril-shim.js's own matching fix for the
+			// same call.
+			if (name === "class") __SetClasses(handle, value == null ? "" : String(value));
 			else if (name === "id") __SetID(handle, value == null ? null : String(value));
 			else if (name.slice(0, 5) === "data-") __AddDataset(handle, name.slice(5), value);
 			else __SetAttribute(handle, name, value == null ? null : value);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mithril-lynx",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "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",

package/plugin.js

@@ -18,6 +18,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
 
 import { RuntimeWrapperWebpackPlugin } from "@lynx-js/runtime-wrapper-webpack-plugin";
 import { LynxEncodePlugin, LynxTemplatePlugin } from "@lynx-js/template-webpack-plugin";
@@ -27,6 +28,55 @@ const PLUGIN_NAME = "mithril-lynx-template-webpack";
 const BACKGROUND_CANDIDATES = ["background.ts", "background.js"];
 const STYLE_CANDIDATES = ["style.css"];
 
+// Live reload's client only runs where a full JS engine with Native Module
+// access exists: the background/JS thread. The main-thread/Lepus VM cannot
+// use it. An app without background.ts therefore gets a synthetic background
+// entry in development; see `includeBackground` below. Imported by this
+// resolved absolute path directly (see the entry-construction loop below),
+// not through a "mithril-lynx/..." bare specifier — that collides with the
+// package's own broader "mithril-lynx" resolve alias.
+const DEV_RELOAD_CLIENT_PATH = path.join(
+	path.dirname(fileURLToPath(import.meta.url)),
+	"src",
+	"dev-reload-client.js",
+);
+
+function createDevReloadClientQuery(api, environment, entryName) {
+	const config = environment.config ?? {};
+	const dev = config.dev ?? {};
+	const server = config.server ?? {};
+	const devServer = api.context.devServer ?? {};
+	// Rsbuild resolves this to the LAN address it advertises when server.host is
+	// 0.0.0.0, which is the address a physical Lynx Go device can actually use.
+	const hostname = dev.client?.host || devServer.hostname || server.host || "";
+	const port = devServer.port ?? server.port ?? "";
+	const protocol = devServer.https ? "https" : "http";
+	// At this point in the pipeline Rsbuild hasn't started the dev server yet,
+	// so `dev.assetPrefix` (when it's the default, host-derived one — see
+	// @lynx-js/rsbuild-plugin) still contains the literal, unsubstituted
+	// "<port>" placeholder it's only resolved to a real port number later, in
+	// its own `printUrls` callback. `hostname`/`port` above are already the
+	// real values, though, so resolve the placeholder the same way that
+	// callback does rather than trusting assetPrefix as pre-resolved.
+	const assetPrefix = (typeof dev.assetPrefix === "string" ? dev.assetPrefix : "/").replaceAll(
+		"<port>",
+		String(port),
+	);
+	const base = /^https?:\/\//.test(assetPrefix)
+		? assetPrefix
+		: `${protocol}://${hostname}${port ? `:${port}` : ""}${assetPrefix}`;
+	const bundleUrl = new URL(`${entryName}.bundle`, base.endsWith("/") ? base : `${base}/`).toString();
+	const params = new URLSearchParams({
+		hostname,
+		port: String(port),
+		pathname: "/rsbuild-hmr",
+		protocol: devServer.https ? "wss" : "ws",
+		"bundle-url": bundleUrl,
+	});
+	if (environment.webSocketToken) params.set("token", environment.webSocketToken);
+	return params.toString();
+}
+
 function findSibling(dir, candidates) {
 	for (const name of candidates) {
 		const candidate = path.join(dir, name);
@@ -59,13 +109,37 @@ function packageRootOf(resolvedFile) {
 
 export function pluginMithrilLynx(options = {}) {
 	const targetSdkVersion = options.targetSdkVersion ?? "3.5";
+	const hmr = options.hmr ?? false;
 
 	return {
 		name: PLUGIN_NAME,
 		setup(api) {
 			// Keep the template plugin discoverable by Rspeedy's Lynx internals.
 			api.expose(Symbol.for("LynxTemplatePlugin"), { LynxTemplatePlugin });
-			api.modifyBundlerChain((chain) => {
+
+			// setupApp()'s render model has no per-module "accept and patch"
+			// story (rendering is driven by native __RenderPage/__UpdatePage
+			// events, not by re-executing a hot-swapped module) -- module-level
+			// HMR's eval'd *.hot-update.js chunks also aren't runtime-wrapped
+			// the way the real background.js bundle is, and fail native-side
+			// with "ReferenceError: exports is not defined" if hot is left on.
+			// Force dev.hmr off (unless the app explicitly set it) so the dev
+			// client's ok() handler takes its other branch -- a full native
+			// Page.reload -- which is the one live-reload path this framework
+			// actually supports cleanly. dev.liveReload stays at its default.
+			api.modifyRsbuildConfig({
+				// Not a plain default: Rsbuild has already stamped dev.hmr:true onto
+				// the config by the time ANY hook sees it (even api.getRsbuildConfig
+				// ("original")), so there's no reliable way to tell "the app asked for
+				// hot module replacement" apart from "Rsbuild defaulted it" -- this
+				// always wins, with an explicit opt-out via pluginMithrilLynx({ hmr })
+				// for anyone who's fixed up their own app-level accept() story and the
+				// RuntimeWrapperWebpackPlugin gap noted below.
+				handler: (config, { mergeRsbuildConfig }) => mergeRsbuildConfig(config, { dev: { hmr } }),
+				order: "post",
+			});
+
+			api.modifyBundlerChain((chain, { isDev, environment }) => {
 				// mithril-lynx's own src/lynx-mithril-shim.js deep-imports mithril's
 				// internal render/cachedAttrsIsStaticMap.js (and its emptyAttrs
 				// singleton). If the app's own `require("mithril")` resolves to a
@@ -137,12 +211,30 @@ export function pluginMithrilLynx(options = {}) {
 					const bgAsset = `.rspeedy/${name}/background.js`;
 					const mtAsset = `.rspeedy/${name}/main-thread.js`;
 					const hasBackground = bgSource != null;
+					// In dev, always materialize a background chunk — even for an app
+					// with no background.ts of its own — so live reload's client has
+					// somewhere to run. In production, keep the original behavior
+					// exactly (no background chunk at all when the app doesn't use one).
+					const includeBackground = hasBackground || isDev;
 
 					// Each entry always has main-thread code and may opt into a
 					// background thread by adding a sibling background.ts file.
-					if (hasBackground) {
+					if (includeBackground) {
+						// Imported by its resolved absolute path (plus the query string
+						// the client reads its config from) rather than through the bare
+						// "mithril-lynx/dev-reload-client" specifier + an alias: the
+						// package-wide "mithril-lynx" prefix alias set above matches that
+						// specifier first regardless of registration order (webpack/
+						// rspack's resolve.alias picks the first matching entry, not the
+						// most specific one), which broke the import entirely.
+						const bgImports = isDev
+							? [
+									`${DEV_RELOAD_CLIENT_PATH}?${createDevReloadClientQuery(api, environment, name)}`,
+									...(hasBackground ? [bgSource] : []),
+								]
+							: bgSource;
 						chain.entry(bgEntry).add({
-							import: bgSource,
+							import: bgImports,
 							filename: bgAsset,
 						});
 					}
@@ -157,14 +249,14 @@ export function pluginMithrilLynx(options = {}) {
 							...LynxTemplatePlugin.defaultOptions,
 							filename: `${name}.bundle`,
 							intermediate: `.rspeedy/${name}`,
-							chunks: hasBackground ? [bgEntry, mtEntry] : [mtEntry],
+							chunks: includeBackground ? [bgEntry, mtEntry] : [mtEntry],
 							dsl: "react_nodiff",
 							targetSdkVersion,
 							cssPlugins: [],
 						},
 					]);
 
-					if (hasBackground) {
+					if (includeBackground) {
 						// Background chunks run in the JavaScript thread and need the
 						// Lynx runtime wrapper; main-thread chunks are encoded as lepus.
 						chain.plugin(`runtime-wrapper-${name}`).use(

package/src/dev-reload-client.js

@@ -0,0 +1,122 @@
+// Development-only client for Lynx Go.
+//
+// Mithril view code runs in the main-thread/Lepus bundle, while WebSocket and
+// Native Module access only exist in the background JS bundle. Consequently
+// normal module HMR cannot patch the view code. On a successful rebuild this
+// client asks Lynx Go's ExplorerModule to load the same bundle URL again.
+
+function parseResourceQuery(query) {
+	const values = {};
+	if (typeof query !== "string" || !query.startsWith("?")) return values;
+	for (const pair of query.slice(1).split("&")) {
+		const index = pair.indexOf("=");
+		const key = index === -1 ? pair : pair.slice(0, index);
+		const value = index === -1 ? "" : pair.slice(index + 1);
+		values[key] = decodeURIComponent(value);
+	}
+	return values;
+}
+
+function socketURL(options) {
+	const hostname = options.hostname || "";
+	const port = options.port ? `:${options.port}` : "";
+	const pathname = options.pathname || "/rsbuild-hmr";
+	const token = options.token ? `?token=${encodeURIComponent(options.token)}` : "";
+	return `${options.protocol || "ws"}://${hostname}${port}${pathname}${token}`;
+}
+
+const options = parseResourceQuery(__resourceQuery);
+const bundleUrl = options["bundle-url"];
+let currentHash;
+let initialBuild = true;
+let socket;
+// ExplorerModule.openSchema(url) makes Lynx Go fully reload — including
+// re-executing this very module from scratch. That would naturally replace
+// this stale instance's socket with a fresh one, except the OLD connection
+// is otherwise left open: confirmed on-device that every earlier reload's
+// socket stays alive and keeps receiving server broadcasts, so a build a few
+// reloads in fires openSchema several times at once (one call per still-open
+// stale socket), and the resulting navigations race and clobber each other —
+// only the first reload after a fresh QR/URL load (a single open socket)
+// reliably lands. Closing this socket ourselves right before reloading, and
+// suppressing the reconnect-on-close it would otherwise trigger, keeps
+// exactly one socket alive at a time.
+let reloading = false;
+
+console.info(
+	"[mithril-lynx] ExplorerModule.openSchema:",
+	typeof NativeModules !== "undefined" && typeof NativeModules.ExplorerModule?.openSchema,
+);
+
+function reload() {
+	const openSchema =
+		typeof NativeModules !== "undefined" && NativeModules.ExplorerModule?.openSchema;
+	if (typeof openSchema !== "function") {
+		console.warn("[mithril-lynx] Live reload unavailable: ExplorerModule.openSchema was not found.");
+		return;
+	}
+	if (!bundleUrl) {
+		console.warn("[mithril-lynx] Live reload unavailable: the bundle URL was not configured.");
+		return;
+	}
+	console.info("[mithril-lynx] Reloading updated bundle.");
+	reloading = true;
+	socket?.close();
+	openSchema.call(NativeModules.ExplorerModule, bundleUrl);
+}
+
+function handleMessage(rawMessage) {
+	let message;
+	try {
+		message = JSON.parse(rawMessage);
+	} catch {
+		console.warn("[mithril-lynx] Ignoring an invalid dev-server message.");
+		return;
+	}
+
+	switch (message.type) {
+		case "hash":
+			currentHash = message.data;
+			break;
+		case "ok":
+			// The server sends hash + ok immediately after connecting. Reloading
+			// then would loop forever, so only act after a later successful build.
+			if (initialBuild) initialBuild = false;
+			else if (currentHash) reload();
+			break;
+		case "still-ok":
+			console.info("[mithril-lynx] Nothing changed.");
+			break;
+		case "warnings":
+			console.warn("[mithril-lynx] Build completed with warnings.", message.data);
+			if (!message.params?.preventReloading && !initialBuild) reload();
+			break;
+		case "errors":
+			console.warn("[mithril-lynx] Build failed; waiting for the next successful build.", message.data);
+			break;
+		case "invalid":
+			console.info("[mithril-lynx] App updated. Recompiling...");
+			break;
+		case "error":
+			console.error("[mithril-lynx] Dev server error:", message.data);
+			break;
+	}
+}
+
+function connect(retries = 0) {
+	socket = new WebSocket(socketURL(options));
+	socket.onmessage = (event) => handleMessage(event.data);
+	socket.onerror = (error) => console.error("[mithril-lynx] Dev server connection error:", error);
+	socket.onclose = () => {
+		if (reloading) return; // Deliberately closed by reload() — a fresh socket is on its way already.
+		if (retries >= 10) {
+			console.error("[mithril-lynx] Unable to reconnect to the dev server.");
+			return;
+		}
+		const delay = 1000 * 2 ** retries + Math.random() * 100;
+		console.info("[mithril-lynx] Dev server disconnected; reconnecting...");
+		setTimeout(() => connect(retries + 1), delay);
+	};
+}
+
+connect();

package/src/lynx-mithril-shim.js

@@ -353,7 +353,15 @@ DIRECT_PROPS.forEach(function (p) {
 
 LynxNodeWrapper.prototype._setDirectProp = function (key, value) {
 	if (key === "className") {
-		__SetClasses(this._handle, value == null ? undefined : String(value))
+		// "" (not undefined) when clearing: real hardware's FiberSetClasses
+		// rejects a non-string argument outright ("FiberSetClasses param 1
+		// should be String"), confirmed on device — a genuinely native-only
+		// validation this shim's own jsdom-backed test mock never catches,
+		// since ElementPAPI's __SetClasses(e, cls) is just `e.className = cls`
+		// and happily accepts undefined. Found via mithril-lynx-ui's FeedList
+		// (a native-list cell recycled between content that has a "class"
+		// attr and content that doesn't).
+		__SetClasses(this._handle, value == null ? "" : String(value))
 	} else if (key === "id") {
 		__SetID(this._handle, value == null ? null : String(value))
 	} else if (key === "checked") {
@@ -365,7 +373,8 @@ LynxNodeWrapper.prototype._setDirectProp = function (key, value) {
 
 LynxNodeWrapper.prototype.setAttribute = function (key, value) {
 	if (key === "class") {
-		__SetClasses(this._handle, value == null ? undefined : String(value))
+		// See _setDirectProp's own comment above: "" not undefined.
+		__SetClasses(this._handle, value == null ? "" : String(value))
 	} else if (key === "id") {
 		__SetID(this._handle, value == null ? null : String(value))
 	} else if (key.slice(0, 5) === "data-") {
@@ -377,7 +386,8 @@ LynxNodeWrapper.prototype.setAttribute = function (key, value) {
 
 LynxNodeWrapper.prototype.removeAttribute = function (key) {
 	if (key === "class") {
-		__SetClasses(this._handle, undefined)
+		// See _setDirectProp's own comment above: "" not undefined.
+		__SetClasses(this._handle, "")
 	} else if (key === "id") {
 		__SetID(this._handle, null)
 	} else if (key.slice(0, 5) === "data-") {