mithril-lynx 2.0.2 → 2.5.0

package/package.json

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

package/src/apply-patch.js

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

package/src/backends/virtual-backend.js

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

package/src/fake-dom.js

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

package/src/list-support.d.ts

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

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;