@sigx/lynx-runtime 0.4.3 → 0.4.5

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

@@ -5,6 +5,16 @@ import type { SharedValue } from './shared-value.js';
 export type { BuiltinMapperName, MapperParams };
 /** Reset hook for tests. */
 export declare function resetAnimatedStyleBindingIds(): void;
+/**
+ * Reactive binding spec — the `{ sv, mapperName, params }` triple an accessor
+ * returns to describe the binding that should currently be live, or `null`
+ * for "no binding right now".
+ */
+export interface AnimatedStyleSpec {
+    sv: SharedValue<unknown>;
+    mapperName: BuiltinMapperName;
+    params?: MapperParams[BuiltinMapperName];
+}
 /**
  * Bind a `MainThreadRef`'s element style to a `SharedValue` via a named
  * mapper. The MT-side runtime applies the mapper's output via
@@ -23,7 +33,24 @@ export declare function resetAnimatedStyleBindingIds(): void;
  * ALL of that element's bindings re-run so partial outputs don't drop the
  * unchanged-axis contribution.
  *
- * @example Ghost follower at 0.5×
+ * Two call shapes:
+ *
+ *  - **Static** `useAnimatedStyle(ref, sv, mapperName, params)` — registers the
+ *    binding once at setup and unregisters at unmount. Use this when the
+ *    binding never changes for the element's lifetime (the common case:
+ *    Draggable, Swipeable, drawer offsets, …).
+ *
+ *  - **Reactive** `useAnimatedStyle(ref, () => spec | null)` — runs the
+ *    accessor in an `effect` and (re)binds whenever the returned spec changes,
+ *    or unbinds when it returns `null`. The binding always targets the *same*
+ *    element, so the host element (and its subtree) stays mounted across
+ *    rebinds. Use this when a single element transitions between animation
+ *    states at runtime — e.g. a navigator layer that animates during a
+ *    transition then settles to a static rest position. Re-binding on the
+ *    same element is what lets `<Stack>` avoid remounting screens per
+ *    animation phase (see `lynx-navigation`'s `<Layer>`).
+ *
+ * @example Ghost follower at 0.5× (static)
  * ```tsx
  * const tx = useSharedValue(0);
  * const ghostRef = useMainThreadRef<MainThread.Element | null>(null);
@@ -33,5 +60,16 @@ export declare function resetAnimatedStyleBindingIds(): void;
  * <Draggable translateX={tx} />
  * <view main-thread:ref={ghostRef} style={...} />
  * ```
+ *
+ * @example Animate-then-rest, no remount (reactive)
+ * ```tsx
+ * useAnimatedStyle(ref, () =>
+ *   props.animation
+ *     ? { sv: props.animation.progress, mapperName: props.animation.axis,
+ *         params: { inputRange: [...], outputRange: [...] } }
+ *     : null,
+ * );
+ * ```
  */
 export declare function useAnimatedStyle<N extends BuiltinMapperName>(elRef: MainThreadRef<MainThread.Element | null>, sv: SharedValue<unknown>, mapperName: N, params?: MapperParams[N]): void;
+export declare function useAnimatedStyle(elRef: MainThreadRef<MainThread.Element | null>, spec: () => AnimatedStyleSpec | null): void;

package/dist/animated/use-animated-style.js

@@ -1,4 +1,5 @@
 import { onUnmounted } from '@sigx/runtime-core';
+import { effect } from '@sigx/reactivity';
 import { pushOp, scheduleFlush } from '../op-queue.js';
 import { OP } from '@sigx/lynx-runtime-internal';
 let nextBindingId = 1;
@@ -14,35 +15,31 @@ function allocBindingId() {
     return nextBindingId++;
 }
 /**
- * Bind a `MainThreadRef`'s element style to a `SharedValue` via a named
- * mapper. The MT-side runtime applies the mapper's output via
- * `setStyleProperties` on every flush boundary where the SharedValue's value changed.
- *
- * The mapper runs on the **Main Thread** with no thread crossing per frame —
- * the only inputs are the SharedValue's value (already on MT) and the `params` shipped
- * once in the registration op. Because mappers are looked up by *name*, the
- * SWC worklet transform doesn't have to capture a function reference (which
- * it can't), so this fits the existing worklet pipeline cleanly.
- *
- * Multiple bindings on the same element compose into a single
- * `setStyleProperties` call per flush. `transform` outputs concatenate in
- * registration order (e.g. `translateX(50px) translateY(20px)`); other style
- * keys merge by last-write-wins. When ANY binding on an element is dirty,
- * ALL of that element's bindings re-run so partial outputs don't drop the
- * unchanged-axis contribution.
- *
- * @example Ghost follower at 0.5×
- * ```tsx
- * const tx = useSharedValue(0);
- * const ghostRef = useMainThreadRef<MainThread.Element | null>(null);
- *
- * useAnimatedStyle(ghostRef, tx, 'translateX', { factor: 0.5 });
- *
- * <Draggable translateX={tx} />
- * <view main-thread:ref={ghostRef} style={...} />
- * ```
+ * Stable identity for a spec so the reactive binder can tell "same binding,
+ * different object instance" (no-op) from "actually changed" (rebind). The
+ * SharedValue's `_wvid` plus the mapper name + JSON-serialized params uniquely
+ * pin the binding the MT side would register.
  */
-export function useAnimatedStyle(elRef, sv, mapperName, params) {
+function specSignature(cfg) {
+    if (!cfg)
+        return 'none';
+    let p = '';
+    try {
+        p = cfg.params == null ? '' : JSON.stringify(cfg.params);
+    }
+    catch {
+        p = '';
+    }
+    return `${cfg.mapperName}:${cfg.sv._wvid}:${p}`;
+}
+export function useAnimatedStyle(elRef, svOrSpec, mapperName, params) {
+    // Reactive form: drive register/unregister from an effect on the accessor.
+    if (typeof svOrSpec === 'function') {
+        bindReactiveAnimatedStyle(elRef, svOrSpec);
+        return;
+    }
+    // Static form (unchanged): register once, unregister at unmount.
+    const sv = svOrSpec;
     const bindingId = allocBindingId();
     pushOp(OP.REGISTER_AV_STYLE_BINDING, bindingId, elRef._wvid, sv._wvid, mapperName, params ?? null);
     scheduleFlush();
@@ -51,3 +48,51 @@ export function useAnimatedStyle(elRef, sv, mapperName, params) {
         scheduleFlush();
     });
 }
+/**
+ * Reactive-binding implementation. Runs `accessor` in an `effect`; when the
+ * resulting spec's *signature* changes, unregisters the previous binding (if
+ * any) and registers the new one against the same element. A `null` spec means
+ * "no binding right now" — the element keeps the last style the MT applied
+ * (mappers are not reset on unregister), which for transition transforms is the
+ * resting identity transform.
+ *
+ * The signature dedupe is load-bearing: callers typically build a *fresh* spec
+ * object on every render (e.g. `computeLayers` in `<Stack>`), so the accessor's
+ * return value changes identity every render even when the logical binding is
+ * unchanged. Without the dedupe the binding would thrash register/unregister on
+ * every progress-driven re-render.
+ *
+ * Ordering note: we `scheduleFlush()` (microtask-deferred), never `flushNow()`,
+ * so the REGISTER op lands on the same channel and ordering the static form
+ * uses — preserving the "bindings register → SV resets inside the worklet →
+ * withTiming starts" sequence the navigator relies on.
+ */
+function bindReactiveAnimatedStyle(elRef, accessor) {
+    let bindingId = null;
+    let sig = null;
+    const runner = effect(() => {
+        const cfg = accessor();
+        const nextSig = specSignature(cfg);
+        if (nextSig === sig)
+            return;
+        sig = nextSig;
+        if (bindingId !== null) {
+            pushOp(OP.UNREGISTER_AV_STYLE_BINDING, bindingId);
+            bindingId = null;
+        }
+        if (cfg) {
+            const id = allocBindingId();
+            bindingId = id;
+            pushOp(OP.REGISTER_AV_STYLE_BINDING, id, elRef._wvid, cfg.sv._wvid, cfg.mapperName, cfg.params ?? null);
+        }
+        scheduleFlush();
+    });
+    onUnmounted(() => {
+        runner.stop();
+        if (bindingId !== null) {
+            pushOp(OP.UNREGISTER_AV_STYLE_BINDING, bindingId);
+            bindingId = null;
+            scheduleFlush();
+        }
+    });
+}

package/dist/index.d.ts

@@ -18,6 +18,7 @@ export { registerBgSink, unregisterBgSink, ingestAvPublishes, resetBgAvBridge, b
 export { useSharedValue, SharedValue, } from './animated/shared-value.js';
 export type { SharedValueState } from './animated/shared-value.js';
 export { useAnimatedStyle, resetAnimatedStyleBindingIds, } from './animated/use-animated-style.js';
+export type { AnimatedStyleSpec } from './animated/use-animated-style.js';
 export { useAnimatedValue, AnimatedValue, } from './animated/animated-value.js';
 export type { AnimatedValueState } from './animated/animated-value.js';
 export { runOnMainThread, runOnBackground, resetThreading, transformToWorklet, resetRunOnBackgroundState, } from './threading.js';

package/dist/jsx.d.ts

@@ -233,6 +233,12 @@ export interface ListAttributes extends LynxCommonAttributes {
 }
 export interface ListItemAttributes extends LynxCommonAttributes {
     children?: any;
+    /**
+     * Unique, stable key identifying this item for the native recycler. Lynx
+     * uses it to diff and reuse `<list-item>` views as the list scrolls; it
+     * must be unique among siblings within the same `<list>`.
+     */
+    'item-key'?: string;
     /** Item type for recycling (items with same item-type share a view pool) */
     'item-type'?: string | number;
     /** Sticky offset from top */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sigx/lynx-runtime",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "description": "Lynx renderer for SignalX (background thread)",
   "type": "module",
   "main": "./dist/index.js",
@@ -41,7 +41,7 @@
   "dependencies": {
     "@sigx/runtime-core": "^0.4.8",
     "@sigx/reactivity": "^0.4.8",
-    "@sigx/lynx-runtime-internal": "^0.4.3"
+    "@sigx/lynx-runtime-internal": "^0.4.5"
   },
   "peerDependencies": {
     "@lynx-js/types": "*"