mithril-lynx 0.0.1

package/src/worklet-runtime.js

@@ -0,0 +1,82 @@
+// src/worklet-runtime.js
+//
+// Minimal, self-contained substitute for @lynx-js/react's real
+// `runtime/lib/worklet-runtime` — needed because native's gesture (and,
+// more generally, "Main Thread Script"/worklet) callback dispatch does NOT
+// call a JS function value directly. Confirmed by reading the real, shipped
+// @lynx-js/react v0.123.0 source (not guesswork — the same technique that
+// resolved list.js's Tier 2 silent-failure bug):
+//
+//   - runtime/lib/worklet-runtime/index.js is a side-effecting module: on
+//     import, if `globalThis.lynxWorkletImpl === undefined`, it calls
+//     `initWorklet()`, which sets `globalThis.registerWorklet` and
+//     `globalThis.runWorklet`. mithril-lynx never did this — those globals
+//     were simply undefined in every app built with it.
+//   - runtime/lib/worklet-runtime/workletRuntime.js's own comment on
+//     `runWorklet(ctx, params, options)`: "Entrance of all worklet calls.
+//     Native event touch handler will call this function." — i.e. native
+//     invokes gesture callbacks BY NAME through this global, not by calling
+//     the callback value itself.
+//   - `validateWorklet(ctx)` there requires
+//     `typeof ctx === 'object' && ctx !== null && ('_wkltId' in ctx || '_lepusWorkletHash' in ctx)`.
+//     A plain JS function has `typeof fn === 'function'`, which fails this
+//     check outright — explaining gesture.js's previous silent, error-free
+//     failure on a real device: nothing ever rejected the plain-function
+//     callback, native (or the missing `runWorklet`) just never ran it.
+//   - The real function body is registered separately, keyed by a
+//     `_wkltId`, via `globalThis.registerWorklet(type, id, fn)` — normally
+//     done by ReactLynx's compiled snapshot codegen, which this project
+//     deliberately has none of, so it's done by hand here at
+//     `createGesture()` call time instead (see gesture.js).
+//
+// What THIS module deliberately does NOT replicate from the real
+// workletRuntime.js (out of scope for v1, same spirit as list.js's/
+// gesture.js's own documented cuts): WorkletRef resolution, the
+// JsFunctionLifecycleManager refcounting (`runOnBackground` cross-thread
+// closures), and `addEventMethodsIfNeeded`'s event-method injection
+// (`e.stopPropagation()`-style calls from inside a worklet body). A gesture
+// callback that only reads its event argument and/or calls other
+// mithril-lynx APIs (setState, background.runOnBackground, ...) is fully
+// covered; one relying on those extra pieces is not, in v1.
+
+function ensureWorkletRuntime() {
+	if (globalThis.lynxWorkletImpl !== undefined) return;
+	globalThis.lynxWorkletImpl = { _workletMap: {} };
+	globalThis.registerWorklet = function (_type, id, fn) {
+		globalThis.lynxWorkletImpl._workletMap[id] = fn;
+	};
+	globalThis.runWorklet = function (ctx, params) {
+		if (typeof ctx !== "object" || ctx === null || !("_wkltId" in ctx)) return;
+		var fn = globalThis.lynxWorkletImpl._workletMap[ctx._wkltId];
+		if (typeof fn !== "function") return;
+		var args = Array.isArray(params) ? params : params != null ? [params] : [];
+		// Deliberately NOT fn.apply(ctx, args): native passes gesture
+		// callbacks a 2nd argument — a native "gesture controller" object
+		// ({__SetGestureState, __ConsumeGesture}) — that throws "TypeError:
+		// not a object" when it crosses Function.prototype.apply()'s
+		// argument-list marshalling, but is fine passed positionally.
+		// Confirmed on-device by bisecting each call step; matches
+		// @lynx-js/react's own runWorkletImpl, which never uses apply()/
+		// call() either — it does `worklet(...params_)`, a plain spread call.
+		return fn.bind(ctx)(...args);
+	};
+}
+
+let nextWorkletId = 1;
+
+/**
+ * Registers `fn` as a callable worklet and returns the ctx object native
+ * expects in its place (`{ _wkltId }`), per `validateWorklet()`'s real
+ * contract. `workletType` matches ReactLynx's own values ("main-thread" is
+ * the only one mithril-lynx currently has a use for — see gesture.js).
+ */
+function wrapWorkletCallback(fn, workletType) {
+	if (typeof fn !== "function") return fn;
+	ensureWorkletRuntime();
+	const id = "mithril-lynx-worklet-" + nextWorkletId++;
+	globalThis.registerWorklet(workletType || "main-thread", id, fn);
+	return { _wkltId: id };
+}
+
+module.exports.ensureWorkletRuntime = ensureWorkletRuntime;
+module.exports.wrapWorkletCallback = wrapWorkletCallback;

package/testing.d.ts

@@ -0,0 +1,10 @@
+// Ambient declaration for the ESM testing.js (the file itself is not
+// type-checked; this describes its runtime export shape for TS consumers).
+
+/**
+ * Installs the @lynx-js/testing-environment PAPI polyfill mithril-lynx apps
+ * need for their own tests. Assign to
+ * globalThis.onInjectMainThreadGlobals in a test setup file. See the
+ * project plan, Phase 9.
+ */
+export function installTestingPolyfills(target: any): void;

package/testing.js

@@ -0,0 +1,91 @@
+// testing.js
+//
+// Reusable @lynx-js/testing-environment PAPI polyfill for mithril-lynx apps
+// (project plan, Phase 9). @lynx-js/testing-environment implements the
+// string/worklet event PAPI ReactLynx uses (__AddEvent); the shim binds REAL
+// JS function listeners through __AddEventListener, so that family — plus a
+// handful of other PAPI functions the testing environment doesn't implement
+// at all (used by element.js/gesture.js/list.js) — is polyfilled here.
+//
+// Usage, in a test setup file (e.g. test/setup.ts):
+//
+//   import { installTestingPolyfills } from "mithril-lynx/testing";
+//   globalThis.onInjectMainThreadGlobals = installTestingPolyfills;
+//
+// Originally lived duplicated in mithril-app's own test/setup.ts and this
+// package's; extracted here once both copies needed the exact same fixes
+// (getEngine alias, __SetGestureState, __InvokeUIMethod) independently.
+
+const papiCalls = [];
+
+function record(name, fn) {
+	const wrapped = (...args) => {
+		papiCalls.push({ fn: name, args });
+		return fn(...args);
+	};
+	wrapped.__papiRecorded = true;
+	return wrapped;
+}
+
+/**
+ * Installs the polyfill on the main-thread globals object
+ * @lynx-js/testing-environment hands to onInjectMainThreadGlobals.
+ */
+export function installTestingPolyfills(target) {
+	// The testing environment exposes the native page-lifecycle event bus via
+	// lynx.getNative() (addEventListener/removeEventListener/dispatchEvent),
+	// but doesn't alias it to getEngine() (what real Lynx and mithril-lynx's
+	// main-thread.js call). Alias it here so setupApp()/setupRenderer() can
+	// register for __RenderPage/__UpdatePage/__DestroyLifetime and tests can
+	// drive them via lynx.getEngine().dispatchEvent(...).
+	target.lynx.getEngine = target.lynx.getNative;
+
+	// Function-based event listeners (the testing env only implements the
+	// string/worklet __AddEvent family). Stored per element so tests can
+	// simulate a user gesture by invoking them.
+	target.__AddEventListener = (node, name, handler) => {
+		node.__vanillaListeners ??= {};
+		(node.__vanillaListeners[name] ??= new Set()).add(handler);
+	};
+
+	target.__RemoveEventListener = (node, name, handler) => {
+		node.__vanillaListeners?.[name]?.delete(handler);
+	};
+
+	target.__GetChildren = (node) => Array.from(node.childNodes ?? []);
+
+	target.__ElementIsEqual = (left, right) => left === right;
+
+	// Not implemented by the testing environment — used by gesture.js's
+	// Gesture.setState(). Recorded on the element for tests to inspect.
+	target.__SetGestureState = (node, id, state) => {
+		node.gestureState = { id, state };
+	};
+
+	// Not implemented by the testing environment at all — used by element.js's
+	// invoke(). Always succeeds, echoing back the call, so tests can assert on
+	// what element.js passed through without this polyfill guessing at real
+	// native success/failure semantics.
+	target.__InvokeUIMethod = (_node, method, params, callback) => {
+		callback({ code: 0, data: { method, params } });
+		return [];
+	};
+
+	// Tree-traversal helpers the shim needs that the testing env does not provide.
+	target.__GetParent = (node) => node?.parentNode ?? null;
+	target.__NextElement = (node) => node?.nextSibling ?? null;
+	target.__ReplaceElements = (parent, newChildren, oldChildren) => {
+		for (const child of oldChildren ?? []) {
+			if (child.parentNode === parent) parent.removeChild(child);
+		}
+		for (const child of newChildren ?? []) parent.appendChild(child);
+	};
+
+	// Record every PAPI call so tests can assert on side effects.
+	for (const name of Object.getOwnPropertyNames(target)) {
+		if (name.startsWith("__") && typeof target[name] === "function" && !target[name].__papiRecorded) {
+			target[name] = record(name, target[name]);
+		}
+	}
+	target.__papiCalls = papiCalls;
+}