mithril-lynx 2.0.1 → 2.5.0

package/src/list-support.js

@@ -0,0 +1,167 @@
+// 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.
+//
+// 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.
+//
+// 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.`,
+		);
+	}
+
+	let items = [];
+	let count = 0;
+	const recycleMap = new Map(); // typeKey -> Map<sign, cell>
+	const signMap = new Map(); // sign -> cell
+
+	function bindFreshItem(listHandle, listId, cellIndex, opId, vnode, typeKey) {
+		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 sign = __GetElementUniqueID(wrapperHandle);
+		signMap.set(sign, cell);
+		__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;
+		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 });
+		return sign;
+	}
+
+	function componentAtIndex(listHandle, listId, cellIndex, opId) {
+		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);
+	}
+
+	function enqueueComponent(_listHandle, _listId, sign) {
+		const cell = signMap.get(sign);
+		if (cell == null) return;
+		signMap.delete(sign);
+		if (!recycleMap.has(cell.typeKey)) recycleMap.set(cell.typeKey, new Map());
+		recycleMap.get(cell.typeKey).set(sign, cell);
+	}
+
+	function sendListInfo(listHandle, listId, insertAction, removeAction, updateAction) {
+		__SetAttribute(listHandle, "update-list-info", { insertAction, removeAction, updateAction });
+		__UpdateListCallbacks(listHandle, componentAtIndex, enqueueComponent);
+	}
+
+	const listHandle = __CreateList(pageId, componentAtIndex, enqueueComponent, {});
+	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;
+		if (nextCount === count) return;
+		if (nextCount > count) {
+			sendListInfo(
+				listHandle,
+				listId,
+				Array.from({ length: nextCount - count }, (_, i) => ({ position: count + i, type: "cell", "item-key": String(count + i) })),
+				[],
+				[],
+			);
+		} else {
+			sendListInfo(listHandle, listId, [], Array.from({ length: count - nextCount }, (_, i) => nextCount + i), []);
+		}
+		count = nextCount;
+	};
+
+	return listHandle;
+}

package/src/mount-redraw.d.ts

@@ -0,0 +1,13 @@
+/** Called by `renderApp()` right after it creates its own redraw function.
+ * Public so a reusable component library (not just this package's own
+ * request.js) can trigger a redraw of whichever app is currently mounted
+ * after an async state change (a timer/animation callback, a promise) that
+ * didn't happen inside a real event handler — the case mithril-lynx's own
+ * auto-redraw-after-event contract doesn't cover. */
+export function register(redraw: () => void): void;
+
+/** No-op before any app has mounted. Scheduled, not synchronous — see
+ * mount-redraw.js's own header for why a synchronous call here would race
+ * a caller's own pending `.then()`/callback that hasn't stored its result
+ * yet. */
+export function redraw(): void;

package/src/mount-redraw.js

@@ -15,6 +15,13 @@
 // for the app's whole lifetime (plan §3.1), so "the current redraw
 // function" is a single slot, not a list.
 //
+// Also exported publicly (`mithril-lynx/mount-redraw`), not just used
+// internally by request.js — any reusable component (not just this
+// package's own code) that mutates state from an async callback outside a
+// real event handler (a timer, a promise, an animation frame) needs the
+// exact same "redraw whichever app is mounted" call this module already
+// provides; there is no reason to make library authors reinvent it.
+//
 // `redraw()` schedules instead of calling `currentRedraw()` inline — same
 // reason real Mithril's version schedules through the platform's
 // requestAnimationFrame instead of rendering synchronously: `request.js`'s

package/src/patch-protocol.js

@@ -28,6 +28,27 @@ export const Op = Object.freeze({
 	SetText: 11, // id, value (nodeValue on a text node)
 	AddEvent: 12, // id, type
 	RemoveEvent: 13, // id, type
+	// gestureId, gestureType, arenaPolicy — registers a real native gesture
+	// detector on the main thread. arenaPolicy is a small, JSON-serializable
+	// description of when to claim/release the gesture arena, evaluated
+	// synchronously on the main thread against just the event's own
+	// coordinates (no background-thread round trip) — see
+	// docs/native-papi/papi-05-native-gestures.md in mithril-lynx-ui for
+	// the full design writeup and why this is deliberately narrower than a
+	// generic remote-controller RPC. Resulting onTouchesDown/Move/Up events
+	// are forwarded to the background thread as plain events (type
+	// "gesturedown"/"gesturemove"/"gestureup"), through the exact same
+	// channel any other native event already uses — nothing new on the
+	// background-thread side.
+	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)
 });
 
 /**

package/src/testing.d.ts

@@ -0,0 +1,16 @@
+export interface PatchApplier {
+	registerPageRoot(pageRootHandle: unknown): void;
+	applyPatch(ops: unknown[]): void;
+	/** The real PAPI element handle for a given background-side id, or
+	 * `undefined` if nothing was ever created for it. */
+	getHandle(id: unknown): unknown;
+}
+
+/** See apply-patch.js's own header for the exact op vocabulary this replays. */
+export function createPatchApplier(pageId: unknown, options?: { onEvent?: (id: unknown, type: string, payload: unknown) => void }): PatchApplier;
+
+/** Installs the @lynx-js/testing-environment PAPI gap-fill mithril-lynx
+ * needs, on the main-thread globals object it hands to
+ * `onInjectMainThreadGlobals`. See testing.js's own header for exactly what
+ * this covers. */
+export function installTestingPolyfills(target: any): void;

package/src/testing.js

@@ -0,0 +1,48 @@
+// src/testing.js
+//
+// Reusable @lynx-js/testing-environment PAPI polyfill + patch applier for
+// apps/libraries built on mithril-lynx, not just this package's own test
+// suite — same reason the previous mithril-lynx exposed its own
+// mithril-lynx/testing: a separate package (mithril-lynx-ui, or any app)
+// needs the exact same gap-fill to write a REAL end-to-end test (mount via
+// renderApp(), replay the resulting ops onto real Element PAPI via
+// @lynx-js/testing-environment, dispatch a real event) rather than mocking
+// mithril-lynx itself.
+//
+// Usage, in a test setup file (e.g. test/setup.ts):
+//
+//   import { installTestingPolyfills } from "mithril-lynx/testing";
+//   globalThis.onInjectMainThreadGlobals = installTestingPolyfills;
+//
+// createPatchApplier is re-exported here too — it's what a test needs to
+// actually replay a renderApp() root's ops onto real PAPI elements (see
+// this package's own test/end-to-end.test.ts for the full pattern); it has
+// no other public export point.
+
+export { createPatchApplier } from "./apply-patch.js";
+
+/**
+ * Installs the polyfill on the main-thread globals object
+ * @lynx-js/testing-environment hands to onInjectMainThreadGlobals. Scoped
+ * to exactly what apply-patch.js calls (no gesture/list support — those
+ * don't exist in mithril-lynx yet, see the main README's known gaps):
+ * @lynx-js/testing-environment already implements __CreateView/__CreateText/
+ * __CreateElement/__CreateRawText/__AppendElement/__InsertElementBefore/
+ * __RemoveElement/__SetAttribute/__SetClasses/__AddInlineStyle/
+ * __FlushElementTree/__GetElementUniqueID — the one real gap is
+ * __AddEventListener (the testing environment only implements the
+ * string/worklet-event __AddEvent family that ReactLynx uses; mithril-lynx
+ * binds real JS function listeners directly).
+ */
+export function installTestingPolyfills(target) {
+	target.lynx.getEngine = target.lynx.getNative;
+
+	target.__AddEventListener = (node, name, handler) => {
+		node.__vanillaListeners ??= {};
+		(node.__vanillaListeners[name] ??= new Set()).add(handler);
+	};
+
+	target.__RemoveEventListener = (node, name, handler) => {
+		node.__vanillaListeners?.[name]?.delete(handler);
+	};
+}

package/test/gesture.test.ts

@@ -0,0 +1,175 @@
+import { describe, expect, it } from "@rstest/core";
+import m from "mithril";
+import { renderApp } from "../src/background.js";
+import { createPatchApplier } from "../src/apply-patch.js";
+
+// Op.SetGestureDetector end-to-end: a component calls vnode.dom's own
+// setGestureDetector() (fake-dom.js) in oncreate, the resulting op gets
+// replayed onto a REAL simulated __SetGestureDetector call (via
+// @lynx-js/testing-environment, not a mock), and the arena-claim policy
+// (apply-patch.js's own createArenaTracker) is exercised by extracting the
+// registered worklet callbacks and invoking them the same way native would
+// — see mithril-lynx-ui's docs/native-papi/papi-05-native-gestures.md for
+// the full design writeup this implements.
+
+function gestureCallbacksOf(handle: any): Record<string, (event: unknown, controller: unknown) => void> {
+	const entries = handle.gesture.config.callbacks as { name: string; callback: unknown }[];
+	const out: Record<string, (event: unknown, controller: unknown) => void> = {};
+	for (const entry of entries) {
+		out[entry.name] = (event, controller) => (globalThis as any).runWorklet(entry.callback, [event, controller]);
+	}
+	return out;
+}
+
+function touchEvent(clientX: number, clientY: number) {
+	return { params: { clientX, clientY } };
+}
+
+function makeController() {
+	const calls: { fn: string; args: unknown[] }[] = [];
+	return {
+		calls,
+		__SetGestureState(...args: unknown[]) {
+			calls.push({ fn: "__SetGestureState", args });
+		},
+		__ConsumeGesture(...args: unknown[]) {
+			calls.push({ fn: "__ConsumeGesture", args });
+		},
+	};
+}
+
+function mountWithGesture(arenaPolicy: unknown) {
+	lynxTestingEnv.switchToMainThread();
+	const pageId = __GetElementUniqueID(__CreatePage());
+	const receivedEvents: { type: string; clientX: number; clientY: number }[] = [];
+	const applier = createPatchApplier(pageId, {
+		onEvent: (id, type, payload: any) => {
+			receivedEvents.push({ type, clientX: payload.clientX, clientY: payload.clientY });
+		},
+	});
+	applier.registerPageRoot(__CreateView(pageId));
+
+	lynxTestingEnv.switchToBackgroundThread();
+	let lastOps: unknown[] | null = null;
+	const app = renderApp({
+		root: () => m("view", { class: "target", oncreate: (vnode: any) => vnode.dom.setGestureDetector("native", arenaPolicy) }),
+		sendPatch: (ops) => {
+			lastOps = ops;
+		},
+	});
+
+	lynxTestingEnv.switchToMainThread();
+	applier.applyPatch(lastOps as unknown[]);
+
+	const handle = applier.getHandle(1);
+	return { handle, callbacks: gestureCallbacksOf(handle), receivedEvents };
+}
+
+describe("Op.SetGestureDetector (native gesture support)", () => {
+	it("registers a real __SetGestureDetector call with the given type", () => {
+		const { handle } = mountWithGesture({ mode: "claim" });
+		expect(handle.gesture.type).toBe(7); // GESTURE_TYPE_CODES.native
+	});
+
+	it('"claim" policy claims on touches-down and never reconsiders', () => {
+		const { callbacks } = mountWithGesture({ mode: "claim" });
+		const controller = makeController();
+
+		callbacks.onTouchesDown(touchEvent(0, 0), controller);
+		callbacks.onTouchesMove(touchEvent(50, 0), controller);
+		callbacks.onTouchesMove(touchEvent(0, 50), controller); // even a vertical move — no reconsideration
+
+		expect(controller.calls).toEqual([{ fn: "__ConsumeGesture", args: [expect.anything(), expect.any(Number), { consume: true, inner: false }] }]);
+	});
+
+	it('"axis-lock" (referenceMoves: 0) decides on the first move, using touches-down as the reference', () => {
+		const { callbacks } = mountWithGesture({ mode: "axis-lock", axis: "horizontal", referenceMoves: 0 });
+		const controller = makeController();
+
+		callbacks.onTouchesDown(touchEvent(0, 0), controller);
+		callbacks.onTouchesMove(touchEvent(40, 5), controller); // mostly horizontal
+
+		expect(controller.calls.map((c) => c.fn)).toEqual(["__ConsumeGesture", "__ConsumeGesture"]);
+		expect(controller.calls[1].args[2]).toEqual({ consume: true, inner: false });
+	});
+
+	it('"axis-lock" releases and fails the gesture when the losing axis wins', () => {
+		const { callbacks } = mountWithGesture({ mode: "axis-lock", axis: "horizontal", referenceMoves: 0 });
+		const controller = makeController();
+
+		callbacks.onTouchesDown(touchEvent(0, 0), controller);
+		callbacks.onTouchesMove(touchEvent(5, 40), controller); // mostly vertical
+
+		// Claim eagerly on down, release once the axis loses, THEN fail —
+		// releasing the claim before failing matters: an ancestor (e.g. a
+		// <scroll-view>) must see the arena freed, not just "this gesture gave up".
+		expect(controller.calls.map((c) => c.fn)).toEqual(["__ConsumeGesture", "__ConsumeGesture", "__SetGestureState"]);
+		expect(controller.calls[1].args[2]).toEqual({ consume: false, inner: false });
+		expect(controller.calls[2].args[2]).toBe(2); // GestureState.fail (args: [handle, gestureId, state])
+	});
+
+	it('"axis-lock" (referenceMoves: 1) uses the first move as reference and decides on the second', () => {
+		const { callbacks } = mountWithGesture({ mode: "axis-lock", axis: "horizontal", referenceMoves: 1 });
+		const controller = makeController();
+
+		callbacks.onTouchesDown(touchEvent(0, 0), controller);
+		callbacks.onTouchesMove(touchEvent(10, 10), controller); // just records the reference — no decision yet
+		expect(controller.calls.map((c) => c.fn)).toEqual(["__ConsumeGesture"]);
+
+		callbacks.onTouchesMove(touchEvent(60, 15), controller); // horizontal relative to the FIRST move
+		expect(controller.calls.map((c) => c.fn)).toEqual(["__ConsumeGesture", "__ConsumeGesture"]);
+	});
+
+	it("forwards touches-down/move/up to the background thread as gesturedown/gesturemove/gestureup events", () => {
+		const { callbacks, receivedEvents } = mountWithGesture({ mode: "claim" });
+		const controller = makeController();
+
+		callbacks.onTouchesDown(touchEvent(1, 2), controller);
+		callbacks.onTouchesMove(touchEvent(3, 4), controller);
+		callbacks.onTouchesUp(touchEvent(5, 6), controller);
+
+		expect(receivedEvents).toEqual([
+			{ type: "gesturedown", clientX: 1, clientY: 2 },
+			{ type: "gesturemove", clientX: 3, clientY: 4 },
+			{ type: "gestureup", clientX: 5, clientY: 6 },
+		]);
+	});
+
+	it("a forwarded gesture event reaches the background-thread fake-dom node like any other event", () => {
+		lynxTestingEnv.switchToMainThread();
+		const pageId = __GetElementUniqueID(__CreatePage());
+		let forward: ((id: number, type: string, payload: unknown) => void) | null = null;
+		const applier = createPatchApplier(pageId, {
+			onEvent: (id, type, payload) => forward?.(id, type, payload),
+		});
+		applier.registerPageRoot(__CreateView(pageId));
+
+		lynxTestingEnv.switchToBackgroundThread();
+		const moves: number[] = [];
+		let lastOps: unknown[] | null = null;
+		const app = renderApp({
+			root: () =>
+				m("view", {
+					class: "target",
+					oncreate: (vnode: any) => vnode.dom.setGestureDetector("native", { mode: "claim" }),
+					ongesturemove: (e: any) => moves.push(e.clientX),
+				}),
+			sendPatch: (ops) => {
+				lastOps = ops;
+			},
+		});
+		forward = (id, type, payload: any) => {
+			const node = app.document.getNodeById(id);
+			node?.dispatchEvent({ type, currentTarget: node, ...payload });
+		};
+
+		lynxTestingEnv.switchToMainThread();
+		applier.applyPatch(lastOps as unknown[]);
+		const handle = applier.getHandle(1);
+		const callback = gestureCallbacksOf(handle).onTouchesMove;
+		const controller = makeController();
+		callback(touchEvent(42, 0), controller);
+
+		expect(moves).toEqual([42]);
+	});
+});

package/test/list.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from "@rstest/core";
+import m from "mithril";
+import { createPatchApplier } from "../src/apply-patch.js";
+import { registerListRenderer } from "../src/list-support.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.
+
+function requestCell(listHandle: any, index: number, opId = 1) {
+	const listId = __GetElementUniqueID(listHandle);
+	return listHandle.componentAtIndex(listHandle, listId, index, opId);
+}
+
+function releaseCell(listHandle: any, sign: unknown) {
+	const listId = __GetElementUniqueID(listHandle);
+	listHandle.enqueueComponent(listHandle, listId, sign);
+}
+
+function textOf(node: any): string {
+	if (node == null) return "";
+	let out = "";
+	for (let child = node.firstChild; child != null; child = child.nextSibling) {
+		out += child.nodeType === 3 ? child.nodeValue : textOf(child);
+	}
+	return out;
+}
+
+function setupList(rendererKey: string) {
+	lynxTestingEnv.switchToMainThread();
+	const pageId = __GetElementUniqueID(__CreatePage());
+	const applier = createPatchApplier(pageId);
+	applier.registerPageRoot(__CreateView(pageId));
+	applier.applyPatch([Op.CreateList, 1, rendererKey, "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)]);
+}
+
+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"]);
+
+		requestCell(listHandle, 0);
+		requestCell(listHandle, 1);
+		const cellWrapper = listHandle.children[1]; // second appended cell -> index 1
+		expect(textOf(cellWrapper)).toBe("1:b");
+	});
+
+	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 signA = requestCell(listHandle, 0);
+		const wrapperA = listHandle.children[0];
+		expect(textOf(wrapperA)).toBe("0:a");
+
+		releaseCell(listHandle, signA);
+		const signD = requestCell(listHandle, 3);
+
+		// Recycled: the SAME sign/wrapper comes back, now showing the new index's content.
+		expect(signD).toBe(signA);
+		expect(textOf(wrapperA)).toBe("3:d");
+	});
+
+	it("SetListItems with a larger array requests the newly available indices without error", () => {
+		registerListRenderer("grow", (item: string, index: number) => m("text", {}, `${index}:${item}`));
+
+		const { applier, listHandle } = setupList("grow");
+
+		setItems(applier, ["a", "b"]);
+		expect(() => requestCell(listHandle, 1)).not.toThrow();
+		expect(() => requestCell(listHandle, 2)).toThrow(/cellIndex 2 out of range/);
+
+		setItems(applier, ["a", "b", "c"]);
+		expect(() => requestCell(listHandle, 2)).not.toThrow();
+	});
+});

package/test/setup.ts

@@ -1,25 +1,9 @@
 // test/setup.ts
 //
-// The minimal gap-fill on top of @lynx-js/testing-environment's own PAPI
-// polyfill — same idea as the previous mithril-lynx's testing.js, scoped
-// down to only what apply-patch.js actually calls so far (no gestures/lists
-// yet, see the plan's non-goals). `@lynx-js/testing-environment` already
-// implements __CreateView/__CreateText/__CreateElement/__CreateRawText/
-// __AppendElement/__InsertElementBefore/__RemoveElement/__SetAttribute/
-// __SetClasses/__AddInlineStyle/__FlushElementTree/__GetElementUniqueID —
-// the one real gap is __AddEventListener (the testing environment only
-// implements the string/worklet-event __AddEvent family that ReactLynx
-// uses; mithril-lynx binds real JS function listeners directly).
+// This package's own tests use the exact same polyfill it now publishes
+// for everyone else (src/testing.js's installTestingPolyfills) — see that
+// file's header for what it covers and why.
 
-globalThis.onInjectMainThreadGlobals = (target: any) => {
-	target.lynx.getEngine = target.lynx.getNative;
+import { installTestingPolyfills } from "../src/testing.js";
 
-	target.__AddEventListener = (node: any, name: string, handler: (...args: unknown[]) => unknown) => {
-		node.__vanillaListeners ??= {};
-		(node.__vanillaListeners[name] ??= new Set()).add(handler);
-	};
-
-	target.__RemoveEventListener = (node: any, name: string, handler: unknown) => {
-		node.__vanillaListeners?.[name]?.delete(handler);
-	};
-};
+globalThis.onInjectMainThreadGlobals = installTestingPolyfills;