mithril-lynx 0.0.8 → 2.0.0

package/src/dev-reload-client.js

@@ -0,0 +1,245 @@
+// Development-only client for Lynx Go — background thread only.
+//
+// Adapted from mithril-lynx v1's src/dev-reload-client.js, with the F0
+// monkey-patch of `lynx.requireModuleAsync` REMOVED: that patch existed
+// only because v1's `RuntimeWrapperWebpackPlugin` config never matched
+// `.hot-update.js` chunks, so the native eval context had no `module`/
+// `exports` bindings for them (see mithril-lynx-v2-desde-cero.md §F0.2 —
+// the real fix is the widened `test` regex in this package's plugin.js,
+// applied at build time to every chunk including hot-update ones, not a
+// runtime patch of the module loader).
+//
+// Also REMOVED: the `__mithril_redraw` global v1 called after a successful
+// check(). It isn't needed — the app's own background.ts calls
+// `module.hot.accept("./index.js", ...)` and re-renders from ITS OWN
+// closure when that fires (see the demo app's background.ts for the
+// pattern). This client's only job is: decide whether a rebuild can be
+// applied via HMR at all, and fall back to a full CDP `Page.reload` when
+// it can't (structural changes, `module.hot.decline()`, or a check()
+// rejection).
+//
+// One real fix over v1 that IS new here: the "race de doble-build" (two
+// rebuilds landing close together made v1 see `hotStatus !== "idle"` and
+// give up to a full reload even though each edit alone was light) is
+// fixed by coalescing instead of by a version counter — see
+// `pendingRecheckHash` below. `module.hot.check()` itself already refuses
+// to run when not idle (real webpack behavior), so the fix has to live on
+// this side of that call, not inside it.
+
+var MRL = "[mrl-trace]";
+
+function parseResourceQuery(query) {
+	var values = {};
+	if (typeof query !== "string" || !query.startsWith("?")) return values;
+	for (var i = 0, pairs = query.slice(1).split("&"); i < pairs.length; i++) {
+		var pair = pairs[i];
+		var index = pair.indexOf("=");
+		var key = index === -1 ? pair : pair.slice(0, index);
+		var value = index === -1 ? "" : pair.slice(index + 1);
+		values[key] = decodeURIComponent(value);
+	}
+	return values;
+}
+
+function socketURL(options) {
+	var hostname = options.hostname || "";
+	var port = options.port ? ":" + options.port : "";
+	var pathname = options.pathname || "/rsbuild-hmr";
+	var token = options.token ? "?token=" + encodeURIComponent(options.token) : "";
+	return (options.protocol || "ws") + "://" + hostname + port + pathname + token;
+}
+
+/**
+ * Lynx keys both the HTTP layer and its bytecode cache by URL — a
+ * `Page.reload` with the SAME url re-runs the previous bundle byte-for-byte
+ * even with `ignoreCache: true` (measured on-device against v1, 0.0.8).
+ */
+function cacheBustedUrl(url, now) {
+	if (typeof url !== "string" || !/^https?:\/\//i.test(url)) return undefined;
+	if (now === undefined) now = Date.now();
+	var parts = url.split("?");
+	var base = parts[0];
+	var query = parts[1] || "";
+	var params = new URLSearchParams(query);
+	params.set("t", String(now));
+	return base + "?" + params.toString();
+}
+
+var options = parseResourceQuery(__resourceQuery);
+var bundleUrl = options["bundle-url"];
+
+console.info(MRL + ":0 client-boot", JSON.stringify({
+	hostname: options.hostname,
+	port: options.port,
+	protocol: options.protocol,
+	pathname: options.pathname,
+	hasToken: !!options.token,
+	bundleUrl: bundleUrl,
+}));
+
+var currentHash;
+var initialBuild = true;
+// Anti-loop guard: without comparing against the hash the running bundle
+// was actually built with, every boot would trigger check() for the SAME
+// hash it already carries -> manifest 404 -> full reload -> boot -> loop.
+var runtimeHash = typeof __webpack_require__ !== "undefined"
+	&& typeof __webpack_require__.h === "function"
+	? __webpack_require__.h()
+	: null;
+var socket;
+var reloading = false;
+// Set when an "ok" for a NEW hash arrives while a check() from a PREVIOUS
+// hash is still in flight. Instead of giving up to a full reload (v1's
+// race), the in-flight check's `.then`/`.catch` re-drives the check logic
+// against this hash once it settles.
+var pendingRecheckHash;
+
+function invokeCdpReload() {
+	var upperCase = typeof NativeModules !== "undefined" ? NativeModules.LynxDevToolSetModule : undefined;
+	var lowerCase = typeof NativeModules !== "undefined" ? NativeModules.LynxDevtoolSetModule : undefined;
+	var invokeCdp =
+		(upperCase && upperCase.invokeCdp ? upperCase.invokeCdp.bind(upperCase) : undefined) ??
+		(typeof (lowerCase && lowerCase.invokeCdp) === "function" ? lowerCase.invokeCdp.bind(lowerCase, "Page.reload") : undefined);
+	if (typeof invokeCdp !== "function") return false;
+
+	var params = { ignoreCache: true };
+	var url = cacheBustedUrl(bundleUrl);
+	if (url != null) params.url = url;
+
+	console.info(MRL + ":9 cdp-page-reload", JSON.stringify({ url: url, bundleUrl: bundleUrl }));
+
+	invokeCdp(
+		JSON.stringify({ method: "Page.reload", params }),
+		function (data) {
+			if (!data) return;
+			try {
+				var parsed = JSON.parse(data);
+				if (parsed.error) console.error("[mithril-lynx-v2] Page.reload failed:", parsed.error.message);
+			} catch (e) {
+				// response is not JSON — ignore
+			}
+		},
+	);
+	return true;
+}
+
+function reload(reason) {
+	console.info(MRL + ":8 reload-called", JSON.stringify({ reason: reason || "unspecified" }));
+	reloading = true;
+	if (socket) socket.close();
+	if (!invokeCdpReload()) {
+		console.warn(
+			"[mithril-lynx-v2] Live reload unavailable: NativeModules.LynxDevToolSetModule.invokeCdp was not found.",
+		);
+	}
+}
+
+function runCheck(hash) {
+	console.info(MRL + ":5 hmr-check-calling", "module.hot.check(true)");
+	module.hot.check(true).then(function (updatedModules) {
+		console.info(MRL + ":6 hmr-check-resolved", JSON.stringify({
+			updatedModulesLength: updatedModules ? updatedModules.length : 0,
+		}));
+		var recheck = pendingRecheckHash;
+		pendingRecheckHash = undefined;
+		if (recheck && recheck !== hash) {
+			console.info(MRL + ":6d coalesced-recheck", JSON.stringify({ hash: recheck }));
+			maybeCheck(recheck);
+			return;
+		}
+		if (!updatedModules || updatedModules.length === 0) {
+			console.info(MRL + ":6c hmr-no-modules", "falling back to full reload");
+			reload("hmr-check-returned-no-modules");
+		}
+	}).catch(function (err) {
+		console.warn(MRL + ":7 hmr-check-rejected", JSON.stringify({
+			message: err && err.message,
+		}));
+		var recheck = pendingRecheckHash;
+		pendingRecheckHash = undefined;
+		if (recheck) {
+			maybeCheck(recheck);
+			return;
+		}
+		reload("hmr-check-rejected:" + (err && err.message ? err.message : String(err)));
+	});
+}
+
+function maybeCheck(hash) {
+	var hasHot = typeof module !== "undefined" && module.hot;
+	var hotStatus = hasHot ? module.hot.status() : "n/a";
+
+	console.info(MRL + ":4 hmr-check", JSON.stringify({ hasModuleHot: hasHot, hotStatus: hotStatus }));
+
+	if (!hasHot) {
+		console.info(MRL + ":4a hmr-unavailable", JSON.stringify({ hasHot: hasHot }));
+		reload("hmr-unavailable:no-module-hot");
+		return;
+	}
+	if (hotStatus !== "idle") {
+		// A check for an OLDER hash is still in flight — coalesce instead of
+		// bailing to a full reload (the v1 "race de doble-build" fix).
+		pendingRecheckHash = hash;
+		console.info(MRL + ":4b hmr-check-in-flight", JSON.stringify({ queuedHash: hash }));
+		return;
+	}
+	runCheck(hash);
+}
+
+function handleMessage(rawMessage) {
+	var message;
+	try {
+		message = JSON.parse(rawMessage);
+	} catch (e) {
+		console.warn("[mithril-lynx-v2] Ignoring an invalid dev-server message.");
+		return;
+	}
+
+	switch (message.type) {
+		case "hash":
+			currentHash = message.data;
+			console.info(MRL + ":2a hash-received", JSON.stringify({ hash: message.data }));
+			break;
+		case "ok":
+			console.info(MRL + ":3 ok-received", JSON.stringify({ initialBuild: initialBuild }));
+			if (initialBuild) {
+				initialBuild = false;
+				console.info(MRL + ":3a initial-build-skipped");
+			} else if (currentHash) {
+				if (runtimeHash && currentHash === runtimeHash) {
+					console.info(MRL + ":3b hash-equal-same-build");
+					break;
+				}
+				maybeCheck(currentHash);
+			}
+			break;
+		case "warnings":
+			if (!message.params || !message.params.preventReloading) {
+				if (!initialBuild) reload("build-warnings");
+			}
+			break;
+		case "errors":
+			console.warn("[mithril-lynx-v2] Build failed; waiting for the next successful build.", message.data);
+			break;
+	}
+}
+
+function connect(retries) {
+	if (retries === undefined) retries = 0;
+	console.info(MRL + ":1 ws-connecting", JSON.stringify({ url: socketURL(options), retry: retries }));
+
+	socket = new WebSocket(socketURL(options));
+	socket.onmessage = function (event) { handleMessage(event.data); };
+	socket.onerror = function (error) { console.error("[mithril-lynx-v2] Dev server connection error:", error); };
+	socket.onclose = function () {
+		if (reloading) return;
+		if (retries >= 10) {
+			console.error("[mithril-lynx-v2] Unable to reconnect to the dev server.");
+			return;
+		}
+		var delay = 1000 * Math.pow(2, retries) + Math.random() * 100;
+		setTimeout(function () { connect(retries + 1); }, delay);
+	};
+}
+
+connect();

package/src/dev-transport-noop.js

@@ -0,0 +1,10 @@
+// No-op stand-in for @lynx-js/webpack-dev-transport/client.
+//
+// `dev.hmr: true` makes Rsbuild/Rspeedy inject the official transport
+// client, which opens its OWN WebSocket to /rsbuild-hmr and full-reloads
+// via reloadApp.js — a second reload channel on top of this package's
+// in-bundle dev-reload-client.js. plugin.js re-aliases the module here
+// (order "post", so it wins over the alias @lynx-js/rsbuild-plugin
+// registers) so `module.hot` stays live without a competing channel. Same
+// fix as mithril-lynx v1's F2 (src/dev-transport-noop.js).
+export default class DevTransportClientNoop {}

package/src/fake-dom.js

@@ -0,0 +1,374 @@
+// src/fake-dom.js
+//
+// A DOM implementation good enough for the REAL `render/render.js` (from
+// `mithril-runtime`, https://github.com/carlos-sweb/mithril-runtime — a
+// distribution of Mithril 2.3.8 that drops the browser-only route/trust/
+// request APIs, with render/render.js itself otherwise unmodified from
+// upstream, see CONTRACT.md §g) to run against — nothing more. The exact
+// surface required is documented in `mithril-lynx/CONTRACT.md` (a prior,
+// verified-by-grep extraction of what render.js actually touches on its
+// `dom` parameter): createElement(NS)/createTextNode/createDocumentFragment,
+// insertBefore/appendChild/removeChild, nodeValue, value/checked/
+// selectedIndex, className, setAttribute/removeAttribute/setAttributeNS,
+// style, innerHTML, textContent, firstChild, parentNode, ownerDocument,
+// namespaceURI, contains, focus, nextSibling. render.js never calls
+// `getAttribute` and never checks `nodeType` — so neither is implemented
+// here.
+//
+// This file only runs on the BACKGROUND thread, against a `backend` that
+// records patch ops instead of touching real elements (see
+// backends/virtual-backend.js). The main thread never runs this file, or
+// Mithril's render.js at all — it only replays the recorded ops through
+// `apply-patch.js`, which calls the real Element PAPI directly. That split
+// is the point of the whole architecture (see
+// mithril-lynx-v2/.omo/plans/mithril-lynx-v2-desde-cero.md §3.1): only ONE
+// side needs to be "a DOM", the other side only needs to be "a PAPI patch
+// applier".
+
+const DASH_CASE = /-/;
+
+function camelToDash(name) {
+	return name.replace(/[A-Z]/g, (c) => "-" + c.toLowerCase());
+}
+
+class LynxNode {
+	constructor(ownerDocument) {
+		this.ownerDocument = ownerDocument;
+		this._parent = null;
+	}
+
+	get parentNode() {
+		return this._parent;
+	}
+
+	get nextSibling() {
+		if (!this._parent) return null;
+		const siblings = this._parent._children;
+		const index = siblings.indexOf(this);
+		return index === -1 ? null : (siblings[index + 1] ?? null);
+	}
+}
+
+// Shared child-list bookkeeping for anything that can contain other nodes:
+// real elements, fragments, and the document/root itself. `insertBefore`
+// handles the one piece of real-DOM behavior render.js actually depends on
+// for fragments (CONTRACT.md §c, `createDocumentFragment`): inserting a
+// fragment moves ITS children into the target and leaves the fragment
+// empty, rather than inserting the fragment node itself.
+class LynxContainerNode extends LynxNode {
+	constructor(ownerDocument) {
+		super(ownerDocument);
+		this._children = [];
+	}
+
+	get firstChild() {
+		return this._children[0] ?? null;
+	}
+
+	contains(other) {
+		let node = other;
+		while (node) {
+			if (node === this) return true;
+			node = node._parent;
+		}
+		return false;
+	}
+
+	appendChild(child) {
+		this.insertBefore(child, null);
+		return child;
+	}
+
+	insertBefore(child, refChild) {
+		if (child instanceof LynxFragment) {
+			// Real DOM semantics: the fragment itself is never attached —
+			// only its (already backend-created) children are moved in, in
+			// order, then the fragment is left empty.
+			const grandchildren = child._children.slice();
+			child._children.length = 0;
+			for (const gc of grandchildren) this.insertBefore(gc, refChild);
+			return child;
+		}
+		if (child._parent) child._parent._removeChildBookkeeping(child);
+		const index = refChild ? this._children.indexOf(refChild) : -1;
+		if (index === -1) {
+			this._children.push(child);
+		} else {
+			this._children.splice(index, 0, child);
+		}
+		child._parent = this;
+		if (this._id != null && child._id != null) {
+			this._backend.insertBefore(this._id, child._id, refChild ? refChild._id : -1);
+		}
+		return child;
+	}
+
+	removeChild(child) {
+		this._removeChildBookkeeping(child);
+		if (this._id != null && child._id != null) {
+			this._backend.removeChild(this._id, child._id);
+		}
+		return child;
+	}
+
+	_removeChildBookkeeping(child) {
+		const index = this._children.indexOf(child);
+		if (index !== -1) this._children.splice(index, 1);
+		child._parent = null;
+	}
+}
+
+function createStyleProxy(element) {
+	const methods = {
+		setProperty(name, value) {
+			element._backend.setStyleProperty(element._id, name, String(value));
+		},
+		removeProperty(name) {
+			element._backend.removeStyleProperty(element._id, name);
+		},
+	};
+	return new Proxy(methods, {
+		get(target, prop) {
+			return target[prop];
+		},
+		set(_target, prop, value) {
+			if (typeof prop !== "string") return true;
+			// Direct camelCase assignment path (CONTRACT.md §f, line 764/781).
+			// Normalized to dash-case so the backend/PAPI only ever sees one
+			// key shape regardless of which of Mithril's two style paths ran.
+			const name = DASH_CASE.test(prop) ? prop : camelToDash(prop);
+			if (value === "" || value == null) {
+				element._backend.removeStyleProperty(element._id, name);
+			} else {
+				element._backend.setStyleProperty(element._id, name, String(value));
+			}
+			return true;
+		},
+	});
+}
+
+export class LynxElement extends LynxContainerNode {
+	constructor(ownerDocument, backend, tag, ns) {
+		super(ownerDocument);
+		this._backend = backend;
+		this.tag = tag;
+		this.namespaceURI = ns;
+		this._id = ns ? backend.createElementNS(ns, tag) : backend.createElement(tag);
+		ownerDocument._nodesById.set(this._id, this);
+		this._style = null;
+		this._listeners = Object.create(null);
+		// `hasPropertyKey` (CONTRACT.md §e) requires `"value" in vnode.dom` etc.
+		// to be true for the property-write fast path to apply to form
+		// elements — plain own properties satisfy the `in` check.
+		this.value = undefined;
+		this.checked = undefined;
+		this.selectedIndex = undefined;
+	}
+
+	get style() {
+		if (!this._style) this._style = createStyleProxy(this);
+		return this._style;
+	}
+
+	set style(value) {
+		if (value == null || value === "") {
+			// `element.style = ""` (CONTRACT.md §f, lines 750-752): clear.
+			// We don't track which properties were set, so this relies on the
+			// backend/native side treating a style-reset op as "clear all" —
+			// see backends/virtual-backend.js `Op.SetStyleProperty` with a
+			// name of `*`.
+			this._backend.removeStyleProperty(this._id, "*");
+			return;
+		}
+		if (typeof value !== "object") {
+			// `element.style = "color: red"` (string passthrough, §f lines
+			// 753-755) — not supported: Lynx's style PAPI is key/value, not a
+			// CSS-text parser. Documented limitation, not a silent bug.
+			if (typeof console !== "undefined") {
+				console.warn(
+					"[mithril-lynx-v2] Assigning a CSS text string to `style` is not supported; use a style object.",
+				);
+			}
+			return;
+		}
+		// Mithril itself never assigns a plain object to `.style` directly —
+		// `updateStyle` always goes through `.setProperty`/property
+		// assignment for object styles (§f). This branch exists only for
+		// completeness against the DOM contract.
+		for (const key of Object.keys(value)) {
+			this.style[key] = value[key];
+		}
+	}
+
+	get className() {
+		return this._className ?? "";
+	}
+
+	set className(value) {
+		// Mithril's `setAttr`/`removeAttr` map `className` -> the `"class"`
+		// attribute (CONTRACT.md §e); routed here directly since `className`
+		// is also a real property on this class (`hasPropertyKey` would
+		// otherwise be tempted to use the property path instead).
+		this._className = value;
+		this._backend.setClasses(this._id, value == null ? "" : String(value));
+	}
+
+	setAttribute(name, value) {
+		if (name === "class") {
+			this.className = value;
+			return;
+		}
+		this._backend.setAttribute(this._id, name, value == null ? null : String(value));
+	}
+
+	removeAttribute(name) {
+		if (name === "class") {
+			this.className = "";
+			return;
+		}
+		this._backend.removeAttribute(this._id, name);
+	}
+
+	setAttributeNS(ns, name, value) {
+		this._backend.setAttributeNS(this._id, ns, name, value == null ? null : String(value));
+	}
+
+	addEventListener(type, listener) {
+		const isNew = !(type in this._listeners);
+		this._listeners[type] = listener;
+		if (isNew) this._backend.addEvent(this._id, type);
+	}
+
+	removeEventListener(type) {
+		if (!(type in this._listeners)) return;
+		delete this._listeners[type];
+		this._backend.removeEvent(this._id, type);
+	}
+
+	/** Invoked by the background-side event router when a forwarded native
+	 * event for this element's id arrives — see background.js. Mirrors what
+	 * a real DOM does automatically for an EventListener OBJECT (as opposed
+	 * to a plain function) registered via addEventListener: it calls
+	 * `.handleEvent(ev)` on it. Mithril's own `EventDict` (render.js) relies
+	 * on exactly this. */
+	dispatchEvent(event) {
+		const listener = this._listeners[event.type];
+		if (!listener) return;
+		if (typeof listener === "function") listener.call(event.currentTarget, event);
+		else if (typeof listener.handleEvent === "function") listener.handleEvent(event);
+	}
+
+	set textContent(value) {
+		// render.js only ever does `dom.textContent = ""` (first-render
+		// clear, CONTRACT.md §b line 898) — implemented as "remove every
+		// child", which is exactly what that assignment means for an
+		// already-empty-or-not container.
+		if (value !== "") {
+			if (typeof console !== "undefined") {
+				console.warn("[mithril-lynx-v2] Non-empty `textContent` assignment is not supported.");
+			}
+			return;
+		}
+		for (const child of this._children.slice()) this.removeChild(child);
+	}
+
+	set innerHTML(_value) {
+		// `m.trust()`/contenteditable sync (CONTRACT.md §c) — Lynx elements
+		// have no HTML-string target to parse into. Documented as
+		// unsupported, matching this project's existing stance on other
+		// browser-only Mithril features (e.g. `m.request`, see
+		// mithril-lynx/AGENTS.md history) rather than silently doing nothing
+		// with no signal.
+		if (typeof console !== "undefined") {
+			console.warn("[mithril-lynx-v2] `m.trust()` / innerHTML is not supported on Lynx elements.");
+		}
+	}
+
+	focus() {
+		// Native `<input>` focus on Lynx is managed by the platform, not by
+		// a JS `.focus()` call reaching into the render pipeline — calling
+		// into the backend here would mean patch application could disturb
+		// focus mid-keystroke, which is the exact failure mode
+		// mithril-lynx v1 was designed around (its `<input>` deliberately
+		// has no bound `value` for the same reason). No-op by design.
+	}
+}
+
+export class LynxText extends LynxNode {
+	constructor(ownerDocument, backend, text) {
+		super(ownerDocument);
+		this._backend = backend;
+		this._id = backend.createText(text);
+	}
+
+	get nodeValue() {
+		return this._text;
+	}
+
+	set nodeValue(value) {
+		this._text = value;
+		this._backend.setText(this._id, value);
+	}
+}
+
+// Fragments never get a backend id — see LynxContainerNode#insertBefore,
+// which special-cases them by moving their children instead of attaching
+// the fragment itself. `_id` stays `undefined` on purpose: the `if
+// (this._id != null && child._id != null)` guards in insertBefore/
+// removeChild are what keep a fragment-as-parent from ever trying to call
+// the backend for itself.
+export class LynxFragment extends LynxContainerNode {}
+
+export class LynxDocument extends LynxContainerNode {
+	constructor(backend) {
+		super(null);
+		this._backend = backend;
+		this.ownerDocument = this;
+		// id 0 is reserved for "the real page container" — pre-registered by
+		// the main-thread patch applier before any ops are replayed (see
+		// apply-patch.js). Explicit and inspectable, unlike an implicit
+		// "whatever the first created element happens to be" convention.
+		this._id = 0;
+		this.namespaceURI = undefined;
+		/** id -> node, for dispatching a forwarded native event (which only
+		 * carries an id + type) to the right fake-dom element. Populated by
+		 * every LynxElement/LynxText constructor; never by fragments, which
+		 * have no id and are never event targets. */
+		this._nodesById = new Map();
+	}
+
+	getNodeById(id) {
+		return this._nodesById.get(id) ?? null;
+	}
+
+	focus() {
+		// Never meaningfully called on the document root itself; present so
+		// render.js's post-render focus-restoration check (CONTRACT.md §b)
+		// never throws if `activeElement` happens to resolve to the root.
+	}
+
+	set textContent(value) {
+		if (value !== "") return;
+		for (const child of this._children.slice()) this.removeChild(child);
+	}
+
+	createElement(tag) {
+		return new LynxElement(this, this._backend, tag, undefined);
+	}
+
+	createElementNS(ns, tag) {
+		return new LynxElement(this, this._backend, tag, ns);
+	}
+
+	createTextNode(text) {
+		return new LynxText(this, this._backend, text);
+	}
+
+	createDocumentFragment() {
+		return new LynxFragment(this);
+	}
+}
+
+export function createLynxDocument(backend) {
+	return new LynxDocument(backend);
+}

package/src/main-thread.d.ts

@@ -0,0 +1 @@
+export function setupRenderer(): void;

package/src/main-thread.js

@@ -0,0 +1,68 @@
+// src/main-thread.js
+//
+// Entry point for the main thread (Lepus VM). Never runs Mithril or any app
+// view code (see background.js's header, plan §3.1) — only replays patches
+// from the background thread onto real Element PAPI, and forwards native
+// events back. Structure ported from mithril-lynx v1's
+// renderer/main-thread.js (setupRenderer()), which already validated this
+// exact __RenderPage/__DestroyLifetime timing and patch-buffering behavior
+// on a real device (mithril-lynx/DEVICE_VERIFICATION.md) — that plumbing
+// was never part of the bug this rewrite exists to fix.
+
+import { createPatchApplier } from "./apply-patch.js";
+import {
+	destroyLifetimeEventName,
+	onPatchFromBackground,
+	renderPageEventName,
+	sendEventToBackground,
+} from "./channel.js";
+
+// The native engine unconditionally invokes a global `processData(initData)`
+// hook on every __RenderPage — found missing here via real-device testing
+// in mithril-lynx v1 (its main-thread.js already had this fix; its
+// renderer/main-thread.js needed it too). Required regardless of framework.
+Object.assign(globalThis, {
+	processData: (data) => data,
+});
+
+/**
+ * Call once, at main-thread.ts's top level. Waits for `__RenderPage` to
+ * create the real page (the background thread's own initial render may
+ * finish before or after that fires — patches arriving early are buffered
+ * and replayed in order once the page exists), then wires the patch/event
+ * channel for the lifetime of the page.
+ */
+export function setupRenderer() {
+	const engine = lynx.getEngine();
+	let applier = null;
+	let pageReady = false;
+	let pendingPatches = [];
+
+	const onPatch = (event) => {
+		if (!pageReady) {
+			pendingPatches.push(event.data);
+			return;
+		}
+		applier.applyPatch(event.data);
+	};
+	onPatchFromBackground(onPatch);
+
+	const onRenderPage = () => {
+		const page = __CreatePage("0", 0);
+		const pageId = __GetElementUniqueID(page);
+		applier = createPatchApplier(pageId, {
+			onEvent: (id, type, nativeEvent) => sendEventToBackground(id, type, nativeEvent),
+		});
+		applier.registerPageRoot(page);
+		pageReady = true;
+		for (const ops of pendingPatches) applier.applyPatch(ops);
+		pendingPatches = [];
+	};
+	engine.addEventListener(renderPageEventName, onRenderPage);
+
+	const onDestroyLifetime = () => {
+		engine.removeEventListener(renderPageEventName, onRenderPage);
+		engine.removeEventListener(destroyLifetimeEventName, onDestroyLifetime);
+	};
+	engine.addEventListener(destroyLifetimeEventName, onDestroyLifetime);
+}