mithril-lynx 0.0.4 → 0.0.6

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

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.4",
+  "version": "0.0.6",
   "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/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-") {
@@ -696,23 +706,41 @@ function factory() {
 
 	function initComponent(vnode, hooks) {
 		var sentinel
-		if (typeof vnode.tag.view === "function") {
+		var classStyle = typeof vnode.tag.view !== "function"
+		if (!classStyle) {
 			vnode.state = Object.create(vnode.tag)
 			sentinel = vnode.state.view
-			if (sentinel.$$reentrantLock$$ != null) return
-			sentinel.$$reentrantLock$$ = true
 		} else {
-			vnode.state = void 0
 			sentinel = vnode.tag
-			if (sentinel.$$reentrantLock$$ != null) return
-			sentinel.$$reentrantLock$$ = true
-			vnode.state = (vnode.tag.prototype != null && typeof vnode.tag.prototype.view === "function") ? new vnode.tag(vnode) : vnode.tag(vnode)
 		}
-		initLifecycle(vnode.state, vnode, hooks)
-		if (vnode.attrs != null) initLifecycle(vnode.attrs, vnode, hooks)
-		vnode.instance = Vnode.normalize(callHook.call(vnode.state.view, vnode))
-		if (vnode.instance === vnode) throw Error("A view cannot return the vnode it received as argument")
-		sentinel.$$reentrantLock$$ = null
+		if (sentinel.$$reentrantLock$$ != null) return
+		sentinel.$$reentrantLock$$ = true
+		// The lock above is stored on `sentinel` — the component's OWN shared
+		// view function (or, for class-style components, the tag itself), NOT
+		// on this vnode instance — so it's shared by EVERY use of this
+		// component anywhere in the app. Without the try/finally below, a
+		// view() (or, for a class-style component, its CONSTRUCTOR) that
+		// throws on a component's first render (e.g. a fail-loudly validation
+		// error) skips the `sentinel.$$reentrantLock$$ = null` reset entirely,
+		// leaving that lock stuck at `true` forever. Every later attempt to
+		// create that SAME component type — anywhere, not just the one
+		// instance that threw — then silently no-ops right here
+		// (`if (sentinel.$$reentrantLock$$ != null) return`): no render, no
+		// error, nothing. Found via mithril-lynx-ui's own test suite: a
+		// component whose view() deliberately throws to validate a prop,
+		// exercised in one test, made every SUBSEQUENT test mounting that
+		// same component silently render nothing, no matter how unrelated.
+		try {
+			if (classStyle) {
+				vnode.state = (vnode.tag.prototype != null && typeof vnode.tag.prototype.view === "function") ? new vnode.tag(vnode) : vnode.tag(vnode)
+			}
+			initLifecycle(vnode.state, vnode, hooks)
+			if (vnode.attrs != null) initLifecycle(vnode.attrs, vnode, hooks)
+			vnode.instance = Vnode.normalize(callHook.call(vnode.state.view, vnode))
+			if (vnode.instance === vnode) throw Error("A view cannot return the vnode it received as argument")
+		} finally {
+			sentinel.$$reentrantLock$$ = null
+		}
 	}
 
 	function createComponent(parent, vnode, hooks, ns, nextSibling) {