mithril-lynx 0.0.5 → 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.5",
+  "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-") {