mithril-lynx 2.0.1 → 2.5.0

package/README.md

@@ -53,6 +53,14 @@ renderApp({ root: () => m(Counter) });
 
 `m.request`, reimplemented as a wrapper over Lynx's own `fetch`. See [`REQUEST.md`](./REQUEST.md) for the full API, and [`FETCH_INVESTIGATION.md`](./FETCH_INVESTIGATION.md) for the complete option-by-option gap analysis against the real `m.request` spec, backed by real-device evidence rather than docs/types alone (which were wrong twice during that investigation).
 
+## Custom fonts
+
+Use a plain CSS `@font-face` rule — not `lynx.addFont()` (that JS API only fires post-mount, too late to win the first-frame race). Three gotchas, all confirmed on real hardware and inherited unchanged from the previous mithril-lynx (none of this is architecture-specific):
+
+- **The font file must be `.ttf`, not `.woff2`** — a `.woff2` `@font-face` compiles fine but the native text renderer silently never applies it.
+- **`font-family` set on `:root` (or any ancestor) does not cascade to descendants by default** — `pluginLynxConfig({ enableCSSInheritance: true })` turns that on.
+- **A declarative `@font-face` resolves synchronously on the first native `__FlushElementTree()` call**, and that cost scales with how many text nodes resolve it — up to +2s of cold start on a mid/low-end device. Filed upstream as [lynx-family/lynx#9431](https://github.com/lynx-family/lynx/issues/9431). The workaround is a native-side prefetch hook, not a JS-level fix — see [`ANDROID_APK_GUIDE.md`](./ANDROID_APK_GUIDE.md) Part D for the full procedure, or scaffold it directly with `create-mithril-lynx`'s `--with-font <file.ttf>` flag.
+
 ## Known gaps
 
 - **`m.trust`** — not present. Stripped from `mithril-runtime` at the source, and Lynx's Element PAPI has no innerHTML-equivalent injection point to reimplement it against anyway (same permanent gap v1 documented).
@@ -72,3 +80,4 @@ Runs against `@lynx-js/testing-environment`'s real Element PAPI simulation via `
 - `.omo/plans/m-route-en-memoria.md` — how `m.route` was designed and verified for an in-memory, URL-less environment.
 - `.omo/plans/m-request-fetch-lynx.md` — the `m.request`-vs-`fetch` investigation plan and its execution log.
 - [`ROUTE.md`](./ROUTE.md), [`REQUEST.md`](./REQUEST.md), [`FETCH_INVESTIGATION.md`](./FETCH_INVESTIGATION.md) — user-facing reference docs for the two Lynx-specific reimplementations.
+- [`ANDROID_APK_GUIDE.md`](./ANDROID_APK_GUIDE.md) — building a native Android host and APK from scratch, Gradle-CLI only, including the `.ttf` cold-start hack from "Custom fonts" above. Automated end to end by `create-mithril-lynx --android`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mithril-lynx",
-  "version": "2.0.1",
+  "version": "2.5.0",
   "description": "Mithril.js on Lynx: real mithril/render/render.js driven through a Lynx-backed fake DOM, with an explicit single commit hook (no conditional global flush) and three reload modes (data-light, structural-light, full). A complete rewrite of the previous mithril-lynx (0.0.x).",
   "license": "MIT",
   "type": "module",
@@ -24,6 +24,18 @@
     "./request": {
       "types": "./src/request.d.ts",
       "default": "./src/request.js"
+    },
+    "./mount-redraw": {
+      "types": "./src/mount-redraw.d.ts",
+      "default": "./src/mount-redraw.js"
+    },
+    "./testing": {
+      "types": "./src/testing.d.ts",
+      "default": "./src/testing.js"
+    },
+    "./list-support": {
+      "types": "./src/list-support.d.ts",
+      "default": "./src/list-support.js"
     }
   },
   "scripts": {

package/src/apply-patch.js

@@ -1,11 +1,16 @@
 // src/apply-patch.js
 //
-// The main-thread half of the patch protocol. Deliberately NOT a DOM — it
-// never runs Mithril's render.js (only the background thread does, see
-// background.js) — it is a direct, low-level interpreter of the flat op
-// array straight onto the real Element PAPI, in the spirit of ReactLynx's
-// own `snapshotPatchApply.js` (see rspeedy-react-analysis/LYNX_PAPI_SPEC.md
-// §4.3): a switch over op codes, one real PAPI call per case, nothing else.
+// The main-thread half of the patch protocol. Deliberately NOT a DOM for
+// the app's OWN tree — it never runs Mithril's render.js for that (only
+// the background thread does, see background.js) — it is a direct,
+// low-level interpreter of the flat op array straight onto the real
+// Element PAPI, in the spirit of ReactLynx's own `snapshotPatchApply.js`
+// (see rspeedy-react-analysis/LYNX_PAPI_SPEC.md §4.3): a switch over op
+// codes, one real PAPI call per case, nothing else. One deliberate
+// exception: Op.CreateList's own cell content (see list-support.js) DOES
+// run a real Mithril render pass right here, on this thread — the only way
+// to satisfy native's synchronous componentAtIndex contract at all (see
+// docs/native-papi/papi-06-virtualized-lists.md in mithril-lynx-ui).
 //
 // The exact `__Create*`/pageId contract below (one `pageId` shared by every
 // element on a page, `__CreateView`/`__CreateText`/generic `__CreateElement`
@@ -18,6 +23,169 @@
 // commit/reload layer (commit.js, reload/*.js), never in this mapping.
 
 import { Op } from "./patch-protocol.js";
+import { createNativeList } from "./list-support.js";
+
+// --- Native gesture support (Op.SetGestureDetector) ------------------------
+//
+// See patch-protocol.js's own note and mithril-lynx-ui's
+// docs/native-papi/papi-05-native-gestures.md for the full design writeup.
+// Everything below runs on the MAIN thread, synchronously, inside a native
+// gesture callback — never on the background thread, and never waits on a
+// round trip to it. The arena-claim decision (arenaPolicy) is evaluated
+// here using only the event's own coordinates; the resulting touches-down/
+// move/up events are then forwarded to the background thread as ordinary
+// events (via `onEvent`, the exact same callback Op.AddEvent already uses),
+// so app code sees them as plain "gesturedown"/"gesturemove"/"gestureup"
+// listeners with no gesture-specific machinery of its own.
+
+const GESTURE_TYPE_CODES = { composed: -1, pan: 0, fling: 1, default: 2, tap: 3, longpress: 4, rotation: 5, pinch: 6, native: 7 };
+const GestureState = { active: 1, fail: 2, end: 3 };
+
+// Native does not call a gesture callback function directly — it calls a
+// global `runWorklet(ctx, params)`, looking up the real function by
+// `ctx._wkltId`. This is a real native requirement (confirmed on device by
+// this project's own predecessor, mithril-lynx v1's gesture.js), not
+// specific to any one package — every gesture callback has to be wrapped
+// through this registry before being handed to __SetGestureDetector.
+function ensureWorkletRuntime() {
+	if (globalThis.lynxWorkletImpl !== undefined) return;
+	globalThis.lynxWorkletImpl = { _workletMap: {} };
+	globalThis.registerWorklet = function (_type, id, fn) {
+		globalThis.lynxWorkletImpl._workletMap[id] = fn;
+	};
+	globalThis.runWorklet = function (ctx, params) {
+		if (typeof ctx !== "object" || ctx === null || !("_wkltId" in ctx)) return;
+		const fn = globalThis.lynxWorkletImpl._workletMap[ctx._wkltId];
+		if (typeof fn !== "function") return;
+		const args = Array.isArray(params) ? params : params != null ? [params] : [];
+		// A plain call, deliberately not .apply()/.call() — native's own
+		// `controller` argument throws if marshalled through either (same
+		// finding mithril-lynx v1's gesture.js already made).
+		return fn.bind(ctx)(...args);
+	};
+}
+
+let nextWorkletId = 1;
+function wrapWorkletCallback(fn) {
+	ensureWorkletRuntime();
+	const id = "mithril-lynx-gesture-" + nextWorkletId++;
+	globalThis.registerWorklet("main-thread", id, fn);
+	return { _wkltId: id };
+}
+
+/**
+ * A small, generic claim/release policy — covers the two real shapes this
+ * project's consumers need, not an arbitrary one:
+ *   - `{ mode: "claim" }` — claim on touches-down, never reconsider (a
+ *     single-axis drag with nothing else competing for the gesture).
+ *   - `{ mode: "axis-lock", axis: "horizontal" | "vertical", referenceMoves }`
+ *     — claim eagerly on touches-down, then on the move `referenceMoves + 1`
+ *     (0: decide using the down position as reference, right on the first
+ *     move; 1: use the first move's own position as reference and decide on
+ *     the second), release and fail the gesture if the dominant axis of the
+ *     resulting delta doesn't match `axis`.
+ * Unverified on a real device (no device access this session) — the claim
+ * timing (down vs. first/second move) mirrors what mithril-lynx v1's own
+ * device-verified sheet.js/swipe-action.js/swiper.js already did; the NEW
+ * part, evaluating it here instead of in app code, has not been confirmed
+ * to feel the same on-device.
+ */
+function createArenaTracker(policy) {
+	const mode = (policy && policy.mode) || "claim";
+	let refX = null;
+	let refY = null;
+	let movesSeen = 0;
+	let decided = false;
+
+	return {
+		onDown(x, y, consume) {
+			consume(true);
+			if (mode === "axis-lock" && (policy.referenceMoves || 0) === 0) {
+				refX = x;
+				refY = y;
+			}
+		},
+		onMove(x, y, consume, fail) {
+			if (mode !== "axis-lock" || decided) return;
+			if ((policy.referenceMoves || 0) === 1 && movesSeen === 0) {
+				refX = x;
+				refY = y;
+				movesSeen++;
+				return;
+			}
+			movesSeen++;
+			if (refX == null) return;
+			const dx = x - refX;
+			const dy = y - refY;
+			if (dx === 0 && dy === 0) return; // not enough signal yet
+			decided = true;
+			const isHorizontal = Math.abs(dx) >= Math.abs(dy);
+			const wins = policy.axis === "horizontal" ? isHorizontal : !isHorizontal;
+			if (wins) {
+				consume(true);
+			} else {
+				// Release the claim touches-down made eagerly, THEN fail —
+				// both, not just the latter: a bare fail() with the arena
+				// still marked "claimed" would keep blocking an ancestor
+				// (e.g. a <scroll-view>) from ever seeing this touch.
+				consume(false);
+				fail();
+			}
+		},
+	};
+}
+
+function registerGestureDetector(handle, id, gestureId, gestureType, arenaPolicy, onEvent) {
+	const tracker = createArenaTracker(arenaPolicy);
+	const gestureTypeCode = typeof gestureType === "string" ? GESTURE_TYPE_CODES[gestureType] : gestureType;
+
+	function consume(controller, shouldClaim) {
+		if (controller != null && typeof controller.__ConsumeGesture === "function") {
+			controller.__ConsumeGesture(handle, gestureId, { consume: shouldClaim, inner: false });
+		}
+	}
+	function fail(controller) {
+		if (controller != null && typeof controller.__SetGestureState === "function") {
+			controller.__SetGestureState(handle, gestureId, GestureState.fail);
+		}
+	}
+	// timestamp: a real field native's own touch/gesture params already
+	// carry (mithril-lynx v1's gesture consumers already read
+	// event.params.timestamp for velocity calculations) — forwarded as-is
+	// rather than having a consumer approximate it from receipt time on
+	// the background thread, which would fold cross-thread forwarding
+	// latency into a velocity computation.
+	function coordsOf(event) {
+		const p = (event && event.params) || {};
+		return { clientX: p.clientX, clientY: p.clientY, timestamp: p.timestamp };
+	}
+
+	const callbacks = {
+		onTouchesDown: (event, controller) => {
+			const coords = coordsOf(event);
+			tracker.onDown(coords.clientX, coords.clientY, (claim) => consume(controller, claim));
+			onEvent?.(id, "gesturedown", coords);
+		},
+		onTouchesMove: (event, controller) => {
+			const coords = coordsOf(event);
+			tracker.onMove(coords.clientX, coords.clientY, (claim) => consume(controller, claim), () => fail(controller));
+			onEvent?.(id, "gesturemove", coords);
+		},
+		onTouchesUp: (event) => {
+			onEvent?.(id, "gestureup", coordsOf(event));
+		},
+	};
+
+	__SetAttribute(handle, "has-react-gesture", true);
+	__SetAttribute(handle, "flatten", false);
+	__SetGestureDetector(
+		handle,
+		gestureId,
+		gestureTypeCode,
+		{ callbacks: Object.keys(callbacks).map((name) => ({ name, callback: wrapWorkletCallback(callbacks[name]) })) },
+		{},
+	);
+}
 
 /**
  * @param {number} pageId - `__GetElementUniqueID(pageElement)` of the real
@@ -101,7 +269,15 @@ export function createPatchApplier(pageId, { onEvent } = {}) {
 					const name = ops[i++];
 					const value = ops[i++];
 					const handle = handles.get(id);
+					// "class" and "id" each have their own dedicated PAPI call
+					// (__SetClasses/__SetID) — __SetAttribute itself rejects
+					// both ("Cannot use __SetAttribute for \"class\"/\"id\"").
+					// Found porting a component that assigns a native `id` for
+					// an imperative selector-query ref (see mithril-lynx-ui's
+					// docs/native-papi/papi-01-imperative-refs.md) — nothing
+					// in this rewrite's own test suite had set `id` before.
 					if (name === "class") __SetClasses(handle, value == null ? "" : value);
+					else if (name === "id") __SetID(handle, value == null ? null : value);
 					else __SetAttribute(handle, name, value);
 					break;
 				}
@@ -110,6 +286,7 @@ export function createPatchApplier(pageId, { onEvent } = {}) {
 					const name = ops[i++];
 					const handle = handles.get(id);
 					if (name === "class") __SetClasses(handle, "");
+					else if (name === "id") __SetID(handle, null);
 					else __SetAttribute(handle, name, null);
 					break;
 				}
@@ -168,6 +345,38 @@ export function createPatchApplier(pageId, { onEvent } = {}) {
 					i += 2;
 					break;
 				}
+				case Op.SetGestureDetector: {
+					const id = ops[i++];
+					const gestureId = ops[i++];
+					const gestureType = ops[i++];
+					const arenaPolicy = ops[i++];
+					const handle = handles.get(id);
+					registerGestureDetector(handle, id, gestureId, gestureType, arenaPolicy, onEvent);
+					break;
+				}
+				case Op.RemoveGestureDetector: {
+					const id = ops[i++];
+					const gestureId = ops[i++];
+					const handle = handles.get(id);
+					if (typeof __RemoveGestureDetector === "function") __RemoveGestureDetector(handle, gestureId);
+					break;
+				}
+				case Op.CreateList: {
+					const id = ops[i++];
+					const rendererKey = ops[i++];
+					const scrollOrientation = ops[i++];
+					const listType = ops[i++];
+					const spanCount = ops[i++];
+					handles.set(id, createNativeList(pageId, rendererKey, scrollOrientation, listType, spanCount, createPatchApplier, onEvent));
+					break;
+				}
+				case Op.SetListItems: {
+					const id = ops[i++];
+					const itemsJSON = ops[i++];
+					const listHandle = handles.get(id);
+					listHandle.__setItems(JSON.parse(itemsJSON));
+					break;
+				}
 				default:
 					throw new Error(`[mithril-lynx] Unknown patch opcode: ${opcode}`);
 			}
@@ -175,5 +384,19 @@ export function createPatchApplier(pageId, { onEvent } = {}) {
 		__FlushElementTree();
 	}
 
-	return { registerPageRoot, applyPatch };
+	return {
+		registerPageRoot,
+		applyPatch,
+		/** The real PAPI element handle for a given background-side id, or
+		 * `undefined` if nothing was ever created for it. Exists for tests
+		 * (see mithril-lynx/testing) that need to correlate a fake-dom node's
+		 * `_id` with the real element the testing environment's PAPI
+		 * recording (mithril-lynx-v1's own installTestingPolyfills wraps
+		 * every `__`-prefixed call regardless of which package called it, so
+		 * this is how a v2 test finds "which of those calls targeted THIS
+		 * element") — never needed by application code. */
+		getHandle(id) {
+			return handles.get(id);
+		},
+	};
 }

package/src/backends/virtual-backend.js

@@ -69,6 +69,20 @@ export function createVirtualBackend() {
 		removeEvent(id, type) {
 			pushOp(ops, Op.RemoveEvent, id, type);
 		},
+		setGestureDetector(id, gestureId, gestureType, arenaPolicy) {
+			pushOp(ops, Op.SetGestureDetector, id, gestureId, gestureType, arenaPolicy);
+		},
+		removeGestureDetector(id, gestureId) {
+			pushOp(ops, Op.RemoveGestureDetector, id, gestureId);
+		},
+		createList(rendererKey, scrollOrientation, listType, spanCount) {
+			const id = nextId++;
+			pushOp(ops, Op.CreateList, id, rendererKey, scrollOrientation, listType, spanCount);
+			return id;
+		},
+		setListItems(id, items) {
+			pushOp(ops, Op.SetListItems, id, JSON.stringify(items));
+		},
 		/** Drains and returns the accumulated ops. Called once per commit. */
 		takeOps() {
 			if (ops.length === 0) return null;

package/src/fake-dom.js

@@ -65,6 +65,15 @@ class LynxContainerNode extends LynxNode {
 		return this._children[0] ?? null;
 	}
 
+	// Real Mithril's render.js reads `fragment.childNodes.length` right
+	// after `insertDOM`'ing a multi-node children list into a
+	// `createDocumentFragment()` (createNodes' fragment-batching path) — a
+	// real DOM's `childNodes` is a live NodeList, but render.js only ever
+	// reads `.length` off it here, so the plain backing array is enough.
+	get childNodes() {
+		return this._children;
+	}
+
 	contains(other) {
 		let node = other;
 		while (node) {
@@ -121,6 +130,7 @@ class LynxContainerNode extends LynxNode {
 function createStyleProxy(element) {
 	const methods = {
 		setProperty(name, value) {
+			element._styleEverSet = true;
 			element._backend.setStyleProperty(element._id, name, String(value));
 		},
 		removeProperty(name) {
@@ -140,6 +150,7 @@ function createStyleProxy(element) {
 			if (value === "" || value == null) {
 				element._backend.removeStyleProperty(element._id, name);
 			} else {
+				element._styleEverSet = true;
 				element._backend.setStyleProperty(element._id, name, String(value));
 			}
 			return true;
@@ -147,15 +158,33 @@ function createStyleProxy(element) {
 	});
 }
 
+// Module-level, not per-document: mirrors patch-protocol.js's own id spaces
+// (element ids are per-backend, but a gesture id only needs to be unique
+// within whatever set apply-patch.js's real __SetGestureDetector call sees
+// on the main thread — a single incrementing counter is simplest).
+let nextGestureId = 1;
+
 export class LynxElement extends LynxContainerNode {
-	constructor(ownerDocument, backend, tag, ns) {
+	/**
+	 * `listConfig`, when given, makes this a native virtualized list
+	 * element instead of a plain one — see patch-protocol.js's
+	 * Op.CreateList and docs/native-papi/papi-06-virtualized-lists.md
+	 * (mithril-lynx-ui) for the full design. Not constructed directly;
+	 * use LynxDocument#createNativeList().
+	 */
+	constructor(ownerDocument, backend, tag, ns, listConfig) {
 		super(ownerDocument);
 		this._backend = backend;
 		this.tag = tag;
 		this.namespaceURI = ns;
-		this._id = ns ? backend.createElementNS(ns, tag) : backend.createElement(tag);
+		this._id = listConfig
+			? backend.createList(listConfig.rendererKey, listConfig.scrollOrientation, listConfig.listType, listConfig.spanCount)
+			: ns
+				? backend.createElementNS(ns, tag)
+				: backend.createElement(tag);
 		ownerDocument._nodesById.set(this._id, this);
 		this._style = null;
+		this._styleEverSet = false;
 		this._listeners = Object.create(null);
 		// `hasPropertyKey` (CONTRACT.md §e) requires `"value" in vnode.dom` etc.
 		// to be true for the property-write fast path to apply to form
@@ -173,11 +202,20 @@ export class LynxElement extends LynxContainerNode {
 	set style(value) {
 		if (value == null || value === "") {
 			// `element.style = ""` (CONTRACT.md §f, lines 750-752): clear.
-			// We don't track which properties were set, so this relies on the
-			// backend/native side treating a style-reset op as "clear all" —
-			// see backends/virtual-backend.js `Op.SetStyleProperty` with a
-			// name of `*`.
-			this._backend.removeStyleProperty(this._id, "*");
+			// render.js's own updateStyle() calls this UNCONDITIONALLY right
+			// before applying an object style, even on an element that never
+			// had any style at all (its "old is missing or a string, style is
+			// an object" branch — see mithril-runtime/render/render.js) — so
+			// without this guard, EVERY component with a plain object style
+			// prop (an extremely common pattern, not an edge case) would hit
+			// apply-patch.js's "bulk-clear not implemented" throw on its very
+			// first render. `_styleEverSet` (set by createStyleProxy whenever
+			// a real property is written) is exactly "was there anything to
+			// clear" — skip emitting the op at all when there wasn't; the
+			// throw still fires for the genuine case (an update actually
+			// replacing a previously-set style), where a real bulk-clear PAPI
+			// call would actually be needed and hasn't been validated yet.
+			if (this._styleEverSet) this._backend.removeStyleProperty(this._id, "*");
 			return;
 		}
 		if (typeof value !== "object") {
@@ -233,6 +271,31 @@ export class LynxElement extends LynxContainerNode {
 		this._backend.setAttributeNS(this._id, ns, name, value == null ? null : String(value));
 	}
 
+	/**
+	 * Registers a real native gesture detector on this element — see
+	 * patch-protocol.js's Op.SetGestureDetector for the design. `type` is
+	 * one of "pan"/"native"/... matching the native GestureType names.
+	 * `arenaPolicy` decides claim/release timing on the main thread; the
+	 * resulting touches-down/move/up events arrive back here as ordinary
+	 * "gesturedown"/"gesturemove"/"gestureup" events — add plain listeners
+	 * for those the same way as any other event. Returns an id to pass to
+	 * removeGestureDetector().
+	 */
+	setGestureDetector(type, arenaPolicy) {
+		const gestureId = nextGestureId++;
+		this._backend.setGestureDetector(this._id, gestureId, type, arenaPolicy);
+		return gestureId;
+	}
+
+	removeGestureDetector(gestureId) {
+		this._backend.removeGestureDetector(this._id, gestureId);
+	}
+
+	/** Only meaningful on an element created via LynxDocument#createNativeList(). */
+	setListItems(items) {
+		this._backend.setListItems(this._id, items);
+	}
+
 	addEventListener(type, listener) {
 		const isNew = !(type in this._listeners);
 		this._listeners[type] = listener;
@@ -298,6 +361,13 @@ export class LynxText extends LynxNode {
 	constructor(ownerDocument, backend, text) {
 		super(ownerDocument);
 		this._backend = backend;
+		// Mithril's render.js never reads `.nodeValue` back itself (it only
+		// ever WRITES it, on an update pass — see render.js's own updateText),
+		// so this had no effect on real rendering; it only broke anything
+		// ELSE reading a freshly-created text node's value before its first
+		// update (found writing a real device-verification test for
+		// mithril-lynx-ui — see that repo's test/v2-harness.ts).
+		this._text = text;
 		this._id = backend.createText(text);
 	}
 
@@ -367,6 +437,25 @@ export class LynxDocument extends LynxContainerNode {
 	createDocumentFragment() {
 		return new LynxFragment(this);
 	}
+
+	/**
+	 * A native virtualized list — see patch-protocol.js's Op.CreateList.
+	 * `rendererKey` must match a key registered on the MAIN thread via
+	 * mithril-lynx/list-support's registerListRenderer() (see
+	 * docs/native-papi/papi-06-virtualized-lists.md in mithril-lynx-ui):
+	 * the renderer function itself can't cross the thread boundary, only
+	 * this string key can. Call `.setListItems(items)` on the result to
+	 * populate it — items must be JSON-serializable, since they DO cross
+	 * the boundary, as data.
+	 */
+	createNativeList(rendererKey, options = {}) {
+		return new LynxElement(this, this._backend, "list", undefined, {
+			rendererKey,
+			scrollOrientation: options.scrollOrientation ?? "vertical",
+			listType: options.listType ?? "single",
+			spanCount: options.spanCount ?? 1,
+		});
+	}
 }
 
 export function createLynxDocument(backend) {

package/src/list-support.d.ts

@@ -0,0 +1,10 @@
+// Ambient declaration for the ESM src/list-support.js.
+//
+// Import this from your app's main-thread.ts (alongside setupRenderer()
+// from "mithril-lynx/main-thread") and call registerListRenderer() once
+// per list your app uses — see that file's own header, and
+// docs/native-papi/papi-06-virtualized-lists.md in mithril-lynx-ui, for
+// why the render function itself has to be registered here rather than
+// passed in from background.ts directly.
+
+export function registerListRenderer(key: string, renderItem: (item: unknown, index: number) => unknown): void;