mithril-lynx 0.0.7 → 0.0.9

package/README.md

@@ -300,10 +300,45 @@ Tests run against `@lynx-js/testing-environment`'s jsdom-backed PAPI polyfill. T
 
 **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.
+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.
+
+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.7",
+  "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",
@@ -87,6 +87,7 @@
     "test": "rstest run"
   },
   "dependencies": {
+    "@lynx-js/devtool-connector": "^0.13.2",
     "@lynx-js/runtime-wrapper-webpack-plugin": "^0.2.4",
     "@lynx-js/template-webpack-plugin": "^0.16.0"
   },

package/plugin.d.ts

@@ -6,6 +6,26 @@ import type { RsbuildPlugin } from "@lynx-js/rspeedy";
 export interface PluginMithrilLynxOptions {
   /** Lynx engine target SDK version. Defaults to "3.5". */
   targetSdkVersion?: string;
+  /**
+   * Opt back into module-level HMR. Defaults to false, which the plugin forces
+   * because rspack's hot runtime can only patch modules on the background
+   * thread, while Mithril view code always runs on the main thread — so HMR
+   * adds hot-update error noise without ever being able to update anything.
+   */
+  hmr?: boolean;
+  /**
+   * Reload the running page after each successful dev rebuild. Defaults to
+   * 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 | "devtool";
 }
 
 /**

package/plugin.js

@@ -28,36 +28,90 @@ 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.
+// ---------------------------------------------------------------------------
+// Live reload (dev only)
+//
+// Two strategies, both triggered by a successful rebuild, picked by the
+// `liveReload` option:
+//
+// - `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).
+//
+// - `"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.
+//
+// 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 actually use.
+	// 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 — 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.
+	// 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),
@@ -65,18 +119,195 @@ function createDevReloadClientQuery(api, environment, entryName) {
 	const base = /^https?:\/\//.test(assetPrefix)
 		? assetPrefix
 		: `${protocol}://${hostname}${port ? `:${port}` : ""}${assetPrefix}`;
-	const bundleUrl = new URL(`${entryName}.bundle`, base.endsWith("/") ? base : `${base}/`).toString();
+	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": bundleUrl,
+		"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";
+
+let connectorPromise;
+let devtoolTransport;
+
+/**
+ * Lazily loads the DevTool connector. Kept lazy so `@lynx-js/devtool-connector`
+ * is only ever loaded by a dev rebuild, never by a production build.
+ */
+function getDevtoolConnector() {
+	if (!connectorPromise) {
+		connectorPromise = Promise.all([
+			import("@lynx-js/devtool-connector"),
+			import("@lynx-js/devtool-connector/transport"),
+		])
+			.then(([{ Connector }, { AndroidTransport }]) => {
+				devtoolTransport = new AndroidTransport();
+				return new Connector([devtoolTransport]);
+			})
+			.catch((error) => {
+				// Don't cache a rejection: the usual cause is the package not
+				// being installed yet, and the dev server outlives an
+				// `npm install`.
+				connectorPromise = undefined;
+				throw error;
+			});
+	}
+	return connectorPromise;
+}
+
+/** Last path segment of a URL, ignoring any query string or fragment. */
+function bundleBasename(url) {
+	if (typeof url !== "string") return "";
+	const withoutQuery = url.split("?")[0].split("#")[0];
+	const segments = withoutQuery.split("/");
+	return segments[segments.length - 1] || withoutQuery;
+}
+
+function isViewerShell(url) {
+	return bundleBasename(url) === VIEWER_SHELL_BUNDLE;
+}
+
+/**
+ * Adds a unique query parameter to a bundle URL.
+ *
+ * `Page.reload` on its own is not enough to pick up a rebuild: measured
+ * on-device, a reload without this re-fetched and re-ran the PREVIOUS bundle
+ * (the loaded template stayed byte-for-byte the old one, and the old text
+ * stayed on screen) even with `ignoreCache: true`. Both the HTTP layer and
+ * Lynx's own bytecode cache are keyed by URL, so changing the URL is what
+ * actually invalidates them. The session's own URL is unaffected — the DevTools
+ * reference notes it does not change after a reload, and that was confirmed
+ * here too.
+ *
+ * Returns undefined for anything that isn't an http(s) URL, in which case the
+ * caller lets Page.reload use the URL it already has (it rejects anything else).
+ */
+export 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()}`;
+}
+
+function matchesHint(url, hints) {
+	if (typeof url !== "string" || hints.length === 0) return false;
+	return hints.some((hint) => url.includes(hint));
+}
+
+/**
+ * Chooses which client/session to reload: `targets` is `[{ client, sessions }]`,
+ * returns `{ clientId, sessionId, url }` or null.
+ *
+ * Pure and exported so it can be tested without a device attached.
+ */
+export function pickReloadTarget(targets, { bundleHints = [] } = {}) {
+	const candidates = [];
+	for (const { client, sessions } of targets) {
+		for (const session of sessions ?? []) {
+			if (session?.type !== "lynx") continue;
+			if (isViewerShell(session.url)) continue;
+			candidates.push({ clientId: client.id, session });
+		}
+	}
+	if (candidates.length === 0) return null;
+
+	// Prefer the session actually serving one of this app's bundles over
+	// "whatever was opened most recently": with a second Lynx app, or a second
+	// attached device, the newest session need not be ours.
+	const preferred = candidates.filter((candidate) => matchesHint(candidate.session.url, bundleHints));
+	const pool = preferred.length > 0 ? preferred : candidates;
+
+	const latest = pool.reduce((a, b) => (b.session.session_id > a.session.session_id ? b : a));
+	return {
+		clientId: latest.clientId,
+		sessionId: latest.session.session_id,
+		url: latest.session.url,
+	};
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+async function listClientSessions(connector) {
+	const clients = await connector.listClients();
+	const targets = [];
+	for (const client of clients) {
+		try {
+			targets.push({ client, sessions: await connector.sendListSessionMessage(client.id) });
+		} catch {
+			// This client doesn't support session listing, or isn't ready yet.
+		}
+	}
+	return targets;
+}
+
+/**
+ * Finds a session worth reloading, retrying briefly: on the very first rebuild
+ * the DevTool client may not have registered with the device yet.
+ */
+async function findReloadTarget(bundleHints, { attempts = 3, delayMs = 400 } = {}) {
+	const connector = await getDevtoolConnector();
+	for (let attempt = 0; attempt < attempts; attempt++) {
+		const target = pickReloadTarget(await listClientSessions(connector), { bundleHints });
+		if (target) return { connector, target };
+		if (attempt < attempts - 1) await sleep(delayMs);
+	}
+	return { connector, target: null };
+}
+
+/**
+ * Reloads the running page in place. Returns true when a session was reloaded,
+ * false when none was found (the caller logs that).
+ */
+async function reloadViaDevtool(bundleHints) {
+	const { connector, target } = await findReloadTarget(bundleHints);
+	if (!target) return false;
+
+	const params = { ignoreCache: true };
+	// Without a changed URL the device replays its cached copy of the previous
+	// bundle — see cacheBustedUrl(). The session URL itself does not change.
+	const url = cacheBustedUrl(target.url);
+	if (url != null) params.url = url;
+
+	await connector.sendCDPMessage(target.clientId, target.sessionId, "Page.reload", params);
+	console.info(
+		`[mithril-lynx] Reloaded ${target.url || "(url unknown)"} (session ${target.sessionId}${url != null ? "" : ", no cache-busting: non-http url"}).`,
+	);
+	return true;
+}
+
+/** Releases the adb connection when the dev server goes away. */
+async function closeDevtoolTransport() {
+	const transport = devtoolTransport;
+	devtoolTransport = undefined;
+	connectorPromise = undefined;
+	await transport?.close?.();
+}
+
+/** Turns a connector failure into an actionable one-liner. */
+function describeReloadFailure(error) {
+	if (error?.code === "ERR_MODULE_NOT_FOUND" || /devtool-connector/.test(error?.message ?? "")) {
+		return "Live reload is off: @lynx-js/devtool-connector is not installed. Run `npm install @lynx-js/devtool-connector`, then restart the dev server.";
+	}
+	return `Live reload unavailable: ${error instanceof Error ? error.message : String(error)}`;
+}
+
 function findSibling(dir, candidates) {
 	for (const name of candidates) {
 		const candidate = path.join(dir, name);
@@ -110,6 +341,17 @@ 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 (devtool mode only).
+	const bundleHints = new Set();
 
 	return {
 		name: PLUGIN_NAME,
@@ -123,10 +365,11 @@ export function pluginMithrilLynx(options = {}) {
 			// 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.
+			// Force dev.hmr off (unless the app explicitly set it) -- real HMR
+			// 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
@@ -139,6 +382,34 @@ export function pluginMithrilLynx(options = {}) {
 				order: "post",
 			});
 
+			// 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;
+					try {
+						reloaded = await reloadViaDevtool([...bundleHints]);
+					} catch (error) {
+						console.warn(`[mithril-lynx] ${describeReloadFailure(error)}`);
+						return;
+					}
+					if (!reloaded) {
+						console.warn(
+							"[mithril-lynx] Live reload unavailable: no Lynx session found for this app. " +
+								"Is the device connected over adb with the page open in Lynx Go? Reload manually.",
+						);
+					}
+				});
+
+				// The transport owns adb port-forwards; don't let them outlive
+				// the dev server.
+				api.onCloseDevServer?.(closeDevtoolTransport);
+			}
+
 			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
@@ -211,27 +482,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;
+					// 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 (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
+						// 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: bgImports,
@@ -256,6 +530,12 @@ 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 devtool-mode reload pick out this
+					// app's session.
+					bundleHints.add(`${name}.bundle`);
+
 					if (includeBackground) {
 						// Background chunks run in the JavaScript thread and need the
 						// Lynx runtime wrapper; main-thread chunks are encoded as lepus.

package/src/dev-reload-client.js

@@ -3,7 +3,42 @@
 // 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.
+// 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 = {};
@@ -27,39 +62,143 @@ function socketURL(options) {
 
 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;
-// 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.
+// 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] ExplorerModule.openSchema:",
+	"[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: ExplorerModule.openSchema was not found.");
+		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.");
+	console.info("[mithril-lynx] Reloading updated bundle via ExplorerModule.openSchema (fallback).");
 	reloading = true;
 	socket?.close();
 	openSchema.call(NativeModules.ExplorerModule, bundleUrl);