mithril-lynx 0.0.8 → 0.0.9

package/README.md

@@ -303,24 +303,42 @@ Tests run against `@lynx-js/testing-environment`'s jsdom-backed PAPI polyfill. T
 In development, `pluginMithrilLynx()` reloads the running page after every
 successful rebuild instead of attempting module HMR — Mithril view code runs in
 the main-thread/Lepus bundle, and rspack's hot runtime can only patch modules on
-the background thread, so HMR could never reach it. (No synthetic background
-entry is created for this: the reload runs from the dev-server process, not from
-a chunk inside the app.)
-
-The reload goes through the Lynx DevTool connector and sends CDP `Page.reload`
-to the session currently serving your bundle. That reloads the existing page
-**in place**, so nothing is pushed onto the viewer's back stack. Two consequences
-worth knowing:
-
-- **Live reload reaches the device over adb, not over the LAN.** The DevTool
-  connector talks to the adb server (it sets up an adb reverse tunnel to the
-  device's DebugRouter). `npm run dev` and the QR-scan flow are unaffected and
-  still work over Wi-Fi — only the automatic reload needs adb. With no adb
-  connection the rebuild logs a warning and you reload by hand. Wireless
-  debugging (`adb connect <ip>:5555`) satisfies this with no cable, and
-  `ANDROID_SERIAL` picks the device when several are attached.
-- It is a **dev-server convenience, not a portable SDK API**: the connector is
-  imported lazily by a dev rebuild only, and no reload code is bundled into the
-  app in any build.
-
-Turn it off with `pluginMithrilLynx({ liveReload: false })`.
+the background thread, so HMR could never reach it.
+
+The default strategy (`liveReload: true`) is an **in-bundle client**: a small
+WebSocket client (`src/dev-reload-client.js`) is injected into a synthetic
+background chunk and runs on the device itself. On a successful rebuild it sends
+CDP `Page.reload` through `NativeModules.LynxDevToolSetModule.invokeCdp` — the
+same mechanism Rspeedy's own live-reload client uses
+(`@lynx-js/webpack-dev-transport/lib/client/reloadApp.js`) — with a cache-busted
+URL. That reloads the existing page **in place**, so nothing is pushed onto the
+viewer's back stack. Because the client is *in* the bundle, the only network hop
+is the WebSocket itself: **the reload works over Wi-Fi alone — no adb, no cable**
+(the initial load via QR/URL is also over Wi-Fi). Three consequences worth
+knowing:
+
+- **Why not module HMR**: real HMR would need to patch main-thread/Lepus view
+  code, which rspack's hot runtime can only reach from the background thread —
+  an architectural mismatch, not a bug to fix. The plugin forces `dev.hmr` off.
+- **Why not `lynx.reload()`**: on current engines it re-executes the main-thread
+  bundle against the live session without re-injecting
+  `removeComponents`/`updatePage`, crashing with two TypeErrors (measured on a
+  real device). It is kept only as an in-client fallback for viewers/SDKs whose
+  reload path is intact.
+- It is a **dev-server convenience, not a portable SDK API**: the client is only
+  ever imported in dev builds, and no reload code is bundled into the app in a
+  production build.
+
+Two alternative strategies exist, selected via the `liveReload` option:
+
+- **`liveReload: "devtool"`** — the 0.0.8 strategy. The reload runs from the
+  Node dev-server process via `@lynx-js/devtool-connector`, which reaches the
+  device over adb (it sets up an adb reverse tunnel to the device's DebugRouter);
+  with no adb connection the rebuild logs a warning and you reload by hand.
+  Wireless debugging (`adb connect <ip>:5555`) satisfies this with no cable, and
+  `ANDROID_SERIAL` picks the device when several are attached. Use this for
+  viewers/SDKs that don't expose the in-bundle DevTool CDP bridge module.
+- **`liveReload: false`** — no live reload at all; reload the page by hand.
+
+The full 0.0.7 → 0.0.8 → 0.0.9 history and the measured on-device evidence live
+in `NETWORK_LIVE_RELOAD_INVESTIGATION.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mithril-lynx",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "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.d.ts

@@ -15,11 +15,17 @@ export interface PluginMithrilLynxOptions {
   hmr?: boolean;
   /**
    * Reload the running page after each successful dev rebuild. Defaults to
-   * true. Reloading goes through the Lynx DevTool connector, which reaches the
-   * device over adb, so a device connected only over Wi-Fi must be reloaded
-   * manually.
+   * true. `true` uses the in-bundle client (`src/dev-reload-client.js`):
+   * a WebSocket client injected into a synthetic background chunk that sends
+   * CDP `Page.reload` via `NativeModules.LynxDevToolSetModule.invokeCdp`
+   * (cache-busted URL) — works over Wi-Fi alone, no adb, no back-stack
+   * corruption. `"devtool"` uses the 0.0.8 strategy: the Node dev-server
+   * process sends CDP `Page.reload` through
+   * `@lynx-js/devtool-connector`, which reaches the device over adb — the
+   * fallback for viewers/SDKs without the in-bundle DevTool CDP bridge.
+   * `false` disables live reload.
    */
-  liveReload?: boolean;
+  liveReload?: boolean | "devtool";
 }
 
 /**

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";
@@ -30,31 +31,115 @@ const STYLE_CANDIDATES = ["style.css"];
 // ---------------------------------------------------------------------------
 // Live reload (dev only)
 //
-// How a rebuild reaches the device, and why it works this way:
+// Two strategies, both triggered by a successful rebuild, picked by the
+// `liveReload` option:
 //
-// - Real module HMR cannot help here at all. Mithril view code lives in the
-//   main-thread/Lepus chunk, and rspack's hot runtime can only patch modules in
-//   the registry it runs from — the background/JS thread. That is an
-//   architectural mismatch, not a bug to fix.
-// - A CDP command the bundle sends to *itself*
-//   (NativeModules.LynxDevToolSetModule.invokeCdp) is a silent no-op: there is
-//   no external DevTool session behind it.
-// - ExplorerModule.openSchema(url) — what 0.0.7 shipped — works, but it is a
-//   real navigation: Lynx Go starts a NEW LynxViewShellActivity every time and
-//   never finishes the one it replaces, so Back then steps through one frozen
-//   snapshot per reload.
-// - Page.reload from an *external* DevTool session reloads the existing page in
-//   place (the DevTools reference notes the session URL is unchanged after it),
-//   so nothing new is pushed onto the back stack.
+// - `true` (default): the "in-bundle" client. A small WebSocket client
+//   (src/dev-reload-client.js) is injected into a synthetic background chunk
+//   and runs on the device; on an `ok` message it sends a CDP `Page.reload`
+//   through `NativeModules.LynxDevToolSetModule.invokeCdp` — the same
+//   mechanism Rspeedy's own live-reload client uses
+//   (@lynx-js/webpack-dev-transport/lib/client/reloadApp.js) — with a
+//   cache-busted URL. Page.reload reloads the CURRENT page in place without
+//   starting a new Activity (verified in 0.0.8). This works over Wi-Fi alone
+//   (the WebSocket is the only network hop): no adb, no cable. Requires the
+//   viewer SDK to expose the DevTool CDP bridge native module (Lynx Go does).
 //
-// So this runs from the Node dev-server process rather than from a chunk
-// bundled into the app, and no synthetic background entry is needed.
+// - `"devtool"`: the 0.0.8 strategy. Runs from the Node dev-server process
+//   via @lynx-js/devtool-connector (adb on Android) and sends CDP
+//   `Page.reload` to the session serving this app's bundle. Also reloads in
+//   place (no back-stack corruption), but needs the device on adb — so it is
+//   the fallback for viewers/SDKs where the in-bundle CDP bridge is missing.
 //
-// The trade-off: the DevTool connector reaches the device through adb, so live
-// reload needs the device connected over adb. openSchema could work over Wi-Fi
-// alone, but only by corrupting the back stack.
+// Why not real module HMR: mithril view code lives in the main-thread/Lepus
+// chunk, and rspack's hot runtime can only patch modules in the registry it
+// runs from — the background/JS thread. That is an architectural mismatch,
+// not a bug to fix. dev.hmr is forced off regardless of strategy.
+//
+// Why not lynx.reload() (0.0.9's original mechanism): on the device's engine
+// (reported 3.5) it re-executes the main-thread bundle against the live
+// session but does not re-inject the runtime helpers
+// removeComponents/updatePage, so the render crashes with two TypeErrors and
+// the background chunk never re-runs (socket dies; later builds ignored). Kept
+// only as an in-client fallback for viewers whose reload path is intact.
+//
+// Why not ExplorerModule.openSchema(url) (0.0.7's mechanism): it works over
+// Wi-Fi, but it is a real navigation — Lynx Go starts a NEW
+// LynxViewShellActivity every time and never finishes the one it replaces, so
+// Back steps through one frozen snapshot per reload. Kept only as an
+// in-client fallback for viewers lacking `lynx.reload`.
+//
+// Why not lynx.fetchBundle + lynx.loadScript: in lynx-core these are the
+// lazy-bundle path (LazyBundleLoader / LoadCustomSectionScript) — they load a
+// customSection of a SEPARATE lazily-fetched bundle, not the page's own
+// main-thread/Lepus template, so they cannot re-render the current page.
 // ---------------------------------------------------------------------------
 
+// The in-bundle client only runs where a full JS engine with WebSocket + the
+// `lynx` global 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
+// 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
+// below 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 in 0.0.7.
+const DEV_RELOAD_CLIENT_PATH = path.join(
+	path.dirname(fileURLToPath(import.meta.url)),
+	"src",
+	"dev-reload-client.js",
+);
+
+/**
+ * Builds the query string the in-bundle dev-reload client reads its config
+ * from: the WebSocket endpoint to connect to and the bundle URL it would
+ * fall back to (ExplorerModule.openSchema). Mirrors what
+ * `@lynx-js/rsbuild-plugin` bakes into `@lynx-js/webpack-dev-transport/client`.
+ */
+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 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) still
+	// contains the literal "<port>" placeholder it's only resolved to a real
+	// port number later. `hostname`/`port` above are already the real values,
+	// so resolve the placeholder the same way rather than trusting assetPrefix.
+	const assetPrefix = (typeof dev.assetPrefix === "string" ? dev.assetPrefix : "/").replaceAll(
+		"<port>",
+		String(port),
+	);
+	const base = /^https?:\/\//.test(assetPrefix)
+		? assetPrefix
+		: `${protocol}://${hostname}${port ? `:${port}` : ""}${assetPrefix}`;
+	const clientBundleUrl = 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": clientBundleUrl,
+	});
+	if (environment.webSocketToken) params.set("token", environment.webSocketToken);
+	return params.toString();
+}
+
+// --- Devtool-connector strategy (liveReload: "devtool") --------------------
+// Everything below through closeDevtoolTransport()/describeReloadFailure() is
+// the 0.0.8 adb/CDP path, used only when the in-bundle client can't run (e.g.
+// a viewer whose SDK predates the DevTool CDP bridge native module). It is
+// otherwise dormant.
+
 /** Lynx Go's own shell page is a Lynx session too — never a reload target. */
 const VIEWER_SHELL_BUNDLE = "homepage.lynx.bundle";
 
@@ -256,11 +341,16 @@ function packageRootOf(resolvedFile) {
 export function pluginMithrilLynx(options = {}) {
 	const targetSdkVersion = options.targetSdkVersion ?? "3.5";
 	const hmr = options.hmr ?? false;
+	// `true` (default): in-bundle client over Wi-Fi via CDP Page.reload (see
+	// src/dev-reload-client.js) — no adb. `"devtool"`: 0.0.8's adb/CDP
+	// Page.reload path (fallback for viewers without the in-bundle CDP bridge).
+	// `false`: off.
 	const liveReload = options.liveReload ?? true;
+	const useDevtoolReload = liveReload === "devtool";
 
 	// Filled in by modifyBundlerChain below with "<entry>.bundle" for every
 	// configured entry, so a reload prefers the session actually serving this
-	// app over whichever Lynx session happens to be newest.
+	// app over whichever Lynx session happens to be newest (devtool mode only).
 	const bundleHints = new Set();
 
 	return {
@@ -276,9 +366,10 @@ export function pluginMithrilLynx(options = {}) {
 			// 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) -- real HMR
-			// can't reach this framework's app code regardless of how reload
-			// itself is triggered (see reloadViaDevtool() above), so leaving it
-			// on only adds that error noise for no benefit.
+			// can't reach this framework's app code regardless of whether the
+			// reload strategy is in-bundle (CDP Page.reload) or devtool (Node
+			// process, CDP Page.reload), so leaving it on only adds error noise
+			// for no benefit.
 			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
@@ -291,12 +382,12 @@ export function pluginMithrilLynx(options = {}) {
 				order: "post",
 			});
 
-			// Live reload itself: on every successful dev rebuild (skipping the
-			// first, which is the initial build rather than an edit), find the
-			// running Lynx session and CDP-reload it in place. See the block
-			// above reloadViaDevtool() for why this runs from here (the Node
-			// dev-server process) instead of from a chunk bundled into the app.
-			if (liveReload) {
+			// Live reload (devtool strategy only): on every successful dev rebuild
+			// (skipping the first), find the running Lynx session over adb and
+			// CDP-reload it in place. The default in-bundle strategy needs none of
+			// this — its client (injected below into a synthetic background chunk)
+			// drives the reload itself via CDP Page.reload.
+			if (useDevtoolReload) {
 				api.onAfterDevCompile(async ({ isFirstCompile, stats }) => {
 					if (isFirstCompile || stats.hasErrors()) return;
 					let reloaded = false;
@@ -319,7 +410,7 @@ export function pluginMithrilLynx(options = {}) {
 				api.onCloseDevServer?.(closeDevtoolTransport);
 			}
 
-			api.modifyBundlerChain((chain) => {
+			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
@@ -391,12 +482,33 @@ export function pluginMithrilLynx(options = {}) {
 					const bgAsset = `.rspeedy/${name}/background.js`;
 					const mtAsset = `.rspeedy/${name}/main-thread.js`;
 					const hasBackground = bgSource != null;
+					// In dev with the in-bundle reload client, always materialize a
+					// background chunk — even for an app with no background.ts of its
+					// own — so the dev-reload client has somewhere to run. In
+					// production, or when the reload is driven from the Node process
+					// (devtool mode), keep the original behavior exactly (no
+					// background chunk at all when the app doesn't use one).
+					const includeBackground = hasBackground || (isDev && liveReload === true);
 
 					// 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) {
+						// The dev-reload client is imported by its resolved absolute path
+						// (plus the query string it 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 in
+						// 0.0.7.
+						const bgImports = isDev && liveReload === true
+							? [
+									`${DEV_RELOAD_CLIENT_PATH}?${createDevReloadClientQuery(api, environment, name)}`,
+									...(hasBackground ? [bgSource] : []),
+							]
+							: bgSource;
 						chain.entry(bgEntry).add({
-							import: bgSource,
+							import: bgImports,
 							filename: bgAsset,
 						});
 					}
@@ -411,7 +523,7 @@ 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: [],
@@ -420,10 +532,11 @@ export function pluginMithrilLynx(options = {}) {
 
 					// The bundle this entry produces is always "<name>.bundle"
 					// (the filename above), and a loaded session's URL ends with
-					// it — that is what lets a reload pick out this app's session.
+					// it — that is what lets a devtool-mode reload pick out this
+					// app's session.
 					bundleHints.add(`${name}.bundle`);
 
-					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,261 @@
+// 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 triggers an in-place reload of the current page.
+//
+// Mechanism: CDP `Page.reload` via the DevTool native module
+// (`NativeModules.LynxDevToolSetModule.invokeCdp`) — the same mechanism
+// Rspeedy's own official live-reload client uses
+// (`@lynx-js/webpack-dev-transport/lib/client/reloadApp.js`). It reloads the
+// CURRENT page in place (no new Activity on the back stack) and it is invoked
+// from inside the bundle itself, so the only network hop is the WebSocket the
+// client runs on: Wi-Fi only, no adb, no cable.
+//
+// Why not the alternatives (each verified on-device):
+// - `lynx.reload({})` (v0.0.9's original mechanism): on the device's engine it
+//   re-executes the main-thread bundle against the live session, but the
+//   runtime helpers `removeComponents`/`updatePage` are not re-injected, so
+//   the render crashes with two TypeErrors (captured via lynx-devtool) and the
+//   background chunk never re-runs — the socket dies and later builds are
+//   silently ignored.
+// - `ExplorerModule.openSchema(url)` (0.0.7's mechanism): real navigation —
+//   Lynx Go starts a NEW LynxViewShellActivity every time and never finishes
+//   the one it replaces, so Back steps through one frozen snapshot per reload.
+// - `lynx.fetchBundle(url)` + `lynx.loadScript(sectionName, {bundleName})`:
+//   in lynx-core these are the lazy-bundle path (`LazyBundleLoader` /
+//   `LoadCustomSectionScript`) — they load a customSection of a SEPARATE
+//   lazily-fetched bundle, not the page's own main-thread/Lepus template, so
+//   they cannot re-render the current page.
+//
+// The reload passes a cache-busted `url` (`?t=<ts>`) because Lynx keys both
+// its HTTP layer and its bytecode cache by URL: measured on-device in 0.0.8,
+// a `Page.reload` without a changed URL re-runs the PREVIOUS bundle
+// byte-for-byte even with `ignoreCache:true` (see `cacheBustedUrl()` in
+// plugin.js).
+//
+// This client runs on the background/JS thread (where WebSocket + the
+// `lynx`/`NativeModules` globals are available), is only ever imported in dev
+// builds (see plugin.js's synthetic background chunk), and reads its config
+// from a resource query string injected at build time.
+
+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"];
+
+/**
+ * Appends a unique query parameter to a bundle URL. Lynx keys both the HTTP
+ * layer and its bytecode cache by URL, so `Page.reload` with the SAME URL
+ * re-runs the previous bundle byte-for-byte even with `ignoreCache: true`
+ * (measured on-device in 0.0.8). Changing the URL is what actually forces a
+ * fresh fetch — same reasoning as `cacheBustedUrl()` in plugin.js.
+ *
+ * Returns undefined for anything that isn't an http(s) URL, so the caller can
+ * fall back to letting Page.reload use its existing URL.
+ */
+function cacheBustedUrl(url, now = Date.now()) {
+	if (typeof url !== "string" || !/^https?:\/\//i.test(url)) return undefined;
+	const [base, query = ""] = url.split("?");
+	const params = new URLSearchParams(query);
+	params.set("t", String(now));
+	return `${base}?${params.toString()}`;
+}
+
+let currentHash;
+let initialBuild = true;
+let socket;
+// Reloading the current page — including re-executing this very module from
+// scratch would naturally replace this stale instance's socket with a fresh
+// one, except the OLD connection is otherwise left open: confirmed on-device
+// (0.0.7) that every earlier reload's socket stays alive and keeps receiving
+// server broadcasts, so a build a few reloads in fires the reload several
+// times at once (one call per still-open stale socket), and the resulting
+// reloads race. 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. Same lifecycle bug as 0.0.7, identical fix.
+let reloading = false;
+
+console.info(
+	"[mithril-lynx] LynxDevToolSetModule.invokeCdp:",
+	typeof NativeModules !== "undefined" && typeof NativeModules.LynxDevToolSetModule?.invokeCdp,
+	"| lynx.reload:",
+	typeof lynx !== "undefined" && typeof lynx?.reload,
+	"| ExplorerModule.openSchema:",
+	typeof NativeModules !== "undefined" && typeof NativeModules.ExplorerModule?.openSchema,
+);
+
+function invokeCdpReload() {
+	// Mirrors @lynx-js/webpack-dev-transport/lib/client/reloadApp.js:
+	// Lynx Go exposes the DevTool CDP bridge under two module casings;
+	// either one accepts the Page.reload CDP message. Note the older
+	// casing binds "Page.reload" as a leading argument, like the official
+	// client does.
+	const upperCase = typeof NativeModules !== "undefined" ? NativeModules.LynxDevToolSetModule : undefined;
+	const lowerCase = typeof NativeModules !== "undefined" ? NativeModules.LynxDevtoolSetModule : undefined;
+	const invokeCdp =
+		(upperCase?.invokeCdp?.bind(upperCase)) ??
+		(typeof lowerCase?.invokeCdp === "function" ? lowerCase.invokeCdp.bind(lowerCase, "Page.reload") : undefined);
+	if (typeof invokeCdp !== "function") return false;
+
+	// Page.reload with the SAME URL re-runs the previous bundle (URL-keyed
+	// bytecode cache — measured in 0.0.8), so pass the cache-busted URL. If
+	// the URL is unusable for some reason, fall back to the bare CDP reload
+	// rather than skipping the reload entirely.
+	const params = { ignoreCache: true };
+	const url = cacheBustedUrl(bundleUrl);
+	if (url != null) params.url = url;
+
+	invokeCdp(
+		JSON.stringify({ method: "Page.reload", params }),
+		(data) => {
+			if (!data) return;
+			try {
+				const { error } = JSON.parse(data);
+				if (error) console.error("[mithril-lynx] Page.reload failed:", error.message);
+			} catch {
+				// response is not JSON — ignore
+			}
+		},
+	);
+	return true;
+}
+
+function reload() {
+	// Preferred: CDP Page.reload through the DevTool native module — the
+	// same mechanism Rspeedy's own live-reload client uses. Page.reload
+	// reloads the current page in place (no new Activity, no back-stack
+	// corruption — verified on-device in 0.0.8), and because it is invoked
+	// from inside the bundle it works over Wi-Fi alone.
+	const cdpModule =
+		(typeof NativeModules !== "undefined" && NativeModules.LynxDevToolSetModule?.invokeCdp) ||
+		(typeof NativeModules !== "undefined" && NativeModules.LynxDevtoolSetModule?.invokeCdp);
+	if (typeof cdpModule === "function") {
+		console.info("[mithril-lynx] Reloading in place via CDP Page.reload.");
+		reloading = true;
+		socket?.close();
+		invokeCdpReload();
+		return;
+	}
+
+	// Fallback: lynx.reload() reloads the current page in place — no new
+	// Activity, no back-stack corruption. `value` is the new init data for the
+	// page; pass {} to keep the same (no new initData), mirroring openSchema's
+	// full reload. The callback fires when the reload completes. NOTE: on the
+	// engine this project targets (reported 3.5 on-device), lynx.reload
+	// re-executes the main-thread bundle against the live session without
+	// re-injecting the runtime helpers removeComponents/updatePage, crashing
+	// with two TypeErrors and never re-running the background chunk — that is
+	// why CDP is preferred and lynx.reload stays only as a fallback for
+	// viewers/SDKs whose reload path is intact.
+	const reloadFn = typeof lynx !== "undefined" && typeof lynx?.reload === "function" ? lynx.reload : null;
+	if (reloadFn) {
+		console.info("[mithril-lynx] Reloading in place via lynx.reload().");
+		reloading = true;
+		socket?.close();
+		try {
+			reloadFn.call(lynx, {}, () => {
+				console.info("[mithril-lynx] Reload complete.");
+			});
+		} catch (error) {
+			console.error("[mithril-lynx] lynx.reload threw:", error);
+		}
+		return;
+	}
+
+	// Last resort: ExplorerModule.openSchema(url) — the 0.0.7 mechanism. Works
+	// over Wi-Fi too, but it is a real navigation and stacks a new
+	// LynxViewShellActivity per reload (Back then walks frozen snapshots). Kept
+	// only for viewers/SDKs where lynx.reload is unavailable.
+	const openSchema =
+		typeof NativeModules !== "undefined" && NativeModules.ExplorerModule?.openSchema;
+	if (typeof openSchema !== "function") {
+		console.warn(
+			"[mithril-lynx] Live reload unavailable: neither CDP invokeCdp, lynx.reload, nor ExplorerModule.openSchema was 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 via ExplorerModule.openSchema (fallback).");
+	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();