mithril-lynx 0.0.6 → 0.0.7

package/README.md

@@ -298,4 +298,12 @@ bun run test
 
 Tests run against `@lynx-js/testing-environment`'s jsdom-backed PAPI polyfill. The polyfill itself is published as `mithril-lynx/testing`'s `installTestingPolyfills()` (see `test/setup.ts` for the one-line setup) — consuming apps can use the exact same polyfill for their own tests instead of maintaining a duplicate copy; see `mithril-app/test/setup.ts` for a worked example.
 
-**Not provided**: Fast Refresh and a devtools/inspector bundle (project plan, Phase 9 / subsystem 12) are explicitly out of scope — they're deep, compiler-driven DX features in upstream ReactLynx with no zero-compiler equivalent worth building. `rspeedy dev`'s existing full-reload-on-file-change loop is the honest substitute.
+**Not provided**: Fast Refresh and a devtools/inspector bundle (project plan, Phase 9 / subsystem 12) are explicitly out of scope — they're deep, compiler-driven DX features in upstream ReactLynx with no zero-compiler equivalent worth building.
+
+In development, `pluginMithrilLynx()` adds a small background-thread client even
+when the app has no `background.ts`. After a successful rebuild it reloads the
+bundle through Lynx Go's `ExplorerModule.openSchema()`, rather than attempting
+module HMR (Mithril views run in the separate main-thread/Lepus bundle). This
+is intentionally a **Lynx Go viewer** convenience, not a portable SDK API: a
+different viewer or a final native host that does not provide `ExplorerModule`
+will log a warning and must be reloaded manually.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mithril-lynx",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "Mithril.js rendered through Lynx's Element PAPI \u2014 a contract-complete port of mithril/render/render.js@2.3.8 to the Lynx main thread, packaged as a reusable framework.",
   "license": "MIT",
   "type": "module",

package/plugin.js

@@ -18,6 +18,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
 
 import { RuntimeWrapperWebpackPlugin } from "@lynx-js/runtime-wrapper-webpack-plugin";
 import { LynxEncodePlugin, LynxTemplatePlugin } from "@lynx-js/template-webpack-plugin";
@@ -27,6 +28,55 @@ const PLUGIN_NAME = "mithril-lynx-template-webpack";
 const BACKGROUND_CANDIDATES = ["background.ts", "background.js"];
 const STYLE_CANDIDATES = ["style.css"];
 
+// Live reload's client only runs where a full JS engine with Native Module
+// access exists: the background/JS thread. The main-thread/Lepus VM cannot
+// use it. An app without background.ts therefore gets a synthetic background
+// entry in development; see `includeBackground` below. Imported by this
+// resolved absolute path directly (see the entry-construction loop below),
+// not through a "mithril-lynx/..." bare specifier — that collides with the
+// package's own broader "mithril-lynx" resolve alias.
+const DEV_RELOAD_CLIENT_PATH = path.join(
+	path.dirname(fileURLToPath(import.meta.url)),
+	"src",
+	"dev-reload-client.js",
+);
+
+function createDevReloadClientQuery(api, environment, entryName) {
+	const config = environment.config ?? {};
+	const dev = config.dev ?? {};
+	const server = config.server ?? {};
+	const devServer = api.context.devServer ?? {};
+	// Rsbuild resolves this to the LAN address it advertises when server.host is
+	// 0.0.0.0, which is the address a physical Lynx Go device can actually use.
+	const hostname = dev.client?.host || devServer.hostname || server.host || "";
+	const port = devServer.port ?? server.port ?? "";
+	const protocol = devServer.https ? "https" : "http";
+	// At this point in the pipeline Rsbuild hasn't started the dev server yet,
+	// so `dev.assetPrefix` (when it's the default, host-derived one — see
+	// @lynx-js/rsbuild-plugin) still contains the literal, unsubstituted
+	// "<port>" placeholder it's only resolved to a real port number later, in
+	// its own `printUrls` callback. `hostname`/`port` above are already the
+	// real values, though, so resolve the placeholder the same way that
+	// callback does rather than trusting assetPrefix as pre-resolved.
+	const assetPrefix = (typeof dev.assetPrefix === "string" ? dev.assetPrefix : "/").replaceAll(
+		"<port>",
+		String(port),
+	);
+	const base = /^https?:\/\//.test(assetPrefix)
+		? assetPrefix
+		: `${protocol}://${hostname}${port ? `:${port}` : ""}${assetPrefix}`;
+	const bundleUrl = new URL(`${entryName}.bundle`, base.endsWith("/") ? base : `${base}/`).toString();
+	const params = new URLSearchParams({
+		hostname,
+		port: String(port),
+		pathname: "/rsbuild-hmr",
+		protocol: devServer.https ? "wss" : "ws",
+		"bundle-url": bundleUrl,
+	});
+	if (environment.webSocketToken) params.set("token", environment.webSocketToken);
+	return params.toString();
+}
+
 function findSibling(dir, candidates) {
 	for (const name of candidates) {
 		const candidate = path.join(dir, name);
@@ -59,13 +109,37 @@ function packageRootOf(resolvedFile) {
 
 export function pluginMithrilLynx(options = {}) {
 	const targetSdkVersion = options.targetSdkVersion ?? "3.5";
+	const hmr = options.hmr ?? false;
 
 	return {
 		name: PLUGIN_NAME,
 		setup(api) {
 			// Keep the template plugin discoverable by Rspeedy's Lynx internals.
 			api.expose(Symbol.for("LynxTemplatePlugin"), { LynxTemplatePlugin });
-			api.modifyBundlerChain((chain) => {
+
+			// setupApp()'s render model has no per-module "accept and patch"
+			// story (rendering is driven by native __RenderPage/__UpdatePage
+			// events, not by re-executing a hot-swapped module) -- module-level
+			// HMR's eval'd *.hot-update.js chunks also aren't runtime-wrapped
+			// the way the real background.js bundle is, and fail native-side
+			// with "ReferenceError: exports is not defined" if hot is left on.
+			// Force dev.hmr off (unless the app explicitly set it) so the dev
+			// client's ok() handler takes its other branch -- a full native
+			// Page.reload -- which is the one live-reload path this framework
+			// actually supports cleanly. dev.liveReload stays at its default.
+			api.modifyRsbuildConfig({
+				// Not a plain default: Rsbuild has already stamped dev.hmr:true onto
+				// the config by the time ANY hook sees it (even api.getRsbuildConfig
+				// ("original")), so there's no reliable way to tell "the app asked for
+				// hot module replacement" apart from "Rsbuild defaulted it" -- this
+				// always wins, with an explicit opt-out via pluginMithrilLynx({ hmr })
+				// for anyone who's fixed up their own app-level accept() story and the
+				// RuntimeWrapperWebpackPlugin gap noted below.
+				handler: (config, { mergeRsbuildConfig }) => mergeRsbuildConfig(config, { dev: { hmr } }),
+				order: "post",
+			});
+
+			api.modifyBundlerChain((chain, { isDev, environment }) => {
 				// mithril-lynx's own src/lynx-mithril-shim.js deep-imports mithril's
 				// internal render/cachedAttrsIsStaticMap.js (and its emptyAttrs
 				// singleton). If the app's own `require("mithril")` resolves to a
@@ -137,12 +211,30 @@ export function pluginMithrilLynx(options = {}) {
 					const bgAsset = `.rspeedy/${name}/background.js`;
 					const mtAsset = `.rspeedy/${name}/main-thread.js`;
 					const hasBackground = bgSource != null;
+					// In dev, always materialize a background chunk — even for an app
+					// with no background.ts of its own — so live reload's client has
+					// somewhere to run. In production, keep the original behavior
+					// exactly (no background chunk at all when the app doesn't use one).
+					const includeBackground = hasBackground || isDev;
 
 					// Each entry always has main-thread code and may opt into a
 					// background thread by adding a sibling background.ts file.
-					if (hasBackground) {
+					if (includeBackground) {
+						// Imported by its resolved absolute path (plus the query string
+						// the client reads its config from) rather than through the bare
+						// "mithril-lynx/dev-reload-client" specifier + an alias: the
+						// package-wide "mithril-lynx" prefix alias set above matches that
+						// specifier first regardless of registration order (webpack/
+						// rspack's resolve.alias picks the first matching entry, not the
+						// most specific one), which broke the import entirely.
+						const bgImports = isDev
+							? [
+									`${DEV_RELOAD_CLIENT_PATH}?${createDevReloadClientQuery(api, environment, name)}`,
+									...(hasBackground ? [bgSource] : []),
+								]
+							: bgSource;
 						chain.entry(bgEntry).add({
-							import: bgSource,
+							import: bgImports,
 							filename: bgAsset,
 						});
 					}
@@ -157,14 +249,14 @@ export function pluginMithrilLynx(options = {}) {
 							...LynxTemplatePlugin.defaultOptions,
 							filename: `${name}.bundle`,
 							intermediate: `.rspeedy/${name}`,
-							chunks: hasBackground ? [bgEntry, mtEntry] : [mtEntry],
+							chunks: includeBackground ? [bgEntry, mtEntry] : [mtEntry],
 							dsl: "react_nodiff",
 							targetSdkVersion,
 							cssPlugins: [],
 						},
 					]);
 
-					if (hasBackground) {
+					if (includeBackground) {
 						// Background chunks run in the JavaScript thread and need the
 						// Lynx runtime wrapper; main-thread chunks are encoded as lepus.
 						chain.plugin(`runtime-wrapper-${name}`).use(

package/src/dev-reload-client.js

@@ -0,0 +1,122 @@
+// Development-only client for Lynx Go.
+//
+// Mithril view code runs in the main-thread/Lepus bundle, while WebSocket and
+// Native Module access only exist in the background JS bundle. Consequently
+// normal module HMR cannot patch the view code. On a successful rebuild this
+// client asks Lynx Go's ExplorerModule to load the same bundle URL again.
+
+function parseResourceQuery(query) {
+	const values = {};
+	if (typeof query !== "string" || !query.startsWith("?")) return values;
+	for (const pair of query.slice(1).split("&")) {
+		const index = pair.indexOf("=");
+		const key = index === -1 ? pair : pair.slice(0, index);
+		const value = index === -1 ? "" : pair.slice(index + 1);
+		values[key] = decodeURIComponent(value);
+	}
+	return values;
+}
+
+function socketURL(options) {
+	const hostname = options.hostname || "";
+	const port = options.port ? `:${options.port}` : "";
+	const pathname = options.pathname || "/rsbuild-hmr";
+	const token = options.token ? `?token=${encodeURIComponent(options.token)}` : "";
+	return `${options.protocol || "ws"}://${hostname}${port}${pathname}${token}`;
+}
+
+const options = parseResourceQuery(__resourceQuery);
+const bundleUrl = options["bundle-url"];
+let currentHash;
+let initialBuild = true;
+let socket;
+// ExplorerModule.openSchema(url) makes Lynx Go fully reload — including
+// re-executing this very module from scratch. That would naturally replace
+// this stale instance's socket with a fresh one, except the OLD connection
+// is otherwise left open: confirmed on-device that every earlier reload's
+// socket stays alive and keeps receiving server broadcasts, so a build a few
+// reloads in fires openSchema several times at once (one call per still-open
+// stale socket), and the resulting navigations race and clobber each other —
+// only the first reload after a fresh QR/URL load (a single open socket)
+// reliably lands. Closing this socket ourselves right before reloading, and
+// suppressing the reconnect-on-close it would otherwise trigger, keeps
+// exactly one socket alive at a time.
+let reloading = false;
+
+console.info(
+	"[mithril-lynx] ExplorerModule.openSchema:",
+	typeof NativeModules !== "undefined" && typeof NativeModules.ExplorerModule?.openSchema,
+);
+
+function reload() {
+	const openSchema =
+		typeof NativeModules !== "undefined" && NativeModules.ExplorerModule?.openSchema;
+	if (typeof openSchema !== "function") {
+		console.warn("[mithril-lynx] Live reload unavailable: ExplorerModule.openSchema was not found.");
+		return;
+	}
+	if (!bundleUrl) {
+		console.warn("[mithril-lynx] Live reload unavailable: the bundle URL was not configured.");
+		return;
+	}
+	console.info("[mithril-lynx] Reloading updated bundle.");
+	reloading = true;
+	socket?.close();
+	openSchema.call(NativeModules.ExplorerModule, bundleUrl);
+}
+
+function handleMessage(rawMessage) {
+	let message;
+	try {
+		message = JSON.parse(rawMessage);
+	} catch {
+		console.warn("[mithril-lynx] Ignoring an invalid dev-server message.");
+		return;
+	}
+
+	switch (message.type) {
+		case "hash":
+			currentHash = message.data;
+			break;
+		case "ok":
+			// The server sends hash + ok immediately after connecting. Reloading
+			// then would loop forever, so only act after a later successful build.
+			if (initialBuild) initialBuild = false;
+			else if (currentHash) reload();
+			break;
+		case "still-ok":
+			console.info("[mithril-lynx] Nothing changed.");
+			break;
+		case "warnings":
+			console.warn("[mithril-lynx] Build completed with warnings.", message.data);
+			if (!message.params?.preventReloading && !initialBuild) reload();
+			break;
+		case "errors":
+			console.warn("[mithril-lynx] Build failed; waiting for the next successful build.", message.data);
+			break;
+		case "invalid":
+			console.info("[mithril-lynx] App updated. Recompiling...");
+			break;
+		case "error":
+			console.error("[mithril-lynx] Dev server error:", message.data);
+			break;
+	}
+}
+
+function connect(retries = 0) {
+	socket = new WebSocket(socketURL(options));
+	socket.onmessage = (event) => handleMessage(event.data);
+	socket.onerror = (error) => console.error("[mithril-lynx] Dev server connection error:", error);
+	socket.onclose = () => {
+		if (reloading) return; // Deliberately closed by reload() — a fresh socket is on its way already.
+		if (retries >= 10) {
+			console.error("[mithril-lynx] Unable to reconnect to the dev server.");
+			return;
+		}
+		const delay = 1000 * 2 ** retries + Math.random() * 100;
+		console.info("[mithril-lynx] Dev server disconnected; reconnecting...");
+		setTimeout(() => connect(retries + 1), delay);
+	};
+}
+
+connect();