@sigx/lynx-runtime-main 0.2.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Andreas Ekdahl
+
+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/README.md

@@ -0,0 +1,28 @@
+# @sigx/lynx-runtime-main
+
+Main-thread (Lepus) runtime for [SignalX](https://github.com/signalxjs) 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`](../lynx-plugin)) wires it into the main-thread bundle automatically.
+
+## 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.
+
+## 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

package/dist/animated-bridge-mt.d.ts

@@ -0,0 +1,77 @@
+/**
+ * MT-side SharedValue bridge — publishes MT-thread mutations to BG.
+ *
+ * Diffs every registered SharedValue against its last-published snapshot
+ * and dispatches one batched `Lynx.Sigx.AvPublish` event per flush boundary
+ * with the changed `[wvid, value]` tuples. The BG side ingests these via
+ * `@sigx/lynx-runtime/src/animated-bridge.ts` and writes them into the
+ * mirror signal so any sigx `effect` reading `sv.value` re-runs.
+ *
+ * Bridge state (`bridgedAvWvids` / `bridgedAvLastValues`) lives in
+ * `ops-apply.ts` because the BG→MT op handlers mutate it; this module
+ * imports the references and reads them on every flush.
+ *
+ * Two flush hook points:
+ *   1. `ops-apply.ts` calls `flushAvBridgePublishes()` at its tail (covers
+ *      every BG-driven ops batch).
+ *   2. `installAvBridgeFlushHook()` wraps `globalThis.__FlushElementTree`
+ *      so spontaneous MT writes (e.g. a touchmove worklet that eventually
+ *      calls `setStyleProperties`) also trigger a publish on the same
+ *      tick the native tree flushes. Called once from `entry-main.ts`
+ *      after PAPI globals are present.
+ *
+ * Coalescing: `===` per-wvid diff. Identical writes are filtered. N writes
+ * within one flush window collapse to one BG event with N entries.
+ */
+/**
+ * Diff registered AVs against their last-published snapshots; dispatch one
+ * batched `Lynx.Sigx.AvPublish` event with all changed tuples. No-op when
+ * the bridge set is empty or when nothing has changed since the last call.
+ */
+export declare function flushAvBridgePublishes(): void;
+/**
+ * Register a binding (called from the OP.REGISTER_AV_STYLE_BINDING op
+ * handler in `ops-apply.ts`). Initializes `lastValue` to a sentinel so the
+ * first flush always applies the mapper, even when the AV is at its initial.
+ */
+export declare function registerAnimatedStyleBinding(bindingId: number, elementWvid: number, avWvid: number, mapperName: string, params: unknown): void;
+export declare function unregisterAnimatedStyleBinding(bindingId: number): void;
+export declare function resetAnimatedStyleBindings(): void;
+export declare function animatedStyleBindingCount(): number;
+/**
+ * For each element with at least one *dirty* binding (AV value changed since
+ * the last apply), re-run **all** of that element's bindings, merge their
+ * mapper outputs, and apply the result with a single `setStyleProperties`
+ * call. Called from the wrapped `__FlushElementTree` *before* the native
+ * tree flush.
+ *
+ * Why "all bindings on a dirty element" rather than "only changed bindings":
+ *   - Multiple bindings on the same element can write the same style key
+ *     (e.g. `translateX` + `translateY` both produce `transform`). If we
+ *     applied only the changed ones, the unchanged-binding's contribution
+ *     would be lost and the element would visibly snap. By re-running every
+ *     binding on the dirty element and merging, all contributions land in
+ *     the same `setStyleProperties` call.
+ *
+ * Merge semantics:
+ *   - `transform` values from multiple bindings *concatenate* in registration
+ *     order (e.g. `translateX(50px)` + `translateY(20px)` ->
+ *     `translateX(50px) translateY(20px)`).
+ *   - All other keys merge by last-write-wins; a binding registered later on
+ *     the same element overwrites an earlier binding's same-key output.
+ *
+ * Skip cases (silent, by design):
+ *   - AV ref missing in `_workletRefMap` (race with unregister).
+ *   - Element ref's `current` is null (component not yet mounted, or
+ *     unmounted before the binding's UNREGISTER op landed).
+ *   - Mapper name not registered (typo or missing custom registration).
+ */
+export declare function flushAnimatedStyleBindings(): void;
+/**
+ * Wrap `globalThis.__FlushElementTree` once so every flush also runs the AV
+ * bridge publish step. Idempotent — safe to call across hot reloads. Test
+ * setups that `vi.stubGlobal('__FlushElementTree', ...)` AFTER this hook
+ * installs will replace our wrapper, which is the correct behavior for
+ * unit tests that drive `flushAvBridgePublishes` directly.
+ */
+export declare function installAvBridgeFlushHook(): void;

package/dist/animated-style-mappers.d.ts

@@ -0,0 +1,38 @@
+/**
+ * MT-side mapper registry for `useAnimatedStyle`.
+ *
+ * Maps a `SharedValue`'s current scalar to a partial style object that the
+ * binding flush passes to `setStyleProperties` on the bound element. Keyed by
+ * a string name (`'translateX'`, `'scale'`, ...) so the SWC worklet transform
+ * can capture the selection trivially: a string is a primitive `_c` value
+ * with no special lifting required (unlike arbitrary functions, which can't
+ * be captured into a worklet's closure).
+ *
+ * Custom mappers can be registered via `registerMapper(name, fn)` from MT
+ * code (e.g. a `'main thread'`-marked module body in a user app). BG-side
+ * `useAnimatedStyle` validates the name only against the type union; a
+ * lookup mismatch on MT is a silent no-op at flush time.
+ *
+ * Param shapes are mapper-specific. The `MapperParams` type in
+ * `@sigx/lynx-runtime-internal` is the single source of truth — both
+ * BG-side `useAnimatedStyle` and the MT runtime import it from there.
+ *
+ * Range mapping: `translateX` / `translateY` / `scale` / `opacity` accept
+ * either their linear `factor`/`offset` shape or a `RangeParams` shape
+ * (`{ inputRange, outputRange, extrapolate? }`). The mapper picks the branch
+ * by looking for `inputRange` on the params.
+ */
+import type { AnimatedStyleMapper } from '@sigx/lynx-runtime-internal';
+export type { MapperParams, BuiltinMapperName, AnimatedStyleMapper, RangeParams, } from '@sigx/lynx-runtime-internal';
+/**
+ * Look up a registered mapper by name. Returns `undefined` if the name
+ * isn't registered — the binding flush treats that as a no-op.
+ */
+export declare function lookupMapper(name: string): AnimatedStyleMapper | undefined;
+/**
+ * Register a custom MT-side mapper. Idempotent on (name, fn) — last
+ * registration wins for the same name. Intended for `'main thread'`-marked
+ * user modules that ship project-specific styling math.
+ */
+export declare function registerMapper(name: string, mapper: AnimatedStyleMapper): void;
+export declare function resetMappers(): void;

package/dist/element-registry.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Element registry — maps BG-thread ShadowElement IDs to Lynx Main Thread
+ * element handles.
+ */
+/** Map from BG-thread ShadowElement id to Lynx Main Thread element handle */
+export declare const elements: Map<number, MainThreadElement>;
+/**
+ * PAPI unique ID of the root PageElement.
+ * Passed as `parentComponentUniqueId` to element creation PAPI calls.
+ * `__SetCSSId` sets `css_style_sheet_manager_` directly on each element,
+ * so CSS rendering works without a ComponentElement ancestor.
+ */
+export declare let pageUniqueId: number;
+export declare function setPageUniqueId(id: number): void;