mithril-lynx 2.5.0 → 2.6.2

package/src/apply-patch.js

@@ -6,11 +6,11 @@
 // low-level interpreter of the flat op array straight onto the real
 // Element PAPI, in the spirit of ReactLynx's own `snapshotPatchApply.js`
 // (see rspeedy-react-analysis/LYNX_PAPI_SPEC.md §4.3): a switch over op
-// codes, one real PAPI call per case, nothing else. One deliberate
-// exception: Op.CreateList's own cell content (see list-support.js) DOES
-// run a real Mithril render pass right here, on this thread — the only way
-// to satisfy native's synchronous componentAtIndex contract at all (see
-// docs/native-papi/papi-06-virtualized-lists.md in mithril-lynx-ui).
+// codes, one real PAPI call per case, nothing else. Op.CreateList's own
+// cell content (list-support.js) is no exception to that: componentAtIndex
+// replays ops the background thread already computed (list-cell.js), the
+// same way this function replays the app's own top-level tree — see
+// docs/native-papi/papi-06-virtualized-lists.md in mithril-lynx-ui.
 //
 // The exact `__Create*`/pageId contract below (one `pageId` shared by every
 // element on a page, `__CreateView`/`__CreateText`/generic `__CreateElement`
@@ -191,16 +191,47 @@ function registerGestureDetector(handle, id, gestureId, gestureType, arenaPolicy
  * @param {number} pageId - `__GetElementUniqueID(pageElement)` of the real
  *   page this applier is attached to. Every element this applier creates
  *   belongs to that one page — see CONTRACT.md / lynx-mithril-shim.js.
+ * @param {object} [options]
+ * @param {Function} [options.onEvent]
+ * @param {boolean} [options.flush] - Whether `applyPatch` calls the bare,
+ *   whole-page `__FlushElementTree()` after applying its ops. Defaults to
+ *   `true` — the right default for the ONE real top-level applier per page
+ *   (main-thread.js's own use). `false` for a per-cell applier
+ *   (list-support.js): a list cell's real commit point is the list-specific
+ *   `__FlushElementTree(wrapperHandle, {triggerLayout, operationID,
+ *   elementID, listID})` call list-support.js already makes right after —
+ *   calling the bare, whole-page flush too, from inside native's own
+ *   synchronous componentAtIndex callback, is a second, unrelated flush this
+ *   applier was never meant to trigger on that call site's behalf.
  */
-export function createPatchApplier(pageId, { onEvent } = {}) {
+export function createPatchApplier(pageId, { onEvent, flush = true } = {}) {
 	// id (as allocated by the background's virtual backend) -> real PAPI
 	// element handle. id 0 is reserved for "the page itself" (see
 	// fake-dom.js's LynxDocument) — pre-seeded here so the very first
 	// InsertBefore/AppendChild targeting id 0 has somewhere real to land.
 	const handles = new Map();
+	// list id -> its setCells(cells) function (list-support.js) — kept here,
+	// not as a property on the list's own handle: a real native list handle
+	// does not reliably hold a custom property across calls (confirmed on
+	// device), only `handles` (a plain Map) does.
+	const listSetters = new Map();
+
+	// id -> Map<event type, listener callback>. `__AddEventListener` needs the
+	// exact callback reference back when `__RemoveEventListener` runs, so the
+	// listener cannot be an inline closure re-created per Op.AddEvent — it is
+	// stored here and reused by the Op.RemoveEvent case.
+	const eventListeners = new Map();
+
+	/** General form: seed the mapping for any id, not just the page root —
+	 * list-support.js uses this to alias a list-cell.js `containerId` (an
+	 * off-tree id from the background thread's OWN document) to the real
+	 * native wrapper element it created for that cell. */
+	function registerRoot(id, handle) {
+		handles.set(id, handle);
+	}
 
 	function registerPageRoot(pageElementHandle) {
-		handles.set(0, pageElementHandle);
+		registerRoot(0, pageElementHandle);
 	}
 
 	function createElementHandle(tag) {
@@ -210,12 +241,15 @@ export function createPatchApplier(pageId, { onEvent } = {}) {
 	}
 
 	/**
-	 * Applies one commit's worth of ops, then flushes exactly once —
-	 * `__FlushElementTree` is the real commit; nothing before it is visible.
-	 * This function itself is the ONLY caller of `__FlushElementTree` on
-	 * this applier's page — never called conditionally, never looked up
-	 * through a global (mirrors the fix in commit.js on the background
-	 * side: one explicit call site, not an implicit one).
+	 * Applies one commit's worth of ops, then — unless this applier was
+	 * created with `flush: false` (see this function's own constructor
+	 * options above) — flushes exactly once with the bare, whole-page
+	 * `__FlushElementTree()`; that call is the real commit for the ONE
+	 * top-level applier per page, never looked up through a global. A
+	 * per-cell applier (list-support.js) passes `flush: false` and issues
+	 * its own list-specific `__FlushElementTree(wrapperHandle, {...})` call
+	 * afterward instead — that one, not this one, is that cell's real
+	 * commit point.
 	 */
 	function applyPatch(ops) {
 		for (let i = 0; i < ops.length; ) {
@@ -331,18 +365,43 @@ export function createPatchApplier(pageId, { onEvent } = {}) {
 					const id = ops[i++];
 					const type = ops[i++];
 					const handle = handles.get(id);
-					__AddEventListener(handle, type, (nativeEvent) => {
+					const listener = (nativeEvent) => {
 						onEvent?.(id, type, nativeEvent);
-					}, {});
+					};
+					let byType = eventListeners.get(id);
+					if (byType == null) eventListeners.set(id, (byType = new Map()));
+					byType.set(type, listener);
+					__AddEventListener(handle, type, listener, {});
 					break;
 				}
 				case Op.RemoveEvent: {
-					// PAPI has no documented `__RemoveEventListener` in the
-					// validated v1 surface (CONTRACT.md never needed it,
-					// since mithril-lynx v1 never tore down individual
-					// listeners outside of removing the whole element).
-					// Left as an explicit no-op + TODO rather than a guess.
-					i += 2;
+					const id = ops[i++];
+					const type = ops[i++];
+					const handle = handles.get(id);
+					const byType = eventListeners.get(id);
+					const listener = byType ? byType.get(type) : undefined;
+					if (typeof __RemoveEventListener === "function") {
+						// Native Fiber requires the options argument (>= 4 params) and
+						// derives the binding slot from it — pass the same `{}` the
+						// Op.AddEvent case uses so add/remove target the same slot.
+						if (listener != null) __RemoveEventListener(handle, type, listener, {});
+					} else if (listener != null) {
+						// Failing loudly is deliberate: without __RemoveEventListener a
+						// remove→re-add cycle on a kept element would accumulate
+						// duplicate native listeners and fire the handler N times per
+						// event. A silent no-op here is exactly the class of bug the
+						// whole project refuses to ship.
+						throw new Error(
+							"[mithril-lynx] __RemoveEventListener is not available on this runtime, " +
+								"so Op.RemoveEvent cannot be applied — a conditional event handler " +
+								"would leak duplicate listeners. Keep the handler constant or " +
+								"remove the whole element instead.",
+						);
+					}
+					if (byType != null) {
+						byType.delete(type);
+						if (byType.size === 0) eventListeners.delete(id);
+					}
 					break;
 				}
 				case Op.SetGestureDetector: {
@@ -363,29 +422,30 @@ export function createPatchApplier(pageId, { onEvent } = {}) {
 				}
 				case Op.CreateList: {
 					const id = ops[i++];
-					const rendererKey = ops[i++];
 					const scrollOrientation = ops[i++];
 					const listType = ops[i++];
 					const spanCount = ops[i++];
-					handles.set(id, createNativeList(pageId, rendererKey, scrollOrientation, listType, spanCount, createPatchApplier, onEvent));
+					const { handle, setCells } = createNativeList(pageId, scrollOrientation, listType, spanCount, createPatchApplier, onEvent);
+					handles.set(id, handle);
+					listSetters.set(id, setCells);
 					break;
 				}
 				case Op.SetListItems: {
 					const id = ops[i++];
-					const itemsJSON = ops[i++];
-					const listHandle = handles.get(id);
-					listHandle.__setItems(JSON.parse(itemsJSON));
+					const cells = ops[i++];
+					listSetters.get(id)(cells);
 					break;
 				}
 				default:
 					throw new Error(`[mithril-lynx] Unknown patch opcode: ${opcode}`);
 			}
 		}
-		__FlushElementTree();
+		if (flush) __FlushElementTree();
 	}
 
 	return {
 		registerPageRoot,
+		registerRoot,
 		applyPatch,
 		/** The real PAPI element handle for a given background-side id, or
 		 * `undefined` if nothing was ever created for it. Exists for tests

package/src/backends/virtual-backend.js

@@ -75,13 +75,13 @@ export function createVirtualBackend() {
 		removeGestureDetector(id, gestureId) {
 			pushOp(ops, Op.RemoveGestureDetector, id, gestureId);
 		},
-		createList(rendererKey, scrollOrientation, listType, spanCount) {
+		createList(scrollOrientation, listType, spanCount) {
 			const id = nextId++;
-			pushOp(ops, Op.CreateList, id, rendererKey, scrollOrientation, listType, spanCount);
+			pushOp(ops, Op.CreateList, id, scrollOrientation, listType, spanCount);
 			return id;
 		},
-		setListItems(id, items) {
-			pushOp(ops, Op.SetListItems, id, JSON.stringify(items));
+		setListItems(id, cells) {
+			pushOp(ops, Op.SetListItems, id, cells);
 		},
 		/** Drains and returns the accumulated ops. Called once per commit. */
 		takeOps() {
@@ -90,5 +90,19 @@ export function createVirtualBackend() {
 			ops = [];
 			return out;
 		},
+		/**
+		 * Runs `fn` (a DOM mutation against a node from THIS backend's own
+		 * document — same id space as everything else, so event dispatch
+		 * keeps working normally) and returns just the ops it produced,
+		 * removing them from the shared buffer so they never also go out
+		 * with the next `takeOps()`. Used by list-cell.js to render one list
+		 * item off-tree and ship its construction ops separately, instead of
+		 * as part of the app's own visible-tree patch.
+		 */
+		captureOps(fn) {
+			const start = ops.length;
+			fn();
+			return ops.splice(start, ops.length - start);
+		},
 	};
 }

package/src/background.d.ts

@@ -3,9 +3,22 @@ export interface RenderAppOptions {
 	sendPatch?: (ops: unknown[]) => void;
 }
 
+/** Minimal shape of a fake-DOM node exposed for tests and HMR glue — enough
+ * to dispatch a synthetic event (e.g. `node.dispatchEvent({ type: "tap" })`)
+ * and correlate with a background-side id. */
+export interface LynxNode {
+	dispatchEvent(event: unknown): unknown;
+}
+
+/** The subset of the fake-DOM document exposed on the render handle — used
+ * by tests and by an app's own HMR glue, never by the channel wiring. */
+export interface LynxDocument {
+	getNodeById(id: number): LynxNode | null;
+}
+
 export interface RenderAppHandle {
 	redraw: () => void;
-	document: unknown;
+	document: LynxDocument;
 }
 
 export function renderApp(options: RenderAppOptions): RenderAppHandle;

package/src/channel.js

@@ -20,9 +20,17 @@ export const eventFromMainThreadEventName = "MithrilLynx:Event";
 export const renderPageEventName = "__RenderPage";
 export const destroyLifetimeEventName = "__DestroyLifetime";
 
-/** Background thread: ship one commit's ops to the main thread. */
+import { PROTOCOL_VERSION } from "./patch-protocol.js";
+
+/**
+ * Background thread: ship one commit's ops to the main thread.
+ *
+ * The patch is prefixed with `PROTOCOL_VERSION` so the main thread can
+ * detect a stale/desynced bundle (partial HMR, cache) and fail loudly
+ * instead of re-interpreting reordered opcodes against the shared id space.
+ */
 export function sendPatchToMainThread(ops) {
-	lynx.getCoreContext().dispatchEvent({ type: patchEventName, data: ops });
+	lynx.getCoreContext().dispatchEvent({ type: patchEventName, data: [PROTOCOL_VERSION, ...ops] });
 }
 
 /** Background thread: receive a forwarded native event `{ id, type, payload }`. */

package/src/fake-dom.js

@@ -178,7 +178,7 @@ export class LynxElement extends LynxContainerNode {
 		this.tag = tag;
 		this.namespaceURI = ns;
 		this._id = listConfig
-			? backend.createList(listConfig.rendererKey, listConfig.scrollOrientation, listConfig.listType, listConfig.spanCount)
+			? backend.createList(listConfig.scrollOrientation, listConfig.listType, listConfig.spanCount)
 			: ns
 				? backend.createElementNS(ns, tag)
 				: backend.createElement(tag);
@@ -440,22 +440,25 @@ export class LynxDocument extends LynxContainerNode {
 
 	/**
 	 * A native virtualized list — see patch-protocol.js's Op.CreateList.
-	 * `rendererKey` must match a key registered on the MAIN thread via
-	 * mithril-lynx/list-support's registerListRenderer() (see
-	 * docs/native-papi/papi-06-virtualized-lists.md in mithril-lynx-ui):
-	 * the renderer function itself can't cross the thread boundary, only
-	 * this string key can. Call `.setListItems(items)` on the result to
-	 * populate it — items must be JSON-serializable, since they DO cross
-	 * the boundary, as data.
+	 * Populate it via `.setListItems(cells)` (list-cell.js builds `cells`
+	 * from an app's own `items`/`renderItem`) — see
+	 * docs/native-papi/papi-06-virtualized-lists.md in mithril-lynx-ui.
 	 */
-	createNativeList(rendererKey, options = {}) {
+	createNativeList(options = {}) {
 		return new LynxElement(this, this._backend, "list", undefined, {
-			rendererKey,
 			scrollOrientation: options.scrollOrientation ?? "vertical",
 			listType: options.listType ?? "single",
 			spanCount: options.spanCount ?? 1,
 		});
 	}
+
+	/** Delegates to the backend — see virtual-backend.js's own captureOps
+	 * for what this is for. Kept behind LynxDocument's public surface like
+	 * every other backend interaction in this file, rather than exposing
+	 * `_backend` itself to callers (list-cell.js). */
+	captureOps(fn) {
+		return this._backend.captureOps(fn);
+	}
 }
 
 export function createLynxDocument(backend) {

package/src/list-cell.d.ts

@@ -0,0 +1,20 @@
+// Ambient declaration for the ESM src/list-cell.js — the background-thread
+// half of native list support. mithril-lynx-ui's <List>/<FeedList> call
+// this once per item, from the SAME thread/document as the rest of the
+// app's own tree — see that file's own header for why.
+
+export interface ListCell {
+	typeKey: string;
+	containerId: number;
+	ops: unknown[];
+	rootChildIds: number[];
+}
+
+export function renderListCell(
+	document: unknown,
+	render: (dom: unknown, vnodes: unknown[], redraw: () => void) => void,
+	redraw: () => void,
+	renderItem: (item: unknown, index: number) => unknown,
+	item: unknown,
+	index: number,
+): ListCell;

package/src/list-cell.js

@@ -0,0 +1,73 @@
+// src/list-cell.js
+//
+// Runs ONLY on the background thread — the counterpart to list-support.js's
+// main-thread half. Turns one `renderItem(item, index)` call into a
+// self-contained set of construction ops, using the app's OWN document/
+// backend/render (the same ones background.js already created for the rest
+// of the tree) — never a separate, isolated render pipeline. That's the
+// whole point: the item's real fake-dom nodes end up registered in the same
+// `document._nodesById` map as everything else in the app, so a forwarded
+// native event for one of them dispatches through `onEventFromMainThread`
+// exactly like any other element's event already does. No extra reporting
+// convention needed.
+//
+// The main thread never calls renderItem() itself — see list-support.js.
+
+import { Op, forEachOp } from "./patch-protocol.js";
+
+function typeKeyOf(vnode) {
+	return typeof vnode.tag === "string" ? vnode.tag : (vnode.tag && vnode.tag.name) || "default";
+}
+
+/** The real handle ids inserted directly under `containerId` — what a
+ * recycled cell on the main thread needs to remove before it can attach a
+ * different item's content into the same native wrapper (see
+ * list-support.js's clearWrapperChildren). Scanning the ops after the fact,
+ * instead of tracking during render, keeps this file from needing any
+ * backend-internal access beyond `captureOps` itself. */
+function findTopLevelChildIds(ops, containerId) {
+	const ids = [];
+	forEachOp(ops, (opcode, args) => {
+		if (opcode === Op.InsertBefore && args[0] === containerId) ids.push(args[1]);
+	});
+	return ids;
+}
+
+/**
+ * @param {import("./fake-dom.js").LynxDocument} document - the app's own
+ *   document (e.g. `vnode.dom.ownerDocument` from inside a component) — NOT
+ *   a separate one. Sharing it is what keeps a list cell's ids in the same
+ *   `_nodesById` space as the rest of the app.
+ * @param {(dom: object, vnodes: unknown[], redraw: () => void) => void} render
+ *   - a `mithril-runtime/render/render.js` instance. Callers typically keep
+ *   one shared instance per `<List>` (see mithril-lynx-ui's list.js), not
+ *   one per cell — render() is designed to manage multiple independent
+ *   containers safely.
+ * @param {() => void} redraw - forwarded as render()'s own redraw callback,
+ *   so a `ontap` (etc.) handler inside the rendered cell triggers a REAL
+ *   app-wide redraw afterward, exactly like any other event in the app —
+ *   see mithril-lynx/mount-redraw's `redraw()`.
+ * @param {(item: unknown, index: number) => unknown} renderItem
+ * @param {unknown} item
+ * @param {number} index
+ * @returns {{ typeKey: string, containerId: number, ops: unknown[], rootChildIds: number[] }}
+ */
+export function renderListCell(document, render, redraw, renderItem, item, index) {
+	// An ordinary element in the SAME document, never inserted into the
+	// visible tree (no `appendChild`/`insertBefore` call targets it) — its
+	// own `Op.CreateElement` never gets captured below since it's created
+	// OUTSIDE the capture, before there's anything to record; only what
+	// render() does INSIDE it is captured. The main thread's list-support.js
+	// treats `containerId` as an alias for whatever real native wrapper it
+	// creates for this cell, the same way apply-patch.js's top-level applier
+	// treats id 0 as an alias for the real page element.
+	const container = document.createElement("list-cell-root");
+	const vnode = renderItem(item, index);
+	const typeKey = typeKeyOf(vnode);
+
+	const ops = document.captureOps(() => {
+		render(container, [vnode], redraw);
+	});
+
+	return { typeKey, containerId: container._id, ops, rootChildIds: findTopLevelChildIds(ops, container._id) };
+}

package/src/list-support.d.ts

@@ -1,10 +1,13 @@
-// Ambient declaration for the ESM src/list-support.js.
-//
-// Import this from your app's main-thread.ts (alongside setupRenderer()
-// from "mithril-lynx/main-thread") and call registerListRenderer() once
-// per list your app uses — see that file's own header, and
-// docs/native-papi/papi-06-virtualized-lists.md in mithril-lynx-ui, for
-// why the render function itself has to be registered here rather than
-// passed in from background.ts directly.
+// Ambient declaration for the ESM src/list-support.js — the main-thread
+// half of native list support. Not meant to be imported directly by app
+// code; apply-patch.js's own Op.CreateList case is the only caller. See
+// list-cell.d.ts for the background-thread half an app actually uses.
 
-export function registerListRenderer(key: string, renderItem: (item: unknown, index: number) => unknown): void;
+export function createNativeList(
+	pageId: number,
+	scrollOrientation: string,
+	listType: string,
+	spanCount: number,
+	createPatchApplier: (pageId: number, options?: { onEvent?: Function; flush?: boolean }) => object,
+	onEvent?: Function,
+): { handle: unknown; setCells: (cells: unknown[]) => void };