mithril-lynx 0.0.1

package/plugin.js

@@ -0,0 +1,185 @@
+// plugin.js
+//
+// Generalized version of lynx-examples/examples/vanilla/plugin.ts's
+// dual-bundle build pattern, published as a reusable Rsbuild/Rspeedy plugin
+// instead of being copy-pasted per app.
+//
+// Convention: for each configured entry, the entry's import path names a
+// "main-thread" file. If a sibling "background.ts"/"background.js" exists
+// next to it, it is picked up automatically and compiled as a second Lynx
+// bundle chunk (the background/JS-thread bundle), while the main-thread file
+// is always compiled and encoded as lepus (main-thread/Lepus VM chunk).
+//
+// This is pure multi-entry bundling, no AST transform of user code: apps
+// author two plain files (main-thread.ts + optional background.ts) and this
+// plugin wires them into the two Lynx bundle slots. See mithril-lynx's
+// project plan, Phase 2.
+
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+
+import { RuntimeWrapperWebpackPlugin } from "@lynx-js/runtime-wrapper-webpack-plugin";
+import { LynxEncodePlugin, LynxTemplatePlugin } from "@lynx-js/template-webpack-plugin";
+
+const PLUGIN_NAME = "mithril-lynx-template-webpack";
+
+const BACKGROUND_CANDIDATES = ["background.ts", "background.js"];
+const STYLE_CANDIDATES = ["style.css"];
+
+function findSibling(dir, candidates) {
+	for (const name of candidates) {
+		const candidate = path.join(dir, name);
+		if (fs.existsSync(candidate)) return candidate;
+	}
+	return null;
+}
+
+export function pluginMithrilLynx(options = {}) {
+	const targetSdkVersion = options.targetSdkVersion ?? "3.5";
+
+	return {
+		name: PLUGIN_NAME,
+		setup(api) {
+			// Keep the template plugin discoverable by Rspeedy's Lynx internals.
+			api.expose(Symbol.for("LynxTemplatePlugin"), { LynxTemplatePlugin });
+			api.modifyBundlerChain((chain) => {
+				// mithril-lynx's own src/lynx-mithril-shim.js deep-imports mithril's
+				// internal render/cachedAttrsIsStaticMap.js (and its emptyAttrs
+				// singleton). If the app's own `require("mithril")` resolves to a
+				// DIFFERENT physical copy of the package than the one mithril-lynx
+				// itself was installed/linked with — the norm for a `file:`-linked
+				// local package, whose own node_modules (built for ITS OWN tests)
+				// shadows Node's normal directory-walk resolution once linked — the
+				// two copies' emptyAttrs singletons differ. The shim then can't
+				// recognize the app's legitimately-reused empty-attrs object as
+				// such, and Mithril's own updateAttrs() misfires its "Don't reuse
+				// attrs object" warning on every plain `m(tag, null, ...)` element,
+				// every redraw. Force a single resolution by aliasing "mithril" to
+				// whatever copy the app itself resolves from its own project root.
+				try {
+					const appRequire = createRequire(path.join(process.cwd(), "package.json"));
+					// Resolve the PACKAGE DIRECTORY (not mithril's own main entry
+					// file) — a prefix alias needs "mithril/render/x" to rewrite to
+					// "<dir>/render/x", which only works aliased to a directory.
+					const mithrilDir = path.dirname(appRequire.resolve("mithril/package.json"));
+					chain.resolve.alias.set("mithril", mithrilDir);
+				} catch {
+					// App has no local "mithril" resolvable from its own root —
+					// leave resolution as-is rather than guessing.
+				}
+
+				const rawEntries = Object.entries(chain.entryPoints.entries() ?? {});
+				chain.entryPoints.clear();
+
+				for (const [name, entry] of rawEntries) {
+					const value = entry.values()?.[0];
+					const imports = typeof value === "string" || Array.isArray(value) ? value : value?.import;
+					const mtSource = Array.isArray(imports) ? imports[0] : imports;
+					if (typeof mtSource !== "string") continue;
+
+					const dir = path.dirname(mtSource);
+					const bgSource = findSibling(dir, BACKGROUND_CANDIDATES);
+					const cssSource = findSibling(dir, STYLE_CANDIDATES);
+
+					const bgEntry = `${name}__background`;
+					const mtEntry = `${name}__main-thread`;
+					const bgAsset = `.rspeedy/${name}/background.js`;
+					const mtAsset = `.rspeedy/${name}/main-thread.js`;
+					const hasBackground = bgSource != null;
+
+					// Each entry always has main-thread code and may opt into a
+					// background thread by adding a sibling background.ts file.
+					if (hasBackground) {
+						chain.entry(bgEntry).add({
+							import: bgSource,
+							filename: bgAsset,
+						});
+					}
+
+					chain.entry(mtEntry).add({
+						import: cssSource != null ? [mtSource, cssSource] : [mtSource],
+						filename: mtAsset,
+					});
+
+					chain.plugin(`template-${name}`).use(LynxTemplatePlugin, [
+						{
+							...LynxTemplatePlugin.defaultOptions,
+							filename: `${name}.bundle`,
+							intermediate: `.rspeedy/${name}`,
+							chunks: hasBackground ? [bgEntry, mtEntry] : [mtEntry],
+							dsl: "react_nodiff",
+							targetSdkVersion,
+							cssPlugins: [],
+						},
+					]);
+
+					if (hasBackground) {
+						// Background chunks run in the JavaScript thread and need the
+						// Lynx runtime wrapper; main-thread chunks are encoded as lepus.
+						chain.plugin(`runtime-wrapper-${name}`).use(
+							RuntimeWrapperWebpackPlugin,
+							[
+								{
+									targetSdkVersion,
+									test: new RegExp(`${name}/background\\.js$`),
+								},
+							],
+						);
+					}
+				}
+
+				chain.plugin("encode").use(LynxEncodePlugin, []);
+
+				chain.plugin("before-encode").use({
+					apply(compiler) {
+						compiler.hooks.thisCompilation.tap(PLUGIN_NAME, (compilation) => {
+							// The default grouping only routes a chunk to lepus (main thread)
+							// when its asset carries `lynx:main-thread`. These hand-built
+							// entries don't, so main-thread JS lands in `manifest` and lepus
+							// stays empty. Re-map it here: background JS to manifest, the
+							// main-thread chunk to lepus. CSS is already grouped correctly.
+							const hooks = LynxTemplatePlugin.getLynxTemplatePluginHooks(compilation);
+							hooks.beforeEncode.tap(PLUGIN_NAME, (args) => {
+								const pageName = args.intermediate ? path.basename(args.intermediate) : "";
+								if (!pageName) return args;
+
+								const bgAsset = `.rspeedy/${pageName}/background.js`;
+								const mtAsset = `.rspeedy/${pageName}/main-thread.js`;
+
+								const backgroundAsset = compilation.getAsset(bgAsset);
+								const mainThreadAsset = compilation.getAsset(mtAsset);
+
+								if (!mainThreadAsset) return args;
+
+								args.encodeData.compilerOptions.targetSdkVersion = targetSdkVersion;
+								args.encodeData.compilerOptions.enableEventRefactor = true;
+
+								// Route tap/gesture events through the refactored main-thread
+								// path so `__AddEventListener` handlers fire. This page-config
+								// flag was dropped from `@lynx-js/config-rsbuild-plugin` 0.2.0's
+								// schema, so set it on the page config directly.
+								args.encodeData.sourceContent.config.enableEventHandleRefactor = true;
+
+								args.encodeData.manifest = backgroundAsset
+									? {
+										[backgroundAsset.name]: backgroundAsset.source
+											.source()
+											.toString(),
+									}
+									: {};
+								args.encodeData.lepusCode = {
+									root: mainThreadAsset,
+									chunks: [],
+									filename: mainThreadAsset.name,
+								};
+
+								return args;
+							});
+						});
+					},
+				});
+			});
+		},
+	};
+}

package/renderer/background.d.ts

@@ -0,0 +1,21 @@
+// Ambient declaration for the ESM renderer/background.js (the file itself is
+// not type-checked; this describes its runtime export shape for TS consumers).
+
+export interface RenderAppOptions {
+  /** Called exactly once to build the root Mithril vnode against the virtual tree. */
+  root(): unknown;
+}
+
+/**
+ * Renders `root()` against a virtual (op-log-recording) tree and sends the
+ * resulting patch to the main thread. Call once, at background.ts's top
+ * level. See the project plan, Phase 4 ("renderer mode").
+ */
+export function renderApp(options: RenderAppOptions): void;
+
+/**
+ * Re-invokes the app's view() (via the shim's own redraw()) and flushes the
+ * resulting patch to the main thread. Call this instead of importing the
+ * shim's redraw() directly in renderer-mode event handlers.
+ */
+export function redraw(): void;

package/renderer/background.js

@@ -0,0 +1,84 @@
+// renderer/background.js
+//
+// "Renderer mode" (project plan, Phase 4): runs Mithril's UNMODIFIED diff
+// algorithm on the background thread against a VirtualNodeWrapper tree
+// (internal/virtual-node.js) instead of a real Element PAPI tree. Every
+// mutation the diff makes is recorded as a serializable op; ops accumulated
+// during one render/redraw pass are flushed as a single batch to the main
+// thread, which replays them against a real LynxNodeWrapper tree (see
+// renderer/main-thread.js's applyPatch()).
+//
+// This reuses the shim's OWN render()/redraw() convenience API unmodified —
+// the algorithm never knows it's talking to a virtual tree, because it only
+// ever calls generic dom.* methods (see ../CONTRACT.md). Note: render(), not
+// renderToPage() — renderToPage() expects a RAW native page handle and calls
+// __GetElementUniqueID() on it internally; render() takes an
+// already-constructed wrapper directly, which is what the virtual root is.
+
+import shim from "../src/lynx-mithril-shim.js";
+import { createVirtualDocument } from "../internal/virtual-node.js";
+import { rendererEventEventName, rendererPatchEventName } from "../internal/constants.js";
+
+// A real app calls renderApp() exactly once, establishing this state for the
+// lifetime of the app; redraw() operates on whatever the latest renderApp()
+// call set up. Kept in module scope (rather than passed around) only because
+// redraw() is a separate export with no other way to reach it — NOT shared
+// across independent virtual trees the way a naively module-level
+// styleProxies/vid-counter would be (createVirtualDocument() is called AFRESH
+// inside renderApp(), so each call gets its own independent document, vid
+// counter, and style-proxy registry).
+let opLog = [];
+let flushStyleProxies = () => {};
+
+/**
+ * Renders `root()` once against the virtual tree and sends the initial
+ * patch. Call exactly once, at background.ts's top level (mirrors
+ * setupApp()'s root() contract in data-channel mode: subsequent updates
+ * flow through redraw(), which re-invokes the component's view(), not
+ * root() again).
+ */
+export function renderApp(options) {
+	const { root } = options;
+	opLog = [];
+	// vid -> VirtualNodeWrapper, so forwarded main-thread events (addressed by
+	// vid) can be dispatched to the right node's listener.
+	const nodesByVid = new Map();
+
+	const virtualDocument = createVirtualDocument(
+		(op) => opLog.push(op),
+		(wrapper) => nodesByVid.set(wrapper._vid, wrapper),
+	);
+	flushStyleProxies = virtualDocument.flushStyleProxies;
+
+	const rootWrapper = virtualDocument.createRootWrapper();
+
+	shim.render(rootWrapper, root());
+	flush();
+
+	lynx.getCoreContext().addEventListener(rendererEventEventName, (event) => {
+		const { vid, type, payload } = event.data;
+		const node = nodesByVid.get(vid);
+		if (node == null) return;
+		node.dispatchEvent({
+			type,
+			currentTarget: node,
+			preventDefault() {},
+			stopPropagation() {},
+			...payload,
+		});
+	});
+}
+
+function flush() {
+	flushStyleProxies();
+	if (opLog.length === 0) return;
+	const ops = opLog;
+	opLog = [];
+	lynx.getCoreContext().dispatchEvent({ type: rendererPatchEventName, data: ops });
+}
+
+/** Re-invokes the app's view() and flushes the resulting patch. Call this — not shim.redraw() directly — after mutating state in an event handler. */
+export function redraw() {
+	shim.redraw();
+	flush();
+}

package/renderer/main-thread.d.ts

@@ -0,0 +1,12 @@
+// Ambient declaration for the ESM renderer/main-thread.js (the file itself
+// is not type-checked; this describes its runtime export shape for TS
+// consumers).
+
+/**
+ * Wires the Lynx engine's page lifecycle and the renderer-mode patch/event
+ * channel: replays op-log patches from the background thread's virtual tree
+ * against a real Element PAPI tree, and forwards real PAPI events back to
+ * the background thread by vid. Call once, at main-thread.ts's top level.
+ * See the project plan, Phase 4 ("renderer mode").
+ */
+export function setupRenderer(): void;

package/renderer/main-thread.js

@@ -0,0 +1,175 @@
+// renderer/main-thread.js
+//
+// "Renderer mode" (project plan, Phase 4) main-thread half: replays the
+// op-log produced by renderer/background.js's virtual tree against a real
+// LynxNodeWrapper tree, and forwards real Element PAPI events back to the
+// background thread by vid (see renderer/background.js's header for the
+// full picture).
+//
+// applyPatch() deliberately does NOT reimplement any PAPI-mapping logic —
+// every op is replayed by calling the EXACT SAME method (setAttribute,
+// className =, style.setProperty, ...) a normal main-thread-owned Mithril
+// app would call on a real LynxNodeWrapper, so it inherits that (already
+// tested) code's correctness for free. The one exception is style: see the
+// setStyleProps case below for why it calls __SetInlineStyles directly.
+
+import shim from "../src/lynx-mithril-shim.js";
+import {
+	destroyLifetimeEventName,
+	renderPageEventName,
+	rendererEventEventName,
+	rendererPatchEventName,
+} from "../internal/constants.js";
+
+// The native engine unconditionally invokes a global `processData(initData)`
+// hook on every __RenderPage, regardless of framework or rendering mode —
+// found missing here via real-device testing (main-thread.js, data-channel
+// mode, already had this fix from Phase 1; this file was never given it).
+Object.assign(globalThis, {
+	processData: (data) => data,
+});
+
+/**
+ * Waits for __RenderPage to create the real page (matching data-channel
+ * mode's timing, in case native requires it before the tree can be built),
+ * then wires the patch/event channel. The background thread's own initial
+ * renderApp() runs independently and may finish before or after
+ * __RenderPage fires, so patches arriving early are buffered and replayed
+ * in order once the page exists. Call once, at main-thread.ts's top level.
+ */
+export function setupRenderer() {
+	// vid -> LynxNodeWrapper. Scoped to this setupRenderer() call (a real app
+	// calls it exactly once) rather than module-level, so it can never hold
+	// stale entries from a previous, unrelated render.
+	const vidMap = new Map();
+	// (vid + ":" + type) -> the forwarding function passed to addEventListener,
+	// so a later removeEvent op can pass the SAME reference to
+	// removeEventListener (LynxNodeWrapper matches listeners by identity).
+	const forwarders = new Map();
+
+	function applyOp(op) {
+		switch (op.op) {
+			case "createElement": {
+				const wrapper = vidMap.get(0).ownerDocument.createElement(op.tag);
+				vidMap.set(op.vid, wrapper);
+				break;
+			}
+			case "createText": {
+				const wrapper = vidMap.get(0).ownerDocument.createTextNode(op.value);
+				vidMap.set(op.vid, wrapper);
+				break;
+			}
+			case "appendChild":
+				vidMap.get(op.parentVid).appendChild(vidMap.get(op.childVid));
+				break;
+			case "insertBefore":
+				vidMap.get(op.parentVid).insertBefore(
+					vidMap.get(op.childVid),
+					op.refVid != null ? vidMap.get(op.refVid) : null,
+				);
+				break;
+			case "removeChild":
+				vidMap.get(op.parentVid).removeChild(vidMap.get(op.childVid));
+				vidMap.delete(op.childVid);
+				break;
+			case "setProp":
+				vidMap.get(op.vid)[op.key] = op.value;
+				break;
+			case "setAttribute":
+				vidMap.get(op.vid).setAttribute(op.key, op.value);
+				break;
+			case "removeAttribute":
+				vidMap.get(op.vid).removeAttribute(op.key);
+				break;
+			case "setStyleProps": {
+				// The virtual side's styles object is already the COMPLETE, current
+				// style set (VirtualStyleProxy._flush recomputes it from scratch
+				// every time, exactly like the real LynxStyleProxy._flush does).
+				// Calling __SetInlineStyles directly with that complete object —
+				// rather than replaying individual `wrapper.style[key] = value`
+				// assignments through the real LynxStyleProxy — is what correctly
+				// propagates REMOVALS: the real proxy only accumulates/overwrites via
+				// setProperty, so a key absent from this op (because it was removed
+				// on the virtual side) would otherwise never get cleared.
+				//
+				// Every node gets a style proxy flushed unconditionally (matching
+				// the real shim's own flushTree(), which does the same for EVERY
+				// LynxStyleProxy ever created) — including raw text nodes, which
+				// don't support inline styles at all. The real shim's flushTree()
+				// silently swallows that failure (`try { ... } catch {}`) since it
+				// runs the flush and the PAPI call in one step, same-thread; here
+				// the two are split across the wire, so the try/catch has to live
+				// here, on the replay side, instead.
+				try {
+					__SetInlineStyles(vidMap.get(op.vid)._handle, op.styles);
+				} catch (e) {
+					/* ignore, e.g. raw text nodes have no .style */
+				}
+				break;
+			}
+			case "setText":
+				vidMap.get(op.vid).nodeValue = op.value;
+				break;
+			case "addEvent": {
+				const wrapper = vidMap.get(op.vid);
+				const forward = (ev) => {
+					const { currentTarget, preventDefault, stopPropagation, ...payload } = ev;
+					lynx.getJSContext().dispatchEvent({
+						type: rendererEventEventName,
+						data: { vid: op.vid, type: ev.type, payload },
+					});
+				};
+				forwarders.set(op.vid + ":" + op.type, forward);
+				wrapper.addEventListener(op.type, forward, {});
+				break;
+			}
+			case "removeEvent": {
+				const key = op.vid + ":" + op.type;
+				const forward = forwarders.get(key);
+				if (forward != null) {
+					vidMap.get(op.vid).removeEventListener(op.type, forward, {});
+					forwarders.delete(key);
+				}
+				break;
+			}
+			default:
+				throw new Error(`renderer/main-thread.js: unknown op "${op.op}"`);
+		}
+	}
+
+	function applyPatch(ops) {
+		for (const op of ops) applyOp(op);
+		__FlushElementTree();
+	}
+
+	const engine = lynx.getEngine();
+	const background = lynx.getJSContext();
+	let pageReady = false;
+	let pendingPatches = [];
+
+	const onPatch = (event) => {
+		if (!pageReady) {
+			pendingPatches.push(event.data);
+			return;
+		}
+		applyPatch(event.data);
+	};
+	background.addEventListener(rendererPatchEventName, onPatch);
+
+	const onRenderPage = () => {
+		const page = __CreatePage("0", 0);
+		vidMap.set(0, shim.createPageWrapper(page));
+		pageReady = true;
+		for (const ops of pendingPatches) applyPatch(ops);
+		pendingPatches = [];
+	};
+	engine.addEventListener(renderPageEventName, onRenderPage);
+
+	const onDestroyLifetime = () => {
+		background.dispatchEvent({ type: destroyLifetimeEventName, data: undefined });
+		background.removeEventListener(rendererPatchEventName, onPatch);
+		engine.removeEventListener(renderPageEventName, onRenderPage);
+		engine.removeEventListener(destroyLifetimeEventName, onDestroyLifetime);
+	};
+	engine.addEventListener(destroyLifetimeEventName, onDestroyLifetime);
+}

package/src/lynx-mithril-shim.d.ts

@@ -0,0 +1,16 @@
+// Ambient declaration for the CJS lynx-mithril-shim.js (the file itself is
+// not type-checked; this describes its runtime export shape for main-thread.ts).
+
+declare const shim: {
+  (dom: unknown, vnodes: unknown, redraw?: () => void): void;
+  render(rootWrapper: unknown, vnode: unknown): void;
+  redraw(): void;
+  createPageWrapper(pageElement: unknown): unknown;
+  renderToPage(pageElement: unknown, vnode: unknown): unknown;
+  createLynxWindow(pageElement: unknown): unknown;
+  LynxNodeWrapper: unknown;
+  LynxStyleProxy: unknown;
+  normalizeEvent(rawEv: unknown, node: unknown): unknown;
+};
+
+export default shim;