@sigx/lynx-runtime-main

Main-thread (Lepus) runtime for SignalX on Lynx. Receives the op stream from @sigx/lynx-runtime, mutates the native render tree via Lynx PAPI, and runs 'main thread'-marked worklets at the host's display refresh rate.

Application code rarely imports from this package directly. The build pipeline (@sigx/lynx-plugin) wires it into the main-thread bundle automatically.

📚 Documentation

Full guides, API reference and live examples → https://sigx.dev/lynx/modules/runtime-main/overview/

Responsibilities

• entry-main.ts — installs globalThis.processData, renderPage, updatePage, sigxPatchUpdate, sigxRunOnMT, and runOnBackground. This is the file the build plugin lists as the first import in the MT bundle so the Lynx runtime finds the global hooks it expects.
• ops-apply.ts — the applyOps loop that consumes the BG → MT op stream (CREATE, INSERT, SET_STYLE, SET_WORKLET_EVENT, INIT_MT_REF, REGISTER_AV_BRIDGE, ...) and translates them into PAPI calls (__CreatePage, __SetInlineStyles, __AddEvent, etc.).
• MTElementWrapper — high-level wrapper your worklets drive via mainThreadRef.current.method(...) (setStyleProperties, getComputedStyleProperty, animate, invoke, query selectors).
• Hybrid worklet dispatch — the slot machine in event-slots.ts plus the hybrid context in hybrid-worklet.ts lets a single MT slot carry both a worklet handler and a BG-side handler for the same event, dispatching to both.
• AnimatedValue bridge — animated-bridge-mt.ts diffs registered AVs against last-published snapshots and dispatches batched Lynx.Sigx.AvPublish events to BG once per __FlushElementTree boundary. The matching BG sink lives in @sigx/lynx-runtime.
• useAnimatedStyle mapper registry — animated-style-mappers.ts ships built-in mappers (translateX, scale, opacity, ...) and exposes registerMapper(name, fn) so MT-side code can add custom ones.
• Snapshot runtime — snapshot-mt.ts (#620) instantiates compiled snapshot templates on the MT: lazy ensureElements() (staged records until first materialization), hole patching through each template's update[i], synthetic negative ids feeding the same event-slot/ref machinery as op-built elements, and the hole-updater hooks installed into @sigx/lynx-runtime-internal/snapshot at bootstrap. No production callers yet — the wire protocol and the transform arrive in later #620 phases.
• mt-ref-bind.ts — MainThreadRef → element binding (upstream ref map + web style fallback + the wvid → elementId record), shared by the SET_MT_REF op and the snapshot runtime.

Bootstrap order

Three modules must evaluate in this order on the MT thread:

1. entry-main — sets globalThis.SystemInfo and the renderer hooks.
2. @lynx-js/react/worklet-runtime — installs lynxWorkletImpl, registerWorkletInternal, runWorklet.
3. install-hybrid-worklet — registers the hybrid dispatcher into the now-populated worklet map.

@sigx/lynx-plugin prepends side-effect imports for these three at the top of every file in the MT bundle, so the order is enforced regardless of which user file the Lynx runtime evaluates first.

License

MIT