mithril-lynx 2.6.0 → 2.6.2

package/src/apply-patch.js

@@ -216,6 +216,12 @@ export function createPatchApplier(pageId, { onEvent, flush = true } = {}) {
 	// device), only `handles` (a plain Map) does.
 	const listSetters = new Map();
 
+	// id -> Map<event type, listener callback>. `__AddEventListener` needs the
+	// exact callback reference back when `__RemoveEventListener` runs, so the
+	// listener cannot be an inline closure re-created per Op.AddEvent — it is
+	// stored here and reused by the Op.RemoveEvent case.
+	const eventListeners = 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
@@ -359,18 +365,43 @@ export function createPatchApplier(pageId, { onEvent, flush = true } = {}) {
 					const id = ops[i++];
 					const type = ops[i++];
 					const handle = handles.get(id);
-					__AddEventListener(handle, type, (nativeEvent) => {
+					const listener = (nativeEvent) => {
 						onEvent?.(id, type, nativeEvent);
-					}, {});
+					};
+					let byType = eventListeners.get(id);
+					if (byType == null) eventListeners.set(id, (byType = new Map()));
+					byType.set(type, listener);
+					__AddEventListener(handle, type, listener, {});
 					break;
 				}
 				case Op.RemoveEvent: {
-					// PAPI has no documented `__RemoveEventListener` in the
-					// validated v1 surface (CONTRACT.md never needed it,
-					// since mithril-lynx v1 never tore down individual
-					// listeners outside of removing the whole element).
-					// Left as an explicit no-op + TODO rather than a guess.
-					i += 2;
+					const id = ops[i++];
+					const type = ops[i++];
+					const handle = handles.get(id);
+					const byType = eventListeners.get(id);
+					const listener = byType ? byType.get(type) : undefined;
+					if (typeof __RemoveEventListener === "function") {
+						// Native Fiber requires the options argument (>= 4 params) and
+						// derives the binding slot from it — pass the same `{}` the
+						// Op.AddEvent case uses so add/remove target the same slot.
+						if (listener != null) __RemoveEventListener(handle, type, listener, {});
+					} else if (listener != null) {
+						// Failing loudly is deliberate: without __RemoveEventListener a
+						// remove→re-add cycle on a kept element would accumulate
+						// duplicate native listeners and fire the handler N times per
+						// event. A silent no-op here is exactly the class of bug the
+						// whole project refuses to ship.
+						throw new Error(
+							"[mithril-lynx] __RemoveEventListener is not available on this runtime, " +
+								"so Op.RemoveEvent cannot be applied — a conditional event handler " +
+								"would leak duplicate listeners. Keep the handler constant or " +
+								"remove the whole element instead.",
+						);
+					}
+					if (byType != null) {
+						byType.delete(type);
+						if (byType.size === 0) eventListeners.delete(id);
+					}
 					break;
 				}
 				case Op.SetGestureDetector: {
@@ -401,8 +432,8 @@ export function createPatchApplier(pageId, { onEvent, flush = true } = {}) {
 				}
 				case Op.SetListItems: {
 					const id = ops[i++];
-					const cellsJSON = ops[i++];
-					listSetters.get(id)(JSON.parse(cellsJSON));
+					const cells = ops[i++];
+					listSetters.get(id)(cells);
 					break;
 				}
 				default:

package/src/backends/virtual-backend.js

@@ -81,7 +81,7 @@ export function createVirtualBackend() {
 			return id;
 		},
 		setListItems(id, cells) {
-			pushOp(ops, Op.SetListItems, id, JSON.stringify(cells));
+			pushOp(ops, Op.SetListItems, id, cells);
 		},
 		/** Drains and returns the accumulated ops. Called once per commit. */
 		takeOps() {

package/src/background.d.ts

@@ -3,9 +3,22 @@ export interface RenderAppOptions {
 	sendPatch?: (ops: unknown[]) => void;
 }
 
+/** Minimal shape of a fake-DOM node exposed for tests and HMR glue — enough
+ * to dispatch a synthetic event (e.g. `node.dispatchEvent({ type: "tap" })`)
+ * and correlate with a background-side id. */
+export interface LynxNode {
+	dispatchEvent(event: unknown): unknown;
+}
+
+/** The subset of the fake-DOM document exposed on the render handle — used
+ * by tests and by an app's own HMR glue, never by the channel wiring. */
+export interface LynxDocument {
+	getNodeById(id: number): LynxNode | null;
+}
+
 export interface RenderAppHandle {
 	redraw: () => void;
-	document: unknown;
+	document: LynxDocument;
 }
 
 export function renderApp(options: RenderAppOptions): RenderAppHandle;

package/src/channel.js

@@ -20,9 +20,17 @@ export const eventFromMainThreadEventName = "MithrilLynx:Event";
 export const renderPageEventName = "__RenderPage";
 export const destroyLifetimeEventName = "__DestroyLifetime";
 
-/** Background thread: ship one commit's ops to the main thread. */
+import { PROTOCOL_VERSION } from "./patch-protocol.js";
+
+/**
+ * Background thread: ship one commit's ops to the main thread.
+ *
+ * The patch is prefixed with `PROTOCOL_VERSION` so the main thread can
+ * detect a stale/desynced bundle (partial HMR, cache) and fail loudly
+ * instead of re-interpreting reordered opcodes against the shared id space.
+ */
 export function sendPatchToMainThread(ops) {
-	lynx.getCoreContext().dispatchEvent({ type: patchEventName, data: ops });
+	lynx.getCoreContext().dispatchEvent({ type: patchEventName, data: [PROTOCOL_VERSION, ...ops] });
 }
 
 /** Background thread: receive a forwarded native event `{ id, type, payload }`. */

package/src/list-support.js

@@ -46,10 +46,35 @@ export function createNativeList(pageId, scrollOrientation, listType, spanCount,
 		}
 	}
 
+	/** The wrapper of the lowest currently-attached cellIndex greater than
+	 * `cellIndex`, or null if none — the DOM position a cell at `cellIndex`
+	 * needs to be inserted before to land in the right place. Native lays
+	 * cells out in document-tree order, not by `item-key`, so a recycled
+	 * wrapper that keeps its OLD tree position (this file's own first
+	 * version never repositioned it at all) shows up out of order the
+	 * moment it's reused for a different index — confirmed on real
+	 * hardware via a scrambled child order after scrolling (item-keys
+	 * 7,8,9,3,4,5,6). Same problem `@lynx-js/react`'s own
+	 * `attachListItemAtIndex`/`findNextAttachedItem` solves for its
+	 * Element Template list. */
+	function findNextAttachedWrapper(cellIndex) {
+		let best = null;
+		for (const entry of signMap.values()) {
+			if (entry.cellIndex > cellIndex && (best == null || entry.cellIndex < best.cellIndex)) best = entry;
+		}
+		return best ? best.wrapperHandle : null;
+	}
+
+	function attachWrapper(listHandle, wrapperHandle, cellIndex) {
+		const refHandle = findNextAttachedWrapper(cellIndex);
+		if (refHandle != null) __InsertElementBefore(listHandle, wrapperHandle, refHandle);
+		else __AppendElement(listHandle, wrapperHandle);
+	}
+
 	function bindFreshItem(listHandle, listId, cellIndex, opId, cell, flush) {
 		const wrapperHandle = __CreateElement("list-item", pageId, {});
 		__SetAttribute(wrapperHandle, "item-key", String(cellIndex));
-		__AppendElement(listHandle, wrapperHandle);
+		attachWrapper(listHandle, wrapperHandle, cellIndex);
 
 		const applier = replayCell(wrapperHandle, cell);
 		const sign = __GetElementUniqueID(wrapperHandle);
@@ -58,11 +83,12 @@ export function createNativeList(pageId, scrollOrientation, listType, spanCount,
 		return sign;
 	}
 
-	function bindRecycledItem(listId, cellIndex, opId, cell, pool, flush) {
+	function bindRecycledItem(listHandle, listId, cellIndex, opId, cell, pool, flush) {
 		const [sign, entry] = pool.entries().next().value;
 		pool.delete(sign);
 		clearWrapperChildren(entry);
 		__SetAttribute(entry.wrapperHandle, "item-key", String(cellIndex));
+		attachWrapper(listHandle, entry.wrapperHandle, cellIndex);
 		const applier = replayCell(entry.wrapperHandle, cell);
 		entry.applier = applier;
 		entry.rootChildIds = cell.rootChildIds;
@@ -78,7 +104,7 @@ export function createNativeList(pageId, scrollOrientation, listType, spanCount,
 		}
 		const cell = cells[cellIndex];
 		const pool = recycleMap.get(cell.typeKey);
-		if (pool && pool.size > 0) return bindRecycledItem(listId, cellIndex, opId, cell, pool, flush);
+		if (pool && pool.size > 0) return bindRecycledItem(listHandle, listId, cellIndex, opId, cell, pool, flush);
 		return bindFreshItem(listHandle, listId, cellIndex, opId, cell, flush);
 	}
 

package/src/main-thread.js

@@ -10,6 +10,7 @@
 // was never part of the bug this rewrite exists to fix.
 
 import { createPatchApplier } from "./apply-patch.js";
+import { PROTOCOL_VERSION } from "./patch-protocol.js";
 import {
 	destroyLifetimeEventName,
 	onPatchFromBackground,
@@ -39,11 +40,23 @@ export function setupRenderer() {
 	let pendingPatches = [];
 
 	const onPatch = (event) => {
+		const data = event.data;
+		if (!Array.isArray(data) || data[0] !== PROTOCOL_VERSION) {
+			throw new Error(
+				`[mithril-lynx] patch protocol mismatch: expected version ${PROTOCOL_VERSION}, ` +
+					`got ${Array.isArray(data) ? String(data[0]) : typeof data}. ` +
+					"This is always a stale/desynced bundle (partial HMR or a cached main-thread chunk) — " +
+					"rebuild both bundles together.",
+			);
+		}
+		// Strip the version prefix so applyPatch() still receives the bare
+		// flat op array the rest of the protocol documents.
+		const ops = data.slice(1);
 		if (!pageReady) {
-			pendingPatches.push(event.data);
+			pendingPatches.push(ops);
 			return;
 		}
-		applier.applyPatch(event.data);
+		applier.applyPatch(ops);
 	};
 	onPatchFromBackground(onPatch);
 

package/src/mount-redraw.d.ts

@@ -6,6 +6,16 @@
  * auto-redraw-after-event contract doesn't cover. */
 export function register(redraw: () => void): void;
 
+/** Clears the current redraw registration (and the pending debounce flag).
+ * Fail-fast counterpart to {@link register}: a second `register()` throws,
+ * so call this on teardown or full reload before mounting a new app. */
+export function unregister(): void;
+
+/** Overrides the debounce delay `redraw()` uses (default 50ms — see the
+ * `mount-redraw.js` header for why it is an empirical margin, not a
+ * scheduling guarantee). */
+export function configure(options?: { redrawDelayMs?: number }): 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

package/src/mount-redraw.js

@@ -48,16 +48,68 @@ const REDRAW_DELAY_MS = 50;
 
 let currentRedraw = null;
 let pending = false;
+/** Handle of the currently-scheduled redraw timer, so `unregister()` can
+ * cancel it instead of leaving a stray callback that fires into a later
+ * mount. */
+let pendingTimer = null;
+/** Overridable via {@link configure}; defaults to REDRAW_DELAY_MS. */
+let redrawDelayMs = REDRAW_DELAY_MS;
+
+/**
+ * Overrides the debounce delay `redraw()` uses. Defaults to `REDRAW_DELAY_MS`
+ * (50ms) — the empirically-chosen margin documented at the top of this file,
+ * which is a safety margin rather than a scheduling guarantee. A device whose
+ * timer behaves differently (see FETCH_INVESTIGATION.md §4.6) can raise or
+ * lower it here.
+ */
+export function configure(options) {
+	if (options && options.redrawDelayMs != null) {
+		redrawDelayMs = options.redrawDelayMs;
+	}
+}
 
 function schedule(fn) {
 	const timer = typeof lynx !== "undefined" && typeof lynx.setTimeout === "function" ? lynx.setTimeout.bind(lynx) : setTimeout;
-	timer(fn, REDRAW_DELAY_MS);
+	return timer(fn, redrawDelayMs);
 }
 
+/**
+ * Registers the current app's redraw. Fail-fast: throws if a redraw is
+ * already registered, because a second live `renderApp()` in the same
+ * background context would silently overwrite the slot and let two
+ * documents corrupt the shared id space (see R2 in
+ * informe-contrato-mithril-lynx.md). Call {@link unregister} on teardown
+ * or full reload before registering a new one.
+ */
 export function register(redraw) {
+	if (currentRedraw != null) {
+		throw new Error(
+			"[mithril-lynx] redraw already registered — a shim instance is single-use: " +
+				"one renderApp() per background context, one redraw slot, for the " +
+				"lifetime of that context. Call unregister() (or do a full reload) " +
+				"before mounting a new app.",
+		);
+	}
 	currentRedraw = redraw;
 }
 
+/**
+ * Clears the current redraw registration (and the pending debounce flag) —
+ * used by a full reload and by the test suite between mounts. After this,
+ * `redraw()` is a no-op again until the next `register()`.
+ */
+export function unregister() {
+	currentRedraw = null;
+	pending = false;
+	if (pendingTimer != null) {
+		const clear = typeof lynx !== "undefined" && typeof lynx.clearTimeout === "function"
+			? lynx.clearTimeout.bind(lynx)
+			: clearTimeout;
+		clear(pendingTimer);
+		pendingTimer = null;
+	}
+}
+
 /** What `request.js` calls after a non-background request resolves. A
  * no-op before any app has mounted — a request kicked off before
  * renderApp()/route() ran has nothing to redraw yet, which isn't
@@ -67,7 +119,8 @@ export function register(redraw) {
 export function redraw() {
 	if (pending) return;
 	pending = true;
-	schedule(() => {
+	pendingTimer = schedule(() => {
+		pendingTimer = null;
 		pending = false;
 		if (currentRedraw != null) currentRedraw();
 	});

package/src/patch-protocol.js

@@ -13,6 +13,20 @@
 // main-thread side by `applyPatch()` (see backends/papi-backend.js), so
 // nodes never need to be looked up by anything other than that integer.
 
+/**
+ * The wire protocol version, prepended to every patch by
+ * `sendPatchToMainThread()` and validated (then stripped) by the main
+ * thread before any op is interpreted. The two bundles are normally built
+ * from the same source, but a partial HMR or a cached main-thread bundle
+ * could otherwise re-interpret a reordered opcode silently — a version
+ * mismatch throws instead of corrupting the mirrored id space.
+ *
+ * The value is deliberately outside the 0..17 opcode range (0x4d4c = "ML"
+ * in ASCII) so a versioned array can never be misread as an op sequence if
+ * it is ever fed to `applyPatch()` without the strip.
+ */
+export const PROTOCOL_VERSION = 0x4d4c;
+
 export const Op = Object.freeze({
 	CreateElement: 0,
 	CreateElementNS: 1,
@@ -49,7 +63,7 @@ export const Op = Object.freeze({
 	// 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.
+	SetListItems: 17, // id, 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.
 });
 
 /**
@@ -85,7 +99,7 @@ export const OP_ARITY = Object.freeze({
 	[Op.SetGestureDetector]: 4, // id, gestureId, gestureType, arenaPolicy
 	[Op.RemoveGestureDetector]: 2, // id, gestureId
 	[Op.CreateList]: 4, // id, scrollOrientation, listType, spanCount
-	[Op.SetListItems]: 2, // id, cellsJSON
+	[Op.SetListItems]: 2, // id, cells
 });
 
 /** Walks a flat ops array, calling `visit(opcode, args)` once per op — args

package/src/request.d.ts

@@ -10,6 +10,8 @@ export interface RequestOptions<T = any> {
 	serialize?: (data: unknown) => string;
 	deserialize?: (data: unknown) => unknown;
 	extract?: (response: unknown, options: RequestOptions<T>) => unknown;
+	/** A constructor applied to the response: per element when the response
+	 * is an array (matching real `m.request`), otherwise to the whole result. */
 	type?: new (data: any) => T;
 	background?: boolean;
 	// Present on the real m.request signature but confirmed unsupported —

package/src/request.js

@@ -112,9 +112,13 @@ export function createRequestor(fetchImpl) {
 		// controller so a caller-provided signal and our timeout can both
 		// trigger the same abort.
 		const ctrl = new AbortController();
+		// Stored so the listener can be detached on settle (see detachSignal
+		// below) — a long-lived shared AbortSignal would otherwise accumulate
+		// one dead closure per request.
+		const abortHandler = () => ctrl.abort();
 		if (options.signal) {
 			if (options.signal.aborted) ctrl.abort();
-			else options.signal.addEventListener("abort", () => ctrl.abort());
+			else options.signal.addEventListener("abort", abortHandler);
 		}
 		let timeoutId;
 		if (options.timeout) {
@@ -138,8 +142,10 @@ export function createRequestor(fetchImpl) {
 
 			if (typeof options.extract === "function") {
 				// Matches real m.request: extract() bypasses the status check
-				// entirely — it decides success/failure itself.
-				return options.extract(response, options);
+				// entirely — it decides success/failure itself. `type` is still
+				// applied afterwards, exactly as upstream does (extract does NOT
+				// skip the type constructor).
+				return applyType(options.extract(response, options), options.type);
 			}
 
 			const ok = response.ok || response.status === 304;
@@ -156,12 +162,24 @@ export function createRequestor(fetchImpl) {
 			});
 		});
 
+		// Detach the caller's signal listener once this request settles, so a
+		// long-lived shared AbortSignal doesn't accumulate a dead closure per
+		// request. Done inside the settled handlers (rather than a separate
+		// `.then`) so an ignored rejection still surfaces as unhandled.
+		const detachSignal = () => {
+			if (options.signal && !options.signal.aborted) {
+				options.signal.removeEventListener("abort", abortHandler);
+			}
+		};
+
 		const result = promise.then(
 			(value) => {
+				detachSignal();
 				if (options.background !== true) sharedRedraw();
 				return value;
 			},
 			(error) => {
+				detachSignal();
 				clearRequestTimeout();
 				if (options.background !== true) sharedRedraw();
 				throw error;

package/src/route.d.ts

@@ -1,4 +1,14 @@
-import type { Component } from "mithril";
+/**
+ * Minimal Mithril-style component type. Declared locally because this
+ * package's runtime peer is `mithril-runtime`, which ships no TypeScript
+ * types of its own; the previous `import type { Component } from "mithril"`
+ * depended on an undeclared module. `view`'s return is typed `any` so
+ * `route.Link` stays assignable to a caller's own `m()` typed against
+ * `@types/mithril`.
+ */
+export interface Component<Attrs = unknown> {
+	view(vnode: { attrs: Attrs; children?: unknown }): any;
+}
 
 export interface RouteResolver {
 	onmatch?(args: Record<string, string>, requestedPath: string, route: string): unknown;
@@ -19,9 +29,18 @@ export interface Route {
 	(defaultRoute: string, routes: Record<string, unknown | RouteResolver>): void;
 	set(path: string, data?: unknown, options?: { replace?: boolean }): void;
 	get(): string | undefined;
+	/** Returns the named route parameter (with `key`), or the whole params
+	 * object (without). Typed `unknown` because the value can be a string
+	 * (path params), a string|boolean (query params — `"true"`/`"false"` are
+	 * coerced), or anything passed as `data` to `set(path, data)`; the common
+	 * path-param case is always a string. */
 	param(key?: string): unknown;
-	back(): void;
-	forward(): void;
+	/** Walks back one entry; returns `false` (without navigating) at the top
+	 * of the history stack so a back affordance can disable itself. */
+	back(): boolean;
+	/** Walks forward one entry; returns `false` (without navigating) at the
+	 * end of the history stack so a forward affordance can disable itself. */
+	forward(): boolean;
 	prefix: string;
 	SKIP: unknown;
 	Link: Component<RouteLinkAttrs>;

package/src/route.js

@@ -116,15 +116,32 @@ export function createRoute() {
 		if (!compiled.some((entry) => entry.check(defaultData))) {
 			throw new ReferenceError("Default route doesn't match any known routes.");
 		}
-		history = [defaultRoute];
-		historyIndex = 0;
-		ready = true;
-		resolveRoute(defaultRoute, null);
+		if (!ready) {
+			history = [defaultRoute];
+			historyIndex = 0;
+			ready = true;
+			resolveRoute(defaultRoute, null);
+		} else {
+			// Re-registration (e.g. HMR of the route module): keep the history
+			// stack and re-resolve the CURRENT path against the new table —
+			// the same thing the documented HMR pattern does by hand with
+			// route.set(route.get(), null, {replace: true}). Resolving
+			// defaultRoute here instead would silently jump the screen back to
+			// the initial route and discard the user's back/forward stack.
+			resolveRoute(currentPath != null ? currentPath : defaultRoute, null);
+		}
 	}
 
 	route.SKIP = {};
 
 	route.set = function (path, data, options) {
+		if (!ready) {
+			throw new Error(
+				"[mithril-lynx] route.set() called before route(defaultRoute, routes) — " +
+					"the route table does not exist yet, so this navigation would be " +
+					"silently dropped. Call route() first.",
+			);
+		}
 		if (lastUpdate != null) {
 			options = options || {};
 			options.replace = true;
@@ -161,14 +178,16 @@ export function createRoute() {
 	 * is F4/F5 of the plan, not done yet.
 	 */
 	route.back = function () {
-		if (historyIndex <= 0) return;
+		if (historyIndex <= 0) return false;
 		historyIndex--;
 		resolveRoute(history[historyIndex], null);
+		return true;
 	};
 	route.forward = function () {
-		if (historyIndex >= history.length - 1) return;
+		if (historyIndex >= history.length - 1) return false;
 		historyIndex++;
 		resolveRoute(history[historyIndex], null);
+		return true;
 	};
 
 	// Lynx has no `<a>`/`onclick` — this renders a tap-driven element

package/src/testing.js

@@ -24,25 +24,38 @@ 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).
+ * to the one real gap: @lynx-js/testing-environment already implements
+ * __CreateView/__CreateText/__CreateElement/__CreateRawText/__AppendElement/
+ * __InsertElementBefore/__RemoveElement/__SetAttribute/__SetClasses/
+ * __AddInlineStyle/__FlushElementTree/__GetElementUniqueID — the missing
+ * piece is __AddEventListener/__RemoveEventListener (the testing environment
+ * only implements the string/worklet-event __AddEvent family that ReactLynx
+ * uses; mithril-lynx binds real JS function listeners directly). Gesture and
+ * list ops (Op.SetGestureDetector/Op.CreateList) are covered by the testing
+ * environment itself, not by this polyfill — see test/gesture.test.ts and
+ * test/list.test.ts.
  */
 export function installTestingPolyfills(target) {
 	target.lynx.getEngine = target.lynx.getNative;
 
-	target.__AddEventListener = (node, name, handler) => {
+	// Faithful stand-ins for the native `__AddEventListener` /
+	// `__RemoveEventListener` PAPIs (element, name, callback, options). The
+	// options object is accepted and ignored here — the real native side
+	// requires it (FiberRemoveEventListener throws "param size should >= 4"
+	// without it), so __RemoveEventListener mirrors that arity requirement to
+	// keep the test environment honest about the wire contract.
+	target.__AddEventListener = (node, name, handler, _options) => {
 		node.__vanillaListeners ??= {};
 		(node.__vanillaListeners[name] ??= new Set()).add(handler);
 	};
 
-	target.__RemoveEventListener = (node, name, handler) => {
+	target.__RemoveEventListener = function (node, name, handler, _options) {
+		if (arguments.length < 4) {
+			throw new Error(
+				"[mithril-lynx/testing] __RemoveEventListener requires 4 params " +
+					"(element, name, callback, options) — matching FiberRemoveEventListener.",
+			);
+		}
 		node.__vanillaListeners?.[name]?.delete(handler);
 	};
 }

package/test/list.test.ts

@@ -59,7 +59,7 @@ function setupList() {
 }
 
 function setCells(applier: ReturnType<typeof createPatchApplier>, cells: unknown[]) {
-	applier.applyPatch([Op.SetListItems, 1, JSON.stringify(cells)]);
+	applier.applyPatch([Op.SetListItems, 1, cells]);
 }
 
 describe("Op.CreateList (native virtualized list support)", () => {
@@ -116,6 +116,24 @@ describe("Op.CreateList (native virtualized list support)", () => {
 		expect(textOf(wrapper)).toBe("0:z");
 	});
 
+	it("a recycled cell is repositioned in the real tree to match its new index, not left where it was created", () => {
+		const { buildCells } = makeCellSource((item: string, index: number) => m("text", {}, `${index}:${item}`));
+		const { applier, listHandle } = setupList();
+		setCells(applier, buildCells(["a", "b", "c", "d"]));
+
+		requestCell(listHandle, 0);
+		const signB = requestCell(listHandle, 1);
+		requestCell(listHandle, 2);
+		// Real tree order matches request order so far: a, b, c.
+		expect([listHandle.children[0], listHandle.children[1], listHandle.children[2]].map(textOf)).toEqual(["0:a", "1:b", "2:c"]);
+
+		releaseCell(listHandle, signB); // b's wrapper goes to the recycle pool, still sitting in the middle of the tree
+		requestCell(listHandle, 3); // recycled for "d" — index 3 is after every other attached cell, so it belongs at the END
+
+		const children = [listHandle.children[0], listHandle.children[1], listHandle.children[2]];
+		expect(children.map(textOf)).toEqual(["0:a", "2:c", "3:d"]); // not ["0:a", "3:d", "2:c"] — the bug this test guards against
+	});
+
 	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"),

package/test/patch-protocol.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from "@rstest/core";
+import { Op, OP_ARITY, PROTOCOL_VERSION, forEachOp, pushOp } from "../src/patch-protocol.js";
+
+// M8: OP_ARITY is the "single source of truth" for walking a flat op array,
+// but apply-patch.js re-implements the arity inline in its own switch. These
+// tests lock the two to each other: every opcode must have an arity entry
+// (no gap → no silent desync in forEachOp/list-cell), and the version prefix
+// must never collide with a real opcode.
+describe("patch-protocol OP_ARITY completeness", () => {
+	it("has an arity entry for every opcode in Op", () => {
+		const opcodes = Object.values(Op) as number[];
+		expect(opcodes.length).toBeGreaterThan(0);
+		for (const opcode of opcodes) {
+			expect(OP_ARITY[opcode], `OP_ARITY is missing opcode ${opcode}`).toBeDefined();
+		}
+	});
+
+	it("PROTOCOL_VERSION does not collide with any opcode value", () => {
+		for (const opcode of Object.values(Op) as number[]) {
+			expect(opcode).not.toBe(PROTOCOL_VERSION);
+		}
+	});
+
+	it("forEachOp walks a flat array built by pushOp without desyncing", () => {
+		const ops: unknown[] = [];
+		pushOp(ops, Op.CreateElement, "view", 1);
+		pushOp(ops, Op.SetText, 1, "hi");
+		pushOp(ops, Op.InsertBefore, 0, 1, -1);
+
+		const seen: number[] = [];
+		forEachOp(ops, (opcode, args) => {
+			seen.push(opcode);
+			if (opcode === Op.InsertBefore) expect(args).toEqual([0, 1, -1]);
+		});
+		expect(seen).toEqual([Op.CreateElement, Op.SetText, Op.InsertBefore]);
+	});
+
+	it("forEachOp throws on an unknown opcode instead of silently desyncing", () => {
+		expect(() => forEachOp([999], () => {})).toThrow(/Unknown patch opcode/);
+	});
+});