mithril-lynx 2.6.0 → 3.0.0

package/ROUTE.md

@@ -1,11 +1,21 @@
 # `mithril-lynx/route`
 
-`m.route`, reimplemented for an environment with no URL bar and no `window.history` — Lynx pages aren't URL-addressable, so there's nothing for a real `popstate`-based router to hook into. This is not a limitation specific to Mithril: it's why React Router ships `MemoryRouter` and Vue Router ships `createMemoryHistory()` for exactly this kind of environment. `route.js` follows the same pattern — an in-memory array standing in for the browser's session history — while keeping the rest of the real `m.route` API shape, so route-using view code doesn't need to be rewritten, just re-imported.
+`m.route`, reimplemented for an environment with no URL bar and no `window.history`. Lynx pages aren't URL-addressable, so there's nothing for a `popstate`-based router to hook into — which is why ReactLynx's documented routers do the same thing: React Router with `MemoryRouter`, TanStack Router with `createMemoryHistory()`. `route.js` keeps history in an in-memory array and otherwise follows the real `m.route` API and behavior (Mithril 2.3.8), so route-using view code only needs to be re-imported. [`ROUTE_CONTRACT_ANALYSIS.md`](./ROUTE_CONTRACT_ANALYSIS.md) has the full parity table.
 
 ```js
 import route from "mithril-lynx/route";
 ```
 
+**Changed in 3.0.0:**
+- **Breaking:** `route.set()` is asynchronous, as in Mithril (see "Navigating").
+- A changed `:key` param recreates the page.
+- `options.state` is supported.
+- `route.Link` runs its lifecycle hooks once, honors `e.preventDefault()` and accepts a `{ handleEvent }` object.
+- `route.get()` returns the decoded path.
+- New: `route.canGoBack()` and `route.listenBackButton()` (see "Android back button").
+
+[`ROUTE_CONTRACT_ANALYSIS.md`](./ROUTE_CONTRACT_ANALYSIS.md) has the details.
+
 ## Setup
 
 ```js
@@ -15,7 +25,7 @@ route("/", {
 });
 ```
 
-Unlike real Mithril, this call takes no `root` DOM argument — this package has exactly one `renderApp()` for the app's whole lifetime (see the main README's architecture section), so `route(...)` calls it internally the first time a route resolves. `defaultRoute` (`"/"` above) is both the fallback for an unmatched path **and** the screen the app starts on — there's no browser URL to read an initial path from, so this is the Lynx equivalent of React Router's `initialEntries={["/"]}`.
+Unlike real Mithril, this call takes no `root` DOM argument — this package has exactly one `renderApp()` for the app's whole lifetime, so `route(...)` calls it internally the first time a route resolves. `defaultRoute` (`"/"` above) is required: it's both the fallback for an unmatched path **and** the screen the app starts on (there's no browser URL to read an initial path from — the Lynx equivalent of React Router's `initialEntries={["/"]}`).
 
 Route values can be a plain component, or a resolver object with `onmatch`/`render`, exactly like real Mithril:
 
@@ -29,24 +39,105 @@ route("/", {
 });
 ```
 
-`route.SKIP` falls through to the next matching route, same as upstream.
+`route.SKIP` falls through to the next matching route. Route templates follow upstream's rules: they must start with `/`, and params must be separated by `/`, `.` or `-` (`/:a:b` throws a `SyntaxError`). A `:key` param works as in Mithril: when it changes, the page is recreated with fresh state.
 
 ## Navigating
 
 ```js
-route.set("/detail/:id", { id: 42 });   // pushes a new history entry
-route.set("/detail/:id", { id: 42 }, { replace: true }); // overwrites the current one
-route.get();                             // current resolved path, e.g. "/detail/42"
-route.param("id");                       // "42" — or route.param() for the whole params object
+route.set("/detail/:id", { id: 42 });                     // pushes a new history entry
+route.set("/detail/:id", { id: 42 }, { replace: true });  // overwrites the current one
+route.set("/detail/:id", { id: 42 }, { state: { from: "home" } }); // state is merged into params
+route.get();        // current path, decoded, e.g. "/detail/42"
+route.param("id");  // "42" — or route.param() for the whole params object
+```
+
+**`route.set()` is asynchronous, like `m.route`:** the history changes right away, but the new screen resolves on the next microtask, and several navigations in the same tick resolve only the last one. `route.get()` still returns the previous path until then. This is what makes a redirect from inside a render safe (e.g. `route.set("/login")` in a page's `oninit`).
+
+`options.state` is stored with the history entry, merged into the route's params, and restored by `back()`/`forward()`. `options.title` is accepted and ignored.
+
+`route.back()` / `route.forward()` walk the same in-memory history. **These are not part of `m.route`** — there's no browser back button. Both return `true` when they navigated and `false` at the start/end of the stack, and `route.canGoBack()` tells whether `back()` would navigate, so a back affordance can enable itself.
+
+`route.prefix` exists only so code ported from a real Mithril app (`m.route.prefix = ""`) doesn't throw; it has no effect.
+
+## Android back button
+
+The system back button doesn't reach JS on its own (Lynx only exposes it inside an `<overlay>`, through `bindrequestclose`), so by default pressing back closes the app from any screen. `route.listenBackButton()` connects it, opt-in, through the same channel apps already use for host → JS events (`sendGlobalEvent` → `GlobalEventEmitter`):
+
+1. The host sends a global event when back is pressed, from an `OnBackPressedCallback` that starts **disabled**.
+2. JS calls `route.back()` when the event arrives.
+3. JS tells the host whether there's history to go back to (`onCanGoBackChange`); the host enables its callback only while there is. At the first screen the callback is disabled, so Android's default (closing the app) applies.
+
+Nothing blocks when this isn't set up: without the host part, the event never arrives; without the JS part, the callback stays disabled; without `GlobalEventEmitter`, it logs a warning and does nothing.
+
+**JS** (e.g. in `background.ts`, after `route(...)`):
+
+```js
+route.listenBackButton({
+  // eventName: "mithrilLynx:back",  // the default
+  onCanGoBackChange: (canGoBack) => NativeModules.NavModule?.setCanGoBack(canGoBack),
+});
+```
+
+It returns a function that stops listening (useful for HMR).
+
+**Android host** (Kotlin):
+
+```kotlin
+// MainActivity.kt
+import androidx.activity.OnBackPressedCallback
+import com.lynx.react.bridge.JavaOnlyArray
+
+class MainActivity : AppCompatActivity() {
+    companion object {
+        // Disabled until JS reports there is history to go back to.
+        var backCallback: OnBackPressedCallback? = null
+    }
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        val builder = LynxViewBuilder()
+        builder.registerModule("NavModule", NavModule::class.java)
+        val lynxView = builder.build(this)
+        // ... load the bundle, setContentView(lynxView)
+
+        val callback = object : OnBackPressedCallback(false) {
+            override fun handleOnBackPressed() {
+                lynxView.sendGlobalEvent("mithrilLynx:back", JavaOnlyArray())
+            }
+        }
+        onBackPressedDispatcher.addCallback(this, callback)
+        backCallback = callback
+    }
+
+    override fun onDestroy() {
+        backCallback = null
+        super.onDestroy()
+    }
+}
 ```
 
-`route.back()` / `route.forward()` walk the same in-memory history stack `route.set` writes to. **These do not exist on real Mithril** — they're new here because Lynx has no hardware/gesture "back" button exposed to JS (only app-lifecycle events like `onAppEnterBackground`, not navigation), so an app's own back affordance has to call something explicit. Wire a screen's back button to `route.back()`.
+```kotlin
+// NavModule.kt
+import android.content.Context
+import android.os.Handler
+import android.os.Looper
+import com.lynx.jsbridge.LynxMethod
+import com.lynx.jsbridge.LynxModule
+
+class NavModule(context: Context) : LynxModule(context) {
+    @LynxMethod
+    fun setCanGoBack(canGoBack: Boolean) {
+        // Called from the JS thread; the callback must be touched on the UI thread.
+        Handler(Looper.getMainLooper()).post { MainActivity.backCallback?.isEnabled = canGoBack }
+    }
+}
+```
 
-`route.prefix` exists only so app code defensively ported from a real Mithril app (`m.route.prefix = ""`) doesn't throw on import — there's no URL bar for a prefix to apply to, so setting it does nothing.
+Because the callback is only enabled while there's history, this also works with Android's predictive back gesture.
 
 ## Links
 
-Lynx has no `<a>`/`onclick` — `route.Link` renders a tap-driven element instead (the same shape ReactLynx's `useNavigate()` + `ontap` pattern and Vue Lynx's custom `RouterLink` slot use):
+Lynx has no `<a>`/`onclick` — `route.Link` renders a tap-driven element instead (the same shape as ReactLynx's `useNavigate()` + `bindtap` pattern):
 
 ```js
 m(route.Link, { href: "/detail/:id", params: { id: 42 } }, [
@@ -57,15 +148,19 @@ m(route.Link, { href: "/detail/:id", params: { id: 42 } }, [
 - `selector` picks the rendered tag (default `"view"`).
 - `params` interpolates into `href` the same way `route.set`'s second argument does.
 - `options` is passed straight through to the underlying `route.set` call (e.g. `{ replace: true }`).
-- `disabled: true` renders the element with no `ontap` at all, rather than an `ontap` that no-ops.
-- Your own `ontap` still runs first; returning `false` from it cancels the navigation (matches real Mithril's `m.route.Link` behavior).
+- `disabled: true` renders the element with no `ontap` at all.
+- Your own `ontap` runs first (a function or a `{ handleEvent }` object); returning `false` from it, or calling `e.preventDefault()`, cancels the navigation.
+- `key` and lifecycle hooks (`oncreate`, …) stay on the Link itself and aren't copied onto the rendered element, as in upstream.
 
 ## Known differences from real `m.route`
 
-- No `root` argument to the setup call (see "Setup" above) — architectural, not an oversight.
-- `route.back()`/`route.forward()` are new additions, not part of the real `m.route` API — see "Navigating" above for why Lynx needs them.
-- History is in-memory only: it does not survive a full app restart, and there is no deep-linking from outside the app (nothing external can set the initial path — it's always `defaultRoute`).
+- No `root` argument to the setup call, and `defaultRoute` is required (see "Setup").
+- `onclick` on a Link is `ontap` here (Lynx's tap event).
+- `back()`, `forward()`, `canGoBack()` and `listenBackButton()` are additions.
+- `route.prefix` has no effect; `options.title` is ignored.
+- History is in-memory only: it doesn't survive an app restart.
+- **Deep links aren't supported yet.** The host *can* pass data to a page (`initData` at `loadTemplate`, `updateData`, `globalProps`), but `route` doesn't read an initial path from it — the app always starts at `defaultRoute`. Tracked in `ROUTE_CONTRACT_ANALYSIS.md`.
 
 ## Device verification
 
-Navigation (Home → Detail with param interpolation, `route.Link` taps, `back()`/`forward()`), hot-reload while sitting on a non-default route (`module.hot.accept` + `route.set(route.get(), null, { replace: true })` to re-resolve after swapping a screen module), and confirmation that navigating away tears down the previous screen's nodes cleanly (via real patch ops — `Op.RemoveChild`/`Op.CreateElement`, not comparing CDP node ids, which are not stable identity across separate `DOM.getDocument()` calls) are all covered on a real connected Android device. See `.omo/plans/m-route-en-memoria.md` §4–§6 for the full research (how React Native/Vue-on-Lynx handle navigation) and the device evidence.
+Navigation (Home → Detail with param interpolation, `route.Link` taps, `back()`/`forward()`), hot-reload while sitting on a non-default route (`module.hot.accept` + `route.set(route.get(), null, { replace: true })` to re-resolve after swapping a screen module), and confirmation that navigating away tears down the previous screen's nodes cleanly (via real patch ops, not CDP node ids, which are not stable identity across separate `DOM.getDocument()` calls) were covered on a real Android device before 3.0.0. The asynchronous `set()`, the parity fixes and `listenBackButton()` are covered by unit tests (`test/route.test.ts`). The back button was checked on the same device with a real app (`non-contact`, a debug build wired as in "Android back button" above): back on the first screen closes the app, back on a pushed screen returns to the previous one, and an in-app `route.back()` updates `canGoBack` so the next system back closes the app.

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.