@sigx/lynx-runtime 0.4.0 → 0.4.1

package/dist/jsx.d.ts

@@ -17,7 +17,7 @@
  * the imports — see lynx-runtime README for details.
  */
 import type { Model } from '@sigx/runtime-core';
-import type { MainThreadRef } from './main-thread-ref';
+import type { MainThreadRef } from './main-thread-ref.js';
 export type LynxEventHandler<E = any> = (event: E) => void;
 export declare namespace MainThread {
     /** Element handle available in main-thread event handlers via MainThreadRef.current. */
@@ -97,12 +97,21 @@ export interface LynxCommonAttributes {
     catchtouchend?: LynxEventHandler;
     bindtouchcancel?: LynxEventHandler;
     catchtouchcancel?: LynxEventHandler;
+    /**
+     * Fires when this element's measured layout (frame, padding, border)
+     * changes. Lynx 3.7+. Works on any element; for `<text>` specifically
+     * see also the text-only `bindlayout` event which carries extra
+     * baseline/line metrics.
+     */
+    bindlayoutchange?: LynxEventHandler;
+    catchlayoutchange?: LynxEventHandler;
     onTap?: LynxEventHandler;
     onLongpress?: LynxEventHandler;
     onTouchstart?: LynxEventHandler;
     onTouchmove?: LynxEventHandler;
     onTouchend?: LynxEventHandler;
     onTouchcancel?: LynxEventHandler;
+    onLayoutchange?: LynxEventHandler;
     /** Bind a MainThreadRef to this element for synchronous MT access. */
     'main-thread:ref'?: MainThreadRef<MainThread.Element | null>;
     'main-thread-bindtap'?: LynxEventHandler;
@@ -129,8 +138,25 @@ export interface TextAttributes extends LynxCommonAttributes {
     'number-of-lines'?: number;
     /** Text overflow mode */
     'text-overflow'?: 'clip' | 'ellipsis';
-    /** Selectable text */
-    selectable?: boolean;
+    /**
+     * Enable native text selection (long-press to select, system context
+     * menu for copy/share). Lynx 3.7+.
+     */
+    'text-selection'?: boolean;
+    /**
+     * Suppress the system context menu after selection so the app can
+     * render its own. Only takes effect when `text-selection` is enabled.
+     * Lynx 3.7+.
+     */
+    'custom-text-selection'?: boolean;
+    /** Fires when the selection range changes (selection start/end). */
+    bindselectionchange?: LynxEventHandler;
+    /** Fires when text layout is computed (frame/baseline/line metrics). */
+    bindlayout?: LynxEventHandler;
+    /** Convenience alias for `bindselectionchange`. */
+    onSelectionchange?: LynxEventHandler;
+    /** Convenience alias for `bindlayout`. */
+    onLayout?: LynxEventHandler;
 }
 export interface ImageAttributes extends LynxCommonAttributes {
     /** Image source URI */

package/dist/jsx.js

@@ -0,0 +1,19 @@
+/**
+ * Lynx JSX intrinsic element type definitions for SignalX.
+ *
+ * Importing this file (which happens automatically when you import
+ * `@sigx/lynx-runtime`) globally augments `JSX.IntrinsicElements` so
+ * that <view>, <text>, <image>, <scroll-view>, <list>, <list-item>,
+ * <input>, <textarea>, <page>, <svg>, <filter-image> are recognised
+ * with their proper attribute types.
+ *
+ * Same pattern as packages/runtime-dom/src/jsx.tsx (DOM elements) and
+ * packages/runtime-terminal/src/index.ts (<box>/<text>/<br>).
+ *
+ * Hybrid web+lynx codebases that import both @sigx/runtime-dom and
+ * @sigx/lynx-runtime will hit a TypeScript merge error on <input>
+ * because runtime-dom declares it via InputHTMLAttributes and we
+ * declare it via InputAttributes. Pick one platform per app or alias
+ * the imports — see lynx-runtime README for details.
+ */
+export {};

package/dist/main-thread-ref.js

@@ -0,0 +1,134 @@
+/**
+ * MainThreadRef — a ref whose `.current` value lives on the Main Thread.
+ *
+ * On the Background Thread, `.current` is always the initial value (typically
+ * `null`). On the Main Thread, `.current` is set to the real Lynx element
+ * handle when the ref is bound via `main-thread:ref={ref}`.
+ *
+ * This is the sigx equivalent of react-lynx's `useMainThreadRef()` and
+ * vue-lynx's `useMainThreadRef()`. It enables zero-latency style updates
+ * and animations by giving main-thread event handlers synchronous access
+ * to native elements.
+ *
+ * Architecture:
+ *   BG: useMainThreadRef(init) → MainThreadRef { wvid, current: init }
+ *        → pushOp(INIT_MT_REF, wvid, init)
+ *   BG: patchProp('main-thread:ref', ref) → pushOp(SET_MT_REF, elId, wvid)
+ *   MT: INIT_MT_REF → workletRefs.set(wvid, { current: init })
+ *   MT: SET_MT_REF  → workletRefs.get(wvid).current = elements.get(elId)
+ */
+import { onUnmounted } from '@sigx/runtime-core';
+import { OP, pushOp, scheduleFlush } from './op-queue.js';
+// ---------------------------------------------------------------------------
+// Worklet variable ID generator
+// ---------------------------------------------------------------------------
+let nextWvid = 1;
+export function resetWvidCounter() {
+    nextWvid = 1;
+}
+// ---------------------------------------------------------------------------
+// MainThreadRef class
+// ---------------------------------------------------------------------------
+/**
+ * A ref whose `.current` property is managed on the Main Thread.
+ *
+ * On the BG thread, `.current` returns the `initValue` and is read-only
+ * (setting it has no effect — the real value lives on MT).
+ *
+ * In main-thread event handlers and `runOnMainThread` callbacks, `.current`
+ * is the real Lynx element handle with methods like `setStyleProperties()`,
+ * `getComputedStyleProperty()`, and `animate()`.
+ */
+export class MainThreadRef {
+    /**
+     * Worklet variable ID — uniquely identifies this ref across threads.
+     * Underscored to match the field name `transformWorklet` walks for
+     * in @lynx-js/react/worklet-runtime when expanding `_c` captures.
+     */
+    _wvid;
+    /**
+     * Initial value snapshot — sent to MT in INIT_MT_REF and used by
+     * the worklet-runtime to seed the firstScreen ref map.
+     */
+    _initValue;
+    /**
+     * On BG: the init value (read-only snapshot).
+     * On MT: the real element handle (set by SET_MT_REF op).
+     */
+    current;
+    constructor(initValue) {
+        this._wvid = nextWvid++;
+        this._initValue = initValue;
+        this.current = initValue;
+    }
+}
+/**
+ * Walk a captured `_c` map and serialize MainThreadRef instances to plain
+ * `{ _wvid, _initValue }` objects so they survive the JSON round-trip across
+ * the BG→MT bridge. Upstream's worklet-runtime walks `_c` looking for `_wvid`
+ * to recognize ref captures and resolve them via
+ * `lynxWorkletImpl._refImpl._workletRefMap`.
+ *
+ * Used by both the SET_WORKLET_EVENT path (`nodeOps.patchProp`) and the
+ * SET_GESTURE_DETECTOR path (`native/gesture-detector.ts`).
+ */
+export function sanitizeCaptured(captured) {
+    const out = {};
+    for (const k in captured) {
+        const v = captured[k];
+        if (v instanceof MainThreadRef) {
+            out[k] = { _wvid: v._wvid, _initValue: v._initValue };
+        }
+        else {
+            out[k] = v;
+        }
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// useMainThreadRef composable
+// ---------------------------------------------------------------------------
+/**
+ * Create a ref that provides synchronous access to a native element on the
+ * Main Thread. Bind it to an element via `main-thread:ref={ref}`.
+ *
+ * @example
+ * ```tsx
+ * const elRef = useMainThreadRef<MainThread.Element>(null);
+ *
+ * function handleScroll(e: ScrollEvent) {
+ *   'main thread';
+ *   const offset = e.detail.scrollTop;
+ *   elRef.current?.setStyleProperties({
+ *     transform: `translateY(${-offset}px)`,
+ *   });
+ * }
+ *
+ * return (
+ *   <scroll-view
+ *     main-thread-bindscroll={handleScroll}
+ *   >
+ *     <view main-thread:ref={elRef}>
+ *       <text>Sticky header</text>
+ *     </view>
+ *   </scroll-view>
+ * );
+ * ```
+ */
+export function useMainThreadRef(initValue) {
+    const ref = new MainThreadRef(initValue);
+    // Tell the MT to create a worklet ref holder with this ID and initial value.
+    pushOp(OP.INIT_MT_REF, ref._wvid, initValue);
+    scheduleFlush();
+    // Release the holder when the owning component unmounts. Without this, the
+    // MT-side `_workletRefMap` grows monotonically across mount/unmount cycles
+    // (router-driven apps with frequent navigation hit this fastest).
+    // `onUnmounted` no-ops if called outside a component setup; callers that
+    // construct refs ad-hoc (e.g. tests) just won't get a release op, which is
+    // the same as today's behaviour.
+    onUnmounted(() => {
+        pushOp(OP.RELEASE_MT_REF, ref._wvid);
+        scheduleFlush();
+    });
+    return ref;
+}

package/dist/model-processor.js

@@ -0,0 +1,76 @@
+/**
+ * Platform-specific model processor for Lynx form elements.
+ *
+ * Wires sigx's `model={() => state.field}` two-way binding directive to
+ * Lynx's <input> and <textarea> elements. The processor runs at JSX
+ * creation time (called from runtime-core/jsx-runtime.ts when an
+ * intrinsic element has a `model` prop) and rewrites the props to:
+ *
+ *   1. Set the initial `value` from the bound state
+ *   2. Install a `bindinput` handler that pushes the new value back into state
+ *
+ * Lynx differs from DOM in two important ways:
+ *
+ *   - Lynx <input> fires `bindinput` with `event.detail.value` containing
+ *     the new text. There is no DOM-style `target.value` property — the
+ *     value lives on the event detail object.
+ *   - Lynx Go (and most current Lynx hosts) have no native checkbox or
+ *     radio elements. We only handle text-style <input> and <textarea>
+ *     here. Adding checkbox/radio later is straightforward — mirror the
+ *     branches in packages/runtime-dom/src/model-processor.ts.
+ *
+ * Mirrors packages/runtime-dom/src/model-processor.ts.
+ */
+import { setPlatformModelProcessor } from '@sigx/runtime-core/internals';
+setPlatformModelProcessor((type, props, [stateObj, key], _originalProps) => {
+    // Helper to set value — uses onUpdate handler if available (for props
+    // model forwarding through component boundaries).
+    const setValue = (v) => {
+        const updateHandler = stateObj[`onUpdate:${key}`];
+        if (typeof updateHandler === 'function') {
+            updateHandler(v);
+        }
+        else {
+            stateObj[key] = v;
+        }
+    };
+    // Text <input>
+    if (type === 'input') {
+        props.value = stateObj[key] ?? '';
+        const existingBindInput = props.bindinput;
+        props.bindinput = (e) => {
+            const v = e?.detail?.value ?? '';
+            setValue(v);
+            if (existingBindInput)
+                existingBindInput(e);
+        };
+        const existingHandler = props['onUpdate:modelValue'];
+        props['onUpdate:modelValue'] = (v) => {
+            setValue(v);
+            if (existingHandler)
+                existingHandler(v);
+        };
+        return true;
+    }
+    // <textarea>
+    if (type === 'textarea') {
+        props.value = stateObj[key] ?? '';
+        const existingBindInput = props.bindinput;
+        props.bindinput = (e) => {
+            const v = e?.detail?.value ?? '';
+            setValue(v);
+            if (existingBindInput)
+                existingBindInput(e);
+        };
+        const existingHandler = props['onUpdate:modelValue'];
+        props['onUpdate:modelValue'] = (v) => {
+            setValue(v);
+            if (existingHandler)
+                existingHandler(v);
+        };
+        return true;
+    }
+    // Not handled — fall back to the generic modelValue/onUpdate:modelValue
+    // pair so component-level model forwarding still works.
+    return false;
+});

package/dist/mt-hmr-bridge.js

@@ -1,58 +1,130 @@
-//#region src/mt-hmr-bridge.ts
-function e() {
-	let e = __webpack_require__?.c;
-	if (e) for (let t in e) {
-		if (!t.includes("@rspack") || !t.endsWith("emitter.js")) continue;
-		let n = e[t]?.exports;
-		if (n && typeof n.on == "function" && typeof n.emit == "function") return n;
-	}
+"use strict";
+/**
+ * BG → MT hot-update bridge.
+ *
+ * The MT bundle has rspack's HMR runtime in code (because `module.hot.accept`
+ * is referenced) but no transport feeding it updates. After a save, BG's HMR
+ * client patches App.tsx and re-renders, generating worklet placeholders with
+ * new content-hash `_wkltId`s. MT's `_workletMap` still holds the old IDs, so
+ * the lookup fails (`bind of undefined`) when the user taps.
+ *
+ * This bridge closes the gap. We hook the same `webpackHotUpdate` event the
+ * rspack HMR client subscribes to. On every cycle:
+ *   1. Fetch the matching `main__main-thread.<hash>.hot-update.js` over the
+ *      dev server URL (`__webpack_require__.p`).
+ *   2. Extract every `registerWorkletInternal(...)` call from the response.
+ *   3. Forward the concatenated calls to MT via
+ *      `callLepusMethod('sigxApplyMtHotUpdate', { code }, ...)`.
+ * The MT handler `eval`s them in the existing realm, registering the new IDs
+ * into the live `_workletMap` before the user taps a freshly re-rendered
+ * button.
+ *
+ * Loaded only in dev mode — wired into the BG entry by `lynx-plugin`'s
+ * `applyEntry` when `enabledHMR` is true.
+ */
+function findRspackEmitter() {
+    const cache = __webpack_require__?.c;
+    if (!cache)
+        return undefined;
+    for (const id in cache) {
+        if (!id.includes('@rspack') || !id.endsWith('emitter.js'))
+            continue;
+        const exp = cache[id]?.exports;
+        if (exp
+            && typeof exp.on === 'function'
+            && typeof exp.emit === 'function') {
+            return exp;
+        }
+    }
+    return undefined;
 }
+// Defer subscription via a microtask: the entry chain prepends this bridge
+// before `@rspack/core/hot/dev-server`, so at module-eval time the emitter
+// isn't in the webpack cache yet. By the next microtask, dev-server has run
+// its top-level code and the emitter module is cached.
 Promise.resolve().then(() => {
-	let n = e();
-	if (!n) {
-		console.log("[sigx-mt-hmr-bridge] rspack emitter not found — bridge inactive");
-		return;
-	}
-	n.on("webpackHotUpdate", () => {
-		t();
-	});
+    const emitter = findRspackEmitter();
+    if (!emitter) {
+        console.log('[sigx-mt-hmr-bridge] rspack emitter not found — bridge inactive');
+        return;
+    }
+    emitter.on('webpackHotUpdate', () => {
+        fetchAndForward();
+    });
 });
-function t() {
-	let e = __webpack_require__?.p ?? "", t = __webpack_require__?.hu;
-	if (typeof t != "function") return;
-	let r = e + t("main__main-thread"), i = lynx?.requireModuleAsync;
-	typeof i == "function" && i(r, (e, t) => {
-		if (e) {
-			console.log("[sigx-mt-hmr-bridge] requireModuleAsync failed:", String(e));
-			return;
-		}
-		let r = "";
-		for (let e in t.modules) {
-			let n = t.modules[e];
-			typeof n == "function" && (r += n.toString() + "\n");
-		}
-		let i = n(r);
-		if (!i) return;
-		let a = lynx?.getNativeApp?.();
-		!a || typeof a.callLepusMethod != "function" || a.callLepusMethod("sigxApplyMtHotUpdate", { code: i }, () => {});
-	});
+function fetchAndForward() {
+    // The `webpackHotUpdate` event payload is the *new* hash, but hot-update
+    // chunks are named with the *previous* hash (the "delta-from" hash). Use
+    // `__webpack_require__.hu` — same helper rspack's own loader uses — which
+    // reads `__webpack_require__.h()` to build the URL with the right hash.
+    const publicPath = __webpack_require__?.p ?? '';
+    const hu = __webpack_require__?.hu;
+    if (typeof hu !== 'function')
+        return;
+    const url = publicPath + hu('main__main-thread');
+    // Lynx's BG runtime doesn't have a working `fetch` for arbitrary URLs in
+    // many hosts; rspack's own HMR loader uses `lynx.requireModuleAsync` (see
+    // `loadUpdateChunk` in the BG bundle). It returns the parsed hot-update
+    // shape `{ modules, runtime }` — each `modules[id]` is the compiled JS
+    // factory function. We extract registerWorkletInternal calls from
+    // `factory.toString()` so we don't have to actually evaluate the factory
+    // (which would import worklet-runtime / install-hybrid into BG's webpack
+    // module graph, with unwanted side effects).
+    const requireModuleAsync = lynx?.requireModuleAsync;
+    if (typeof requireModuleAsync !== 'function')
+        return;
+    requireModuleAsync(url, (err, update) => {
+        if (err) {
+            console.log('[sigx-mt-hmr-bridge] requireModuleAsync failed:', String(err));
+            return;
+        }
+        let combined = '';
+        for (const id in update.modules) {
+            const factory = update.modules[id];
+            if (typeof factory === 'function')
+                combined += factory.toString() + '\n';
+        }
+        const code = extractRegistrations(combined);
+        if (!code)
+            return;
+        const app = lynx?.getNativeApp?.();
+        if (!app || typeof app.callLepusMethod !== 'function')
+            return;
+        app.callLepusMethod('sigxApplyMtHotUpdate', { code }, () => { });
+    });
 }
-function n(e) {
-	let t = [], n = 0;
-	for (;;) {
-		let r = e.indexOf("registerWorkletInternal(", n);
-		if (r === -1) break;
-		let i = 0, a = r + 24 - 1;
-		for (; a < e.length; a++) {
-			let t = e[a];
-			if (t === "(") i++;
-			else if (t === ")" && (i--, i === 0)) break;
-		}
-		let o = a + 1;
-		o < e.length && e[o] === ";" && o++, t.push(e.slice(r, o)), n = o;
-	}
-	return t.join("\n");
+/**
+ * Extract `registerWorkletInternal(...)` calls from a hot-update body.
+ *
+ * Mirrors `lynx-plugin/src/loaders/worklet-utils.ts:extractRegistrations`
+ * (duplicated here to avoid a runtime → build-time dep). Bracket-depth count
+ * handles nested braces in the function body.
+ */
+function extractRegistrations(source) {
+    const out = [];
+    const marker = 'registerWorkletInternal(';
+    let from = 0;
+    while (true) {
+        const idx = source.indexOf(marker, from);
+        if (idx === -1)
+            break;
+        let depth = 0;
+        let i = idx + marker.length - 1; // points at the opening '('
+        for (; i < source.length; i++) {
+            const ch = source[i];
+            if (ch === '(')
+                depth++;
+            else if (ch === ')') {
+                depth--;
+                if (depth === 0)
+                    break;
+            }
+        }
+        let end = i + 1;
+        if (end < source.length && source[end] === ';')
+            end++;
+        out.push(source.slice(idx, end));
+        from = end;
+    }
+    return out.join('\n');
 }
-//#endregion
-
-//# sourceMappingURL=mt-hmr-bridge.js.map

package/dist/native/gesture-detector.d.ts

@@ -16,7 +16,7 @@
  *     SET_MT_REF op (pushed during the first JSX render) is applied before
  *     the SET_GESTURE_DETECTOR op tries to resolve the workletRefMap entry.
  */
-import { MainThreadRef } from '../main-thread-ref';
+import { MainThreadRef } from '../main-thread-ref.js';
 export declare const GestureType: {
     readonly COMPOSED: -1;
     readonly PAN: 0;