mithril-lynx 2.5.0 → 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.5.0",
+  "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",
@@ -36,6 +36,10 @@
     "./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

@@ -6,11 +6,11 @@
 // 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).
+// 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`
@@ -191,16 +191,41 @@ function registerGestureDetector(handle, id, gestureId, gestureType, arenaPolicy
  * @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) {
@@ -210,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; ) {
@@ -363,29 +391,30 @@ export function createPatchApplier(pageId, { onEvent } = {}) {
 				}
 				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));
+					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 itemsJSON = ops[i++];
-					const listHandle = handles.get(id);
-					listHandle.__setItems(JSON.parse(itemsJSON));
+					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,
+		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

package/src/backends/virtual-backend.js

@@ -75,13 +75,13 @@ export function createVirtualBackend() {
 		removeGestureDetector(id, gestureId) {
 			pushOp(ops, Op.RemoveGestureDetector, id, gestureId);
 		},
-		createList(rendererKey, scrollOrientation, listType, spanCount) {
+		createList(scrollOrientation, listType, spanCount) {
 			const id = nextId++;
-			pushOp(ops, Op.CreateList, id, rendererKey, scrollOrientation, listType, spanCount);
+			pushOp(ops, Op.CreateList, id, scrollOrientation, listType, spanCount);
 			return id;
 		},
-		setListItems(id, items) {
-			pushOp(ops, Op.SetListItems, id, JSON.stringify(items));
+		setListItems(id, cells) {
+			pushOp(ops, Op.SetListItems, id, JSON.stringify(cells));
 		},
 		/** Drains and returns the accumulated ops. Called once per commit. */
 		takeOps() {
@@ -90,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

@@ -178,7 +178,7 @@ export class LynxElement extends LynxContainerNode {
 		this.tag = tag;
 		this.namespaceURI = ns;
 		this._id = listConfig
-			? backend.createList(listConfig.rendererKey, listConfig.scrollOrientation, listConfig.listType, listConfig.spanCount)
+			? backend.createList(listConfig.scrollOrientation, listConfig.listType, listConfig.spanCount)
 			: ns
 				? backend.createElementNS(ns, tag)
 				: backend.createElement(tag);
@@ -440,22 +440,25 @@ export class LynxDocument extends LynxContainerNode {
 
 	/**
 	 * 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.
+	 * 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(rendererKey, options = {}) {
+	createNativeList(options = {}) {
 		return new LynxElement(this, this._backend, "list", undefined, {
-			rendererKey,
 			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;

package/src/list-cell.js

@@ -0,0 +1,73 @@
+// src/list-cell.js
+//
+// Runs ONLY on the background thread — the counterpart to list-support.js's
+// main-thread half. Turns one `renderItem(item, index)` call into a
+// self-contained set of construction ops, using the app's OWN document/
+// backend/render (the same ones background.js already created for the rest
+// of the tree) — never a separate, isolated render pipeline. That's the
+// whole point: the item's real fake-dom nodes end up registered in the same
+// `document._nodesById` map as everything else in the app, so a forwarded
+// native event for one of them dispatches through `onEventFromMainThread`
+// exactly like any other element's event already does. No extra reporting
+// convention needed.
+//
+// The main thread never calls renderItem() itself — see list-support.js.
+
+import { Op, forEachOp } from "./patch-protocol.js";
+
+function typeKeyOf(vnode) {
+	return typeof vnode.tag === "string" ? vnode.tag : (vnode.tag && vnode.tag.name) || "default";
+}
+
+/** The real handle ids inserted directly under `containerId` — what a
+ * recycled cell on the main thread needs to remove before it can attach a
+ * different item's content into the same native wrapper (see
+ * list-support.js's clearWrapperChildren). Scanning the ops after the fact,
+ * instead of tracking during render, keeps this file from needing any
+ * backend-internal access beyond `captureOps` itself. */
+function findTopLevelChildIds(ops, containerId) {
+	const ids = [];
+	forEachOp(ops, (opcode, args) => {
+		if (opcode === Op.InsertBefore && args[0] === containerId) ids.push(args[1]);
+	});
+	return ids;
+}
+
+/**
+ * @param {import("./fake-dom.js").LynxDocument} document - the app's own
+ *   document (e.g. `vnode.dom.ownerDocument` from inside a component) — NOT
+ *   a separate one. Sharing it is what keeps a list cell's ids in the same
+ *   `_nodesById` space as the rest of the app.
+ * @param {(dom: object, vnodes: unknown[], redraw: () => void) => void} render
+ *   - a `mithril-runtime/render/render.js` instance. Callers typically keep
+ *   one shared instance per `<List>` (see mithril-lynx-ui's list.js), not
+ *   one per cell — render() is designed to manage multiple independent
+ *   containers safely.
+ * @param {() => void} redraw - forwarded as render()'s own redraw callback,
+ *   so a `ontap` (etc.) handler inside the rendered cell triggers a REAL
+ *   app-wide redraw afterward, exactly like any other event in the app —
+ *   see mithril-lynx/mount-redraw's `redraw()`.
+ * @param {(item: unknown, index: number) => unknown} renderItem
+ * @param {unknown} item
+ * @param {number} index
+ * @returns {{ typeKey: string, containerId: number, ops: unknown[], rootChildIds: number[] }}
+ */
+export function renderListCell(document, render, redraw, renderItem, item, index) {
+	// An ordinary element in the SAME document, never inserted into the
+	// visible tree (no `appendChild`/`insertBefore` call targets it) — its
+	// own `Op.CreateElement` never gets captured below since it's created
+	// OUTSIDE the capture, before there's anything to record; only what
+	// render() does INSIDE it is captured. The main thread's list-support.js
+	// treats `containerId` as an alias for whatever real native wrapper it
+	// creates for this cell, the same way apply-patch.js's top-level applier
+	// treats id 0 as an alias for the real page element.
+	const container = document.createElement("list-cell-root");
+	const vnode = renderItem(item, index);
+	const typeKey = typeKeyOf(vnode);
+
+	const ops = document.captureOps(() => {
+		render(container, [vnode], redraw);
+	});
+
+	return { typeKey, containerId: container._id, ops, rootChildIds: findTopLevelChildIds(ops, container._id) };
+}

package/src/list-support.d.ts

@@ -1,10 +1,13 @@
-// 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.
+// Ambient declaration for the ESM src/list-support.js — the main-thread
+// half of native list support. Not meant to be imported directly by app
+// code; apply-patch.js's own Op.CreateList case is the only caller. See
+// list-cell.d.ts for the background-thread half an app actually uses.
 
-export function registerListRenderer(key: string, renderItem: (item: unknown, index: number) => unknown): void;
+export function createNativeList(
+	pageId: number,
+	scrollOrientation: string,
+	listType: string,
+	spanCount: number,
+	createPatchApplier: (pageId: number, options?: { onEvent?: Function; flush?: boolean }) => object,
+	onEvent?: Function,
+): { handle: unknown; setCells: (cells: unknown[]) => void };

package/src/list-support.js

@@ -1,153 +1,149 @@
 // src/list-support.js
 //
-// Runs ONLY on the main thread — imported from an app's own main-thread.ts,
-// alongside setupRenderer() (see docs/native-papi/papi-06-virtualized-lists.md
-// in mithril-lynx-ui for the full design). Registers the render function(s)
-// a native virtualized list needs: the function itself can never cross the
-// background-thread/main-thread boundary (real main and background threads
-// are separate JS engine instances — no shared closures, only serializable
-// messages), so an app registers it here by a string key instead, and
-// mithril-lynx-ui's List component references that same key from
-// background.ts.
+// Runs ONLY on the main thread — the counterpart to list-cell.js's
+// background-thread half. Wires up the native list contract
+// (__CreateList/__UpdateListCallbacks, the synchronous componentAtIndex/
+// enqueueComponent pair, recycling cells by a type key) — unchanged from
+// mithril-lynx v1's own device-verified list.js.
 //
-// The native list contract this wires up (__CreateList/__UpdateListCallbacks,
-// the synchronous componentAtIndex/enqueueComponent pair, recycling cells by
-// a type key) is unchanged from mithril-lynx v1's own list.js — that part
-// was already device-verified. What's different: each cell is rendered by a
-// REAL, self-contained render pass entirely on THIS thread (the exact same
-// pieces background.js uses for the app's own tree — mithril-runtime's real
-// render(), fake-dom.js, a virtual backend — just applied to itself
-// immediately via a nested patch applier, instead of crossing a channel).
-// componentAtIndex's native contract is synchronous; a cross-thread round
-// trip could never satisfy that, so this is the only architecture that can.
+// What's different from v1, and from this file's own first version: a
+// cell's content is never rendered here. `componentAtIndex` only replays
+// ops the background thread already computed (list-cell.js), the same way
+// apply-patch.js's own top-level applyPatch replays the app's own tree —
+// this file has no dependency on mithril-runtime, fake-dom.js, or a virtual
+// backend at all anymore, because it never runs a render pass of its own.
+// componentAtIndex(itemCount) cost is therefore the cost of creating/
+// updating real elements from an already-known op list, same as any other
+// patch — not a render.
 //
-// KNOWN GAP, not solved by this file: an event handler (e.g. `ontap`)
-// inside a renderItem()-produced vnode fires entirely on this thread, with
-// no way back to the app's own state on the background thread — there is
-// no background-thread fake-dom node for list cell content to dispatch
-// through (unlike every other element in the app, which the background
-// thread DOES know about). Reaching back into app state from inside a list
-// cell needs a deliberate reporting convention, not built here yet.
-
-import renderFactory from "mithril-runtime/render/render.js";
-import { createLynxDocument } from "./fake-dom.js";
-import { createVirtualBackend } from "./backends/virtual-backend.js";
-
-const renderers = new Map();
-
-/** Call once per list your app uses, from main-thread.ts — see this file's
- * own header for why the render function itself can't just be imported
- * from background.ts and passed across directly. */
-export function registerListRenderer(key, renderItem) {
-	renderers.set(key, renderItem);
-}
-
-function typeKeyOf(vnode) {
-	return typeof vnode.tag === "string" ? vnode.tag : (vnode.tag && vnode.tag.name) || "default";
-}
-
-function makeCell(pageId, wrapperHandle, createPatchApplier) {
-	const backend = createVirtualBackend();
-	const document = createLynxDocument(backend);
-	const render = renderFactory();
-	const applier = createPatchApplier(pageId);
-	applier.registerPageRoot(wrapperHandle);
-	return { wrapper: wrapperHandle, backend, document, render, applier, typeKey: null };
-}
-
-/** Re-renders `vnode` into `cell`'s own persistent fake-dom document —
- * Mithril's own diff (real, not simulated) computes the minimal update
- * against whatever this cell showed before, exactly like a normal redraw,
- * so recycling a cell for a different item never needs a manual "clear
- * old content first" step. */
-function renderCellVnode(cell, vnode) {
-	cell.render(cell.document, [vnode], () => {});
-	const ops = cell.backend.takeOps();
-	if (ops) cell.applier.applyPatch(ops);
-}
-
-/**
- * @param {number} pageId
- * @param {string} rendererKey
- * @param {(pageId: number, options?: {onEvent?: Function}) => object} createPatchApplier
- *   - passed in rather than imported, to avoid a circular import with
- *   apply-patch.js (the only caller).
- * @param {Function} [onEvent] - forwarded into each cell's own patch
- *   applier, same as the top-level one — see this file's own "known gap"
- *   note above for what this does NOT yet solve.
- */
-export function createNativeList(pageId, rendererKey, scrollOrientation, listType, spanCount, createPatchApplier, onEvent) {
-	const renderItem = renderers.get(rendererKey);
-	if (renderItem == null) {
-		throw new Error(
-			`[mithril-lynx] no list renderer registered for "${rendererKey}" — call registerListRenderer("${rendererKey}", ...) from main-thread.ts.`,
-		);
+// Recycling a cell for a different item clears its real children (removed
+// by the handle ids list-cell.js recorded — see clearWrapperChildren below)
+// and replays the new item's ops fresh; this is a real teardown-and-rebuild
+// of that cell's content, not a diff against what was there before. A real
+// Mithril diff on recycle would need a persistent per-slot fake-dom
+// document kept in sync with which native cell native actually chose to
+// reuse — information only native has, on the main thread, which the
+// background thread (where the diff would have to run) can't see without a
+// round trip. Not implemented.
+
+export function createNativeList(pageId, scrollOrientation, listType, spanCount, createPatchApplier, onEvent) {
+	let cells = []; // current cells, indexed by cellIndex — see patch-protocol.js's Op.SetListItems
+	let count = 0;
+	const signMap = new Map(); // sign -> { wrapperHandle, applier, rootChildIds, cellIndex, typeKey }
+	const recycleMap = new Map(); // typeKey -> Map<sign, entry> (entries currently off-screen, available to reuse)
+
+	function replayCell(wrapperHandle, cell) {
+		const applier = createPatchApplier(pageId, { onEvent, flush: false });
+		applier.registerRoot(cell.containerId, wrapperHandle);
+		applier.applyPatch(cell.ops);
+		return applier;
 	}
 
-	let items = [];
-	let count = 0;
-	const recycleMap = new Map(); // typeKey -> Map<sign, cell>
-	const signMap = new Map(); // sign -> cell
+	function clearWrapperChildren(entry) {
+		for (const id of entry.rootChildIds) {
+			const handle = entry.applier.getHandle(id);
+			if (handle != null) __RemoveElement(entry.wrapperHandle, handle);
+		}
+	}
 
-	function bindFreshItem(listHandle, listId, cellIndex, opId, vnode, typeKey) {
+	function bindFreshItem(listHandle, listId, cellIndex, opId, cell, flush) {
 		const wrapperHandle = __CreateElement("list-item", pageId, {});
 		__SetAttribute(wrapperHandle, "item-key", String(cellIndex));
 		__AppendElement(listHandle, wrapperHandle);
 
-		const cell = makeCell(pageId, wrapperHandle, (pid) => createPatchApplier(pid, { onEvent }));
-		cell.typeKey = typeKey;
-		renderCellVnode(cell, vnode);
-
+		const applier = replayCell(wrapperHandle, cell);
 		const sign = __GetElementUniqueID(wrapperHandle);
-		signMap.set(sign, cell);
-		__FlushElementTree(wrapperHandle, { triggerLayout: true, operationID: opId, elementID: sign, listID: listId });
+		signMap.set(sign, { wrapperHandle, applier, rootChildIds: cell.rootChildIds, cellIndex, typeKey: cell.typeKey });
+		if (flush) __FlushElementTree(wrapperHandle, { triggerLayout: true, operationID: opId, elementID: sign, listID: listId });
 		return sign;
 	}
 
-	function bindRecycledItem(listId, cellIndex, opId, vnode, typeKey, pool) {
-		const [sign, cell] = pool.entries().next().value;
+	function bindRecycledItem(listId, cellIndex, opId, cell, pool, flush) {
+		const [sign, entry] = pool.entries().next().value;
 		pool.delete(sign);
-		__SetAttribute(cell.wrapper, "item-key", String(cellIndex));
-		cell.typeKey = typeKey;
-		renderCellVnode(cell, vnode);
-		signMap.set(sign, cell);
-		__FlushElementTree(cell.wrapper, { triggerLayout: true, operationID: opId, elementID: sign, listID: listId });
+		clearWrapperChildren(entry);
+		__SetAttribute(entry.wrapperHandle, "item-key", String(cellIndex));
+		const applier = replayCell(entry.wrapperHandle, cell);
+		entry.applier = applier;
+		entry.rootChildIds = cell.rootChildIds;
+		entry.cellIndex = cellIndex;
+		signMap.set(sign, entry);
+		if (flush) __FlushElementTree(entry.wrapperHandle, { triggerLayout: true, operationID: opId, elementID: sign, listID: listId });
 		return sign;
 	}
 
-	function componentAtIndex(listHandle, listId, cellIndex, opId) {
+	function bindCell(listHandle, listId, cellIndex, opId, flush) {
 		if (cellIndex < 0 || cellIndex >= count) {
 			throw new Error(`[mithril-lynx] list: cellIndex ${cellIndex} out of range (itemCount=${count})`);
 		}
-		const vnode = renderItem(items[cellIndex], cellIndex);
-		const typeKey = typeKeyOf(vnode);
-		const pool = recycleMap.get(typeKey);
-		if (pool && pool.size > 0) return bindRecycledItem(listId, cellIndex, opId, vnode, typeKey, pool);
-		return bindFreshItem(listHandle, listId, cellIndex, opId, vnode, typeKey);
+		const cell = cells[cellIndex];
+		const pool = recycleMap.get(cell.typeKey);
+		if (pool && pool.size > 0) return bindRecycledItem(listId, cellIndex, opId, cell, pool, flush);
+		return bindFreshItem(listHandle, listId, cellIndex, opId, cell, flush);
+	}
+
+	function componentAtIndex(listHandle, listId, cellIndex, opId) {
+		return bindCell(listHandle, listId, cellIndex, opId, true);
+	}
+
+	/**
+	 * The batched form of componentAtIndex — real native calls this (not a
+	 * fallback: confirmed against `@lynx-js/react`'s own
+	 * componentAtIndexFactory/attachListItemAtIndex, which always registers
+	 * BOTH forms) for several cells at once, expecting exactly ONE
+	 * `__FlushElementTree` covering all of them (`operationIDs`/`elementIDs`
+	 * arrays), not one per cell — the real reason a native list's initial,
+	 * simultaneously-visible cells need this at all.
+	 */
+	function componentAtIndexes(listHandle, listId, cellIndexes, operationIDs) {
+		const elementIDs = cellIndexes.map((cellIndex, i) => bindCell(listHandle, listId, cellIndex, operationIDs[i], false));
+		__FlushElementTree(listHandle, { triggerLayout: true, operationIDs, elementIDs, listID: listId });
 	}
 
 	function enqueueComponent(_listHandle, _listId, sign) {
-		const cell = signMap.get(sign);
-		if (cell == null) return;
+		const entry = signMap.get(sign);
+		if (entry == null) return;
 		signMap.delete(sign);
-		if (!recycleMap.has(cell.typeKey)) recycleMap.set(cell.typeKey, new Map());
-		recycleMap.get(cell.typeKey).set(sign, cell);
+		if (!recycleMap.has(entry.typeKey)) recycleMap.set(entry.typeKey, new Map());
+		recycleMap.get(entry.typeKey).set(sign, entry);
 	}
 
 	function sendListInfo(listHandle, listId, insertAction, removeAction, updateAction) {
 		__SetAttribute(listHandle, "update-list-info", { insertAction, removeAction, updateAction });
-		__UpdateListCallbacks(listHandle, componentAtIndex, enqueueComponent);
+		__UpdateListCallbacks(listHandle, componentAtIndex, enqueueComponent, componentAtIndexes);
 	}
 
-	const listHandle = __CreateList(pageId, componentAtIndex, enqueueComponent, {});
+	const listHandle = __CreateList(pageId, componentAtIndex, enqueueComponent, {}, componentAtIndexes);
 	const listId = __GetElementUniqueID(listHandle);
 	__SetAttribute(listHandle, "scroll-orientation", scrollOrientation);
 	__SetAttribute(listHandle, "list-type", listType);
 	__SetAttribute(listHandle, "span-count", String(spanCount));
 
-	listHandle.__setItems = (nextItems) => {
-		const nextCount = nextItems.length;
-		items = nextItems;
+	// Re-flushes every currently-attached (on-screen) cell with its newest
+	// ops — e.g. after a redraw triggered by a tap inside a cell, or any
+	// other app state change that reaches this list's items. Unconditional,
+	// same as List's own onupdate already unconditionally resends the whole
+	// `items` array on every relevant redraw (see mithril-lynx-ui's
+	// list/list.js) — a real "did this cell's content actually change"
+	// check would need to compare `ops` arrays, not implemented yet. Cells
+	// that aren't attached right now just pick up their new content next
+	// time componentAtIndex asks for that index.
+	function refreshAttachedCells(nextCells) {
+		for (const [sign, entry] of signMap) {
+			const nextCell = nextCells[entry.cellIndex];
+			clearWrapperChildren(entry);
+			entry.applier = replayCell(entry.wrapperHandle, nextCell);
+			entry.rootChildIds = nextCell.rootChildIds;
+			entry.typeKey = nextCell.typeKey;
+			signMap.set(sign, entry);
+			__FlushElementTree(entry.wrapperHandle, { triggerLayout: false });
+		}
+	}
+
+	function setCells(nextCells) {
+		const nextCount = nextCells.length;
+		refreshAttachedCells(nextCells);
+		cells = nextCells;
 		if (nextCount === count) return;
 		if (nextCount > count) {
 			sendListInfo(
@@ -161,7 +157,15 @@ export function createNativeList(pageId, rendererKey, scrollOrientation, listTyp
 			sendListInfo(listHandle, listId, [], Array.from({ length: count - nextCount }, (_, i) => nextCount + i), []);
 		}
 		count = nextCount;
-	};
+	}
 
-	return listHandle;
+	// Returned separately, not as a property stuck onto `listHandle` itself:
+	// confirmed on real hardware (unlike @lynx-js/testing-environment's
+	// simulated PAPI) that a native list's own returned handle does not
+	// reliably hold a custom property across calls — assigning one there
+	// and reading it back later from apply-patch.js's Op.SetListItems case
+	// threw "TypeError: not a function" on the very first SetListItems, even
+	// with zero items. apply-patch.js keeps `setCells` in its own map
+	// instead, keyed the same way `handles` already is.
+	return { handle: listHandle, setCells };
 }

package/src/patch-protocol.js

@@ -43,12 +43,13 @@ export const Op = Object.freeze({
 	SetGestureDetector: 14, // id, gestureId, gestureType, arenaPolicy
 	RemoveGestureDetector: 15, // id, gestureId
 	// A native virtualized list — see docs/native-papi/papi-06-virtualized-lists.md
-	// in mithril-lynx-ui for the full design. rendererKey looks up a
-	// render function registered on the MAIN thread (mithril-lynx/
-	// list-support's registerListRenderer()) — the function itself can't
-	// cross the thread boundary, only this string key can.
-	CreateList: 16, // id, rendererKey, scrollOrientation, listType, spanCount
-	SetListItems: 17, // id, itemsJSON (items must be JSON-serializable — they DO cross the boundary, as data)
+	// in mithril-lynx-ui for the full design. Each list item is rendered on
+	// the BACKGROUND thread, through the app's own real render pass
+	// (list-cell.js), same as everything else in the tree — the main thread
+	// never runs renderItem() itself, only replays the ops that rendering
+	// already produced (apply-patch.js's Op.CreateList case + list-support.js).
+	CreateList: 16, // id, scrollOrientation, listType, spanCount
+	SetListItems: 17, // id, cellsJSON — cellsJSON = JSON.stringify(cells), cells: Array<{ typeKey, containerId, ops, rootChildIds }>, one entry per current item, computed by list-cell.js's renderListCell(). `ops` is a flat op array in this SAME encoding, scoped to `containerId` as its root parent id.
 });
 
 /**
@@ -59,3 +60,43 @@ export const Op = Object.freeze({
 export function pushOp(ops, opcode, ...args) {
 	ops.push(opcode, ...args);
 }
+
+// How many argument slots follow each opcode — the single source of truth
+// for walking a flat ops array without re-interpreting it (apply-patch.js's
+// own switch increments `i` inline instead of using this table, since it
+// also needs to look at individual arg values as it goes; this exists for
+// callers that only need to skip/scan, e.g. list-cell.js's
+// findTopLevelChildIds(), which never applies the ops itself).
+export const OP_ARITY = Object.freeze({
+	[Op.CreateElement]: 2, // tag, id
+	[Op.CreateElementNS]: 3, // ns, tag, id
+	[Op.CreateText]: 2, // value, id
+	[Op.CreateFragment]: 1, // id (never actually emitted — see fake-dom.js's LynxFragment)
+	[Op.InsertBefore]: 3, // parentId, childId, refId
+	[Op.RemoveChild]: 2, // parentId, childId
+	[Op.SetAttribute]: 3, // id, name, value
+	[Op.RemoveAttribute]: 2, // id, name
+	[Op.SetAttributeNS]: 4, // id, ns, name, value
+	[Op.SetStyleProperty]: 3, // id, name, value
+	[Op.RemoveStyleProperty]: 2, // id, name
+	[Op.SetText]: 2, // id, value
+	[Op.AddEvent]: 2, // id, type
+	[Op.RemoveEvent]: 2, // id, type
+	[Op.SetGestureDetector]: 4, // id, gestureId, gestureType, arenaPolicy
+	[Op.RemoveGestureDetector]: 2, // id, gestureId
+	[Op.CreateList]: 4, // id, scrollOrientation, listType, spanCount
+	[Op.SetListItems]: 2, // id, cellsJSON
+});
+
+/** Walks a flat ops array, calling `visit(opcode, args)` once per op — args
+ * is the plain slice of that op's own arguments (not including the opcode
+ * itself). Throws on an unknown opcode rather than silently desyncing. */
+export function forEachOp(ops, visit) {
+	for (let i = 0; i < ops.length; ) {
+		const opcode = ops[i++];
+		const arity = OP_ARITY[opcode];
+		if (arity === undefined) throw new Error(`[mithril-lynx] Unknown patch opcode: ${opcode}`);
+		visit(opcode, ops.slice(i, i + arity));
+		i += arity;
+	}
+}

package/test/list.test.ts

@@ -1,19 +1,21 @@
 import { describe, expect, it } from "@rstest/core";
 import m from "mithril";
+import renderFactory from "mithril-runtime/render/render.js";
 import { createPatchApplier } from "../src/apply-patch.js";
-import { registerListRenderer } from "../src/list-support.js";
+import { createVirtualBackend } from "../src/backends/virtual-backend.js";
+import { createLynxDocument } from "../src/fake-dom.js";
+import { renderListCell } from "../src/list-cell.js";
 import { Op } from "../src/patch-protocol.js";
 
-// Op.CreateList end-to-end: registerListRenderer() (the main-thread.ts side
-// of the design — see docs/native-papi/papi-06-virtualized-lists.md in
-// mithril-lynx-ui) plus a raw CreateList/SetListItems op sequence applied
-// directly (mithril-lynx-ui's own List component is what normally produces
-// these ops from the background thread; this test drives apply-patch.js
-// directly, the same level end-to-end.test.ts already operates at).
-//
-// componentAtIndex/enqueueComponent are native's own synchronous contract —
-// driven directly here, exactly like mithril-lynx-ui's own list.test.ts
-// already does against mithril-lynx-v1's list.js.
+// Op.CreateList end-to-end. A cell's own content is computed on the
+// BACKGROUND thread (list-cell.js's renderListCell(), through the app's own
+// document/render — no separate render pipeline) and only replayed on the
+// main thread (list-support.js) — see
+// docs/native-papi/papi-06-virtualized-lists.md in mithril-lynx-ui. This
+// test drives both halves directly: a background document renders each item
+// into cells, then a main-thread applier replays Op.CreateList/
+// Op.SetListItems with those cells, exactly like mithril-lynx-ui's own List
+// component does end to end.
 
 function requestCell(listHandle: any, index: number, opId = 1) {
 	const listId = __GetElementUniqueID(listHandle);
@@ -34,37 +36,37 @@ function textOf(node: any): string {
 	return out;
 }
 
-function setupList(rendererKey: string) {
+/** Stands in for mithril-lynx-ui's <List>: one persistent background
+ * document + render instance, reused across calls — see list-cell.js's own
+ * header for why callers keep one of these per list, not one per cell. */
+function makeCellSource(renderItem: (item: any, index: number) => unknown) {
+	const document = createLynxDocument(createVirtualBackend());
+	const render = renderFactory();
+	return {
+		document,
+		buildCells: (items: unknown[]) => items.map((item, index) => renderListCell(document, render, () => {}, renderItem, item, index)),
+	};
+}
+
+function setupList() {
 	lynxTestingEnv.switchToMainThread();
 	const pageId = __GetElementUniqueID(__CreatePage());
 	const applier = createPatchApplier(pageId);
 	applier.registerPageRoot(__CreateView(pageId));
-	applier.applyPatch([Op.CreateList, 1, rendererKey, "vertical", "single", 1]);
+	applier.applyPatch([Op.CreateList, 1, "vertical", "single", 1]);
 	const listHandle = applier.getHandle(1) as any;
 	return { applier, listHandle };
 }
 
-function setItems(applier: ReturnType<typeof createPatchApplier>, items: unknown[]) {
-	applier.applyPatch([Op.SetListItems, 1, JSON.stringify(items)]);
+function setCells(applier: ReturnType<typeof createPatchApplier>, cells: unknown[]) {
+	applier.applyPatch([Op.SetListItems, 1, JSON.stringify(cells)]);
 }
 
 describe("Op.CreateList (native virtualized list support)", () => {
-	it("throws a clear error for an unregistered renderer key", () => {
-		lynxTestingEnv.switchToMainThread();
-		const pageId = __GetElementUniqueID(__CreatePage());
-		const applier = createPatchApplier(pageId);
-		applier.registerPageRoot(__CreateView(pageId));
-
-		expect(() => applier.applyPatch([Op.CreateList, 1, "nonexistent-key", "vertical", "single", 1])).toThrow(
-			/no list renderer registered for "nonexistent-key"/,
-		);
-	});
-
-	it("renders real content per cell via the registered renderer, driven by componentAtIndex", () => {
-		registerListRenderer("basic", (item: string, index: number) => m("text", {}, `${index}:${item}`));
-
-		const { applier, listHandle } = setupList("basic");
-		setItems(applier, ["a", "b", "c"]);
+	it("renders real content per cell from ops the background thread already computed", () => {
+		const { buildCells } = makeCellSource((item: string, index: number) => m("text", {}, `${index}:${item}`));
+		const { applier, listHandle } = setupList();
+		setCells(applier, buildCells(["a", "b", "c"]));
 
 		requestCell(listHandle, 0);
 		requestCell(listHandle, 1);
@@ -73,10 +75,9 @@ describe("Op.CreateList (native virtualized list support)", () => {
 	});
 
 	it("recycles a cell for a different index, and its content updates to match", () => {
-		registerListRenderer("recycle-basic", (item: string, index: number) => m("text", {}, `${index}:${item}`));
-
-		const { applier, listHandle } = setupList("recycle-basic");
-		setItems(applier, ["a", "b", "c", "d"]);
+		const { buildCells } = makeCellSource((item: string, index: number) => m("text", {}, `${index}:${item}`));
+		const { applier, listHandle } = setupList();
+		setCells(applier, buildCells(["a", "b", "c", "d"]));
 
 		const signA = requestCell(listHandle, 0);
 		const wrapperA = listHandle.children[0];
@@ -91,15 +92,42 @@ describe("Op.CreateList (native virtualized list support)", () => {
 	});
 
 	it("SetListItems with a larger array requests the newly available indices without error", () => {
-		registerListRenderer("grow", (item: string, index: number) => m("text", {}, `${index}:${item}`));
+		const { buildCells } = makeCellSource((item: string, index: number) => m("text", {}, `${index}:${item}`));
+		const { applier, listHandle } = setupList();
 
-		const { applier, listHandle } = setupList("grow");
-
-		setItems(applier, ["a", "b"]);
+		setCells(applier, buildCells(["a", "b"]));
 		expect(() => requestCell(listHandle, 1)).not.toThrow();
 		expect(() => requestCell(listHandle, 2)).toThrow(/cellIndex 2 out of range/);
 
-		setItems(applier, ["a", "b", "c"]);
+		setCells(applier, buildCells(["a", "b", "c"]));
 		expect(() => requestCell(listHandle, 2)).not.toThrow();
 	});
+
+	it("SetListItems re-flushes an already-attached cell's content in place", () => {
+		const { buildCells } = makeCellSource((item: string, index: number) => m("text", {}, `${index}:${item}`));
+		const { applier, listHandle } = setupList();
+		setCells(applier, buildCells(["a", "b"]));
+
+		requestCell(listHandle, 0);
+		const wrapper = listHandle.children[0];
+		expect(textOf(wrapper)).toBe("0:a");
+
+		setCells(applier, buildCells(["z", "b"])); // same count, index 0's content changed
+		expect(textOf(wrapper)).toBe("0:z");
+	});
+
+	it("a tap inside a cell dispatches through the background thread's own fake-dom node", () => {
+		const { document, buildCells } = makeCellSource(() =>
+			m("text", { ontap: () => { taps += 1; } }, "tap me"),
+		);
+		let taps = 0;
+		const { applier, listHandle } = setupList();
+		const cells = buildCells([{}]);
+		setCells(applier, cells);
+		requestCell(listHandle, 0);
+
+		const node = document.getNodeById((cells[0] as any).rootChildIds[0]);
+		node!.dispatchEvent({ type: "tap", currentTarget: node, preventDefault() {}, stopPropagation() {} });
+		expect(taps).toBe(1);
+	});
 });