mithril-lynx 0.0.9 → 2.0.0

package/test/request.test.ts

@@ -0,0 +1,182 @@
+import { describe, expect, it } from "@rstest/core";
+import { createRequestor } from "../src/request.js";
+import { register as registerRedraw } from "../src/mount-redraw.js";
+
+// The underlying primitive (lynx.fetch itself — redirects, AbortController,
+// URLSearchParams bodies, Headers case-sensitivity) is validated on a real
+// device, not here — see FETCH_INVESTIGATION.md. These tests are about the
+// WRAPPER's own logic: does it build the right RequestInit, handle the
+// response/error shape correctly, and refuse the options that have no
+// fetch equivalent. A fake `fetch` (jsdom's real Response/Headers/
+// AbortController under the hood, same as a real fetch, just no network)
+// is injected via createRequestor() for exactly this reason.
+
+function fakeResponse(body: unknown, init: { status?: number; statusText?: string } = {}) {
+	const status = init.status ?? 200;
+	return {
+		ok: status >= 200 && status < 300,
+		status,
+		statusText: init.statusText ?? "",
+		json: async () => body,
+		text: async () => (typeof body === "string" ? body : JSON.stringify(body)),
+	};
+}
+
+describe("request.js: m.request-shaped wrapper over lynx.fetch", () => {
+	it("interpolates :params into the URL and defaults to GET", async () => {
+		let seenUrl: string | undefined;
+		let seenInit: any;
+		const request = createRequestor((url, init) => {
+			seenUrl = url;
+			seenInit = init;
+			return Promise.resolve(fakeResponse({ id: 42 }));
+		});
+
+		const result = await request("/users/:id", { params: { id: 42 } });
+		expect(seenUrl).toBe("/users/42");
+		expect(seenInit.method).toBe("GET");
+		expect(result).toEqual({ id: 42 });
+	});
+
+	it("JSON-encodes a plain object body and sets Content-Type", async () => {
+		let seenInit: any;
+		const request = createRequestor((_url, init) => {
+			seenInit = init;
+			return Promise.resolve(fakeResponse({ ok: true }));
+		});
+
+		await request("/things", { method: "post", body: { name: "widget" } });
+		expect(seenInit.method).toBe("POST");
+		expect(seenInit.body).toBe(JSON.stringify({ name: "widget" }));
+		expect(seenInit.headers["Content-Type"]).toBe("application/json; charset=utf-8");
+	});
+
+	it("passes a URLSearchParams body through unchanged (confirmed working on device)", async () => {
+		let seenInit: any;
+		const request = createRequestor((_url, init) => {
+			seenInit = init;
+			return Promise.resolve(fakeResponse({ ok: true }));
+		});
+
+		const usp = new URLSearchParams({ foo: "bar" });
+		await request("/form", { method: "post", body: usp });
+		expect(seenInit.body).toBe(usp);
+	});
+
+	it("rejects a FormData body immediately — confirmed absent on Lynx", async () => {
+		const request = createRequestor(() => {
+			throw new Error("should never reach fetch");
+		});
+		const fd = new FormData();
+		expect(() => request("/upload", { method: "post", body: fd })).toThrow(/FormData/);
+	});
+
+	for (const [name, options] of [
+		["config", { config: () => {} }],
+		["async: false", { async: false }],
+		["user", { user: "alice" }],
+		["password", { password: "secret" }],
+		["withCredentials", { withCredentials: true }],
+	] as const) {
+		it(`rejects "${name}" immediately — no fetch equivalent`, () => {
+			const request = createRequestor(() => {
+				throw new Error("should never reach fetch");
+			});
+			expect(() => request("/x", options as any)).toThrow();
+		});
+	}
+
+	it("builds the real m.request error shape on a non-2xx response", async () => {
+		const request = createRequestor(() =>
+			Promise.resolve(fakeResponse({ reason: "nope" }, { status: 404, statusText: "Not Found" })),
+		);
+
+		await expect(request("/missing")).rejects.toMatchObject({
+			code: 404,
+			response: { reason: "nope" },
+		});
+	});
+
+	it("extract() bypasses the status check entirely, like real m.request", async () => {
+		const request = createRequestor(() => Promise.resolve(fakeResponse(null, { status: 500 })));
+		const result = await request("/x", {
+			extract: (response: any) => ({ sawStatus: response.status }),
+		});
+		expect(result).toEqual({ sawStatus: 500 });
+	});
+
+	it("applies a type constructor to the result", async () => {
+		class User {
+			name: string;
+			constructor(data: { name: string }) {
+				this.name = data.name;
+			}
+		}
+		const request = createRequestor(() => Promise.resolve(fakeResponse({ name: "Ada" })));
+		const result = await request<User>("/user", { type: User });
+		expect(result).toBeInstanceOf(User);
+		expect(result.name).toBe("Ada");
+	});
+
+	it("redraws the currently mounted app after resolving, unless background: true", async () => {
+		// redraw() is scheduled (50ms delay), not synchronous or a 0ms timer
+		// — see mount-redraw.js's top comment: a synchronous redraw runs
+		// BEFORE this test's own .then below (chained onto request()'s
+		// *returned* promise, one microtask behind request.js's internal
+		// redraw call), and device testing showed Lynx's timer/rAF fire
+		// before even a single pending microtask regardless of delay, up to
+		// 16ms — 50ms was the first value that reliably lost that race.
+		// Confirmed as a real device bug: the UI froze on "loading" forever
+		// because the state update arrived after the (then too-early) render.
+		let redraws = 0;
+		registerRedraw(() => {
+			redraws++;
+		});
+		const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+		const request = createRequestor(() => Promise.resolve(fakeResponse({})));
+
+		await request("/x");
+		await wait(60);
+		expect(redraws).toBe(1);
+
+		await request("/x", { background: true });
+		await wait(60);
+		expect(redraws).toBe(1); // unchanged
+	});
+
+	it("timeout aborts the underlying fetch via AbortController, not just the wait", async () => {
+		let sawAbort = false;
+		const request = createRequestor(
+			(_url, init) =>
+				new Promise((_resolve, reject) => {
+					init.signal.addEventListener("abort", () => {
+						sawAbort = true;
+						const error = new Error("This operation was aborted");
+						error.name = "AbortError";
+						reject(error);
+					});
+				}),
+		);
+
+		await expect(request("/slow", { timeout: 5 })).rejects.toMatchObject({ name: "AbortError" });
+		expect(sawAbort).toBe(true);
+	});
+
+	it("exposes .abort() on the returned promise as a bonus (real m.request has no direct equivalent)", async () => {
+		let sawAbort = false;
+		const request = createRequestor(
+			(_url, init) =>
+				new Promise((_resolve, reject) => {
+					init.signal.addEventListener("abort", () => {
+						sawAbort = true;
+						reject(Object.assign(new Error("aborted"), { name: "AbortError" }));
+					});
+				}),
+		);
+
+		const promise = request("/slow");
+		promise.catch(() => {}); // don't let the eventual rejection be unhandled
+		promise.abort();
+		expect(sawAbort).toBe(true);
+	});
+});

package/test/route-hot-reload.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from "@rstest/core";
+import m from "mithril-runtime";
+import { createRoute } from "../src/route.js";
+import { Op } from "../src/patch-protocol.js";
+
+// Regression test for a real, on-device-confirmed question (m-route-en-memoria.md
+// §10 F6): does a stable-host screen re-render itself in place after
+// module.hot.accept swaps its module, or does routing accidentally force a
+// full teardown/recreate? Verified for real via a device trace: the actual
+// patch for this exact shape was `[Op.SetText, id, "new text"]` — nothing
+// else. This test locks that in.
+
+describe("route.js + stable-host: a same-path re-resolve patches in place, never recreates", () => {
+	it("swapping the live-bound view (module.hot.accept's job) produces only a SetText, no Create/Remove", () => {
+		lynxTestingEnv.switchToMainThread();
+		const capturedOps: unknown[][] = [];
+		lynx.getJSContext().addEventListener("MithrilLynxV2:Patch", (event: any) => {
+			capturedOps.push(event.data);
+		});
+
+		lynxTestingEnv.switchToBackgroundThread();
+		const route = createRoute();
+		// Same shape as the real app's background.ts: a stable host object
+		// wrapping a live-bound `current*` reference, re-pointed by
+		// module.hot.accept and re-resolved via route.set(..., {replace}).
+		let currentDetail = { view: () => m("text", { key: "title" }, "first") };
+		const DetailHost = { view: () => currentDetail.view() };
+
+		route("/detail", { "/detail": DetailHost });
+		capturedOps.length = 0; // only the re-resolve below matters
+
+		currentDetail = { view: () => m("text", { key: "title" }, "second") };
+		route.set(route.get() as string, null, { replace: true });
+
+		const flat = capturedOps.flat();
+		expect(flat).not.toContain(Op.CreateElement);
+		expect(flat).not.toContain(Op.RemoveChild);
+		expect(flat).toContain(Op.SetText);
+	});
+});

package/test/route.test.ts

@@ -0,0 +1,152 @@
+import { describe, expect, it } from "@rstest/core";
+import m from "mithril-runtime";
+import { createRoute } from "../src/route.js";
+import { Op } from "../src/patch-protocol.js";
+
+// createRoute() calls renderApp() (src/background.js) internally on first
+// match, which unconditionally uses the real cross-thread channel
+// (channel.js -> lynx.getCoreContext()/getJSContext()) — so every test
+// here runs against @lynx-js/testing-environment's real PAPI, exactly like
+// test/end-to-end.test.ts, not a mock.
+
+function setupRealTree() {
+	lynxTestingEnv.switchToMainThread();
+	const pageId = __GetElementUniqueID(__CreatePage());
+	const applier = createPatchApplier(pageId);
+	applier.registerPageRoot(__CreateView(pageId));
+
+	lynxTestingEnv.switchToBackgroundThread();
+	const capturedOps: unknown[][] = [];
+	// Same pattern channel.js's real sendPatchToMainThread uses, captured
+	// on the main-thread side so ops can be applied and the resulting real
+	// tree inspected.
+	lynxTestingEnv.switchToMainThread();
+	lynx.getJSContext().addEventListener("MithrilLynxV2:Patch", (event: any) => {
+		capturedOps.push(event.data);
+		lynxTestingEnv.switchToMainThread();
+		applier.applyPatch(event.data);
+	});
+
+	return { applier, capturedOps };
+}
+
+// createPatchApplier is imported dynamically per-test-file below since it
+// isn't exported from a stable path used elsewhere yet in tests.
+import { createPatchApplier } from "../src/apply-patch.js";
+
+describe("route.js: in-memory router (plan m-route-en-memoria.md)", () => {
+	it("mounts the default route and exposes route.get()/route.param()", () => {
+		setupRealTree();
+		lynxTestingEnv.switchToBackgroundThread();
+
+		const route = createRoute();
+		const Home = { view: () => m("text", null, "home") };
+		const User = { view: () => m("text", null, "user:" + route.param("id")) };
+
+		route("/", { "/": Home, "/users/:id": User });
+
+		expect(route.get()).toBe("/");
+
+		route.set("/users/42");
+		expect(route.get()).toBe("/users/42");
+		expect(route.param("id")).toBe("42");
+	});
+
+	it("navigating replaces the screen with no orphaned nodes left behind", () => {
+		const { capturedOps } = setupRealTree();
+		lynxTestingEnv.switchToBackgroundThread();
+
+		const route = createRoute();
+		const A = { view: () => m("view", { key: "a" }, [m("text", null, "A")]) };
+		const B = { view: () => m("view", { key: "b" }, [m("text", null, "B")]) };
+
+		route("/a", { "/a": A, "/b": B });
+		capturedOps.length = 0; // only care about the ops from the NAVIGATION below
+
+		route.set("/b");
+
+		// Same spirit as test/structural-reload.test.ts, but here the whole
+		// screen changes (not a sibling insert) — the decisive check is
+		// that A's subtree is actually torn down (RemoveChild present, and
+		// no id from A gets reused for a create), not left dangling while
+		// B's is appended on top of it.
+		const navOps = capturedOps.flat();
+		expect(navOps).toContain(Op.RemoveChild);
+		expect(navOps).toContain(Op.CreateElement);
+	});
+
+	it("back()/forward() walk the in-memory history stack", () => {
+		setupRealTree();
+		lynxTestingEnv.switchToBackgroundThread();
+
+		const route = createRoute();
+		const A = { view: () => m("text", null, "A") };
+		const B = { view: () => m("text", null, "B") };
+		const C = { view: () => m("text", null, "C") };
+
+		route("/a", { "/a": A, "/b": B, "/c": C });
+		route.set("/b");
+		route.set("/c");
+		expect(route.get()).toBe("/c");
+
+		route.back();
+		expect(route.get()).toBe("/b");
+
+		route.back();
+		expect(route.get()).toBe("/a");
+
+		route.forward();
+		expect(route.get()).toBe("/b");
+	});
+
+	it("onmatch + SKIP falls through to the next matching route", () => {
+		setupRealTree();
+		lynxTestingEnv.switchToBackgroundThread();
+
+		const route = createRoute();
+		const Fallback = { view: () => m("text", null, "fallback") };
+		let calls = 0;
+
+		route("/x", {
+			"/x": {
+				onmatch() {
+					calls++;
+					return route.SKIP;
+				},
+			},
+			"/:any...": Fallback,
+		});
+
+		return new Promise<void>((resolve) => {
+			setTimeout(() => {
+				expect(calls).toBe(1);
+				expect(route.get()).toBe("/x");
+				resolve();
+			}, 0);
+		});
+	});
+
+	it("route.Link navigates on tap, and disabled Links don't wire ontap", () => {
+		setupRealTree();
+		lynxTestingEnv.switchToBackgroundThread();
+
+		const route = createRoute();
+		const A = { view: () => m("text", null, "A") };
+		const B = { view: () => m("text", null, "B") };
+		route("/a", { "/a": A, "/b": B });
+
+		const link = (route as any).Link.view({
+			attrs: { href: "/b" },
+			children: ["Go"],
+		});
+		expect(typeof link.attrs.ontap).toBe("function");
+		link.attrs.ontap({ currentTarget: null, redraw: true });
+		expect(route.get()).toBe("/b");
+
+		const disabledLink = (route as any).Link.view({
+			attrs: { href: "/a", disabled: true },
+			children: ["Go"],
+		});
+		expect(disabledLink.attrs.ontap).toBeUndefined();
+	});
+});

package/test/setup.ts

@@ -0,0 +1,25 @@
+// test/setup.ts
+//
+// The minimal gap-fill on top of @lynx-js/testing-environment's own PAPI
+// polyfill — same idea as mithril-lynx v1's testing.js, scoped down to only
+// what v2's apply-patch.js actually calls so far (no gestures/lists yet,
+// see the v2 plan's non-goals). `@lynx-js/testing-environment` already
+// implements __CreateView/__CreateText/__CreateElement/__CreateRawText/
+// __AppendElement/__InsertElementBefore/__RemoveElement/__SetAttribute/
+// __SetClasses/__AddInlineStyle/__FlushElementTree/__GetElementUniqueID —
+// the one real gap is __AddEventListener (the testing environment only
+// implements the string/worklet-event __AddEvent family that ReactLynx
+// uses; mithril-lynx binds real JS function listeners directly).
+
+globalThis.onInjectMainThreadGlobals = (target: any) => {
+	target.lynx.getEngine = target.lynx.getNative;
+
+	target.__AddEventListener = (node: any, name: string, handler: (...args: unknown[]) => unknown) => {
+		node.__vanillaListeners ??= {};
+		(node.__vanillaListeners[name] ??= new Set()).add(handler);
+	};
+
+	target.__RemoveEventListener = (node: any, name: string, handler: unknown) => {
+		node.__vanillaListeners?.[name]?.delete(handler);
+	};
+};

package/test/structural-reload.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from "@rstest/core";
+import m from "mithril";
+import { Op } from "../src/patch-protocol.js";
+import { createVirtualBackend } from "../src/backends/virtual-backend.js";
+import { createLynxDocument } from "../src/fake-dom.js";
+import renderFactory from "mithril/render/render.js";
+
+// Tests the v2 plan's §3.6 hypothesis directly, WITHOUT a device: does
+// re-rendering the SAME root/document with a structurally different tree
+// (a sibling inserted next to an unrelated, focused-in-spirit node) reuse
+// the unrelated node's id — i.e. does it survive as the SAME element,
+// rather than being torn down and recreated? This is exactly what "reload
+// B (estructural) doesn't lose the input's focus" depends on, and it's
+// mithril's own diff doing the work, not a hand-written reconciler (see
+// mithril-lynx-v2-desde-cero.md §3.6).
+//
+// This does not replace on-device verification (F4) — it verifies the
+// PART of the hypothesis that's actually testable off-device: id/identity
+// stability across a structural re-render. Whether the real native
+// `<input>` keeps keyboard focus and in-progress text is a device-only
+// question (F4's real acceptance criterion).
+
+describe("structural re-render reuses unrelated nodes (v2 plan §3.6 hypothesis)", () => {
+	it("does not recreate a sibling `input`-like node when a new node is inserted next to it", () => {
+		const backend = createVirtualBackend();
+		const document = createLynxDocument(backend);
+		const render = renderFactory();
+
+		function redraw() {
+			render(document, view(), redraw);
+		}
+
+		// `key` on every sibling is load-bearing here, not decoration: this is
+		// exactly the discipline the plan's §3.6 calls out as required for
+		// Mithril's own (unkeyed-diff) middle-insertion trap to not apply —
+		// without keys, an unkeyed diff treats "insert in the middle" as
+		// "index 1 changed tag" and recreates everything from that index on,
+		// which is a real Mithril behavior, not a v2 bug. The un-keyed case
+		// is deliberately NOT what this test asserts.
+		let showExtra = false;
+		function view() {
+			const children = [m("view", { key: "a", class: "a" }, "A")];
+			if (showExtra) children.push(m("view", { key: "extra", class: "extra" }, "EXTRA"));
+			children.push(m("input", { key: "input", class: "focused-input" }));
+			return m("view", { class: "root" }, children);
+		}
+
+		redraw();
+		backend.takeOps(); // discard the initial patch — we only care about the DELTA below
+
+		// Capture the input's id BEFORE the structural change, by walking
+		// the fake-dom tree the same way app code never has to (test-only
+		// introspection): the root element's last child is the input.
+		const rootEl = document.firstChild as any;
+		const inputBefore = rootEl._children[rootEl._children.length - 1];
+		const inputIdBefore = inputBefore._id;
+
+		showExtra = true;
+		redraw();
+		const deltaOps = backend.takeOps() ?? [];
+
+		// The decisive check: no RemoveChild/CreateElement op in the delta
+		// touches the input's id — it was reused in place, only a new
+		// sibling was created and inserted before it.
+		const ARITY = {
+			[Op.CreateElement]: 2,
+			[Op.CreateElementNS]: 3,
+			[Op.CreateText]: 2,
+			[Op.InsertBefore]: 3,
+			[Op.RemoveChild]: 2,
+			[Op.SetAttribute]: 3,
+			[Op.RemoveAttribute]: 2,
+			[Op.SetAttributeNS]: 4,
+			[Op.SetStyleProperty]: 3,
+			[Op.RemoveStyleProperty]: 2,
+			[Op.SetText]: 2,
+			[Op.AddEvent]: 2,
+			[Op.RemoveEvent]: 2,
+		} as Record<number, number>;
+		for (let i = 0; i < deltaOps.length; ) {
+			const opcode = deltaOps[i++] as number;
+			const args = deltaOps.slice(i, i + ARITY[opcode]);
+			if (opcode === Op.CreateElement) {
+				expect(args[1]).not.toBe(inputIdBefore);
+			} else if (opcode === Op.RemoveChild) {
+				expect(args[1]).not.toBe(inputIdBefore);
+			}
+			i += ARITY[opcode];
+		}
+
+		const rootElAfter = document.firstChild as any;
+		const inputAfter = rootElAfter._children[rootElAfter._children.length - 1];
+		expect(inputAfter._id).toBe(inputIdBefore);
+	});
+});

package/CONTRACT.md

@@ -1,151 +0,0 @@
-# Mithril 2.3.8 `render/render.js` — Extracted Contract
-
-Source: `node_modules/mithril/render/render.js` (910 lines), mithril **2.3.8**.
-All line numbers cite that file unless prefixed with `hyperscript.js:` (which cites `node_modules/mithril/render/hyperscript.js`).
-
----
-
-## a. Factory signature & how the render function is obtained
-
-- **Line 8**: `module.exports = function() {` — the module exports a **zero-argument factory function**.
-- The factory closes over module-level mutable state:
-  - `currentRedraw` (line 14) — the active `redraw` callback, captured by `EventDict` for auto-redraw.
-  - `currentRender` (line 15) — a per-render generation marker object (used by `delayedRemoval`).
-  - `currentDOM` (line 880) — the DOM node currently being rendered to (reentrancy lock).
-- The **render function is the closure returned by the factory**: lines 882–909, `return function(dom, vnodes, redraw) { ... }`.
-- Module dependencies (lines 3–6): `./vnode`, `./delayedRemoval`, `./domFor`, `./cachedAttrsIsStaticMap`.
-- The factory pattern means each call to `require("mithril/render/render")()` produces an **independent renderer instance** with its own `currentRedraw`/`currentDOM`/`currentRender` state.
-
-## b. Render function signature: `render(dom, vnodes, redraw)`
-
-Defined at **line 882**: `return function(dom, vnodes, redraw) {`
-
-| Param | Contract |
-|---|---|
-| `dom` | The DOM element to render into. **Line 883**: throws `TypeError("DOM element being rendered to does not exist.")` if falsy. **Lines 884–886**: throws `TypeError("Node is currently being rendered to and thus is locked.")` if `currentDOM != null && dom.contains(currentDOM)` (reentrancy guard). |
-| `vnodes` | A vnode or array of vnodes. **Line 899**: normalized via `Vnode.normalizeChildren(Array.isArray(vnodes) ? vnodes : [vnodes])`. |
-| `redraw` | Optional. **Line 894**: `currentRedraw = typeof redraw === "function" ? redraw : undefined`. Consumed by `EventDict.handleEvent` (lines 811–817) to auto-redraw after events. |
-
-Body sequence:
-1. **Line 898**: first render into a node clears it — `if (dom.vnodes == null) dom.textContent = ""`.
-2. **Line 900**: `updateNodes(dom, dom.vnodes, vnodes, hooks, null, namespace === "http://www.w3.org/1999/xhtml" ? undefined : namespace)` — diffs old (`dom.vnodes`) vs new (`vnodes`); the XHTML namespace is normalized to `undefined` (which enables the property-key path in `hasPropertyKey`).
-3. **Line 901**: `dom.vnodes = vnodes` — **prior vnodes are stored on the DOM node itself**.
-4. **Line 903**: focus restoration — if `document.activeElement` changed and the old active element still has `.focus`, it is refocused.
-5. **Line 904**: post-render hooks (`oncreate`/`onupdate`) flushed in order.
-6. **Lines 905–908**: `finally` restores `currentRedraw`/`currentDOM` to their previous values.
-
-## c. DOM surface accessed on the `dom` parameter
-
-All access goes through the `dom` node passed to `render()` (or its descendants). `getDocument(dom)` (lines 17–19) returns `dom.ownerDocument`.
-
-| API | Lines | Usage |
-|---|---|---|
-| `ownerDocument` | 18 | `getDocument()`; source of all document-level factories |
-| `createTextNode` | 76 | `createText` — `vnode.dom = getDocument(parent).createTextNode(vnode.children)` |
-| `createElement` / `createElementNS` | 120–122 | `createElement` for HTML, `createElementNS(ns, tag)` for svg/math; `{is: is}` third arg for custom elements |
-| `createDocumentFragment` | 96, 104, 551 | `createHTML` (96), `createFragment` (104), `moveDOM` for multi-node moves (551) |
-| `insertBefore` / `appendChild` | 558–561 | `insertDOM`: `insertBefore(dom, nextSibling)` if `nextSibling != null`, else `appendChild(dom)` |
-| `removeChild` | 610–617 | `removeDOM`: single `removeChild(vnode.dom)` or per-node via `domFor` for fragments |
-| `nodeValue` | 422 | `updateText` — `old.dom.nodeValue = vnode.children` |
-| `value` | 654–658, 666, 699, 703 | Read for same-value coercion skips (input/textarea/select/option); written via generic `vnode.dom[key] = value` (666); select late-attrs (699, 703) |
-| `checked` | 730 | Only as a key name in `isFormAttribute`; written via generic property path (666) |
-| `selectedIndex` | 685, 699, 702, 707 | `removeAttr` guard (685), `setLateSelectAttrs` (699, 702, 707) |
-| `className` | 672, 681, 693 | `setAttr` maps `className` → `"class"` attribute (672); `removeAttr` excludes it from property-null path (681) and maps to `"class"` (693) |
-| `setAttribute` | 665, 669–670, 672 | input `type` (665), boolean attrs (669–670), generic attrs (672) |
-| `removeAttribute` | 670, 693 | boolean-false (670), generic removal (693) |
-| `setAttributeNS` | 645 | `xlink:`-prefixed keys → `setAttributeNS("http://www.w3.org/1999/xlink", key.slice(6), value)` |
-| `style` | 646, 678, 747–787 | `updateStyle` dual-mode (see §f) |
-| `innerHTML` | 89, 92, 571 | `createHTML` (89 svg-wrapped, 92 plain), contenteditable sync (571) |
-| `textContent` | 898 | First-render clear |
-| `firstChild` | 90, 94, 98, 109 | `createHTML` unwrap (90, 94, 98), `createFragment` dom anchor (109) |
-| `parentNode` | 730 | `isFormAttribute` — `option` whose parent is the active element |
-| `contains` | 884 | Reentrancy lock check |
-| `namespaceURI` | 891 | Namespace detection for the diff call |
-| `focus` | 903 | Focus restoration |
-| `nextSibling` | domFor.js:12 | Fragment iteration in `domFor` |
-
-**Not used (verified by grep across the whole package):**
-- `getAttribute` — render.js only *writes* attributes (`setAttribute`/`removeAttribute`/`setAttributeNS`); it never reads them.
-- `nodeType` — appears nowhere in mithril. Do not rely on it in a reimplementation.
-
-## d. Prior-vnode storage & diffing of repeated `render()` calls
-
-**Storage**: old vnodes live on the DOM node as `dom.vnodes` — read at line 898 (first-render check) and 900 (diff input), written at line 901.
-
-**`updateNodes(parent, old, vnodes, hooks, nextSibling, ns)`** (lines 270–395):
-
-1. **Trivial cases** (271–273): `old === vnodes` or both null → no-op; `old` empty → create all; `vnodes` empty → remove all.
-2. **Keyed detection** (275–276): lists are keyed iff `old[0].key != null` / `vnodes[0].key != null` (first non-null node, 278–279).
-3. **Keyed/unkeyed mismatch** (280–282): remove all old + create all new.
-4. **Unkeyed diff** (283–299): walk the common length index-by-index; `o === v` or both null → skip; null old → create; null new → remove; else `updateNode`. Tails handled by `removeNodes` (298) / `createNodes` (299).
-5. **Keyed diff** (300–392), with the documented optimizations (comment block 184–268):
-   - **Bottom-up tail match** (305–312): while tail keys equal, update in place — identical tails are guaranteed part of the LIS, so no moves (tail optimization, comment 244–245).
-   - **Top-down head match** (314–320): same for the head.
-   - **Swaps & reversals** (322–336): two-node cross-swap fast path.
-   - **Bottom-up again** (338–345): re-check tails after head/tail consumption.
-   - **Leftovers** (346–347): remove remaining old or create remaining new.
-   - **LIS-based middle diff** (348–391): builds `oldIndices` (350–351), maps new keys → old indices via `getKeyMap` (352–365; impl 478–488), nulls matched old entries, removes unmatched old (367), creates all if nothing matched (368), then either moves non-LIS nodes (`makeLisIndices`, 370–383; impl 494–534, lifted from ivi) or a simple create loop when order was preserved (384–390).
-6. **`getNextSibling`** (536–541): next sibling is found by scanning the *old* list forward from `i+1` for a node with a `dom` — this is what makes top-down DOM insertion correct.
-7. **`moveDOM`** (544–556): moves single nodes directly; multi-node fragments are moved via a `createDocumentFragment` + `domFor` loop.
-
-**`updateNode`** (396–419): same `tag` + same `is` → in-place update (state/events carried over at 399–400; `shouldNotUpdate` short-circuit at 401, impl 852–878); otherwise `removeNode` + `createNode`. Per-tag updates: `updateText` (420–425), `updateHTML` (426–435), `updateFragment` (436–450), `updateElement` (451–461), `updateComponent` (462–477).
-
-## e. How `m()` (hyperscript) creates events & attrs
-
-**Hyperscript side** (`render/hyperscript.js`):
-- Selector parsing: `compileSelector` (hyperscript.js:21–42) — `#id`, `.class`, `[attr]`, `[attr=value]`; `class` → `className` (hyperscript.js:38); form-attribute keys (`value`/`checked`/`selectedIndex`/`selected`) mark the attrs object as non-static (hyperscript.js:17–19, 34).
-- `class` attr → `className` (hyperscript.js:54–57); `input[type]` reordered first (hyperscript.js:69–74, workaround for #2622); `vnode.is = attrs.is` (hyperscript.js:77).
-
-**Event side** (render.js):
-- **Dispatch rule** (line 644): any attr key starting with `on` (`key[0] === "o" && key[1] === "n"`) is routed to `updateEvent` (826–842), never to the DOM attribute path.
-- **`EventDict`** (800–823): a per-element event listener object, prototype `Object.create(null)` (804). Constructor captures `this._ = currentRedraw` (802). `handleEvent(ev)` (805–823):
-  - Looks up `this["on" + ev.type]` (806).
-  - Function handler → called with `ev.currentTarget` as `this` (808); object handler → `handler.handleEvent(ev)` (809).
-  - Auto-redraw: if `this._ != null` and `ev.redraw !== false`, calls the captured redraw (811–812); also after the handler's returned promise resolves (813–817).
-  - `return false` → `ev.preventDefault()` + `ev.stopPropagation()` (819–822).
-- **`updateEvent`** (826–842): `addEventListener(key.slice(2), vnode.events, false)` — the **EventDict object itself is the listener** (831, 839); handlers stored as `vnode.events[key]`; removal via `removeEventListener` (834). `vnode.events` is carried across updates (line 400).
-
-**Attribute side** (render.js):
-- **`setAttr`** (642–674) precedence: skip `key`/null-value/lifecycle (643) → `on*` events (644) → `xlink:` (645) → `style` (646) → **`hasPropertyKey`** (647–666) → attribute fallback (667–673).
-- **`hasPropertyKey`** (735–744): property assignment only when `ns === undefined` AND (custom element: tag contains `-` or `vnode.is`, OR key not in the browser-bug blacklist `href`/`list`/`form`/`width`/`height`) AND `key in vnode.dom`.
-- Property path (666): `vnode.dom[key] = value`, with `value` coercion guards (648–663: input/textarea/select/option same-value skip; file-input read-only warning at 661) and `input[type]` forced through `setAttribute` (665).
-- Attribute path (667–673): boolean → `setAttribute(key, "")` / `removeAttribute(key)`; else `setAttribute(key === "className" ? "class" : key, value)`.
-- **`removeAttr`** (675–695): property-null path excludes `className`, `title`, `value` (option/select edge), `input[type]`; else `removeAttribute` with `className` → `"class"` mapping.
-- **`updateAttrs`** (709–728): removals first (713–722), then sets (723–727); warns on reused attrs objects (714–716).
-- **`isFormAttribute`** (729–731): `value`/`checked`/`selectedIndex`/`selected` (with active-element/option-parent conditions) — these bypass the `old === value` skip so form state always syncs.
-
-## f. `updateStyle()` dual-mode (lines 747–787)
-
-`updateStyle(element, old, style)`:
-
-| Case | Lines | Behavior |
-|---|---|---|
-| `old === style` | 748–749 | No-op |
-| `style == null` | 750–752 | `element.style = ""` (clear) |
-| `typeof style !== "object"` | 753–755 | `element.style = style` (string passthrough) |
-| `old` missing/string, `style` object | 756–766 | Clear, then for each key: **`key.includes("-")` → `element.style.setProperty(key, String(value))`** (763); **else `element.style[key] = String(value)`** (764) |
-| Both objects | 767–786 | Remove stale keys first (772–777: `removeProperty` for dash-case, `= ""` for camelCase), then set changed keys (779–785: same dual-mode) |
-
-Key contract points:
-- **Dash-case keys** (`-` in the name) → `setProperty` / `removeProperty`; **camelCase keys** → direct `style[k]` assignment.
-- All values coerced with `String()` (763–764, 781).
-- Removal happens before setting (770–771) to avoid dash-case/camelCase aliasing bugs.
-
-## g. Version & packaging
-
-- **Version**: `2.3.8` (package.json `version` field).
-- **No `main` / `module` field** in package.json (verified — only `unpkg`/`jsdelivr`/`repository`/`license`/`scripts`/`devDependencies`). The package is consumed by **file-path require**: `require("mithril/render/render")` resolves directly to `node_modules/mithril/render/render.js`.
-- Entry points: `index.js` (browser bundle), `render.js` (top-level re-export of `render/render.js`), `hyperscript.js` (re-export of `render/hyperscript.js` + `trust`/`fragment`).
-- 2.3.8 is the latest mithril release on npm (as of this scaffold's dependency pin).
-
----
-
-## Reimplementation checklist (what a Lynx port must honor)
-
-1. Factory `module.exports = function()` returning `function(dom, vnodes, redraw)` with per-instance `currentRedraw`/`currentRender`/`currentDOM` state.
-2. Store prior vnodes on the target node (`dom.vnodes`); first render clears via `textContent = ""`.
-3. Diff pipeline: trivial cases → keyed detection → unkeyed walk → keyed (tail/head/swaps/LIS) → leftover create/remove.
-4. DOM surface: `createTextNode`, `createElement(NS)`, `createDocumentFragment`, `insertBefore`/`appendChild`, `removeChild`, `nodeValue`, `value`, `checked`, `selectedIndex`, `className`, `setAttribute`/`removeAttribute`/`setAttributeNS`, `style`, `innerHTML`, `textContent`, `firstChild`, `parentNode`, `ownerDocument`, `namespaceURI`, `contains`, `focus`. **No `getAttribute`, no `nodeType`.**
-5. Events: `on*` keys → single `EventDict` object per element registered via `addEventListener`; `handleEvent` dispatches by `ev.type`, binds `this` to `ev.currentTarget`, auto-redraws, honors `return false`.
-6. Attrs: `hasPropertyKey` gate (property vs attribute), `className`→`class` mapping, boolean attrs, `xlink:` namespace, `value`/`checked`/`selectedIndex` form-attribute exceptions.
-7. Styles: dual-mode `updateStyle` — `setProperty` for `-` keys, `style[k] = v` for camelCase, `String()` coercion, remove-before-set.