mithril-lynx 0.0.8 → 2.0.0

package/plugin.js

@@ -1,226 +1,84 @@
 // plugin.js
 //
-// Generalized version of lynx-examples/examples/vanilla/plugin.ts's
-// dual-bundle build pattern, published as a reusable Rsbuild/Rspeedy plugin
-// instead of being copy-pasted per app.
+// Rspeedy/Rsbuild plugin wiring the two-bundle build (main-thread/Lepus +
+// background/JS) for mithril-lynx-v2 apps. Adapted from mithril-lynx v1's
+// plugin.js — this file is build TOOLING, not the redraw/reload mechanism
+// that motivated the v2 rewrite (see mithril-lynx-v2-desde-cero.md §2: v1's
+// bugs lived in the shim/commit/reload layer, never here), so it is reused
+// with fixes rather than rewritten from nothing. Two real changes from v1:
 //
-// Convention: for each configured entry, the entry's import path names a
-// "main-thread" file. If a sibling "background.ts"/"background.js" exists
-// next to it, it is picked up automatically and compiled as a second Lynx
-// bundle chunk (the background/JS-thread bundle), while the main-thread file
-// is always compiled and encoded as lepus (main-thread/Lepus VM chunk).
+// 1. (F0.2 fix, the actual point of this file's existence in the plan)
+//    `RuntimeWrapperWebpackPlugin`'s `test` regex now also matches
+//    `.hot-update.js` chunks. v1's regex (`${name}/background\.js$`)
+//    matched the initial background ASSET path (nested under
+//    `.rspeedy/<name>/`, with a slash) but never the flat, double-
+//    underscore-named hot-update chunk (`<name>__background.<hash>.hot-
+//    update.js`) — confirmed with a plain regex test against both real
+//    filenames, not a guess. That gap is the entire reason v1 needed a
+//    runtime monkey-patch of `lynx.requireModuleAsync` in its dev-reload
+//    client; v2's client has no such patch (see src/dev-reload-client.js).
 //
-// This is pure multi-entry bundling, no AST transform of user code: apps
-// author two plain files (main-thread.ts + optional background.ts) and this
-// plugin wires them into the two Lynx bundle slots. See mithril-lynx's
-// project plan, Phase 2.
+// 2. Only ONE rendering mode exists (v2 plan §2 non-goals: no main-thread-
+//    owned/data-channel modes) — so there is no mode-detection logic here,
+//    `dev.hmr` is unconditionally on in dev, and every entry always gets a
+//    background chunk.
 
 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";
 
-const PLUGIN_NAME = "mithril-lynx-template-webpack";
-
-const BACKGROUND_CANDIDATES = ["background.ts", "background.js"];
+const PLUGIN_NAME = "mithril-lynx-v2-template-webpack";
 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;
-}
+const DEV_RELOAD_CLIENT_PATH = path.join(
+	path.dirname(fileURLToPath(import.meta.url)),
+	"src",
+	"dev-reload-client.js",
+);
 
-/**
- * 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 };
-}
+const DEV_TRANSPORT_NOOP_PATH = path.join(
+	path.dirname(fileURLToPath(import.meta.url)),
+	"src",
+	"dev-transport-noop.js",
+);
 
 /**
- * Reloads the running page in place. Returns true when a session was reloaded,
- * false when none was found (the caller logs that).
+ * Builds the query string the in-bundle dev-reload client reads its config
+ * from — unchanged from v1's version (build-tooling glue, not part of the
+ * bug this rewrite is about).
  */
-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"}).`,
+function createDevReloadClientQuery(api, environment, entryName) {
+	const config = environment.config ?? {};
+	const dev = config.dev ?? {};
+	const server = config.server ?? {};
+	const devServer = api.context.devServer ?? {};
+	const hostname = dev.client?.host || devServer.hostname || server.host || "";
+	const port = devServer.port ?? server.port ?? "";
+	const protocol = devServer.https ? "https" : "http";
+	const assetPrefix = (typeof dev.assetPrefix === "string" ? dev.assetPrefix : "/").replaceAll(
+		"<port>",
+		String(port),
 	);
-	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)}`;
+	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();
 }
 
 function findSibling(dir, candidates) {
@@ -231,18 +89,12 @@ function findSibling(dir, candidates) {
 	return null;
 }
 
-/**
- * Walks up from a resolved file to the root of the package that owns it,
- * verified by name rather than assumed from the layout — this package's
- * exports map deliberately doesn't expose ./package.json, so the usual
- * require.resolve("<pkg>/package.json") trick isn't available here.
- */
-function packageRootOf(resolvedFile) {
+function packageRootOf(resolvedFile, expectedName) {
 	let dir = path.dirname(resolvedFile);
 	for (let i = 0; i < 10; i++) {
 		try {
 			const pkg = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8"));
-			if (pkg.name === "mithril-lynx") return dir;
+			if (pkg.name === expectedName) return dir;
 		} catch {
 			// keep walking
 		}
@@ -253,125 +105,60 @@ function packageRootOf(resolvedFile) {
 	return null;
 }
 
-export function pluginMithrilLynx(options = {}) {
+export function pluginMithrilLynxV2(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.
+			// One mode only -> dev.hmr is unconditionally on in dev (v1 had to
+			// detect renderer-mode-vs-not here; v2 has no "not").
 			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 } }),
+				handler: (config, { mergeRsbuildConfig }) => mergeRsbuildConfig(config, { dev: { hmr: true } }),
 				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
-				// singleton). If the app's own `require("mithril")` resolves to a
-				// DIFFERENT physical copy of the package than the one mithril-lynx
-				// itself was installed/linked with — the norm for a `file:`-linked
-				// local package, whose own node_modules (built for ITS OWN tests)
-				// shadows Node's normal directory-walk resolution once linked — the
-				// two copies' emptyAttrs singletons differ. The shim then can't
-				// recognize the app's legitimately-reused empty-attrs object as
-				// such, and Mithril's own updateAttrs() misfires its "Don't reuse
-				// attrs object" warning on every plain `m(tag, null, ...)` element,
-				// every redraw. Force a single resolution by aliasing "mithril" to
-				// whatever copy the app itself resolves from its own project root.
-				try {
-					const appRequire = createRequire(path.join(process.cwd(), "package.json"));
-					// Resolve the PACKAGE DIRECTORY (not mithril's own main entry
-					// file) — a prefix alias needs "mithril/render/x" to rewrite to
-					// "<dir>/render/x", which only works aliased to a directory.
-					const mithrilDir = path.dirname(appRequire.resolve("mithril/package.json"));
-					chain.resolve.alias.set("mithril", mithrilDir);
-				} catch {
-					// App has no local "mithril" resolvable from its own root —
-					// leave resolution as-is rather than guessing.
-				}
+			// dev.hmr:true makes Rsbuild/Rspeedy inject its own HMR transport
+			// client (a second WebSocket to /rsbuild-hmr) alongside the
+			// in-bundle client above — re-alias it to a no-op so `module.hot`
+			// stays live without a competing channel (same fix v1 F2 made).
+			api.modifyBundlerChain({
+				handler: (chain, { isDev }) => {
+					if (!isDev) return;
+					chain.resolve.alias.set("@lynx-js/webpack-dev-transport/client", DEV_TRANSPORT_NOOP_PATH);
+				},
+				order: "post",
+			});
 
-				// Same class of problem, worse symptom: mithril-lynx itself keeps
-				// per-app state in module-level variables — the shim's rootWrapper/
-				// redraw/runRender, main-thread.js's latestData and its cross-thread
-				// handler maps, background.js's mirror of those. Two physical copies
-				// means two disconnected renderers: the app renders through one, and
-				// any LIBRARY that depends on mithril-lynx (a component library, say,
-				// resolving its own nested copy once linked) calls shim.redraw() on
-				// the other — whose `redraw` is still null. That's a silent no-op:
-				// no error, nothing logged, components simply never update. Confirmed
-				// on real hardware 2026-09-11 while building mithril-lynx-ui, where
-				// it read as "the animation just doesn't run".
+			api.modifyBundlerChain((chain, { isDev, environment }) => {
+				// Force a single resolved copy of "mithril-runtime" and
+				// "mithril-lynx-v2" — a `file:`-linked local package can
+				// otherwise resolve a second physical copy with its own
+				// module-level state (this exact class of bug bit v1 twice:
+				// mithril's emptyAttrs singleton, and mithril-lynx's own
+				// per-app render state — see mithril-lynx/plugin.js's
+				// comments for the on-device symptom).
 				try {
 					const appRequire = createRequire(path.join(process.cwd(), "package.json"));
-					const selfDir = packageRootOf(appRequire.resolve("mithril-lynx"));
-					if (selfDir != null) {
-						// The bare specifier has to point at the entry FILE: aliasing it
-						// to the directory would bypass this package's own exports map
-						// (which has no "main" to fall back on) and fail to resolve.
-						// The prefix alias then keeps subpaths — "mithril-lynx/main-thread"
-						// and friends, which hold state of their own — on that same copy.
-						chain.resolve.alias.set("mithril-lynx$", path.join(selfDir, "src", "lynx-mithril-shim.js"));
-						chain.resolve.alias.set("mithril-lynx", selfDir);
-					}
+					const mithrilDir = path.dirname(appRequire.resolve("mithril-runtime/package.json"));
+					chain.resolve.alias.set("mithril-runtime", mithrilDir);
 				} catch {
-					// App doesn't resolve mithril-lynx from its own root (it's being
-					// consumed some other way) — leave resolution alone.
+					// App has no local "mithril-runtime" resolvable from its own root.
 				}
+				// Note: v1 also force-aliased its OWN package name here (a
+				// second copy of mithril-lynx would mean two disconnected
+				// renderers with separate module-level state — see
+				// mithril-lynx/plugin.js's comment for the on-device
+				// symptom). v2's per-app state lives inside closures created
+				// by `renderApp()`/`setupRenderer()` calls, not module-level
+				// variables — same class of bug can't reappear the same way,
+				// so this dedup isn't reproduced here. Revisit if a
+				// multi-copy scenario (npm link, a component library
+				// nesting its own copy) turns up the same symptom in
+				// practice.
 
 				const rawEntries = Object.entries(chain.entryPoints.entries() ?? {});
 				chain.entryPoints.clear();
@@ -383,24 +170,25 @@ export function pluginMithrilLynx(options = {}) {
 					if (typeof mtSource !== "string") continue;
 
 					const dir = path.dirname(mtSource);
-					const bgSource = findSibling(dir, BACKGROUND_CANDIDATES);
+					const bgSource = findSibling(dir, ["background.ts", "background.js"]);
 					const cssSource = findSibling(dir, STYLE_CANDIDATES);
+					if (bgSource == null) {
+						throw new Error(
+							`[mithril-lynx-v2] entry "${name}": no sibling background.ts/background.js found next to ${mtSource}. ` +
+								"mithril-lynx-v2 has exactly one rendering mode and it always needs a background entry — see the plan's §2 non-goals.",
+						);
+					}
 
 					const bgEntry = `${name}__background`;
 					const mtEntry = `${name}__main-thread`;
 					const bgAsset = `.rspeedy/${name}/background.js`;
 					const mtAsset = `.rspeedy/${name}/main-thread.js`;
-					const hasBackground = bgSource != null;
 
-					// Each entry always has main-thread code and may opt into a
-					// background thread by adding a sibling background.ts file.
-					if (hasBackground) {
-						chain.entry(bgEntry).add({
-							import: bgSource,
-							filename: bgAsset,
-						});
-					}
+					const bgImports = isDev && liveReload
+						? [`${DEV_RELOAD_CLIENT_PATH}?${createDevReloadClientQuery(api, environment, name)}`, bgSource]
+						: bgSource;
 
+					chain.entry(bgEntry).add({ import: bgImports, filename: bgAsset });
 					chain.entry(mtEntry).add({
 						import: cssSource != null ? [mtSource, cssSource] : [mtSource],
 						filename: mtAsset,
@@ -411,31 +199,41 @@ export function pluginMithrilLynx(options = {}) {
 							...LynxTemplatePlugin.defaultOptions,
 							filename: `${name}.bundle`,
 							intermediate: `.rspeedy/${name}`,
-							chunks: hasBackground ? [bgEntry, mtEntry] : [mtEntry],
+							chunks: [bgEntry, mtEntry],
 							dsl: "react_nodiff",
 							targetSdkVersion,
 							cssPlugins: [],
 						},
 					]);
 
-					// 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.
-						chain.plugin(`runtime-wrapper-${name}`).use(
-							RuntimeWrapperWebpackPlugin,
-							[
-								{
-									targetSdkVersion,
-									test: new RegExp(`${name}/background\\.js$`),
-								},
-							],
-						);
-					}
+					// --- F0.2 fix: the actual change this plugin exists to make ---
+					// v1: `test: new RegExp(`${name}/background\\.js$`)` matches
+					// the initial asset (`.rspeedy/<name>/background.js`, a
+					// nested PATH using a slash) but never a hot-update chunk
+					// (`<bgEntry>.<hash>.hot-update.js` — a FLAT file named
+					// after the webpack chunk NAME, with a double underscore,
+					// no slash). Verified against both real filename shapes
+					// with a plain regex test, not a live build, before
+					// writing this — see the plan's §8 F0.2 entry. Requiring
+					// `${name}[_/]` scopes the match to just this entry's own
+					// chunks (so a multi-entry app's OTHER pages' background
+					// chunks aren't double-wrapped by this instance) while
+					// still excluding the main-thread/lepus asset, which
+					// never contains "background".
+					chain.plugin(`runtime-wrapper-${name}`).use(
+						RuntimeWrapperWebpackPlugin,
+						[
+							{
+								targetSdkVersion,
+								test: new RegExp(`(^|/)${name}[_/].*background.*\\.js$`),
+							},
+						],
+					);
+
+					console.info(
+						`[mithril-lynx-v2:build] entry="${name}" hmr=true liveReload=${liveReload} ` +
+							`bgEntry=${bgEntry} mtEntry=${mtEntry} targetSdk=${targetSdkVersion}`,
+					);
 				}
 
 				chain.plugin("encode").use(LynxEncodePlugin, []);
@@ -443,11 +241,6 @@ export function pluginMithrilLynx(options = {}) {
 				chain.plugin("before-encode").use({
 					apply(compiler) {
 						compiler.hooks.thisCompilation.tap(PLUGIN_NAME, (compilation) => {
-							// The default grouping only routes a chunk to lepus (main thread)
-							// when its asset carries `lynx:main-thread`. These hand-built
-							// entries don't, so main-thread JS lands in `manifest` and lepus
-							// stays empty. Re-map it here: background JS to manifest, the
-							// main-thread chunk to lepus. CSS is already grouped correctly.
 							const hooks = LynxTemplatePlugin.getLynxTemplatePluginHooks(compilation);
 							hooks.beforeEncode.tap(PLUGIN_NAME, (args) => {
 								const pageName = args.intermediate ? path.basename(args.intermediate) : "";
@@ -458,24 +251,14 @@ export function pluginMithrilLynx(options = {}) {
 
 								const backgroundAsset = compilation.getAsset(bgAsset);
 								const mainThreadAsset = compilation.getAsset(mtAsset);
-
 								if (!mainThreadAsset) return args;
 
 								args.encodeData.compilerOptions.targetSdkVersion = targetSdkVersion;
 								args.encodeData.compilerOptions.enableEventRefactor = true;
-
-								// Route tap/gesture events through the refactored main-thread
-								// path so `__AddEventListener` handlers fire. This page-config
-								// flag was dropped from `@lynx-js/config-rsbuild-plugin` 0.2.0's
-								// schema, so set it on the page config directly.
 								args.encodeData.sourceContent.config.enableEventHandleRefactor = true;
 
 								args.encodeData.manifest = backgroundAsset
-									? {
-										[backgroundAsset.name]: backgroundAsset.source
-											.source()
-											.toString(),
-									}
+									? { [backgroundAsset.name]: backgroundAsset.source.source().toString() }
 									: {};
 								args.encodeData.lepusCode = {
 									root: mainThreadAsset,

package/rstest.config.ts

@@ -0,0 +1,27 @@
+import { defineConfig } from "@rstest/core";
+
+export default defineConfig({
+	testEnvironment: "jsdom",
+	setupFiles: [
+		"./test/setup.ts",
+		"@lynx-js/testing-environment/env/rstest",
+	],
+	globals: true,
+	include: ["test/**/*.test.ts"],
+	tools: {
+		rspack: {
+			module: {
+				rules: [
+					// src/ is CommonJS-shaped in a "type": "module" package in a
+					// couple of places (none yet as of F1, kept for parity with
+					// v1's config in case a future file needs it) — see
+					// mithril-lynx/rstest.config.ts for the original rationale.
+					{
+						test: /\/src\/.*\.cjs$/,
+						type: "javascript/dynamic",
+					},
+				],
+			},
+		},
+	},
+});