@sigx/lynx-runtime-main 0.4.0 → 0.4.2

package/dist/event-slots.js

@@ -0,0 +1,111 @@
+/**
+ * MT-side per-slot event registration state machine.
+ *
+ * Lynx native's `__AddEvent(el, eventType, eventName, value)` only stores ONE
+ * value per `(el, eventType, eventName)` slot — the second call wins. When
+ * sigx user code declares both a `main-thread-bind*` worklet AND a regular
+ * `bind*` BG handler on the same element, two ops arrive in the same patch
+ * batch (SET_WORKLET_EVENT + SET_EVENT). Calling `__AddEvent` eagerly per op
+ * means the second one silently overwrites the first.
+ *
+ * This module defers the `__AddEvent` call. Each op updates per-slot state
+ * (`worklet?`, `bgSign?`) and marks the slot dirty. After the entire op
+ * batch is processed (`flushDirtySlots` is called at the tail of `applyOps`),
+ * we issue ONE `__AddEvent` per dirty slot using whichever shape combines
+ * the present handlers — string sign, worklet ctx, or hybrid ctx.
+ *
+ * State persists across batches because re-renders may update only one of
+ * the two handlers (the BG event-registry already deduplicates SET_EVENT
+ * after the first registration, and `sentWorklets` deduplicates
+ * SET_WORKLET_EVENT by `_wkltId`).
+ */
+import { elements } from './element-registry.js';
+import { hybridCtx } from './hybrid-worklet.js';
+/** elementId → typeName ('bindEvent:tap' etc.) → slot state */
+const slotStates = new Map();
+/** Set of `${elementId}|${typeName}` keys that need __AddEvent re-issuing. */
+const dirtySlots = new Set();
+function getOrCreateSlot(elId, type, name) {
+    let perEl = slotStates.get(elId);
+    if (!perEl) {
+        perEl = new Map();
+        slotStates.set(elId, perEl);
+    }
+    const typeName = `${type}:${name}`;
+    let slot = perEl.get(typeName);
+    if (!slot) {
+        slot = {};
+        perEl.set(typeName, slot);
+    }
+    return slot;
+}
+function markDirty(elId, type, name) {
+    dirtySlots.add(`${elId}|${type}:${name}`);
+}
+export function setSlotWorklet(elId, type, name, ctx) {
+    const slot = getOrCreateSlot(elId, type, name);
+    slot.worklet = ctx;
+    markDirty(elId, type, name);
+}
+export function setSlotBgSign(elId, type, name, sign) {
+    const slot = getOrCreateSlot(elId, type, name);
+    slot.bgSign = sign;
+    markDirty(elId, type, name);
+}
+/**
+ * Pick the right __AddEvent value given which handlers are present.
+ * Returns `undefined` to mean "unregister this slot".
+ */
+function computeAddEventValue(slot) {
+    const { worklet, bgSign } = slot;
+    if (!worklet && !bgSign)
+        return undefined;
+    if (worklet && !bgSign) {
+        return { type: 'worklet', value: worklet };
+    }
+    if (!worklet && bgSign) {
+        return bgSign;
+    }
+    return { type: 'worklet', value: hybridCtx(worklet, bgSign) };
+}
+/**
+ * Commit __AddEvent for every slot that changed since the last flush.
+ * Called from `applyOps` after the op loop, before `__FlushElementTree()`.
+ */
+export function flushDirtySlots() {
+    for (const key of dirtySlots) {
+        const sep = key.indexOf('|');
+        const elId = Number(key.slice(0, sep));
+        const typeName = key.slice(sep + 1);
+        const colon = typeName.indexOf(':');
+        const type = typeName.slice(0, colon);
+        const name = typeName.slice(colon + 1);
+        const el = elements.get(elId);
+        if (!el)
+            continue;
+        const slot = slotStates.get(elId)?.get(typeName);
+        if (!slot)
+            continue;
+        const value = computeAddEventValue(slot);
+        if (sameRef(value, slot.installed))
+            continue;
+        // Lynx PAPI: undefined as the 4th arg unregisters.
+        __AddEvent(el, type, name, value);
+        slot.installed = value;
+    }
+    dirtySlots.clear();
+}
+function sameRef(a, b) {
+    // Reference equality is enough for our usage:
+    //  - undefined === undefined
+    //  - bgSign string deduplicated by event-registry, so identity stable
+    //  - worklet ctx is a fresh object per SET_WORKLET_EVENT op (never compared
+    //    to itself across batches because the prev value would always differ),
+    //    so this is mostly a defensive no-op for the first three branches.
+    return a === b;
+}
+/** Hot-reload / test reset hook — clears all slot state. */
+export function resetSlotStates() {
+    slotStates.clear();
+    dirtySlots.clear();
+}

package/dist/hybrid-worklet.d.ts

@@ -13,7 +13,7 @@
  * just invokes it, then bridges to BG via the `Lynx.Sigx.PublishEvent`
  * channel that `bg-bridge.ts` listens on.
  */
-import type { WorkletPlaceholder } from './worklet-events';
+import type { WorkletPlaceholder } from './worklet-events.js';
 export declare const HYBRID_WORKLET_ID = "__sigx_hybrid_dispatch__";
 /**
  * Install the hybrid worklet into upstream's worklet map. Must be called

package/dist/hybrid-worklet.js

@@ -0,0 +1,73 @@
+/**
+ * Hybrid worklet — combines a user worklet handler and a BG-side handler
+ * into a single registration that fits Lynx's one-handler-per-slot rule.
+ *
+ * Registered ONCE at MT init under the stable id `__sigx_hybrid_dispatch__`
+ * in upstream's `lynxWorkletImpl._workletMap`. When the slot machine sees a
+ * slot with both a worklet and a BG sign, it asks `hybridCtx(worklet, sign)`
+ * for the ctx to hand to `__AddEvent({ type: 'worklet', value })`.
+ *
+ * Lynx native dispatches via `runWorklet` → upstream's `transformWorklet`
+ * walks the ctx and `_c`. It detects nested `_wkltId` (our `realCtx`) and
+ * replaces it with the bound user-worklet callable. Our hybrid body then
+ * just invokes it, then bridges to BG via the `Lynx.Sigx.PublishEvent`
+ * channel that `bg-bridge.ts` listens on.
+ */
+export const HYBRID_WORKLET_ID = '__sigx_hybrid_dispatch__';
+function hybridDispatch(event) {
+    if (this._c.realCtx) {
+        try {
+            this._c.realCtx(event);
+        }
+        catch (e) {
+            console.log('[sigx-mt] hybrid worklet body threw:', String(e));
+        }
+    }
+    if (this._c.bgSign)
+        bridgeToBg(this._c.bgSign, event);
+}
+function bridgeToBg(sign, event) {
+    const lynxObj = globalThis.lynx;
+    if (!lynxObj) {
+        console.log('[sigx-mt] bridgeToBg: globalThis.lynx is undefined');
+        return;
+    }
+    const ctx = lynxObj.getJSContext?.();
+    if (!ctx) {
+        console.log('[sigx-mt] bridgeToBg: lynx.getJSContext() returned', typeof ctx);
+        return;
+    }
+    if (!ctx.dispatchEvent) {
+        console.log('[sigx-mt] bridgeToBg: jsContext has no dispatchEvent', Object.keys(ctx).join(','));
+        return;
+    }
+    let data;
+    try {
+        data = JSON.stringify({ sign, event });
+    }
+    catch (e) {
+        console.log('[sigx-mt] bridgeToBg: JSON.stringify failed', String(e));
+        return;
+    }
+    console.log('[sigx-mt] bridgeToBg: dispatching to BG, sign=', sign);
+    ctx.dispatchEvent({ type: 'Lynx.Sigx.PublishEvent', data });
+}
+/**
+ * Install the hybrid worklet into upstream's worklet map. Must be called
+ * AFTER the @lynx-js/react/worklet-runtime IIFE has populated
+ * globalThis.lynxWorkletImpl. Idempotent — safe to call across hot reloads.
+ */
+export function installHybridWorklet() {
+    const impl = globalThis
+        .lynxWorkletImpl;
+    if (impl)
+        impl._workletMap[HYBRID_WORKLET_ID] = hybridDispatch;
+}
+/** Build the ctx for a hybrid registration. */
+export function hybridCtx(realCtx, bgSign) {
+    return {
+        _wkltId: HYBRID_WORKLET_ID,
+        _workletType: 'main-thread',
+        _c: { realCtx, bgSign },
+    };
+}

package/dist/index.d.ts

@@ -1,10 +1,10 @@
-import './entry-main';
-export { elements, pageUniqueId, setPageUniqueId } from './element-registry';
-export { applyOps, resetMainThreadState } from './ops-apply';
-export { MTElementWrapper } from './mt-element';
-export { invokeWorklet, type WorkletPlaceholder } from './worklet-events';
-export { setSlotWorklet, setSlotBgSign, flushDirtySlots, resetSlotStates, } from './event-slots';
-export { HYBRID_WORKLET_ID, hybridCtx, installHybridWorklet, } from './hybrid-worklet';
+import './entry-main.js';
+export { elements, pageUniqueId, setPageUniqueId } from './element-registry.js';
+export { applyOps, resetMainThreadState } from './ops-apply.js';
+export { MTElementWrapper } from './mt-element.js';
+export { invokeWorklet, type WorkletPlaceholder } from './worklet-events.js';
+export { setSlotWorklet, setSlotBgSign, flushDirtySlots, resetSlotStates, } from './event-slots.js';
+export { HYBRID_WORKLET_ID, hybridCtx, installHybridWorklet, } from './hybrid-worklet.js';
 /**
  * Compatibility shim — upstream's worklet-runtime provides the canonical
  * `loadWorkletRuntime`, but @lynx-js/react/transform's LEPUS output imports

package/dist/index.js

@@ -1,64 +1,23 @@
-import { a as e, c as t, i as n, l as r, n as i, o as a, r as o, s, t as c, u as l } from "./entry-main-CBM2DHsU.js";
-import { n as u, r as d, t as f } from "./hybrid-worklet-nTcCh-mA.js";
-//#region src/mt-element.ts
-var p = !1, m = class e {
-	_el;
-	constructor(e) {
-		this._el = e;
-	}
-	flushElementTree() {
-		p || (p = !0, Promise.resolve().then(() => {
-			p = !1, __FlushElementTree();
-		}));
-	}
-	setStyleProperties(e) {
-		__SetInlineStyles(this._el, e), this.flushElementTree();
-	}
-	getComputedStyleProperty(e) {
-		return typeof __GetComputedStyleByKey == "function" ? __GetComputedStyleByKey(this._el, e) : "";
-	}
-	getAttribute(e) {
-		if (typeof __GetAttributeByName == "function") return __GetAttributeByName(this._el, e);
-	}
-	getAttributeNames() {
-		return typeof __GetAttributeNames == "function" ? __GetAttributeNames(this._el) : [];
-	}
-	querySelector(t) {
-		if (typeof __QuerySelector != "function") return null;
-		let n = __QuerySelector(this._el, t, {});
-		return n ? new e(n) : null;
-	}
-	querySelectorAll(t) {
-		return typeof __QuerySelectorAll == "function" ? __QuerySelectorAll(this._el, t, {}).map((t) => new e(t)) : [];
-	}
-	invoke(e, t) {
-		return new Promise((n, r) => {
-			if (typeof __InvokeUIMethod != "function") {
-				r(/* @__PURE__ */ Error("UI method invoke: __InvokeUIMethod not available"));
-				return;
-			}
-			__InvokeUIMethod(this._el, e, t ?? {}, (e) => {
-				e.code === 0 ? n(e.data) : r(/* @__PURE__ */ Error("UI method invoke: " + JSON.stringify(e)));
-			}), this.flushElementTree();
-		});
-	}
-	animate(e, t = {}) {
-		let n = this._el;
-		return typeof n.animate == "function" ? n.animate(e, t) : null;
-	}
-	setAttribute(e, t) {
-		__SetAttribute(this._el, e, t), this.flushElementTree();
-	}
-	setStyleProperty(e, t) {
-		__AddInlineStyle(this._el, e, t), this.flushElementTree();
-	}
-};
-//#endregion
-//#region src/index.ts
-function h(e) {
-	return !0;
+/// <reference path="./shims.d.ts" />
+// Side-effect import — entry-main.ts registers globalThis.renderPage /
+// processData / sigxPatchUpdate / sigxRunOnMT and side-effect imports
+// @lynx-js/react/worklet-runtime which installs lynxWorkletImpl /
+// registerWorkletInternal / runWorklet. Must run at module load time so
+// the main-thread entry of the Lynx template has these globals.
+import './entry-main.js';
+export { elements, pageUniqueId, setPageUniqueId } from './element-registry.js';
+export { applyOps, resetMainThreadState } from './ops-apply.js';
+export { MTElementWrapper } from './mt-element.js';
+export { invokeWorklet } from './worklet-events.js';
+export { setSlotWorklet, setSlotBgSign, flushDirtySlots, resetSlotStates, } from './event-slots.js';
+export { HYBRID_WORKLET_ID, hybridCtx, installHybridWorklet, } from './hybrid-worklet.js';
+/**
+ * Compatibility shim — upstream's worklet-runtime provides the canonical
+ * `loadWorkletRuntime`, but @lynx-js/react/transform's LEPUS output imports
+ * it from `runtimePkg`. Our MT loader strips the import + gating before
+ * shipping registrations, so this re-export is only for the rare case where
+ * upstream's raw output is used unstripped (tests, future Phase 1c).
+ */
+export function loadWorkletRuntime(_globDynamicComponentEntry) {
+    return true;
 }
-//#endregion
-export { f as HYBRID_WORKLET_ID, m as MTElementWrapper, c as applyOps, t as elements, o as flushDirtySlots, u as hybridCtx, d as installHybridWorklet, s as invokeWorklet, h as loadWorkletRuntime, r as pageUniqueId, i as resetMainThreadState, n as resetSlotStates, l as setPageUniqueId, e as setSlotBgSign, a as setSlotWorklet };
-
-//# sourceMappingURL=index.js.map

package/dist/install-hybrid-worklet.js

@@ -1,6 +1,19 @@
-import { r as e } from "./hybrid-worklet-nTcCh-mA.js";
-//#region src/install-hybrid-worklet.ts
-e();
-//#endregion
-
-//# sourceMappingURL=install-hybrid-worklet.js.map
+/**
+ * Side-effect module that installs the hybrid worklet into upstream's
+ * `lynxWorkletImpl._workletMap`.
+ *
+ * Must be loaded AFTER `@lynx-js/react/worklet-runtime` (which populates
+ * `lynxWorkletImpl`) but BEFORE user code runs. The MT bootstrap preamble
+ * in `lynx-plugin/src/loaders/worklet-loader-mt.ts` lists it third in the
+ * import order:
+ *
+ *   1. @sigx/lynx-runtime-main/entry-main      (sets SystemInfo + globals)
+ *   2. @lynx-js/react/worklet-runtime          (installs lynxWorkletImpl)
+ *   3. @sigx/lynx-runtime-main/install-hybrid  (this file)
+ *   4. user code                                (calls registerWorkletInternal)
+ *
+ * Splitting this out is necessary because vite would otherwise hoist any
+ * bare `import` statement above whatever sets up its prerequisites.
+ */
+import { installHybridWorklet } from './hybrid-worklet.js';
+installHybridWorklet();

package/dist/mt-element.js

@@ -0,0 +1,203 @@
+/**
+ * MainThread element wrapper — provides a high-level API over raw PAPI
+ * element handles for use in main-thread event handlers.
+ *
+ * When a MainThreadRef's `.current` is set, it receives one of these
+ * wrappers so user code can call:
+ *   - setStyleProperties({ transform: '...' })
+ *   - getComputedStyleProperty('width')
+ *   - animate(keyframes, options)
+ *
+ * These methods call Lynx PAPI directly on the main thread — no cross-thread
+ * round-trip, enabling zero-latency UI updates.
+ */
+// ---------------------------------------------------------------------------
+// MTElementWrapper
+// ---------------------------------------------------------------------------
+/**
+ * Module-level latch that microtask-debounces `__FlushElementTree()` across
+ * every MTElementWrapper write within a single microtask. Mirrors the
+ * pattern in upstream `@lynx-js/react`'s `Element` class
+ * (`runtime/lib/worklet-runtime/api/element.js`):
+ *
+ *   - First write in a microtask: schedule one Promise-microtask to flush.
+ *   - Subsequent writes (same wrapper or any other) before the microtask
+ *     fires: no-op (`willFlush` is already `true`).
+ *   - Microtask runs: clear the latch, call the (animated-bridge-wrapped)
+ *     `__FlushElementTree()` exactly once.
+ *
+ * Why the latch is module-level, not per-instance: a single tick often
+ * touches multiple element wrappers (e.g. `<Draggable>` writes its own
+ * transform AND issues `scrollBy` on the parent `<scroll-view>`). Two
+ * wrappers, two writes, but the native flush is a tree-wide operation —
+ * coalescing them into one is the whole point.
+ *
+ * Without this debounce, each of `setStyleProperties` / `setStyleProperty`
+ * / `setAttribute` / `invoke` was firing a synchronous
+ * `__FlushElementTree()`, paying the full layout pass per-call. The
+ * stutter showed up most obviously in the `<Draggable edgeScroll>` rAF
+ * tick (one transform write + one scrollBy invoke = 2 flushes/frame).
+ */
+let willFlush = false;
+export class MTElementWrapper {
+    /** The raw PAPI element handle. */
+    _el;
+    constructor(el) {
+        this._el = el;
+    }
+    /**
+     * Coalesce multiple element writes into a single `__FlushElementTree()`
+     * call at the end of the current microtask. See `willFlush` doc for the
+     * full rationale; mirrors `Element.flushElementTree` in upstream
+     * `@lynx-js/react`.
+     *
+     * `__FlushElementTree` itself is wrapped by `animated-bridge-mt` to
+     * apply pending `useAnimatedStyle` bindings before the native flush, so
+     * the debounce automatically coalesces SV-binding application too.
+     */
+    flushElementTree() {
+        if (willFlush)
+            return;
+        willFlush = true;
+        void Promise.resolve().then(() => {
+            willFlush = false;
+            __FlushElementTree();
+        });
+    }
+    /**
+     * Synchronously update inline styles on this element.
+     * This bypasses the BG→MT op queue — styles are applied immediately
+     * on the main thread, making it ideal for scroll-driven animations.
+     *
+     * The native `__FlushElementTree` call is microtask-debounced (see
+     * `flushElementTree`), so chaining multiple writes within one tick
+     * pays for a single flush instead of one per call.
+     *
+     * @example
+     * ```ts
+     * ref.current?.setStyleProperties({
+     *   transform: `translateX(${offset}px)`,
+     *   opacity: `${1 - ratio}`,
+     * });
+     * ```
+     */
+    setStyleProperties(styles) {
+        __SetInlineStyles(this._el, styles);
+        this.flushElementTree();
+    }
+    /**
+     * Get a computed style property value from this element.
+     *
+     * @param name - CSS property name in kebab-case (e.g. 'background-color')
+     * @returns The computed value as a string
+     */
+    getComputedStyleProperty(name) {
+        if (typeof __GetComputedStyleByKey === 'function') {
+            return __GetComputedStyleByKey(this._el, name);
+        }
+        return '';
+    }
+    /**
+     * Get a single attribute value by name. Returns the value as set via
+     * `setAttribute` (or by a parent component); does not resolve aliases.
+     */
+    getAttribute(name) {
+        if (typeof __GetAttributeByName === 'function') {
+            return __GetAttributeByName(this._el, name);
+        }
+        return undefined;
+    }
+    /**
+     * Get the list of attribute names currently set on this element.
+     */
+    getAttributeNames() {
+        if (typeof __GetAttributeNames === 'function') {
+            return __GetAttributeNames(this._el);
+        }
+        return [];
+    }
+    /**
+     * Find the first descendant element matching the CSS selector.
+     * Mirrors `Element.prototype.querySelector` from the DOM.
+     *
+     * Returns `null` when no match is found OR when the host runtime does not
+     * provide `__QuerySelector` (older Lynx SDKs).
+     */
+    querySelector(selector) {
+        if (typeof __QuerySelector !== 'function')
+            return null;
+        const ref = __QuerySelector(this._el, selector, {});
+        return ref ? new MTElementWrapper(ref) : null;
+    }
+    /**
+     * Find every descendant element matching the CSS selector. Returns an empty
+     * array when nothing matches OR when the host runtime does not provide
+     * `__QuerySelectorAll`.
+     */
+    querySelectorAll(selector) {
+        if (typeof __QuerySelectorAll !== 'function')
+            return [];
+        return __QuerySelectorAll(this._el, selector, {})
+            .map((el) => new MTElementWrapper(el));
+    }
+    /**
+     * Invoke a UI method exposed by the underlying native element (e.g.
+     * `scrollIntoView` on `<scroll-view>`, `scrollToIndex` on `<list>`).
+     *
+     * Resolves with the method's `data` payload on success (`code === 0`);
+     * rejects with an Error containing the JSON-stringified response otherwise.
+     */
+    invoke(methodName, params) {
+        return new Promise((resolve, reject) => {
+            if (typeof __InvokeUIMethod !== 'function') {
+                reject(new Error('UI method invoke: __InvokeUIMethod not available'));
+                return;
+            }
+            __InvokeUIMethod(this._el, methodName, params ?? {}, (res) => {
+                if (res.code === 0)
+                    resolve(res.data);
+                else
+                    reject(new Error('UI method invoke: ' + JSON.stringify(res)));
+            });
+            this.flushElementTree();
+        });
+    }
+    /**
+     * Start a keyframe animation on this element using the Lynx animation API.
+     *
+     * @param keyframes - Array of keyframe objects
+     * @param options - Animation configuration
+     * @returns Animation controller with play/pause/cancel methods
+     *
+     * @example
+     * ```ts
+     * ref.current?.animate(
+     *   [{ opacity: 0 }, { opacity: 1 }],
+     *   { duration: 300, easing: 'ease-in-out' }
+     * );
+     * ```
+     */
+    animate(keyframes, options = {}) {
+        const el = this._el;
+        if (typeof el.animate === 'function') {
+            return el.animate(keyframes, options);
+        }
+        return null;
+    }
+    /**
+     * Set a single attribute on this element. Microtask-debounced flush —
+     * see `flushElementTree`.
+     */
+    setAttribute(key, value) {
+        __SetAttribute(this._el, key, value);
+        this.flushElementTree();
+    }
+    /**
+     * Set a single inline style property. Microtask-debounced flush — see
+     * `flushElementTree`.
+     */
+    setStyleProperty(name, value) {
+        __AddInlineStyle(this._el, name, value);
+        this.flushElementTree();
+    }
+}