mithril-lynx 2.5.0 → 2.6.2

package/src/list-support.js

@@ -1,153 +1,175 @@
 // src/list-support.js
 //
-// Runs ONLY on the main thread — imported from an app's own main-thread.ts,
-// alongside setupRenderer() (see docs/native-papi/papi-06-virtualized-lists.md
-// in mithril-lynx-ui for the full design). Registers the render function(s)
-// a native virtualized list needs: the function itself can never cross the
-// background-thread/main-thread boundary (real main and background threads
-// are separate JS engine instances — no shared closures, only serializable
-// messages), so an app registers it here by a string key instead, and
-// mithril-lynx-ui's List component references that same key from
-// background.ts.
+// 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.
 //
-// The native list contract this wires up (__CreateList/__UpdateListCallbacks,
-// the synchronous componentAtIndex/enqueueComponent pair, recycling cells by
-// a type key) is unchanged from mithril-lynx v1's own list.js — that part
-// was already device-verified. What's different: each cell is rendered by a
-// REAL, self-contained render pass entirely on THIS thread (the exact same
-// pieces background.js uses for the app's own tree — mithril-runtime's real
-// render(), fake-dom.js, a virtual backend — just applied to itself
-// immediately via a nested patch applier, instead of crossing a channel).
-// componentAtIndex's native contract is synchronous; a cross-thread round
-// trip could never satisfy that, so this is the only architecture that can.
+// 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.
 //
-// KNOWN GAP, not solved by this file: an event handler (e.g. `ontap`)
-// inside a renderItem()-produced vnode fires entirely on this thread, with
-// no way back to the app's own state on the background thread — there is
-// no background-thread fake-dom node for list cell content to dispatch
-// through (unlike every other element in the app, which the background
-// thread DOES know about). Reaching back into app state from inside a list
-// cell needs a deliberate reporting convention, not built here yet.
-
-import renderFactory from "mithril-runtime/render/render.js";
-import { createLynxDocument } from "./fake-dom.js";
-import { createVirtualBackend } from "./backends/virtual-backend.js";
-
-const renderers = new Map();
-
-/** Call once per list your app uses, from main-thread.ts — see this file's
- * own header for why the render function itself can't just be imported
- * from background.ts and passed across directly. */
-export function registerListRenderer(key, renderItem) {
-	renderers.set(key, renderItem);
-}
-
-function typeKeyOf(vnode) {
-	return typeof vnode.tag === "string" ? vnode.tag : (vnode.tag && vnode.tag.name) || "default";
-}
-
-function makeCell(pageId, wrapperHandle, createPatchApplier) {
-	const backend = createVirtualBackend();
-	const document = createLynxDocument(backend);
-	const render = renderFactory();
-	const applier = createPatchApplier(pageId);
-	applier.registerPageRoot(wrapperHandle);
-	return { wrapper: wrapperHandle, backend, document, render, applier, typeKey: null };
-}
+// 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;
+	}
 
-/** Re-renders `vnode` into `cell`'s own persistent fake-dom document —
- * Mithril's own diff (real, not simulated) computes the minimal update
- * against whatever this cell showed before, exactly like a normal redraw,
- * so recycling a cell for a different item never needs a manual "clear
- * old content first" step. */
-function renderCellVnode(cell, vnode) {
-	cell.render(cell.document, [vnode], () => {});
-	const ops = cell.backend.takeOps();
-	if (ops) cell.applier.applyPatch(ops);
-}
+	function clearWrapperChildren(entry) {
+		for (const id of entry.rootChildIds) {
+			const handle = entry.applier.getHandle(id);
+			if (handle != null) __RemoveElement(entry.wrapperHandle, handle);
+		}
+	}
 
-/**
- * @param {number} pageId
- * @param {string} rendererKey
- * @param {(pageId: number, options?: {onEvent?: Function}) => object} createPatchApplier
- *   - passed in rather than imported, to avoid a circular import with
- *   apply-patch.js (the only caller).
- * @param {Function} [onEvent] - forwarded into each cell's own patch
- *   applier, same as the top-level one — see this file's own "known gap"
- *   note above for what this does NOT yet solve.
- */
-export function createNativeList(pageId, rendererKey, scrollOrientation, listType, spanCount, createPatchApplier, onEvent) {
-	const renderItem = renderers.get(rendererKey);
-	if (renderItem == null) {
-		throw new Error(
-			`[mithril-lynx] no list renderer registered for "${rendererKey}" — call registerListRenderer("${rendererKey}", ...) from main-thread.ts.`,
-		);
+	/** The wrapper of the lowest currently-attached cellIndex greater than
+	 * `cellIndex`, or null if none — the DOM position a cell at `cellIndex`
+	 * needs to be inserted before to land in the right place. Native lays
+	 * cells out in document-tree order, not by `item-key`, so a recycled
+	 * wrapper that keeps its OLD tree position (this file's own first
+	 * version never repositioned it at all) shows up out of order the
+	 * moment it's reused for a different index — confirmed on real
+	 * hardware via a scrambled child order after scrolling (item-keys
+	 * 7,8,9,3,4,5,6). Same problem `@lynx-js/react`'s own
+	 * `attachListItemAtIndex`/`findNextAttachedItem` solves for its
+	 * Element Template list. */
+	function findNextAttachedWrapper(cellIndex) {
+		let best = null;
+		for (const entry of signMap.values()) {
+			if (entry.cellIndex > cellIndex && (best == null || entry.cellIndex < best.cellIndex)) best = entry;
+		}
+		return best ? best.wrapperHandle : null;
 	}
 
-	let items = [];
-	let count = 0;
-	const recycleMap = new Map(); // typeKey -> Map<sign, cell>
-	const signMap = new Map(); // sign -> cell
+	function attachWrapper(listHandle, wrapperHandle, cellIndex) {
+		const refHandle = findNextAttachedWrapper(cellIndex);
+		if (refHandle != null) __InsertElementBefore(listHandle, wrapperHandle, refHandle);
+		else __AppendElement(listHandle, wrapperHandle);
+	}
 
-	function bindFreshItem(listHandle, listId, cellIndex, opId, vnode, typeKey) {
+	function bindFreshItem(listHandle, listId, cellIndex, opId, cell, flush) {
 		const wrapperHandle = __CreateElement("list-item", pageId, {});
 		__SetAttribute(wrapperHandle, "item-key", String(cellIndex));
-		__AppendElement(listHandle, wrapperHandle);
-
-		const cell = makeCell(pageId, wrapperHandle, (pid) => createPatchApplier(pid, { onEvent }));
-		cell.typeKey = typeKey;
-		renderCellVnode(cell, vnode);
+		attachWrapper(listHandle, wrapperHandle, cellIndex);
 
+		const applier = replayCell(wrapperHandle, cell);
 		const sign = __GetElementUniqueID(wrapperHandle);
-		signMap.set(sign, cell);
-		__FlushElementTree(wrapperHandle, { triggerLayout: true, operationID: opId, elementID: sign, listID: listId });
+		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, vnode, typeKey, pool) {
-		const [sign, cell] = pool.entries().next().value;
+	function bindRecycledItem(listHandle, listId, cellIndex, opId, cell, pool, flush) {
+		const [sign, entry] = pool.entries().next().value;
 		pool.delete(sign);
-		__SetAttribute(cell.wrapper, "item-key", String(cellIndex));
-		cell.typeKey = typeKey;
-		renderCellVnode(cell, vnode);
-		signMap.set(sign, cell);
-		__FlushElementTree(cell.wrapper, { triggerLayout: true, operationID: opId, elementID: sign, listID: listId });
+		clearWrapperChildren(entry);
+		__SetAttribute(entry.wrapperHandle, "item-key", String(cellIndex));
+		attachWrapper(listHandle, entry.wrapperHandle, 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 componentAtIndex(listHandle, listId, cellIndex, opId) {
+	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 vnode = renderItem(items[cellIndex], cellIndex);
-		const typeKey = typeKeyOf(vnode);
-		const pool = recycleMap.get(typeKey);
-		if (pool && pool.size > 0) return bindRecycledItem(listId, cellIndex, opId, vnode, typeKey, pool);
-		return bindFreshItem(listHandle, listId, cellIndex, opId, vnode, typeKey);
+		const cell = cells[cellIndex];
+		const pool = recycleMap.get(cell.typeKey);
+		if (pool && pool.size > 0) return bindRecycledItem(listHandle, 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 cell = signMap.get(sign);
-		if (cell == null) return;
+		const entry = signMap.get(sign);
+		if (entry == null) return;
 		signMap.delete(sign);
-		if (!recycleMap.has(cell.typeKey)) recycleMap.set(cell.typeKey, new Map());
-		recycleMap.get(cell.typeKey).set(sign, cell);
+		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);
+		__UpdateListCallbacks(listHandle, componentAtIndex, enqueueComponent, componentAtIndexes);
 	}
 
-	const listHandle = __CreateList(pageId, componentAtIndex, enqueueComponent, {});
+	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));
 
-	listHandle.__setItems = (nextItems) => {
-		const nextCount = nextItems.length;
-		items = nextItems;
+	// 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(
@@ -161,7 +183,15 @@ export function createNativeList(pageId, rendererKey, scrollOrientation, listTyp
 			sendListInfo(listHandle, listId, [], Array.from({ length: count - nextCount }, (_, i) => nextCount + i), []);
 		}
 		count = nextCount;
-	};
+	}
 
-	return listHandle;
+	// 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/main-thread.js

@@ -10,6 +10,7 @@
 // was never part of the bug this rewrite exists to fix.
 
 import { createPatchApplier } from "./apply-patch.js";
+import { PROTOCOL_VERSION } from "./patch-protocol.js";
 import {
 	destroyLifetimeEventName,
 	onPatchFromBackground,
@@ -39,11 +40,23 @@ export function setupRenderer() {
 	let pendingPatches = [];
 
 	const onPatch = (event) => {
+		const data = event.data;
+		if (!Array.isArray(data) || data[0] !== PROTOCOL_VERSION) {
+			throw new Error(
+				`[mithril-lynx] patch protocol mismatch: expected version ${PROTOCOL_VERSION}, ` +
+					`got ${Array.isArray(data) ? String(data[0]) : typeof data}. ` +
+					"This is always a stale/desynced bundle (partial HMR or a cached main-thread chunk) — " +
+					"rebuild both bundles together.",
+			);
+		}
+		// Strip the version prefix so applyPatch() still receives the bare
+		// flat op array the rest of the protocol documents.
+		const ops = data.slice(1);
 		if (!pageReady) {
-			pendingPatches.push(event.data);
+			pendingPatches.push(ops);
 			return;
 		}
-		applier.applyPatch(event.data);
+		applier.applyPatch(ops);
 	};
 	onPatchFromBackground(onPatch);
 

package/src/mount-redraw.d.ts

@@ -6,6 +6,16 @@
  * auto-redraw-after-event contract doesn't cover. */
 export function register(redraw: () => void): void;
 
+/** Clears the current redraw registration (and the pending debounce flag).
+ * Fail-fast counterpart to {@link register}: a second `register()` throws,
+ * so call this on teardown or full reload before mounting a new app. */
+export function unregister(): void;
+
+/** Overrides the debounce delay `redraw()` uses (default 50ms — see the
+ * `mount-redraw.js` header for why it is an empirical margin, not a
+ * scheduling guarantee). */
+export function configure(options?: { redrawDelayMs?: number }): 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

package/src/mount-redraw.js

@@ -48,16 +48,68 @@ const REDRAW_DELAY_MS = 50;
 
 let currentRedraw = null;
 let pending = false;
+/** Handle of the currently-scheduled redraw timer, so `unregister()` can
+ * cancel it instead of leaving a stray callback that fires into a later
+ * mount. */
+let pendingTimer = null;
+/** Overridable via {@link configure}; defaults to REDRAW_DELAY_MS. */
+let redrawDelayMs = REDRAW_DELAY_MS;
+
+/**
+ * Overrides the debounce delay `redraw()` uses. Defaults to `REDRAW_DELAY_MS`
+ * (50ms) — the empirically-chosen margin documented at the top of this file,
+ * which is a safety margin rather than a scheduling guarantee. A device whose
+ * timer behaves differently (see FETCH_INVESTIGATION.md §4.6) can raise or
+ * lower it here.
+ */
+export function configure(options) {
+	if (options && options.redrawDelayMs != null) {
+		redrawDelayMs = options.redrawDelayMs;
+	}
+}
 
 function schedule(fn) {
 	const timer = typeof lynx !== "undefined" && typeof lynx.setTimeout === "function" ? lynx.setTimeout.bind(lynx) : setTimeout;
-	timer(fn, REDRAW_DELAY_MS);
+	return timer(fn, redrawDelayMs);
 }
 
+/**
+ * Registers the current app's redraw. Fail-fast: throws if a redraw is
+ * already registered, because a second live `renderApp()` in the same
+ * background context would silently overwrite the slot and let two
+ * documents corrupt the shared id space (see R2 in
+ * informe-contrato-mithril-lynx.md). Call {@link unregister} on teardown
+ * or full reload before registering a new one.
+ */
 export function register(redraw) {
+	if (currentRedraw != null) {
+		throw new Error(
+			"[mithril-lynx] redraw already registered — a shim instance is single-use: " +
+				"one renderApp() per background context, one redraw slot, for the " +
+				"lifetime of that context. Call unregister() (or do a full reload) " +
+				"before mounting a new app.",
+		);
+	}
 	currentRedraw = redraw;
 }
 
+/**
+ * Clears the current redraw registration (and the pending debounce flag) —
+ * used by a full reload and by the test suite between mounts. After this,
+ * `redraw()` is a no-op again until the next `register()`.
+ */
+export function unregister() {
+	currentRedraw = null;
+	pending = false;
+	if (pendingTimer != null) {
+		const clear = typeof lynx !== "undefined" && typeof lynx.clearTimeout === "function"
+			? lynx.clearTimeout.bind(lynx)
+			: clearTimeout;
+		clear(pendingTimer);
+		pendingTimer = null;
+	}
+}
+
 /** What `request.js` calls after a non-background request resolves. A
  * no-op before any app has mounted — a request kicked off before
  * renderApp()/route() ran has nothing to redraw yet, which isn't
@@ -67,7 +119,8 @@ export function register(redraw) {
 export function redraw() {
 	if (pending) return;
 	pending = true;
-	schedule(() => {
+	pendingTimer = schedule(() => {
+		pendingTimer = null;
 		pending = false;
 		if (currentRedraw != null) currentRedraw();
 	});

package/src/patch-protocol.js

@@ -13,6 +13,20 @@
 // main-thread side by `applyPatch()` (see backends/papi-backend.js), so
 // nodes never need to be looked up by anything other than that integer.
 
+/**
+ * The wire protocol version, prepended to every patch by
+ * `sendPatchToMainThread()` and validated (then stripped) by the main
+ * thread before any op is interpreted. The two bundles are normally built
+ * from the same source, but a partial HMR or a cached main-thread bundle
+ * could otherwise re-interpret a reordered opcode silently — a version
+ * mismatch throws instead of corrupting the mirrored id space.
+ *
+ * The value is deliberately outside the 0..17 opcode range (0x4d4c = "ML"
+ * in ASCII) so a versioned array can never be misread as an op sequence if
+ * it is ever fed to `applyPatch()` without the strip.
+ */
+export const PROTOCOL_VERSION = 0x4d4c;
+
 export const Op = Object.freeze({
 	CreateElement: 0,
 	CreateElementNS: 1,
@@ -43,12 +57,13 @@ export const Op = Object.freeze({
 	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. rendererKey looks up a
-	// render function registered on the MAIN thread (mithril-lynx/
-	// list-support's registerListRenderer()) — the function itself can't
-	// cross the thread boundary, only this string key can.
-	CreateList: 16, // id, rendererKey, scrollOrientation, listType, spanCount
-	SetListItems: 17, // id, itemsJSON (items must be JSON-serializable — they DO cross the boundary, as data)
+	// 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, 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.
 });
 
 /**
@@ -59,3 +74,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, cells
+});
+
+/** 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/request.d.ts

@@ -10,6 +10,8 @@ export interface RequestOptions<T = any> {
 	serialize?: (data: unknown) => string;
 	deserialize?: (data: unknown) => unknown;
 	extract?: (response: unknown, options: RequestOptions<T>) => unknown;
+	/** A constructor applied to the response: per element when the response
+	 * is an array (matching real `m.request`), otherwise to the whole result. */
 	type?: new (data: any) => T;
 	background?: boolean;
 	// Present on the real m.request signature but confirmed unsupported —

package/src/request.js

@@ -112,9 +112,13 @@ export function createRequestor(fetchImpl) {
 		// controller so a caller-provided signal and our timeout can both
 		// trigger the same abort.
 		const ctrl = new AbortController();
+		// Stored so the listener can be detached on settle (see detachSignal
+		// below) — a long-lived shared AbortSignal would otherwise accumulate
+		// one dead closure per request.
+		const abortHandler = () => ctrl.abort();
 		if (options.signal) {
 			if (options.signal.aborted) ctrl.abort();
-			else options.signal.addEventListener("abort", () => ctrl.abort());
+			else options.signal.addEventListener("abort", abortHandler);
 		}
 		let timeoutId;
 		if (options.timeout) {
@@ -138,8 +142,10 @@ export function createRequestor(fetchImpl) {
 
 			if (typeof options.extract === "function") {
 				// Matches real m.request: extract() bypasses the status check
-				// entirely — it decides success/failure itself.
-				return options.extract(response, options);
+				// entirely — it decides success/failure itself. `type` is still
+				// applied afterwards, exactly as upstream does (extract does NOT
+				// skip the type constructor).
+				return applyType(options.extract(response, options), options.type);
 			}
 
 			const ok = response.ok || response.status === 304;
@@ -156,12 +162,24 @@ export function createRequestor(fetchImpl) {
 			});
 		});
 
+		// Detach the caller's signal listener once this request settles, so a
+		// long-lived shared AbortSignal doesn't accumulate a dead closure per
+		// request. Done inside the settled handlers (rather than a separate
+		// `.then`) so an ignored rejection still surfaces as unhandled.
+		const detachSignal = () => {
+			if (options.signal && !options.signal.aborted) {
+				options.signal.removeEventListener("abort", abortHandler);
+			}
+		};
+
 		const result = promise.then(
 			(value) => {
+				detachSignal();
 				if (options.background !== true) sharedRedraw();
 				return value;
 			},
 			(error) => {
+				detachSignal();
 				clearRequestTimeout();
 				if (options.background !== true) sharedRedraw();
 				throw error;

package/src/route.d.ts

@@ -1,4 +1,14 @@
-import type { Component } from "mithril";
+/**
+ * Minimal Mithril-style component type. Declared locally because this
+ * package's runtime peer is `mithril-runtime`, which ships no TypeScript
+ * types of its own; the previous `import type { Component } from "mithril"`
+ * depended on an undeclared module. `view`'s return is typed `any` so
+ * `route.Link` stays assignable to a caller's own `m()` typed against
+ * `@types/mithril`.
+ */
+export interface Component<Attrs = unknown> {
+	view(vnode: { attrs: Attrs; children?: unknown }): any;
+}
 
 export interface RouteResolver {
 	onmatch?(args: Record<string, string>, requestedPath: string, route: string): unknown;
@@ -19,9 +29,18 @@ export interface Route {
 	(defaultRoute: string, routes: Record<string, unknown | RouteResolver>): void;
 	set(path: string, data?: unknown, options?: { replace?: boolean }): void;
 	get(): string | undefined;
+	/** Returns the named route parameter (with `key`), or the whole params
+	 * object (without). Typed `unknown` because the value can be a string
+	 * (path params), a string|boolean (query params — `"true"`/`"false"` are
+	 * coerced), or anything passed as `data` to `set(path, data)`; the common
+	 * path-param case is always a string. */
 	param(key?: string): unknown;
-	back(): void;
-	forward(): void;
+	/** Walks back one entry; returns `false` (without navigating) at the top
+	 * of the history stack so a back affordance can disable itself. */
+	back(): boolean;
+	/** Walks forward one entry; returns `false` (without navigating) at the
+	 * end of the history stack so a forward affordance can disable itself. */
+	forward(): boolean;
 	prefix: string;
 	SKIP: unknown;
 	Link: Component<RouteLinkAttrs>;