mithril-lynx 0.0.9 → 2.0.0

package/src/fake-dom.js

@@ -0,0 +1,374 @@
+// src/fake-dom.js
+//
+// A DOM implementation good enough for the REAL `render/render.js` (from
+// `mithril-runtime`, https://github.com/carlos-sweb/mithril-runtime — a
+// distribution of Mithril 2.3.8 that drops the browser-only route/trust/
+// request APIs, with render/render.js itself otherwise unmodified from
+// upstream, see CONTRACT.md §g) to run against — nothing more. The exact
+// surface required is documented in `mithril-lynx/CONTRACT.md` (a prior,
+// verified-by-grep extraction of what render.js actually touches on its
+// `dom` parameter): createElement(NS)/createTextNode/createDocumentFragment,
+// insertBefore/appendChild/removeChild, nodeValue, value/checked/
+// selectedIndex, className, setAttribute/removeAttribute/setAttributeNS,
+// style, innerHTML, textContent, firstChild, parentNode, ownerDocument,
+// namespaceURI, contains, focus, nextSibling. render.js never calls
+// `getAttribute` and never checks `nodeType` — so neither is implemented
+// here.
+//
+// This file only runs on the BACKGROUND thread, against a `backend` that
+// records patch ops instead of touching real elements (see
+// backends/virtual-backend.js). The main thread never runs this file, or
+// Mithril's render.js at all — it only replays the recorded ops through
+// `apply-patch.js`, which calls the real Element PAPI directly. That split
+// is the point of the whole architecture (see
+// mithril-lynx-v2/.omo/plans/mithril-lynx-v2-desde-cero.md §3.1): only ONE
+// side needs to be "a DOM", the other side only needs to be "a PAPI patch
+// applier".
+
+const DASH_CASE = /-/;
+
+function camelToDash(name) {
+	return name.replace(/[A-Z]/g, (c) => "-" + c.toLowerCase());
+}
+
+class LynxNode {
+	constructor(ownerDocument) {
+		this.ownerDocument = ownerDocument;
+		this._parent = null;
+	}
+
+	get parentNode() {
+		return this._parent;
+	}
+
+	get nextSibling() {
+		if (!this._parent) return null;
+		const siblings = this._parent._children;
+		const index = siblings.indexOf(this);
+		return index === -1 ? null : (siblings[index + 1] ?? null);
+	}
+}
+
+// Shared child-list bookkeeping for anything that can contain other nodes:
+// real elements, fragments, and the document/root itself. `insertBefore`
+// handles the one piece of real-DOM behavior render.js actually depends on
+// 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.
+class LynxContainerNode extends LynxNode {
+	constructor(ownerDocument) {
+		super(ownerDocument);
+		this._children = [];
+	}
+
+	get firstChild() {
+		return this._children[0] ?? null;
+	}
+
+	contains(other) {
+		let node = other;
+		while (node) {
+			if (node === this) return true;
+			node = node._parent;
+		}
+		return false;
+	}
+
+	appendChild(child) {
+		this.insertBefore(child, null);
+		return child;
+	}
+
+	insertBefore(child, refChild) {
+		if (child instanceof LynxFragment) {
+			// Real DOM semantics: the fragment itself is never attached —
+			// only its (already backend-created) children are moved in, in
+			// order, then the fragment is left empty.
+			const grandchildren = child._children.slice();
+			child._children.length = 0;
+			for (const gc of grandchildren) this.insertBefore(gc, refChild);
+			return child;
+		}
+		if (child._parent) child._parent._removeChildBookkeeping(child);
+		const index = refChild ? this._children.indexOf(refChild) : -1;
+		if (index === -1) {
+			this._children.push(child);
+		} else {
+			this._children.splice(index, 0, child);
+		}
+		child._parent = this;
+		if (this._id != null && child._id != null) {
+			this._backend.insertBefore(this._id, child._id, refChild ? refChild._id : -1);
+		}
+		return child;
+	}
+
+	removeChild(child) {
+		this._removeChildBookkeeping(child);
+		if (this._id != null && child._id != null) {
+			this._backend.removeChild(this._id, child._id);
+		}
+		return child;
+	}
+
+	_removeChildBookkeeping(child) {
+		const index = this._children.indexOf(child);
+		if (index !== -1) this._children.splice(index, 1);
+		child._parent = null;
+	}
+}
+
+function createStyleProxy(element) {
+	const methods = {
+		setProperty(name, value) {
+			element._backend.setStyleProperty(element._id, name, String(value));
+		},
+		removeProperty(name) {
+			element._backend.removeStyleProperty(element._id, name);
+		},
+	};
+	return new Proxy(methods, {
+		get(target, prop) {
+			return target[prop];
+		},
+		set(_target, prop, value) {
+			if (typeof prop !== "string") return true;
+			// Direct camelCase assignment path (CONTRACT.md §f, line 764/781).
+			// Normalized to dash-case so the backend/PAPI only ever sees one
+			// 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._backend.removeStyleProperty(element._id, name);
+			} else {
+				element._backend.setStyleProperty(element._id, name, String(value));
+			}
+			return true;
+		},
+	});
+}
+
+export class LynxElement extends LynxContainerNode {
+	constructor(ownerDocument, backend, tag, ns) {
+		super(ownerDocument);
+		this._backend = backend;
+		this.tag = tag;
+		this.namespaceURI = ns;
+		this._id = ns ? backend.createElementNS(ns, tag) : backend.createElement(tag);
+		ownerDocument._nodesById.set(this._id, this);
+		this._style = null;
+		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;
+		this.checked = undefined;
+		this.selectedIndex = undefined;
+	}
+
+	get style() {
+		if (!this._style) this._style = createStyleProxy(this);
+		return this._style;
+	}
+
+	set style(value) {
+		if (value == null || value === "") {
+			// `element.style = ""` (CONTRACT.md §f, lines 750-752): clear.
+			// We don't track which properties were set, so this relies on the
+			// backend/native side treating a style-reset op as "clear all" —
+			// see backends/virtual-backend.js `Op.SetStyleProperty` with a
+			// name of `*`.
+			this._backend.removeStyleProperty(this._id, "*");
+			return;
+		}
+		if (typeof value !== "object") {
+			// `element.style = "color: red"` (string passthrough, §f lines
+			// 753-755) — not supported: Lynx's style PAPI is key/value, not a
+			// CSS-text parser. Documented limitation, not a silent bug.
+			if (typeof console !== "undefined") {
+				console.warn(
+					"[mithril-lynx-v2] Assigning a CSS text string to `style` is not supported; use a style object.",
+				);
+			}
+			return;
+		}
+		// Mithril itself never assigns a plain object to `.style` directly —
+		// `updateStyle` always goes through `.setProperty`/property
+		// assignment for object styles (§f). This branch exists only for
+		// completeness against the DOM contract.
+		for (const key of Object.keys(value)) {
+			this.style[key] = value[key];
+		}
+	}
+
+	get className() {
+		return this._className ?? "";
+	}
+
+	set className(value) {
+		// Mithril's `setAttr`/`removeAttr` map `className` -> the `"class"`
+		// attribute (CONTRACT.md §e); routed here directly since `className`
+		// is also a real property on this class (`hasPropertyKey` would
+		// otherwise be tempted to use the property path instead).
+		this._className = value;
+		this._backend.setClasses(this._id, value == null ? "" : String(value));
+	}
+
+	setAttribute(name, value) {
+		if (name === "class") {
+			this.className = value;
+			return;
+		}
+		this._backend.setAttribute(this._id, name, value == null ? null : String(value));
+	}
+
+	removeAttribute(name) {
+		if (name === "class") {
+			this.className = "";
+			return;
+		}
+		this._backend.removeAttribute(this._id, name);
+	}
+
+	setAttributeNS(ns, name, value) {
+		this._backend.setAttributeNS(this._id, ns, name, value == null ? null : String(value));
+	}
+
+	addEventListener(type, listener) {
+		const isNew = !(type in this._listeners);
+		this._listeners[type] = listener;
+		if (isNew) this._backend.addEvent(this._id, type);
+	}
+
+	removeEventListener(type) {
+		if (!(type in this._listeners)) return;
+		delete this._listeners[type];
+		this._backend.removeEvent(this._id, type);
+	}
+
+	/** Invoked by the background-side event router when a forwarded native
+	 * event for this element's id arrives — see background.js. Mirrors what
+	 * a real DOM does automatically for an EventListener OBJECT (as opposed
+	 * to a plain function) registered via addEventListener: it calls
+	 * `.handleEvent(ev)` on it. Mithril's own `EventDict` (render.js) relies
+	 * on exactly this. */
+	dispatchEvent(event) {
+		const listener = this._listeners[event.type];
+		if (!listener) return;
+		if (typeof listener === "function") listener.call(event.currentTarget, event);
+		else if (typeof listener.handleEvent === "function") listener.handleEvent(event);
+	}
+
+	set textContent(value) {
+		// render.js only ever does `dom.textContent = ""` (first-render
+		// clear, CONTRACT.md §b line 898) — implemented as "remove every
+		// child", which is exactly what that assignment means for an
+		// already-empty-or-not container.
+		if (value !== "") {
+			if (typeof console !== "undefined") {
+				console.warn("[mithril-lynx-v2] Non-empty `textContent` assignment is not supported.");
+			}
+			return;
+		}
+		for (const child of this._children.slice()) this.removeChild(child);
+	}
+
+	set innerHTML(_value) {
+		// `m.trust()`/contenteditable sync (CONTRACT.md §c) — Lynx elements
+		// have no HTML-string target to parse into. Documented as
+		// unsupported, matching this project's existing stance on other
+		// browser-only Mithril features (e.g. `m.request`, see
+		// mithril-lynx/AGENTS.md history) rather than silently doing nothing
+		// with no signal.
+		if (typeof console !== "undefined") {
+			console.warn("[mithril-lynx-v2] `m.trust()` / innerHTML is not supported on Lynx elements.");
+		}
+	}
+
+	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.
+	}
+}
+
+export class LynxText extends LynxNode {
+	constructor(ownerDocument, backend, text) {
+		super(ownerDocument);
+		this._backend = backend;
+		this._id = backend.createText(text);
+	}
+
+	get nodeValue() {
+		return this._text;
+	}
+
+	set nodeValue(value) {
+		this._text = value;
+		this._backend.setText(this._id, value);
+	}
+}
+
+// Fragments never get a backend id — see LynxContainerNode#insertBefore,
+// which special-cases them by moving their children instead of attaching
+// the fragment itself. `_id` stays `undefined` on purpose: the `if
+// (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.
+export class LynxFragment extends LynxContainerNode {}
+
+export class LynxDocument extends LynxContainerNode {
+	constructor(backend) {
+		super(null);
+		this._backend = backend;
+		this.ownerDocument = this;
+		// id 0 is reserved for "the real page container" — pre-registered by
+		// the main-thread patch applier before any ops are replayed (see
+		// apply-patch.js). Explicit and inspectable, unlike an implicit
+		// "whatever the first created element happens to be" convention.
+		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. */
+		this._nodesById = new Map();
+	}
+
+	getNodeById(id) {
+		return this._nodesById.get(id) ?? null;
+	}
+
+	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.
+	}
+
+	set textContent(value) {
+		if (value !== "") return;
+		for (const child of this._children.slice()) this.removeChild(child);
+	}
+
+	createElement(tag) {
+		return new LynxElement(this, this._backend, tag, undefined);
+	}
+
+	createElementNS(ns, tag) {
+		return new LynxElement(this, this._backend, tag, ns);
+	}
+
+	createTextNode(text) {
+		return new LynxText(this, this._backend, text);
+	}
+
+	createDocumentFragment() {
+		return new LynxFragment(this);
+	}
+}
+
+export function createLynxDocument(backend) {
+	return new LynxDocument(backend);
+}

package/src/main-thread.d.ts

@@ -0,0 +1 @@
+export function setupRenderer(): void;

package/src/main-thread.js

@@ -0,0 +1,68 @@
+// src/main-thread.js
+//
+// Entry point for the main thread (Lepus VM). Never runs Mithril or any app
+// view code (see background.js's header, plan §3.1) — only replays patches
+// from the background thread onto real Element PAPI, and forwards native
+// events back. Structure ported from mithril-lynx v1's
+// renderer/main-thread.js (setupRenderer()), which already validated this
+// exact __RenderPage/__DestroyLifetime timing and patch-buffering behavior
+// on a real device (mithril-lynx/DEVICE_VERIFICATION.md) — that plumbing
+// was never part of the bug this rewrite exists to fix.
+
+import { createPatchApplier } from "./apply-patch.js";
+import {
+	destroyLifetimeEventName,
+	onPatchFromBackground,
+	renderPageEventName,
+	sendEventToBackground,
+} from "./channel.js";
+
+// The native engine unconditionally invokes a global `processData(initData)`
+// hook on every __RenderPage — found missing here via real-device testing
+// in mithril-lynx v1 (its main-thread.js already had this fix; its
+// renderer/main-thread.js needed it too). Required regardless of framework.
+Object.assign(globalThis, {
+	processData: (data) => data,
+});
+
+/**
+ * Call once, at main-thread.ts's top level. Waits for `__RenderPage` to
+ * create the real page (the background thread's own initial render may
+ * finish before or after that fires — patches arriving early are buffered
+ * and replayed in order once the page exists), then wires the patch/event
+ * channel for the lifetime of the page.
+ */
+export function setupRenderer() {
+	const engine = lynx.getEngine();
+	let applier = null;
+	let pageReady = false;
+	let pendingPatches = [];
+
+	const onPatch = (event) => {
+		if (!pageReady) {
+			pendingPatches.push(event.data);
+			return;
+		}
+		applier.applyPatch(event.data);
+	};
+	onPatchFromBackground(onPatch);
+
+	const onRenderPage = () => {
+		const page = __CreatePage("0", 0);
+		const pageId = __GetElementUniqueID(page);
+		applier = createPatchApplier(pageId, {
+			onEvent: (id, type, nativeEvent) => sendEventToBackground(id, type, nativeEvent),
+		});
+		applier.registerPageRoot(page);
+		pageReady = true;
+		for (const ops of pendingPatches) applier.applyPatch(ops);
+		pendingPatches = [];
+	};
+	engine.addEventListener(renderPageEventName, onRenderPage);
+
+	const onDestroyLifetime = () => {
+		engine.removeEventListener(renderPageEventName, onRenderPage);
+		engine.removeEventListener(destroyLifetimeEventName, onDestroyLifetime);
+	};
+	engine.addEventListener(destroyLifetimeEventName, onDestroyLifetime);
+}

package/src/mount-redraw.js

@@ -0,0 +1,67 @@
+// src/mount-redraw.js
+//
+// A minimal version of real Mithril's `api/mount-redraw.js`: a shared
+// singleton so `request.js` can trigger a redraw of whichever app is
+// currently mounted, without needing a direct reference to that specific
+// `renderApp()` call's handle. `background.js` registers its own
+// `performRender` here right after creating it; `route.js` could too, but
+// doesn't need to (it already redraws itself directly on every
+// navigation) — this module exists specifically so `request.js` isn't
+// coupled to "did this app mount via route() or a plain renderApp() call".
+//
+// Deliberately NOT a queue/pubsub of multiple mounted apps (real Mithril's
+// mount-redraw.js supports that because a browser page can `m.mount()`
+// several independent roots) — mithril-lynx-v2 has exactly one `renderApp()`
+// for the app's whole lifetime (plan §3.1), so "the current redraw
+// function" is a single slot, not a list.
+//
+// `redraw()` schedules instead of calling `currentRedraw()` inline — same
+// reason real Mithril's version schedules through the platform's
+// requestAnimationFrame instead of rendering synchronously: `request.js`'s
+// own `promise.then(onSuccess)` calls this BEFORE the caller's own
+// `.then()` runs (that callback is chained onto `request()`'s *returned*
+// promise, one microtask hop further back) — a synchronous redraw here
+// would render the screen one tick too early, before the caller has stored
+// the response in its own state.
+//
+// DEVICE-CONFIRMED LYNX QUIRK (see FETCH_INVESTIGATION.md): unlike a spec
+// browser, where a macrotask (rAF, setTimeout) is guaranteed to run only
+// after every currently-queued microtask (including ones enqueued by other
+// microtasks) has drained, on this Lynx background-thread runtime BOTH
+// `lynx.setTimeout(fn, 0)` and `lynx.requestAnimationFrame(fn)` fire before
+// even the FIRST pending microtask — confirmed with a Promise chain logging
+// three chained `.then()`s against a 0ms/1ms/4ms/16ms timer and against
+// `requestAnimationFrame`: the timer/rAF callback always logged first. A
+// 50ms delay was the first value that reliably let a single `.then()`
+// (the realistic caller shape: `request(url).then(cb)`) run first. There is
+// no known Lynx primitive that defers "until microtasks finish" the way a
+// spec-compliant macrotask does — this delay is an empirical safety margin,
+// not a scheduling guarantee.
+const REDRAW_DELAY_MS = 50;
+
+let currentRedraw = null;
+let pending = false;
+
+function schedule(fn) {
+	const timer = typeof lynx !== "undefined" && typeof lynx.setTimeout === "function" ? lynx.setTimeout.bind(lynx) : setTimeout;
+	timer(fn, REDRAW_DELAY_MS);
+}
+
+export function register(redraw) {
+	currentRedraw = redraw;
+}
+
+/** 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
+ * necessarily a bug the way calling commit() before mounting is. Multiple
+ * calls within the delay window collapse into a single scheduled render,
+ * same debounce real Mithril's `redraw()` does with its `pending` flag. */
+export function redraw() {
+	if (pending) return;
+	pending = true;
+	schedule(() => {
+		pending = false;
+		if (currentRedraw != null) currentRedraw();
+	});
+}

package/src/patch-protocol.js

@@ -0,0 +1,40 @@
+// src/patch-protocol.js
+//
+// The wire vocabulary between the background thread (real Mithril diff,
+// running against a virtual tree) and the main thread (applies the patch to
+// real Lynx elements). Adopted from ReactLynx's `SnapshotOperation` pattern
+// (see rspeedy-react-analysis/LYNX_PAPI_SPEC.md §4.3): a FLAT array of
+// numbers/strings/values, not an array of `{op, ...}` objects — cheaper to
+// serialize, and a pattern already proven in production at ReactLynx's scale.
+//
+// Every op is `[opcode, ...args]` concatenated into one flat array. `id`
+// below always refers to the integer handle a node was given by
+// `createVirtualBackend()` — the SAME id space is mirrored 1:1 on the
+// main-thread side by `applyPatch()` (see backends/papi-backend.js), so
+// nodes never need to be looked up by anything other than that integer.
+
+export const Op = Object.freeze({
+	CreateElement: 0,
+	CreateElementNS: 1,
+	CreateText: 2,
+	CreateFragment: 3,
+	InsertBefore: 4, // parentId, childId, refId(-1 = append)
+	RemoveChild: 5, // parentId, childId
+	SetAttribute: 6, // id, name, value
+	RemoveAttribute: 7, // id, name
+	SetAttributeNS: 8, // id, ns, name, value
+	SetStyleProperty: 9, // id, name, value (dash-case, via setProperty semantics)
+	RemoveStyleProperty: 10, // id, name
+	SetText: 11, // id, value (nodeValue on a text node)
+	AddEvent: 12, // id, type
+	RemoveEvent: 13, // id, type
+});
+
+/**
+ * Encodes one op onto a flat ops array. Kept as a tiny helper (not a class)
+ * so the hot path (called on every attribute/child mutation during a real
+ * Mithril diff) is just array pushes — no object allocation per op.
+ */
+export function pushOp(ops, opcode, ...args) {
+	ops.push(opcode, ...args);
+}

package/src/reload/version.js

@@ -0,0 +1,28 @@
+// src/reload/version.js
+//
+// Race guard for concurrent hot-updates (method A/B, reload/hot-accept.js).
+// v1 had this bug for real: two rebuilds landing close together made the
+// dev client see a `module.hot.check()` still in flight and degrade to a
+// full reload EVEN THOUGH each edit individually would have been light
+// (mithril-lynx/.omo/plans/arquitectura-dual-reload.md, F1 "race de
+// doble-build"). ReactLynx doesn't avoid the race with a status flag at
+// all — it lets both builds' patches land in whatever order they arrive,
+// and discards any patch whose `reloadVersion` is older than the current
+// one (rspeedy-react-analysis/LYNX_PAPI_SPEC.md §5.1). This is that same
+// counter, adopted directly rather than re-deriving a flag-based guard.
+
+let version = 0;
+
+export function getReloadVersion() {
+	return version;
+}
+
+export function increaseReloadVersion() {
+	return ++version;
+}
+
+/** True if a patch stamped with `patchVersion` is stale and must be
+ * dropped without being applied — the ENTIRE guard, one comparison. */
+export function isStaleVersion(patchVersion) {
+	return typeof patchVersion === "number" && patchVersion < version;
+}

package/src/request.d.ts

@@ -0,0 +1,37 @@
+export interface RequestOptions<T = any> {
+	method?: string;
+	url?: string;
+	params?: Record<string, unknown>;
+	body?: unknown;
+	headers?: Record<string, string>;
+	timeout?: number;
+	signal?: AbortSignal;
+	responseType?: "json" | "text";
+	serialize?: (data: unknown) => string;
+	deserialize?: (data: unknown) => unknown;
+	extract?: (response: unknown, options: RequestOptions<T>) => unknown;
+	type?: new (data: any) => T;
+	background?: boolean;
+	// Present on the real m.request signature but confirmed unsupported —
+	// listed here (rather than omitted) so passing one is a type error at
+	// the call site, not a surprise at runtime.
+	config?: never;
+	async?: never;
+	user?: never;
+	password?: never;
+	withCredentials?: never;
+}
+
+export interface RequestPromise<T> extends Promise<T> {
+	/** Not part of real m.request's API — free to add since Lynx's
+	 * AbortController makes it a real, working cancellation, unlike the
+	 * `config`-only escape hatch losing `config` takes away. */
+	abort(): void;
+}
+
+export type Request = <T = any>(url: string | RequestOptions<T>, options?: RequestOptions<T>) => RequestPromise<T>;
+
+export function createRequestor(fetchImpl?: (url: string, init: RequestInit) => Promise<Response>): Request;
+
+declare const request: Request;
+export default request;