mithril-lynx 2.6.0 → 3.0.0

package/src/route.js

@@ -1,62 +1,97 @@
 // src/route.js
 //
 // In-memory `m.route`, replacing `window.history`/`popstate` with a plain
-// array — the exact same pattern React Router's `MemoryRouter` and Vue
-// Router's `createMemoryHistory()` use for Lynx (see
-// .omo/plans/m-route-en-memoria.md §1–§3): both official framework
-// integrations converge on "history lives in a JS array, not the browser",
-// for the same reason we're doing it here — Lynx has no
-// `window.location`/History API at all.
+// array — the same pattern ReactLynx's documented routers use (React
+// Router's `MemoryRouter`, TanStack Router's `createMemoryHistory()`):
+// Lynx has no `window.location`/History API, so history lives in a JS array.
 //
-// Structured to mirror real Mithril's `api/router.js` as closely as
-// possible (same variable names/flow for `resolveRoute`/`route.set`'s
-// `hasBeenResolved` gate) so porting route-using app code only requires
-// swapping the import, not relearning the control flow. The one
-// unavoidable signature change: `m.route(root, defaultRoute, routes)`
-// loses `root` — there is no DOM node to point it at in this architecture
-// (a single `renderApp()` for the app's whole lifetime, plan §3.1) — see
-// the plan §5.2 for why that's a deliberate, documented deviation rather
-// than a fake DOM node just to keep the arg count.
+// Structured to mirror real Mithril's `api/router.js` (2.3.8) as closely as
+// possible — same resolution flow (`resolveRoute`/`loop`/`lastUpdate`),
+// resolution deferred after `route.set()` like upstream's `fireAsync`, the
+// matched component wrapped in a keyed fragment, `options.state` merged into
+// params, and `route.Link` censoring lifecycle hooks — so porting route-using
+// app code only requires swapping the import. See ROUTE_CONTRACT_ANALYSIS.md
+// for the full parity table. Deliberate differences: no `root` argument (one
+// `renderApp()` for the app's whole lifetime), a required `defaultRoute`
+// (there is no URL to start from), `back()`/`forward()`/`canGoBack()`, and
+// the opt-in Android back button bridge `listenBackButton()`.
 
 import m from "mithril-runtime";
 import buildPathname from "mithril-runtime/pathname/build.js";
 import parsePathname from "mithril-runtime/pathname/parse.js";
 import compileTemplate from "mithril-runtime/pathname/compileTemplate.js";
+import censor from "mithril-runtime/util/censor.js";
+import decodeURIComponentSafe from "mithril-runtime/util/decodeURIComponentSafe.js";
 import { renderApp } from "./background.js";
 
+/** Default global event name for {@link createRoute}'s `listenBackButton`. */
+export const BACK_EVENT_NAME = "mithrilLynx:back";
+
+/**
+ * Creates an in-memory router with the `m.route` API.
+ * @returns {Function & {SKIP: Object, set: Function, get: Function, param: Function, prefix: string, back: Function, forward: Function, canGoBack: Function, listenBackButton: Function, Link: Object}} The `route` function.
+ */
 export function createRoute() {
 	var compiled, fallbackRoute;
 	var component, attrs, currentPath, currentResolver;
 	var lastUpdate = null;
 	var ready = false;
 	var hasBeenResolved = false;
+	var scheduled = false;
 	var app = null;
 
-	// The in-memory equivalent of the browser's session history: a plain
-	// stack of resolved paths. `route.set(path, data, {replace: true})`
-	// overwrites the top entry instead of pushing — same semantics as
-	// `history.replaceState` vs `history.pushState`, just without a
-	// browser underneath it.
+	// The in-memory equivalent of the browser's session history: one
+	// `{ path, state }` entry per navigation. `route.set(path, data,
+	// {replace: true})` overwrites the current entry instead of pushing —
+	// same semantics as `history.replaceState` vs `history.pushState`.
 	var history = [];
 	var historyIndex = -1;
 
+	// listenBackButton() subscribers, told whenever canGoBack() changes.
+	var backWatchers = new Set();
+
 	var RouterRoot = {
+		/**
+		 * Renders the current route's component, through its resolver's
+		 * `render` when present. Like upstream, the component is wrapped in a
+		 * fragment so its `key` (a `:key` route param) is honored: a new key
+		 * remounts the page.
+		 * @returns {*} The vnode(s) to render.
+		 */
 		view() {
-			var vnode = component != null ? m(component, attrs) : null;
-			return currentResolver ? currentResolver.render(vnode) : vnode;
+			var vnode = m(component, attrs);
+			if (currentResolver) return currentResolver.render(vnode);
+			return [vnode];
 		},
 	};
 
-	function resolveRoute(path, data) {
+	/**
+	 * Finds the route matching `path` and renders it, starting the app on the first resolution.
+	 * @param {string} path - The path to resolve (as stored in history: encoded).
+	 * @param {Object|null} state - The entry's state, merged into the parsed params.
+	 * @returns {void}
+	 * @throws {Error} If the default route cannot be resolved.
+	 */
+	function resolveRoute(path, state) {
 		var parsed = parsePathname(path);
-		if (data) Object.assign(parsed.params, data);
+		if (state) Object.assign(parsed.params, state);
 
+		/**
+		 * Logs a failed `onmatch` and navigates to the default route.
+		 * @param {*} e - The error to log.
+		 * @returns {void}
+		 */
 		function reject(e) {
 			if (typeof console !== "undefined") console.error(e);
 			route.set(fallbackRoute, null, { replace: true });
 		}
 
 		loop(0);
+		/**
+		 * Tries each compiled route from `i` onward.
+		 * @param {number} i - The index to start from.
+		 * @returns {void}
+		 */
 		function loop(i) {
 			for (; i < compiled.length; i++) {
 				if (compiled[i].check(parsed)) {
@@ -68,7 +103,7 @@ export function createRoute() {
 							? comp
 							: "view";
 						attrs = parsed.params;
-						currentPath = path;
+						currentPath = decodeURIComponentSafe(path);
 						lastUpdate = null;
 						currentResolver = payload.render ? payload : null;
 						if (hasBeenResolved) {
@@ -97,18 +132,66 @@ export function createRoute() {
 		}
 	}
 
+	/**
+	 * Resolves the current history entry on the next microtask, once — like
+	 * upstream's `fireAsync`. Several navigations in one tick resolve only
+	 * the last one, and a navigation started during a render (a redirect in
+	 * a page's `oninit`) runs after that render instead of re-entering it.
+	 * @returns {void}
+	 */
+	function scheduleResolve() {
+		if (scheduled) return;
+		scheduled = true;
+		Promise.resolve().then(() => {
+			scheduled = false;
+			var entry = history[historyIndex];
+			resolveRoute(entry.path, entry.state);
+		});
+	}
+
+	/**
+	 * Tells every listenBackButton() subscriber the current canGoBack()
+	 * value, if it changed for them. A throwing callback (e.g. a missing
+	 * native module) is logged and never breaks navigation.
+	 * @returns {void}
+	 */
+	function notifyBackWatchers() {
+		var can = route.canGoBack();
+		for (var watcher of backWatchers) {
+			if (watcher.last === can) continue;
+			watcher.last = can;
+			try {
+				watcher.onChange(can);
+			} catch (e) {
+				if (typeof console !== "undefined") console.error("[mithril-lynx] route: onCanGoBackChange threw:", e);
+			}
+		}
+	}
+
 	/**
 	 * @param {string} defaultRoute - Both the fallback for an unmatched path
 	 *   AND the screen the app starts on — there is no browser URL to read
 	 *   an initial path from, so this is the one path the app always starts at
 	 *   (the closest in-memory equivalent of React Router's
-	 *   `initialEntries={["/"]}`).
+	 *   `initialEntries={["/"]}`). Required, unlike upstream.
 	 * @param {Record<string, unknown>} routes - Same shape as real
 	 *   `m.route`: `{ "/path/:param": Component | { onmatch, render } }`.
+	 * @returns {void}
+	 * @throws {TypeError} If `defaultRoute` is missing.
+	 * @throws {SyntaxError} If a route does not start with `/`, or has two params not separated by `/`, `.` or `-`.
+	 * @throws {ReferenceError} If the default route matches no known route.
 	 */
 	function route(defaultRoute, routes) {
+		if (typeof defaultRoute !== "string") {
+			throw new TypeError(
+				"[mithril-lynx] route(defaultRoute, routes): defaultRoute is required — Lynx has no URL to start from.",
+			);
+		}
 		compiled = Object.keys(routes).map((r) => {
 			if (r[0] !== "/") throw new SyntaxError("Routes must start with a '/'.");
+			if (/:([^\/\.-]+)(\.{3})?:/.test(r)) {
+				throw new SyntaxError("Route parameter names must be separated with either '/', '.', or '-'.");
+			}
 			return { route: r, payload: routes[r], check: compileTemplate(r) };
 		});
 		fallbackRoute = defaultRoute;
@@ -116,33 +199,71 @@ 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 = [{ path: defaultRoute, state: null }];
+			historyIndex = 0;
+			ready = true;
+			resolveRoute(defaultRoute, null);
+			notifyBackWatchers();
+		} else {
+			// Re-registration (e.g. HMR of the route module): keep the history
+			// stack and re-resolve the CURRENT entry 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.
+			var entry = history[historyIndex];
+			resolveRoute(entry.path, entry.state);
+		}
 	}
 
 	route.SKIP = {};
 
+	/**
+	 * Navigates to a path, pushing (or, with `replace`, overwriting) a
+	 * history entry. The history changes right away; the new screen is
+	 * resolved on the next microtask, like upstream — so `route.get()` still
+	 * returns the previous path until then.
+	 * @param {string} path - The path or template to navigate to.
+	 * @param {Object|null} [data] - Params to fill the path template with (extra keys become the query string).
+	 * @param {{replace?: boolean, state?: Object, title?: string}} [options] - Navigation options. `state` is merged into the route's params and restored by back()/forward(); `title` is accepted and ignored.
+	 * @returns {void}
+	 * @throws {Error} If called before `route(defaultRoute, routes)`.
+	 */
 	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;
 		}
 		lastUpdate = null;
-		path = buildPathname(path, data);
+		var entry = { path: buildPathname(path, data), state: (options && options.state) || null };
 		if (options && options.replace) {
-			history[Math.max(historyIndex, 0)] = path;
+			history[Math.max(historyIndex, 0)] = entry;
 		} else {
 			history = history.slice(0, historyIndex + 1);
-			history.push(path);
+			history.push(entry);
 			historyIndex = history.length - 1;
 		}
-		if (ready) resolveRoute(path, null);
+		scheduleResolve();
+		notifyBackWatchers();
 	};
 
+	/**
+	 * @returns {string|undefined} The current (decoded) path, or `undefined` before the first resolution.
+	 */
 	route.get = () => currentPath;
 
+	/**
+	 * @param {string} [key] - A param name.
+	 * @returns {*} That param's value, or all params when `key` is omitted.
+	 */
 	route.param = (key) => (attrs && key != null ? attrs[key] : attrs);
 
 	// No URL bar in Lynx — kept as an assignable no-op so app code ported
@@ -151,52 +272,108 @@ export function createRoute() {
 	route.prefix = "";
 
 	/**
-	 * `back()`/`forward()` walk the SAME in-memory stack `route.set` writes
-	 * to — this is the "no native back button" answer from plan §5.7/F0:
-	 * static analysis of the installed Lynx runtime found no hardware/
-	 * gesture "back" event exposed to JS (only `onAppEnterBackground`,
-	 * which is app-lifecycle, not navigation) — so an app's own explicit
-	 * back affordance (a `route.Link`/button calling this) is the only
-	 * way back navigation happens. Confirming this holds on a real device
-	 * is F4/F5 of the plan, not done yet.
+	 * Moves one entry back in the in-memory history. Not part of `m.route`:
+	 * there is no browser back button — wire an in-app back affordance to
+	 * this, and the Android back button through listenBackButton().
+	 * @returns {boolean} `true` when the history moved back, `false` when already at the start.
 	 */
 	route.back = function () {
-		if (historyIndex <= 0) return;
+		if (historyIndex <= 0) return false;
 		historyIndex--;
-		resolveRoute(history[historyIndex], null);
+		scheduleResolve();
+		notifyBackWatchers();
+		return true;
 	};
+	/**
+	 * Moves one entry forward in the in-memory history.
+	 * @returns {boolean} `true` when the history moved forward, `false` when already at the end.
+	 */
 	route.forward = function () {
-		if (historyIndex >= history.length - 1) return;
+		if (historyIndex >= history.length - 1) return false;
 		historyIndex++;
-		resolveRoute(history[historyIndex], null);
+		scheduleResolve();
+		notifyBackWatchers();
+		return true;
+	};
+
+	/**
+	 * @returns {boolean} Whether back() would navigate (there is an earlier entry).
+	 */
+	route.canGoBack = () => historyIndex > 0;
+
+	/**
+	 * Opt-in bridge for the Android back button. The host sends a global
+	 * event (`LynxView.sendGlobalEvent(eventName, ...)`) when back is pressed
+	 * and its OnBackPressedCallback is enabled; this calls `route.back()`.
+	 * `onCanGoBackChange` is called with the current canGoBack() right away
+	 * and whenever it changes, so the host can enable its callback only while
+	 * there is history — with none, Android's default (closing the app)
+	 * applies. Nothing here blocks: without a host that sends the event, or
+	 * without GlobalEventEmitter, it does nothing. See ROUTE.md for the
+	 * Android host side.
+	 * @param {{eventName?: string, onCanGoBackChange?: (canGoBack: boolean) => void}} [options] - The global event name (default `"mithrilLynx:back"`) and the host notification callback.
+	 * @returns {() => void} Stops listening.
+	 */
+	route.listenBackButton = function (options) {
+		var eventName = (options && options.eventName) || BACK_EVENT_NAME;
+		var onChange = options && options.onCanGoBackChange;
+		var emitter = null;
+		try {
+			emitter = typeof lynx !== "undefined" && typeof lynx.getJSModule === "function" ? lynx.getJSModule("GlobalEventEmitter") : null;
+		} catch (e) {
+			emitter = null;
+		}
+		if (emitter == null || typeof emitter.addListener !== "function") {
+			if (typeof console !== "undefined") {
+				console.warn("[mithril-lynx] route.listenBackButton(): GlobalEventEmitter is not available — back button events will not be received.");
+			}
+		}
+		var onBack = () => {
+			route.back();
+		};
+		if (emitter != null && typeof emitter.addListener === "function") emitter.addListener(eventName, onBack);
+		var watcher = null;
+		if (typeof onChange === "function") {
+			watcher = { onChange, last: undefined };
+			backWatchers.add(watcher);
+			if (ready) notifyBackWatchers();
+		}
+		return function stop() {
+			if (emitter != null && typeof emitter.removeListener === "function") emitter.removeListener(eventName, onBack);
+			if (watcher != null) backWatchers.delete(watcher);
+		};
 	};
 
 	// Lynx has no `<a>`/`onclick` — this renders a tap-driven element
-	// instead, the same shape ReactLynx's `useNavigate()+ontap` and Vue
-	// Lynx's custom `RouterLink` slot use (plan §1–§2, §5.4).
+	// instead, the same shape ReactLynx's `useNavigate()+bindtap` pattern uses.
 	route.Link = {
+		/**
+		 * Renders a tap-driven element that navigates to `href`. Like
+		 * upstream, `key` and lifecycle hooks stay on the Link component and
+		 * are not copied onto the rendered element (they would run twice).
+		 * @param {{attrs: {href: string, params?: Object, options?: Object, selector?: string, disabled?: boolean, ontap?: Function|{handleEvent: Function}}, children: *}} vnode - The Mithril vnode.
+		 * @returns {*} The rendered vnode.
+		 */
 		view(vnode) {
 			var a = vnode.attrs;
-			var selector = a.selector || "view";
-			var rest = {};
-			for (var key in a) {
-				if (key !== "selector" && key !== "options" && key !== "params" && key !== "href" && key !== "ontap") {
-					rest[key] = a[key];
-				}
-			}
+			var rest = censor(a, ["selector", "options", "params", "href", "ontap"]);
 			var disabled = Boolean(a.disabled);
 			rest.disabled = disabled;
 			if (!disabled) {
+				var ontap = a.ontap;
+				var href = buildPathname(a.href, a.params);
+				var options = a.options;
 				rest.ontap = function (e) {
 					var result;
-					if (typeof a.ontap === "function") result = a.ontap.call(e.currentTarget, e);
-					if (result !== false) {
+					if (typeof ontap === "function") result = ontap.call(e.currentTarget, e);
+					else if (ontap != null && typeof ontap === "object" && typeof ontap.handleEvent === "function") ontap.handleEvent(e);
+					if (result !== false && !e.defaultPrevented) {
 						e.redraw = false;
-						route.set(buildPathname(a.href, a.params), null, a.options);
+						route.set(href, null, options);
 					}
 				};
 			}
-			return m(selector, rest, vnode.children);
+			return m(a.selector || "view", rest, vnode.children);
 		},
 	};
 

package/src/testing.d.ts

@@ -4,13 +4,26 @@ export interface PatchApplier {
 	/** The real PAPI element handle for a given background-side id, or
 	 * `undefined` if nothing was ever created for it. */
 	getHandle(id: unknown): unknown;
+	/** Neutralizes every native list's callbacks (for `__DestroyLifetime`). */
+	dispose(): void;
 }
 
 /** 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;
+export function createPatchApplier(
+	pageId: unknown,
+	options?: { onEvent?: (id: unknown, type: string, payload: unknown, seq?: number) => void; flush?: boolean },
+): 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;
+
+/** Every `__InvokeUIMethod` call made through the testing stand-in, in order. */
+export const uiMethodCalls: { element: unknown; method: string; params: Record<string, unknown> }[];
+
+/** Sets how the `__InvokeUIMethod` stand-in answers (`null`: `{ code: 0 }` to every call). */
+export function setUIMethodResponder(
+	responder: ((element: unknown, method: string, params: Record<string, unknown>) => { code: number; data?: unknown }) | null,
+): void;

package/src/testing.js

@@ -21,28 +21,96 @@
 
 export { createPatchApplier } from "./apply-patch.js";
 
+/** Every `__InvokeUIMethod` call made through the stand-in below, in order
+ * (`{ element, method, params }`) — module-level, so it survives the testing
+ * environment re-injecting the main-thread globals. Clear it with
+ * `uiMethodCalls.length = 0`. */
+export const uiMethodCalls = [];
+
+let uiMethodResponder = null;
+
+/**
+ * Sets how the `__InvokeUIMethod` stand-in answers: `responder(element,
+ * method, params)` returns the `{ code, data }` passed to the callback.
+ * `null` (the default) answers `{ code: 0, data: undefined }` to every call.
+ * @param {((element: unknown, method: string, params: Object) => {code: number, data?: unknown})|null} responder - The responder.
+ * @returns {void}
+ */
+export function setUIMethodResponder(responder) {
+	uiMethodResponder = responder;
+}
+
 /**
  * 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 elements (Op.SetGestureDetector, `list`/`list-item`) are covered by the testing
+ * environment itself, not by this polyfill — see test/gesture.test.ts and
+ * test/list.test.ts.
+ * @param {{lynx: Object}} target - The main-thread globals object from `@lynx-js/testing-environment`.
+ * @returns {void}
  */
 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.
+	/**
+	 * Stand-in for the native `__AddEventListener` PAPI.
+	 * @param {Object} node - The element.
+	 * @param {string} name - The event type.
+	 * @param {Function} handler - The listener.
+	 * @param {Object} _options - Accepted and ignored.
+	 * @returns {void}
+	 */
+	target.__AddEventListener = (node, name, handler, _options) => {
 		node.__vanillaListeners ??= {};
 		(node.__vanillaListeners[name] ??= new Set()).add(handler);
 	};
 
-	target.__RemoveEventListener = (node, name, handler) => {
+	/**
+	 * Stand-in for the native `__RemoveEventListener` PAPI.
+	 * @param {Object} node - The element.
+	 * @param {string} name - The event type.
+	 * @param {Function} handler - The listener to remove.
+	 * @param {Object} _options - Required (four arguments), mirroring native.
+	 * @returns {void}
+	 * @throws {Error} If called with fewer than four arguments.
+	 */
+	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);
 	};
+
+	// Stand-in for the native `__InvokeUIMethod` PAPI (element, method,
+	// params, callback), which the testing environment lacks: records the
+	// call and answers synchronously (native answers later; nothing in
+	// mithril-lynx depends on either timing).
+	/**
+	 * Stand-in for the native `__InvokeUIMethod` PAPI.
+	 * @param {Object} element - The element.
+	 * @param {string} method - The UI method name.
+	 * @param {Object} params - Its parameters.
+	 * @param {(res: {code: number, data?: unknown}) => void} callback - Receives the result.
+	 * @returns {void}
+	 */
+	target.__InvokeUIMethod = (element, method, params, callback) => {
+		uiMethodCalls.push({ element, method, params });
+		callback(uiMethodResponder ? uiMethodResponder(element, method, params) : { code: 0, data: undefined });
+	};
 }

package/test/event-render-coalescing.test.ts

@@ -0,0 +1,117 @@
+import { afterEach, beforeEach, describe, expect, it, rstest } from "@rstest/core";
+import m from "mithril-runtime";
+import { renderApp } from "../src/background.js";
+import { unregister } from "../src/mount-redraw.js";
+
+// High-frequency events (gesturemove, touchmove, scroll) must reach the app's
+// handler once per sample, but must NOT trigger one full render + patch per
+// sample — the redraw they ask for is coalesced to at most one per frame.
+// Everything else still renders synchronously.
+
+type Router = (event: { data: { id: number; type: string; payload?: object } }) => void;
+
+function mountCounter() {
+	lynxTestingEnv.switchToBackgroundThread();
+	unregister();
+	const moves: number[] = [];
+	let count = 0;
+	let patches = 0;
+	let router: Router | null = null;
+	const app = renderApp({
+		root: () =>
+			m(
+				"view",
+				{
+					ongesturemove: (e: any) => {
+						moves.push(e.clientX);
+						count++;
+						if (e.skipRedraw) e.redraw = false;
+					},
+					ongestureup: () => {
+						count++;
+					},
+					ontap: () => {
+						count++;
+					},
+				},
+				m("text", String(count)),
+			),
+		sendPatch: () => {
+			patches++;
+		},
+		subscribeEvents: (handler: Router) => {
+			router = handler;
+		},
+	});
+	const id = (app.document.firstChild as any)._id as number;
+	const send = (type: string, payload?: object) => router!({ data: { id, type, payload } });
+	return { app, moves, send, patches: () => patches };
+}
+
+// Fake timers: the coalesced render uses a 16ms timer when
+// lynx.requestAnimationFrame is absent (as in the testing environment), so
+// advancing the clock makes "one frame later" deterministic.
+const nextFrame = () => rstest.advanceTimersByTime(16);
+
+describe("renders after high-frequency events are coalesced per frame", () => {
+	beforeEach(() => {
+		rstest.useFakeTimers();
+	});
+	afterEach(() => {
+		rstest.useRealTimers();
+	});
+
+	it("five gesturemoves in one tick: every handler runs, one render follows", () => {
+		const { moves, send, patches } = mountCounter();
+		const before = patches();
+
+		for (let x = 1; x <= 5; x++) send("gesturemove", { clientX: x });
+		expect(moves).toEqual([1, 2, 3, 4, 5]);
+		expect(patches()).toBe(before);
+
+		nextFrame();
+		expect(patches()).toBe(before + 1);
+	});
+
+	it("gestureup after moves renders immediately and cancels the pending frame render", () => {
+		const { send, patches } = mountCounter();
+		const before = patches();
+
+		send("gesturemove", { clientX: 1 });
+		send("gesturemove", { clientX: 2 });
+		send("gestureup");
+		expect(patches()).toBe(before + 1);
+
+		nextFrame();
+		expect(patches()).toBe(before + 1);
+	});
+
+	it("a tap still renders synchronously", () => {
+		const { send, patches } = mountCounter();
+		const before = patches();
+
+		send("tap");
+		expect(patches()).toBe(before + 1);
+	});
+
+	it("an explicit redraw() between moves and the frame makes the frame render a no-op", () => {
+		const { app, send, patches } = mountCounter();
+		const before = patches();
+
+		send("gesturemove", { clientX: 1 });
+		app.redraw();
+		expect(patches()).toBe(before + 1);
+
+		nextFrame();
+		expect(patches()).toBe(before + 1);
+	});
+
+	it("a move whose handler sets e.redraw = false schedules no render at all", () => {
+		const { send, patches } = mountCounter();
+		const before = patches();
+
+		send("gesturemove", { clientX: 1, skipRedraw: true });
+		nextFrame();
+		expect(patches()).toBe(before);
+	});
+});