mithril-lynx 2.6.2 → 3.0.0

package/ROUTE_CONTRACT_ANALYSIS.md

@@ -0,0 +1,224 @@
+# `mithril-lynx/route` — contract and parity analysis
+
+Date: 2026-09-25. Scope: `src/route.js` (mithril-lynx 3.0.0, unpublished;
+identical route code to 2.6.2) against Mithril 2.3.8's `api/router.js`, the
+official Lynx documentation (`lynxjs.org/llms-full.txt`, read in full for
+navigation topics), and its use in the `non-contact` production app.
+
+Every "Verified" claim below was checked by running code against the real
+`route.js` (a throwaway test through `@lynx-js/testing-environment`), not by
+reading it. Claims about Lynx come from the official docs and are cited by
+page.
+
+## 0. Status after the fixes (commit 63fbedd)
+
+Everything in section 4 marked ❌ or ⚠️ that isn't an intentional
+difference is fixed, each with a test in `test/route.test.ts` that fails on
+the previous `route.js`:
+
+| Item | Now |
+|---|---|
+| Redirect during a render throws | fixed — resolution deferred to a microtask, coalesced |
+| `:key` change doesn't remount | fixed — keyed fragment, as upstream |
+| `route.Link` runs lifecycle hooks twice | fixed — `censor` (upstream util) strips `key` + hooks |
+| `route.Link` ignores `preventDefault()` / `{ handleEvent }` | fixed (forwarded events now record `defaultPrevented`) |
+| `options.state` ignored | fixed — stored per entry, merged into params, restored by back/forward |
+| Param-name separator check missing | fixed — same `SyntaxError` as upstream |
+| `null` default route → TypeError from inside | now a clear `TypeError`; intentional (no URL to start from) |
+| `get()` returns the encoded path | fixed — decoded, as upstream |
+| `set()` is synchronous | now asynchronous, as upstream (**breaking**, documented in `ROUTE.md`) |
+| Android back button | `route.canGoBack()` + opt-in `route.listenBackButton()`; host recipe in `ROUTE.md` |
+
+Still open: deep links (5.2), the `non-contact` host integration (5.1),
+and a device check of the asynchronous `set()` and the back button.
+
+The rest of this document is the analysis as written before the fixes.
+
+## 1. Verdict
+
+- **The model is right.** Lynx has no browser History API and no
+  navigation in its core. ReactLynx's two documented routers use exactly the
+  same in-memory approach as `mithril-lynx/route` (React Router's
+  `MemoryRouter`, TanStack Router's `createMemoryHistory`).
+- **API parity with `m.route` is high but not complete:** 3 real bugs
+  (redirect during a render throws, a changed `:key` doesn't remount the
+  page, `route.Link` runs lifecycle hooks twice), 3 missing pieces
+  (`options.state`, `null` default route, param-name check) and 4 behavior
+  differences that aren't documented (section 4).
+- **The Lynx integration has gaps:** the Android back button isn't wired
+  (in `non-contact`, back most likely closes the app), deep links from the
+  host aren't supported, and `ROUTE.md` states two things about Lynx that
+  the docs contradict (section 5).
+
+## 2. How navigation works in Lynx
+
+From the official docs:
+
+| Topic | What Lynx provides | Source |
+|---|---|---|
+| Native navigation in the core | **None.** Native navigation is delegated to "app frameworks"; the 2025 roadmap listed "native navigation" as future app-level work. | `/guide/start/build-with-app-framework.md`, `/blog/lynx-open-source-roadmap-2025.md` |
+| Official app framework | **Sparkling** (TikTok): "scheme-driven multi-page routing". Each page is its own Lynx container; `open({ scheme: "hybrid://lynxview_page?bundle=…" })`, `navigate({ path, options: { params } })`, `close()` from `sparkling-navigation`. Params reach the page through initData/globalProps. | `/blog/lynx-open-source-roadmap-2026.md`, tiktok.github.io/sparkling (APIs → Navigation, Scheme) |
+| Routing inside a page (ReactLynx) | React Router v6 with `MemoryRouter`; TanStack Router with `createMemoryHistory` ("required due to browser History API limitations in Lynx"). Neither has a `<Link>` in Lynx: you navigate from `bindtap`. | `/react/routing/react-router.md`, `/react/routing/tanstack-router.md` |
+| Host → page data | `initData` at `LynxView.loadTemplate()`, updates via `updateData()`; `lynx.__globalProps` + `onGlobalPropsChanged`. | `/guide/use-data-from-host-platform.md`, `/api/lynx-api/lynx/lynx-global-props.md` |
+| Host → page events | `LynxView/LynxContext.sendGlobalEvent(name, params)` → JS `lynx.getJSModule("GlobalEventEmitter").addListener(name, …)`. | `/api/lynx-native-api/lynx-view/send-global-event.md`, `/guide/interaction/event-handling/event-propagation.md` |
+| Back button reaching JS | Only inside an `<overlay>`: `bindrequestclose` — "Callback when the back button is clicked" (Android, Desktop, Harmony; Lynx 3.5). No general back-button event. | `/api/elements/built-in/overlay.md` |
+
+So there are two navigation models on Lynx:
+
+1. **In-page routing** — one page, one LynxView; screens are swapped inside
+   it by a memory router. This is what ReactLynx's routers and
+   `mithril-lynx/route` do.
+2. **Multi-page native navigation** — one container per screen, a native
+   stack, a real system back gesture (Sparkling). Each page is a separate
+   bundle entry, and data travels as initData/globalProps.
+
+`mithril-lynx/route` implements model 1, the same one as ReactLynx. Model 2
+lives in the host app/framework, not in the JS router; mithril-lynx works
+inside such pages unchanged (each page is its own `renderApp()`).
+
+## 3. What `m.route` is (the reference)
+
+Mithril 2.3.8 `api/router.js`, 243 lines: `route(root, defaultRoute, routes)`,
+`route.set(path, data, options)`, `route.get()`, `route.param(key)`,
+`route.prefix`, `route.Link`, `route.SKIP`, route resolvers
+(`onmatch`/`render`), resolution deferred with `setTimeout` on `set` and
+`popstate`, and `history.state` merged into params.
+
+## 4. Parity table
+
+✅ same behavior · ⚠️ differs · ❌ missing or broken.
+
+### Setup — `route(…)`
+
+| Aspect | `m.route` | `mithril-lynx/route` | Status |
+|---|---|---|---|
+| Signature | `route(root, defaultRoute, routes)` | `route(defaultRoute, routes)` — no `root`; mounts through its own `renderApp()` | ⚠️ intentional, documented |
+| Routes must start with `/` | SyntaxError | same | ✅ |
+| Param-name separator check (`/:a:b`) | SyntaxError "Route parameter names must be separated with either '/', '.', or '-'." | **accepted** (verified) | ❌ missing check |
+| Default route must match a route | ReferenceError | same | ✅ |
+| `defaultRoute` may be `null` | allowed (skips the check) | **TypeError** "Cannot read properties of null" (verified) | ❌ |
+| Calling it again (re-registration) | re-registers and re-resolves the browser URL | re-resolves the **current** path, keeps history (HMR support) | ⚠️ intentional improvement, documented in code |
+| Teardown when the router unmounts | `RouterRoot.onremove` resets state | none (one `renderApp()` per app lifetime) | ⚠️ intentional |
+
+### Resolution
+
+| Aspect | `m.route` | `mithril-lynx/route` | Status |
+|---|---|---|---|
+| Timing | `set()` schedules resolution (`setTimeout`); several `set()`s in a row coalesce | **synchronous**: `get()` returns the new path right after `set()` (verified) | ⚠️ undocumented |
+| Redirect during a render (e.g. `route.set("/login")` in a page's `oninit`) | works (deferred) | **throws** "Node is currently being rendered to and thus is locked." (verified) | ❌ **bug** |
+| Resolvers: `onmatch` (sync or promise), `render`, `SKIP` fallthrough | yes | same | ✅ |
+| `route.set` while an `onmatch` is pending → forced `replace` | yes | same | ✅ |
+| `onmatch` rejection → `console.error` + fallback with replace | yes | same | ✅ |
+| Unmatched path → fallback with replace; unmatched default → Error | yes | same | ✅ |
+| Component fallback when `onmatch` returns nothing | `"div"` | `"view"` | ✅ (Lynx equivalent) |
+| Remount when the matched component stays but a `:key` param changes | yes — `Vnode(component, attrs.key, attrs)` wrapped in a fragment "to preserve existing key semantics" | **no** — same instance kept, state persists (verified) | ❌ **bug** |
+| Path decoding | whole path decoded before matching | params decoded (verified `"a b/c"`), but `get()` returns the encoded path `"/d/a%20b%2Fc"` (verified) | ⚠️ |
+| Query string → params (with `"true"`/`"false"` coercion) | yes | same (verified) | ✅ |
+
+### Navigation — `route.set / get / param`
+
+| Aspect | `m.route` | `mithril-lynx/route` | Status |
+|---|---|---|---|
+| `set(path, data)` interpolation via `buildPathname` | yes | same | ✅ |
+| `options.replace` | `replaceState` | overwrites the current history entry | ✅ |
+| `options.state` | stored in `history.state`, merged into params, restored on back/forward | **ignored** (verified) | ❌ missing |
+| `options.title` | passed to `pushState` (browsers mostly ignore it) | ignored | ✅ (no-op on Lynx is fine) |
+| `set()` before `route()` | `location.href = …` | throws a clear error | ⚠️ intentional, documented |
+| Same path pushed twice | two history entries | same (verified) | ✅ |
+| `get()` | current path | same (encoded, see above) | ✅/⚠️ |
+| `param(key)` / `param()` | yes | same | ✅ |
+| `prefix` | `"#!"`, used in URLs | `""`, no effect | ⚠️ intentional, documented |
+
+### `route.Link`
+
+| Aspect | `m.route` | `mithril-lynx/route` | Status |
+|---|---|---|---|
+| Default element | `a` | `view` | ✅ (Lynx equivalent) |
+| Trigger | `onclick` (+ modifier-key / non-left-click checks) | `ontap` | ✅ (Lynx equivalent) — apps porting `onclick` on a Link must rename it |
+| Lifecycle hooks and `key` in the Link's attrs | removed before rendering the child (`censor`: `key`, `oninit`, `oncreate`, `onbeforeupdate`, `onupdate`, `onbeforeremove`, `onremove`) | **passed to the child too**: `oncreate` ran **twice** (verified) | ❌ **bug** |
+| Handler returning `false` cancels navigation | yes | yes | ✅ |
+| Handler calling `preventDefault()` cancels navigation | yes (`e.defaultPrevented`) | no | ⚠️ |
+| EventListener object (`{ handleEvent }`) as handler | supported | not supported | ⚠️ |
+| `disabled` | no handler, `href` removed, `aria-disabled` | no handler; `disabled` passed through | ✅ |
+| `params` / `options` | yes | yes | ✅ |
+
+### Not in `m.route` (mithril-lynx additions)
+
+| Addition | Purpose | Status |
+|---|---|---|
+| `route.back()` / `route.forward()` returning `boolean` | walk the in-memory history (no browser back) | ✅ works; see 5.1 for the missing hardware-back wiring |
+| HMR re-registration keeps the current path and history | hot reload without losing the screen | ✅ used by `non-contact` (`route.set(route.get(), null, { replace: true })`) |
+
+## 5. Gaps against what Lynx and the host offer
+
+### 5.1 Android back button
+
+- `ROUTE.md` says "Lynx has no hardware/gesture back button exposed to JS".
+  That's incomplete: `<overlay>` has `bindrequestclose` (overlays only), and
+  any host can forward the back key to JS with `sendGlobalEvent` →
+  `GlobalEventEmitter` — `non-contact` already uses that exact channel for
+  its QR scanner (`NonContactScannerModule.kt` → `scanResult`).
+- **`non-contact`:** `MainActivity` is a plain `AppCompatActivity` with no
+  back handling. Android's default then finishes the activity, so pressing
+  back on "Países" or "Historial" **closes the app** instead of returning to
+  the dialer — confirmed on the device by the app's owner.
+- **Missing piece:** a documented, tested recipe (or a small helper) —
+  host intercepts back (`OnBackPressedCallback`), sends a global event, JS
+  calls `route.back()`, and if that returns `false` asks the host to finish
+  (a NativeModule method).
+
+### 5.2 Deep links / initial route from the host
+
+- `ROUTE.md` says "nothing external can set the initial path — it's always
+  `defaultRoute`". The host *can* pass data (`initData` on `loadTemplate`,
+  `updateData` later, `globalProps`); what's missing is support in `route`
+  for reading an initial path from it. `main-thread.js` already registers a
+  pass-through `processData`, so initData reaches the page.
+- **Open question:** how the background thread reads initData without
+  ReactLynx (ReactLynx keeps it in `lynx.__initData`); needs checking on a
+  device before designing the API.
+
+### 5.3 Multi-page native navigation
+
+Out of scope for the router by design (section 2). A Sparkling-style host
+can load several mithril-lynx pages; no change needed, but it isn't
+documented or tested.
+
+### 5.4 Page teardown log noise
+
+Navigating between screens logs a burst of
+`DestroyLayoutNodeBeforeRemoveFromParent` errors (non-fatal). It happens
+with 2.6.2 as well (64 lines on dialer → countries), so it isn't caused by
+the 3.0.0 changes. It comes from the renderer removing a whole screen
+subtree, not from `route.js` itself. Not investigated.
+
+## 6. Recommendations
+
+In priority order:
+
+1. **Fix the render-time redirect bug:** resolve `route.set()` outside the
+   current render (defer it, as upstream does), at least when called during
+   a render. Add a test with the `oninit` guard pattern.
+2. **Fix `route.Link`** to strip `key` and lifecycle hooks from the child's
+   attrs (upstream `censor` set); honor `e.defaultPrevented`.
+3. **Restore key semantics:** render the matched component as
+   `[m(component, attrs)]` so a changed `:key` param remounts it.
+4. **Implement `options.state`:** store it with each history entry, merge it
+   into params, and restore it on `back()`/`forward()`.
+5. **Small parity items:** param-name separator check, `null` default
+   route, and a decoded `route.get()` — or document them as deliberate.
+6. **Back button:** ship the host recipe (5.1), then fix `non-contact`
+   after confirming the current behavior on the device.
+7. **Deep links:** verify how initData is read on the background thread,
+   then add an opt-in initial path (e.g. `route(defaultRoute, routes,
+   { initialPath })`).
+8. **Correct `ROUTE.md`** (back button, deep links) and list the remaining
+   intentional differences in one place.
+
+## 7. Verification plan
+
+- Unit tests for items 1–5 through `@lynx-js/testing-environment`, following
+  `test/route.test.ts` (the probes used for this analysis can be turned into
+  them directly).
+- On a device: the render-time redirect, hardware back in `non-contact`
+  (before and after the fix), and a deep link via initData.

package/UPDATE_ANIMATION_GAP.md

@@ -0,0 +1,133 @@
+# Known gap: `<list update-animation="default">`
+
+**Status:** open. **Affects:** mithril-lynx 3.0.0 (the native `list` /
+`list-item` elements). **Severity:** do not use `update-animation` in
+production yet. Everything else about `<list>` is verified on a real device
+(see mithril-lynx-ui's `docs/native-papi/papi-07-list-redesign.md`).
+
+## Summary
+
+`update-animation="default"` asks native to animate inserts, removes and
+updates. Removing an item that is **on screen** has no correct handling in
+mithril-lynx yet:
+
+- if mithril-lynx detaches the removed item's element (which is what it does
+  without the animation, and what native needs there), **native crashes when
+  the removal animation ends** (SIGSEGV);
+- if mithril-lynx leaves it attached (what it does today on such lists, to
+  avoid the crash), **stale cells stay drawn over the list** and the removed
+  elements accumulate as orphan children of the list.
+
+Inserts and updates were not seen to misbehave; the problem is removals of
+items that are currently attached (on screen).
+
+## What mithril-lynx does today
+
+`src/list-runtime.js` tracks the list's `update-animation` attribute
+(`setUpdateAnimation()`, fed by `src/apply-patch.js`'s SetAttribute /
+RemoveAttribute cases). When it is `"default"`:
+
+- `detachRemoved()` skips detaching removed on-screen items (no crash);
+- a `console.warn` is logged once per assignment, pointing here.
+
+Without `update-animation`, removed on-screen items are detached right after
+the patch's `update-list-info` flush — the contract verified on the device
+(next section). Tests: `test/list.test.ts`, "a removed on-screen item is
+detached only after the patch's update-list-info flush" and "with
+update-animation on, a removed on-screen item is left attached".
+
+## Evidence (real device)
+
+**Setup:** Samsung SM-A075M, Android 16, Lynx Go 2026.06.06
+(`com.funcs.io.lynx.go`), mithril-lynx 3.0.0 (local), `non-contact`'s
+country picker migrated to `list`, with sticky letter headers
+(`full-span` + `sticky-top` + `reuse-identifier="header"`) and lab
+attributes on the list. The bundle came from `rspeedy dev` over
+`adb reverse tcp:3000 tcp:3000`, opened with `agent-lynx open`.
+
+**Action:** type `a`, `r`, `g` in the search box (each keystroke filters ~250
+rows down, removing many on-screen items), then delete the text again
+(re-inserting them).
+
+What native does with a removed on-screen item, per strategy:
+
+| Strategy for a removed on-screen item | Without `update-animation` | With `update-animation="default"` |
+|---|---|---|
+| Detach it before the patch's flush | **Crash** — SIGSEGV right after `[List] Fail to erase item holder at pos = 73` | not tried (already crashes without) |
+| Detach it right after the patch's flush (**current default**) | **Correct** — renders fine, only the visible items stay attached (12–14), no duplicates | **Crash** — SIGSEGV right after `Basic Animation End` |
+| Never detach it (**current behavior with the animation**) | Renders fine, but removed elements stay as orphan children of the list and grow with each filter (57, then 125, with duplicated `item-key`s) | **Stale cells** drawn over the real ones (overlapping rows, persisting seconds later); 61 attached elements, duplicated `item-key`s: AD, AF, AL, AM, AO, AR, AZ, DZ, MG, h-M |
+
+Relevant log lines of the animation crash (`adb logcat`, same run):
+
+```
+I lynx : [List] DefaultListAdapter::BindItemHolder: enqueue component before render with item_key = AZ ...
+W lynx : FiberElement::FlushActionsAsRoot maybe from a wrong parent, this tag:list-item
+I lynx : SendCustomEvent event name:layoutcomplete tag:87
+I lynx : Basic Animation End.
+F libc : Fatal signal 11 (SIGSEGV), code 1 (SEGV_MAPERR), fault addr 0x3320332e31344c32
+```
+
+The backtrace is inside `liblynx.so` with no symbols.
+
+Other facts established on the device, true with or without the animation:
+
+- Native **never calls `enqueueComponent`** for items removed through
+  `update-list-info` (instrumented: 9 on-screen items removed, 0 enqueues).
+- Native logs `[List] Fail to erase item holder at pos = N` (non-fatal)
+  during bulk removals, whether or not mithril-lynx detaches anything.
+
+## How ReactLynx handles removals (for comparison)
+
+Read from `@lynx-js/react` 0.126.1:
+
+- **Snapshot runtime** (`runtime/lib/snapshot/snapshot/snapshot.js`,
+  `removeChild` on a list holder): records the removal for
+  `update-list-info` and **never calls `__RemoveElement`**.
+- **Element-template runtime** (`runtime/lib/element-template/runtime/patch.js`,
+  `removeTypedListItem` → `releaseRemovedSubtreeHandles`): drops the item from
+  its state and releases JS handles, **without detaching** it natively.
+
+So ReactLynx takes the "never detach" row. Whether a ReactLynx app shows the
+same stale cells / orphan growth with `update-animation` on this device has
+**not been tested** — that is the first thing to check (below).
+
+## Hypotheses (unverified)
+
+1. Native owns the removed cell until its removal animation finishes, then
+   releases it itself; detaching the element earlier frees memory the
+   animation still uses (fits the crash right after `Basic Animation End`).
+2. The stale cells in the "never detach" row may come from the orphan
+   elements still being children of the list element, so they take part in
+   the list's layout/render after the animation. ReactLynx may avoid this
+   through something mithril-lynx doesn't do (e.g. item-holder bookkeeping
+   specific to its runtimes), or may have the same problem.
+3. A detach deferred until after the animation (not after the flush) could
+   be safe — but mithril-lynx gets no signal for "animation ended"
+   (`Basic Animation End` is only a native log line), and a timer on the
+   main thread is unverified.
+
+## Next steps to close the gap
+
+1. **Baseline with ReactLynx:** build a minimal ReactLynx page with the same
+   filter pattern (`<list update-animation="default">`, keyed items, bulk
+   removals) and run it on the same device. Check for stale cells, orphan
+   growth (`DOM.getDocument` via `agent-lynx cdp`) and crashes. If ReactLynx
+   is also broken, report it upstream and keep this limitation documented.
+2. **If ReactLynx works:** diff the exact PAPI call sequence (both runtimes
+   log list callbacks behind `__ALOG__`; mithril-lynx can be instrumented the
+   same way) to find what native needs that mithril-lynx doesn't send.
+3. **Look for a completion signal:** check whether `layoutcomplete` (or any
+   other list event) fires after the removal animation, and whether a
+   deferred detach from that event is safe.
+4. **Acceptance:** the same filter stress on the device with
+   `update-animation="default"` — no crash, no stale cells, attached children
+   equal to the visible items, no duplicated `item-key`s. Then remove the
+   `animatesUpdates` branch and the warning, and turn the second test above
+   into a regular removal test.
+
+## Guidance until then
+
+- Don't set `update-animation` on lists that can remove on-screen items
+  (filtering, deleting rows, replacing data).
+- A list that only appends (a feed with "load more") is not affected by this
+  gap, but was not verified with the animation either.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mithril-lynx",
-  "version": "2.6.2",
+  "version": "3.0.0",
   "description": "Mithril.js on Lynx: real mithril/render/render.js driven through a Lynx-backed fake DOM, with an explicit single commit hook (no conditional global flush) and three reload modes (data-light, structural-light, full). A complete rewrite of the previous mithril-lynx (0.0.x).",
   "license": "MIT",
   "type": "module",
@@ -32,14 +32,6 @@
     "./testing": {
       "types": "./src/testing.d.ts",
       "default": "./src/testing.js"
-    },
-    "./list-support": {
-      "types": "./src/list-support.d.ts",
-      "default": "./src/list-support.js"
-    },
-    "./list-cell": {
-      "types": "./src/list-cell.d.ts",
-      "default": "./src/list-cell.js"
     }
   },
   "scripts": {

package/plugin.js

@@ -52,6 +52,10 @@ const DEV_TRANSPORT_NOOP_PATH = path.join(
  * 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).
+ * @param {Object} api - The Rsbuild plugin API.
+ * @param {Object} environment - The current build environment.
+ * @param {string} entryName - The entry (page) name.
+ * @returns {string} The query string, without the leading `?`.
  */
 function createDevReloadClientQuery(api, environment, entryName) {
 	const config = environment.config ?? {};
@@ -83,6 +87,12 @@ function createDevReloadClientQuery(api, environment, entryName) {
 	return params.toString();
 }
 
+/**
+ * Finds the first existing file among `candidates` in `dir`.
+ * @param {string} dir - The directory to search.
+ * @param {string[]} candidates - File names in priority order.
+ * @returns {string|null} The full path of the first match, or `null`.
+ */
 function findSibling(dir, candidates) {
 	for (const name of candidates) {
 		const candidate = path.join(dir, name);
@@ -91,6 +101,12 @@ function findSibling(dir, candidates) {
 	return null;
 }
 
+/**
+ * Walks up from a resolved file to the root of the named package.
+ * @param {string} resolvedFile - A file inside the package.
+ * @param {string} expectedName - The package `name` to look for.
+ * @returns {string|null} The package root directory, or `null` when not found within 10 levels.
+ */
 function packageRootOf(resolvedFile, expectedName) {
 	let dir = path.dirname(resolvedFile);
 	for (let i = 0; i < 10; i++) {
@@ -107,12 +123,24 @@ function packageRootOf(resolvedFile, expectedName) {
 	return null;
 }
 
+/**
+ * Creates the Rsbuild plugin that builds a mithril-lynx app's background and main-thread bundles.
+ * @param {Object} [options] - Plugin options.
+ * @param {string} [options.targetSdkVersion="3.5"] - Lynx target SDK version.
+ * @param {boolean} [options.liveReload=true] - Whether to inject the dev live-reload client in dev builds.
+ * @returns {{name: string, setup: (api: Object) => void}} The Rsbuild plugin.
+ */
 export function pluginMithrilLynx(options = {}) {
 	const targetSdkVersion = options.targetSdkVersion ?? "3.5";
 	const liveReload = options.liveReload ?? true;
 
 	return {
 		name: PLUGIN_NAME,
+		/**
+		 * @param {Object} api - The Rsbuild plugin API.
+		 * @returns {void}
+		 * @throws {Error} If an entry has no sibling `background.ts`/`background.js`.
+		 */
 		setup(api) {
 			api.expose(Symbol.for("LynxTemplatePlugin"), { LynxTemplatePlugin });
 
@@ -240,6 +268,11 @@ export function pluginMithrilLynx(options = {}) {
 				chain.plugin("encode").use(LynxEncodePlugin, []);
 
 				chain.plugin("before-encode").use({
+					/**
+					 * Taps the template plugin's `beforeEncode` hook to attach the background and main-thread assets.
+					 * @param {Object} compiler - The bundler compiler.
+					 * @returns {void}
+					 */
 					apply(compiler) {
 						compiler.hooks.thisCompilation.tap(PLUGIN_NAME, (compilation) => {
 							const hooks = LynxTemplatePlugin.getLynxTemplatePluginHooks(compilation);