mithril-lynx 2.6.2 → 3.0.0

package/src/backends/virtual-backend.js

@@ -8,81 +8,192 @@
 
 import { Op, pushOp } from "../patch-protocol.js";
 
+/**
+ * Creates the background-thread patch backend: every call appends one op to a flat buffer.
+ * @returns {{allocId: () => number, createElement: (tag: string) => number, createElementNS: (ns: string, tag: string) => number, createText: (text: string) => number, insertBefore: (parentId: number, childId: number, refId?: number) => void, removeChild: (parentId: number, childId: number) => void, setAttribute: (id: number, name: string, value: *) => void, removeAttribute: (id: number, name: string) => void, setAttributeNS: (id: number, ns: string|null, name: string, value: string|null) => void, setClasses: (id: number, value: string) => void, setStyleProperty: (id: number, name: string, value: string) => void, removeStyleProperty: (id: number, name: string) => void, setText: (id: number, value: string) => void, addEvent: (id: number, type: string) => void, removeEvent: (id: number, type: string) => void, setGestureDetector: (id: number, gestureId: number, gestureType: string, arenaPolicy: string) => void, removeGestureDetector: (id: number, gestureId: number) => void, invokeUIMethod: (id: number, method: string, params: Object, callbackId: number) => void, setInputValue: (id: number, value: string, seq: number) => void, onUIMethodOp: (() => void)|null, takeOps: () => unknown[]|null}} The backend object.
+ */
 export function createVirtualBackend() {
 	let nextId = 1;
 	let ops = [];
 
-	return {
+	const backend = {
 		// Exposed for tests that want to assert on id allocation directly;
 		// application code should never need it.
+		/**
+		 * @returns {number} A fresh element id.
+		 */
 		allocId() {
 			return nextId++;
 		},
+		/**
+		 * @param {string} tag - The tag name.
+		 * @returns {number} The new element's id.
+		 */
 		createElement(tag) {
 			const id = nextId++;
 			pushOp(ops, Op.CreateElement, tag, id);
 			return id;
 		},
+		/**
+		 * @param {string} ns - The namespace URI.
+		 * @param {string} tag - The tag name.
+		 * @returns {number} The new element's id.
+		 */
 		createElementNS(ns, tag) {
 			const id = nextId++;
 			pushOp(ops, Op.CreateElementNS, ns, tag, id);
 			return id;
 		},
+		/**
+		 * @param {string} text - The initial text.
+		 * @returns {number} The new text node's id.
+		 */
 		createText(text) {
 			const id = nextId++;
 			pushOp(ops, Op.CreateText, text, id);
 			return id;
 		},
+		/**
+		 * @param {number} parentId - Parent element id.
+		 * @param {number} childId - Child id to insert.
+		 * @param {number} [refId] - Id to insert before; `-1` (or omitted) appends.
+		 * @returns {void}
+		 */
 		insertBefore(parentId, childId, refId) {
 			pushOp(ops, Op.InsertBefore, parentId, childId, refId ?? -1);
 		},
+		/**
+		 * @param {number} parentId - Parent element id.
+		 * @param {number} childId - Child id to remove.
+		 * @returns {void}
+		 */
 		removeChild(parentId, childId) {
 			pushOp(ops, Op.RemoveChild, parentId, childId);
 		},
+		/**
+		 * @param {number} id - Element id.
+		 * @param {string} name - Attribute name.
+		 * @param {*} value - Attribute value: a string, or a raw typed value for a catalogued list/list-item attribute.
+		 * @returns {void}
+		 */
 		setAttribute(id, name, value) {
 			pushOp(ops, Op.SetAttribute, id, name, value);
 		},
+		/**
+		 * @param {number} id - Element id.
+		 * @param {string} name - Attribute name.
+		 * @returns {void}
+		 */
 		removeAttribute(id, name) {
 			pushOp(ops, Op.RemoveAttribute, id, name);
 		},
+		/**
+		 * @param {number} id - Element id.
+		 * @param {string|null} ns - Attribute namespace.
+		 * @param {string} name - Attribute name.
+		 * @param {string|null} value - Attribute value.
+		 * @returns {void}
+		 */
 		setAttributeNS(id, ns, name, value) {
 			pushOp(ops, Op.SetAttributeNS, id, ns, name, value);
 		},
+		/**
+		 * @param {number} id - Element id.
+		 * @param {string} value - The class string.
+		 * @returns {void}
+		 */
 		setClasses(id, value) {
 			// Encoded as a SetAttribute on the synthetic "class" name — the
 			// patch applier special-cases that name into `__SetClasses`, the
 			// same split fake-dom.js already does on the way in.
 			pushOp(ops, Op.SetAttribute, id, "class", value);
 		},
+		/**
+		 * @param {number} id - Element id.
+		 * @param {string} name - Dash-case style property name.
+		 * @param {string} value - Style value.
+		 * @returns {void}
+		 */
 		setStyleProperty(id, name, value) {
 			pushOp(ops, Op.SetStyleProperty, id, name, value);
 		},
+		/**
+		 * @param {number} id - Element id.
+		 * @param {string} name - Dash-case style property name (`"*"` requests a bulk clear).
+		 * @returns {void}
+		 */
 		removeStyleProperty(id, name) {
 			pushOp(ops, Op.RemoveStyleProperty, id, name);
 		},
+		/**
+		 * @param {number} id - Text node id.
+		 * @param {string} value - The new text.
+		 * @returns {void}
+		 */
 		setText(id, value) {
 			pushOp(ops, Op.SetText, id, value);
 		},
+		/**
+		 * @param {number} id - Element id.
+		 * @param {string} type - Event type.
+		 * @returns {void}
+		 */
 		addEvent(id, type) {
 			pushOp(ops, Op.AddEvent, id, type);
 		},
+		/**
+		 * @param {number} id - Element id.
+		 * @param {string} type - Event type.
+		 * @returns {void}
+		 */
 		removeEvent(id, type) {
 			pushOp(ops, Op.RemoveEvent, id, type);
 		},
+		/**
+		 * @param {number} id - Element id.
+		 * @param {number} gestureId - Unique gesture id.
+		 * @param {string} gestureType - Native gesture type name.
+		 * @param {string} arenaPolicy - Claim/release policy.
+		 * @returns {void}
+		 */
 		setGestureDetector(id, gestureId, gestureType, arenaPolicy) {
 			pushOp(ops, Op.SetGestureDetector, id, gestureId, gestureType, arenaPolicy);
 		},
+		/**
+		 * @param {number} id - Element id.
+		 * @param {number} gestureId - Gesture id to remove.
+		 * @returns {void}
+		 */
 		removeGestureDetector(id, gestureId) {
 			pushOp(ops, Op.RemoveGestureDetector, id, gestureId);
 		},
-		createList(scrollOrientation, listType, spanCount) {
-			const id = nextId++;
-			pushOp(ops, Op.CreateList, id, scrollOrientation, listType, spanCount);
-			return id;
-		},
-		setListItems(id, cells) {
-			pushOp(ops, Op.SetListItems, id, cells);
+		/**
+		 * Records a native UI method call (Op.InvokeUIMethod).
+		 * @param {number} id - Element id.
+		 * @param {string} method - UI method name.
+		 * @param {Object} params - Its parameters.
+		 * @param {number} callbackId - `0` for none, else the document's pending-invoke id.
+		 * @returns {void}
+		 */
+		invokeUIMethod(id, method, params, callbackId) {
+			pushOp(ops, Op.InvokeUIMethod, id, method, params, callbackId);
+			backend.onUIMethodOp?.();
 		},
+		/**
+		 * Records an <input>/<textarea> value change (Op.SetInputValue).
+		 * @param {number} id - Element id.
+		 * @param {string} value - The new text.
+		 * @param {number} seq - The field's input-event count when the value was computed.
+		 * @returns {void}
+		 */
+		setInputValue(id, value, seq) {
+			pushOp(ops, Op.SetInputValue, id, value, seq);
+			backend.onUIMethodOp?.();
+		},
+		/** Called after a UI method op is recorded — set by renderApp() to
+		 * flush calls made outside a render pass (a timer, a promise), which
+		 * no render would otherwise commit. */
+		onUIMethodOp: null,
 		/** Drains and returns the accumulated ops. Called once per commit. */
 		takeOps() {
 			if (ops.length === 0) return null;
@@ -90,19 +201,6 @@ export function createVirtualBackend() {
 			ops = [];
 			return out;
 		},
-		/**
-		 * Runs `fn` (a DOM mutation against a node from THIS backend's own
-		 * document — same id space as everything else, so event dispatch
-		 * keeps working normally) and returns just the ops it produced,
-		 * removing them from the shared buffer so they never also go out
-		 * with the next `takeOps()`. Used by list-cell.js to render one list
-		 * item off-tree and ship its construction ops separately, instead of
-		 * as part of the app's own visible-tree patch.
-		 */
-		captureOps(fn) {
-			const start = ops.length;
-			fn();
-			return ops.splice(start, ops.length - start);
-		},
 	};
+	return backend;
 }

package/src/background.d.ts

@@ -10,6 +10,32 @@ export interface LynxNode {
 	dispatchEvent(event: unknown): unknown;
 }
 
+/** A fake-DOM element (`vnode.dom` of any element vnode). Its UI methods run
+ * on the main thread right after the patch that carries them is flushed, so
+ * they are safe from `oncreate`; no `id` or selector query is involved. */
+export interface LynxElement extends LynxNode {
+	/** Calls a native UI method (`getValue`, `scrollTo`, `autoScroll`, …).
+	 * Rejects with an `Error` carrying the native `code`/`data`, or when the
+	 * element is removed before the call runs. */
+	invoke<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
+	/** The native `focus` UI method (fire-and-forget). */
+	focus(): void;
+	/** The native `blur` UI method (fire-and-forget). */
+	blur(): void;
+}
+
+/** `vnode.dom` of an `input` or `textarea`. `value` mirrors the native text:
+ * synced from every event of the field, and sent with `setValue` when set to
+ * something else. */
+export interface LynxFormFieldElement extends LynxElement {
+	value: string;
+	readonly selectionStart: number;
+	readonly selectionEnd: number;
+	/** Focuses the field once, on creation (set through the `autofocus` attribute). */
+	autofocus: boolean;
+	setSelectionRange(selectionStart: number, selectionEnd: number): Promise<unknown>;
+}
+
 /** The subset of the fake-DOM document exposed on the render handle — used
  * by tests and by an app's own HMR glue, never by the channel wiring. */
 export interface LynxDocument {

package/src/background.js

@@ -10,8 +10,19 @@
 // by which "a tap handler that mutates state repaints the screen" works,
 // with no cooperation from app code. v1's bug was that the function on the
 // other end of that call was sometimes undefined depending on load order;
-// here it is `performRender` — a plain closure, captured once, always the
+// here it is `requestRender` — a plain closure, captured once, always the
 // same reference, never looked up through a global.
+//
+// `requestRender` renders synchronously (it calls `performRender`) for every
+// redraw except one kind: the automatic redraw after a HIGH-FREQUENCY event
+// (`gesturemove`, `touchmove`, `scroll`). Those fire 60-120 times a second
+// during a drag, and a synchronous render after each one means a full diff,
+// commit and patch back to the main thread per sample. Instead, the handler
+// still runs for every single event (every sample reaches app code, in
+// order), but the render it asks for is coalesced into at most one per
+// frame. Any other render — a tap, `gestureup`, `redraw()`, a promise
+// handler's later redraw — renders immediately and turns a pending frame
+// render into a no-op, so the final state is always painted in order.
 
 import renderFactory from "mithril-runtime/render/render.js";
 import { createLynxDocument } from "./fake-dom.js";
@@ -19,6 +30,28 @@ import { createVirtualBackend } from "./backends/virtual-backend.js";
 import { createCommitController } from "./commit.js";
 import { onEventFromMainThread, sendPatchToMainThread } from "./channel.js";
 import { register as registerRedraw } from "./mount-redraw.js";
+import { INVOKE_RESULT_EVENT } from "./patch-protocol.js";
+
+/** Event types whose automatic redraw is coalesced to one per frame. Only
+ * add types that fire continuously during one interaction (every sample of
+ * a drag/scroll): their handlers still run per event, but the screen only
+ * catches up once per frame. Discrete events (tap, input, gestureup) must
+ * stay out so they keep rendering synchronously. */
+const HIGH_FREQUENCY_EVENTS = new Set(["gesturemove", "touchmove", "scroll"]);
+
+/**
+ * Runs `fn` on the next frame: `lynx.requestAnimationFrame` when available,
+ * otherwise a ~16ms timer.
+ * @param {() => void} fn - The callback to run.
+ * @returns {void}
+ */
+function scheduleFrame(fn) {
+	if (typeof lynx !== "undefined" && typeof lynx.requestAnimationFrame === "function") {
+		lynx.requestAnimationFrame(fn);
+	} else {
+		setTimeout(fn, 16);
+	}
+}
 
 /**
  * @param {object} options
@@ -29,44 +62,120 @@ import { register as registerRedraw } from "./mount-redraw.js";
  *   worth of ops across the thread boundary. Defaults to the real channel
  *   (channel.js, F0.1's decision) — tests override it to capture ops
  *   in-process instead.
+ * @param {(handler: (event: {data: {id: number, type: string, payload?: object}}) => void) => void} [options.subscribeEvents] -
+ *   Subscribes the forwarded-event router. Defaults to the real channel's
+ *   `onEventFromMainThread` — tests override it to drive the router directly.
+ * @returns {{redraw: () => void, document: import("./fake-dom.js").LynxDocument}} The redraw function and the app's fake document.
  */
-export function renderApp({ root, sendPatch = sendPatchToMainThread }) {
+export function renderApp({ root, sendPatch = sendPatchToMainThread, subscribeEvents = onEventFromMainThread }) {
 	const backend = createVirtualBackend();
 	const document = createLynxDocument(backend);
 	const render = renderFactory();
 	const commitController = createCommitController();
 
+	/**
+	 * Drains the backend's ops and sends them, if there are any.
+	 * @returns {void}
+	 */
 	function flush() {
 		const ops = backend.takeOps();
 		if (ops) sendPatch(ops);
 	}
 	commitController.install(flush);
 
+	// A UI method call made outside a render pass (`dom.focus()` in a timer,
+	// `dom.invoke()` after a fetch) has no commit to travel with: send it at
+	// the end of the current task. Inside a render (or an event handler,
+	// which is followed by one) the render's own commit sends it first and
+	// this finds nothing left to send.
+	let uiFlushScheduled = false;
+	backend.onUIMethodOp = () => {
+		if (uiFlushScheduled) return;
+		uiFlushScheduled = true;
+		Promise.resolve().then(() => {
+			uiFlushScheduled = false;
+			flush();
+		});
+	};
+
 	// This is Mithril's actual redraw service pattern (the same shape as
 	// upstream `mithril/api/mount-redraw.js`'s internal `run()`): the
 	// "redraw" callback IS "call render() again", not "send a patch"
 	// directly — flushing is a side effect of every render pass completing,
 	// whether that pass was the first one, an auto-redraw after an event, a
 	// manual `redraw()` call, or a hot-update re-render (see reload/*.js).
+	/**
+	 * Runs one full render pass and commits the resulting patch, synchronously.
+	 * @returns {void}
+	 */
 	function performRender() {
-		render(document, root(), performRender);
+		framePending = false;
+		render(document, root(), requestRender);
 		commitController.commit();
 	}
 
+	// True only while a high-frequency event's handler is running.
+	let dispatchingHighFrequency = false;
+	// True while a coalesced render is scheduled for the next frame. Any
+	// render in between clears it, so the scheduled one becomes a no-op
+	// instead of needing a cancel API.
+	let framePending = false;
+
+	/**
+	 * Mithril's redraw callback: renders now, except after a high-frequency
+	 * event, where it schedules at most one render for the next frame.
+	 * @returns {void}
+	 */
+	function requestRender() {
+		if (!dispatchingHighFrequency) {
+			performRender();
+			return;
+		}
+		if (framePending) return;
+		framePending = true;
+		scheduleFrame(() => {
+			if (framePending) performRender();
+		});
+	}
+
 	performRender();
 	registerRedraw(performRender);
 
 	// Wires every forwarded native event straight to the fake-dom node it
 	// targets — `dispatchEvent` (fake-dom.js) then invokes Mithril's own
 	// EventDict exactly as a real DOM would, and (per the contract at the
-	// top of this file) `performRender` auto-fires afterward if the
+	// top of this file) `requestRender` auto-fires afterward if the
 	// handler doesn't opt out. This is the ONLY consumer of
 	// `onEventFromMainThread` — app code never touches the channel directly.
-	onEventFromMainThread((event) => {
-		const { id, type, payload } = event.data;
+	subscribeEvents((event) => {
+		const { id, type, payload, seq } = event.data;
+		if (type === INVOKE_RESULT_EVENT) {
+			document.resolveInvoke(payload);
+			return;
+		}
 		const node = document.getNodeById(id);
 		if (!node) return;
-		node.dispatchEvent({ type, currentTarget: node, preventDefault() {}, stopPropagation() {}, ...payload });
+		// An <input>/<textarea> learns its native value before any handler
+		// runs, as a browser input would (see fake-dom.js).
+		if (typeof node._syncFromEvent === "function") node._syncFromEvent(payload, seq);
+		dispatchingHighFrequency = HIGH_FREQUENCY_EVENTS.has(type);
+		try {
+			node.dispatchEvent({
+				type,
+				currentTarget: node,
+				defaultPrevented: false,
+				// Lynx has no default action to cancel; recording the call lets
+				// handlers that check `e.defaultPrevented` (route.Link, like
+				// upstream m.route.Link) behave as on the web.
+				preventDefault() {
+					this.defaultPrevented = true;
+				},
+				stopPropagation() {},
+				...payload,
+			});
+		} finally {
+			dispatchingHighFrequency = false;
+		}
 	});
 
 	return {

package/src/channel.js

@@ -28,22 +28,39 @@ import { PROTOCOL_VERSION } from "./patch-protocol.js";
  * The patch is prefixed with `PROTOCOL_VERSION` so the main thread can
  * detect a stale/desynced bundle (partial HMR, cache) and fail loudly
  * instead of re-interpreting reordered opcodes against the shared id space.
+ * @param {unknown[]} ops - The flat op array for one commit.
+ * @returns {void}
  */
 export function sendPatchToMainThread(ops) {
 	lynx.getCoreContext().dispatchEvent({ type: patchEventName, data: [PROTOCOL_VERSION, ...ops] });
 }
 
-/** Background thread: receive a forwarded native event `{ id, type, payload }`. */
+/** Background thread: receive a forwarded native event `{ id, type, payload, seq? }`
+ * (`seq`: see apply-patch.js's `fields`), or an Op.InvokeUIMethod result
+ * (`type` = `INVOKE_RESULT_EVENT`, see patch-protocol.js).
+ * @param {(event: {data: {id: number, type: string, payload: unknown, seq?: number}}) => void} handler - Called for every forwarded event.
+ * @returns {void}
+ */
 export function onEventFromMainThread(handler) {
 	lynx.getCoreContext().addEventListener(eventFromMainThreadEventName, handler);
 }
 
-/** Main thread: receive a patch (an ops array) from the background thread. */
+/** Main thread: receive a patch (an ops array) from the background thread.
+ * @param {(event: {data: unknown}) => void} handler - Called with each version-prefixed patch.
+ * @returns {void}
+ */
 export function onPatchFromBackground(handler) {
 	lynx.getJSContext().addEventListener(patchEventName, handler);
 }
 
-/** Main thread: forward a native event on element `id` back to the background thread. */
-export function sendEventToBackground(id, type, payload) {
-	lynx.getJSContext().dispatchEvent({ type: eventFromMainThreadEventName, data: { id, type, payload } });
+/** Main thread: forward a native event on element `id` back to the background thread.
+ * @param {number} id - The element id.
+ * @param {string} type - The event type.
+ * @param {unknown} payload - The native event payload.
+ * @param {number} [seq] - For an <input>/<textarea>, its native `input` event count.
+ * @returns {void}
+ */
+export function sendEventToBackground(id, type, payload, seq) {
+	const data = seq === undefined ? { id, type, payload } : { id, type, payload, seq };
+	lynx.getJSContext().dispatchEvent({ type: eventFromMainThreadEventName, data });
 }

package/src/commit.js

@@ -20,6 +20,10 @@
 
 const NOT_MOUNTED = Symbol("mithril-lynx:not-mounted");
 
+/**
+ * Creates the single-use commit controller for one `renderApp()` call.
+ * @returns {{install: (fn: () => void) => void, commit: () => void}} The controller.
+ */
 export function createCommitController() {
 	let commitFn = NOT_MOUNTED;
 
@@ -29,6 +33,9 @@ export function createCommitController() {
 		 * `renderApp()` (background.js), before Mithril's `render()` is ever
 		 * invoked — so nothing can observe the "not mounted yet" state from
 		 * inside a redraw.
+		 * @param {() => void} fn - The commit callback.
+		 * @returns {void}
+		 * @throws {Error} If a commit callback was already installed.
 		 */
 		install(fn) {
 			if (commitFn !== NOT_MOUNTED) {
@@ -51,6 +58,8 @@ export function createCommitController() {
 		 * after any event handler runs, with no cooperation required from
 		 * app code — that automatic call is what makes redraw "just work"
 		 * like it does in React/Preact.
+		 * @returns {void}
+		 * @throws {Error} If called before a commit callback was installed.
 		 */
 		commit() {
 			if (commitFn === NOT_MOUNTED) {

package/src/dev-reload-client.js

@@ -28,6 +28,11 @@
 
 var MRL = "[mrl-trace]";
 
+/**
+ * Parses a webpack `__resourceQuery` string into a key/value map.
+ * @param {string} query - The query string, beginning with `?`.
+ * @returns {Object<string, string>} The decoded values (empty when `query` is not a `?` string).
+ */
 function parseResourceQuery(query) {
 	var values = {};
 	if (typeof query !== "string" || !query.startsWith("?")) return values;
@@ -41,6 +46,11 @@ function parseResourceQuery(query) {
 	return values;
 }
 
+/**
+ * Builds the dev-server WebSocket URL.
+ * @param {{protocol?: string, hostname?: string, port?: string, pathname?: string, token?: string}} options - Connection settings parsed from the resource query.
+ * @returns {string} The `ws(s)://` URL.
+ */
 function socketURL(options) {
 	var hostname = options.hostname || "";
 	var port = options.port ? ":" + options.port : "";
@@ -53,6 +63,9 @@ function socketURL(options) {
  * Lynx keys both the HTTP layer and its bytecode cache by URL — a
  * `Page.reload` with the SAME url re-runs the previous bundle byte-for-byte
  * even with `ignoreCache: true` (measured on-device against v1, 0.0.8).
+ * @param {string} url - The bundle URL.
+ * @param {number} [now=Date.now()] - Timestamp used for the `t` parameter.
+ * @returns {string|undefined} The URL with a `t` parameter, or `undefined` when `url` is not an http(s) URL.
  */
 function cacheBustedUrl(url, now) {
 	if (typeof url !== "string" || !/^https?:\/\//i.test(url)) return undefined;
@@ -94,6 +107,10 @@ var reloading = false;
 // against this hash once it settles.
 var pendingRecheckHash;
 
+/**
+ * Asks the DevTool native module to reload the page (`Page.reload`, cache ignored).
+ * @returns {boolean} `true` when the reload request was sent, `false` when the native module is unavailable.
+ */
 function invokeCdpReload() {
 	var upperCase = typeof NativeModules !== "undefined" ? NativeModules.LynxDevToolSetModule : undefined;
 	var lowerCase = typeof NativeModules !== "undefined" ? NativeModules.LynxDevtoolSetModule : undefined;
@@ -110,6 +127,10 @@ function invokeCdpReload() {
 
 	invokeCdp(
 		JSON.stringify({ method: "Page.reload", params }),
+		/**
+		 * @param {string} [data] - The raw CDP response; logged when it carries an error.
+		 * @returns {void}
+		 */
 		function (data) {
 			if (!data) return;
 			try {
@@ -123,6 +144,11 @@ function invokeCdpReload() {
 	return true;
 }
 
+/**
+ * Closes the socket and triggers a full page reload.
+ * @param {string} [reason] - Why the reload was requested (logged).
+ * @returns {void}
+ */
 function reload(reason) {
 	console.info(MRL + ":8 reload-called", JSON.stringify({ reason: reason || "unspecified" }));
 	reloading = true;
@@ -134,6 +160,11 @@ function reload(reason) {
 	}
 }
 
+/**
+ * Runs `module.hot.check(true)`, coalescing a queued newer hash or falling back to a full reload.
+ * @param {string} hash - The build hash being checked.
+ * @returns {void}
+ */
 function runCheck(hash) {
 	console.info(MRL + ":5 hmr-check-calling", "module.hot.check(true)");
 	module.hot.check(true).then(function (updatedModules) {
@@ -165,6 +196,11 @@ function runCheck(hash) {
 	});
 }
 
+/**
+ * Starts an HMR check for `hash`, queues it if another check is in flight, or reloads when HMR is unavailable.
+ * @param {string} hash - The build hash to check.
+ * @returns {void}
+ */
 function maybeCheck(hash) {
 	var hasHot = typeof module !== "undefined" && module.hot;
 	var hotStatus = hasHot ? module.hot.status() : "n/a";
@@ -186,6 +222,11 @@ function maybeCheck(hash) {
 	runCheck(hash);
 }
 
+/**
+ * Handles one dev-server message (`hash`, `ok`, `warnings`, `errors`).
+ * @param {string} rawMessage - The raw JSON message text; invalid JSON is ignored with a warning.
+ * @returns {void}
+ */
 function handleMessage(rawMessage) {
 	var message;
 	try {
@@ -224,6 +265,11 @@ function handleMessage(rawMessage) {
 	}
 }
 
+/**
+ * Opens the dev-server WebSocket and reconnects with exponential backoff (up to 10 retries).
+ * @param {number} [retries=0] - The number of reconnect attempts made so far.
+ * @returns {void}
+ */
 function connect(retries) {
 	if (retries === undefined) retries = 0;
 	console.info(MRL + ":1 ws-connecting", JSON.stringify({ url: socketURL(options), retry: retries }));

package/src/dev-transport-noop.js

@@ -7,4 +7,7 @@
 // (order "post", so it wins over the alias @lynx-js/rsbuild-plugin
 // registers) so `module.hot` stays live without a competing channel. Same
 // fix as mithril-lynx v1's F2 (src/dev-transport-noop.js).
+/**
+ * No-op replacement for the official dev transport client.
+ */
 export default class DevTransportClientNoop {}