mithril-lynx 0.0.1

package/CONTRACT.md

@@ -0,0 +1,151 @@
+# Mithril 2.3.8 `render/render.js` — Extracted Contract
+
+Source: `node_modules/mithril/render/render.js` (910 lines), mithril **2.3.8**.
+All line numbers cite that file unless prefixed with `hyperscript.js:` (which cites `node_modules/mithril/render/hyperscript.js`).
+
+---
+
+## a. Factory signature & how the render function is obtained
+
+- **Line 8**: `module.exports = function() {` — the module exports a **zero-argument factory function**.
+- The factory closes over module-level mutable state:
+  - `currentRedraw` (line 14) — the active `redraw` callback, captured by `EventDict` for auto-redraw.
+  - `currentRender` (line 15) — a per-render generation marker object (used by `delayedRemoval`).
+  - `currentDOM` (line 880) — the DOM node currently being rendered to (reentrancy lock).
+- The **render function is the closure returned by the factory**: lines 882–909, `return function(dom, vnodes, redraw) { ... }`.
+- Module dependencies (lines 3–6): `./vnode`, `./delayedRemoval`, `./domFor`, `./cachedAttrsIsStaticMap`.
+- The factory pattern means each call to `require("mithril/render/render")()` produces an **independent renderer instance** with its own `currentRedraw`/`currentDOM`/`currentRender` state.
+
+## b. Render function signature: `render(dom, vnodes, redraw)`
+
+Defined at **line 882**: `return function(dom, vnodes, redraw) {`
+
+| Param | Contract |
+|---|---|
+| `dom` | The DOM element to render into. **Line 883**: throws `TypeError("DOM element being rendered to does not exist.")` if falsy. **Lines 884–886**: throws `TypeError("Node is currently being rendered to and thus is locked.")` if `currentDOM != null && dom.contains(currentDOM)` (reentrancy guard). |
+| `vnodes` | A vnode or array of vnodes. **Line 899**: normalized via `Vnode.normalizeChildren(Array.isArray(vnodes) ? vnodes : [vnodes])`. |
+| `redraw` | Optional. **Line 894**: `currentRedraw = typeof redraw === "function" ? redraw : undefined`. Consumed by `EventDict.handleEvent` (lines 811–817) to auto-redraw after events. |
+
+Body sequence:
+1. **Line 898**: first render into a node clears it — `if (dom.vnodes == null) dom.textContent = ""`.
+2. **Line 900**: `updateNodes(dom, dom.vnodes, vnodes, hooks, null, namespace === "http://www.w3.org/1999/xhtml" ? undefined : namespace)` — diffs old (`dom.vnodes`) vs new (`vnodes`); the XHTML namespace is normalized to `undefined` (which enables the property-key path in `hasPropertyKey`).
+3. **Line 901**: `dom.vnodes = vnodes` — **prior vnodes are stored on the DOM node itself**.
+4. **Line 903**: focus restoration — if `document.activeElement` changed and the old active element still has `.focus`, it is refocused.
+5. **Line 904**: post-render hooks (`oncreate`/`onupdate`) flushed in order.
+6. **Lines 905–908**: `finally` restores `currentRedraw`/`currentDOM` to their previous values.
+
+## c. DOM surface accessed on the `dom` parameter
+
+All access goes through the `dom` node passed to `render()` (or its descendants). `getDocument(dom)` (lines 17–19) returns `dom.ownerDocument`.
+
+| API | Lines | Usage |
+|---|---|---|
+| `ownerDocument` | 18 | `getDocument()`; source of all document-level factories |
+| `createTextNode` | 76 | `createText` — `vnode.dom = getDocument(parent).createTextNode(vnode.children)` |
+| `createElement` / `createElementNS` | 120–122 | `createElement` for HTML, `createElementNS(ns, tag)` for svg/math; `{is: is}` third arg for custom elements |
+| `createDocumentFragment` | 96, 104, 551 | `createHTML` (96), `createFragment` (104), `moveDOM` for multi-node moves (551) |
+| `insertBefore` / `appendChild` | 558–561 | `insertDOM`: `insertBefore(dom, nextSibling)` if `nextSibling != null`, else `appendChild(dom)` |
+| `removeChild` | 610–617 | `removeDOM`: single `removeChild(vnode.dom)` or per-node via `domFor` for fragments |
+| `nodeValue` | 422 | `updateText` — `old.dom.nodeValue = vnode.children` |
+| `value` | 654–658, 666, 699, 703 | Read for same-value coercion skips (input/textarea/select/option); written via generic `vnode.dom[key] = value` (666); select late-attrs (699, 703) |
+| `checked` | 730 | Only as a key name in `isFormAttribute`; written via generic property path (666) |
+| `selectedIndex` | 685, 699, 702, 707 | `removeAttr` guard (685), `setLateSelectAttrs` (699, 702, 707) |
+| `className` | 672, 681, 693 | `setAttr` maps `className` → `"class"` attribute (672); `removeAttr` excludes it from property-null path (681) and maps to `"class"` (693) |
+| `setAttribute` | 665, 669–670, 672 | input `type` (665), boolean attrs (669–670), generic attrs (672) |
+| `removeAttribute` | 670, 693 | boolean-false (670), generic removal (693) |
+| `setAttributeNS` | 645 | `xlink:`-prefixed keys → `setAttributeNS("http://www.w3.org/1999/xlink", key.slice(6), value)` |
+| `style` | 646, 678, 747–787 | `updateStyle` dual-mode (see §f) |
+| `innerHTML` | 89, 92, 571 | `createHTML` (89 svg-wrapped, 92 plain), contenteditable sync (571) |
+| `textContent` | 898 | First-render clear |
+| `firstChild` | 90, 94, 98, 109 | `createHTML` unwrap (90, 94, 98), `createFragment` dom anchor (109) |
+| `parentNode` | 730 | `isFormAttribute` — `option` whose parent is the active element |
+| `contains` | 884 | Reentrancy lock check |
+| `namespaceURI` | 891 | Namespace detection for the diff call |
+| `focus` | 903 | Focus restoration |
+| `nextSibling` | domFor.js:12 | Fragment iteration in `domFor` |
+
+**Not used (verified by grep across the whole package):**
+- `getAttribute` — render.js only *writes* attributes (`setAttribute`/`removeAttribute`/`setAttributeNS`); it never reads them.
+- `nodeType` — appears nowhere in mithril. Do not rely on it in a reimplementation.
+
+## d. Prior-vnode storage & diffing of repeated `render()` calls
+
+**Storage**: old vnodes live on the DOM node as `dom.vnodes` — read at line 898 (first-render check) and 900 (diff input), written at line 901.
+
+**`updateNodes(parent, old, vnodes, hooks, nextSibling, ns)`** (lines 270–395):
+
+1. **Trivial cases** (271–273): `old === vnodes` or both null → no-op; `old` empty → create all; `vnodes` empty → remove all.
+2. **Keyed detection** (275–276): lists are keyed iff `old[0].key != null` / `vnodes[0].key != null` (first non-null node, 278–279).
+3. **Keyed/unkeyed mismatch** (280–282): remove all old + create all new.
+4. **Unkeyed diff** (283–299): walk the common length index-by-index; `o === v` or both null → skip; null old → create; null new → remove; else `updateNode`. Tails handled by `removeNodes` (298) / `createNodes` (299).
+5. **Keyed diff** (300–392), with the documented optimizations (comment block 184–268):
+   - **Bottom-up tail match** (305–312): while tail keys equal, update in place — identical tails are guaranteed part of the LIS, so no moves (tail optimization, comment 244–245).
+   - **Top-down head match** (314–320): same for the head.
+   - **Swaps & reversals** (322–336): two-node cross-swap fast path.
+   - **Bottom-up again** (338–345): re-check tails after head/tail consumption.
+   - **Leftovers** (346–347): remove remaining old or create remaining new.
+   - **LIS-based middle diff** (348–391): builds `oldIndices` (350–351), maps new keys → old indices via `getKeyMap` (352–365; impl 478–488), nulls matched old entries, removes unmatched old (367), creates all if nothing matched (368), then either moves non-LIS nodes (`makeLisIndices`, 370–383; impl 494–534, lifted from ivi) or a simple create loop when order was preserved (384–390).
+6. **`getNextSibling`** (536–541): next sibling is found by scanning the *old* list forward from `i+1` for a node with a `dom` — this is what makes top-down DOM insertion correct.
+7. **`moveDOM`** (544–556): moves single nodes directly; multi-node fragments are moved via a `createDocumentFragment` + `domFor` loop.
+
+**`updateNode`** (396–419): same `tag` + same `is` → in-place update (state/events carried over at 399–400; `shouldNotUpdate` short-circuit at 401, impl 852–878); otherwise `removeNode` + `createNode`. Per-tag updates: `updateText` (420–425), `updateHTML` (426–435), `updateFragment` (436–450), `updateElement` (451–461), `updateComponent` (462–477).
+
+## e. How `m()` (hyperscript) creates events & attrs
+
+**Hyperscript side** (`render/hyperscript.js`):
+- Selector parsing: `compileSelector` (hyperscript.js:21–42) — `#id`, `.class`, `[attr]`, `[attr=value]`; `class` → `className` (hyperscript.js:38); form-attribute keys (`value`/`checked`/`selectedIndex`/`selected`) mark the attrs object as non-static (hyperscript.js:17–19, 34).
+- `class` attr → `className` (hyperscript.js:54–57); `input[type]` reordered first (hyperscript.js:69–74, workaround for #2622); `vnode.is = attrs.is` (hyperscript.js:77).
+
+**Event side** (render.js):
+- **Dispatch rule** (line 644): any attr key starting with `on` (`key[0] === "o" && key[1] === "n"`) is routed to `updateEvent` (826–842), never to the DOM attribute path.
+- **`EventDict`** (800–823): a per-element event listener object, prototype `Object.create(null)` (804). Constructor captures `this._ = currentRedraw` (802). `handleEvent(ev)` (805–823):
+  - Looks up `this["on" + ev.type]` (806).
+  - Function handler → called with `ev.currentTarget` as `this` (808); object handler → `handler.handleEvent(ev)` (809).
+  - Auto-redraw: if `this._ != null` and `ev.redraw !== false`, calls the captured redraw (811–812); also after the handler's returned promise resolves (813–817).
+  - `return false` → `ev.preventDefault()` + `ev.stopPropagation()` (819–822).
+- **`updateEvent`** (826–842): `addEventListener(key.slice(2), vnode.events, false)` — the **EventDict object itself is the listener** (831, 839); handlers stored as `vnode.events[key]`; removal via `removeEventListener` (834). `vnode.events` is carried across updates (line 400).
+
+**Attribute side** (render.js):
+- **`setAttr`** (642–674) precedence: skip `key`/null-value/lifecycle (643) → `on*` events (644) → `xlink:` (645) → `style` (646) → **`hasPropertyKey`** (647–666) → attribute fallback (667–673).
+- **`hasPropertyKey`** (735–744): property assignment only when `ns === undefined` AND (custom element: tag contains `-` or `vnode.is`, OR key not in the browser-bug blacklist `href`/`list`/`form`/`width`/`height`) AND `key in vnode.dom`.
+- Property path (666): `vnode.dom[key] = value`, with `value` coercion guards (648–663: input/textarea/select/option same-value skip; file-input read-only warning at 661) and `input[type]` forced through `setAttribute` (665).
+- Attribute path (667–673): boolean → `setAttribute(key, "")` / `removeAttribute(key)`; else `setAttribute(key === "className" ? "class" : key, value)`.
+- **`removeAttr`** (675–695): property-null path excludes `className`, `title`, `value` (option/select edge), `input[type]`; else `removeAttribute` with `className` → `"class"` mapping.
+- **`updateAttrs`** (709–728): removals first (713–722), then sets (723–727); warns on reused attrs objects (714–716).
+- **`isFormAttribute`** (729–731): `value`/`checked`/`selectedIndex`/`selected` (with active-element/option-parent conditions) — these bypass the `old === value` skip so form state always syncs.
+
+## f. `updateStyle()` dual-mode (lines 747–787)
+
+`updateStyle(element, old, style)`:
+
+| Case | Lines | Behavior |
+|---|---|---|
+| `old === style` | 748–749 | No-op |
+| `style == null` | 750–752 | `element.style = ""` (clear) |
+| `typeof style !== "object"` | 753–755 | `element.style = style` (string passthrough) |
+| `old` missing/string, `style` object | 756–766 | Clear, then for each key: **`key.includes("-")` → `element.style.setProperty(key, String(value))`** (763); **else `element.style[key] = String(value)`** (764) |
+| Both objects | 767–786 | Remove stale keys first (772–777: `removeProperty` for dash-case, `= ""` for camelCase), then set changed keys (779–785: same dual-mode) |
+
+Key contract points:
+- **Dash-case keys** (`-` in the name) → `setProperty` / `removeProperty`; **camelCase keys** → direct `style[k]` assignment.
+- All values coerced with `String()` (763–764, 781).
+- Removal happens before setting (770–771) to avoid dash-case/camelCase aliasing bugs.
+
+## g. Version & packaging
+
+- **Version**: `2.3.8` (package.json `version` field).
+- **No `main` / `module` field** in package.json (verified — only `unpkg`/`jsdelivr`/`repository`/`license`/`scripts`/`devDependencies`). The package is consumed by **file-path require**: `require("mithril/render/render")` resolves directly to `node_modules/mithril/render/render.js`.
+- Entry points: `index.js` (browser bundle), `render.js` (top-level re-export of `render/render.js`), `hyperscript.js` (re-export of `render/hyperscript.js` + `trust`/`fragment`).
+- 2.3.8 is the latest mithril release on npm (as of this scaffold's dependency pin).
+
+---
+
+## Reimplementation checklist (what a Lynx port must honor)
+
+1. Factory `module.exports = function()` returning `function(dom, vnodes, redraw)` with per-instance `currentRedraw`/`currentRender`/`currentDOM` state.
+2. Store prior vnodes on the target node (`dom.vnodes`); first render clears via `textContent = ""`.
+3. Diff pipeline: trivial cases → keyed detection → unkeyed walk → keyed (tail/head/swaps/LIS) → leftover create/remove.
+4. DOM surface: `createTextNode`, `createElement(NS)`, `createDocumentFragment`, `insertBefore`/`appendChild`, `removeChild`, `nodeValue`, `value`, `checked`, `selectedIndex`, `className`, `setAttribute`/`removeAttribute`/`setAttributeNS`, `style`, `innerHTML`, `textContent`, `firstChild`, `parentNode`, `ownerDocument`, `namespaceURI`, `contains`, `focus`. **No `getAttribute`, no `nodeType`.**
+5. Events: `on*` keys → single `EventDict` object per element registered via `addEventListener`; `handleEvent` dispatches by `ev.type`, binds `this` to `ev.currentTarget`, auto-redraws, honors `return false`.
+6. Attrs: `hasPropertyKey` gate (property vs attribute), `className`→`class` mapping, boolean attrs, `xlink:` namespace, `value`/`checked`/`selectedIndex` form-attribute exceptions.
+7. Styles: dual-mode `updateStyle` — `setProperty` for `-` keys, `style[k] = v` for camelCase, `String()` coercion, remove-before-set.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 carlos-sweb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,227 @@
+# mithril-lynx
+
+Mithril.js rendered through [Lynx](https://lynxjs.org)'s Element PAPI — the core runtime layer of a Mithril-based alternative to [`@lynx-js/react`](https://lynxjs.org/react/).
+
+## What this package is
+
+`src/lynx-mithril-shim.js` is a contract-complete, line-by-line port of `mithril/render/render.js@2.3.8`: the exact same diff algorithm (`createNode`/`updateNodes`/`updateNode`/keyed-diff-with-LIS/etc.) as upstream Mithril, with every DOM call it makes redirected onto Lynx's Element PAPI (`__CreateView`, `__AppendElement`, `__SetAttribute`, `__SetInlineStyles`, `__AddEventListener`, ...) instead of the browser DOM. See `CONTRACT.md` for the exhaustive, reverse-engineered spec of exactly which DOM surface Mithril's renderer touches — that document is the reference this shim is built and validated against.
+
+`mithril` is a `peerDependency`, not a `dependency` — install it yourself (`mithril@2.3.8`) rather than relying on a copy `mithril-lynx` pulls in. The shim deep-imports mithril's own internal `emptyAttrs`/`cachedAttrsIsStaticMap` singletons (needed to correctly recognize mithril's own legitimately-reused empty attrs object); a second physical copy of `mithril` anywhere in the dependency graph breaks that recognition and produces a spurious `"Don't reuse attrs object"` console warning on every plain `m(tag, null, ...)` element, every redraw (confirmed and fixed on-device 2026-09-09 — see `DEVICE_VERIFICATION.md`). `mithril-lynx/plugin`'s `pluginMithrilLynx()` already forces a single resolution via a build-time alias, so apps using it don't need to do anything extra beyond installing `mithril` themselves.
+
+Everything in this README is tested against `@lynx-js/testing-environment`'s jsdom-backed PAPI simulation, not a real device — several capabilities (renderer mode, gestures, list Tier 2, refs) were built from reading real `@lynx-js/react` source as ground truth without ever calling the real native PAPI they call. See `DEVICE_VERIFICATION.md` for exactly which claims are still unconfirmed on real hardware and the plan to confirm them.
+
+This is part of a larger effort to bring Mithril to full functional parity with ReactLynx's dual-thread architecture, refs, gestures, list virtualization, and testing tooling — see the project plan for the full roadmap. Three rendering modes exist today:
+
+- **Main-thread-owned** (`mithril-lynx` + `mithril-lynx/main-thread` alone, no `background.ts`): the app renders directly on the main thread, synchronously, on first paint. Simplest option; no dual-bundle build needed.
+- **Data-channel mode** (`mithril-lynx/main-thread` + `mithril-lynx/background`, opt in by adding a sibling `background.ts` — see `mithril-lynx/plugin`): business-logic state lives on the background thread; only plain JSON data crosses the thread boundary, and the main thread's Mithril render turns it into UI. First paint waits one round trip for the background thread's initial push, in exchange for keeping business logic off the main thread.
+- **Renderer mode** (`mithril-lynx/renderer/main-thread` + `mithril-lynx/renderer/background`): Mithril's diff algorithm itself runs on the background thread, against a virtual (op-log-recording) tree; the main thread replays the ops against real elements and forwards real events back by node id. This is the closest analog to ReactLynx's default architecture — full reconciliation off the main thread, not just data pushes — at the cost of first paint waiting for the background thread's initial patch (same tradeoff as data-channel mode, one level deeper).
+
+## Usage — main-thread-owned
+
+```js
+import shim from "mithril-lynx";
+import m from "mithril";
+
+// The native engine unconditionally calls a global processData(initData)
+// on every __RenderPage/__UpdatePage — install a pass-through default
+// (mithril-lynx/main-thread does this for you in data-channel mode, but
+// this bare pattern doesn't go through that module).
+Object.assign(globalThis, { processData: (data) => data });
+
+const engine = lynx.getEngine();
+engine.addEventListener("__RenderPage", () => {
+  const page = __CreatePage("0", 0);
+  shim.renderToPage(page, m(MyComponent));
+});
+```
+
+Subsequent UI updates flow through `shim.redraw()` (called automatically by event handlers bound via Mithril's own `on*` attrs, since the shim ports Mithril's `EventDict`/redraw machinery verbatim) — **never plain `m.redraw()`**, which is a no-op in this shim-based architecture.
+
+## Usage — data-channel mode
+
+`main-thread.ts`:
+
+```js
+import { setupApp, getData, dispatchToBackground } from "mithril-lynx/main-thread";
+import m from "mithril";
+
+const Counter = {
+  view: () => m("text", { ontap: () => dispatchToBackground("increment") }, String(getData()?.count ?? 0)),
+};
+
+setupApp({ root: () => m(Counter) });
+```
+
+`background.ts` (sibling file — `mithril-lynx/plugin` picks it up automatically as a second bundle):
+
+```js
+import { setupBackground, getData, setData, setBackgroundEventHandler } from "mithril-lynx/background";
+
+setupBackground();
+setData({ count: 0 }, { shouldSyncToMainThread: false });
+setBackgroundEventHandler((handlerName) => {
+  if (handlerName === "increment") setData({ count: (getData().count ?? 0) + 1 });
+});
+```
+
+`root()` is called exactly once, on the first `__RenderPage`; every later update — from the engine's `__UpdatePage` or a `background.setData()` push — flows through the shim's own `redraw()`, re-invoking the component's `view()` (not `root()` again). See `mithril-lynx/test/data-channel.test.ts` for a complete worked example and the full cross-thread test. `mithril-app` (this project's own hello-world template) uses main-thread-owned mode instead — see its `src/{main-thread,index}.js` for that simpler pattern applied end to end.
+
+## Usage — renderer mode
+
+`main-thread.ts`:
+
+```js
+import { setupRenderer } from "mithril-lynx/renderer/main-thread";
+
+setupRenderer();
+```
+
+`background.ts`:
+
+```js
+import { renderApp, redraw } from "mithril-lynx/renderer/background";
+import m from "mithril";
+
+let count = 0;
+const Counter = {
+  view: () => m("text", { ontap: () => { count += 1; redraw(); } }, String(count)),
+};
+
+renderApp({ root: () => m(Counter) });
+```
+
+Unlike data-channel mode, `main-thread.ts` needs no app-specific code at all — `setupRenderer()` is generic; all app logic, including the Mithril component tree, lives in `background.ts`. Call `redraw()` (not `shim.redraw()`) after mutating state in a handler — it re-invokes the view and flushes the resulting patch to the main thread. See `mithril-lynx/test/renderer-ops.test.ts` (op-log assertions) and `mithril-lynx/test/renderer-integration.test.ts` (full round trip through real PAPI replay, including a tap forwarded from the main thread back to the background thread's handler) for worked examples.
+
+## Refs / native imperative bridge
+
+Mithril has no `useRef`/`ref` hook system — the idiomatic way to reach a real node is Mithril's own `oncreate(vnode)`/`onupdate(vnode)` lifecycle attrs, which hand you `vnode.dom` directly. Two helpers cover the two threads:
+
+- **Main-thread side** (`mithril-lynx/element`): `wrapElement(node)` wraps any node with a `_handle` (a real `LynxNodeWrapper`, or a raw result from `querySelector`) in ergonomic methods `render.js` itself never needs — `setStyleProperty(ies)`, `setAttribute` (mirrors the real wrapper's class/id/data-prefixed/generic special-casing), `querySelector(All)`, `animate`/`playAnimation`/`pauseAnimation`/`cancelAnimation`, and `invoke(method, params)` (wraps `__InvokeUIMethod`'s callback in a Promise).
+
+  ```js
+  import { wrapElement } from "mithril-lynx/element";
+
+  m("input", {
+    oncreate: (vnode) => wrapElement(vnode.dom).invoke("focus"),
+  });
+  ```
+
+  **Confirmed working on a real device** (see `DEVICE_VERIFICATION.md`): `invoke("boundingClientRect", {})` resolved with a real native response (`{code: 0, data: {top, left, width, height, ...}}`), confirming `__InvokeUIMethod`'s callback contract matches what this file assumes.
+
+- **Background-thread side** (`mithril-lynx/background`'s `createRef(selector)`): the background thread has no direct native handle, so imperative calls go through Lynx's existing `lynx.createSelectorQuery().select(selector).invoke({...}).exec()` bridge — the same primitive ReactLynx's own background-thread refs ultimately use.
+
+  ```js
+  import { createRef } from "mithril-lynx/background";
+
+  const input = createRef("#my-input");
+  await input.invoke("focus"); // resolves with success data, rejects with failure data
+  ```
+
+  **Confirmed working on a real device 2026-09-09** (see `DEVICE_VERIFICATION.md`): a background-thread `createRef(selector).invoke("boundingClientRect", {})` resolved with a real native response, round-tripped back to the main thread through the normal data channel and displayed there.
+
+**Known quirk, not a bug**: style patches sometimes carry a key with an empty-string value (e.g. `{ backgroundColor: "" }`) instead of omitting it entirely, when a non-dash-case style property is cleared after being set via plain assignment rather than `style.setProperty()`. This matches the real `LynxStyleProxy`'s exact behavior in main-thread-owned mode too (verified — not something renderer mode changed), and `__SetInlineStyles`/CSSOM treat an empty string as "clear this property," so it's functionally equivalent to an absent key.
+
+## Cross-thread function calls (worklet substitute)
+
+ReactLynx's Main Thread Scripting (worklets) exists to solve two different problems, and only one of them needs a compiler:
+
+- **A gesture/tap handler needs to run on the thread it's defined on** — under mithril-lynx's two-file convention, this needs *zero new mechanism*: a `main-thread:bindtap`-equivalent handler is just an ordinary function in `main-thread.ts`/`background.ts`, never mixed with the other thread's code to begin with.
+- **One thread needs to trigger a named action on the other thread outside the normal render/data cycle** — this genuinely can't cross a JS-engine boundary without either a compiler (to extract and ship a closure) or an explicit registry. `registerHandler`/`runOnMainThread`/`runOnBackground` (in `mithril-lynx/main-thread` and `mithril-lynx/background`) are that registry — call/return correlated, Promise-based:
+
+  ```js
+  // main-thread.ts
+  import { registerHandler } from "mithril-lynx/main-thread";
+  registerHandler("flashBackground", (color) => { /* ... */ });
+  ```
+  ```js
+  // background.ts
+  import { runOnMainThread } from "mithril-lynx/background";
+  await runOnMainThread("flashBackground", "red");
+  ```
+
+  This is equal *capability* to upstream's own `runOnMainThread`/`runOnBackground` (both are async serialized RPC under the hood there too, not real closure transfer) — only worse *ergonomics*, since there's no compiler to auto-extract an inline closure at the call site. Args and return values must be JSON-serializable, and handlers must be named and registered ahead of time, on the thread they run on.
+
+  **Explicitly rejected**: reconstructing a closure via `fn.toString()` + `new Function(...)` shipped across the wire, as a sugar layer over the registry. It breaks under any minifier/bundler that renames free identifiers, can't support real closures anyway (so it wouldn't actually improve on "write a named function"), and fails only in production builds, never in dev. Not revisited without re-litigating this tradeoff.
+
+## Gestures
+
+`mithril-lynx/gesture`'s `createGesture(node, options)` is a thin, same-thread wrapper over `__SetGestureDetector` — no cross-thread serialization, since gesture recognition and its callbacks all run on the main thread already. It DOES need a small amount of worklet machinery, though (see below) — native invokes gesture callbacks by looking them up in a registry, not by calling a function value directly, and `mithril-lynx` supplies a minimal, from-scratch registry for exactly this (`src/worklet-runtime.js`), not a dependency on `@lynx-js/react`'s own.
+
+```js
+import { createGesture, GestureType } from "mithril-lynx/gesture";
+
+m("view", {
+  oncreate: (vnode) => {
+    createGesture(vnode.dom, {
+      type: GestureType.PAN, // or the string "pan"
+      callbacks: {
+        onStart: () => { /* ... */ },
+        onUpdate: () => { /* ... */ },
+      },
+    });
+  },
+});
+```
+
+Each callback is actually invoked as `(event, controller) => {}` — `controller` is a native gesture-arena handle (`{__SetGestureState, __ConsumeGesture}`); most callbacks can ignore it and just take `event` (or no parameters at all, as above).
+
+`waitFor`/`simultaneousWith`/`continueWith` take arrays of *other* `createGesture()` return values, for gesture-arena composition (e.g. a pan that only starts after a tap gesture fails). If a callback needs to notify background-owned state, call `main-thread.js`'s `runOnBackground()` (previous section) from inside it — an explicit, opt-in cross-thread hop, not something gesture composition requires structurally.
+
+**Confirmed WORKING end-to-end on a real device 2026-09-09** (see `DEVICE_VERIFICATION.md` for the full story): a real `adb shell input swipe` across a `PAN`-gesture element drove its callbacks through start → update → end with zero errors. Getting there took three stacked fixes, in order: (1) gesture callbacks must be wrapped as worklet-ctx objects (`{_wkltId}`), not passed as plain functions — `createGesture()` does this internally via `src/worklet-runtime.js`, a small from-scratch worklet registry, transparent to callers; (2) the consuming app's `lynx.config.ts` must pass `{ enableNewGesture: true }` to `pluginLynxConfig()` — without it, native's entire gesture arena stays off and `__SetGestureDetector` calls are silently inert; (3) `worklet-runtime.js` must call callbacks positionally (`fn.bind(ctx)(...args)`), never via `Function.prototype.apply()` — the native `controller` argument throws under `apply()`'s argument marshalling specifically. (1) and (3) are internal to this package; (2) is a one-line addition an app using `mithril-lynx/gesture` must make itself.
+
+## Lists
+
+Two tiers, matching the real complexity spread in Lynx's own `list` examples:
+
+- **Tier 1 (prefer this)**: `<list>`/`<list-item>` need no code at all — they're just ordinary tags through the existing shim:
+
+  ```js
+  m("list", { class: "my-list" },
+    items.map((item) => m("list-item", { key: item.id }, [ItemView(item)])))
+  ```
+
+  Native does cell recycling at the native layer; Mithril's own already-tested keyed/LIS diff (`test/keyed-diff.test.ts`) computes add/remove/reorder of the `list-item` children — no different from any other keyed list.
+
+- **Tier 2 — `mithril-lynx/list`'s `createList(parentNode, options)`** (opt in, for when you specifically need native-driven recycling, e.g. very large lists): an imperative escape hatch like `element.js`/`gesture.js` — call from `oncreate(vnode)`, attach the result yourself:
+
+  ```js
+  import { createList } from "mithril-lynx/list";
+
+  m("view", {
+    oncreate: (vnode) => {
+      const list = createList(vnode.dom, {
+        itemCount: items.length,
+        renderItem: (index) => m("text", { class: "cell" }, items[index].label),
+      });
+      vnode.dom.appendChild(list);
+    },
+  });
+  ```
+
+  The sign/recycle-pool design (cells reused by *type*, matching RecyclerView/UICollectionView semantics) and the exact `__FlushElementTree({ triggerLayout, operationID, elementID, listID })` call shape are ported from `@lynx-js/react`'s own shipped `list.js` — real, proven code. `renderItem(index)` must return a fresh vnode every time it's called (it can be called more than once for the same index, on recycling); a recycled cell's content is *diffed* into its existing DOM subtree via Mithril's own diff, not recreated — verified in `test/list.test.ts` by asserting no new `__CreateElement` calls happen on reuse.
+
+  `createList()` also sets `scroll-orientation`/`list-type`/`span-count` on the list and `item-key` on every item (all required by native, confirmed by a real device never calling `componentAtIndex` without them — see `LIST_INVESTIGATION.md`), and sends a `"update-list-info"` attribute (`{insertAction, removeAction, updateAction}`, each entry needing `position`, `type`, and `item-key`) alongside `__UpdateListCallbacks` on creation and on every `setItemCount()` call — **this is the piece that actually makes native start calling `componentAtIndex` at all**; without it, `__CreateList` silently does nothing forever.
+
+  **Confirmed WORKING on a real device 2026-09-09** (see `DEVICE_VERIFICATION.md`): 37+ cells rendered and scrolled correctly, each recycled cell showing fresh, correct, non-duplicated content.
+
+  **Deliberately out of scope for v1** (documented, not silently missing): deferred list items (ReactLynx's `defer`/`isReady` promise dance), `componentAtIndexes` batching, and independent per-item redraw after the initial bind — a bound cell's content is recomputed fresh from `renderItem(index)` only when native calls `componentAtIndex` for it (scroll-driven reuse), not automatically when app state changes.
+
+## Known permanent gaps
+
+- `m.trust` / innerHTML vnodes — no Lynx PAPI equivalent to raw innerHTML injection.
+- `m.route` — Lynx pages aren't URL-addressable the way DOM `history` is.
+
+## Compat with the plain-JS ecosystem
+
+Mithril was never hooks-based, so — unlike React — there's no special rules-of-hooks compatibility story to build: `m.redraw()` after any state mutation already works with any plain-JS state library (a simple pub/sub store, streams, whatever). Nothing in this package needs to shim a specific state-management library for that reason; if something in the ecosystem doesn't work, it's not because of a hooks-equivalence gap.
+
+## Testing
+
+```bash
+bun install
+bun run test
+```
+
+Tests run against `@lynx-js/testing-environment`'s jsdom-backed PAPI polyfill. The polyfill itself is published as `mithril-lynx/testing`'s `installTestingPolyfills()` (see `test/setup.ts` for the one-line setup) — consuming apps can use the exact same polyfill for their own tests instead of maintaining a duplicate copy; see `mithril-app/test/setup.ts` for a worked example.
+
+**Not provided**: Fast Refresh and a devtools/inspector bundle (project plan, Phase 9 / subsystem 12) are explicitly out of scope — they're deep, compiler-driven DX features in upstream ReactLynx with no zero-compiler equivalent worth building. `rspeedy dev`'s existing full-reload-on-file-change loop is the honest substitute.

package/background.d.ts

@@ -0,0 +1,54 @@
+// Ambient declaration for the ESM background.js (the file itself is not
+// type-checked; this describes its runtime export shape for TS consumers).
+
+export type StoreData = Record<string, unknown>;
+
+export interface SetDataOptions {
+  /** Set false to update the store without pushing a sync to the main thread. Defaults to true. */
+  shouldSyncToMainThread?: boolean;
+}
+
+/** Returns the background thread's mutable data store. */
+export function getData<T = StoreData>(): T;
+
+/** Merges `patch` into the store, then (by default) pushes the changed keys to the main thread. */
+export function setData(patch: StoreData, options?: SetDataOptions): void;
+
+/**
+ * Registers the single handler invoked for every dispatchToBackground() call
+ * made from the main thread, as (handlerName, data).
+ */
+export function setBackgroundEventHandler(
+  handleEvent: (handlerName: string, data: unknown) => unknown,
+): void;
+
+/**
+ * Wires the background thread's core-context listeners for the
+ * main-thread <-> background-thread data channel. Call once, at
+ * background.ts's top level. See the project plan, Phase 3.
+ */
+export function setupBackground(): void;
+
+export interface BackgroundRef {
+  /** Resolves with the native method's success data, rejects with its failure data. */
+  invoke(method: string, params?: Record<string, unknown>): Promise<unknown>;
+}
+
+/**
+ * A background-thread ref: imperative calls to a native element identified
+ * by a CSS selector, via lynx.createSelectorQuery(). See the project plan,
+ * Phase 5.
+ */
+export function createRef(selector: string): BackgroundRef;
+
+/**
+ * Registers a handler main-thread.js's runOnBackground(key, ...args) can
+ * call by name. See the project plan, Phase 6.
+ */
+export function registerHandler(key: string, fn: (...args: unknown[]) => unknown): void;
+
+/**
+ * Calls a handler main-thread.js registered via registerHandler(key, fn).
+ * Args and the resolved value must be JSON-serializable.
+ */
+export function runOnMainThread<T = unknown>(key: string, ...args: unknown[]): Promise<T>;

package/background.js

@@ -0,0 +1,169 @@
+// background.js
+//
+// Cross-thread "data-channel mode" adapter for the background thread (see
+// the project plan, Phase 3). Ports
+// lynx-examples/examples/vanilla/src/common/background/{setup,data,event}.ts
+// into a single module — this side is framework-agnostic (Mithril never
+// renders on the background thread in data-channel mode), so nothing here
+// depends on the shim.
+//
+// A single mutable data store is diffed against its last-synced snapshot on
+// every setData() call and only the changed keys are pushed to the main
+// thread. Data received FROM the main thread is never echoed back (the
+// reference implementation does, on every update after the first — a
+// pure round-trip echo that's wasteful, and directly visible as a redundant
+// extra Mithril redraw in this port, so it isn't reproduced here).
+
+import {
+	callBackgroundEventName,
+	callBackgroundResultEventName,
+	callMainThreadEventName,
+	callMainThreadResultEventName,
+	destroyLifetimeEventName,
+	dispatchEventToBackgroundEventName,
+	updateDataFromBackgroundEventName,
+	updateDataFromMainThreadEventName,
+} from "./internal/constants.js";
+
+const data = {};
+let lastSyncedData = { ...data };
+let handleBackgroundEvent;
+
+export function getData() {
+	return data;
+}
+
+export function setData(patch, options = {}) {
+	const { shouldSyncToMainThread = true } = options;
+	Object.assign(data, patch);
+	if (!shouldSyncToMainThread) {
+		lastSyncedData = { ...data };
+		return;
+	}
+	sendToMainThread();
+}
+
+function sendToMainThread() {
+	const patch = {};
+	for (const [key, value] of Object.entries(data)) {
+		if (value !== lastSyncedData[key]) patch[key] = value;
+	}
+	if (Object.keys(patch).length === 0) return;
+	lastSyncedData = { ...data };
+	lynx.getCoreContext().dispatchEvent({
+		type: updateDataFromBackgroundEventName,
+		data: patch,
+	});
+}
+
+// handleEvent(handlerName, data) — called for every dispatchToBackground()
+// call made from the main thread. Only one handler at a time; Phase 6 of the
+// project plan generalizes this into a full string-keyed registry with
+// call/return correlation.
+export function setBackgroundEventHandler(handleEvent) {
+	handleBackgroundEvent = handleEvent;
+}
+
+export function setupBackground() {
+	const coreContext = lynx.getCoreContext();
+
+	const onUpdateDataFromMainThread = (event) => {
+		const incoming = event.data;
+		if (!incoming || typeof incoming !== "object" || Array.isArray(incoming)) return;
+		// Never echo data back to the thread it just came from — only
+		// background-initiated setData() calls (elsewhere in app code)
+		// should sync to the main thread.
+		setData(incoming, { shouldSyncToMainThread: false });
+	};
+
+	const onDispatchToBackground = (event) => {
+		const payload = event.data;
+		if (!payload || typeof payload.handlerName !== "string") return;
+		handleBackgroundEvent?.(payload.handlerName, payload.data);
+	};
+
+	const cleanup = () => {
+		coreContext.removeEventListener(updateDataFromMainThreadEventName, onUpdateDataFromMainThread);
+		coreContext.removeEventListener(dispatchEventToBackgroundEventName, onDispatchToBackground);
+		coreContext.removeEventListener(destroyLifetimeEventName, cleanup);
+	};
+
+	coreContext.addEventListener(updateDataFromMainThreadEventName, onUpdateDataFromMainThread);
+	coreContext.addEventListener(dispatchEventToBackgroundEventName, onDispatchToBackground);
+	coreContext.addEventListener(destroyLifetimeEventName, cleanup);
+}
+
+// Refs (project plan, Phase 5): the background thread has no direct native
+// handle, so imperative calls go through Lynx's existing selector-query
+// bridge (the same primitive ReactLynx's own background-thread refs
+// ultimately bottom out on) rather than a new protocol.
+export function createRef(selector) {
+	return {
+		invoke(method, params) {
+			return new Promise((resolve, reject) => {
+				lynx.createSelectorQuery()
+					.select(selector)
+					.invoke({
+						method,
+						params: params || {},
+						success: (data) => resolve(data),
+						fail: (data) => reject(data),
+					})
+					.exec();
+			});
+		},
+	};
+}
+
+// Cross-thread function registry (project plan, Phase 6 — worklet
+// substitute). See main-thread.js's registerHandler()/runOnBackground() for
+// the full rationale; this is the mirror image for the reverse direction.
+// Lazy setup on first use, same reasoning as main-thread.js.
+const backgroundHandlers = new Map();
+const pendingMainThreadCalls = new Map();
+let nextCallId = 1;
+let crossThreadCallsReady = false;
+
+function ensureCrossThreadCalls() {
+	if (crossThreadCallsReady) return;
+	crossThreadCallsReady = true;
+	const coreContext = lynx.getCoreContext();
+
+	coreContext.addEventListener(callBackgroundEventName, (event) => {
+		const { callId, key, args } = event.data;
+		const fn = backgroundHandlers.get(key);
+		let result;
+		let error;
+		try {
+			result = fn ? fn(...args) : undefined;
+		} catch (e) {
+			error = e instanceof Error ? e.message : String(e);
+		}
+		coreContext.dispatchEvent({ type: callBackgroundResultEventName, data: { callId, result, error } });
+	});
+
+	coreContext.addEventListener(callMainThreadResultEventName, (event) => {
+		const { callId, result, error } = event.data;
+		const pending = pendingMainThreadCalls.get(callId);
+		if (pending == null) return;
+		pendingMainThreadCalls.delete(callId);
+		if (error != null) pending.reject(new Error(error));
+		else pending.resolve(result);
+	});
+}
+
+/** Registers a handler main-thread.js's runOnBackground(key, ...) can call by name. */
+export function registerHandler(key, fn) {
+	ensureCrossThreadCalls();
+	backgroundHandlers.set(key, fn);
+}
+
+/** Calls a handler main-thread.js registered via registerHandler(key, fn), by name. Args must be JSON-serializable. */
+export function runOnMainThread(key, ...args) {
+	ensureCrossThreadCalls();
+	return new Promise((resolve, reject) => {
+		const callId = nextCallId++;
+		pendingMainThreadCalls.set(callId, { resolve, reject });
+		lynx.getCoreContext().dispatchEvent({ type: callMainThreadEventName, data: { callId, key, args } });
+	});
+}