mithril-lynx 0.0.6 → 0.0.8

package/README.md

@@ -298,4 +298,29 @@ 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()` 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 })`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mithril-lynx",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "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,20 @@ 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. 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.
+   */
+  liveReload?: boolean;
 }
 
 /**

package/plugin.js

@@ -27,6 +27,202 @@ const PLUGIN_NAME = "mithril-lynx-template-webpack";
 const BACKGROUND_CANDIDATES = ["background.ts", "background.js"];
 const STYLE_CANDIDATES = ["style.css"];
 
+// ---------------------------------------------------------------------------
+// Live reload (dev only)
+//
+// How a rebuild reaches the device, and why it works this way:
+//
+// - 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.
+//
+// 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.
+//
+// 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.
+// ---------------------------------------------------------------------------
+
+/** 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);
@@ -59,12 +255,70 @@ function packageRootOf(resolvedFile) {
 
 export function pluginMithrilLynx(options = {}) {
 	const targetSdkVersion = options.targetSdkVersion ?? "3.5";
+	const hmr = options.hmr ?? false;
+	const liveReload = options.liveReload ?? true;
+
+	// 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.
+	const bundleHints = new Set();
 
 	return {
 		name: PLUGIN_NAME,
 		setup(api) {
 			// Keep the template plugin discoverable by Rspeedy's Lynx internals.
 			api.expose(Symbol.for("LynxTemplatePlugin"), { LynxTemplatePlugin });
+
+			// 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) -- 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.
+			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",
+			});
+
+			// 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) {
+				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) => {
 				// mithril-lynx's own src/lynx-mithril-shim.js deep-imports mithril's
 				// internal render/cachedAttrsIsStaticMap.js (and its emptyAttrs
@@ -164,6 +418,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.
+					bundleHints.add(`${name}.bundle`);
+
 					if (hasBackground) {
 						// Background chunks run in the JavaScript thread and need the
 						// Lynx runtime wrapper; main-thread chunks are encoded as lepus.