@sigx/lynx-gestures 0.1.0

package/src/components/Pressable.tsx

@@ -0,0 +1,175 @@
+import {
+  component,
+  useMainThreadRef,
+  runOnBackground,
+  Gesture,
+  useGestureDetector,
+  type Define,
+  type MainThread,
+} from '@sigx/lynx';
+
+export type PressableProps =
+  & Define.Prop<'pressedOpacity', number, false>
+  & Define.Prop<'pressedScale', number, false>
+  & Define.Prop<'longPressDuration', number, false>
+  & Define.Prop<'maxDistance', number, false>
+  & Define.Prop<'disabled', boolean, false>
+  & Define.Prop<'class', string, false>
+  & Define.Prop<'style', Record<string, string | number>, false>
+  & Define.Slot<'default'>
+  & Define.Event<'press', void>
+  & Define.Event<'longPress', void>;
+
+interface PressableMTState {
+  longPressFired: boolean;
+  pressEmitted: boolean;
+  startPageX: number;
+  startPageY: number;
+}
+
+/**
+ * MT-thread tap + long-press recognizer with built-in pressed-state visual
+ * feedback (opacity + scale). Press and long-press callbacks are dispatched
+ * to BG via `runOnBackground` (low-frequency cross-thread is fine).
+ *
+ * Cross-platform gesture-arena quirks (Phase 2.12.1, observed on iOS Lynx
+ * 3.5 sim and Android Lynx 3.6 / Pixel 9 Pro XL) make this component a
+ * hybrid: it composes `Gesture.Tap()` + `Gesture.LongPress()` via
+ * `Simultaneous` AND adds an onEnd-fallback path inside LongPress, so press
+ * emission works on both platforms via different routes:
+ *
+ * - **Android**: `Tap.onStart` fires on touch-up (as documented). Press
+ *   emits there; the LongPress fallback sees `pressEmitted=true` and
+ *   skips. `Tap.onEnd` fires on the same touch-up — but iOS's premature
+ *   onEnd (next bullet) means we can't safely reset styles here, so style
+ *   reset lives in LongPress.onEnd.
+ * - **iOS**: `Tap.onEnd` fires ~6ms after touchstart (an arena
+ *   fail/reset path that doesn't trigger on Android). `Tap.onStart`
+ *   never fires for our composition. We rely on `LongPress.onEnd` to
+ *   detect "lift before duration with no movement" and emit press from
+ *   the fallback. `Gesture.Race` would be simpler in theory, but its
+ *   `waitFor` deadlocks Tap on iOS — the arena dispatches Tap before
+ *   LongPress reaches Fail state.
+ *
+ * State tracks `longPressFired` and `pressEmitted` so neither event
+ * double-fires regardless of which platform path resolves first.
+ * Movement past `maxDistance` is tracked from `e.params.pageX/pageY`;
+ * `LongPress.onEnd` skips press emission when the touch drifted past
+ * the threshold (matching Tap's success criteria).
+ *
+ * Disabled is captured at setup; runtime toggling won't update an active
+ * gesture's behavior. Wrap the parent in conditional rendering for now if
+ * dynamic disable is needed.
+ */
+export const Pressable = component<PressableProps>(({ props, slots, emit }) => {
+  const elRef = useMainThreadRef<MainThread.Element | null>(null);
+
+  const opacity = props.pressedOpacity ?? 0.6;
+  const scale = props.pressedScale ?? 1;
+  // longPressDuration === 0 disables long-press: we set minDuration to a
+  // huge value so the platform timer never fires; the iOS press fallback
+  // path still works because it's gated on `!longPressFired` (which stays
+  // false), and on Android the Tap.onStart path is unaffected.
+  const longPressDuration = props.longPressDuration ?? 500;
+  const minDuration = longPressDuration > 0 ? longPressDuration : 1_000_000;
+  const maxDistance = props.maxDistance ?? 10;
+  const maxDistanceSq = maxDistance * maxDistance;
+  const disabled = props.disabled ?? false;
+
+  const state = useMainThreadRef<PressableMTState>({
+    longPressFired: false,
+    pressEmitted: false,
+    startPageX: 0,
+    startPageY: 0,
+  });
+
+  const tap = Gesture.Tap()
+    .maxDistance(maxDistance)
+    .onBegin((e: any) => {
+      'main thread';
+      if (disabled) return;
+      // Reset the cross-platform state on every fresh touch-down. Both
+      // Tap.onBegin and LongPress.onBegin fire — first one wins, second
+      // is a no-op because pressEmitted/longPressFired are already false.
+      state.current.longPressFired = false;
+      state.current.pressEmitted = false;
+      const p = e && e.params;
+      state.current.startPageX = (p && p.pageX) || 0;
+      state.current.startPageY = (p && p.pageY) || 0;
+      elRef.current?.setStyleProperties({
+        opacity: opacity,
+        transform: 'scale(' + scale + ')',
+      });
+    })
+    .onStart(() => {
+      'main thread';
+      if (disabled) return;
+      // Android path: Tap.onStart fires on touchend within maxDuration;
+      // emit press here. The LongPress.onEnd fallback below is gated on
+      // !pressEmitted so it won't double-fire on Android.
+      if (!state.current.pressEmitted) {
+        state.current.pressEmitted = true;
+        runOnBackground(() => { emit('press'); })();
+      }
+    });
+  // No Tap.onEnd: iOS fires it ~6ms after touchstart (arena fail/reset
+  // path), which would prematurely reset our press-state styles. Style
+  // reset lives in LongPress.onEnd, which fires only on real touch-up.
+
+  const longPress = Gesture.LongPress()
+    .minDuration(minDuration)
+    .maxDistance(maxDistance)
+    .onBegin(() => {
+      'main thread';
+      if (disabled) return;
+      // Idempotent with Tap.onBegin — both fire on touch-down. State has
+      // already been initialised by Tap.onBegin (whichever fires first).
+      elRef.current?.setStyleProperties({
+        opacity: opacity,
+        transform: 'scale(' + scale + ')',
+      });
+    })
+    .onStart(() => {
+      'main thread';
+      if (disabled) return;
+      state.current.longPressFired = true;
+      runOnBackground(() => { emit('longPress'); })();
+    })
+    .onEnd((e: any) => {
+      'main thread';
+      // Reset visual feedback regardless of how this terminal state was
+      // reached (success / fail / cancel / lift-before-duration).
+      elRef.current?.setStyleProperties({
+        opacity: 1,
+        transform: 'scale(1)',
+      });
+      if (disabled) return;
+      // iOS fallback path. On iOS Tap.onStart never fires, so press would
+      // never emit without this. On Android this is a no-op because
+      // pressEmitted is already true (or longPressFired is true).
+      if (state.current.longPressFired || state.current.pressEmitted) return;
+      const p = e && e.params;
+      if (!p) return;
+      const dx = (p.pageX || 0) - state.current.startPageX;
+      const dy = (p.pageY || 0) - state.current.startPageY;
+      if (dx * dx + dy * dy > maxDistanceSq) return;  // movement-cancel
+      state.current.pressEmitted = true;
+      runOnBackground(() => { emit('press'); })();
+    });
+
+  const gesture = longPressDuration > 0
+    ? Gesture.Simultaneous(tap, longPress)
+    : tap;
+
+  useGestureDetector(elRef, gesture);
+
+  return () => (
+    <view
+      class={props.class}
+      style={props.style}
+      main-thread:ref={elRef}
+    >
+      {slots.default?.()}
+    </view>
+  );
+});

package/src/components/ScrollView.tsx

@@ -0,0 +1,123 @@
+import {
+  component,
+  signal,
+  useSharedValue,
+  useMainThreadRef,
+  defineProvide,
+  type SharedValue,
+  type Define,
+  type MainThread,
+} from '@sigx/lynx';
+import { useScrollContext } from '../scroll-context.js';
+
+export type ScrollViewProps =
+  & Define.Prop<'offsetX', SharedValue<number>, false>
+  & Define.Prop<'offsetY', SharedValue<number>, false>
+  & Define.Prop<'scroll-orientation', 'vertical' | 'horizontal', false>
+  /**
+   * Toggle native scroll responsiveness at runtime — set false to lock the
+   * scroll-view (e.g. while a child `<Draggable>` is mid-drag, so Lynx's
+   * native pan gesture doesn't steal the touch). Maps to Lynx's
+   * `enable-scroll` attribute.
+   */
+  & Define.Prop<'enable-scroll', boolean, false>
+  & Define.Prop<'class', string, false>
+  & Define.Prop<'style', Record<string, string | number>, false>
+  & Define.Slot<'default'>;
+
+/**
+ * MT-thread `<scroll-view>` wrapper that mirrors scroll position into a
+ * `SharedValue`. Pair with `useAnimatedStyle` for parallax / fade / scale
+ * effects driven by scroll, all running on MT with zero per-frame thread
+ * crossings.
+ *
+ * The component is the API; the inline `'main thread'` worklet, the
+ * `__FlushElementTree()` trigger, and the runtime registration are all
+ * internal. Users just pass a `SharedValue<number>` for the axis they care
+ * about — same shape as `<Draggable translateX={tx}>`.
+ *
+ * @example Parallax header
+ * ```tsx
+ * const scrollY = useSharedValue(0);
+ * const headerRef = useMainThreadRef<MainThread.Element | null>(null);
+ *
+ * useAnimatedStyle(headerRef, scrollY, 'translateY', {
+ *   inputRange: [0, 300], outputRange: [0, -150], extrapolate: 'clamp',
+ * });
+ *
+ * <ScrollView offsetY={scrollY}>
+ *   <view main-thread:ref={headerRef}><image src={hero} /></view>
+ *   <text>Body…</text>
+ * </ScrollView>
+ * ```
+ *
+ * @example BG-reactive scroll readout
+ * ```tsx
+ * const scrollY = useSharedValue(0);
+ * <ScrollView offsetY={scrollY}>...</ScrollView>
+ * <text>Scrolled: {scrollY.value.toFixed(0)}px</text>
+ * ```
+ */
+export const ScrollView = component<ScrollViewProps>(({ props, slots }) => {
+  // Always allocate fallback SharedValues — hooks must run unconditionally.
+  // The render closure picks between own/external; the worklet always sees
+  // a defined SharedValue in its `_c` capture.
+  const ownX = useSharedValue(0);
+  const ownY = useSharedValue(0);
+
+  // Phase 2.12 ScrollView ↔ child-gesture coordination. Descendant
+  // `<Draggable>` / `<Swipeable>` flip this signal during their drag so the
+  // UIKit `panGestureRecognizer` (which doesn't participate in the new
+  // gesture arena) yields the touch. See `scroll-context.ts` for the why.
+  const dragging = signal(false);
+
+  // Phase 2.13: publish the scroll-view's element ref through the context so
+  // descendants can drive scroll directly from worklets (e.g. <Draggable
+  // edgeScroll>). Captured at setup so the worklet `_c` map sees a stable
+  // ref identity.
+  const scrollViewRef = useMainThreadRef<MainThread.Element | null>(null);
+
+  // Pick the axis SVs once; the same identity is shared with descendants via
+  // the context (so they can read live scroll position) and used at render
+  // time for the bindscroll worklet's `_c` capture.
+  const x: SharedValue<number> = props.offsetX ?? ownX;
+  const y: SharedValue<number> = props.offsetY ?? ownY;
+  const scrollOrientation = props['scroll-orientation'] ?? 'vertical';
+
+  defineProvide(useScrollContext, () => ({
+    dragging,
+    scrollViewRef,
+    offsetX: x,
+    offsetY: y,
+    scrollOrientation,
+  }));
+
+  return () => {
+    // Compose user-passed enable-scroll with the descendant-driven flag:
+    // both must be true. User can still force-lock by passing `false`.
+    const userEnableScroll = props['enable-scroll'] ?? true;
+    const enableScroll = userEnableScroll && !dragging.value;
+    return (
+      <scroll-view
+        main-thread:ref={scrollViewRef}
+        scroll-orientation={scrollOrientation}
+        enable-scroll={enableScroll}
+        class={props.class}
+        style={props.style}
+        main-thread-bindscroll={(e: any) => {
+          'main thread';
+          y.current.value = e.detail.scrollTop;
+          x.current.value = e.detail.scrollLeft;
+          // Apply useAnimatedStyle bindings on the same frame. Inlined
+          // (rather than calling a helper) because plain function imports
+          // don't survive worklet `_c` capture across the MT bundle —
+          // same constraint @sigx/lynx-motion's `animate()` documents.
+          const __flush = (globalThis as Record<string, unknown>)['__FlushElementTree'] as (() => void) | undefined;
+          if (__flush) __flush();
+        }}
+      >
+        {slots.default?.()}
+      </scroll-view>
+    );
+  };
+});

package/src/components/Swipeable.tsx

@@ -0,0 +1,220 @@
+import {
+  component,
+  useMainThreadRef,
+  useSharedValue,
+  useAnimatedStyle,
+  runOnBackground,
+  Gesture,
+  useGestureDetector,
+  type Define,
+  type MainThread,
+} from '@sigx/lynx';
+import { useScrollContext } from '../scroll-context.js';
+
+export type SwipeSide = 'left' | 'right';
+
+export type SwipeableProps =
+  & Define.Prop<'leftActionsWidth', number, false>
+  & Define.Prop<'rightActionsWidth', number, false>
+  & Define.Prop<'snapThreshold', number, false>
+  & Define.Prop<'snapDuration', number, false>
+  & Define.Prop<'leftActions', () => unknown, false>
+  & Define.Prop<'rightActions', () => unknown, false>
+  & Define.Prop<'class', string, false>
+  & Define.Prop<'style', Record<string, string | number>, false>
+  & Define.Prop<'foregroundStyle', Record<string, string | number>, false>
+  & Define.Slot<'default'>
+  & Define.Event<'swipeOpen', { side: SwipeSide }>
+  & Define.Event<'swipeClose', void>;
+
+interface SwipeMTState {
+  startPageX: number;
+  offsetX: number;
+  /** Snapped resting position: 0, +leftWidth, or -rightWidth. */
+  currentX: number;
+}
+
+/**
+ * Horizontal swipe-to-reveal container, built on the native gesture arena
+ * via `Gesture.Pan().axis('x')`. The foreground is dragged horizontally on
+ * the MT thread; on release it snaps to one of three resting positions
+ * (closed / open-left / open-right) using `MTElementWrapper.animate()`.
+ * Open and close events are dispatched to BG via `runOnBackground`.
+ *
+ * Migrated from a 4-`bindtouch*`-worklet implementation to a single
+ * `Gesture.Pan()` (Phase 2.12). Carries the same Phase 2.11 quirks:
+ *   - `.onBegin(() => {})` no-op is load-bearing on iOS Pan to gate
+ *     `_isInvokedBegin` open so onStart/onEnd fire.
+ *   - `e.params.pageX` (not `e.pageX`) — Lynx pan event nests the touch
+ *     payload under `params`.
+ *
+ * Supply `leftActions` and/or `rightActions` as render-prop functions:
+ *
+ * ```tsx
+ * <Swipeable
+ *   rightActions={() => <view><text>Delete</text></view>}
+ *   onSwipeOpen={(e) => console.log('opened', e.side)}
+ * >
+ *   <view><text>Row content</text></view>
+ * </Swipeable>
+ * ```
+ *
+ * **Scroll composition** (Phase 2.12.3): nesting `<Swipeable>` inside
+ * `<ScrollView>` is automatic — `useScrollContext` is read at setup and
+ * the BG-side onStart/onEnd handlers flip `scrollCtx.dragging` so the
+ * parent yields its UIKit pan for the duration of the swipe. No consumer
+ * wiring required.
+ */
+export const Swipeable = component<SwipeableProps>(({ props, slots, emit }) => {
+  const fgRef = useMainThreadRef<MainThread.Element | null>(null);
+
+  // Drive the foreground transform via a SharedValue so external animations
+  // could compose if we ever wanted spring snaps. For now we still call
+  // `.animate()` on the element directly for the snap; the SV is only the
+  // intermediate write target during the drag.
+  const tx = useSharedValue(0);
+  useAnimatedStyle(fgRef, tx, 'translateX');
+
+  const drag = useMainThreadRef<SwipeMTState>({
+    startPageX: 0,
+    offsetX: 0,
+    currentX: 0,
+  });
+
+  // Coordinate with the parent <ScrollView> (Phase 2.12.3) — see Draggable
+  // for the why. Null when no ancestor ScrollView.
+  const scrollCtx = useScrollContext();
+
+  const leftWidth = props.leftActionsWidth ?? 100;
+  const rightWidth = props.rightActionsWidth ?? 100;
+  const snapThreshold = props.snapThreshold ?? 60;
+  const snapDuration = props.snapDuration ?? 200;
+  const hasLeft = !!props.leftActions;
+  const hasRight = !!props.rightActions;
+  const upper = hasLeft ? leftWidth : 0;
+  const lower = hasRight ? -rightWidth : 0;
+
+  const pan = Gesture.Pan()
+    .axis('x')
+    // Empty onBegin gates `_isInvokedBegin` open on iOS so onStart/onEnd fire.
+    .onBegin(() => {
+      'main thread';
+    })
+    .onStart((e: any) => {
+      'main thread';
+      const p = e && e.params;
+      drag.current.startPageX = (p && p.pageX) || 0;
+      drag.current.offsetX = drag.current.currentX;
+      // Tell the parent ScrollView (if any) we own the touch.
+      runOnBackground(() => {
+        if (scrollCtx) scrollCtx.dragging.value = true;
+      })();
+    })
+    .onUpdate((e: any) => {
+      'main thread';
+      const p = e && e.params;
+      const pageX = (p && p.pageX) || 0;
+      let x = drag.current.offsetX + (pageX - drag.current.startPageX);
+      if (x > upper) x = upper;
+      if (x < lower) x = lower;
+      tx.current.value = x;
+      // Bridge the binding on the same frame so the foreground tracks the
+      // finger without a vsync delay (same trick as Draggable).
+      const __flush = (globalThis as Record<string, unknown>)['__FlushElementTree'] as (() => void) | undefined;
+      if (__flush) __flush();
+    })
+    .onEnd(() => {
+      'main thread';
+      const x = tx.current.value;
+      // Snap to closest resting position.
+      let target = 0;
+      if (hasLeft && x > snapThreshold) target = leftWidth;
+      else if (hasRight && x < -snapThreshold) target = -rightWidth;
+      fgRef.current?.animate(
+        [
+          { transform: 'translateX(' + x + 'px)' },
+          { transform: 'translateX(' + target + 'px)' },
+        ],
+        { duration: snapDuration, fill: 'forwards', easing: 'cubic-bezier(0.2, 0.8, 0.2, 1)' },
+      )?.play();
+      // Keep the SV in sync with the snap target so subsequent drags don't
+      // jump back to the pre-animate position.
+      tx.current.value = target;
+      const wasOpen = drag.current.currentX !== 0;
+      const nowOpen = target !== 0;
+      drag.current.currentX = target;
+      // Always release the parent ScrollView's claim, regardless of snap.
+      // Bundled into the same runOnBackground call as the emit so we only
+      // pay one cross-thread hop.
+      if (nowOpen) {
+        const side: SwipeSide = target > 0 ? 'left' : 'right';
+        runOnBackground((s: SwipeSide) => {
+          if (scrollCtx) scrollCtx.dragging.value = false;
+          emit('swipeOpen', { side: s });
+        })(side);
+      } else if (wasOpen) {
+        runOnBackground(() => {
+          if (scrollCtx) scrollCtx.dragging.value = false;
+          emit('swipeClose');
+        })();
+      } else {
+        // Closed→closed: still need to release the ScrollView claim.
+        runOnBackground(() => {
+          if (scrollCtx) scrollCtx.dragging.value = false;
+        })();
+      }
+    });
+
+  useGestureDetector(fgRef, pan);
+
+  return () => (
+    <view
+      class={props.class}
+      style={{
+        position: 'relative',
+        overflow: 'hidden',
+        ...(props.style || {}),
+      }}
+    >
+      {hasLeft ? (
+        <view style={{
+          position: 'absolute',
+          left: '0',
+          top: '0',
+          bottom: '0',
+          width: leftWidth + 'px',
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+        }}>
+          {props.leftActions!()}
+        </view>
+      ) : null}
+
+      {hasRight ? (
+        <view style={{
+          position: 'absolute',
+          right: '0',
+          top: '0',
+          bottom: '0',
+          width: rightWidth + 'px',
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+        }}>
+          {props.rightActions!()}
+        </view>
+      ) : null}
+
+      <view
+        main-thread:ref={fgRef}
+        style={{
+          position: 'relative',
+          ...(props.foregroundStyle || {}),
+        }}
+      >
+        {slots.default?.()}
+      </view>
+    </view>
+  );
+});

package/src/index.ts

@@ -0,0 +1,61 @@
+// Multi-touch JS-only fallback hooks. Lynx's native gesture arena ships a
+// `Gesture.Pinch()` / `Gesture.Rotation()` builder pair (`GestureType.PINCH`,
+// `GestureType.ROTATION`), but the platform-side handlers are unfinished
+// in Lynx 3.5 — these hooks parse `bindtouch*` events directly until that
+// changes. The other legacy hooks (`useTap`, `useLongPress`, `usePan`,
+// `useFling`, `useSwipe`, `useGesture`, `usePanResponder`) were deleted in
+// Phase 2.12.4 — use `Gesture.*` + `useGestureDetector` instead.
+export { usePinch } from './use-pinch.js';
+export { useRotation } from './use-rotation.js';
+
+// Cross-thread value primitive — re-exported from @sigx/lynx for back-compat.
+// @deprecated since 0.3.0 — import directly from '@sigx/lynx' instead.
+// The primitives moved out of @sigx/lynx-gestures in Phase 2.6 because they
+// have no gesture coupling (SharedValue extends MainThreadRef and the
+// bridge plumbing already lives in the runtime packages).
+export {
+  useSharedValue,
+  SharedValue,
+  // @deprecated — kept for back-compat. Use `useSharedValue` / `SharedValue`.
+  useAnimatedValue,
+  AnimatedValue,
+  useAnimatedStyle,
+  resetAnimatedStyleBindingIds,
+} from '@sigx/lynx';
+export type {
+  SharedValueState,
+  // @deprecated — use `SharedValueState`.
+  AnimatedValueState,
+  BuiltinMapperName,
+  MapperParams,
+} from '@sigx/lynx';
+
+// Built-in MT components (arena-driven via `Gesture.*` + `useGestureDetector`).
+export { Pressable } from './components/Pressable.js';
+export type { PressableProps } from './components/Pressable.js';
+export { Draggable } from './components/Draggable.js';
+export type { DraggableProps, DragEndDetail } from './components/Draggable.js';
+export { Swipeable } from './components/Swipeable.js';
+export type { SwipeableProps, SwipeSide } from './components/Swipeable.js';
+export { ScrollView } from './components/ScrollView.js';
+export type { ScrollViewProps } from './components/ScrollView.js';
+
+// ScrollView ↔ child-gesture coordination (Phase 2.12.3). Public mostly so
+// custom gesture components can opt in to the same auto-yield behavior that
+// `<Draggable>` and `<Swipeable>` get for free.
+export { useScrollContext } from './scroll-context.js';
+export type { ScrollContext } from './scroll-context.js';
+
+// Types
+export type {
+  TouchPoint,
+  TouchEvent,
+  GesturePhase,
+  GestureHandlers,
+  PinchState,
+  UsePinchOptions,
+  UsePinchReturn,
+  RotationState,
+  UseRotationOptions,
+  UseRotationReturn,
+} from './types.js';

package/src/scroll-context.ts

@@ -0,0 +1,72 @@
+import {
+  defineInjectable,
+  type PrimitiveSignal,
+  type SharedValue,
+  type MainThreadRef,
+  type MainThread,
+} from '@sigx/lynx';
+
+/**
+ * Scroll-arena coordination context, provided by `<ScrollView>` and consumed
+ * by descendant gesture components (`<Draggable>`, `<Swipeable>`).
+ *
+ * Why this exists: Lynx's `<scroll-view>` does NOT participate in the new
+ * gesture arena (`LynxGestureArenaManager`) on iOS — its UIKit
+ * `panGestureRecognizer` runs independently of arena gestures, so a Pan
+ * registered on a descendant element fires concurrently with the parent
+ * scroll. The visible result is "drag works but the page scrolls too,
+ * sliding the box away from the finger".
+ *
+ * Workaround: the parent `<ScrollView>` exposes a BG-side `dragging` signal
+ * that gates its `enable-scroll` prop. Gesture children flip the signal
+ * during their lifecycle (onStart/onEnd → onDragStart/onDragEnd) so the
+ * UIScrollView pan recognizer is disabled while a child gesture owns the
+ * touch.
+ *
+ * This is a Phase 2.12 framework-level encapsulation of what consumers had
+ * to wire by hand in Phase 2.11. A proper fix lives on the Lynx native
+ * side: making `<scroll-view>`'s pan recognizer participate in the arena
+ * (or yielding to arena recognizers in `shouldBeRequiredToFailByGestureRecognizer:`).
+ * Until then, this is the cleanest the framework can be.
+ *
+ * Returns `null` when no parent `<ScrollView>` is in scope, so consumers
+ * branch on presence:
+ *
+ * ```ts
+ * const scrollCtx = useScrollContext();
+ * // ... inside an onStart's runOnBackground arrow:
+ * if (scrollCtx) scrollCtx.dragging.value = true;
+ * ```
+ *
+ * Phase 2.13 extends the context with the scroll-view's element ref + live
+ * scroll-position SVs + axis, so descendants can drive scroll directly
+ * (edge-scroll while dragging, etc.) without re-piping refs through props.
+ */
+export interface ScrollContext {
+  /** BG-side flag the parent `<ScrollView>` reads as `enable-scroll={!dragging.value}`. */
+  dragging: PrimitiveSignal<boolean>;
+  /**
+   * MT element ref to the underlying `<scroll-view>`. Null until mounted.
+   * Descendants call `scrollViewRef.current?.invoke('scrollBy', ...)` from
+   * worklets to drive scroll programmatically.
+   */
+  scrollViewRef: MainThreadRef<MainThread.Element | null>;
+  /**
+   * Live horizontal scroll position. Same SV the consumer passes via
+   * `<ScrollView offsetX={…}>` (or an internally-allocated fallback).
+   */
+  offsetX: SharedValue<number>;
+  /**
+   * Live vertical scroll position. Same SV the consumer passes via
+   * `<ScrollView offsetY={…}>` (or an internally-allocated fallback).
+   */
+  offsetY: SharedValue<number>;
+  /**
+   * Scroll axis as configured on the `<scroll-view>`. Edge-scroll
+   * descendants pick which edges to monitor based on this:
+   * `'vertical'` → top/bottom; `'horizontal'` → left/right.
+   */
+  scrollOrientation: 'vertical' | 'horizontal';
+}
+
+export const useScrollContext = defineInjectable<ScrollContext | null>(() => null);