@sigx/lynx-runtime-main 0.4.0 → 0.4.2

package/dist/ops-apply.js

@@ -0,0 +1,449 @@
+/**
+ * Main Thread ops executor.
+ *
+ * Receives the flat-array ops buffer sent by the Background Thread via
+ * callLepusMethod('sigxPatchUpdate', { data: JSON.stringify(ops) }) and applies
+ * each operation using Lynx PAPI.
+ */
+import { OP } from '@sigx/lynx-runtime-internal';
+import { processGesture } from './upstream/processGesture.js';
+import { elements, pageUniqueId, setPageUniqueId, } from './element-registry.js';
+import { resetWorkletEvents } from './worklet-events.js';
+import { setSlotBgSign, setSlotWorklet, flushDirtySlots, resetSlotStates, } from './event-slots.js';
+import { flushAvBridgePublishes, flushAnimatedStyleBindings, registerAnimatedStyleBinding, unregisterAnimatedStyleBinding, resetAnimatedStyleBindings, } from './animated-bridge-mt.js';
+/**
+ * Placeholder element inserted by renderPage() to give the host a non-empty
+ * tree immediately, suppressing the "loadCard failed USER_RUNTIME_ERROR"
+ * timeout. Removed on the first applyOps() call.
+ */
+let placeholderParent = null;
+let placeholderEl = null;
+/**
+ * SharedValue bridge state — registered wvids and last-published snapshots.
+ * The op handlers (`OP.REGISTER_AV_BRIDGE` / `OP.UNREGISTER_AV_BRIDGE` below)
+ * mutate these collections; `animated-bridge-mt.ts:flushAvBridgePublishes`
+ * reads them on every flush boundary to compute the diff to publish to BG.
+ */
+export const bridgedAvWvids = new Set();
+export const bridgedAvLastValues = new Map();
+/**
+ * Gesture-detector tracking — per-element wvid → set of attached gesture ids.
+ * Used to drive the `has-react-gesture` setup attribute lifecycle: set on the
+ * first SET_GESTURE_DETECTOR for an element, cleared when the last gesture is
+ * removed via REMOVE_GESTURE_DETECTOR.
+ */
+const gesturesByElementWvid = new Map();
+/**
+ * Last-set BaseGesture tree per element wvid. Vendored upstream
+ * `processGesture` takes an `oldGesture` arg to diff against — pass the prior
+ * tree so callback updates wire correctly through `onWorkletCtxUpdate`.
+ */
+const lastTreeByElementWvid = new Map();
+/**
+ * elementWvid → elementId mapping populated by SET_MT_REF when a
+ * `main-thread:ref` binds to an element. Gesture ops carry the elRef's wvid
+ * (set at BG-side useGestureDetector time, before the renderer assigns an
+ * element id), so resolution is wvid → elementId → raw MainThreadElement.
+ *
+ * We deliberately do NOT use `lynxWorkletImpl._refImpl._workletRefMap[wvid].current`:
+ * that map stores the upstream-wrapped `Element` class (with `setStyleProperties`
+ * etc.) which is what worklets need, but the platform's `__SetAttribute` /
+ * `__SetGestureDetector` PAPI expect the raw RefCounted element handle.
+ * Passing the wrapper trips the `FiberSetAttribute param 0 should be RefCounted`
+ * native error.
+ */
+const elementIdByWvid = new Map();
+function resolveElementByWvid(wvid) {
+    const elementId = elementIdByWvid.get(wvid);
+    if (elementId === undefined)
+        return undefined;
+    return elements.get(elementId);
+}
+export function setPlaceholder(parent, el) {
+    placeholderParent = parent;
+    placeholderEl = el;
+}
+function removePlaceholderOnce() {
+    if (placeholderEl != null && placeholderParent != null) {
+        __RemoveElement(placeholderParent, placeholderEl);
+        placeholderParent = null;
+        placeholderEl = null;
+    }
+}
+/**
+ * Use typed PAPI creators for known element types.
+ * Native Lynx may set up type-specific internals (e.g. overflow clipping
+ * for View, hardware-accelerated decoding for Image) via the typed functions
+ * that the generic __CreateElement does not.
+ */
+function createTypedElement(type, parentComponentUniqueId) {
+    switch (type) {
+        case 'view':
+            return __CreateView(parentComponentUniqueId);
+        case 'text':
+            return __CreateText(parentComponentUniqueId);
+        case 'image':
+            return __CreateImage(parentComponentUniqueId);
+        case 'scroll-view':
+            return __CreateScrollView(parentComponentUniqueId);
+        case 'page':
+            // The page root is special — it's created once by __CreatePage() in
+            // renderPage() and aliased to ShadowElement id=1 in BG. Lynx hosts
+            // (e.g. Lynx Go) have no behavior class for a second `page` element
+            // and will throw "No BehaviorController defined for class page".
+            // If user code wraps content in <page>...</page>, treat it as a
+            // transparent <view> on the Main Thread so the tree stays valid.
+            return __CreateView(parentComponentUniqueId);
+        default:
+            return __CreateElement(type, parentComponentUniqueId);
+    }
+}
+export function applyOps(ops) {
+    const len = ops.length;
+    if (len === 0)
+        return;
+    // On the first real ops batch, remove the placeholder element that
+    // renderPage() inserted to suppress the host's USER_RUNTIME_ERROR timeout.
+    removePlaceholderOnce();
+    // Detect duplicate batch from double BG bundle evaluation.
+    // Each __init_card_bundle__ invocation gets a fresh webpack module cache, so
+    // ShadowElement.nextId resets to 2, producing the same element IDs.
+    // If the first CREATE op targets an ID that already exists in our elements Map,
+    // this is a duplicate batch — skip it entirely.
+    if (len >= 3 && ops[0] === OP.CREATE) {
+        const firstId = ops[1];
+        if (elements.has(firstId)) {
+            return;
+        }
+    }
+    let i = 0;
+    while (i < len) {
+        const code = ops[i++];
+        switch (code) {
+            case OP.CREATE: {
+                const id = ops[i++];
+                const type = ops[i++];
+                let el;
+                if (type === '__comment') {
+                    el = __CreateRawText('');
+                }
+                else {
+                    el = createTypedElement(type, pageUniqueId);
+                    __SetCSSId([el], 0);
+                }
+                elements.set(id, el);
+                if (type !== '__comment') {
+                    __SetAttribute(el, `sigx-ref-${id}`, 1);
+                }
+                break;
+            }
+            case OP.CREATE_TEXT: {
+                const id = ops[i++];
+                const el = __CreateText(pageUniqueId);
+                __SetCSSId([el], 0);
+                elements.set(id, el);
+                __SetAttribute(el, `sigx-ref-${id}`, 1);
+                break;
+            }
+            case OP.INSERT: {
+                const parentId = ops[i++];
+                const childId = ops[i++];
+                const anchorId = ops[i++];
+                const parent = elements.get(parentId);
+                const child = elements.get(childId);
+                if (parent && child) {
+                    if (anchorId === -1) {
+                        __AppendElement(parent, child);
+                    }
+                    else {
+                        const anchor = elements.get(anchorId);
+                        if (anchor)
+                            __InsertElementBefore(parent, child, anchor);
+                    }
+                }
+                break;
+            }
+            case OP.REMOVE: {
+                const _parentId = ops[i++];
+                const childId = ops[i++];
+                const parent = elements.get(_parentId);
+                const child = elements.get(childId);
+                if (parent && child) {
+                    __RemoveElement(parent, child);
+                }
+                break;
+            }
+            case OP.SET_PROP: {
+                const id = ops[i++];
+                const key = ops[i++];
+                const value = ops[i++];
+                const el = elements.get(id);
+                if (el)
+                    __SetAttribute(el, key, value);
+                break;
+            }
+            case OP.SET_TEXT: {
+                const id = ops[i++];
+                const text = ops[i++];
+                const el = elements.get(id);
+                if (el)
+                    __SetAttribute(el, 'text', text);
+                break;
+            }
+            case OP.SET_EVENT: {
+                const id = ops[i++];
+                const eventType = ops[i++];
+                const eventName = ops[i++];
+                const sign = ops[i++];
+                // Defer __AddEvent to flushDirtySlots (end of batch). When a worklet
+                // is also registered for the same slot, the slot machine combines
+                // them into a single hybrid registration.
+                setSlotBgSign(id, eventType, eventName, sign);
+                break;
+            }
+            case OP.REMOVE_EVENT: {
+                const id = ops[i++];
+                const eventType = ops[i++];
+                const eventName = ops[i++];
+                // Clear the BG side of this slot. The MT worklet (if any) survives.
+                // No worklet-removal op exists yet (see plan Open items).
+                setSlotBgSign(id, eventType, eventName, undefined);
+                break;
+            }
+            case OP.SET_STYLE: {
+                const id = ops[i++];
+                const value = ops[i++];
+                const el = elements.get(id);
+                if (el)
+                    __SetInlineStyles(el, value);
+                break;
+            }
+            case OP.SET_CLASS: {
+                const id = ops[i++];
+                const cls = ops[i++];
+                const el = elements.get(id);
+                if (el)
+                    __SetClasses(el, cls);
+                break;
+            }
+            case OP.SET_ID: {
+                const id = ops[i++];
+                const idStr = ops[i++];
+                const el = elements.get(id);
+                if (el)
+                    __SetID(el, idStr ?? undefined);
+                break;
+            }
+            case OP.SET_WORKLET_EVENT: {
+                const id = ops[i++];
+                const eventType = ops[i++];
+                const eventName = ops[i++];
+                const ctx = ops[i++];
+                if (ctx && ctx._wkltId) {
+                    ctx['_workletType'] = 'main-thread';
+                    // Defer __AddEvent — flushDirtySlots will pick the right shape:
+                    // worklet-only ({type:'worklet', value: ctx}) when no BG handler
+                    // shares this slot, or hybrid ctx when one does.
+                    setSlotWorklet(id, eventType, eventName, ctx);
+                }
+                break;
+            }
+            case OP.SET_MT_REF: {
+                const id = ops[i++];
+                const wvid = ops[i++];
+                const el = elements.get(id);
+                if (el) {
+                    // Delegate to upstream's worklet-runtime. updateWorkletRef wraps the
+                    // element in its own Element class and stores it under _wvid.
+                    const impl = globalThis['lynxWorkletImpl'];
+                    if (impl?._refImpl) {
+                        const refMap = impl._refImpl._workletRefMap;
+                        if (!(wvid in refMap)) {
+                            refMap[wvid] = { current: null, _wvid: wvid };
+                        }
+                        impl._refImpl.updateWorkletRef({ _wvid: wvid }, el);
+                    }
+                    // Record wvid → raw elementId so SET_GESTURE_DETECTOR can resolve
+                    // the unwrapped MainThreadElement for `__SetAttribute` /
+                    // `__SetGestureDetector` (which require RefCounted handles, not
+                    // upstream's Element wrapper).
+                    elementIdByWvid.set(wvid, id);
+                }
+                break;
+            }
+            case OP.INIT_MT_REF: {
+                const wvid = ops[i++];
+                const initValue = ops[i++];
+                const impl = globalThis['lynxWorkletImpl'];
+                if (impl?._refImpl) {
+                    const refMap = impl._refImpl._workletRefMap;
+                    if (!(wvid in refMap)) {
+                        refMap[wvid] = { current: initValue, _wvid: wvid };
+                    }
+                }
+                break;
+            }
+            case OP.RELEASE_MT_REF: {
+                // Owning component unmounted on BG; drop the MT-side holder so the
+                // worklet ref map doesn't grow unbounded across navigation. Mirrors
+                // upstream's WorkletEvents.releaseWorkletRef path (we don't dispatch
+                // upstream's event because we manage the map ourselves via ops).
+                const wvid = ops[i++];
+                const impl = globalThis['lynxWorkletImpl'];
+                if (impl?._refImpl) {
+                    delete impl._refImpl._workletRefMap[wvid];
+                }
+                elementIdByWvid.delete(wvid);
+                break;
+            }
+            case OP.REGISTER_AV_BRIDGE: {
+                const wvid = ops[i++];
+                const initValue = ops[i++];
+                bridgedAvWvids.add(wvid);
+                bridgedAvLastValues.set(wvid, initValue);
+                break;
+            }
+            case OP.UNREGISTER_AV_BRIDGE: {
+                const wvid = ops[i++];
+                bridgedAvWvids.delete(wvid);
+                bridgedAvLastValues.delete(wvid);
+                break;
+            }
+            case OP.REGISTER_AV_STYLE_BINDING: {
+                const bindingId = ops[i++];
+                const elementWvid = ops[i++];
+                const avWvid = ops[i++];
+                const mapperName = ops[i++];
+                const params = ops[i++];
+                registerAnimatedStyleBinding(bindingId, elementWvid, avWvid, mapperName, params);
+                break;
+            }
+            case OP.UNREGISTER_AV_STYLE_BINDING: {
+                const bindingId = ops[i++];
+                unregisterAnimatedStyleBinding(bindingId);
+                break;
+            }
+            case OP.SET_GESTURE_DETECTOR: {
+                // Wire format: [op, wvid, gestureId, type, config, relationMap].
+                // We reconstruct upstream's BaseGesture shape and delegate to vendored
+                // `processGesture` so the platform-call sequence is byte-for-byte
+                // identical to `@lynx-js/react`'s snapshot pipeline. Per-base wire
+                // means we register one base per op; processGesture handles the
+                // single-base fast path. Composed gestures arrive as multiple ops,
+                // each carrying its relationMap.
+                const elementWvid = ops[i++];
+                const gestureId = ops[i++];
+                const type = ops[i++];
+                const config = ops[i++];
+                const relationMap = ops[i++];
+                const el = resolveElementByWvid(elementWvid);
+                if (!el)
+                    break;
+                // Reconstruct callbacks Record from the wire's array shape.
+                const callbacksRecord = {};
+                for (const cb of config.callbacks) {
+                    callbacksRecord[cb.name] = cb.callback;
+                }
+                // Build a fake BaseGesture: relation arrays are id-stubs `[{id}]`
+                // because vendored `getGestureInfo` reads `.id` off each entry to
+                // produce the relationMap. The platform never sees these objects.
+                const stub = (ids) => ids.map((id) => ({ id }));
+                const fakeBaseGesture = {
+                    __isSerialized: true,
+                    type,
+                    id: gestureId,
+                    callbacks: callbacksRecord,
+                    waitFor: stub(relationMap.waitFor),
+                    simultaneousWith: stub(relationMap.simultaneous),
+                    continueWith: stub(relationMap.continueWith),
+                    ...(config.config ? { config: config.config } : {}),
+                };
+                // Phase 2.12.1 bug fix: pass `undefined` as oldGesture, NOT the last
+                // tree we saw on this element.
+                //
+                // Our wire format is one SET_GESTURE_DETECTOR op per BaseGesture.
+                // When `<Pressable>` registers `Simultaneous(Tap, LongPress)`, two
+                // ops arrive in sequence on the same element. If we pass the previous
+                // tree to `processGesture`, its diff path treats the second op as
+                // "Tap → LongPress" and emits a `__RemoveGestureDetector` for Tap
+                // before installing LongPress. Result: only the last gesture stays
+                // registered; all earlier gestures are silently uninstalled.
+                //
+                // The right model for our wire is additive: each op installs ONE
+                // gesture without disturbing siblings. Removal is explicit via the
+                // REMOVE_GESTURE_DETECTOR op (emitted from `useGestureDetector`'s
+                // unmount cleanup), which calls `__RemoveGestureDetector` directly.
+                // Note: this means we don't get diff-based callback updates if the
+                // BG side re-emits a gesture with the same id — but our wire never
+                // does that today; on prop changes BG emits REMOVE then SET.
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                processGesture(el, fakeBaseGesture, undefined, false);
+                lastTreeByElementWvid.set(elementWvid, fakeBaseGesture);
+                // Track for REMOVE op cleanup and to drive `has-react-gesture` toggle
+                // when the last gesture goes (vendored function clears it on remove).
+                let attached = gesturesByElementWvid.get(elementWvid);
+                if (!attached) {
+                    attached = new Set();
+                    gesturesByElementWvid.set(elementWvid, attached);
+                }
+                attached.add(gestureId);
+                break;
+            }
+            case OP.REMOVE_GESTURE_DETECTOR: {
+                const elementWvid = ops[i++];
+                const gestureId = ops[i++];
+                const el = resolveElementByWvid(elementWvid);
+                if (el && typeof __RemoveGestureDetector === 'function') {
+                    __RemoveGestureDetector(el, gestureId);
+                    const attached = gesturesByElementWvid.get(elementWvid);
+                    if (attached) {
+                        attached.delete(gestureId);
+                        if (attached.size === 0) {
+                            gesturesByElementWvid.delete(elementWvid);
+                            lastTreeByElementWvid.delete(elementWvid);
+                            __SetAttribute(el, 'has-react-gesture', null);
+                        }
+                    }
+                }
+                break;
+            }
+            default:
+                // Unknown op – skip (future-compat)
+                break;
+        }
+    }
+    // Commit deferred __AddEvent registrations now that the entire batch is
+    // processed — this is what lets worklet + BG handler on the same slot
+    // coexist via the hybrid worklet ctx, without one overwriting the other.
+    flushDirtySlots();
+    // Diff registered SharedValues against their last-published snapshots
+    // and dispatch a batched Lynx.Sigx.AvPublish event with anything that
+    // changed during this op batch. See animated-bridge-mt.ts for details.
+    flushAvBridgePublishes();
+    // Apply any useAnimatedStyle bindings whose source SharedValue changed
+    // during this batch. Runs after flushAvBridgePublishes so the BG mirror
+    // stays consistent with the styles we're about to commit.
+    flushAnimatedStyleBindings();
+    // Flush all pending PAPI changes to the native layer in one shot.
+    __FlushElementTree();
+}
+/** Reset module state — for testing and hot reload. */
+export function resetMainThreadState() {
+    elements.clear();
+    setPageUniqueId(1);
+    placeholderParent = null;
+    placeholderEl = null;
+    // Also defined in this module's imports — reset worklet state
+    resetWorkletEvents();
+    resetSlotStates();
+    bridgedAvWvids.clear();
+    bridgedAvLastValues.clear();
+    gesturesByElementWvid.clear();
+    lastTreeByElementWvid.clear();
+    elementIdByWvid.clear();
+    resetAnimatedStyleBindings();
+    // Clear upstream's worklet ref map too on hard reset (HMR / test).
+    const impl = globalThis['lynxWorkletImpl'];
+    if (impl?._refImpl)
+        impl._refImpl._workletRefMap = {};
+}

package/dist/run-on-background-mt.js

@@ -0,0 +1,91 @@
+/**
+ * MT-side runOnBackground — dispatches function calls from the Main Thread
+ * to the Background Thread via 'Lynx.Sigx.RunOnBackground' events.
+ *
+ * Called inside extracted worklet bodies on the Main Thread. The SWC LEPUS
+ * pass leaves bare `runOnBackground(_jsFnK)` references in the registered
+ * worklet body; we install this implementation as `globalThis.runOnBackground`
+ * from `entry-main.ts` so the bare identifier resolves at runtime.
+ *
+ * Mirrors @lynx-js/react/runtime/lib/worklet/call/runOnMainThread (the dual
+ * direction) and vue-lynx's run-on-background-mt.ts. Sigx-namespaced event
+ * types so we don't conflict with upstream's own bridge if it ships in the
+ * same lynx process.
+ */
+const RUN_ON_BACKGROUND = 'Lynx.Sigx.RunOnBackground';
+const FUNCTION_CALL_RET = 'Lynx.Sigx.FunctionCallRet';
+// ---------------------------------------------------------------------------
+// Return-value resolver — correlates resolveId → Promise resolve callback
+// ---------------------------------------------------------------------------
+let resolveMap;
+let nextResolveId = 1;
+function getJSContext() {
+    // On MT, `lynx` is a globalThis property (no closure injection like BG).
+    const lynxObj = globalThis.lynx;
+    return lynxObj?.getJSContext?.();
+}
+function initReturnListener() {
+    resolveMap = new Map();
+    getJSContext()?.addEventListener?.(FUNCTION_CALL_RET, (event) => {
+        let payload;
+        try {
+            payload = JSON.parse(event.data);
+        }
+        catch {
+            return;
+        }
+        const resolve = resolveMap?.get(payload.resolveId);
+        if (resolve) {
+            resolveMap.delete(payload.resolveId);
+            resolve(payload.returnValue);
+        }
+    });
+}
+// ---------------------------------------------------------------------------
+// dispatch — ship the call across to BG
+// ---------------------------------------------------------------------------
+function dispatch(fnId, params, execId, resolveId) {
+    getJSContext()?.dispatchEvent?.({
+        type: RUN_ON_BACKGROUND,
+        data: JSON.stringify({
+            obj: { _jsFnId: fnId, _execId: execId },
+            params,
+            resolveId,
+        }),
+    });
+}
+// ---------------------------------------------------------------------------
+// runOnBackground — the global function called in extracted LEPUS code
+// ---------------------------------------------------------------------------
+export function runOnBackground(handle) {
+    return (...params) => {
+        return new Promise((resolve) => {
+            if (!resolveMap)
+                initReturnListener();
+            const resolveId = nextResolveId++;
+            resolveMap.set(resolveId, resolve);
+            if (handle._isFirstScreen
+                && typeof lynxWorkletImpl !== 'undefined'
+                && lynxWorkletImpl?._runOnBackgroundDelayImpl) {
+                lynxWorkletImpl._runOnBackgroundDelayImpl.delayRunOnBackground(handle, (fnId, execId) => dispatch(fnId, params, execId, resolveId));
+                return;
+            }
+            if (handle._jsFnId == null || handle._execId == null) {
+                // Handle never carried a (fnId, execId) pair — most likely the BG
+                // sender did not call registerWorkletCtx. Resolve undefined so the
+                // worklet promise settles instead of leaking.
+                resolveMap.delete(resolveId);
+                resolve(undefined);
+                return;
+            }
+            dispatch(handle._jsFnId, params, handle._execId, resolveId);
+        });
+    };
+}
+// ---------------------------------------------------------------------------
+// Reset — for testing only
+// ---------------------------------------------------------------------------
+export function resetRunOnBackgroundMtState() {
+    resolveMap = undefined;
+    nextResolveId = 1;
+}

package/dist/upstream/observers.js

@@ -0,0 +1,39 @@
+// Copyright 2025 The Lynx Authors. All rights reserved.
+// TypeScript types added 2026 by SignalX contributors.
+//
+// Licensed under the Apache License, Version 2.0. The full license text and
+// upstream attribution are reproduced in `THIRD_PARTY_NOTICES.md` at the
+// root of this package (`@sigx/lynx-runtime-main`). The MIT LICENSE at the
+// repository root governs the rest of this repository; it does NOT apply
+// to this file.
+//
+// Vendored from `@lynx-js/react@0.120.0`'s
+// `runtime/lib/worklet-runtime/bindings/observers.js`. Source preserved
+// verbatim; only types added. We vendor this 15-LOC helper to drop the
+// `@lynx-js/react` runtime dependency from `@sigx/lynx-runtime-main`, which
+// in turn keeps `@types/react` out of the install tree of consumer apps
+// (sigx-lynx apps use sigx primitives, not ReactLynx JSX).
+function impl() {
+    return globalThis.lynxWorkletImpl;
+}
+/**
+ * Must be called when a worklet context is updated. Mirrors the upstream
+ * ReactLynx behaviour:
+ *   1. Register the new worklet with the JS-side lifecycle manager (so the
+ *      background thread can free it).
+ *   2. On first screen with a previous ctx, hydrate the new ctx from the old.
+ *   3. On first screen, flush any worklets that were delayed waiting for this
+ *      element (legacy dynamic-component compat path).
+ */
+export function onWorkletCtxUpdate(worklet, oldWorklet, isFirstScreen, element) {
+    const w = impl();
+    if (worklet._execId !== undefined) {
+        w?._jsFunctionLifecycleManager?.addRef(worklet._execId, worklet);
+    }
+    if (isFirstScreen && oldWorklet) {
+        w?._hydrateCtx(worklet, oldWorklet);
+    }
+    if (isFirstScreen) {
+        w?._eventDelayImpl.runDelayedWorklet(worklet, element);
+    }
+}