mithril-lynx 0.0.9 → 2.0.0

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 carlos-sweb
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/background.d.ts

@@ -1,54 +0,0 @@
-// Ambient declaration for the ESM background.js (the file itself is not
-// type-checked; this describes its runtime export shape for TS consumers).
-
-export type StoreData = Record<string, unknown>;
-
-export interface SetDataOptions {
-  /** Set false to update the store without pushing a sync to the main thread. Defaults to true. */
-  shouldSyncToMainThread?: boolean;
-}
-
-/** Returns the background thread's mutable data store. */
-export function getData<T = StoreData>(): T;
-
-/** Merges `patch` into the store, then (by default) pushes the changed keys to the main thread. */
-export function setData(patch: StoreData, options?: SetDataOptions): void;
-
-/**
- * Registers the single handler invoked for every dispatchToBackground() call
- * made from the main thread, as (handlerName, data).
- */
-export function setBackgroundEventHandler(
-  handleEvent: (handlerName: string, data: unknown) => unknown,
-): void;
-
-/**
- * Wires the background thread's core-context listeners for the
- * main-thread <-> background-thread data channel. Call once, at
- * background.ts's top level. See the project plan, Phase 3.
- */
-export function setupBackground(): void;
-
-export interface BackgroundRef {
-  /** Resolves with the native method's success data, rejects with its failure data. */
-  invoke(method: string, params?: Record<string, unknown>): Promise<unknown>;
-}
-
-/**
- * A background-thread ref: imperative calls to a native element identified
- * by a CSS selector, via lynx.createSelectorQuery(). See the project plan,
- * Phase 5.
- */
-export function createRef(selector: string): BackgroundRef;
-
-/**
- * Registers a handler main-thread.js's runOnBackground(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 main-thread.js registered via registerHandler(key, fn).
- * Args and the resolved value must be JSON-serializable.
- */
-export function runOnMainThread<T = unknown>(key: string, ...args: unknown[]): Promise<T>;

package/background.js

@@ -1,169 +0,0 @@
-// background.js
-//
-// Cross-thread "data-channel mode" adapter for the background thread (see
-// the project plan, Phase 3). Ports
-// lynx-examples/examples/vanilla/src/common/background/{setup,data,event}.ts
-// into a single module — this side is framework-agnostic (Mithril never
-// renders on the background thread in data-channel mode), so nothing here
-// depends on the shim.
-//
-// A single mutable data store is diffed against its last-synced snapshot on
-// every setData() call and only the changed keys are pushed to the main
-// thread. Data received FROM the main thread is never echoed back (the
-// reference implementation does, on every update after the first — a
-// pure round-trip echo that's wasteful, and directly visible as a redundant
-// extra Mithril redraw in this port, so it isn't reproduced here).
-
-import {
-	callBackgroundEventName,
-	callBackgroundResultEventName,
-	callMainThreadEventName,
-	callMainThreadResultEventName,
-	destroyLifetimeEventName,
-	dispatchEventToBackgroundEventName,
-	updateDataFromBackgroundEventName,
-	updateDataFromMainThreadEventName,
-} from "./internal/constants.js";
-
-const data = {};
-let lastSyncedData = { ...data };
-let handleBackgroundEvent;
-
-export function getData() {
-	return data;
-}
-
-export function setData(patch, options = {}) {
-	const { shouldSyncToMainThread = true } = options;
-	Object.assign(data, patch);
-	if (!shouldSyncToMainThread) {
-		lastSyncedData = { ...data };
-		return;
-	}
-	sendToMainThread();
-}
-
-function sendToMainThread() {
-	const patch = {};
-	for (const [key, value] of Object.entries(data)) {
-		if (value !== lastSyncedData[key]) patch[key] = value;
-	}
-	if (Object.keys(patch).length === 0) return;
-	lastSyncedData = { ...data };
-	lynx.getCoreContext().dispatchEvent({
-		type: updateDataFromBackgroundEventName,
-		data: patch,
-	});
-}
-
-// handleEvent(handlerName, data) — called for every dispatchToBackground()
-// call made from the main thread. Only one handler at a time; Phase 6 of the
-// project plan generalizes this into a full string-keyed registry with
-// call/return correlation.
-export function setBackgroundEventHandler(handleEvent) {
-	handleBackgroundEvent = handleEvent;
-}
-
-export function setupBackground() {
-	const coreContext = lynx.getCoreContext();
-
-	const onUpdateDataFromMainThread = (event) => {
-		const incoming = event.data;
-		if (!incoming || typeof incoming !== "object" || Array.isArray(incoming)) return;
-		// Never echo data back to the thread it just came from — only
-		// background-initiated setData() calls (elsewhere in app code)
-		// should sync to the main thread.
-		setData(incoming, { shouldSyncToMainThread: false });
-	};
-
-	const onDispatchToBackground = (event) => {
-		const payload = event.data;
-		if (!payload || typeof payload.handlerName !== "string") return;
-		handleBackgroundEvent?.(payload.handlerName, payload.data);
-	};
-
-	const cleanup = () => {
-		coreContext.removeEventListener(updateDataFromMainThreadEventName, onUpdateDataFromMainThread);
-		coreContext.removeEventListener(dispatchEventToBackgroundEventName, onDispatchToBackground);
-		coreContext.removeEventListener(destroyLifetimeEventName, cleanup);
-	};
-
-	coreContext.addEventListener(updateDataFromMainThreadEventName, onUpdateDataFromMainThread);
-	coreContext.addEventListener(dispatchEventToBackgroundEventName, onDispatchToBackground);
-	coreContext.addEventListener(destroyLifetimeEventName, cleanup);
-}
-
-// Refs (project plan, Phase 5): the background thread has no direct native
-// handle, so imperative calls go through Lynx's existing selector-query
-// bridge (the same primitive ReactLynx's own background-thread refs
-// ultimately bottom out on) rather than a new protocol.
-export function createRef(selector) {
-	return {
-		invoke(method, params) {
-			return new Promise((resolve, reject) => {
-				lynx.createSelectorQuery()
-					.select(selector)
-					.invoke({
-						method,
-						params: params || {},
-						success: (data) => resolve(data),
-						fail: (data) => reject(data),
-					})
-					.exec();
-			});
-		},
-	};
-}
-
-// Cross-thread function registry (project plan, Phase 6 — worklet
-// substitute). See main-thread.js's registerHandler()/runOnBackground() for
-// the full rationale; this is the mirror image for the reverse direction.
-// Lazy setup on first use, same reasoning as main-thread.js.
-const backgroundHandlers = new Map();
-const pendingMainThreadCalls = new Map();
-let nextCallId = 1;
-let crossThreadCallsReady = false;
-
-function ensureCrossThreadCalls() {
-	if (crossThreadCallsReady) return;
-	crossThreadCallsReady = true;
-	const coreContext = lynx.getCoreContext();
-
-	coreContext.addEventListener(callBackgroundEventName, (event) => {
-		const { callId, key, args } = event.data;
-		const fn = backgroundHandlers.get(key);
-		let result;
-		let error;
-		try {
-			result = fn ? fn(...args) : undefined;
-		} catch (e) {
-			error = e instanceof Error ? e.message : String(e);
-		}
-		coreContext.dispatchEvent({ type: callBackgroundResultEventName, data: { callId, result, error } });
-	});
-
-	coreContext.addEventListener(callMainThreadResultEventName, (event) => {
-		const { callId, result, error } = event.data;
-		const pending = pendingMainThreadCalls.get(callId);
-		if (pending == null) return;
-		pendingMainThreadCalls.delete(callId);
-		if (error != null) pending.reject(new Error(error));
-		else pending.resolve(result);
-	});
-}
-
-/** Registers a handler main-thread.js's runOnBackground(key, ...) can call by name. */
-export function registerHandler(key, fn) {
-	ensureCrossThreadCalls();
-	backgroundHandlers.set(key, fn);
-}
-
-/** Calls a handler main-thread.js registered via registerHandler(key, fn), by name. Args must be JSON-serializable. */
-export function runOnMainThread(key, ...args) {
-	ensureCrossThreadCalls();
-	return new Promise((resolve, reject) => {
-		const callId = nextCallId++;
-		pendingMainThreadCalls.set(callId, { resolve, reject });
-		lynx.getCoreContext().dispatchEvent({ type: callMainThreadEventName, data: { callId, key, args } });
-	});
-}

package/element.d.ts

@@ -1,34 +0,0 @@
-// Ambient declaration for the ESM element.js (the file itself is not
-// type-checked; this describes its runtime export shape for TS consumers).
-
-export interface SelectorParams {
-  onlyCurrentComponent?: boolean;
-}
-
-export interface AnimationTimingOptions {
-  name?: string;
-  duration?: number | string;
-  delay?: number | string;
-  iterationCount?: number | string;
-  fillMode?: string;
-  timingFunction?: string;
-  direction?: string;
-}
-
-export type Keyframe = Record<string, string | number>;
-
-export interface MainThreadElement {
-  setStyleProperty(name: string, value: string | number): void;
-  setStyleProperties(styles: Record<string, string | number>): void;
-  setAttribute(name: string, value: unknown): void;
-  querySelector(selector: string, params?: SelectorParams): MainThreadElement | null;
-  querySelectorAll(selector: string, params?: SelectorParams): MainThreadElement[];
-  animate(keyframes: Keyframe[], options?: AnimationTimingOptions): void;
-  playAnimation(name: string): void;
-  pauseAnimation(name: string): void;
-  cancelAnimation(name: string): void;
-  invoke(method: string, params?: Record<string, unknown>): Promise<{ code: number; data: unknown }>;
-}
-
-/** Wraps a node (anything with a `_handle`, i.e. a real LynxNodeWrapper) with imperative PAPI methods. */
-export function wrapElement(node: { _handle: unknown }): MainThreadElement;

package/element.js

@@ -1,83 +0,0 @@
-// element.js
-//
-// Ergonomic imperative escape hatch for a main-thread node — whatever
-// Mithril's oncreate(vnode)/onupdate(vnode) hooks hand you as `vnode.dom`
-// (works for any real LynxNodeWrapper: main-thread-owned mode, or
-// data-channel mode's main-thread half). Not part of render.js's own DOM
-// contract (see ../CONTRACT.md) — these are Element PAPI capabilities apps
-// reach for directly (focusing a native input, animating, calling a native
-// custom element's method), so they live in their own small module instead
-// of the shim.
-//
-// Project plan, Phase 5. Background-thread refs are the selector-query
-// equivalent — see background.js's createRef().
-
-const ANIMATION_OPERATION = { START: 0, PLAY: 1, PAUSE: 2, CANCEL: 3 };
-
-function wrapRef(handle) {
-	return handle == null ? null : wrapElement({ _handle: handle });
-}
-
-/**
- * Wraps a node (anything with a `_handle`, i.e. a real LynxNodeWrapper OR a
- * raw ElementRef from querySelector) with imperative PAPI methods render.js
- * itself never needs. setAttribute mirrors the real LynxNodeWrapper's own
- * class/id/data-prefixed/generic-attribute special-casing (see
- * ../CONTRACT.md) rather than delegating to node.setAttribute() directly —
- * a raw querySelector result has no such method, only a `_handle`.
- */
-export function wrapElement(node) {
-	const handle = node._handle;
-
-	return {
-		setStyleProperty(name, value) {
-			__SetInlineStyles(handle, { [name]: value });
-		},
-
-		setStyleProperties(styles) {
-			__SetInlineStyles(handle, styles);
-		},
-
-		setAttribute(name, value) {
-			// "" not undefined when clearing: real hardware's FiberSetClasses
-			// rejects a non-string argument ("FiberSetClasses param 1 should be
-			// String") — see lynx-mithril-shim.js's own matching fix for the
-			// same call.
-			if (name === "class") __SetClasses(handle, value == null ? "" : String(value));
-			else if (name === "id") __SetID(handle, value == null ? null : String(value));
-			else if (name.slice(0, 5) === "data-") __AddDataset(handle, name.slice(5), value);
-			else __SetAttribute(handle, name, value == null ? null : value);
-		},
-
-		querySelector(selector, params) {
-			return wrapRef(__QuerySelector(handle, selector, params || {}));
-		},
-
-		querySelectorAll(selector, params) {
-			return __QuerySelectorAll(handle, selector, params || {}).map((ref) => wrapRef(ref));
-		},
-
-		animate(keyframes, options) {
-			__ElementAnimate(handle, [ANIMATION_OPERATION.START, (options && options.name) || "", keyframes, options]);
-		},
-
-		playAnimation(name) {
-			__ElementAnimate(handle, [ANIMATION_OPERATION.PLAY, name]);
-		},
-
-		pauseAnimation(name) {
-			__ElementAnimate(handle, [ANIMATION_OPERATION.PAUSE, name]);
-		},
-
-		cancelAnimation(name) {
-			__ElementAnimate(handle, [ANIMATION_OPERATION.CANCEL, name]);
-		},
-
-		/** Always resolves with { code, data } — check `code` yourself; PAPI's success/failure convention isn't assumed here. */
-		invoke(method, params) {
-			return new Promise((resolve) => {
-				__InvokeUIMethod(handle, method, params || {}, (res) => resolve(res));
-			});
-		},
-	};
-}

package/gesture.d.ts

@@ -1,40 +0,0 @@
-// Ambient declaration for the ESM gesture.js (the file itself is not
-// type-checked; this describes its runtime export shape for TS consumers).
-
-export const GestureType: {
-  readonly COMPOSED: -1;
-  readonly PAN: 0;
-  readonly FLING: 1;
-  readonly DEFAULT: 2;
-  readonly TAP: 3;
-  readonly LONGPRESS: 4;
-  readonly ROTATION: 5;
-  readonly PINCH: 6;
-  readonly NATIVE: 7;
-};
-
-export type GestureTypeName = keyof typeof GestureType;
-
-export interface Gesture {
-  id: number;
-  remove(): void;
-  setState(state: number): void;
-}
-
-export interface GestureController {
-  __SetGestureState(state: number): void;
-  __ConsumeGesture(options: Record<string, boolean>): void;
-}
-
-export interface CreateGestureOptions {
-  type: number | GestureTypeName;
-  /** Each callback is invoked as `(event, controller) => {}`; `controller` can usually be ignored. */
-  callbacks?: Record<string, (event: unknown, controller: GestureController) => unknown>;
-  waitFor?: Gesture[];
-  simultaneousWith?: Gesture[];
-  continueWith?: Gesture[];
-  config?: Record<string, unknown>;
-}
-
-/** Registers a gesture detector on a node (anything with a `_handle`). See the project plan, Phase 7. */
-export function createGesture(node: { _handle: unknown }, options: CreateGestureOptions): Gesture;

package/gesture.js

@@ -1,117 +0,0 @@
-// gesture.js
-//
-// Gesture composition API (project plan, Phase 7), main-thread only. Built
-// on __SetGestureDetector — a plain, same-thread PAPI call (no cross-thread
-// serialization boundary), so this needs nothing beyond a real node handle
-// PLUS the small worklet-registration step below. A callback that needs to
-// notify background-owned state can call main-thread.js's
-// runOnBackground() itself, inside the callback body — an explicit, opt-in
-// cross-thread hop only where the app actually needs one.
-//
-// RESOLVED (2026-09-09), via the SAME technique used to fix list.js's Tier
-// 2 (read the real, shipped @lynx-js/react source more deeply — see
-// DEVICE_VERIFICATION.md), plus one config-level bug found the hard way.
-// THREE issues stacked here, found and fixed in this order:
-//
-// 1. The config/relationMap shape below matches @lynx-js/react's own
-//    runtime/lib/snapshot/gesture/processGesture.js verbatim (real, shipped
-//    code — __SetGestureDetector for both create and update, has-react-
-//    gesture/flatten set first). But that file's own callback slot type is
-//    loose (`callback: unknown`) — reading one file deeper,
-//    runtime/lib/worklet-runtime/workletRuntime.js, revealed native invokes
-//    gesture callbacks through a global `runWorklet(ctx, params)`, whose
-//    `validateWorklet(ctx)` requires `typeof ctx === 'object'`. A plain JS
-//    function fails that and is dropped with NO error — exactly this
-//    project's first real-device symptom (zero console output on a swipe).
-//    Fixed by `./src/worklet-runtime.js`'s `wrapWorkletCallback()`.
-// 2. Even with (1) fixed, still zero output — because `enableNewGesture`
-//    (a Lynx SDK compiler/runtime option, @lynx-js/type-config's
-//    config.d.ts, `@defaultValue false`) was never turned on for this app.
-//    Without it, __SetGestureDetector registrations are accepted but the
-//    runtime keeps using "the legacy touch-only gesture path" and never
-//    acts on them at all — see the consuming app's lynx.config.ts.
-// 3. With both fixed, native finally called into JS — and immediately threw
-//    `TypeError: not a object`. Bisected step-by-step on-device: native
-//    calls a gesture callback with TWO arguments, `(event, controller)`,
-//    where `controller` is a native host object (`{__SetGestureState,
-//    __ConsumeGesture}`). That object throws when it crosses
-//    `Function.prototype.apply()`'s argument-list marshalling, but is fine
-//    passed positionally — matching @lynx-js/react's own runWorkletImpl,
-//    which never uses apply()/call() either (`worklet(...params_)`, a
-//    plain spread call). Fixed in `./src/worklet-runtime.js`.
-//
-// Confirmed end-to-end on the real device: a full pan (start → update →
-// end) updates UI state with zero errors. See `./src/worklet-runtime.js`
-// for exactly what's reimplemented vs. scoped out of the real worklet
-// runtime, and `callbacks`' new second-argument note below.
-
-import { wrapWorkletCallback } from "./src/worklet-runtime.js";
-
-export const GestureType = {
-	COMPOSED: -1,
-	PAN: 0,
-	FLING: 1,
-	DEFAULT: 2,
-	TAP: 3,
-	LONGPRESS: 4,
-	ROTATION: 5,
-	PINCH: 6,
-	NATIVE: 7,
-};
-
-let nextGestureId = 1;
-
-/**
- * Registers a gesture detector on `node` (anything with a `_handle`, i.e. a
- * real LynxNodeWrapper). `type` is a GestureType value or its string key
- * ("pan", "tap", ...). `callbacks` keys are event names (e.g. "onStart",
- * "onUpdate", "onEnd") mapped to plain functions, called directly, same
- * thread. Each is invoked as `(event, controller) => {}` — `controller`
- * (`{__SetGestureState, __ConsumeGesture}`) is a native gesture-arena
- * handle; most callbacks can ignore it entirely.
- * `waitFor`/`simultaneousWith`/`continueWith` are arrays of OTHER
- * createGesture() return values, for gesture-arena composition.
- */
-export function createGesture(node, options) {
-	const {
-		type,
-		callbacks = {},
-		waitFor = [],
-		simultaneousWith = [],
-		continueWith = [],
-		config,
-	} = options;
-	const handle = node._handle;
-	const gestureType = typeof type === "string" ? GestureType[type.toUpperCase()] : type;
-	const id = nextGestureId++;
-
-	// Marker attributes native needs to recognize a gesture-enabled element —
-	// kept verbatim from processGesture.js's own names/values, since it's
-	// unclear whether native checks these exact strings independent of
-	// framework, or whether they're purely a ReactLynx-side bookkeeping detail.
-	__SetAttribute(handle, "has-react-gesture", true);
-	__SetAttribute(handle, "flatten", false);
-
-	const detectorConfig = {
-		callbacks: Object.keys(callbacks).map((name) => ({ name, callback: wrapWorkletCallback(callbacks[name]) })),
-	};
-	if (config != null) detectorConfig.config = config;
-
-	const relationMap = {
-		waitFor: waitFor.map((g) => g.id),
-		simultaneous: simultaneousWith.map((g) => g.id),
-		continueWith: continueWith.map((g) => g.id),
-	};
-
-	__SetGestureDetector(handle, id, gestureType, detectorConfig, relationMap);
-
-	return {
-		id,
-		remove() {
-			if (typeof __RemoveGestureDetector === "function") __RemoveGestureDetector(handle, id);
-		},
-		setState(state) {
-			__SetGestureState(handle, id, state);
-		},
-	};
-}

package/internal/constants.js

@@ -1,26 +0,0 @@
-// Shared event-name constants for the main-thread <-> background-thread
-// channel, ported from lynx-examples/examples/vanilla/src/common/constant.ts.
-// Native engine lifecycle events keep their exact native names; custom
-// app-level events are namespaced to avoid colliding with other libraries
-// dispatching on the same shared event bus.
-
-export const renderPageEventName = "__RenderPage";
-export const updatePageEventName = "__UpdatePage";
-export const destroyLifetimeEventName = "__DestroyLifetime";
-
-export const updateDataFromMainThreadEventName = "MithrilLynx:UpdateDataFromMainThread";
-export const updateDataFromBackgroundEventName = "MithrilLynx:UpdateDataFromBackground";
-export const dispatchEventToBackgroundEventName = "MithrilLynx:DispatchEventToBackground";
-
-// Renderer mode (Phase 4): background thread ships op-log patches to main
-// thread; main thread forwards real PAPI events back to background by vid.
-export const rendererPatchEventName = "MithrilLynx:RendererPatch";
-export const rendererEventEventName = "MithrilLynx:RendererEvent";
-
-// Cross-thread function registry (Phase 6, worklet substitute): call/return
-// correlation for genuinely cross-thread calls. "ToMainThread"/"ToBackground"
-// name which side the CALL travels to — each has its own result event.
-export const callMainThreadEventName = "MithrilLynx:CallMainThread";
-export const callMainThreadResultEventName = "MithrilLynx:CallMainThreadResult";
-export const callBackgroundEventName = "MithrilLynx:CallBackground";
-export const callBackgroundResultEventName = "MithrilLynx:CallBackgroundResult";