mithril-lynx 2.6.0 → 3.0.0

package/test/remove-subtree-cleanup.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it } from "@rstest/core";
+import { createPatchApplier } from "../src/apply-patch.js";
+import { createVirtualBackend } from "../src/backends/virtual-backend.js";
+import { createLynxDocument } from "../src/fake-dom.js";
+import { Op } from "../src/patch-protocol.js";
+
+// Mithril's removeDOM only ever calls removeChild on the ROOT of a removed
+// subtree, so both threads must release every descendant's bookkeeping
+// themselves — otherwise a long-running app leaks every element (and its
+// listeners) it ever removed.
+describe("removing a subtree releases every descendant", () => {
+	it("main thread: RemoveChild drops the handles of the whole subtree", () => {
+		lynxTestingEnv.switchToMainThread();
+		const pageId = __GetElementUniqueID(__CreatePage());
+		const applier = createPatchApplier(pageId);
+		applier.registerPageRoot(__CreateView(pageId));
+
+		applier.applyPatch([
+			Op.CreateElement, "view", 1,
+			Op.CreateElement, "view", 2,
+			Op.CreateElement, "view", 3,
+			Op.InsertBefore, 0, 1, -1,
+			Op.InsertBefore, 1, 2, -1,
+			Op.InsertBefore, 2, 3, -1,
+			Op.AddEvent, 2, "tap",
+			Op.AddEvent, 3, "tap",
+		]);
+		expect(applier.getHandle(3)).toBeDefined();
+
+		applier.applyPatch([Op.RemoveChild, 0, 1]);
+		expect(applier.getHandle(1)).toBeUndefined();
+		expect(applier.getHandle(2)).toBeUndefined();
+		expect(applier.getHandle(3)).toBeUndefined();
+		expect(applier.getHandle(0)).toBeDefined();
+	});
+
+	it("main thread: a node moved out of the subtree before removal survives", () => {
+		lynxTestingEnv.switchToMainThread();
+		const pageId = __GetElementUniqueID(__CreatePage());
+		const applier = createPatchApplier(pageId);
+		applier.registerPageRoot(__CreateView(pageId));
+
+		applier.applyPatch([
+			Op.CreateElement, "view", 1,
+			Op.CreateElement, "view", 2,
+			Op.CreateElement, "view", 4,
+			Op.InsertBefore, 0, 1, -1,
+			Op.InsertBefore, 0, 4, -1,
+			Op.InsertBefore, 1, 2, -1,
+			// Move 2 from under 1 to under 4.
+			Op.InsertBefore, 4, 2, -1,
+		]);
+
+		applier.applyPatch([Op.RemoveChild, 0, 1]);
+		expect(applier.getHandle(1)).toBeUndefined();
+		expect(applier.getHandle(2)).toBeDefined();
+		expect(applier.getHandle(4)).toBeDefined();
+	});
+
+	it("background thread: removeChild drops the whole subtree from the id map", () => {
+		const document = createLynxDocument(createVirtualBackend());
+		const a = document.createElement("view");
+		const b = document.createElement("view");
+		const c = document.createElement("text");
+		document.appendChild(a);
+		a.appendChild(b);
+		b.appendChild(c);
+		expect(document.getNodeById(c._id)).toBe(c);
+
+		document.removeChild(a);
+		expect(document.getNodeById(a._id)).toBeNull();
+		expect(document.getNodeById(b._id)).toBeNull();
+		expect(document.getNodeById(c._id)).toBeNull();
+	});
+});

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

@@ -11,11 +11,12 @@ import { Op } from "../src/patch-protocol.js";
 // else. This test locks that in.
 
 describe("route.js + stable-host: a same-path re-resolve patches in place, never recreates", () => {
-	it("swapping the live-bound view (module.hot.accept's job) produces only a SetText, no Create/Remove", () => {
+	it("swapping the live-bound view (module.hot.accept's job) produces only a SetText, no Create/Remove", async () => {
 		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();
@@ -31,6 +32,7 @@ describe("route.js + stable-host: a same-path re-resolve patches in place, never
 
 		currentDetail = { view: () => m("text", { key: "title" }, "second") };
 		route.set(route.get() as string, null, { replace: true });
+		await Promise.resolve(); // navigation resolves on the next microtask
 
 		const flat = capturedOps.flat();
 		expect(flat).not.toContain(Op.CreateElement);

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 };
@@ -34,8 +37,11 @@ function setupRealTree() {
 // isn't exported from a stable path used elsewhere yet in tests.
 import { createPatchApplier } from "../src/apply-patch.js";
 
+/** Navigation resolves on the next microtask (like upstream m.route). */
+const settle = () => Promise.resolve();
+
 describe("route.js: in-memory router (plan m-route-en-memoria.md)", () => {
-	it("mounts the default route and exposes route.get()/route.param()", () => {
+	it("mounts the default route and exposes route.get()/route.param()", async () => {
 		setupRealTree();
 		lynxTestingEnv.switchToBackgroundThread();
 
@@ -48,11 +54,12 @@ describe("route.js: in-memory router (plan m-route-en-memoria.md)", () => {
 		expect(route.get()).toBe("/");
 
 		route.set("/users/42");
+		await settle();
 		expect(route.get()).toBe("/users/42");
 		expect(route.param("id")).toBe("42");
 	});
 
-	it("navigating replaces the screen with no orphaned nodes left behind", () => {
+	it("navigating replaces the screen with no orphaned nodes left behind", async () => {
 		const { capturedOps } = setupRealTree();
 		lynxTestingEnv.switchToBackgroundThread();
 
@@ -64,6 +71,7 @@ describe("route.js: in-memory router (plan m-route-en-memoria.md)", () => {
 		capturedOps.length = 0; // only care about the ops from the NAVIGATION below
 
 		route.set("/b");
+		await settle();
 
 		// Same spirit as test/structural-reload.test.ts, but here the whole
 		// screen changes (not a sibling insert) — the decisive check is
@@ -75,7 +83,7 @@ describe("route.js: in-memory router (plan m-route-en-memoria.md)", () => {
 		expect(navOps).toContain(Op.CreateElement);
 	});
 
-	it("back()/forward() walk the in-memory history stack", () => {
+	it("back()/forward() walk the in-memory history stack", async () => {
 		setupRealTree();
 		lynxTestingEnv.switchToBackgroundThread();
 
@@ -87,15 +95,19 @@ describe("route.js: in-memory router (plan m-route-en-memoria.md)", () => {
 		route("/a", { "/a": A, "/b": B, "/c": C });
 		route.set("/b");
 		route.set("/c");
+		await settle();
 		expect(route.get()).toBe("/c");
 
 		route.back();
+		await settle();
 		expect(route.get()).toBe("/b");
 
 		route.back();
+		await settle();
 		expect(route.get()).toBe("/a");
 
 		route.forward();
+		await settle();
 		expect(route.get()).toBe("/b");
 	});
 
@@ -126,7 +138,7 @@ describe("route.js: in-memory router (plan m-route-en-memoria.md)", () => {
 		});
 	});
 
-	it("route.Link navigates on tap, and disabled Links don't wire ontap", () => {
+	it("route.Link navigates on tap, and disabled Links don't wire ontap", async () => {
 		setupRealTree();
 		lynxTestingEnv.switchToBackgroundThread();
 
@@ -141,6 +153,7 @@ describe("route.js: in-memory router (plan m-route-en-memoria.md)", () => {
 		});
 		expect(typeof link.attrs.ontap).toBe("function");
 		link.attrs.ontap({ currentTarget: null, redraw: true });
+		await settle();
 		expect(route.get()).toBe("/b");
 
 		const disabledLink = (route as any).Link.view({
@@ -150,3 +163,190 @@ describe("route.js: in-memory router (plan m-route-en-memoria.md)", () => {
 		expect(disabledLink.attrs.ontap).toBeUndefined();
 	});
 });
+
+// Parity fixes found by ROUTE_CONTRACT_ANALYSIS.md — each one was first
+// reproduced against the previous route.js, then fixed.
+describe("route.js: parity with Mithril 2.3.8's m.route", () => {
+	function mountRoute(defaultRoute: string, routes: Record<string, unknown>) {
+		setupRealTree();
+		lynxTestingEnv.switchToBackgroundThread();
+		const route = createRoute();
+		route(defaultRoute, routes);
+		return route;
+	}
+
+	it("a redirect from a page's oninit (a guard) works instead of throwing mid-render", async () => {
+		let route: ReturnType<typeof createRoute> | null = null;
+		const Guarded = { oninit: () => route!.set("/login"), view: () => m("text", null, "secret") };
+		route = mountRoute("/", { "/": { view: () => m("text", null, "home") }, "/secret": Guarded, "/login": { view: () => m("text", null, "login") } });
+
+		route!.set("/secret");
+		await settle();
+		await settle();
+		expect(route!.get()).toBe("/login");
+	});
+
+	it("several navigations in one tick resolve once, to the last one", async () => {
+		const views: string[] = [];
+		const page = (name: string) => ({ view: () => (views.push(name), m("text", null, name)) });
+		const route = mountRoute("/a", { "/a": page("a"), "/b": page("b"), "/c": page("c") });
+		views.length = 0;
+
+		route.set("/b");
+		route.set("/c");
+		expect(route.get()).toBe("/a"); // not resolved yet, like upstream
+		await settle();
+		expect(route.get()).toBe("/c");
+		expect(views).toEqual(["c"]);
+	});
+
+	it("a changed :key param remounts the page (fresh state)", async () => {
+		const inits: string[] = [];
+		const Page = { oninit: (v: any) => inits.push(v.attrs.key), view: () => m("text", null, "p") };
+		const route = mountRoute("/p/a", { "/p/:key": Page });
+
+		route.set("/p/:key", { key: "b" });
+		await settle();
+		expect(inits).toEqual(["a", "b"]);
+	});
+
+	it("options.state is merged into params and restored by back()/forward()", async () => {
+		const route = mountRoute("/", { "/": { view: () => m("text", null, "h") }, "/d": { view: () => m("text", null, "d") } });
+
+		route.set("/d", null, { state: { from: "home" } } as any);
+		await settle();
+		expect(route.param("from")).toBe("home");
+
+		route.back();
+		await settle();
+		expect(route.param("from")).toBeUndefined();
+
+		route.forward();
+		await settle();
+		expect(route.param("from")).toBe("home");
+	});
+
+	it("route.get() returns the decoded path, params stay decoded", async () => {
+		const route = mountRoute("/", { "/": { view: () => m("text", null, "h") }, "/d/:id": { view: () => m("text", null, "d") } });
+		route.set("/d/:id", { id: "a b/c" });
+		await settle();
+		expect(route.get()).toBe("/d/a b/c");
+		expect(route.param("id")).toBe("a b/c");
+	});
+
+	it("route.Link runs its lifecycle hooks once (not copied onto the rendered element)", () => {
+		let oncreates = 0;
+		setupRealTree();
+		lynxTestingEnv.switchToBackgroundThread();
+		const route = createRoute();
+		route("/", { "/": { view: () => m((route as any).Link, { href: "/", oncreate: () => oncreates++, key: "l" }, m("text", null, "l")) } });
+		expect(oncreates).toBe(1);
+	});
+
+	it("route.Link: preventDefault() cancels navigation, and an EventListener object works as ontap", async () => {
+		const route = mountRoute("/a", { "/a": { view: () => m("text", null, "a") }, "/b": { view: () => m("text", null, "b") } });
+		const tap = (ontap: unknown) => {
+			const link = (route as any).Link.view({ attrs: { href: "/b", ontap }, children: [] });
+			const e: any = { currentTarget: null, defaultPrevented: false, preventDefault() { this.defaultPrevented = true; } };
+			link.attrs.ontap(e);
+		};
+
+		tap((e: any) => e.preventDefault());
+		await settle();
+		expect(route.get()).toBe("/a");
+
+		let handled = false;
+		tap({ handleEvent: () => { handled = true; } });
+		await settle();
+		expect(handled).toBe(true);
+		expect(route.get()).toBe("/b");
+	});
+
+	it("rejects param names not separated by '/', '.' or '-', and a missing default route", () => {
+		setupRealTree();
+		lynxTestingEnv.switchToBackgroundThread();
+		expect(() => createRoute()("/", { "/": { view: () => m("text", null, "x") }, "/:a:b": { view: () => m("text", null, "y") } })).toThrow(SyntaxError);
+		expect(() => createRoute()(null as any, { "/": { view: () => m("text", null, "x") } })).toThrow(/defaultRoute is required/);
+	});
+});
+
+// Opt-in Android back button bridge: the host sends a global event when back
+// is pressed (only while its OnBackPressedCallback is enabled), and learns
+// through onCanGoBackChange when there is history to go back to.
+describe("route.listenBackButton()", () => {
+	function withFakeEmitter() {
+		const listeners = new Map<string, Set<Function>>();
+		const emitter = {
+			addListener: (name: string, fn: Function) => (listeners.get(name) ?? listeners.set(name, new Set()).get(name)!).add(fn),
+			removeListener: (name: string, fn: Function) => listeners.get(name)?.delete(fn),
+			emit: (name: string) => listeners.get(name)?.forEach((fn) => fn()),
+			count: (name: string) => listeners.get(name)?.size ?? 0,
+		};
+		const original = (lynx as any).getJSModule;
+		(lynx as any).getJSModule = (name: string) => (name === "GlobalEventEmitter" ? emitter : original?.call(lynx, name));
+		return { emitter, restore: () => ((lynx as any).getJSModule = original) };
+	}
+
+	function mountTwoPages() {
+		setupRealTree();
+		lynxTestingEnv.switchToBackgroundThread();
+		const route = createRoute();
+		route("/", { "/": { view: () => m("text", null, "home") }, "/detail": { view: () => m("text", null, "detail") } });
+		return route;
+	}
+
+	it("the back event goes back, and onCanGoBackChange reports each change once", async () => {
+		const route = mountTwoPages();
+		const { emitter, restore } = withFakeEmitter();
+		const changes: boolean[] = [];
+		const stop = route.listenBackButton({ onCanGoBackChange: (can: boolean) => changes.push(can) });
+
+		route.set("/detail");
+		route.set("/detail", null, { replace: true }); // no change in canGoBack
+		await settle();
+		emitter.emit("mithrilLynx:back");
+		await settle();
+
+		expect(route.get()).toBe("/");
+		expect(changes).toEqual([false, true, false]);
+		stop();
+		restore();
+	});
+
+	it("stop() unsubscribes; a custom event name is honored", () => {
+		const route = mountTwoPages();
+		const { emitter, restore } = withFakeEmitter();
+		const stop = route.listenBackButton({ eventName: "hostBack" });
+		expect(emitter.count("hostBack")).toBe(1);
+		stop();
+		expect(emitter.count("hostBack")).toBe(0);
+		restore();
+	});
+
+	it("a throwing onCanGoBackChange (e.g. a missing native module) never breaks navigation", async () => {
+		const route = mountTwoPages();
+		const { restore } = withFakeEmitter();
+		const error = console.error;
+		console.error = () => {};
+		route.listenBackButton({ onCanGoBackChange: () => { throw new Error("no module"); } });
+		route.set("/detail");
+		await settle();
+		console.error = error;
+		expect(route.get()).toBe("/detail");
+		restore();
+	});
+
+	it("without GlobalEventEmitter it only warns and does nothing", () => {
+		const route = mountTwoPages();
+		const original = (lynx as any).getJSModule;
+		(lynx as any).getJSModule = () => undefined;
+		const warn = console.warn;
+		const warnings: string[] = [];
+		console.warn = (msg: string) => warnings.push(msg);
+		const stop = route.listenBackButton();
+		console.warn = warn;
+		(lynx as any).getJSModule = original;
+		expect(warnings.some((w) => w.includes("GlobalEventEmitter"))).toBe(true);
+		expect(() => stop()).not.toThrow();
+	});
+});

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

package/test/style-clear.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, it } from "@rstest/core";
+import m from "mithril-runtime";
+import { createPatchApplier } from "../src/apply-patch.js";
+import { renderApp } from "../src/background.js";
+import { unregister } from "../src/mount-redraw.js";
+import { forEachOp, Op } from "../src/patch-protocol.js";
+
+// Mithril clears a whole style with `element.style = ""` (a style prop that
+// disappears, or unconditionally before a first object style). There is no
+// device-validated bulk-clear PAPI, so fake-dom.js must expand the clear into
+// one RemoveStyleProperty per property actually applied — and emit nothing
+// when there is nothing to clear.
+
+function mount(styleOf: () => Record<string, string> | undefined) {
+	lynxTestingEnv.switchToMainThread();
+	const pageId = __GetElementUniqueID(__CreatePage());
+	const applier = createPatchApplier(pageId);
+	applier.registerPageRoot(__CreateView(pageId));
+
+	lynxTestingEnv.switchToBackgroundThread();
+	unregister();
+	const patches: unknown[][] = [];
+	const app = renderApp({
+		root: () => {
+			const style = styleOf();
+			return m("view", style ? { style } : {});
+		},
+		sendPatch: (ops) => patches.push(ops),
+		subscribeEvents: () => {},
+	});
+
+	/** Applies every patch produced since the last call on the main thread
+	 * (which must not throw) and returns the style ops they carried. */
+	let applied = 0;
+	const flushToMainThread = () => {
+		const fresh = patches.slice(applied);
+		applied = patches.length;
+		lynxTestingEnv.switchToMainThread();
+		for (const ops of fresh) applier.applyPatch(ops);
+		lynxTestingEnv.switchToBackgroundThread();
+		const removed: string[] = [];
+		const set: string[] = [];
+		for (const ops of fresh) {
+			forEachOp(ops, (opcode, args) => {
+				if (opcode === Op.RemoveStyleProperty) removed.push(args[1] as string);
+				if (opcode === Op.SetStyleProperty) set.push(args[1] as string);
+			});
+		}
+		return { removed, set };
+	};
+	return { app, flushToMainThread };
+}
+
+describe("clearing a whole style expands into per-property removals", () => {
+	it("removing the style prop of a styled element no longer throws", () => {
+		let style: Record<string, string> | undefined = { color: "red" };
+		const { app, flushToMainThread } = mount(() => style);
+		flushToMainThread();
+
+		style = undefined;
+		app.redraw();
+		expect(flushToMainThread().removed).toEqual(["color"]);
+	});
+
+	it("clearing {color, width} removes both properties", () => {
+		let style: Record<string, string> | undefined = { color: "red", width: "10px" };
+		const { app, flushToMainThread } = mount(() => style);
+		flushToMainThread();
+
+		style = undefined;
+		app.redraw();
+		expect(flushToMainThread().removed.sort()).toEqual(["color", "width"]);
+	});
+
+	it("clearing a style whose properties were already removed one by one emits nothing", () => {
+		let style: Record<string, string> | undefined = { color: "red", width: "10px" };
+		const { app, flushToMainThread } = mount(() => style);
+		flushToMainThread();
+
+		// Object -> object: Mithril removes the missing keys individually.
+		style = {};
+		app.redraw();
+		expect(flushToMainThread().removed.sort()).toEqual(["color", "width"]);
+
+		// Now the whole style goes away: `style = ""` with nothing left to clear.
+		style = undefined;
+		app.redraw();
+		expect(flushToMainThread().removed).toEqual([]);
+	});
+
+	it("an element that never had a style gets no clear op on its first styled render", () => {
+		const { flushToMainThread } = mount(() => ({ color: "red" }));
+		const { removed, set } = flushToMainThread();
+		expect(removed).toEqual([]);
+		expect(set).toEqual(["color"]);
+	});
+});