mithril-lynx 2.0.2 → 2.6.0

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

@@ -0,0 +1,13 @@
+// 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 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 };

package/src/list-support.js

@@ -0,0 +1,171 @@
+// src/list-support.js
+//
+// Runs ONLY on the main thread — the counterpart to list-cell.js's
+// background-thread half. Wires up the native list contract
+// (__CreateList/__UpdateListCallbacks, the synchronous componentAtIndex/
+// enqueueComponent pair, recycling cells by a type key) — unchanged from
+// mithril-lynx v1's own device-verified list.js.
+//
+// What's different from v1, and from this file's own first version: a
+// cell's content is never rendered here. `componentAtIndex` only replays
+// ops the background thread already computed (list-cell.js), the same way
+// apply-patch.js's own top-level applyPatch replays the app's own tree —
+// this file has no dependency on mithril-runtime, fake-dom.js, or a virtual
+// backend at all anymore, because it never runs a render pass of its own.
+// componentAtIndex(itemCount) cost is therefore the cost of creating/
+// updating real elements from an already-known op list, same as any other
+// patch — not a render.
+//
+// Recycling a cell for a different item clears its real children (removed
+// by the handle ids list-cell.js recorded — see clearWrapperChildren below)
+// and replays the new item's ops fresh; this is a real teardown-and-rebuild
+// of that cell's content, not a diff against what was there before. A real
+// Mithril diff on recycle would need a persistent per-slot fake-dom
+// document kept in sync with which native cell native actually chose to
+// reuse — information only native has, on the main thread, which the
+// background thread (where the diff would have to run) can't see without a
+// round trip. Not implemented.
+
+export function createNativeList(pageId, scrollOrientation, listType, spanCount, createPatchApplier, onEvent) {
+	let cells = []; // current cells, indexed by cellIndex — see patch-protocol.js's Op.SetListItems
+	let count = 0;
+	const signMap = new Map(); // sign -> { wrapperHandle, applier, rootChildIds, cellIndex, typeKey }
+	const recycleMap = new Map(); // typeKey -> Map<sign, entry> (entries currently off-screen, available to reuse)
+
+	function replayCell(wrapperHandle, cell) {
+		const applier = createPatchApplier(pageId, { onEvent, flush: false });
+		applier.registerRoot(cell.containerId, wrapperHandle);
+		applier.applyPatch(cell.ops);
+		return applier;
+	}
+
+	function clearWrapperChildren(entry) {
+		for (const id of entry.rootChildIds) {
+			const handle = entry.applier.getHandle(id);
+			if (handle != null) __RemoveElement(entry.wrapperHandle, handle);
+		}
+	}
+
+	function bindFreshItem(listHandle, listId, cellIndex, opId, cell, flush) {
+		const wrapperHandle = __CreateElement("list-item", pageId, {});
+		__SetAttribute(wrapperHandle, "item-key", String(cellIndex));
+		__AppendElement(listHandle, wrapperHandle);
+
+		const applier = replayCell(wrapperHandle, cell);
+		const sign = __GetElementUniqueID(wrapperHandle);
+		signMap.set(sign, { wrapperHandle, applier, rootChildIds: cell.rootChildIds, cellIndex, typeKey: cell.typeKey });
+		if (flush) __FlushElementTree(wrapperHandle, { triggerLayout: true, operationID: opId, elementID: sign, listID: listId });
+		return sign;
+	}
+
+	function bindRecycledItem(listId, cellIndex, opId, cell, pool, flush) {
+		const [sign, entry] = pool.entries().next().value;
+		pool.delete(sign);
+		clearWrapperChildren(entry);
+		__SetAttribute(entry.wrapperHandle, "item-key", String(cellIndex));
+		const applier = replayCell(entry.wrapperHandle, cell);
+		entry.applier = applier;
+		entry.rootChildIds = cell.rootChildIds;
+		entry.cellIndex = cellIndex;
+		signMap.set(sign, entry);
+		if (flush) __FlushElementTree(entry.wrapperHandle, { triggerLayout: true, operationID: opId, elementID: sign, listID: listId });
+		return sign;
+	}
+
+	function bindCell(listHandle, listId, cellIndex, opId, flush) {
+		if (cellIndex < 0 || cellIndex >= count) {
+			throw new Error(`[mithril-lynx] list: cellIndex ${cellIndex} out of range (itemCount=${count})`);
+		}
+		const cell = cells[cellIndex];
+		const pool = recycleMap.get(cell.typeKey);
+		if (pool && pool.size > 0) return bindRecycledItem(listId, cellIndex, opId, cell, pool, flush);
+		return bindFreshItem(listHandle, listId, cellIndex, opId, cell, flush);
+	}
+
+	function componentAtIndex(listHandle, listId, cellIndex, opId) {
+		return bindCell(listHandle, listId, cellIndex, opId, true);
+	}
+
+	/**
+	 * The batched form of componentAtIndex — real native calls this (not a
+	 * fallback: confirmed against `@lynx-js/react`'s own
+	 * componentAtIndexFactory/attachListItemAtIndex, which always registers
+	 * BOTH forms) for several cells at once, expecting exactly ONE
+	 * `__FlushElementTree` covering all of them (`operationIDs`/`elementIDs`
+	 * arrays), not one per cell — the real reason a native list's initial,
+	 * simultaneously-visible cells need this at all.
+	 */
+	function componentAtIndexes(listHandle, listId, cellIndexes, operationIDs) {
+		const elementIDs = cellIndexes.map((cellIndex, i) => bindCell(listHandle, listId, cellIndex, operationIDs[i], false));
+		__FlushElementTree(listHandle, { triggerLayout: true, operationIDs, elementIDs, listID: listId });
+	}
+
+	function enqueueComponent(_listHandle, _listId, sign) {
+		const entry = signMap.get(sign);
+		if (entry == null) return;
+		signMap.delete(sign);
+		if (!recycleMap.has(entry.typeKey)) recycleMap.set(entry.typeKey, new Map());
+		recycleMap.get(entry.typeKey).set(sign, entry);
+	}
+
+	function sendListInfo(listHandle, listId, insertAction, removeAction, updateAction) {
+		__SetAttribute(listHandle, "update-list-info", { insertAction, removeAction, updateAction });
+		__UpdateListCallbacks(listHandle, componentAtIndex, enqueueComponent, componentAtIndexes);
+	}
+
+	const listHandle = __CreateList(pageId, componentAtIndex, enqueueComponent, {}, componentAtIndexes);
+	const listId = __GetElementUniqueID(listHandle);
+	__SetAttribute(listHandle, "scroll-orientation", scrollOrientation);
+	__SetAttribute(listHandle, "list-type", listType);
+	__SetAttribute(listHandle, "span-count", String(spanCount));
+
+	// Re-flushes every currently-attached (on-screen) cell with its newest
+	// ops — e.g. after a redraw triggered by a tap inside a cell, or any
+	// other app state change that reaches this list's items. Unconditional,
+	// same as List's own onupdate already unconditionally resends the whole
+	// `items` array on every relevant redraw (see mithril-lynx-ui's
+	// list/list.js) — a real "did this cell's content actually change"
+	// check would need to compare `ops` arrays, not implemented yet. Cells
+	// that aren't attached right now just pick up their new content next
+	// time componentAtIndex asks for that index.
+	function refreshAttachedCells(nextCells) {
+		for (const [sign, entry] of signMap) {
+			const nextCell = nextCells[entry.cellIndex];
+			clearWrapperChildren(entry);
+			entry.applier = replayCell(entry.wrapperHandle, nextCell);
+			entry.rootChildIds = nextCell.rootChildIds;
+			entry.typeKey = nextCell.typeKey;
+			signMap.set(sign, entry);
+			__FlushElementTree(entry.wrapperHandle, { triggerLayout: false });
+		}
+	}
+
+	function setCells(nextCells) {
+		const nextCount = nextCells.length;
+		refreshAttachedCells(nextCells);
+		cells = nextCells;
+		if (nextCount === count) return;
+		if (nextCount > count) {
+			sendListInfo(
+				listHandle,
+				listId,
+				Array.from({ length: nextCount - count }, (_, i) => ({ position: count + i, type: "cell", "item-key": String(count + i) })),
+				[],
+				[],
+			);
+		} else {
+			sendListInfo(listHandle, listId, [], Array.from({ length: count - nextCount }, (_, i) => nextCount + i), []);
+		}
+		count = nextCount;
+	}
+
+	// Returned separately, not as a property stuck onto `listHandle` itself:
+	// confirmed on real hardware (unlike @lynx-js/testing-environment's
+	// simulated PAPI) that a native list's own returned handle does not
+	// reliably hold a custom property across calls — assigning one there
+	// and reading it back later from apply-patch.js's Op.SetListItems case
+	// threw "TypeError: not a function" on the very first SetListItems, even
+	// with zero items. apply-patch.js keeps `setCells` in its own map
+	// instead, keyed the same way `handles` already is.
+	return { handle: listHandle, setCells };
+}

package/src/mount-redraw.d.ts

@@ -0,0 +1,13 @@
+/** Called by `renderApp()` right after it creates its own redraw function.
+ * Public so a reusable component library (not just this package's own
+ * request.js) can trigger a redraw of whichever app is currently mounted
+ * after an async state change (a timer/animation callback, a promise) that
+ * didn't happen inside a real event handler — the case mithril-lynx's own
+ * auto-redraw-after-event contract doesn't cover. */
+export function register(redraw: () => void): void;
+
+/** No-op before any app has mounted. Scheduled, not synchronous — see
+ * mount-redraw.js's own header for why a synchronous call here would race
+ * a caller's own pending `.then()`/callback that hasn't stored its result
+ * yet. */
+export function redraw(): void;

package/src/mount-redraw.js

@@ -15,6 +15,13 @@
 // for the app's whole lifetime (plan §3.1), so "the current redraw
 // function" is a single slot, not a list.
 //
+// Also exported publicly (`mithril-lynx/mount-redraw`), not just used
+// internally by request.js — any reusable component (not just this
+// package's own code) that mutates state from an async callback outside a
+// real event handler (a timer, a promise, an animation frame) needs the
+// exact same "redraw whichever app is mounted" call this module already
+// provides; there is no reason to make library authors reinvent it.
+//
 // `redraw()` schedules instead of calling `currentRedraw()` inline — same
 // reason real Mithril's version schedules through the platform's
 // requestAnimationFrame instead of rendering synchronously: `request.js`'s

package/src/patch-protocol.js

@@ -28,6 +28,28 @@ export const Op = Object.freeze({
 	SetText: 11, // id, value (nodeValue on a text node)
 	AddEvent: 12, // id, type
 	RemoveEvent: 13, // id, type
+	// gestureId, gestureType, arenaPolicy — registers a real native gesture
+	// detector on the main thread. arenaPolicy is a small, JSON-serializable
+	// description of when to claim/release the gesture arena, evaluated
+	// synchronously on the main thread against just the event's own
+	// coordinates (no background-thread round trip) — see
+	// docs/native-papi/papi-05-native-gestures.md in mithril-lynx-ui for
+	// the full design writeup and why this is deliberately narrower than a
+	// generic remote-controller RPC. Resulting onTouchesDown/Move/Up events
+	// are forwarded to the background thread as plain events (type
+	// "gesturedown"/"gesturemove"/"gestureup"), through the exact same
+	// channel any other native event already uses — nothing new on the
+	// background-thread side.
+	SetGestureDetector: 14, // id, gestureId, gestureType, arenaPolicy
+	RemoveGestureDetector: 15, // id, gestureId
+	// A native virtualized list — see docs/native-papi/papi-06-virtualized-lists.md
+	// in mithril-lynx-ui for the full design. Each list item is rendered on
+	// the BACKGROUND thread, through the app's own real render pass
+	// (list-cell.js), same as everything else in the tree — the main thread
+	// never runs renderItem() itself, only replays the ops that rendering
+	// already produced (apply-patch.js's Op.CreateList case + list-support.js).
+	CreateList: 16, // id, scrollOrientation, listType, spanCount
+	SetListItems: 17, // id, cellsJSON — cellsJSON = JSON.stringify(cells), cells: Array<{ typeKey, containerId, ops, rootChildIds }>, one entry per current item, computed by list-cell.js's renderListCell(). `ops` is a flat op array in this SAME encoding, scoped to `containerId` as its root parent id.
 });
 
 /**
@@ -38,3 +60,43 @@ export const Op = Object.freeze({
 export function pushOp(ops, opcode, ...args) {
 	ops.push(opcode, ...args);
 }
+
+// How many argument slots follow each opcode — the single source of truth
+// for walking a flat ops array without re-interpreting it (apply-patch.js's
+// own switch increments `i` inline instead of using this table, since it
+// also needs to look at individual arg values as it goes; this exists for
+// callers that only need to skip/scan, e.g. list-cell.js's
+// findTopLevelChildIds(), which never applies the ops itself).
+export const OP_ARITY = Object.freeze({
+	[Op.CreateElement]: 2, // tag, id
+	[Op.CreateElementNS]: 3, // ns, tag, id
+	[Op.CreateText]: 2, // value, id
+	[Op.CreateFragment]: 1, // id (never actually emitted — see fake-dom.js's LynxFragment)
+	[Op.InsertBefore]: 3, // parentId, childId, refId
+	[Op.RemoveChild]: 2, // parentId, childId
+	[Op.SetAttribute]: 3, // id, name, value
+	[Op.RemoveAttribute]: 2, // id, name
+	[Op.SetAttributeNS]: 4, // id, ns, name, value
+	[Op.SetStyleProperty]: 3, // id, name, value
+	[Op.RemoveStyleProperty]: 2, // id, name
+	[Op.SetText]: 2, // id, value
+	[Op.AddEvent]: 2, // id, type
+	[Op.RemoveEvent]: 2, // id, type
+	[Op.SetGestureDetector]: 4, // id, gestureId, gestureType, arenaPolicy
+	[Op.RemoveGestureDetector]: 2, // id, gestureId
+	[Op.CreateList]: 4, // id, scrollOrientation, listType, spanCount
+	[Op.SetListItems]: 2, // id, cellsJSON
+});
+
+/** Walks a flat ops array, calling `visit(opcode, args)` once per op — args
+ * is the plain slice of that op's own arguments (not including the opcode
+ * itself). Throws on an unknown opcode rather than silently desyncing. */
+export function forEachOp(ops, visit) {
+	for (let i = 0; i < ops.length; ) {
+		const opcode = ops[i++];
+		const arity = OP_ARITY[opcode];
+		if (arity === undefined) throw new Error(`[mithril-lynx] Unknown patch opcode: ${opcode}`);
+		visit(opcode, ops.slice(i, i + arity));
+		i += arity;
+	}
+}

package/src/testing.d.ts

@@ -0,0 +1,16 @@
+export interface PatchApplier {
+	registerPageRoot(pageRootHandle: unknown): void;
+	applyPatch(ops: unknown[]): void;
+	/** The real PAPI element handle for a given background-side id, or
+	 * `undefined` if nothing was ever created for it. */
+	getHandle(id: unknown): unknown;
+}
+
+/** See apply-patch.js's own header for the exact op vocabulary this replays. */
+export function createPatchApplier(pageId: unknown, options?: { onEvent?: (id: unknown, type: string, payload: unknown) => void }): PatchApplier;
+
+/** Installs the @lynx-js/testing-environment PAPI gap-fill mithril-lynx
+ * needs, on the main-thread globals object it hands to
+ * `onInjectMainThreadGlobals`. See testing.js's own header for exactly what
+ * this covers. */
+export function installTestingPolyfills(target: any): void;

package/src/testing.js

@@ -0,0 +1,48 @@
+// src/testing.js
+//
+// Reusable @lynx-js/testing-environment PAPI polyfill + patch applier for
+// apps/libraries built on mithril-lynx, not just this package's own test
+// suite — same reason the previous mithril-lynx exposed its own
+// mithril-lynx/testing: a separate package (mithril-lynx-ui, or any app)
+// needs the exact same gap-fill to write a REAL end-to-end test (mount via
+// renderApp(), replay the resulting ops onto real Element PAPI via
+// @lynx-js/testing-environment, dispatch a real event) rather than mocking
+// mithril-lynx itself.
+//
+// Usage, in a test setup file (e.g. test/setup.ts):
+//
+//   import { installTestingPolyfills } from "mithril-lynx/testing";
+//   globalThis.onInjectMainThreadGlobals = installTestingPolyfills;
+//
+// createPatchApplier is re-exported here too — it's what a test needs to
+// actually replay a renderApp() root's ops onto real PAPI elements (see
+// this package's own test/end-to-end.test.ts for the full pattern); it has
+// no other public export point.
+
+export { createPatchApplier } from "./apply-patch.js";
+
+/**
+ * Installs the polyfill on the main-thread globals object
+ * @lynx-js/testing-environment hands to onInjectMainThreadGlobals. Scoped
+ * to exactly what apply-patch.js calls (no gesture/list support — those
+ * don't exist in mithril-lynx yet, see the main README's known gaps):
+ * @lynx-js/testing-environment already implements __CreateView/__CreateText/
+ * __CreateElement/__CreateRawText/__AppendElement/__InsertElementBefore/
+ * __RemoveElement/__SetAttribute/__SetClasses/__AddInlineStyle/
+ * __FlushElementTree/__GetElementUniqueID — the one real gap is
+ * __AddEventListener (the testing environment only implements the
+ * string/worklet-event __AddEvent family that ReactLynx uses; mithril-lynx
+ * binds real JS function listeners directly).
+ */
+export function installTestingPolyfills(target) {
+	target.lynx.getEngine = target.lynx.getNative;
+
+	target.__AddEventListener = (node, name, handler) => {
+		node.__vanillaListeners ??= {};
+		(node.__vanillaListeners[name] ??= new Set()).add(handler);
+	};
+
+	target.__RemoveEventListener = (node, name, handler) => {
+		node.__vanillaListeners?.[name]?.delete(handler);
+	};
+}

package/test/gesture.test.ts

@@ -0,0 +1,175 @@
+import { describe, expect, it } from "@rstest/core";
+import m from "mithril";
+import { renderApp } from "../src/background.js";
+import { createPatchApplier } from "../src/apply-patch.js";
+
+// Op.SetGestureDetector end-to-end: a component calls vnode.dom's own
+// setGestureDetector() (fake-dom.js) in oncreate, the resulting op gets
+// replayed onto a REAL simulated __SetGestureDetector call (via
+// @lynx-js/testing-environment, not a mock), and the arena-claim policy
+// (apply-patch.js's own createArenaTracker) is exercised by extracting the
+// registered worklet callbacks and invoking them the same way native would
+// — see mithril-lynx-ui's docs/native-papi/papi-05-native-gestures.md for
+// the full design writeup this implements.
+
+function gestureCallbacksOf(handle: any): Record<string, (event: unknown, controller: unknown) => void> {
+	const entries = handle.gesture.config.callbacks as { name: string; callback: unknown }[];
+	const out: Record<string, (event: unknown, controller: unknown) => void> = {};
+	for (const entry of entries) {
+		out[entry.name] = (event, controller) => (globalThis as any).runWorklet(entry.callback, [event, controller]);
+	}
+	return out;
+}
+
+function touchEvent(clientX: number, clientY: number) {
+	return { params: { clientX, clientY } };
+}
+
+function makeController() {
+	const calls: { fn: string; args: unknown[] }[] = [];
+	return {
+		calls,
+		__SetGestureState(...args: unknown[]) {
+			calls.push({ fn: "__SetGestureState", args });
+		},
+		__ConsumeGesture(...args: unknown[]) {
+			calls.push({ fn: "__ConsumeGesture", args });
+		},
+	};
+}
+
+function mountWithGesture(arenaPolicy: unknown) {
+	lynxTestingEnv.switchToMainThread();
+	const pageId = __GetElementUniqueID(__CreatePage());
+	const receivedEvents: { type: string; clientX: number; clientY: number }[] = [];
+	const applier = createPatchApplier(pageId, {
+		onEvent: (id, type, payload: any) => {
+			receivedEvents.push({ type, clientX: payload.clientX, clientY: payload.clientY });
+		},
+	});
+	applier.registerPageRoot(__CreateView(pageId));
+
+	lynxTestingEnv.switchToBackgroundThread();
+	let lastOps: unknown[] | null = null;
+	const app = renderApp({
+		root: () => m("view", { class: "target", oncreate: (vnode: any) => vnode.dom.setGestureDetector("native", arenaPolicy) }),
+		sendPatch: (ops) => {
+			lastOps = ops;
+		},
+	});
+
+	lynxTestingEnv.switchToMainThread();
+	applier.applyPatch(lastOps as unknown[]);
+
+	const handle = applier.getHandle(1);
+	return { handle, callbacks: gestureCallbacksOf(handle), receivedEvents };
+}
+
+describe("Op.SetGestureDetector (native gesture support)", () => {
+	it("registers a real __SetGestureDetector call with the given type", () => {
+		const { handle } = mountWithGesture({ mode: "claim" });
+		expect(handle.gesture.type).toBe(7); // GESTURE_TYPE_CODES.native
+	});
+
+	it('"claim" policy claims on touches-down and never reconsiders', () => {
+		const { callbacks } = mountWithGesture({ mode: "claim" });
+		const controller = makeController();
+
+		callbacks.onTouchesDown(touchEvent(0, 0), controller);
+		callbacks.onTouchesMove(touchEvent(50, 0), controller);
+		callbacks.onTouchesMove(touchEvent(0, 50), controller); // even a vertical move — no reconsideration
+
+		expect(controller.calls).toEqual([{ fn: "__ConsumeGesture", args: [expect.anything(), expect.any(Number), { consume: true, inner: false }] }]);
+	});
+
+	it('"axis-lock" (referenceMoves: 0) decides on the first move, using touches-down as the reference', () => {
+		const { callbacks } = mountWithGesture({ mode: "axis-lock", axis: "horizontal", referenceMoves: 0 });
+		const controller = makeController();
+
+		callbacks.onTouchesDown(touchEvent(0, 0), controller);
+		callbacks.onTouchesMove(touchEvent(40, 5), controller); // mostly horizontal
+
+		expect(controller.calls.map((c) => c.fn)).toEqual(["__ConsumeGesture", "__ConsumeGesture"]);
+		expect(controller.calls[1].args[2]).toEqual({ consume: true, inner: false });
+	});
+
+	it('"axis-lock" releases and fails the gesture when the losing axis wins', () => {
+		const { callbacks } = mountWithGesture({ mode: "axis-lock", axis: "horizontal", referenceMoves: 0 });
+		const controller = makeController();
+
+		callbacks.onTouchesDown(touchEvent(0, 0), controller);
+		callbacks.onTouchesMove(touchEvent(5, 40), controller); // mostly vertical
+
+		// Claim eagerly on down, release once the axis loses, THEN fail —
+		// releasing the claim before failing matters: an ancestor (e.g. a
+		// <scroll-view>) must see the arena freed, not just "this gesture gave up".
+		expect(controller.calls.map((c) => c.fn)).toEqual(["__ConsumeGesture", "__ConsumeGesture", "__SetGestureState"]);
+		expect(controller.calls[1].args[2]).toEqual({ consume: false, inner: false });
+		expect(controller.calls[2].args[2]).toBe(2); // GestureState.fail (args: [handle, gestureId, state])
+	});
+
+	it('"axis-lock" (referenceMoves: 1) uses the first move as reference and decides on the second', () => {
+		const { callbacks } = mountWithGesture({ mode: "axis-lock", axis: "horizontal", referenceMoves: 1 });
+		const controller = makeController();
+
+		callbacks.onTouchesDown(touchEvent(0, 0), controller);
+		callbacks.onTouchesMove(touchEvent(10, 10), controller); // just records the reference — no decision yet
+		expect(controller.calls.map((c) => c.fn)).toEqual(["__ConsumeGesture"]);
+
+		callbacks.onTouchesMove(touchEvent(60, 15), controller); // horizontal relative to the FIRST move
+		expect(controller.calls.map((c) => c.fn)).toEqual(["__ConsumeGesture", "__ConsumeGesture"]);
+	});
+
+	it("forwards touches-down/move/up to the background thread as gesturedown/gesturemove/gestureup events", () => {
+		const { callbacks, receivedEvents } = mountWithGesture({ mode: "claim" });
+		const controller = makeController();
+
+		callbacks.onTouchesDown(touchEvent(1, 2), controller);
+		callbacks.onTouchesMove(touchEvent(3, 4), controller);
+		callbacks.onTouchesUp(touchEvent(5, 6), controller);
+
+		expect(receivedEvents).toEqual([
+			{ type: "gesturedown", clientX: 1, clientY: 2 },
+			{ type: "gesturemove", clientX: 3, clientY: 4 },
+			{ type: "gestureup", clientX: 5, clientY: 6 },
+		]);
+	});
+
+	it("a forwarded gesture event reaches the background-thread fake-dom node like any other event", () => {
+		lynxTestingEnv.switchToMainThread();
+		const pageId = __GetElementUniqueID(__CreatePage());
+		let forward: ((id: number, type: string, payload: unknown) => void) | null = null;
+		const applier = createPatchApplier(pageId, {
+			onEvent: (id, type, payload) => forward?.(id, type, payload),
+		});
+		applier.registerPageRoot(__CreateView(pageId));
+
+		lynxTestingEnv.switchToBackgroundThread();
+		const moves: number[] = [];
+		let lastOps: unknown[] | null = null;
+		const app = renderApp({
+			root: () =>
+				m("view", {
+					class: "target",
+					oncreate: (vnode: any) => vnode.dom.setGestureDetector("native", { mode: "claim" }),
+					ongesturemove: (e: any) => moves.push(e.clientX),
+				}),
+			sendPatch: (ops) => {
+				lastOps = ops;
+			},
+		});
+		forward = (id, type, payload: any) => {
+			const node = app.document.getNodeById(id);
+			node?.dispatchEvent({ type, currentTarget: node, ...payload });
+		};
+
+		lynxTestingEnv.switchToMainThread();
+		applier.applyPatch(lastOps as unknown[]);
+		const handle = applier.getHandle(1);
+		const callback = gestureCallbacksOf(handle).onTouchesMove;
+		const controller = makeController();
+		callback(touchEvent(42, 0), controller);
+
+		expect(moves).toEqual([42]);
+	});
+});