mithril-lynx 0.0.8 → 2.0.0

package/src/mount-redraw.js

@@ -0,0 +1,67 @@
+// src/mount-redraw.js
+//
+// A minimal version of real Mithril's `api/mount-redraw.js`: a shared
+// singleton so `request.js` can trigger a redraw of whichever app is
+// currently mounted, without needing a direct reference to that specific
+// `renderApp()` call's handle. `background.js` registers its own
+// `performRender` here right after creating it; `route.js` could too, but
+// doesn't need to (it already redraws itself directly on every
+// navigation) — this module exists specifically so `request.js` isn't
+// coupled to "did this app mount via route() or a plain renderApp() call".
+//
+// Deliberately NOT a queue/pubsub of multiple mounted apps (real Mithril's
+// mount-redraw.js supports that because a browser page can `m.mount()`
+// several independent roots) — mithril-lynx-v2 has exactly one `renderApp()`
+// for the app's whole lifetime (plan §3.1), so "the current redraw
+// function" is a single slot, not a list.
+//
+// `redraw()` schedules instead of calling `currentRedraw()` inline — same
+// reason real Mithril's version schedules through the platform's
+// requestAnimationFrame instead of rendering synchronously: `request.js`'s
+// own `promise.then(onSuccess)` calls this BEFORE the caller's own
+// `.then()` runs (that callback is chained onto `request()`'s *returned*
+// promise, one microtask hop further back) — a synchronous redraw here
+// would render the screen one tick too early, before the caller has stored
+// the response in its own state.
+//
+// DEVICE-CONFIRMED LYNX QUIRK (see FETCH_INVESTIGATION.md): unlike a spec
+// browser, where a macrotask (rAF, setTimeout) is guaranteed to run only
+// after every currently-queued microtask (including ones enqueued by other
+// microtasks) has drained, on this Lynx background-thread runtime BOTH
+// `lynx.setTimeout(fn, 0)` and `lynx.requestAnimationFrame(fn)` fire before
+// even the FIRST pending microtask — confirmed with a Promise chain logging
+// three chained `.then()`s against a 0ms/1ms/4ms/16ms timer and against
+// `requestAnimationFrame`: the timer/rAF callback always logged first. A
+// 50ms delay was the first value that reliably let a single `.then()`
+// (the realistic caller shape: `request(url).then(cb)`) run first. There is
+// no known Lynx primitive that defers "until microtasks finish" the way a
+// spec-compliant macrotask does — this delay is an empirical safety margin,
+// not a scheduling guarantee.
+const REDRAW_DELAY_MS = 50;
+
+let currentRedraw = null;
+let pending = false;
+
+function schedule(fn) {
+	const timer = typeof lynx !== "undefined" && typeof lynx.setTimeout === "function" ? lynx.setTimeout.bind(lynx) : setTimeout;
+	timer(fn, REDRAW_DELAY_MS);
+}
+
+export function register(redraw) {
+	currentRedraw = redraw;
+}
+
+/** 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
+ * necessarily a bug the way calling commit() before mounting is. Multiple
+ * calls within the delay window collapse into a single scheduled render,
+ * same debounce real Mithril's `redraw()` does with its `pending` flag. */
+export function redraw() {
+	if (pending) return;
+	pending = true;
+	schedule(() => {
+		pending = false;
+		if (currentRedraw != null) currentRedraw();
+	});
+}

package/src/patch-protocol.js

@@ -0,0 +1,40 @@
+// src/patch-protocol.js
+//
+// The wire vocabulary between the background thread (real Mithril diff,
+// running against a virtual tree) and the main thread (applies the patch to
+// real Lynx elements). Adopted from ReactLynx's `SnapshotOperation` pattern
+// (see rspeedy-react-analysis/LYNX_PAPI_SPEC.md §4.3): a FLAT array of
+// numbers/strings/values, not an array of `{op, ...}` objects — cheaper to
+// serialize, and a pattern already proven in production at ReactLynx's scale.
+//
+// Every op is `[opcode, ...args]` concatenated into one flat array. `id`
+// below always refers to the integer handle a node was given by
+// `createVirtualBackend()` — the SAME id space is mirrored 1:1 on the
+// main-thread side by `applyPatch()` (see backends/papi-backend.js), so
+// nodes never need to be looked up by anything other than that integer.
+
+export const Op = Object.freeze({
+	CreateElement: 0,
+	CreateElementNS: 1,
+	CreateText: 2,
+	CreateFragment: 3,
+	InsertBefore: 4, // parentId, childId, refId(-1 = append)
+	RemoveChild: 5, // parentId, childId
+	SetAttribute: 6, // id, name, value
+	RemoveAttribute: 7, // id, name
+	SetAttributeNS: 8, // id, ns, name, value
+	SetStyleProperty: 9, // id, name, value (dash-case, via setProperty semantics)
+	RemoveStyleProperty: 10, // id, name
+	SetText: 11, // id, value (nodeValue on a text node)
+	AddEvent: 12, // id, type
+	RemoveEvent: 13, // id, type
+});
+
+/**
+ * Encodes one op onto a flat ops array. Kept as a tiny helper (not a class)
+ * so the hot path (called on every attribute/child mutation during a real
+ * Mithril diff) is just array pushes — no object allocation per op.
+ */
+export function pushOp(ops, opcode, ...args) {
+	ops.push(opcode, ...args);
+}

package/src/reload/version.js

@@ -0,0 +1,28 @@
+// src/reload/version.js
+//
+// Race guard for concurrent hot-updates (method A/B, reload/hot-accept.js).
+// v1 had this bug for real: two rebuilds landing close together made the
+// dev client see a `module.hot.check()` still in flight and degrade to a
+// full reload EVEN THOUGH each edit individually would have been light
+// (mithril-lynx/.omo/plans/arquitectura-dual-reload.md, F1 "race de
+// doble-build"). ReactLynx doesn't avoid the race with a status flag at
+// all — it lets both builds' patches land in whatever order they arrive,
+// and discards any patch whose `reloadVersion` is older than the current
+// one (rspeedy-react-analysis/LYNX_PAPI_SPEC.md §5.1). This is that same
+// counter, adopted directly rather than re-deriving a flag-based guard.
+
+let version = 0;
+
+export function getReloadVersion() {
+	return version;
+}
+
+export function increaseReloadVersion() {
+	return ++version;
+}
+
+/** True if a patch stamped with `patchVersion` is stale and must be
+ * dropped without being applied — the ENTIRE guard, one comparison. */
+export function isStaleVersion(patchVersion) {
+	return typeof patchVersion === "number" && patchVersion < version;
+}

package/src/request.d.ts

@@ -0,0 +1,37 @@
+export interface RequestOptions<T = any> {
+	method?: string;
+	url?: string;
+	params?: Record<string, unknown>;
+	body?: unknown;
+	headers?: Record<string, string>;
+	timeout?: number;
+	signal?: AbortSignal;
+	responseType?: "json" | "text";
+	serialize?: (data: unknown) => string;
+	deserialize?: (data: unknown) => unknown;
+	extract?: (response: unknown, options: RequestOptions<T>) => unknown;
+	type?: new (data: any) => T;
+	background?: boolean;
+	// Present on the real m.request signature but confirmed unsupported —
+	// listed here (rather than omitted) so passing one is a type error at
+	// the call site, not a surprise at runtime.
+	config?: never;
+	async?: never;
+	user?: never;
+	password?: never;
+	withCredentials?: never;
+}
+
+export interface RequestPromise<T> extends Promise<T> {
+	/** Not part of real m.request's API — free to add since Lynx's
+	 * AbortController makes it a real, working cancellation, unlike the
+	 * `config`-only escape hatch losing `config` takes away. */
+	abort(): void;
+}
+
+export type Request = <T = any>(url: string | RequestOptions<T>, options?: RequestOptions<T>) => RequestPromise<T>;
+
+export function createRequestor(fetchImpl?: (url: string, init: RequestInit) => Promise<Response>): Request;
+
+declare const request: Request;
+export default request;

package/src/request.js

@@ -0,0 +1,181 @@
+// src/request.js
+//
+// `m.request`-shaped wrapper over `lynx.fetch` — the subset confirmed
+// faithful in FETCH_INVESTIGATION.md / .omo/plans/m-request-fetch-lynx.md.
+// Every option below is either "works the same as real m.request" or
+// throws immediately with a clear message pointing at the doc — never a
+// silent behavior difference. See FETCH_INVESTIGATION.md §3 for the full
+// option-by-option table this file implements.
+//
+// Explicitly NOT supported, by design, confirmed unfixable on Lynx:
+// - `config(xhr)`: fetch has no live object to hand back.
+// - `body` as `FormData`: confirmed absent at runtime (typeof FormData
+//   === "undefined"). `URLSearchParams` bodies DO work — confirmed on
+//   device — and need no special-casing here beyond not JSON-stringifying
+//   them.
+// - `responseType: "blob"`/`"document"`: no `.blob()` on Lynx's `Body`;
+//   `"document"` has no meaning outside a browser DOM.
+// - `user`/`password` (inline Basic Auth), `withCredentials`,
+//   `async: false`: XMLHttpRequest/browser-only concepts with no `fetch`
+//   equivalent, confirmed (withCredentials: no CORS model on Lynx;
+//   user/password: no `btoa` to build the Authorization header even if
+//   we wanted to guess one).
+
+import buildPathname from "mithril-runtime/pathname/build.js";
+import { redraw as sharedRedraw } from "./mount-redraw.js";
+
+const UNSUPPORTED = [
+	["config", (o) => o.config != null],
+	["async: false", (o) => o.async === false],
+	["user", (o) => typeof o.user === "string"],
+	["password", (o) => typeof o.password === "string"],
+	["withCredentials", (o) => o.withCredentials === true],
+];
+
+function checkUnsupported(options) {
+	for (const [name, matches] of UNSUPPORTED) {
+		if (matches(options)) {
+			throw new Error(
+				`[mithril-lynx-v2/request] "${name}" is not supported — Lynx's fetch has no equivalent ` +
+					"(see FETCH_INVESTIGATION.md for exactly why). This throws instead of silently " +
+					"behaving differently from what you asked for.",
+			);
+		}
+	}
+}
+
+function hasHeader(headers, name) {
+	for (const key in headers) {
+		if (Object.prototype.hasOwnProperty.call(headers, key) && key.toLowerCase() === name) return true;
+	}
+	return false;
+}
+
+function applyType(data, Type) {
+	if (typeof Type !== "function") return data;
+	if (Array.isArray(data)) return data.map((item) => new Type(item));
+	return new Type(data);
+}
+
+/**
+ * @param {(url: string, init: object) => Promise<Response>} [fetchImpl] -
+ *   Defaults to `lynx.fetch`, looked up lazily (not at module load time,
+ *   so importing this file never requires `lynx` to already exist) —
+ *   same pattern route.js uses for `renderApp`. Tests inject a fake here
+ *   instead of hitting a real network.
+ */
+export function createRequestor(fetchImpl) {
+	const doFetch = fetchImpl || ((url, init) => lynx.fetch(url, init));
+
+	return function request(url, options) {
+		if (typeof url !== "string") {
+			options = url;
+			url = url.url;
+		} else if (options == null) {
+			options = {};
+		}
+		checkUnsupported(options);
+
+		if (typeof FormData !== "undefined" && options.body instanceof FormData) {
+			throw new Error(
+				"[mithril-lynx-v2/request] FormData bodies are not supported — Lynx has no FormData " +
+					"at runtime (confirmed absent, see FETCH_INVESTIGATION.md). Use lynx.fetch directly " +
+					"if you have another way to send this data, or restructure it as plain JSON.",
+			);
+		}
+
+		const method = options.method != null ? options.method.toUpperCase() : "GET";
+		const path = buildPathname(url, options.params);
+		const headers = Object.assign({}, options.headers);
+
+		let body;
+		if (options.body != null) {
+			if (typeof URLSearchParams !== "undefined" && options.body instanceof URLSearchParams) {
+				// Confirmed on device: fetch sets Content-Type automatically for
+				// this body type, exactly like a real browser.
+				body = options.body;
+			} else if (typeof options.serialize === "function") {
+				body = options.serialize(options.body);
+			} else {
+				body = JSON.stringify(options.body);
+				if (!hasHeader(headers, "content-type")) headers["Content-Type"] = "application/json; charset=utf-8";
+			}
+		}
+		if (typeof options.deserialize !== "function" && !hasHeader(headers, "accept")) {
+			headers["Accept"] = "application/json, text/*";
+		}
+
+		// Real cancellation/timeout — confirmed working on device (unlike
+		// what an earlier version of the investigation assumed): aborting
+		// actually tears down the in-flight connection, not just abandons
+		// the wait. `options.signal` (if given) is linked into our own
+		// controller so a caller-provided signal and our timeout can both
+		// trigger the same abort.
+		const ctrl = new AbortController();
+		if (options.signal) {
+			if (options.signal.aborted) ctrl.abort();
+			else options.signal.addEventListener("abort", () => ctrl.abort());
+		}
+		let timeoutId;
+		if (options.timeout) {
+			const schedule = typeof lynx !== "undefined" && typeof lynx.setTimeout === "function"
+				? lynx.setTimeout.bind(lynx)
+				: setTimeout;
+			timeoutId = schedule(() => ctrl.abort(), options.timeout);
+		}
+		function clearRequestTimeout() {
+			if (timeoutId == null) return;
+			const clear = typeof lynx !== "undefined" && typeof lynx.clearTimeout === "function"
+				? lynx.clearTimeout.bind(lynx)
+				: clearTimeout;
+			clear(timeoutId);
+		}
+
+		const responseType = options.responseType || (typeof options.extract === "function" ? "" : "json");
+
+		const promise = doFetch(path, { method, headers, body, signal: ctrl.signal }).then((response) => {
+			clearRequestTimeout();
+
+			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);
+			}
+
+			const ok = response.ok || response.status === 304;
+			const bodyPromise = responseType === "text" ? response.text() : response.json();
+			return bodyPromise.then((data) => {
+				if (typeof options.deserialize === "function") data = options.deserialize(data);
+				if (!ok) {
+					const error = new Error(typeof data === "string" ? data : response.statusText);
+					error.code = response.status;
+					error.response = data;
+					throw error;
+				}
+				return applyType(data, options.type);
+			});
+		});
+
+		const result = promise.then(
+			(value) => {
+				if (options.background !== true) sharedRedraw();
+				return value;
+			},
+			(error) => {
+				clearRequestTimeout();
+				if (options.background !== true) sharedRedraw();
+				throw error;
+			},
+		);
+
+		// Not part of real m.request's API (there, you can only reach
+		// xhr.abort() through `config`) — free to add since we already have
+		// the controller, and it's exactly the escape hatch losing `config`
+		// takes away. Documented in FETCH_INVESTIGATION.md, not hidden.
+		result.abort = () => ctrl.abort();
+		return result;
+	};
+}
+
+const request = createRequestor();
+export default request;

package/src/route.d.ts

@@ -0,0 +1,33 @@
+import type { Component } from "mithril";
+
+export interface RouteResolver {
+	onmatch?(args: Record<string, string>, requestedPath: string, route: string): unknown;
+	render?(vnode: unknown): unknown;
+}
+
+export interface RouteLinkAttrs {
+	href: string;
+	selector?: string;
+	params?: Record<string, unknown>;
+	options?: { replace?: boolean };
+	disabled?: boolean;
+	ontap?: (e: unknown) => unknown;
+	[key: string]: unknown;
+}
+
+export interface Route {
+	(defaultRoute: string, routes: Record<string, unknown | RouteResolver>): void;
+	set(path: string, data?: unknown, options?: { replace?: boolean }): void;
+	get(): string | undefined;
+	param(key?: string): unknown;
+	back(): void;
+	forward(): void;
+	prefix: string;
+	SKIP: unknown;
+	Link: Component<RouteLinkAttrs>;
+}
+
+export function createRoute(): Route;
+
+declare const route: Route;
+export default route;

package/src/route.js

@@ -0,0 +1,207 @@
+// 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.
+//
+// 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 v2's 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.
+
+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 { renderApp } from "./background.js";
+
+export function createRoute() {
+	var compiled, fallbackRoute;
+	var component, attrs, currentPath, currentResolver;
+	var lastUpdate = null;
+	var ready = false;
+	var hasBeenResolved = 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.
+	var history = [];
+	var historyIndex = -1;
+
+	var RouterRoot = {
+		view() {
+			var vnode = component != null ? m(component, attrs) : null;
+			return currentResolver ? currentResolver.render(vnode) : vnode;
+		},
+	};
+
+	function resolveRoute(path, data) {
+		var parsed = parsePathname(path);
+		if (data) Object.assign(parsed.params, data);
+
+		function reject(e) {
+			if (typeof console !== "undefined") console.error(e);
+			route.set(fallbackRoute, null, { replace: true });
+		}
+
+		loop(0);
+		function loop(i) {
+			for (; i < compiled.length; i++) {
+				if (compiled[i].check(parsed)) {
+					var payload = compiled[i].payload;
+					var update = (lastUpdate = function (comp) {
+						if (update !== lastUpdate) return;
+						if (comp === route.SKIP) return loop(i + 1);
+						component = comp != null && (typeof comp.view === "function" || typeof comp === "function")
+							? comp
+							: "view";
+						attrs = parsed.params;
+						currentPath = path;
+						lastUpdate = null;
+						currentResolver = payload.render ? payload : null;
+						if (hasBeenResolved) {
+							app.redraw();
+						} else {
+							hasBeenResolved = true;
+							app = renderApp({ root: () => m(RouterRoot) });
+						}
+					});
+					if (payload.view || typeof payload === "function") {
+						update(payload);
+					} else if (payload.onmatch) {
+						Promise.resolve()
+							.then(() => payload.onmatch(parsed.params, path, compiled[i].route))
+							.then(update, path === fallbackRoute ? undefined : reject);
+					} else {
+						update("view");
+					}
+					return;
+				}
+			}
+			if (path === fallbackRoute) {
+				throw new Error("Could not resolve default route " + fallbackRoute + ".");
+			}
+			route.set(fallbackRoute, null, { replace: true });
+		}
+	}
+
+	/**
+	 * @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 v2 always starts at
+	 *   (the closest in-memory equivalent of React Router's
+	 *   `initialEntries={["/"]}`).
+	 * @param {Record<string, unknown>} routes - Same shape as real
+	 *   `m.route`: `{ "/path/:param": Component | { onmatch, render } }`.
+	 */
+	function route(defaultRoute, routes) {
+		compiled = Object.keys(routes).map((r) => {
+			if (r[0] !== "/") throw new SyntaxError("Routes must start with a '/'.");
+			return { route: r, payload: routes[r], check: compileTemplate(r) };
+		});
+		fallbackRoute = defaultRoute;
+		var defaultData = parsePathname(defaultRoute);
+		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);
+	}
+
+	route.SKIP = {};
+
+	route.set = function (path, data, options) {
+		if (lastUpdate != null) {
+			options = options || {};
+			options.replace = true;
+		}
+		lastUpdate = null;
+		path = buildPathname(path, data);
+		if (options && options.replace) {
+			history[Math.max(historyIndex, 0)] = path;
+		} else {
+			history = history.slice(0, historyIndex + 1);
+			history.push(path);
+			historyIndex = history.length - 1;
+		}
+		if (ready) resolveRoute(path, null);
+	};
+
+	route.get = () => currentPath;
+
+	route.param = (key) => (attrs && key != null ? attrs[key] : attrs);
+
+	// No URL bar in Lynx — kept as an assignable no-op so app code ported
+	// from a real Mithril app that defensively sets `m.route.prefix = ""`
+	// doesn't throw. It never affects anything here.
+	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.
+	 */
+	route.back = function () {
+		if (historyIndex <= 0) return;
+		historyIndex--;
+		resolveRoute(history[historyIndex], null);
+	};
+	route.forward = function () {
+		if (historyIndex >= history.length - 1) return;
+		historyIndex++;
+		resolveRoute(history[historyIndex], null);
+	};
+
+	// 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).
+	route.Link = {
+		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 disabled = Boolean(a.disabled);
+			rest.disabled = disabled;
+			if (!disabled) {
+				rest.ontap = function (e) {
+					var result;
+					if (typeof a.ontap === "function") result = a.ontap.call(e.currentTarget, e);
+					if (result !== false) {
+						e.redraw = false;
+						route.set(buildPathname(a.href, a.params), null, a.options);
+					}
+				};
+			}
+			return m(selector, rest, vnode.children);
+		},
+	};
+
+	return route;
+}
+
+const route = createRoute();
+export default route;

package/test/end-to-end.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from "@rstest/core";
+import m from "mithril";
+import { renderApp } from "../src/background.js";
+import { createPatchApplier } from "../src/apply-patch.js";
+
+// Full round trip: background renders real Mithril against the virtual
+// backend, the resulting ops are replayed onto REAL Lynx PAPI elements
+// (via @lynx-js/testing-environment, not a mock), a simulated tap fires on
+// the real element, is forwarded back to the background thread's fake-dom
+// node, and Mithril's OWN automatic redraw-on-event (no explicit redraw()
+// call anywhere in the view below) produces a second patch that updates
+// the real tree again.
+//
+// This is the direct replacement for mithril-lynx v1's
+// `test/renderer-integration.test.ts` — same intent, rewritten for the v2
+// architecture (see mithril-lynx-v2-desde-cero.md §F1's acceptance
+// criterion: this must pass from the first commit, never be fixed later).
+
+function storedListeners(node: any, type: string): Set<(...args: any[]) => unknown> {
+	return node?.__vanillaListeners?.[type] ?? new Set();
+}
+
+describe("background -> apply-patch end-to-end (real PAPI, via @lynx-js/testing-environment)", () => {
+	it("auto-redraws after a tap with NO explicit redraw() call anywhere in the view", () => {
+		lynxTestingEnv.switchToMainThread();
+
+		const pageId = __GetElementUniqueID(__CreatePage());
+		const applier = createPatchApplier(pageId);
+		// id 0 (the fake-dom document root) maps to a real container the
+		// applier creates itself, exactly like the page's own root view.
+		applier.registerPageRoot(__CreateView(pageId));
+
+		let count = 0;
+		function root() {
+			return m("view", { class: "page" }, [
+				m(
+					"view",
+					{
+						class: "button",
+						ontap: () => {
+							// No redraw()/m.redraw() call here on purpose — the
+							// whole point of this test is that Mithril's own
+							// EventDict auto-redraw (CONTRACT.md §e) is what
+							// makes this repaint, with zero cooperation from
+							// app code.
+							count += 1;
+						},
+					},
+					[m("text", null, "Tap")],
+				),
+				m("text", { class: "counter" }, String(count)),
+			]);
+		}
+
+		lynxTestingEnv.switchToBackgroundThread();
+		let lastOps: unknown[] | null = null;
+		const app = renderApp({
+			root,
+			sendPatch: (ops) => {
+				lastOps = ops;
+			},
+		});
+		expect(lastOps).not.toBeNull();
+
+		lynxTestingEnv.switchToMainThread();
+		applier.applyPatch(lastOps as unknown[]);
+
+		// The decisive assertion for "auto-redraw fired": a second
+		// `sendPatch` call happens purely from the tap (dispatched below),
+		// with no explicit redraw() anywhere in `root()`'s view code.
+		lastOps = null;
+
+		lynxTestingEnv.switchToBackgroundThread();
+		// Forward the tap the same way main-thread -> background forwarding
+		// will in the real channel (F2/F3): find the fake-dom node for the
+		// button and dispatch a synthetic tap on it directly. The id is
+		// deterministic here (root=0 is the document; the button is the
+		// second element created — first is the page `view`, second the
+		// button `view`), matching virtual-backend.js's sequential id
+		// allocation starting at 1.
+		app.document.getNodeById(2)!.dispatchEvent({ type: "tap", currentTarget: app.document.getNodeById(2) });
+
+		expect(count).toBe(1);
+		expect(lastOps).not.toBeNull();
+	});
+});