mithril-lynx 2.5.0 → 2.6.2

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

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

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/);
+	});
+});

package/test/remove-event.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from "@rstest/core";
+import { createPatchApplier } from "../src/apply-patch.js";
+import { Op } from "../src/patch-protocol.js";
+
+// R3: Op.RemoveEvent must actually remove the native listener, not silently
+// no-op — otherwise a remove→re-add cycle on a kept element accumulates
+// duplicate native listeners and the app's handler fires N times per event
+// (see informe-contrato-mithril-lynx.md §R3).
+describe("Op.RemoveEvent removes the native listener (no duplicate-fire leak)", () => {
+	it("AddEvent → RemoveEvent → AddEvent leaves exactly one listener", () => {
+		lynxTestingEnv.switchToMainThread();
+		const pageId = __GetElementUniqueID(__CreatePage());
+		const applier = createPatchApplier(pageId);
+		applier.registerPageRoot(__CreateView(pageId));
+
+		applier.applyPatch([Op.CreateElement, "view", 1, Op.AddEvent, 1, "tap"]);
+		const handle = applier.getHandle(1) as any;
+		expect(handle.__vanillaListeners.tap.size).toBe(1);
+
+		applier.applyPatch([Op.RemoveEvent, 1, "tap"]);
+		expect(handle.__vanillaListeners.tap.size).toBe(0);
+
+		applier.applyPatch([Op.AddEvent, 1, "tap"]);
+		expect(handle.__vanillaListeners.tap.size).toBe(1);
+	});
+});

package/test/route-hot-reload.test.ts

@@ -15,7 +15,8 @@ describe("route.js + stable-host: a same-path re-resolve patches in place, never
 		lynxTestingEnv.switchToMainThread();
 		const capturedOps: unknown[][] = [];
 		lynx.getJSContext().addEventListener("MithrilLynx:Patch", (event: any) => {
-			capturedOps.push(event.data);
+			// event.data is [PROTOCOL_VERSION, ...ops] — drop the version prefix.
+			capturedOps.push(event.data.slice(1));
 		});
 
 		lynxTestingEnv.switchToBackgroundThread();

package/test/route.test.ts

@@ -22,9 +22,12 @@ function setupRealTree() {
 	// tree inspected.
 	lynxTestingEnv.switchToMainThread();
 	lynx.getJSContext().addEventListener("MithrilLynx:Patch", (event: any) => {
-		capturedOps.push(event.data);
+		// event.data is [PROTOCOL_VERSION, ...ops] — mirror main-thread.js's
+		// own onPatch by stripping the version prefix before applying.
+		const ops = event.data.slice(1);
+		capturedOps.push(ops);
 		lynxTestingEnv.switchToMainThread();
-		applier.applyPatch(event.data);
+		applier.applyPatch(ops);
 	});
 
 	return { applier, capturedOps };

package/test/setup.ts

@@ -4,6 +4,16 @@
 // for everyone else (src/testing.js's installTestingPolyfills) — see that
 // file's header for what it covers and why.
 
+import { afterEach } from "@rstest/core";
 import { installTestingPolyfills } from "../src/testing.js";
+import { unregister } from "../src/mount-redraw.js";
 
 globalThis.onInjectMainThreadGlobals = installTestingPolyfills;
+
+// mount-redraw.js is a single-slot singleton and register() now fails fast
+// on a second registration (R2) — clear it between tests so each test's own
+// renderApp() starts from a clean slate instead of colliding with the
+// previous test's still-registered redraw.
+afterEach(() => {
+	unregister();
+});