mithril-lynx 2.6.2 → 3.0.0

package/src/fake-dom.js

@@ -25,22 +25,46 @@
 // side needs to be "a DOM", the other side only needs to be "a PAPI patch
 // applier".
 
+import { TYPED_ATTRIBUTES_BY_TAG } from "./list-attributes.js";
+import { FORM_FIELD_TAGS } from "./patch-protocol.js";
+
 const DASH_CASE = /-/;
 
+/**
+ * Converts a camelCase style property name to its dash-case CSS form.
+ * @param {string} name - The camelCase property name (e.g. `backgroundColor`).
+ * @returns {string} The dash-case name (e.g. `background-color`).
+ * @example
+ * camelToDash("backgroundColor"); // "background-color"
+ */
 function camelToDash(name) {
 	return name.replace(/[A-Z]/g, (c) => "-" + c.toLowerCase());
 }
 
+/**
+ * Base class for every fake-DOM node: tracks the owning document and the parent link.
+ */
 class LynxNode {
+	/**
+	 * @param {LynxDocument|null} ownerDocument - The document that owns this node (`null` only for the document itself, which sets it afterwards).
+	 */
 	constructor(ownerDocument) {
 		this.ownerDocument = ownerDocument;
 		this._parent = null;
 	}
 
+	/**
+	 * The parent container, or `null` when detached.
+	 * @returns {LynxContainerNode|null}
+	 */
 	get parentNode() {
 		return this._parent;
 	}
 
+	/**
+	 * The sibling immediately after this node in its parent's child list.
+	 * @returns {LynxNode|null} The next sibling, or `null` when detached or last.
+	 */
 	get nextSibling() {
 		if (!this._parent) return null;
 		const siblings = this._parent._children;
@@ -55,12 +79,22 @@ class LynxNode {
 // for fragments (CONTRACT.md §c, `createDocumentFragment`): inserting a
 // fragment moves ITS children into the target and leaves the fragment
 // empty, rather than inserting the fragment node itself.
+/**
+ * Base class for nodes that can hold children (elements, fragments, the document).
+ */
 class LynxContainerNode extends LynxNode {
+	/**
+	 * @param {LynxDocument|null} ownerDocument - The document that owns this node.
+	 */
 	constructor(ownerDocument) {
 		super(ownerDocument);
 		this._children = [];
 	}
 
+	/**
+	 * The first child node.
+	 * @returns {LynxNode|null} The first child, or `null` when empty.
+	 */
 	get firstChild() {
 		return this._children[0] ?? null;
 	}
@@ -70,10 +104,19 @@ class LynxContainerNode extends LynxNode {
 	// `createDocumentFragment()` (createNodes' fragment-batching path) — a
 	// real DOM's `childNodes` is a live NodeList, but render.js only ever
 	// reads `.length` off it here, so the plain backing array is enough.
+	/**
+	 * The live backing array of child nodes (only `.length` is ever read by render.js).
+	 * @returns {LynxNode[]}
+	 */
 	get childNodes() {
 		return this._children;
 	}
 
+	/**
+	 * Tests whether `other` is this node or one of its descendants.
+	 * @param {LynxNode|null} other - The node to look for.
+	 * @returns {boolean} `true` when `other` is this node or a descendant of it.
+	 */
 	contains(other) {
 		let node = other;
 		while (node) {
@@ -83,11 +126,23 @@ class LynxContainerNode extends LynxNode {
 		return false;
 	}
 
+	/**
+	 * Appends a child at the end of this container.
+	 * @param {LynxNode} child - The node to append.
+	 * @returns {LynxNode} The appended node.
+	 */
 	appendChild(child) {
 		this.insertBefore(child, null);
 		return child;
 	}
 
+	/**
+	 * Inserts a child before a reference node, moving it from any previous parent.
+	 * A fragment is never attached itself: its children are moved in and it is left empty.
+	 * @param {LynxNode} child - The node to insert.
+	 * @param {LynxNode|null} refChild - The node to insert before, or `null` to append.
+	 * @returns {LynxNode} The inserted node.
+	 */
 	insertBefore(child, refChild) {
 		if (child instanceof LynxFragment) {
 			// Real DOM semantics: the fragment itself is never attached —
@@ -112,14 +167,35 @@ class LynxContainerNode extends LynxNode {
 		return child;
 	}
 
+	/**
+	 * Removes a child from this container.
+	 * @param {LynxNode} child - The node to remove.
+	 * @returns {LynxNode} The removed node.
+	 */
 	removeChild(child) {
 		this._removeChildBookkeeping(child);
 		if (this._id != null && child._id != null) {
 			this._backend.removeChild(this._id, child._id);
+			// render.js only removes the ROOT of a removed subtree, so every
+			// descendant has to leave `_nodesById` here too — otherwise the
+			// whole detached subtree stays reachable forever. Moves never
+			// come through here (insertBefore uses _removeChildBookkeeping).
+			const nodesById = this.ownerDocument._nodesById;
+			const stack = [child];
+			while (stack.length > 0) {
+				const node = stack.pop();
+				nodesById.delete(node._id);
+				if (node._children) for (const c of node._children) stack.push(c);
+			}
 		}
 		return child;
 	}
 
+	/**
+	 * Detaches `child` from the local child list and clears its parent link, without touching the backend.
+	 * @param {LynxNode} child - The child to detach.
+	 * @returns {void}
+	 */
 	_removeChildBookkeeping(child) {
 		const index = this._children.indexOf(child);
 		if (index !== -1) this._children.splice(index, 1);
@@ -127,20 +203,49 @@ class LynxContainerNode extends LynxNode {
 	}
 }
 
+/**
+ * Creates the `element.style` object: a proxy that forwards `setProperty`/`removeProperty`
+ * and camelCase or dash-case property assignments to the backend as dash-case ops.
+ * @param {LynxElement} element - The element the style object belongs to.
+ * @returns {CSSStyleDeclaration} A proxy that emulates the subset of `CSSStyleDeclaration` render.js uses.
+ */
 function createStyleProxy(element) {
 	const methods = {
+		/**
+		 * @param {string} name - Dash-case style property name.
+		 * @param {*} value - Value, coerced with `String()`.
+		 * @returns {void}
+		 */
 		setProperty(name, value) {
-			element._styleEverSet = true;
+			element._activeStylesSet.add(name);
 			element._backend.setStyleProperty(element._id, name, String(value));
 		},
+		/**
+		 * @param {string} name - Dash-case style property name.
+		 * @returns {void}
+		 */
 		removeProperty(name) {
+			element._activeStylesSet.delete(name);
 			element._backend.removeStyleProperty(element._id, name);
 		},
 	};
 	return new Proxy(methods, {
+		/**
+		 * Proxy trap: reads pass through to the `setProperty`/`removeProperty` methods.
+		 * @param {Object} target - The methods object.
+		 * @param {string|symbol} prop - The property being read.
+		 * @returns {*} The property value.
+		 */
 		get(target, prop) {
 			return target[prop];
 		},
+		/**
+		 * Proxy trap: assigning a property writes (or, for an empty value, removes) that style property.
+		 * @param {Object} _target - Unused.
+		 * @param {string|symbol} prop - The style property name (camelCase or dash-case); symbols are ignored.
+		 * @param {*} value - The new value; `""`, `null` or `undefined` removes the property.
+		 * @returns {boolean} Always `true`.
+		 */
 		set(_target, prop, value) {
 			if (typeof prop !== "string") return true;
 			// Direct camelCase assignment path (CONTRACT.md §f, line 764/781).
@@ -148,9 +253,10 @@ function createStyleProxy(element) {
 			// key shape regardless of which of Mithril's two style paths ran.
 			const name = DASH_CASE.test(prop) ? prop : camelToDash(prop);
 			if (value === "" || value == null) {
+				element._activeStylesSet.delete(name);
 				element._backend.removeStyleProperty(element._id, name);
 			} else {
-				element._styleEverSet = true;
+				element._activeStylesSet.add(name);
 				element._backend.setStyleProperty(element._id, name, String(value));
 			}
 			return true;
@@ -164,41 +270,61 @@ function createStyleProxy(element) {
 // on the main thread — a single incrementing counter is simplest).
 let nextGestureId = 1;
 
+/**
+ * A fake-DOM element that mirrors every mutation to the backend as a patch op.
+ */
 export class LynxElement extends LynxContainerNode {
 	/**
-	 * `listConfig`, when given, makes this a native virtualized list
-	 * element instead of a plain one — see patch-protocol.js's
-	 * Op.CreateList and docs/native-papi/papi-06-virtualized-lists.md
-	 * (mithril-lynx-ui) for the full design. Not constructed directly;
-	 * use LynxDocument#createNativeList().
+	 * @param {LynxDocument} ownerDocument - The owning document.
+	 * @param {Object} backend - The patch backend that records ops.
+	 * @param {string} tag - The tag name.
+	 * @param {string} [ns] - The namespace URI, if any.
 	 */
-	constructor(ownerDocument, backend, tag, ns, listConfig) {
+	constructor(ownerDocument, backend, tag, ns) {
 		super(ownerDocument);
 		this._backend = backend;
 		this.tag = tag;
 		this.namespaceURI = ns;
-		this._id = listConfig
-			? backend.createList(listConfig.scrollOrientation, listConfig.listType, listConfig.spanCount)
-			: ns
-				? backend.createElementNS(ns, tag)
-				: backend.createElement(tag);
+		this._id = ns ? backend.createElementNS(ns, tag) : backend.createElement(tag);
 		ownerDocument._nodesById.set(this._id, this);
 		this._style = null;
-		this._styleEverSet = false;
 		this._listeners = Object.create(null);
 		// `hasPropertyKey` (CONTRACT.md §e) requires `"value" in vnode.dom` etc.
 		// to be true for the property-write fast path to apply to form
-		// elements — plain own properties satisfy the `in` check.
-		this.value = undefined;
+		// elements — plain own properties satisfy the `in` check. An
+		// <input>/<textarea> has a real `value` accessor on its prototype
+		// (LynxFormFieldElement), which an own property would shadow.
+		if (!("value" in this)) this.value = undefined;
 		this.checked = undefined;
 		this.selectedIndex = undefined;
 	}
 
+	/**
+	 * Lazily created style object for this element.
+	 * @returns {CSSStyleDeclaration}
+	 */
 	get style() {
 		if (!this._style) this._style = createStyleProxy(this);
 		return this._style;
 	}
 
+	/**
+	 * Dash-case names of the style properties currently applied to this
+	 * element, created lazily like `style` itself. Lets `style = ""` expand
+	 * into one RemoveStyleProperty op per property actually set, since there
+	 * is no device-validated bulk-clear PAPI call.
+	 * @returns {Set<string>}
+	 */
+	get _activeStylesSet() {
+		if (!this._activeStyles) this._activeStyles = new Set();
+		return this._activeStyles;
+	}
+
+	/**
+	 * Replaces the element's style. `""`/`null` clears it, an object assigns each key,
+	 * and a CSS text string is unsupported (a warning is logged).
+	 * @param {Object|string|null} value - The new style.
+	 */
 	set style(value) {
 		if (value == null || value === "") {
 			// `element.style = ""` (CONTRACT.md §f, lines 750-752): clear.
@@ -207,15 +333,17 @@ export class LynxElement extends LynxContainerNode {
 			// had any style at all (its "old is missing or a string, style is
 			// an object" branch — see mithril-runtime/render/render.js) — so
 			// without this guard, EVERY component with a plain object style
-			// prop (an extremely common pattern, not an edge case) would hit
-			// apply-patch.js's "bulk-clear not implemented" throw on its very
-			// first render. `_styleEverSet` (set by createStyleProxy whenever
-			// a real property is written) is exactly "was there anything to
-			// clear" — skip emitting the op at all when there wasn't; the
-			// throw still fires for the genuine case (an update actually
-			// replacing a previously-set style), where a real bulk-clear PAPI
-			// call would actually be needed and hasn't been validated yet.
-			if (this._styleEverSet) this._backend.removeStyleProperty(this._id, "*");
+			// prop (an extremely common pattern, not an edge case) would
+			// emit a clear op on its very first render. There is no
+			// device-validated bulk-clear PAPI call, so the clear is expanded
+			// here into one RemoveStyleProperty per property actually applied
+			// (tracked by createStyleProxy). The set is read through its
+			// backing field so a clear on an element that never had a style
+			// neither creates it nor emits anything.
+			const active = this._activeStyles;
+			if (active == null || active.size === 0) return;
+			for (const name of active) this._backend.removeStyleProperty(this._id, name);
+			active.clear();
 			return;
 		}
 		if (typeof value !== "object") {
@@ -238,10 +366,18 @@ export class LynxElement extends LynxContainerNode {
 		}
 	}
 
+	/**
+	 * The element's class string.
+	 * @returns {string} The class string, or `""` when unset.
+	 */
 	get className() {
 		return this._className ?? "";
 	}
 
+	/**
+	 * Sets the element's classes, emitting a `class` attribute op.
+	 * @param {string|null|undefined} value - The class string; `null`/`undefined` clears it.
+	 */
 	set className(value) {
 		// Mithril's `setAttr`/`removeAttr` map `className` -> the `"class"`
 		// attribute (CONTRACT.md §e); routed here directly since `className`
@@ -251,6 +387,12 @@ export class LynxElement extends LynxContainerNode {
 		this._backend.setClasses(this._id, value == null ? "" : String(value));
 	}
 
+	/**
+	 * Sets an attribute; the `class` name is routed to `className`.
+	 * @param {string} name - Attribute name.
+	 * @param {*} value - Attribute value, coerced with `String()`; `null`/`undefined` is sent as `null`.
+	 * @returns {void}
+	 */
 	setAttribute(name, value) {
 		if (name === "class") {
 			this.className = value;
@@ -259,6 +401,11 @@ export class LynxElement extends LynxContainerNode {
 		this._backend.setAttribute(this._id, name, value == null ? null : String(value));
 	}
 
+	/**
+	 * Removes an attribute; removing `class` clears the class string.
+	 * @param {string} name - Attribute name.
+	 * @returns {void}
+	 */
 	removeAttribute(name) {
 		if (name === "class") {
 			this.className = "";
@@ -267,6 +414,13 @@ export class LynxElement extends LynxContainerNode {
 		this._backend.removeAttribute(this._id, name);
 	}
 
+	/**
+	 * Sets a namespaced attribute.
+	 * @param {string|null} ns - Attribute namespace.
+	 * @param {string} name - Attribute name.
+	 * @param {*} value - Attribute value, coerced with `String()`; `null`/`undefined` is sent as `null`.
+	 * @returns {void}
+	 */
 	setAttributeNS(ns, name, value) {
 		this._backend.setAttributeNS(this._id, ns, name, value == null ? null : String(value));
 	}
@@ -287,21 +441,33 @@ export class LynxElement extends LynxContainerNode {
 		return gestureId;
 	}
 
+	/**
+	 * Removes a gesture detector previously registered with `setGestureDetector()`.
+	 * @param {number} gestureId - The id returned by `setGestureDetector()`.
+	 * @returns {void}
+	 */
 	removeGestureDetector(gestureId) {
 		this._backend.removeGestureDetector(this._id, gestureId);
 	}
 
-	/** Only meaningful on an element created via LynxDocument#createNativeList(). */
-	setListItems(items) {
-		this._backend.setListItems(this._id, items);
-	}
-
+	/**
+	 * Registers the single listener for an event type; the backend is told only the first time.
+	 * Replaces any previous listener for the same type.
+	 * @param {string} type - Event type (e.g. `tap`).
+	 * @param {Function|{handleEvent: Function}} listener - A function or an EventListener object.
+	 * @returns {void}
+	 */
 	addEventListener(type, listener) {
 		const isNew = !(type in this._listeners);
 		this._listeners[type] = listener;
 		if (isNew) this._backend.addEvent(this._id, type);
 	}
 
+	/**
+	 * Removes the listener for an event type, if any.
+	 * @param {string} type - Event type.
+	 * @returns {void}
+	 */
 	removeEventListener(type) {
 		if (!(type in this._listeners)) return;
 		delete this._listeners[type];
@@ -321,6 +487,10 @@ export class LynxElement extends LynxContainerNode {
 		else if (typeof listener.handleEvent === "function") listener.handleEvent(event);
 	}
 
+	/**
+	 * Only `""` is supported: removes every child. Any other value logs a warning and is ignored.
+	 * @param {string} value - Must be the empty string.
+	 */
 	set textContent(value) {
 		// render.js only ever does `dom.textContent = ""` (first-render
 		// clear, CONTRACT.md §b line 898) — implemented as "remove every
@@ -335,6 +505,10 @@ export class LynxElement extends LynxContainerNode {
 		for (const child of this._children.slice()) this.removeChild(child);
 	}
 
+	/**
+	 * Unsupported on Lynx elements; logs a warning.
+	 * @param {string} _value - Ignored.
+	 */
 	set innerHTML(_value) {
 		// `m.trust()`/contenteditable sync (CONTRACT.md §c) — Lynx elements
 		// have no HTML-string target to parse into. Documented as
@@ -347,17 +521,268 @@ export class LynxElement extends LynxContainerNode {
 		}
 	}
 
+	/**
+	 * Calls one of the native element's UI methods (`focus`, `getValue`,
+	 * `scrollTo`, `autoScroll`, …) — the promise form of
+	 * `lynx.createSelectorQuery().select(…).invoke({ method, params })`,
+	 * without an `id` or a timer. The call travels with the next patch and
+	 * runs on the main thread right after that patch is flushed, so it is
+	 * safe from `oncreate`, when the element does not exist natively yet.
+	 * Called outside a render (a timer, a promise), it is sent on its own
+	 * within the same tick.
+	 * @param {string} method - The UI method name.
+	 * @param {Object} [params] - The method's parameters.
+	 * @returns {Promise<unknown>} Resolves with the method's result; rejects
+	 *   with an `Error` carrying the native `code` and `data`, or when the
+	 *   element is removed before the call could run.
+	 */
+	invoke(method, params) {
+		return new Promise((resolve, reject) => {
+			const callbackId = this.ownerDocument._registerInvoke(method, resolve, reject);
+			this._backend.invokeUIMethod(this._id, method, params ?? {}, callbackId);
+		});
+	}
+
+	/**
+	 * Fire-and-forget UI method call, for methods whose result nobody reads.
+	 * @param {string} method - The UI method name.
+	 * @returns {void}
+	 */
+	_invokeAndForget(method) {
+		this._backend.invokeUIMethod(this._id, method, {}, 0);
+	}
+
+	/**
+	 * Focuses the element (the native `focus` UI method). Like `invoke()`,
+	 * it runs once the current patch is applied, so it works from `oncreate`.
+	 * Mithril's own post-render focus restoration never calls this: the
+	 * fake document has no `activeElement` (see render.js's `render()`).
+	 * @returns {void}
+	 */
 	focus() {
-		// Native `<input>` focus on Lynx is managed by the platform, not by
-		// a JS `.focus()` call reaching into the render pipeline — calling
-		// into the backend here would mean patch application could disturb
-		// focus mid-keystroke, which is the exact failure mode
-		// mithril-lynx v1 was designed around (its `<input>` deliberately
-		// has no bound `value` for the same reason). No-op by design.
+		this._invokeAndForget("focus");
+	}
+
+	/**
+	 * Removes focus from the element (the native `blur` UI method).
+	 * @returns {void}
+	 */
+	blur() {
+		this._invokeAndForget("blur");
 	}
 }
 
+/**
+ * An `<input>` or `<textarea>`. Native has no `value` attribute, only UI
+ * methods, so `value` here is a real property: assigning a different value
+ * sends a `setValue` call (Op.SetInputValue), and every forwarded event of
+ * the field syncs it back from `detail.value` — exactly what a browser's
+ * input does. That makes Mithril's own form handling work unchanged:
+ * render.js skips writing a `value` equal to `dom.value`, so the text the
+ * user just typed is never sent back, while a value the app changed (a
+ * clear, an uppercase transform) is sent once.
+ */
+class LynxFormFieldElement extends LynxElement {
+	constructor(ownerDocument, backend, tag, ns) {
+		super(ownerDocument, backend, tag, ns);
+		this._value = "";
+		// How many native `input` events the main thread had counted when the
+		// last synced event was sent — echoed in Op.SetInputValue so a value
+		// computed before a newer keystroke is dropped (see apply-patch.js).
+		this._inputSeq = 0;
+		this._selectionStart = -1;
+		this._selectionEnd = -1;
+		this._autofocused = false;
+	}
+
+	/**
+	 * The field's current text, as last seen from native or set here.
+	 * @returns {string}
+	 */
+	get value() {
+		return this._value;
+	}
+
+	/**
+	 * Sets the field's text; `null`/`undefined` clears it. Nothing is sent
+	 * when it already holds that text.
+	 * @param {*} value - The new text, coerced with `String()`.
+	 */
+	set value(value) {
+		const text = value == null ? "" : String(value);
+		if (text === this._value) return;
+		this._value = text;
+		this._backend.setInputValue(this._id, text, this._inputSeq);
+	}
+
+	/**
+	 * Selection start from the last forwarded event, `-1` when unknown.
+	 * @returns {number}
+	 */
+	get selectionStart() {
+		return this._selectionStart;
+	}
+
+	/** Read-only: ignored (a `selectionStart` attribute has no meaning here). */
+	set selectionStart(_value) {}
+
+	/**
+	 * Selection end from the last forwarded event, `-1` when unknown.
+	 * @returns {number}
+	 */
+	get selectionEnd() {
+		return this._selectionEnd;
+	}
+
+	/** Read-only: ignored (a `selectionEnd` attribute has no meaning here). */
+	set selectionEnd(_value) {}
+
+	/**
+	 * Whether the field was focused on creation by `autofocus`.
+	 * @returns {boolean}
+	 */
+	get autofocus() {
+		return this._autofocused;
+	}
+
+	/**
+	 * `autofocus: true` focuses the field once, when it is created — the
+	 * HTML attribute's semantics (Lynx has no such attribute). Later
+	 * redraws, or toggling it, never focus it again.
+	 * @param {*} value - Truthy to focus.
+	 */
+	set autofocus(value) {
+		if (!value || this._autofocused) return;
+		this._autofocused = true;
+		this.focus();
+	}
+
+	/**
+	 * Selects a range of the field's text (the native `setSelectionRange` UI method).
+	 * @param {number} selectionStart - Start index.
+	 * @param {number} selectionEnd - End index.
+	 * @returns {Promise<unknown>}
+	 */
+	setSelectionRange(selectionStart, selectionEnd) {
+		return this.invoke("setSelectionRange", { selectionStart, selectionEnd });
+	}
+
+	/**
+	 * Syncs `value`, the selection and the input sequence from a forwarded
+	 * native event, before its handlers run. Silent: nothing is sent.
+	 * @param {{detail?: {value?: unknown, selectionStart?: unknown, selectionEnd?: unknown}}} payload - The native event.
+	 * @param {number} [seq] - The field's native `input` event count.
+	 * @returns {void}
+	 */
+	_syncFromEvent(payload, seq) {
+		if (typeof seq === "number") this._inputSeq = seq;
+		const detail = payload && payload.detail;
+		if (detail == null) return;
+		if (typeof detail.value === "string") this._value = detail.value;
+		if (typeof detail.selectionStart === "number") this._selectionStart = detail.selectionStart;
+		if (typeof detail.selectionEnd === "number") this._selectionEnd = detail.selectionEnd;
+	}
+}
+
+/**
+ * A fake-DOM text node backed by a native text element.
+ */
+/**
+ * An element whose native attributes are typed (`<list>`, `<list-item>`).
+ * Every catalogued attribute is a real property here (defined on the
+ * per-tag prototype by {@link typedElementClassFor}), so Mithril's property
+ * path assigns raw values — booleans, numbers, the `item-snap` object —
+ * instead of stringifying them or turning `false` into a removal. See
+ * list-attributes.js for why that matters.
+ */
+class LynxTypedElement extends LynxElement {
+	constructor(ownerDocument, backend, tag, ns) {
+		super(ownerDocument, backend, tag, ns);
+		this._typedValues = Object.create(null);
+	}
+
+	/**
+	 * Sets or clears one typed attribute, keeping its raw value. Objects are
+	 * compared by content: Mithril re-assigns object attributes on every
+	 * redraw (render.js `setAttr` never skips `typeof value === "object"`),
+	 * and re-sending an unchanged `item-snap` would be a wasted native write.
+	 * @param {string} name - The attribute name.
+	 * @param {*} value - The raw value; `null`/`undefined` removes the attribute.
+	 * @returns {void}
+	 */
+	_setTypedAttribute(name, value) {
+		const had = name in this._typedValues;
+		if (value == null) {
+			if (!had) return;
+			delete this._typedValues[name];
+			this._backend.removeAttribute(this._id, name);
+			return;
+		}
+		if (had) {
+			const previous = this._typedValues[name];
+			if (previous === value) return;
+			if (typeof value === "object" && typeof previous === "object" && JSON.stringify(previous) === JSON.stringify(value)) return;
+		}
+		this._typedValues[name] = value;
+		this._backend.setAttribute(this._id, name, value);
+	}
+
+	/**
+	 * Catalogued names keep their raw type; everything else behaves like
+	 * {@link LynxElement#setAttribute}.
+	 * @param {string} name - Attribute name.
+	 * @param {*} value - Attribute value.
+	 * @returns {void}
+	 */
+	setAttribute(name, value) {
+		if (TYPED_ATTRIBUTES_BY_TAG[this.tag].includes(name)) this._setTypedAttribute(name, value);
+		else super.setAttribute(name, value);
+	}
+
+	/**
+	 * @param {string} name - Attribute name.
+	 * @returns {void}
+	 */
+	removeAttribute(name) {
+		if (TYPED_ATTRIBUTES_BY_TAG[this.tag].includes(name)) this._setTypedAttribute(name, null);
+		else super.removeAttribute(name);
+	}
+}
+
+const typedElementClasses = Object.create(null);
+
+/**
+ * Returns (and caches) the element class for a typed tag: a subclass of
+ * LynxTypedElement with one accessor per catalogued attribute on its
+ * prototype, so `name in element` holds for Mithril's `hasPropertyKey`.
+ * @param {string} tag - A key of TYPED_ATTRIBUTES_BY_TAG.
+ * @returns {typeof LynxTypedElement}
+ */
+function typedElementClassFor(tag) {
+	let cls = typedElementClasses[tag];
+	if (cls) return cls;
+	cls = class extends LynxTypedElement {};
+	for (const name of TYPED_ATTRIBUTES_BY_TAG[tag]) {
+		Object.defineProperty(cls.prototype, name, {
+			get() {
+				return this._typedValues[name];
+			},
+			set(value) {
+				this._setTypedAttribute(name, value);
+			},
+			configurable: true,
+		});
+	}
+	typedElementClasses[tag] = cls;
+	return cls;
+}
+
 export class LynxText extends LynxNode {
+	/**
+	 * @param {LynxDocument} ownerDocument - The owning document.
+	 * @param {Object} backend - The patch backend used to create and update the text.
+	 * @param {string} text - The initial text.
+	 */
 	constructor(ownerDocument, backend, text) {
 		super(ownerDocument);
 		this._backend = backend;
@@ -371,10 +796,18 @@ export class LynxText extends LynxNode {
 		this._id = backend.createText(text);
 	}
 
+	/**
+	 * The node's text.
+	 * @returns {string}
+	 */
 	get nodeValue() {
 		return this._text;
 	}
 
+	/**
+	 * Updates the text and emits a set-text op.
+	 * @param {string} value - The new text.
+	 */
 	set nodeValue(value) {
 		this._text = value;
 		this._backend.setText(this._id, value);
@@ -387,9 +820,18 @@ export class LynxText extends LynxNode {
 // (this._id != null && child._id != null)` guards in insertBefore/
 // removeChild are what keep a fragment-as-parent from ever trying to call
 // the backend for itself.
+/**
+ * A document fragment: never gets a backend id; its children are moved into the target on insertion.
+ */
 export class LynxFragment extends LynxContainerNode {}
 
+/**
+ * The fake document handed to Mithril's render.js; id `0` is the real page container.
+ */
 export class LynxDocument extends LynxContainerNode {
+	/**
+	 * @param {Object} backend - The patch backend that records ops (see `createVirtualBackend()`).
+	 */
 	constructor(backend) {
 		super(null);
 		this._backend = backend;
@@ -401,66 +843,122 @@ export class LynxDocument extends LynxContainerNode {
 		this._id = 0;
 		this.namespaceURI = undefined;
 		/** id -> node, for dispatching a forwarded native event (which only
-		 * carries an id + type) to the right fake-dom element. Populated by
-		 * every LynxElement/LynxText constructor; never by fragments, which
-		 * have no id and are never event targets. */
+		 * carries an id + type) to the right fake-dom element. Populated only
+		 * by the LynxElement constructor: text nodes have an id but are never
+		 * event targets, fragments have no id at all, and the document itself
+		 * (id 0) is not registered either. */
 		this._nodesById = new Map();
+		// callbackId -> pending `invoke()` promise, settled by resolveInvoke().
+		this._invokeCallbacks = new Map();
+		this._nextCallbackId = 1;
+	}
+
+	/**
+	 * Registers a pending `invoke()` promise.
+	 * @param {string} method - The UI method name, for the error message.
+	 * @param {(data: unknown) => void} resolve - Settles it successfully.
+	 * @param {(error: Error) => void} reject - Settles it with an error.
+	 * @returns {number} The callback id to send with Op.InvokeUIMethod.
+	 */
+	_registerInvoke(method, resolve, reject) {
+		const callbackId = this._nextCallbackId++;
+		this._invokeCallbacks.set(callbackId, { method, resolve, reject });
+		return callbackId;
+	}
+
+	/**
+	 * Settles a pending `invoke()` with the result forwarded by the main
+	 * thread. Unknown ids are ignored.
+	 * @param {{callbackId: number, code: number, data: unknown}} result - The result.
+	 * @returns {void}
+	 */
+	resolveInvoke(result) {
+		const pending = result && this._invokeCallbacks.get(result.callbackId);
+		if (pending == null) return;
+		this._invokeCallbacks.delete(result.callbackId);
+		if (result.code === 0) {
+			pending.resolve(result.data);
+			return;
+		}
+		const detail = typeof result.data === "string" ? result.data : JSON.stringify(result.data);
+		const error = new Error(`[mithril-lynx] UI method "${pending.method}" failed (code ${result.code}): ${detail}`);
+		error.code = result.code;
+		error.data = result.data;
+		pending.reject(error);
 	}
 
+	/**
+	 * Looks up a node by backend id, used to route forwarded native events.
+	 * @param {number} id - The backend id.
+	 * @returns {LynxElement|null} The element, or `null` when unknown (text nodes and the document are never registered).
+	 */
 	getNodeById(id) {
 		return this._nodesById.get(id) ?? null;
 	}
 
+	/**
+	 * No-op; present so render.js's focus-restoration check never throws.
+	 * @returns {void}
+	 */
 	focus() {
 		// Never meaningfully called on the document root itself; present so
 		// render.js's post-render focus-restoration check (CONTRACT.md §b)
 		// never throws if `activeElement` happens to resolve to the root.
 	}
 
+	/**
+	 * Only `""` is honored: removes every child of the document root.
+	 * @param {string} value - Must be the empty string for any effect.
+	 */
 	set textContent(value) {
 		if (value !== "") return;
 		for (const child of this._children.slice()) this.removeChild(child);
 	}
 
+	/**
+	 * Creates an element.
+	 * @param {string} tag - The tag name.
+	 * @returns {LynxElement}
+	 */
 	createElement(tag) {
+		if (tag in TYPED_ATTRIBUTES_BY_TAG) return new (typedElementClassFor(tag))(this, this._backend, tag, undefined);
+		if (FORM_FIELD_TAGS.includes(tag)) return new LynxFormFieldElement(this, this._backend, tag, undefined);
 		return new LynxElement(this, this._backend, tag, undefined);
 	}
 
+	/**
+	 * Creates a namespaced element.
+	 * @param {string} ns - The namespace URI.
+	 * @param {string} tag - The tag name.
+	 * @returns {LynxElement}
+	 */
 	createElementNS(ns, tag) {
 		return new LynxElement(this, this._backend, tag, ns);
 	}
 
+	/**
+	 * Creates a text node.
+	 * @param {string} text - The initial text.
+	 * @returns {LynxText}
+	 */
 	createTextNode(text) {
 		return new LynxText(this, this._backend, text);
 	}
 
-	createDocumentFragment() {
-		return new LynxFragment(this);
-	}
-
 	/**
-	 * A native virtualized list — see patch-protocol.js's Op.CreateList.
-	 * 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.
+	 * Creates an empty document fragment.
+	 * @returns {LynxFragment}
 	 */
-	createNativeList(options = {}) {
-		return new LynxElement(this, this._backend, "list", undefined, {
-			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);
+	createDocumentFragment() {
+		return new LynxFragment(this);
 	}
 }
 
+/**
+ * Creates a fake document bound to a patch backend.
+ * @param {Object} backend - The patch backend (see `createVirtualBackend()`).
+ * @returns {LynxDocument}
+ */
 export function createLynxDocument(backend) {
 	return new LynxDocument(backend);
 }