mithril-lynx 0.0.9 → 2.0.0

package/plugin.js

@@ -1,19 +1,27 @@
 // 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";
@@ -23,95 +31,34 @@ 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)
-//
-// 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",
 );
 
+const DEV_TRANSPORT_NOOP_PATH = path.join(
+	path.dirname(fileURLToPath(import.meta.url)),
+	"src",
+	"dev-transport-noop.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`.
+ * from — unchanged from v1's version (build-tooling glue, not part of the
+ * bug this rewrite is about).
  */
 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),
@@ -134,180 +81,6 @@ function createDevReloadClientQuery(api, environment, entryName) {
 	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);
@@ -316,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
 		}
@@ -338,131 +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;
-	// `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,
 		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 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.
+			// 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 (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);
-			}
+			// 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",
+			});
 
 			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
-				// 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.
-				}
-
-				// 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".
+				// 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();
@@ -474,45 +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;
-					// 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) {
-						// 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,
-							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,
@@ -523,32 +199,41 @@ export function pluginMithrilLynx(options = {}) {
 							...LynxTemplatePlugin.defaultOptions,
 							filename: `${name}.bundle`,
 							intermediate: `.rspeedy/${name}`,
-							chunks: includeBackground ? [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 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.
-						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, []);
@@ -556,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) : "";
@@ -571,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,