mithril-lynx 0.0.8 → 2.0.0

package/src/apply-patch.js

@@ -0,0 +1,179 @@
+// src/apply-patch.js
+//
+// The main-thread half of the patch protocol. Deliberately NOT a DOM — it
+// never runs Mithril's render.js (only the background thread does, see
+// background.js) — it is a direct, low-level interpreter of the flat op
+// array straight onto the real Element PAPI, in the spirit of ReactLynx's
+// own `snapshotPatchApply.js` (see rspeedy-react-analysis/LYNX_PAPI_SPEC.md
+// §4.3): a switch over op codes, one real PAPI call per case, nothing else.
+//
+// The exact `__Create*`/pageId contract below (one `pageId` shared by every
+// element on a page, `__CreateView`/`__CreateText`/generic `__CreateElement`
+// for tags, `__CreateRawText` + `__SetAttribute(id,"text",v)` for raw text
+// content) is not a guess — it's the same contract `mithril-lynx/CONTRACT.md`
+// + `mithril-lynx/src/lynx-mithril-shim.js` already validated on a real
+// device (see mithril-lynx/DEVICE_VERIFICATION.md). Reusing a validated
+// mapping here is exactly the kind of "concept, not code" reuse the v2 plan
+// allows (§2 non-goals) — the bug we're rewriting away lives in the
+// commit/reload layer (commit.js, reload/*.js), never in this mapping.
+
+import { Op } from "./patch-protocol.js";
+
+/**
+ * @param {number} pageId - `__GetElementUniqueID(pageElement)` of the real
+ *   page this applier is attached to. Every element this applier creates
+ *   belongs to that one page — see CONTRACT.md / lynx-mithril-shim.js.
+ */
+export function createPatchApplier(pageId, { onEvent } = {}) {
+	// id (as allocated by the background's virtual backend) -> real PAPI
+	// element handle. id 0 is reserved for "the page itself" (see
+	// fake-dom.js's LynxDocument) — pre-seeded here so the very first
+	// InsertBefore/AppendChild targeting id 0 has somewhere real to land.
+	const handles = new Map();
+
+	function registerPageRoot(pageElementHandle) {
+		handles.set(0, pageElementHandle);
+	}
+
+	function createElementHandle(tag) {
+		if (tag === "view") return __CreateView(pageId);
+		if (tag === "text") return __CreateText(pageId);
+		return __CreateElement(tag, pageId, {});
+	}
+
+	/**
+	 * Applies one commit's worth of ops, then flushes exactly once —
+	 * `__FlushElementTree` is the real commit; nothing before it is visible.
+	 * This function itself is the ONLY caller of `__FlushElementTree` on
+	 * this applier's page — never called conditionally, never looked up
+	 * through a global (mirrors the fix in commit.js on the background
+	 * side: one explicit call site, not an implicit one).
+	 */
+	function applyPatch(ops) {
+		for (let i = 0; i < ops.length; ) {
+			const opcode = ops[i++];
+			switch (opcode) {
+				case Op.CreateElement: {
+					const tag = ops[i++];
+					const id = ops[i++];
+					handles.set(id, createElementHandle(tag));
+					break;
+				}
+				case Op.CreateElementNS: {
+					// Lynx has no XML-namespaced element PAPI distinct from
+					// the generic one — CONTRACT.md's createElementNS exists
+					// only to satisfy render.js's SVG/MathML path, which
+					// mithril-lynx apps don't exercise (no SVG on Lynx).
+					const _ns = ops[i++];
+					const tag = ops[i++];
+					const id = ops[i++];
+					handles.set(id, createElementHandle(tag));
+					break;
+				}
+				case Op.CreateText: {
+					const value = ops[i++];
+					const id = ops[i++];
+					handles.set(id, __CreateRawText(String(value)));
+					break;
+				}
+				case Op.InsertBefore: {
+					const parentId = ops[i++];
+					const childId = ops[i++];
+					const refId = ops[i++];
+					const parent = handles.get(parentId);
+					const child = handles.get(childId);
+					if (refId === -1) {
+						__AppendElement(parent, child);
+					} else {
+						__InsertElementBefore(parent, child, handles.get(refId));
+					}
+					break;
+				}
+				case Op.RemoveChild: {
+					const parentId = ops[i++];
+					const childId = ops[i++];
+					__RemoveElement(handles.get(parentId), handles.get(childId));
+					handles.delete(childId);
+					break;
+				}
+				case Op.SetAttribute: {
+					const id = ops[i++];
+					const name = ops[i++];
+					const value = ops[i++];
+					const handle = handles.get(id);
+					if (name === "class") __SetClasses(handle, value == null ? "" : value);
+					else __SetAttribute(handle, name, value);
+					break;
+				}
+				case Op.RemoveAttribute: {
+					const id = ops[i++];
+					const name = ops[i++];
+					const handle = handles.get(id);
+					if (name === "class") __SetClasses(handle, "");
+					else __SetAttribute(handle, name, null);
+					break;
+				}
+				case Op.SetAttributeNS: {
+					const id = ops[i++];
+					const _ns = ops[i++];
+					const name = ops[i++];
+					const value = ops[i++];
+					__SetAttribute(handles.get(id), name, value);
+					break;
+				}
+				case Op.SetStyleProperty: {
+					const id = ops[i++];
+					const name = ops[i++];
+					const value = ops[i++];
+					__AddInlineStyle(handles.get(id), name, value);
+					break;
+				}
+				case Op.RemoveStyleProperty: {
+					const id = ops[i++];
+					const name = ops[i++];
+					// `"*"` is fake-dom.js's encoding of `element.style = ""`
+					// (clear everything) — there is no bulk-clear PAPI call
+					// validated yet, so this case is a documented gap for
+					// F3, not a silent no-op: it throws so the gap surfaces
+					// as a test failure rather than a mystery on-device.
+					if (name === "*") {
+						throw new Error(
+							"[mithril-lynx-v2] Clearing the whole `style` object at once is not implemented yet (F3 TODO) — set individual properties to \"\" instead.",
+						);
+					}
+					__AddInlineStyle(handles.get(id), name, "");
+					break;
+				}
+				case Op.SetText: {
+					const id = ops[i++];
+					const value = ops[i++];
+					__SetAttribute(handles.get(id), "text", value);
+					break;
+				}
+				case Op.AddEvent: {
+					const id = ops[i++];
+					const type = ops[i++];
+					const handle = handles.get(id);
+					__AddEventListener(handle, type, (nativeEvent) => {
+						onEvent?.(id, type, nativeEvent);
+					}, {});
+					break;
+				}
+				case Op.RemoveEvent: {
+					// PAPI has no documented `__RemoveEventListener` in the
+					// validated v1 surface (CONTRACT.md never needed it,
+					// since mithril-lynx v1 never tore down individual
+					// listeners outside of removing the whole element).
+					// Left as an explicit no-op + TODO rather than a guess.
+					i += 2;
+					break;
+				}
+				default:
+					throw new Error(`[mithril-lynx-v2] Unknown patch opcode: ${opcode}`);
+			}
+		}
+		__FlushElementTree();
+	}
+
+	return { registerPageRoot, applyPatch };
+}

package/src/backends/virtual-backend.js

@@ -0,0 +1,80 @@
+// src/backends/virtual-backend.js
+//
+// The background-thread half of the patch protocol: `fake-dom.js` calls
+// these methods instead of touching real elements, and every call appends
+// one op to a flat array (see ../patch-protocol.js for the op format and
+// why it's flat). `takeOps()` is called once per commit (see ../commit.js)
+// to drain the array for sending across the thread boundary.
+
+import { Op, pushOp } from "../patch-protocol.js";
+
+export function createVirtualBackend() {
+	let nextId = 1;
+	let ops = [];
+
+	return {
+		// Exposed for tests that want to assert on id allocation directly;
+		// application code should never need it.
+		allocId() {
+			return nextId++;
+		},
+		createElement(tag) {
+			const id = nextId++;
+			pushOp(ops, Op.CreateElement, tag, id);
+			return id;
+		},
+		createElementNS(ns, tag) {
+			const id = nextId++;
+			pushOp(ops, Op.CreateElementNS, ns, tag, id);
+			return id;
+		},
+		createText(text) {
+			const id = nextId++;
+			pushOp(ops, Op.CreateText, text, id);
+			return id;
+		},
+		insertBefore(parentId, childId, refId) {
+			pushOp(ops, Op.InsertBefore, parentId, childId, refId ?? -1);
+		},
+		removeChild(parentId, childId) {
+			pushOp(ops, Op.RemoveChild, parentId, childId);
+		},
+		setAttribute(id, name, value) {
+			pushOp(ops, Op.SetAttribute, id, name, value);
+		},
+		removeAttribute(id, name) {
+			pushOp(ops, Op.RemoveAttribute, id, name);
+		},
+		setAttributeNS(id, ns, name, value) {
+			pushOp(ops, Op.SetAttributeNS, id, ns, name, value);
+		},
+		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);
+		},
+		setStyleProperty(id, name, value) {
+			pushOp(ops, Op.SetStyleProperty, id, name, value);
+		},
+		removeStyleProperty(id, name) {
+			pushOp(ops, Op.RemoveStyleProperty, id, name);
+		},
+		setText(id, value) {
+			pushOp(ops, Op.SetText, id, value);
+		},
+		addEvent(id, type) {
+			pushOp(ops, Op.AddEvent, id, type);
+		},
+		removeEvent(id, type) {
+			pushOp(ops, Op.RemoveEvent, id, type);
+		},
+		/** Drains and returns the accumulated ops. Called once per commit. */
+		takeOps() {
+			if (ops.length === 0) return null;
+			const out = ops;
+			ops = [];
+			return out;
+		},
+	};
+}

package/src/background.d.ts

@@ -0,0 +1,11 @@
+export interface RenderAppOptions {
+	root: () => unknown;
+	sendPatch?: (ops: unknown[]) => void;
+}
+
+export interface RenderAppHandle {
+	redraw: () => void;
+	document: unknown;
+}
+
+export function renderApp(options: RenderAppOptions): RenderAppHandle;

package/src/background.js

@@ -0,0 +1,79 @@
+// src/background.js
+//
+// Entry point for the background (JS) thread — the ONLY thread that ever
+// runs a component's view() or Mithril's diff (architecture decision
+// §3.1 of the plan: one thread model, not three like v1 had).
+//
+// The redraw contract, precisely: `render(dom, vnodes, redraw)`'s third
+// argument is what real Mithril calls automatically after any event
+// (CONTRACT.md §e, `EventDict.handleEvent`) — that is the ENTIRE mechanism
+// 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
+// same reference, never looked up through a global.
+
+import renderFactory from "mithril-runtime/render/render.js";
+import { createLynxDocument } from "./fake-dom.js";
+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";
+
+/**
+ * @param {object} options
+ * @param {() => unknown} options.root - Returns the current top-level vnode
+ *   (a fresh hyperscript tree). Called on every render pass, including the
+ *   very first — there is no separate "mount" vnode.
+ * @param {(ops: unknown[]) => void} [options.sendPatch] - Ships one commit's
+ *   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.
+ */
+export function renderApp({ root, sendPatch = sendPatchToMainThread }) {
+	const backend = createVirtualBackend();
+	const document = createLynxDocument(backend);
+	const render = renderFactory();
+	const commitController = createCommitController();
+
+	function flush() {
+		const ops = backend.takeOps();
+		if (ops) sendPatch(ops);
+	}
+	commitController.install(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).
+	function performRender() {
+		render(document, root(), performRender);
+		commitController.commit();
+	}
+
+	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
+	// 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;
+		const node = document.getNodeById(id);
+		if (!node) return;
+		node.dispatchEvent({ type, currentTarget: node, preventDefault() {}, stopPropagation() {}, ...payload });
+	});
+
+	return {
+		redraw: performRender,
+		/** Exposed for tests and for an app's `module.hot.accept` glue (see
+		 * the demo app's background.ts) — never needed by the channel
+		 * wiring above, which is already fully self-contained. */
+		document,
+	};
+}

package/src/channel.js

@@ -0,0 +1,41 @@
+// src/channel.js
+//
+// The cross-thread transport (F0.1's decision, plan §3.2). Uses the exact
+// same mechanism mithril-lynx v1's already-on-device-verified renderer mode
+// used (`lynx.getCoreContext()`/`lynx.getJSContext()` event pub/sub with a
+// namespaced event name) rather than the untested `lynx.triggerLepusGlobalEvent`
+// candidate F0.1 turned up — that candidate is real and worth trying in a
+// later iteration (see the plan's §8 F0.1 note), but shipping a first real
+// device build on a validated channel was the priority for F3, not
+// re-verifying the channel choice from scratch.
+//
+// Naming note: `getCoreContext()` (called from the background thread) and
+// `getJSContext()` (called from the main thread) are two different global
+// accessors for the SAME underlying native pub/sub context — confirmed by
+// v1's renderer/background.js and renderer/main-thread.js dispatching to
+// and listening on each other via exactly this pairing.
+
+export const patchEventName = "MithrilLynxV2:Patch";
+export const eventFromMainThreadEventName = "MithrilLynxV2:Event";
+export const renderPageEventName = "__RenderPage";
+export const destroyLifetimeEventName = "__DestroyLifetime";
+
+/** Background thread: ship one commit's ops to the main thread. */
+export function sendPatchToMainThread(ops) {
+	lynx.getCoreContext().dispatchEvent({ type: patchEventName, data: ops });
+}
+
+/** Background thread: receive a forwarded native event `{ id, type, payload }`. */
+export function onEventFromMainThread(handler) {
+	lynx.getCoreContext().addEventListener(eventFromMainThreadEventName, handler);
+}
+
+/** Main thread: receive a patch (an ops array) from the background thread. */
+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 } });
+}

package/src/commit.js

@@ -0,0 +1,67 @@
+// src/commit.js
+//
+// The single, explicit, non-conditional flush contract — this is the actual
+// fix for the regression that motivated the whole v2 rewrite (see
+// mithril-lynx-v2-desde-cero.md §3.4 and mithril-lynx/AGENTS.md's "Estado
+// actual" section for the v1 postmortem).
+//
+// v1's bug in one sentence: whether a redraw actually reached the main
+// thread depended on `typeof globalThis.__FlushElementTree === "function"`
+// — a question whose answer depended on thread/test/mode ordering. That is
+// a race condition baked into the architecture, not an edge case to patch.
+//
+// v2's rule: there is exactly one commit callback for the lifetime of one
+// `renderApp()` call (see background.js). It is installed explicitly, once,
+// by the code that owns the render — never discovered implicitly by
+// whoever happens to ask first. Asking to commit before installing one is a
+// programmer error and throws immediately and loudly, on the same tick,
+// with a message that says exactly what's missing — never a silently
+// frozen screen (which is what v1 did instead).
+
+const NOT_MOUNTED = Symbol("mithril-lynx-v2:not-mounted");
+
+export function createCommitController() {
+	let commitFn = NOT_MOUNTED;
+
+	return {
+		/**
+		 * Registers the one and only commit callback. Called exactly once by
+		 * `renderApp()` (background.js), before Mithril's `render()` is ever
+		 * invoked — so nothing can observe the "not mounted yet" state from
+		 * inside a redraw.
+		 */
+		install(fn) {
+			if (commitFn !== NOT_MOUNTED) {
+				throw new Error(
+					"[mithril-lynx-v2] commit callback already installed. " +
+						"A shim instance is single-use: one renderApp() call, one " +
+						"commit callback, for the lifetime of that background " +
+						"context. If you're re-mounting for a reload, create a new " +
+						"commit controller instead of reusing this one.",
+				);
+			}
+			commitFn = fn;
+		},
+		/**
+		 * The ONLY path anything (an event, `m.redraw()`, an HMR apply) uses
+		 * to signal "a render pass just happened, push it". Passed as the
+		 * `redraw` argument to every call of Mithril's real `render()` — see
+		 * background.js. Mithril's own `EventDict.handleEvent` (render.js,
+		 * documented in CONTRACT.md §e) already calls this automatically
+		 * 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.
+		 */
+		commit() {
+			if (commitFn === NOT_MOUNTED) {
+				throw new Error(
+					"[mithril-lynx-v2] commit() called before renderApp() mounted " +
+						"the app. This is always a bug in the framework's own " +
+						"wiring, never something app code can trigger by accident " +
+						"— app code never calls commit() directly.",
+				);
+			}
+			commitFn();
+		},
+	};
+}