mithril-lynx 0.0.1

package/list.d.ts

@@ -0,0 +1,31 @@
+// Ambient declaration for the ESM list.js (the file itself is not
+// type-checked; this describes its runtime export shape for TS consumers).
+
+export interface CreateListOptions {
+  itemCount: number;
+  /** Must return a fresh vnode for the cell's content; may be called more than once for the same index (recycling). */
+  renderItem(index: number): unknown;
+  /** Defaults to String(index). Set on every item's "item-key" attribute — required by native, not just an identity hint. */
+  itemKey?(index: number): string;
+  className?: string;
+  /** Defaults to "vertical". */
+  scrollOrientation?: "vertical" | "horizontal";
+  /** Defaults to "single". */
+  listType?: "single" | "flow";
+  /** Defaults to 1. */
+  spanCount?: number;
+}
+
+export interface ListHandle {
+  _handle: unknown;
+  nodeType: 1;
+  /** Call after mutating the underlying data so a subsequently-scrolled-into-view cell reflects the new count. */
+  setItemCount(nextCount: number): void;
+}
+
+/**
+ * Creates a native-recycled `<list>` element (project plan, Phase 8, Tier
+ * 2). Imperative escape hatch — call from oncreate(vnode) and attach the
+ * result yourself (parentNode.appendChild(list)).
+ */
+export function createList(parentNode: { ownerDocument: unknown }, options: CreateListOptions): ListHandle;

package/list.js

@@ -0,0 +1,185 @@
+// list.js
+//
+// List virtualization/recycling (project plan, Phase 8, Tier 2), main-thread
+// only. __CreateList's componentAtIndex/enqueueComponent callbacks are a
+// native-driven recycler: native owns scroll position and cell lifecycle,
+// calling back into JS to fetch or recycle a cell's content by TYPE
+// (matching RecyclerView/UICollectionView semantics), not a JS-side
+// windowing calculation.
+//
+// The sign/recycle map design and the exact __FlushElementTree({triggerLayout,
+// operationID, elementID, listID}) call shape are ported from
+// @lynx-js/react's OWN shipped runtime/lib/snapshot/list/list.js — real,
+// proven code, not guesswork (unlike gesture.js's callback-shape question,
+// this part IS verified against a real implementation). What list.js narrows
+// down for v1, deliberately:
+//   - No deferred list items (ReactLynx's `defer`/`isReady` promise dance —
+//     ties into a whole separate lifecycle-event protocol not otherwise
+//     needed here).
+//   - No componentAtIndexes batching — native's single-cell componentAtIndex
+//     callback only.
+//   - No independent per-item redraw after the initial bind/recycle — a list
+//     item's content is (re)computed fresh from renderItem(index) every time
+//     native calls componentAtIndex for it (on scroll-driven reuse), not
+//     whenever the app's own state changes. An app wanting a currently-bound
+//     visible item to reflect a data change needs its OWN mechanism to ask
+//     native to re-request that cell; list.js does not provide one in v1.
+//
+// This is an imperative escape hatch, like element.js/gesture.js — call it
+// from oncreate(vnode) and attach the result yourself
+// (parentNode.appendChild(list)), rather than mounting it through m().
+// Tier 1 (no code here at all — just m("list", ...)/m("list-item", ...) as
+// ordinary tags through the existing shim, relying on its already-tested
+// keyed/LIS diff) covers the common case and should be preferred unless the
+// app specifically needs native-driven recycling for very large lists.
+
+import shim from "./src/lynx-mithril-shim.js";
+
+// A render function dedicated to list-item content, independent of
+// shim.render()/redraw()'s own single-root convenience-API state (which a
+// main-thread-owned or data-channel-mode app may already be using for the
+// rest of the page). Each item wrapper carries its own `.vnodes`, so reusing
+// one render function sequentially across many items/lists is safe — Mithril
+// diffs against whatever `.vnodes` is already on the target wrapper.
+const renderItemContent = shim();
+
+function typeKeyOf(vnode) {
+	return typeof vnode.tag === "string" ? vnode.tag : (vnode.tag && vnode.tag.name) || "default";
+}
+
+/**
+ * Creates a native-recycled `<list>` element, scoped to the same component
+ * as `parentNode` (anything with an `ownerDocument`, e.g. a real
+ * LynxNodeWrapper). `renderItem(index)` must return a fresh Mithril vnode
+ * for that cell's content every time it's called — it may be called more
+ * than once for the same index (recycling).
+ *
+ * `scrollOrientation`/`listType`/`spanCount` and each item's `item-key` are
+ * NOT optional in practice, even though native's __CreateList/componentAtIndex
+ * types don't require them: every real @lynx-js/react list example sets all
+ * of these unconditionally (verified by reading lynx-examples/examples/list's
+ * base/recyclable/async-rendering demos — see ../LIST_INVESTIGATION.md), and
+ * a real device never called componentAtIndex at all without them. Defaults
+ * here match what those examples use for the simple single-column case.
+ */
+export function createList(parentNode, options) {
+	const {
+		itemCount,
+		renderItem,
+		itemKey,
+		className,
+		scrollOrientation = "vertical",
+		listType = "single",
+		spanCount = 1,
+	} = options;
+	let count = itemCount;
+	const pageId = parentNode.ownerDocument._pageId;
+	const keyOf = typeof itemKey === "function" ? itemKey : (index) => String(index);
+
+	// itemType -> Map<sign, ItemEntry>, the reuse pool.
+	const recycleMap = new Map();
+	// sign -> ItemEntry, currently-bound (visible) items.
+	const signMap = new Map();
+
+	function bindFreshItem(listHandle, listId, cellIndex, opId, vnode, typeKey) {
+		const itemWrapper = parentNode.ownerDocument.createElement("list-item");
+		__SetAttribute(itemWrapper._handle, "item-key", keyOf(cellIndex));
+		__AppendElement(listHandle, itemWrapper._handle);
+		renderItemContent(itemWrapper, vnode);
+
+		const sign = __GetElementUniqueID(itemWrapper._handle);
+		signMap.set(sign, { wrapper: itemWrapper, typeKey });
+		__FlushElementTree(itemWrapper._handle, { triggerLayout: true, operationID: opId, elementID: sign, listID: listId });
+		return sign;
+	}
+
+	function bindRecycledItem(listId, cellIndex, opId, vnode, pool) {
+		const [sign, entry] = pool.entries().next().value;
+		pool.delete(sign);
+		// The recycled wrapper is now bound to a DIFFERENT index — its
+		// item-key must be updated to match, the same way its content does.
+		__SetAttribute(entry.wrapper._handle, "item-key", keyOf(cellIndex));
+		renderItemContent(entry.wrapper, vnode);
+		signMap.set(sign, entry);
+		__FlushElementTree(entry.wrapper._handle, { triggerLayout: true, operationID: opId, elementID: sign, listID: listId });
+		return sign;
+	}
+
+	function componentAtIndex(listHandle, listId, cellIndex, opId) {
+		if (cellIndex < 0 || cellIndex >= count) {
+			throw new Error(`mithril-lynx list: cellIndex ${cellIndex} out of range (itemCount=${count})`);
+		}
+		const vnode = renderItem(cellIndex);
+		const typeKey = typeKeyOf(vnode);
+		const pool = recycleMap.get(typeKey);
+		if (pool && pool.size > 0) return bindRecycledItem(listId, cellIndex, opId, vnode, pool);
+		return bindFreshItem(listHandle, listId, cellIndex, opId, vnode, typeKey);
+	}
+
+	function enqueueComponent(_listHandle, _listId, sign) {
+		const entry = signMap.get(sign);
+		if (entry == null) return;
+		signMap.delete(sign);
+		if (!recycleMap.has(entry.typeKey)) recycleMap.set(entry.typeKey, new Map());
+		recycleMap.get(entry.typeKey).set(sign, entry);
+	}
+
+	// THE missing piece (see LIST_INVESTIGATION.md): __CreateList + attributes
+	// alone never triggers componentAtIndex — native only starts requesting
+	// cells once it's told, via a special "update-list-info" attribute, which
+	// positions currently exist. Ported from @lynx-js/react's OWN
+	// runtime/lib/snapshot/list/listUpdateInfo.js (ListUpdateInfoRecording.flush()),
+	// which sends this on every list-children change, alongside a matching
+	// __UpdateListCallbacks call. Each insertAction entry needs an "item-key"
+	// (dash-case — confirmed by a real device rejecting the first attempt,
+	// which omitted it, with "Error for illegal list item-key in parse
+	// insertAction"; the exact key name matches ReactLynx's own
+	// `__listItemPlatformInfo['item-key']`, a raw JSX-prop-shaped bag it
+	// spreads into each entry). `type` per entry is still UNCONFIRMED —
+	// ReactLynx's version uses its own component-type reference there
+	// (meaningful only to its own recycling, not to native, as far as this
+	// file's reading of the source can tell); a constant string is used
+	// here since this port's own type-based recycling (typeKeyOf(), above)
+	// is tracked independently, in this module, not through native's copy
+	// of `type`.
+	function sendListInfo(insertAction, removeAction, updateAction) {
+		__SetAttribute(listHandle, "update-list-info", { insertAction, removeAction, updateAction });
+		__UpdateListCallbacks(listHandle, componentAtIndex, enqueueComponent);
+	}
+
+	function insertEntry(position) {
+		return { position, type: "cell", "item-key": keyOf(position) };
+	}
+
+	const listHandle = __CreateList(pageId, componentAtIndex, enqueueComponent, {});
+	__SetAttribute(listHandle, "scroll-orientation", scrollOrientation);
+	__SetAttribute(listHandle, "list-type", listType);
+	__SetAttribute(listHandle, "span-count", String(spanCount));
+	if (className != null) __SetClasses(listHandle, className);
+
+	sendListInfo(
+		Array.from({ length: count }, (_, position) => insertEntry(position)),
+		[],
+		[],
+	);
+
+	return {
+		_handle: listHandle,
+		nodeType: 1,
+		/** Call after mutating the underlying data so a subsequently-scrolled-into-view cell reflects the new count. */
+		setItemCount(nextCount) {
+			if (nextCount === count) return;
+			if (nextCount > count) {
+				sendListInfo(
+					Array.from({ length: nextCount - count }, (_, i) => insertEntry(count + i)),
+					[],
+					[],
+				);
+			} else {
+				const removed = Array.from({ length: count - nextCount }, (_, i) => nextCount + i);
+				sendListInfo([], removed, []);
+			}
+			count = nextCount;
+		},
+	};
+}

package/main-thread.d.ts

@@ -0,0 +1,43 @@
+// Ambient declaration for the ESM main-thread.js (the file itself is not
+// type-checked; this describes its runtime export shape for TS consumers).
+
+/** Returns the most recently received data (from __RenderPage/__UpdatePage or a background push). */
+export function getData<T = unknown>(): T | undefined;
+
+/** Sends a named action to the background thread's setBackgroundEventHandler. */
+export function dispatchToBackground(handlerName: string, data?: unknown): void;
+
+export interface SetupAppOptions<TInput = unknown, TData = TInput> {
+  /** Called exactly once, on the first __RenderPage, to build the root Mithril vnode. */
+  root(): unknown;
+  /** Optional transform applied to raw engine/background data before storing it. */
+  processData?(data: TInput): TData;
+  /**
+   * When true (default), pushes processed data to the background thread on
+   * every __RenderPage/__UpdatePage, and listens for background-pushed
+   * updates, redrawing via Mithril's own shim.redraw().
+   */
+  enableBackgroundSync?: boolean;
+}
+
+/**
+ * Wires the Lynx engine's page lifecycle (__RenderPage/__UpdatePage/
+ * __DestroyLifetime) to a Mithril app: renders `root()` once, then calls
+ * the shim's redraw() on every subsequent data push. See the project plan,
+ * Phase 3 ("data-channel mode").
+ */
+export function setupApp<TInput = unknown, TData = TInput>(
+  options: SetupAppOptions<TInput, TData>,
+): void;
+
+/**
+ * Registers a handler background.js's runOnMainThread(key, ...args) can
+ * call by name. See the project plan, Phase 6.
+ */
+export function registerHandler(key: string, fn: (...args: unknown[]) => unknown): void;
+
+/**
+ * Calls a handler background.js registered via registerHandler(key, fn).
+ * Args and the resolved value must be JSON-serializable.
+ */
+export function runOnBackground<T = unknown>(key: string, ...args: unknown[]): Promise<T>;

package/main-thread.js

@@ -0,0 +1,165 @@
+// main-thread.js
+//
+// Cross-thread "data-channel mode" adapter for the main thread (see the
+// project plan, Phase 3). Ports the engine-lifecycle wiring from
+// lynx-examples/examples/vanilla/src/common/main-thread/setup.ts, adapted so
+// the app supplies a Mithril root component instead of hand-written
+// renderPage/updatePage functions: Mithril's own redraw/diff machinery
+// (already ported in ../src/lynx-mithril-shim.js) does the update work.
+//
+// The app is responsible for reading live data inside its Mithril view()
+// functions via getData() — exactly like any plain-JS Mithril store, no
+// special re-invocation of a "mount" function is needed on every update.
+
+import shim from "./src/lynx-mithril-shim.js";
+import {
+	callBackgroundEventName,
+	callBackgroundResultEventName,
+	callMainThreadEventName,
+	callMainThreadResultEventName,
+	destroyLifetimeEventName,
+	dispatchEventToBackgroundEventName,
+	renderPageEventName,
+	updateDataFromBackgroundEventName,
+	updateDataFromMainThreadEventName,
+	updatePageEventName,
+} from "./internal/constants.js";
+
+let latestData;
+
+// The native engine unconditionally invokes a global `processData(initData)`
+// hook on every __RenderPage/__UpdatePage, regardless of framework. Install a
+// pass-through default immediately so apps that don't need to transform
+// incoming data (the common case) don't have to think about this at all.
+Object.assign(globalThis, {
+	processData: (data) => data,
+});
+
+export function getData() {
+	return latestData;
+}
+
+export function dispatchToBackground(handlerName, data) {
+	lynx.getJSContext().dispatchEvent({
+		type: dispatchEventToBackgroundEventName,
+		data: { handlerName, data },
+	});
+}
+
+export function setupApp(options) {
+	const { root, processData, enableBackgroundSync = true } = options;
+	const engine = lynx.getEngine();
+	const background = enableBackgroundSync ? lynx.getJSContext() : undefined;
+	let rendered = false;
+
+	const applyData = (data) => {
+		latestData = typeof processData === "function" ? processData(data) : data;
+		if (enableBackgroundSync) {
+			lynx.getJSContext().dispatchEvent({
+				type: updateDataFromMainThreadEventName,
+				data: latestData,
+			});
+		}
+		return latestData;
+	};
+
+	const onRenderPage = (event) => {
+		const [data] = event.data;
+		applyData(data);
+		const page = __CreatePage("0", 0);
+		shim.renderToPage(page, root());
+		rendered = true;
+	};
+
+	const onUpdatePage = (event) => {
+		const [data] = event.data;
+		applyData(data);
+		if (rendered) shim.redraw();
+	};
+
+	const onDataFromBackground = (event) => {
+		latestData = { ...latestData, ...event.data };
+		if (rendered) shim.redraw();
+	};
+
+	const onDestroyLifetime = () => {
+		if (enableBackgroundSync) {
+			// The background thread has no lynx.getEngine() of its own, so relay
+			// the native lifecycle event across the channel explicitly — this is
+			// what lets background.js's own setupBackground() cleanup run.
+			background.dispatchEvent({ type: destroyLifetimeEventName, data: undefined });
+			background.removeEventListener(updateDataFromBackgroundEventName, onDataFromBackground);
+		}
+		engine.removeEventListener(renderPageEventName, onRenderPage);
+		engine.removeEventListener(updatePageEventName, onUpdatePage);
+		engine.removeEventListener(destroyLifetimeEventName, onDestroyLifetime);
+	};
+
+	engine.addEventListener(renderPageEventName, onRenderPage);
+	engine.addEventListener(updatePageEventName, onUpdatePage);
+	engine.addEventListener(destroyLifetimeEventName, onDestroyLifetime);
+	if (enableBackgroundSync) {
+		background.addEventListener(updateDataFromBackgroundEventName, onDataFromBackground);
+	}
+}
+
+// Cross-thread function registry (project plan, Phase 6 — worklet
+// substitute). The common worklet use case (a gesture/tap handler running
+// on the thread it's authored on) needs NONE of this — it's already just an
+// ordinary function in main-thread.ts. This is only for the remaining case:
+// background-owned code needs to trigger a main-thread action outside the
+// normal render/data cycle. Equal *capability* to upstream ReactLynx's own
+// runOnMainThread/runOnBackground (both are async serialized RPC under the
+// hood there too) — worse *ergonomics* only, since there's no compiler to
+// extract an inline closure; handlers must be named and pre-registered on
+// the thread they run on. Listener setup is lazy (on first use), not
+// module-top-level, so importing this module never assumes a particular
+// thread is active yet.
+const mainThreadHandlers = new Map();
+const pendingBackgroundCalls = new Map();
+let nextCallId = 1;
+let crossThreadCallsReady = false;
+
+function ensureCrossThreadCalls() {
+	if (crossThreadCallsReady) return;
+	crossThreadCallsReady = true;
+	const background = lynx.getJSContext();
+
+	background.addEventListener(callMainThreadEventName, (event) => {
+		const { callId, key, args } = event.data;
+		const fn = mainThreadHandlers.get(key);
+		let result;
+		let error;
+		try {
+			result = fn ? fn(...args) : undefined;
+		} catch (e) {
+			error = e instanceof Error ? e.message : String(e);
+		}
+		background.dispatchEvent({ type: callMainThreadResultEventName, data: { callId, result, error } });
+	});
+
+	background.addEventListener(callBackgroundResultEventName, (event) => {
+		const { callId, result, error } = event.data;
+		const pending = pendingBackgroundCalls.get(callId);
+		if (pending == null) return;
+		pendingBackgroundCalls.delete(callId);
+		if (error != null) pending.reject(new Error(error));
+		else pending.resolve(result);
+	});
+}
+
+/** Registers a handler background.runOnMainThread(key, ...) can call by name. */
+export function registerHandler(key, fn) {
+	ensureCrossThreadCalls();
+	mainThreadHandlers.set(key, fn);
+}
+
+/** Calls a handler background.js registered via registerHandler(key, fn), by name. Args must be JSON-serializable. */
+export function runOnBackground(key, ...args) {
+	ensureCrossThreadCalls();
+	return new Promise((resolve, reject) => {
+		const callId = nextCallId++;
+		pendingBackgroundCalls.set(callId, { resolve, reject });
+		lynx.getJSContext().dispatchEvent({ type: callBackgroundEventName, data: { callId, key, args } });
+	});
+}

package/package.json

@@ -0,0 +1,100 @@
+{
+  "name": "mithril-lynx",
+  "version": "0.0.1",
+  "description": "Mithril.js rendered through Lynx's Element PAPI — a contract-complete port of mithril/render/render.js@2.3.8 to the Lynx main thread, packaged as a reusable framework.",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/carlos-sweb/mithril-lynx.git"
+  },
+  "homepage": "https://github.com/carlos-sweb/mithril-lynx#readme",
+  "bugs": {
+    "url": "https://github.com/carlos-sweb/mithril-lynx/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/lynx-mithril-shim.d.ts",
+      "default": "./src/lynx-mithril-shim.js"
+    },
+    "./plugin": {
+      "types": "./plugin.d.ts",
+      "default": "./plugin.js"
+    },
+    "./main-thread": {
+      "types": "./main-thread.d.ts",
+      "default": "./main-thread.js"
+    },
+    "./background": {
+      "types": "./background.d.ts",
+      "default": "./background.js"
+    },
+    "./renderer/main-thread": {
+      "types": "./renderer/main-thread.d.ts",
+      "default": "./renderer/main-thread.js"
+    },
+    "./renderer/background": {
+      "types": "./renderer/background.d.ts",
+      "default": "./renderer/background.js"
+    },
+    "./element": {
+      "types": "./element.d.ts",
+      "default": "./element.js"
+    },
+    "./gesture": {
+      "types": "./gesture.d.ts",
+      "default": "./gesture.js"
+    },
+    "./list": {
+      "types": "./list.d.ts",
+      "default": "./list.js"
+    },
+    "./testing": {
+      "types": "./testing.d.ts",
+      "default": "./testing.js"
+    }
+  },
+  "files": [
+    "src",
+    "internal",
+    "renderer",
+    "plugin.js",
+    "plugin.d.ts",
+    "main-thread.js",
+    "main-thread.d.ts",
+    "background.js",
+    "background.d.ts",
+    "element.js",
+    "element.d.ts",
+    "gesture.js",
+    "gesture.d.ts",
+    "list.js",
+    "list.d.ts",
+    "testing.js",
+    "testing.d.ts",
+    "CONTRACT.md"
+  ],
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "scripts": {
+    "test": "rstest run"
+  },
+  "dependencies": {
+    "@lynx-js/runtime-wrapper-webpack-plugin": "^0.2.4",
+    "@lynx-js/template-webpack-plugin": "^0.16.0"
+  },
+  "peerDependencies": {
+    "mithril": "2.3.8",
+    "@lynx-js/type-element-api": "0.0.9",
+    "@lynx-js/types": "4.1.0",
+    "@lynx-js/rspeedy": "^0.17.0"
+  },
+  "devDependencies": {
+    "mithril": "2.3.8",
+    "@lynx-js/testing-environment": "npm:@lynx-js/testing-environment-canary@0.3.2-canary-20260803-5a891c73",
+    "@rstest/core": "^0.11.3",
+    "jsdom": "^28.0.0",
+    "typescript": "~6.0.3"
+  }
+}

package/plugin.d.ts

@@ -0,0 +1,17 @@
+// Ambient declaration for the ESM plugin.js (the file itself is not
+// type-checked; this describes its runtime export shape for lynx.config.ts).
+
+import type { RsbuildPlugin } from "@lynx-js/rspeedy";
+
+export interface PluginMithrilLynxOptions {
+  /** Lynx engine target SDK version. Defaults to "3.5". */
+  targetSdkVersion?: string;
+}
+
+/**
+ * Dual-bundle build plugin: for each configured entry, compiles the entry
+ * file as the main-thread/Lepus bundle, and — if a sibling `background.ts`
+ * or `background.js` file exists next to it — compiles that as the
+ * background/JS-thread bundle. Pure multi-entry bundling, no code transform.
+ */
+export function pluginMithrilLynx(options?: PluginMithrilLynxOptions): RsbuildPlugin;