mithril-lynx 2.6.2 → 3.0.0

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. 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.
+// codes, one real PAPI call per case, nothing else. The one element that
+// needs more is Lynx's native `<list>`: its `list-item` children are not
+// inserted natively here but handed to list-runtime.js, which tells native
+// about them through `update-list-info` and attaches each one only when
+// native asks for it (componentAtIndex).
 //
 // The exact `__Create*`/pageId contract below (one `pageId` shared by every
 // element on a page, `__CreateView`/`__CreateText`/generic `__CreateElement`
@@ -22,8 +22,9 @@
 // allows (§2 non-goals) — the bug this rewrite fixes lives in the
 // commit/reload layer (commit.js, reload/*.js), never in this mapping.
 
-import { Op } from "./patch-protocol.js";
-import { createNativeList } from "./list-support.js";
+import { FORM_FIELD_TAGS, INVOKE_RESULT_EVENT, Op } from "./patch-protocol.js";
+import { LIST_ITEM_VIRTUAL_ATTRIBUTES } from "./list-attributes.js";
+import { createListRuntime, isListItemPlatformAttribute } from "./list-runtime.js";
 
 // --- Native gesture support (Op.SetGestureDetector) ------------------------
 //
@@ -47,6 +48,10 @@ const GestureState = { active: 1, fail: 2, end: 3 };
 // this project's own predecessor, mithril-lynx v1's gesture.js), not
 // specific to any one package — every gesture callback has to be wrapped
 // through this registry before being handed to __SetGestureDetector.
+/**
+ * Installs the global worklet registry native requires (`registerWorklet`/`runWorklet`) if not already present.
+ * @returns {void}
+ */
 function ensureWorkletRuntime() {
 	if (globalThis.lynxWorkletImpl !== undefined) return;
 	globalThis.lynxWorkletImpl = { _workletMap: {} };
@@ -66,6 +71,11 @@ function ensureWorkletRuntime() {
 }
 
 let nextWorkletId = 1;
+/**
+ * Registers a gesture callback in the worklet registry under a fresh id.
+ * @param {Function} fn - The callback native should invoke.
+ * @returns {{_wkltId: string}} The worklet context object to hand to `__SetGestureDetector`.
+ */
 function wrapWorkletCallback(fn) {
 	ensureWorkletRuntime();
 	const id = "mithril-lynx-gesture-" + nextWorkletId++;
@@ -73,6 +83,18 @@ function wrapWorkletCallback(fn) {
 	return { _wkltId: id };
 }
 
+/**
+ * Deletes worklets from the registry. A native callback that still arrives
+ * for a deleted id is a no-op: `runWorklet` ignores unknown ids.
+ * @param {string[]} ids - The worklet ids to delete.
+ * @returns {void}
+ */
+function unregisterWorklets(ids) {
+	const impl = globalThis.lynxWorkletImpl;
+	if (impl === undefined) return;
+	for (const id of ids) delete impl._workletMap[id];
+}
+
 /**
  * A small, generic claim/release policy — covers the two real shapes this
  * project's consumers need, not an arbitrary one:
@@ -89,6 +111,8 @@ function wrapWorkletCallback(fn) {
  * device-verified sheet.js/swipe-action.js/swiper.js already did; the NEW
  * part, evaluating it here instead of in app code, has not been confirmed
  * to feel the same on-device.
+ * @param {{mode?: "claim"|"axis-lock", axis?: "horizontal"|"vertical", referenceMoves?: number}} [policy] - The claim/release policy; defaults to `{ mode: "claim" }`.
+ * @returns {{onDown: (x: number, y: number, consume: (claim: boolean) => void) => void, onMove: (x: number, y: number, consume: (claim: boolean) => void, fail: () => void) => void}} The tracker driven by native touch events.
  */
 function createArenaTracker(policy) {
 	const mode = (policy && policy.mode) || "claim";
@@ -98,6 +122,13 @@ function createArenaTracker(policy) {
 	let decided = false;
 
 	return {
+		/**
+		 * Handles touches-down: claims the gesture and records the reference point when applicable.
+		 * @param {number} x - Touch `clientX`.
+		 * @param {number} y - Touch `clientY`.
+		 * @param {(claim: boolean) => void} consume - Claims (`true`) or releases (`false`) the gesture arena.
+		 * @returns {void}
+		 */
 		onDown(x, y, consume) {
 			consume(true);
 			if (mode === "axis-lock" && (policy.referenceMoves || 0) === 0) {
@@ -105,6 +136,14 @@ function createArenaTracker(policy) {
 				refY = y;
 			}
 		},
+		/**
+		 * Handles touches-move: for `axis-lock`, decides once whether the dominant axis matches, otherwise releases and fails the gesture.
+		 * @param {number} x - Touch `clientX`.
+		 * @param {number} y - Touch `clientY`.
+		 * @param {(claim: boolean) => void} consume - Claims (`true`) or releases (`false`) the gesture arena.
+		 * @param {() => void} fail - Marks the gesture as failed.
+		 * @returns {void}
+		 */
 		onMove(x, y, consume, fail) {
 			if (mode !== "axis-lock" || decided) return;
 			if ((policy.referenceMoves || 0) === 1 && movesSeen === 0) {
@@ -135,15 +174,34 @@ function createArenaTracker(policy) {
 	};
 }
 
+/**
+ * Registers a native gesture detector on an element and forwards its touch events to the background thread.
+ * @param {*} handle - The real PAPI element handle.
+ * @param {number} id - The background-side element id.
+ * @param {number} gestureId - The gesture id allocated on the background thread.
+ * @param {string|number} gestureType - A gesture type name (e.g. `"pan"`) or its numeric code.
+ * @param {{mode?: string, axis?: string, referenceMoves?: number}} [arenaPolicy] - The claim/release policy.
+ * @param {(id: number, type: string, payload: unknown) => void} [onEvent] - Receives `gesturedown`/`gesturemove`/`gestureup` events.
+ * @returns {string[]} The ids of the worklets registered for this detector, to pass to `unregisterWorklets` when it goes away.
+ */
 function registerGestureDetector(handle, id, gestureId, gestureType, arenaPolicy, onEvent) {
 	const tracker = createArenaTracker(arenaPolicy);
 	const gestureTypeCode = typeof gestureType === "string" ? GESTURE_TYPE_CODES[gestureType] : gestureType;
 
+	/**
+	 * @param {*} controller - The native gesture controller passed to the callback.
+	 * @param {boolean} shouldClaim - Whether to claim (`true`) or release (`false`) the arena.
+	 * @returns {void}
+	 */
 	function consume(controller, shouldClaim) {
 		if (controller != null && typeof controller.__ConsumeGesture === "function") {
 			controller.__ConsumeGesture(handle, gestureId, { consume: shouldClaim, inner: false });
 		}
 	}
+	/**
+	 * @param {*} controller - The native gesture controller passed to the callback.
+	 * @returns {void}
+	 */
 	function fail(controller) {
 		if (controller != null && typeof controller.__SetGestureState === "function") {
 			controller.__SetGestureState(handle, gestureId, GestureState.fail);
@@ -155,6 +213,10 @@ function registerGestureDetector(handle, id, gestureId, gestureType, arenaPolicy
 	// rather than having a consumer approximate it from receipt time on
 	// the background thread, which would fold cross-thread forwarding
 	// latency into a velocity computation.
+	/**
+	 * @param {{params?: {clientX?: number, clientY?: number, timestamp?: number}}} [event] - A native touch/gesture event.
+	 * @returns {{clientX: number|undefined, clientY: number|undefined, timestamp: number|undefined}} The event's coordinates and timestamp.
+	 */
 	function coordsOf(event) {
 		const p = (event && event.params) || {};
 		return { clientX: p.clientX, clientY: p.clientY, timestamp: p.timestamp };
@@ -176,15 +238,12 @@ function registerGestureDetector(handle, id, gestureId, gestureType, arenaPolicy
 		},
 	};
 
+	const wrapped = Object.keys(callbacks).map((name) => ({ name, callback: wrapWorkletCallback(callbacks[name]) }));
+
 	__SetAttribute(handle, "has-react-gesture", true);
 	__SetAttribute(handle, "flatten", false);
-	__SetGestureDetector(
-		handle,
-		gestureId,
-		gestureTypeCode,
-		{ callbacks: Object.keys(callbacks).map((name) => ({ name, callback: wrapWorkletCallback(callbacks[name]) })) },
-		{},
-	);
+	__SetGestureDetector(handle, gestureId, gestureTypeCode, { callbacks: wrapped }, {});
+	return wrapped.map((entry) => entry.callback._wkltId);
 }
 
 /**
@@ -192,17 +251,16 @@ function registerGestureDetector(handle, id, gestureId, gestureType, arenaPolicy
  *   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 {(id: number, type: string, payload: unknown, seq?: number) => void} [options.onEvent] -
+ *   Forwards a native event to the background thread. `seq` is set for
+ *   events of an <input>/<textarea>: the number of native `input` events
+ *   that field has fired so far (see Op.SetInputValue). Also carries
+ *   Op.InvokeUIMethod results, as `INVOKE_RESULT_EVENT` events on id 0.
  * @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.
+ *   (main-thread.js's own use). `false` when the caller commits by itself.
+ * @returns {{registerPageRoot: (pageElementHandle: *) => void, registerRoot: (id: number, handle: *) => void, applyPatch: (ops: unknown[]) => void, getHandle: (id: number) => *, dispose: () => void}} The patch applier.
  */
 export function createPatchApplier(pageId, { onEvent, flush = true } = {}) {
 	// id (as allocated by the background's virtual backend) -> real PAPI
@@ -210,11 +268,15 @@ export function createPatchApplier(pageId, { onEvent, flush = true } = {}) {
 	// 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();
+	// list id -> its list-runtime.js state — 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 a plain Map
+	// does.
+	const lists = new Map();
+	// list-item id -> its platform info (item-key, full-span, sticky-*, …),
+	// collected from its attribute ops. Kept even before the item is inserted
+	// into a list: Mithril sets an element's attributes before inserting it.
+	const itemInfo = new Map();
 
 	// id -> Map<event type, listener callback>. `__AddEventListener` needs the
 	// exact callback reference back when `__RemoveEventListener` runs, so the
@@ -222,34 +284,189 @@ export function createPatchApplier(pageId, { onEvent, flush = true } = {}) {
 	// 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. */
+	// id -> Map<gestureId, worklet ids>. Every worklet closure holds its
+	// element's native handle, so the registry entries must be deleted when
+	// the detector (Op.RemoveGestureDetector) or its element (releaseSubtree)
+	// goes away — otherwise the global registry keeps the handle alive forever.
+	const gestureWorklets = new Map();
+
+	// The tree shape as seen through InsertBefore/RemoveChild ops. Mithril's
+	// removeDOM (render.js) only ever calls removeChild on the ROOT of a
+	// removed subtree — descendants never get an Op.RemoveChild of their own —
+	// so without this, every descendant's `handles`/`eventListeners`/
+	// `lists`/`itemInfo`/`gestureWorklets` entry would outlive the removal, and
+	// `handles` (plus the worklet registry) would keep the whole detached
+	// native subtree reachable from JS.
+	const childrenOf = new Map(); // parent id -> Set<child id>
+	const parentOf = new Map(); // child id -> parent id
+
+	// <input>/<textarea> id -> { seq, value, composing }:
+	// - `value`/`composing`: the text (and IME state) JS last knew the field
+	//   to hold — from its last forwarded `input` event or the last setValue
+	//   run here. A native `input` event that doesn't change them is not
+	//   forwarded: native fires such events by itself (a <textarea> fires
+	//   `input ""` while it is first flushed; every setValue is echoed back
+	//   as an `input`), and on the web an `input` event only means the user
+	//   changed the text. Forwarding them would hand the app a spurious ""
+	//   at creation — wiping a controlled field's state.
+	// - `seq`: how many text-changing `input` events it has fired. Forwarded
+	//   with every event of the field, echoed back by the background in
+	//   Op.SetInputValue: a value computed before the latest keystroke is
+	//   stale and dropped (the keystroke's own event re-renders), which keeps
+	//   a programmatic value from overwriting text the user typed meanwhile —
+	//   the job lynx-ui's Input does with a main-thread readonly lock.
+	const fields = new Map();
+
+	// Op.InvokeUIMethod / Op.SetInputValue calls of the current patch, in op
+	// order. They run after the patch's flush: a UI method needs the native
+	// element to exist, and an element created by this same patch only does
+	// once the element tree has been flushed.
+	let pendingInvokes = [];
+
+	/**
+	 * Drops every per-id entry for `id` and all of its known descendants.
+	 * Iterative (explicit stack) so a deep subtree can't overflow the call
+	 * stack. Native listeners and gesture detectors are not removed one by
+	 * one: they live on the native elements, which go away with the detached
+	 * subtree once JS stops holding their handles (including through the
+	 * gesture worklets, which are unregistered here). A removed native list
+	 * also gets its callbacks neutralized.
+	 * @param {number} id - The root of the removed subtree.
+	 * @returns {void}
+	 */
+	function releaseSubtree(id) {
+		const stack = [id];
+		while (stack.length > 0) {
+			const current = stack.pop();
+			const children = childrenOf.get(current);
+			if (children != null) {
+				for (const childId of children) stack.push(childId);
+				childrenOf.delete(current);
+			}
+			parentOf.delete(current);
+			handles.delete(current);
+			fields.delete(current);
+			eventListeners.delete(current);
+			itemInfo.delete(current);
+			const list = lists.get(current);
+			if (list != null) {
+				list.destroy();
+				lists.delete(current);
+			}
+			const gestures = gestureWorklets.get(current);
+			if (gestures != null) {
+				for (const workletIds of gestures.values()) unregisterWorklets(workletIds);
+				gestureWorklets.delete(current);
+			}
+		}
+	}
+
+	/** General form: seed the mapping for any id, not just the page root
+	 * (tests use it to mount a subtree under an element they created).
+	 * @param {number} id - The background-side id to alias.
+	 * @param {*} handle - The real PAPI element handle it maps to.
+	 * @returns {void}
+	 */
 	function registerRoot(id, handle) {
 		handles.set(id, handle);
 	}
 
+	/**
+	 * Maps the reserved id `0` to the real page element.
+	 * @param {*} pageElementHandle - The page element created by `__CreatePage`.
+	 * @returns {void}
+	 */
 	function registerPageRoot(pageElementHandle) {
 		registerRoot(0, pageElementHandle);
 	}
 
+	/**
+	 * Creates the real PAPI element for a tag.
+	 * @param {string} tag - The tag name (`view` and `text` use their dedicated creators).
+	 * @returns {*} The new element handle.
+	 */
 	function createElementHandle(tag) {
 		if (tag === "view") return __CreateView(pageId);
 		if (tag === "text") return __CreateText(pageId);
 		return __CreateElement(tag, pageId, {});
 	}
 
+	/**
+	 * Records one platform attribute of a list item: it travels to native in
+	 * `update-list-info` (list-runtime.js), and is also set on the element
+	 * itself unless it is one of the list-only virtual attributes.
+	 * @param {number} id - The list-item id.
+	 * @param {string} name - A platform attribute name.
+	 * @param {*} value - Its value; `null` removes it.
+	 * @returns {void}
+	 */
+	function setItemInfo(id, name, value) {
+		const info = itemInfo.get(id);
+		if (value == null) delete info[name];
+		else info[name] = value;
+		const list = lists.get(parentOf.get(id));
+		if (list != null) list.updateInfo(id, info);
+		if (!LIST_ITEM_VIRTUAL_ATTRIBUTES.includes(name)) __SetAttribute(handles.get(id), name, value == null ? null : value);
+	}
+
+	/**
+	 * Sends an Op.InvokeUIMethod result back to the background thread.
+	 * @param {number} callbackId - The background's callback id (never 0).
+	 * @param {number} code - `0` on success, the native error code otherwise.
+	 * @param {unknown} data - The method's result, or the error detail.
+	 * @returns {void}
+	 */
+	function sendInvokeResult(callbackId, code, data) {
+		onEvent?.(0, INVOKE_RESULT_EVENT, { callbackId, code, data });
+	}
+
+	/**
+	 * Runs the UI method calls queued by the patch just applied, in op order.
+	 * A call whose element was removed by the same patch is skipped (and its
+	 * caller told so); a SetInputValue made stale by a newer keystroke is
+	 * dropped.
+	 * @returns {boolean} Whether any native method was called.
+	 */
+	function runPendingInvokes() {
+		if (pendingInvokes.length === 0) return false;
+		const calls = pendingInvokes;
+		pendingInvokes = [];
+		let invoked = false;
+		for (const call of calls) {
+			const handle = handles.get(call.id);
+			if (handle == null) {
+				if (call.callbackId) sendInvokeResult(call.callbackId, -1, "mithril-lynx: the element was removed before the UI method could run");
+				continue;
+			}
+			const field = call.seq !== undefined ? fields.get(call.id) : undefined;
+			if (field != null) {
+				if (call.seq < field.seq) continue;
+				field.value = call.params.value;
+			}
+			if (typeof __InvokeUIMethod !== "function") {
+				if (call.callbackId) sendInvokeResult(call.callbackId, -1, "mithril-lynx: __InvokeUIMethod is not available on this runtime");
+				continue;
+			}
+			const callbackId = call.callbackId;
+			__InvokeUIMethod(handle, call.method, call.params ?? {}, (res) => {
+				if (callbackId) sendInvokeResult(callbackId, res?.code ?? 0, res?.data);
+			});
+			invoked = true;
+		}
+		return invoked;
+	}
+
 	/**
 	 * 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.
+	 * top-level applier per page, never looked up through a global. Every
+	 * native list that changed sends its `update-list-info` just before
+	 * that flush.
+	 * @param {unknown[]} ops - A flat op array (opcode followed by its arguments, repeated).
+	 * @returns {void}
+	 * @throws {Error} If an unknown opcode is encountered, or `Op.RemoveEvent` needs `__RemoveEventListener` and it is unavailable.
 	 */
 	function applyPatch(ops) {
 		for (let i = 0; i < ops.length; ) {
@@ -258,6 +475,14 @@ export function createPatchApplier(pageId, { onEvent, flush = true } = {}) {
 				case Op.CreateElement: {
 					const tag = ops[i++];
 					const id = ops[i++];
+					if (tag === "list") {
+						const list = createListRuntime(pageId);
+						lists.set(id, list);
+						handles.set(id, list.handle);
+						break;
+					}
+					if (tag === "list-item") itemInfo.set(id, {});
+					else if (FORM_FIELD_TAGS.includes(tag)) fields.set(id, { seq: 0, value: "", composing: false });
 					handles.set(id, createElementHandle(tag));
 					break;
 				}
@@ -284,18 +509,40 @@ export function createPatchApplier(pageId, { onEvent, flush = true } = {}) {
 					const refId = ops[i++];
 					const parent = handles.get(parentId);
 					const child = handles.get(childId);
-					if (refId === -1) {
+					const previousParentId = parentOf.get(childId);
+					const list = lists.get(parentId);
+					// Leaving a list for another parent: the old list drops it
+					// (and detaches it natively if it was on screen).
+					if (previousParentId !== undefined && previousParentId !== parentId) {
+						const previousList = lists.get(previousParentId);
+						if (previousList != null) previousList.remove(childId);
+						else if (list != null) __RemoveElement(handles.get(previousParentId), child);
+					}
+					if (list != null) {
+						// List children are attached natively only on demand.
+						list.insert(childId, child, itemInfo.get(childId) ?? {}, refId);
+					} else if (refId === -1) {
 						__AppendElement(parent, child);
 					} else {
 						__InsertElementBefore(parent, child, handles.get(refId));
 					}
+					// A move (the child already had a parent) detaches it from
+					// the old parent's set first.
+					if (previousParentId !== undefined) childrenOf.get(previousParentId)?.delete(childId);
+					let siblings = childrenOf.get(parentId);
+					if (siblings == null) childrenOf.set(parentId, (siblings = new Set()));
+					siblings.add(childId);
+					parentOf.set(childId, parentId);
 					break;
 				}
 				case Op.RemoveChild: {
 					const parentId = ops[i++];
 					const childId = ops[i++];
-					__RemoveElement(handles.get(parentId), handles.get(childId));
-					handles.delete(childId);
+					const list = lists.get(parentId);
+					if (list != null) list.remove(childId);
+					else __RemoveElement(handles.get(parentId), handles.get(childId));
+					childrenOf.get(parentId)?.delete(childId);
+					releaseSubtree(childId);
 					break;
 				}
 				case Op.SetAttribute: {
@@ -312,7 +559,11 @@ export function createPatchApplier(pageId, { onEvent, flush = true } = {}) {
 					// in this rewrite's own test suite had set `id` before.
 					if (name === "class") __SetClasses(handle, value == null ? "" : value);
 					else if (name === "id") __SetID(handle, value == null ? null : value);
-					else __SetAttribute(handle, name, value);
+					else if (itemInfo.has(id) && isListItemPlatformAttribute(name)) setItemInfo(id, name, value);
+					else {
+						if (name === "update-animation" && lists.has(id)) lists.get(id).setUpdateAnimation(value);
+						__SetAttribute(handle, name, value);
+					}
 					break;
 				}
 				case Op.RemoveAttribute: {
@@ -321,7 +572,11 @@ export function createPatchApplier(pageId, { onEvent, flush = true } = {}) {
 					const handle = handles.get(id);
 					if (name === "class") __SetClasses(handle, "");
 					else if (name === "id") __SetID(handle, null);
-					else __SetAttribute(handle, name, null);
+					else if (itemInfo.has(id) && isListItemPlatformAttribute(name)) setItemInfo(id, name, null);
+					else {
+						if (name === "update-animation" && lists.has(id)) lists.get(id).setUpdateAnimation(null);
+						__SetAttribute(handle, name, null);
+					}
 					break;
 				}
 				case Op.SetAttributeNS: {
@@ -342,14 +597,14 @@ export function createPatchApplier(pageId, { onEvent, flush = true } = {}) {
 				case Op.RemoveStyleProperty: {
 					const id = ops[i++];
 					const name = ops[i++];
-					// `"*"` is fake-dom.js's encoding of `element.style = ""`
-					// (clear everything) — there is no bulk-clear PAPI call
-					// validated yet, so this case is a documented gap for
-					// F3, not a silent no-op: it throws so the gap surfaces
-					// as a test failure rather than a mystery on-device.
+					// fake-dom.js expands `element.style = ""` into one op per
+					// applied property, so a bulk `"*"` name reaching here means
+					// a desynced or foreign op producer — a protocol invariant
+					// violation, not a gap to paper over.
 					if (name === "*") {
 						throw new Error(
-							"[mithril-lynx] Clearing the whole `style` object at once is not implemented yet (F3 TODO) — set individual properties to \"\" instead.",
+							"[mithril-lynx] Protocol error: bulk style clear ('*') should never reach apply-patch — " +
+								"fake-dom.js must expand it to individual RemoveStyleProperty ops.",
 						);
 					}
 					__AddInlineStyle(handles.get(id), name, "");
@@ -365,8 +620,27 @@ export function createPatchApplier(pageId, { onEvent, flush = true } = {}) {
 					const id = ops[i++];
 					const type = ops[i++];
 					const handle = handles.get(id);
+					/**
+					 * Forwards a native event to the background thread.
+					 * @param {*} nativeEvent - The native event object.
+					 * @returns {void}
+					 */
 					const listener = (nativeEvent) => {
-						onEvent?.(id, type, nativeEvent);
+						const field = fields.get(id);
+						if (field != null) {
+							if (type === "input") {
+								const detail = (nativeEvent && nativeEvent.detail) || {};
+								const value = typeof detail.value === "string" ? detail.value : field.value;
+								const composing = detail.isComposing === true;
+								if (value === field.value && composing === field.composing) return;
+								field.seq++;
+								field.value = value;
+								field.composing = composing;
+							}
+							onEvent?.(id, type, nativeEvent, field.seq);
+						} else {
+							onEvent?.(id, type, nativeEvent);
+						}
 					};
 					let byType = eventListeners.get(id);
 					if (byType == null) eventListeners.set(id, (byType = new Map()));
@@ -410,7 +684,10 @@ export function createPatchApplier(pageId, { onEvent, flush = true } = {}) {
 					const gestureType = ops[i++];
 					const arenaPolicy = ops[i++];
 					const handle = handles.get(id);
-					registerGestureDetector(handle, id, gestureId, gestureType, arenaPolicy, onEvent);
+					const workletIds = registerGestureDetector(handle, id, gestureId, gestureType, arenaPolicy, onEvent);
+					let byGesture = gestureWorklets.get(id);
+					if (byGesture == null) gestureWorklets.set(id, (byGesture = new Map()));
+					byGesture.set(gestureId, workletIds);
 					break;
 				}
 				case Op.RemoveGestureDetector: {
@@ -418,29 +695,46 @@ export function createPatchApplier(pageId, { onEvent, flush = true } = {}) {
 					const gestureId = ops[i++];
 					const handle = handles.get(id);
 					if (typeof __RemoveGestureDetector === "function") __RemoveGestureDetector(handle, gestureId);
+					const byGesture = gestureWorklets.get(id);
+					const workletIds = byGesture ? byGesture.get(gestureId) : undefined;
+					if (workletIds != null) {
+						unregisterWorklets(workletIds);
+						byGesture.delete(gestureId);
+						if (byGesture.size === 0) gestureWorklets.delete(id);
+					}
 					break;
 				}
-				case Op.CreateList: {
+				case Op.InvokeUIMethod: {
 					const id = ops[i++];
-					const scrollOrientation = ops[i++];
-					const listType = ops[i++];
-					const spanCount = ops[i++];
-					const { handle, setCells } = createNativeList(pageId, scrollOrientation, listType, spanCount, createPatchApplier, onEvent);
-					handles.set(id, handle);
-					listSetters.set(id, setCells);
+					const method = ops[i++];
+					const params = ops[i++];
+					const callbackId = ops[i++];
+					pendingInvokes.push({ id, method, params, callbackId });
 					break;
 				}
-				case Op.SetListItems: {
+				case Op.SetInputValue: {
 					const id = ops[i++];
-					const cells = ops[i++];
-					listSetters.get(id)(cells);
+					const value = ops[i++];
+					const seq = ops[i++];
+					pendingInvokes.push({ id, method: "setValue", params: { value }, callbackId: 0, seq });
 					break;
 				}
 				default:
 					throw new Error(`[mithril-lynx] Unknown patch opcode: ${opcode}`);
 			}
 		}
+		// Each list that changed tells native about it before the commit.
+		for (const list of lists.values()) list.flushUpdates();
 		if (flush) __FlushElementTree();
+		// On-screen items a list just removed can only be detached once native
+		// has processed that removal (see list-runtime.js's remove()).
+		let detached = false;
+		for (const list of lists.values()) if (list.detachRemoved()) detached = true;
+		if (detached && flush) __FlushElementTree();
+		// UI methods run once the elements they target exist natively; a
+		// method's own UI changes are committed by one more flush (the same
+		// invoke-then-flush order as ReactLynx's main-thread Element.invoke()).
+		if (runPendingInvokes() && flush) __FlushElementTree();
 	}
 
 	return {
@@ -454,9 +748,24 @@ export function createPatchApplier(pageId, { onEvent, flush = true } = {}) {
 		 * recording (mithril-lynx-v1's own installTestingPolyfills wraps
 		 * every `__`-prefixed call regardless of which package called it, so
 		 * this is how a v2 test finds "which of those calls targeted THIS
-		 * element") — never needed by application code. */
+		 * element") — never needed by application code.
+		 * @param {number} id - The background-side element id.
+		 * @returns {*} The real element handle, or `undefined` when none exists.
+		 */
 		getHandle(id) {
 			return handles.get(id);
 		},
+		/**
+		 * Neutralizes every native list's callbacks — for the page's
+		 * `__DestroyLifetime`, after which native must not call back into
+		 * this applier's state.
+		 * @returns {void}
+		 */
+		dispose() {
+			for (const list of lists.values()) list.destroy();
+			lists.clear();
+			fields.clear();
+			pendingInvokes = [];
+		},
 	};
 }