mithril-lynx 2.0.2 → 2.6.0

package/.omo/run-continuation/ses_f48265d07ffenKG0GAz9ZRFvY6.json

@@ -0,0 +1,10 @@
+{
+  "sessionID": "ses_f48265d07ffenKG0GAz9ZRFvY6",
+  "updatedAt": "2026-09-19T04:26:35.138Z",
+  "sources": {
+    "background-task": {
+      "state": "idle",
+      "updatedAt": "2026-09-19T04:26:35.138Z"
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mithril-lynx",
-  "version": "2.0.2",
+  "version": "2.6.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,22 @@
     "./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"
+    },
+    "./list-cell": {
+      "types": "./src/list-cell.d.ts",
+      "default": "./src/list-cell.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. Op.CreateList's own
+// cell content (list-support.js) is no exception to that: componentAtIndex
+// replays ops the background thread already computed (list-cell.js), the
+// same way this function replays the app's own top-level tree — 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,21 +23,209 @@
 // 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
  *   page this applier is attached to. Every element this applier creates
  *   belongs to that one page — see CONTRACT.md / lynx-mithril-shim.js.
+ * @param {object} [options]
+ * @param {Function} [options.onEvent]
+ * @param {boolean} [options.flush] - Whether `applyPatch` calls the bare,
+ *   whole-page `__FlushElementTree()` after applying its ops. Defaults to
+ *   `true` — the right default for the ONE real top-level applier per page
+ *   (main-thread.js's own use). `false` for a per-cell applier
+ *   (list-support.js): a list cell's real commit point is the list-specific
+ *   `__FlushElementTree(wrapperHandle, {triggerLayout, operationID,
+ *   elementID, listID})` call list-support.js already makes right after —
+ *   calling the bare, whole-page flush too, from inside native's own
+ *   synchronous componentAtIndex callback, is a second, unrelated flush this
+ *   applier was never meant to trigger on that call site's behalf.
  */
-export function createPatchApplier(pageId, { onEvent } = {}) {
+export function createPatchApplier(pageId, { onEvent, flush = true } = {}) {
 	// id (as allocated by the background's virtual backend) -> real PAPI
 	// element handle. id 0 is reserved for "the page itself" (see
 	// fake-dom.js's LynxDocument) — pre-seeded here so the very first
 	// InsertBefore/AppendChild targeting id 0 has somewhere real to land.
 	const handles = new Map();
+	// list id -> its setCells(cells) function (list-support.js) — kept here,
+	// not as a property on the list's own handle: a real native list handle
+	// does not reliably hold a custom property across calls (confirmed on
+	// device), only `handles` (a plain Map) does.
+	const listSetters = new Map();
+
+	/** General form: seed the mapping for any id, not just the page root —
+	 * list-support.js uses this to alias a list-cell.js `containerId` (an
+	 * off-tree id from the background thread's OWN document) to the real
+	 * native wrapper element it created for that cell. */
+	function registerRoot(id, handle) {
+		handles.set(id, handle);
+	}
 
 	function registerPageRoot(pageElementHandle) {
-		handles.set(0, pageElementHandle);
+		registerRoot(0, pageElementHandle);
 	}
 
 	function createElementHandle(tag) {
@@ -42,12 +235,15 @@ export function createPatchApplier(pageId, { onEvent } = {}) {
 	}
 
 	/**
-	 * Applies one commit's worth of ops, then flushes exactly once —
-	 * `__FlushElementTree` is the real commit; nothing before it is visible.
-	 * This function itself is the ONLY caller of `__FlushElementTree` on
-	 * this applier's page — never called conditionally, never looked up
-	 * through a global (mirrors the fix in commit.js on the background
-	 * side: one explicit call site, not an implicit one).
+	 * Applies one commit's worth of ops, then — unless this applier was
+	 * created with `flush: false` (see this function's own constructor
+	 * options above) — flushes exactly once with the bare, whole-page
+	 * `__FlushElementTree()`; that call is the real commit for the ONE
+	 * top-level applier per page, never looked up through a global. A
+	 * per-cell applier (list-support.js) passes `flush: false` and issues
+	 * its own list-specific `__FlushElementTree(wrapperHandle, {...})` call
+	 * afterward instead — that one, not this one, is that cell's real
+	 * commit point.
 	 */
 	function applyPatch(ops) {
 		for (let i = 0; i < ops.length; ) {
@@ -101,7 +297,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 +314,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,12 +373,59 @@ 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 scrollOrientation = ops[i++];
+					const listType = ops[i++];
+					const spanCount = ops[i++];
+					const { handle, setCells } = createNativeList(pageId, scrollOrientation, listType, spanCount, createPatchApplier, onEvent);
+					handles.set(id, handle);
+					listSetters.set(id, setCells);
+					break;
+				}
+				case Op.SetListItems: {
+					const id = ops[i++];
+					const cellsJSON = ops[i++];
+					listSetters.get(id)(JSON.parse(cellsJSON));
+					break;
+				}
 				default:
 					throw new Error(`[mithril-lynx] Unknown patch opcode: ${opcode}`);
 			}
 		}
-		__FlushElementTree();
+		if (flush) __FlushElementTree();
 	}
 
-	return { registerPageRoot, applyPatch };
+	return {
+		registerPageRoot,
+		registerRoot,
+		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(scrollOrientation, listType, spanCount) {
+			const id = nextId++;
+			pushOp(ops, Op.CreateList, id, scrollOrientation, listType, spanCount);
+			return id;
+		},
+		setListItems(id, cells) {
+			pushOp(ops, Op.SetListItems, id, JSON.stringify(cells));
+		},
 		/** Drains and returns the accumulated ops. Called once per commit. */
 		takeOps() {
 			if (ops.length === 0) return null;
@@ -76,5 +90,19 @@ export function createVirtualBackend() {
 			ops = [];
 			return out;
 		},
+		/**
+		 * Runs `fn` (a DOM mutation against a node from THIS backend's own
+		 * document — same id space as everything else, so event dispatch
+		 * keeps working normally) and returns just the ops it produced,
+		 * removing them from the shared buffer so they never also go out
+		 * with the next `takeOps()`. Used by list-cell.js to render one list
+		 * item off-tree and ship its construction ops separately, instead of
+		 * as part of the app's own visible-tree patch.
+		 */
+		captureOps(fn) {
+			const start = ops.length;
+			fn();
+			return ops.splice(start, ops.length - start);
+		},
 	};
 }

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.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,28 @@ export class LynxDocument extends LynxContainerNode {
 	createDocumentFragment() {
 		return new LynxFragment(this);
 	}
+
+	/**
+	 * A native virtualized list — see patch-protocol.js's Op.CreateList.
+	 * Populate it via `.setListItems(cells)` (list-cell.js builds `cells`
+	 * from an app's own `items`/`renderItem`) — see
+	 * docs/native-papi/papi-06-virtualized-lists.md in mithril-lynx-ui.
+	 */
+	createNativeList(options = {}) {
+		return new LynxElement(this, this._backend, "list", undefined, {
+			scrollOrientation: options.scrollOrientation ?? "vertical",
+			listType: options.listType ?? "single",
+			spanCount: options.spanCount ?? 1,
+		});
+	}
+
+	/** Delegates to the backend — see virtual-backend.js's own captureOps
+	 * for what this is for. Kept behind LynxDocument's public surface like
+	 * every other backend interaction in this file, rather than exposing
+	 * `_backend` itself to callers (list-cell.js). */
+	captureOps(fn) {
+		return this._backend.captureOps(fn);
+	}
 }
 
 export function createLynxDocument(backend) {

package/src/list-cell.d.ts

@@ -0,0 +1,20 @@
+// Ambient declaration for the ESM src/list-cell.js — the background-thread
+// half of native list support. mithril-lynx-ui's <List>/<FeedList> call
+// this once per item, from the SAME thread/document as the rest of the
+// app's own tree — see that file's own header for why.
+
+export interface ListCell {
+	typeKey: string;
+	containerId: number;
+	ops: unknown[];
+	rootChildIds: number[];
+}
+
+export function renderListCell(
+	document: unknown,
+	render: (dom: unknown, vnodes: unknown[], redraw: () => void) => void,
+	redraw: () => void,
+	renderItem: (item: unknown, index: number) => unknown,
+	item: unknown,
+	index: number,
+): ListCell;