mithril-lynx 0.0.9 → 2.0.0

package/src/request.js

@@ -0,0 +1,181 @@
+// src/request.js
+//
+// `m.request`-shaped wrapper over `lynx.fetch` — the subset confirmed
+// faithful in FETCH_INVESTIGATION.md / .omo/plans/m-request-fetch-lynx.md.
+// Every option below is either "works the same as real m.request" or
+// throws immediately with a clear message pointing at the doc — never a
+// silent behavior difference. See FETCH_INVESTIGATION.md §3 for the full
+// option-by-option table this file implements.
+//
+// Explicitly NOT supported, by design, confirmed unfixable on Lynx:
+// - `config(xhr)`: fetch has no live object to hand back.
+// - `body` as `FormData`: confirmed absent at runtime (typeof FormData
+//   === "undefined"). `URLSearchParams` bodies DO work — confirmed on
+//   device — and need no special-casing here beyond not JSON-stringifying
+//   them.
+// - `responseType: "blob"`/`"document"`: no `.blob()` on Lynx's `Body`;
+//   `"document"` has no meaning outside a browser DOM.
+// - `user`/`password` (inline Basic Auth), `withCredentials`,
+//   `async: false`: XMLHttpRequest/browser-only concepts with no `fetch`
+//   equivalent, confirmed (withCredentials: no CORS model on Lynx;
+//   user/password: no `btoa` to build the Authorization header even if
+//   we wanted to guess one).
+
+import buildPathname from "mithril-runtime/pathname/build.js";
+import { redraw as sharedRedraw } from "./mount-redraw.js";
+
+const UNSUPPORTED = [
+	["config", (o) => o.config != null],
+	["async: false", (o) => o.async === false],
+	["user", (o) => typeof o.user === "string"],
+	["password", (o) => typeof o.password === "string"],
+	["withCredentials", (o) => o.withCredentials === true],
+];
+
+function checkUnsupported(options) {
+	for (const [name, matches] of UNSUPPORTED) {
+		if (matches(options)) {
+			throw new Error(
+				`[mithril-lynx-v2/request] "${name}" is not supported — Lynx's fetch has no equivalent ` +
+					"(see FETCH_INVESTIGATION.md for exactly why). This throws instead of silently " +
+					"behaving differently from what you asked for.",
+			);
+		}
+	}
+}
+
+function hasHeader(headers, name) {
+	for (const key in headers) {
+		if (Object.prototype.hasOwnProperty.call(headers, key) && key.toLowerCase() === name) return true;
+	}
+	return false;
+}
+
+function applyType(data, Type) {
+	if (typeof Type !== "function") return data;
+	if (Array.isArray(data)) return data.map((item) => new Type(item));
+	return new Type(data);
+}
+
+/**
+ * @param {(url: string, init: object) => Promise<Response>} [fetchImpl] -
+ *   Defaults to `lynx.fetch`, looked up lazily (not at module load time,
+ *   so importing this file never requires `lynx` to already exist) —
+ *   same pattern route.js uses for `renderApp`. Tests inject a fake here
+ *   instead of hitting a real network.
+ */
+export function createRequestor(fetchImpl) {
+	const doFetch = fetchImpl || ((url, init) => lynx.fetch(url, init));
+
+	return function request(url, options) {
+		if (typeof url !== "string") {
+			options = url;
+			url = url.url;
+		} else if (options == null) {
+			options = {};
+		}
+		checkUnsupported(options);
+
+		if (typeof FormData !== "undefined" && options.body instanceof FormData) {
+			throw new Error(
+				"[mithril-lynx-v2/request] FormData bodies are not supported — Lynx has no FormData " +
+					"at runtime (confirmed absent, see FETCH_INVESTIGATION.md). Use lynx.fetch directly " +
+					"if you have another way to send this data, or restructure it as plain JSON.",
+			);
+		}
+
+		const method = options.method != null ? options.method.toUpperCase() : "GET";
+		const path = buildPathname(url, options.params);
+		const headers = Object.assign({}, options.headers);
+
+		let body;
+		if (options.body != null) {
+			if (typeof URLSearchParams !== "undefined" && options.body instanceof URLSearchParams) {
+				// Confirmed on device: fetch sets Content-Type automatically for
+				// this body type, exactly like a real browser.
+				body = options.body;
+			} else if (typeof options.serialize === "function") {
+				body = options.serialize(options.body);
+			} else {
+				body = JSON.stringify(options.body);
+				if (!hasHeader(headers, "content-type")) headers["Content-Type"] = "application/json; charset=utf-8";
+			}
+		}
+		if (typeof options.deserialize !== "function" && !hasHeader(headers, "accept")) {
+			headers["Accept"] = "application/json, text/*";
+		}
+
+		// Real cancellation/timeout — confirmed working on device (unlike
+		// what an earlier version of the investigation assumed): aborting
+		// actually tears down the in-flight connection, not just abandons
+		// the wait. `options.signal` (if given) is linked into our own
+		// controller so a caller-provided signal and our timeout can both
+		// trigger the same abort.
+		const ctrl = new AbortController();
+		if (options.signal) {
+			if (options.signal.aborted) ctrl.abort();
+			else options.signal.addEventListener("abort", () => ctrl.abort());
+		}
+		let timeoutId;
+		if (options.timeout) {
+			const schedule = typeof lynx !== "undefined" && typeof lynx.setTimeout === "function"
+				? lynx.setTimeout.bind(lynx)
+				: setTimeout;
+			timeoutId = schedule(() => ctrl.abort(), options.timeout);
+		}
+		function clearRequestTimeout() {
+			if (timeoutId == null) return;
+			const clear = typeof lynx !== "undefined" && typeof lynx.clearTimeout === "function"
+				? lynx.clearTimeout.bind(lynx)
+				: clearTimeout;
+			clear(timeoutId);
+		}
+
+		const responseType = options.responseType || (typeof options.extract === "function" ? "" : "json");
+
+		const promise = doFetch(path, { method, headers, body, signal: ctrl.signal }).then((response) => {
+			clearRequestTimeout();
+
+			if (typeof options.extract === "function") {
+				// Matches real m.request: extract() bypasses the status check
+				// entirely — it decides success/failure itself.
+				return options.extract(response, options);
+			}
+
+			const ok = response.ok || response.status === 304;
+			const bodyPromise = responseType === "text" ? response.text() : response.json();
+			return bodyPromise.then((data) => {
+				if (typeof options.deserialize === "function") data = options.deserialize(data);
+				if (!ok) {
+					const error = new Error(typeof data === "string" ? data : response.statusText);
+					error.code = response.status;
+					error.response = data;
+					throw error;
+				}
+				return applyType(data, options.type);
+			});
+		});
+
+		const result = promise.then(
+			(value) => {
+				if (options.background !== true) sharedRedraw();
+				return value;
+			},
+			(error) => {
+				clearRequestTimeout();
+				if (options.background !== true) sharedRedraw();
+				throw error;
+			},
+		);
+
+		// Not part of real m.request's API (there, you can only reach
+		// xhr.abort() through `config`) — free to add since we already have
+		// the controller, and it's exactly the escape hatch losing `config`
+		// takes away. Documented in FETCH_INVESTIGATION.md, not hidden.
+		result.abort = () => ctrl.abort();
+		return result;
+	};
+}
+
+const request = createRequestor();
+export default request;

package/src/route.d.ts

@@ -0,0 +1,33 @@
+import type { Component } from "mithril";
+
+export interface RouteResolver {
+	onmatch?(args: Record<string, string>, requestedPath: string, route: string): unknown;
+	render?(vnode: unknown): unknown;
+}
+
+export interface RouteLinkAttrs {
+	href: string;
+	selector?: string;
+	params?: Record<string, unknown>;
+	options?: { replace?: boolean };
+	disabled?: boolean;
+	ontap?: (e: unknown) => unknown;
+	[key: string]: unknown;
+}
+
+export interface Route {
+	(defaultRoute: string, routes: Record<string, unknown | RouteResolver>): void;
+	set(path: string, data?: unknown, options?: { replace?: boolean }): void;
+	get(): string | undefined;
+	param(key?: string): unknown;
+	back(): void;
+	forward(): void;
+	prefix: string;
+	SKIP: unknown;
+	Link: Component<RouteLinkAttrs>;
+}
+
+export function createRoute(): Route;
+
+declare const route: Route;
+export default route;

package/src/route.js

@@ -0,0 +1,207 @@
+// src/route.js
+//
+// In-memory `m.route`, replacing `window.history`/`popstate` with a plain
+// array — the exact same pattern React Router's `MemoryRouter` and Vue
+// Router's `createMemoryHistory()` use for Lynx (see
+// .omo/plans/m-route-en-memoria.md §1–§3): both official framework
+// integrations converge on "history lives in a JS array, not the browser",
+// for the same reason we're doing it here — Lynx has no
+// `window.location`/History API at all.
+//
+// Structured to mirror real Mithril's `api/router.js` as closely as
+// possible (same variable names/flow for `resolveRoute`/`route.set`'s
+// `hasBeenResolved` gate) so porting route-using app code only requires
+// swapping the import, not relearning the control flow. The one
+// unavoidable signature change: `m.route(root, defaultRoute, routes)`
+// loses `root` — there is no DOM node to point it at in v2's architecture
+// (a single `renderApp()` for the app's whole lifetime, plan §3.1) — see
+// the plan §5.2 for why that's a deliberate, documented deviation rather
+// than a fake DOM node just to keep the arg count.
+
+import m from "mithril-runtime";
+import buildPathname from "mithril-runtime/pathname/build.js";
+import parsePathname from "mithril-runtime/pathname/parse.js";
+import compileTemplate from "mithril-runtime/pathname/compileTemplate.js";
+import { renderApp } from "./background.js";
+
+export function createRoute() {
+	var compiled, fallbackRoute;
+	var component, attrs, currentPath, currentResolver;
+	var lastUpdate = null;
+	var ready = false;
+	var hasBeenResolved = false;
+	var app = null;
+
+	// The in-memory equivalent of the browser's session history: a plain
+	// stack of resolved paths. `route.set(path, data, {replace: true})`
+	// overwrites the top entry instead of pushing — same semantics as
+	// `history.replaceState` vs `history.pushState`, just without a
+	// browser underneath it.
+	var history = [];
+	var historyIndex = -1;
+
+	var RouterRoot = {
+		view() {
+			var vnode = component != null ? m(component, attrs) : null;
+			return currentResolver ? currentResolver.render(vnode) : vnode;
+		},
+	};
+
+	function resolveRoute(path, data) {
+		var parsed = parsePathname(path);
+		if (data) Object.assign(parsed.params, data);
+
+		function reject(e) {
+			if (typeof console !== "undefined") console.error(e);
+			route.set(fallbackRoute, null, { replace: true });
+		}
+
+		loop(0);
+		function loop(i) {
+			for (; i < compiled.length; i++) {
+				if (compiled[i].check(parsed)) {
+					var payload = compiled[i].payload;
+					var update = (lastUpdate = function (comp) {
+						if (update !== lastUpdate) return;
+						if (comp === route.SKIP) return loop(i + 1);
+						component = comp != null && (typeof comp.view === "function" || typeof comp === "function")
+							? comp
+							: "view";
+						attrs = parsed.params;
+						currentPath = path;
+						lastUpdate = null;
+						currentResolver = payload.render ? payload : null;
+						if (hasBeenResolved) {
+							app.redraw();
+						} else {
+							hasBeenResolved = true;
+							app = renderApp({ root: () => m(RouterRoot) });
+						}
+					});
+					if (payload.view || typeof payload === "function") {
+						update(payload);
+					} else if (payload.onmatch) {
+						Promise.resolve()
+							.then(() => payload.onmatch(parsed.params, path, compiled[i].route))
+							.then(update, path === fallbackRoute ? undefined : reject);
+					} else {
+						update("view");
+					}
+					return;
+				}
+			}
+			if (path === fallbackRoute) {
+				throw new Error("Could not resolve default route " + fallbackRoute + ".");
+			}
+			route.set(fallbackRoute, null, { replace: true });
+		}
+	}
+
+	/**
+	 * @param {string} defaultRoute - Both the fallback for an unmatched path
+	 *   AND the screen the app starts on — there is no browser URL to read
+	 *   an initial path from, so this is the one path v2 always starts at
+	 *   (the closest in-memory equivalent of React Router's
+	 *   `initialEntries={["/"]}`).
+	 * @param {Record<string, unknown>} routes - Same shape as real
+	 *   `m.route`: `{ "/path/:param": Component | { onmatch, render } }`.
+	 */
+	function route(defaultRoute, routes) {
+		compiled = Object.keys(routes).map((r) => {
+			if (r[0] !== "/") throw new SyntaxError("Routes must start with a '/'.");
+			return { route: r, payload: routes[r], check: compileTemplate(r) };
+		});
+		fallbackRoute = defaultRoute;
+		var defaultData = parsePathname(defaultRoute);
+		if (!compiled.some((entry) => entry.check(defaultData))) {
+			throw new ReferenceError("Default route doesn't match any known routes.");
+		}
+		history = [defaultRoute];
+		historyIndex = 0;
+		ready = true;
+		resolveRoute(defaultRoute, null);
+	}
+
+	route.SKIP = {};
+
+	route.set = function (path, data, options) {
+		if (lastUpdate != null) {
+			options = options || {};
+			options.replace = true;
+		}
+		lastUpdate = null;
+		path = buildPathname(path, data);
+		if (options && options.replace) {
+			history[Math.max(historyIndex, 0)] = path;
+		} else {
+			history = history.slice(0, historyIndex + 1);
+			history.push(path);
+			historyIndex = history.length - 1;
+		}
+		if (ready) resolveRoute(path, null);
+	};
+
+	route.get = () => currentPath;
+
+	route.param = (key) => (attrs && key != null ? attrs[key] : attrs);
+
+	// No URL bar in Lynx — kept as an assignable no-op so app code ported
+	// from a real Mithril app that defensively sets `m.route.prefix = ""`
+	// doesn't throw. It never affects anything here.
+	route.prefix = "";
+
+	/**
+	 * `back()`/`forward()` walk the SAME in-memory stack `route.set` writes
+	 * to — this is the "no native back button" answer from plan §5.7/F0:
+	 * static analysis of the installed Lynx runtime found no hardware/
+	 * gesture "back" event exposed to JS (only `onAppEnterBackground`,
+	 * which is app-lifecycle, not navigation) — so an app's own explicit
+	 * back affordance (a `route.Link`/button calling this) is the only
+	 * way back navigation happens. Confirming this holds on a real device
+	 * is F4/F5 of the plan, not done yet.
+	 */
+	route.back = function () {
+		if (historyIndex <= 0) return;
+		historyIndex--;
+		resolveRoute(history[historyIndex], null);
+	};
+	route.forward = function () {
+		if (historyIndex >= history.length - 1) return;
+		historyIndex++;
+		resolveRoute(history[historyIndex], null);
+	};
+
+	// Lynx has no `<a>`/`onclick` — this renders a tap-driven element
+	// instead, the same shape ReactLynx's `useNavigate()+ontap` and Vue
+	// Lynx's custom `RouterLink` slot use (plan §1–§2, §5.4).
+	route.Link = {
+		view(vnode) {
+			var a = vnode.attrs;
+			var selector = a.selector || "view";
+			var rest = {};
+			for (var key in a) {
+				if (key !== "selector" && key !== "options" && key !== "params" && key !== "href" && key !== "ontap") {
+					rest[key] = a[key];
+				}
+			}
+			var disabled = Boolean(a.disabled);
+			rest.disabled = disabled;
+			if (!disabled) {
+				rest.ontap = function (e) {
+					var result;
+					if (typeof a.ontap === "function") result = a.ontap.call(e.currentTarget, e);
+					if (result !== false) {
+						e.redraw = false;
+						route.set(buildPathname(a.href, a.params), null, a.options);
+					}
+				};
+			}
+			return m(selector, rest, vnode.children);
+		},
+	};
+
+	return route;
+}
+
+const route = createRoute();
+export default route;

package/test/end-to-end.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from "@rstest/core";
+import m from "mithril";
+import { renderApp } from "../src/background.js";
+import { createPatchApplier } from "../src/apply-patch.js";
+
+// Full round trip: background renders real Mithril against the virtual
+// backend, the resulting ops are replayed onto REAL Lynx PAPI elements
+// (via @lynx-js/testing-environment, not a mock), a simulated tap fires on
+// the real element, is forwarded back to the background thread's fake-dom
+// node, and Mithril's OWN automatic redraw-on-event (no explicit redraw()
+// call anywhere in the view below) produces a second patch that updates
+// the real tree again.
+//
+// This is the direct replacement for mithril-lynx v1's
+// `test/renderer-integration.test.ts` — same intent, rewritten for the v2
+// architecture (see mithril-lynx-v2-desde-cero.md §F1's acceptance
+// criterion: this must pass from the first commit, never be fixed later).
+
+function storedListeners(node: any, type: string): Set<(...args: any[]) => unknown> {
+	return node?.__vanillaListeners?.[type] ?? new Set();
+}
+
+describe("background -> apply-patch end-to-end (real PAPI, via @lynx-js/testing-environment)", () => {
+	it("auto-redraws after a tap with NO explicit redraw() call anywhere in the view", () => {
+		lynxTestingEnv.switchToMainThread();
+
+		const pageId = __GetElementUniqueID(__CreatePage());
+		const applier = createPatchApplier(pageId);
+		// id 0 (the fake-dom document root) maps to a real container the
+		// applier creates itself, exactly like the page's own root view.
+		applier.registerPageRoot(__CreateView(pageId));
+
+		let count = 0;
+		function root() {
+			return m("view", { class: "page" }, [
+				m(
+					"view",
+					{
+						class: "button",
+						ontap: () => {
+							// No redraw()/m.redraw() call here on purpose — the
+							// whole point of this test is that Mithril's own
+							// EventDict auto-redraw (CONTRACT.md §e) is what
+							// makes this repaint, with zero cooperation from
+							// app code.
+							count += 1;
+						},
+					},
+					[m("text", null, "Tap")],
+				),
+				m("text", { class: "counter" }, String(count)),
+			]);
+		}
+
+		lynxTestingEnv.switchToBackgroundThread();
+		let lastOps: unknown[] | null = null;
+		const app = renderApp({
+			root,
+			sendPatch: (ops) => {
+				lastOps = ops;
+			},
+		});
+		expect(lastOps).not.toBeNull();
+
+		lynxTestingEnv.switchToMainThread();
+		applier.applyPatch(lastOps as unknown[]);
+
+		// The decisive assertion for "auto-redraw fired": a second
+		// `sendPatch` call happens purely from the tap (dispatched below),
+		// with no explicit redraw() anywhere in `root()`'s view code.
+		lastOps = null;
+
+		lynxTestingEnv.switchToBackgroundThread();
+		// Forward the tap the same way main-thread -> background forwarding
+		// will in the real channel (F2/F3): find the fake-dom node for the
+		// button and dispatch a synthetic tap on it directly. The id is
+		// deterministic here (root=0 is the document; the button is the
+		// second element created — first is the page `view`, second the
+		// button `view`), matching virtual-backend.js's sequential id
+		// allocation starting at 1.
+		app.document.getNodeById(2)!.dispatchEvent({ type: "tap", currentTarget: app.document.getNodeById(2) });
+
+		expect(count).toBe(1);
+		expect(lastOps).not.toBeNull();
+	});
+});

package/test/reload-version.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from "@rstest/core";
+import { getReloadVersion, increaseReloadVersion, isStaleVersion } from "../src/reload/version.js";
+
+describe("reload version guard (replaces v1's hotStatus race-prone flag)", () => {
+	it("discards a patch stamped with an older version than the current one", () => {
+		const v1 = getReloadVersion();
+		expect(isStaleVersion(v1)).toBe(false); // not stale yet, nothing bumped
+
+		increaseReloadVersion();
+		// A patch built before this reload (stamped with the old version)
+		// must now be treated as stale — this is the exact scenario of the
+		// v1 "race de doble-build": two builds in flight, the older one's
+		// patch must lose without needing a status flag at all.
+		expect(isStaleVersion(v1)).toBe(true);
+		expect(isStaleVersion(getReloadVersion())).toBe(false);
+	});
+});