@unrulysystems/native-motion 0.1.0-alpha.0

package/src/native/motion/MotionRoot.tsx

@@ -0,0 +1,250 @@
+// REQ-API-022 (FLAG 5a, specs/SPEC-GESTURE.md) — MotionRoot, the public root
+// primitive. On native it OWNS the platform gesture root (GestureHandlerRootView — consumers
+// never import the substrate, the dogfood ban law); the web entry's counterpart renders children
+// unchanged, keeping the one-import universal surface. A gesture-carrying View mounted outside
+// this root would silently never receive touches — the context lets the component fail loud
+// instead (gateMotionRoot), per the severity law.
+//
+// R15 D3 (REQ-API-043 / packet Finding 8): also hosts the hub touch stream — a manual-activation
+// pan spanning the root that records touches and drives hub-originated drag sessions so sibling
+// handles work (the pin's window-level PanSession analog).
+
+import { createContext, useContext, useMemo, useRef } from 'react'
+import type { ViewStyle } from 'react-native'
+import { Gesture, GestureDetector, GestureHandlerRootView } from 'react-native-gesture-handler'
+import { runNativeEventCallback, useWorkletDriver } from '../driver/workletDriver'
+import { createDragHubStream, type DragHubStream } from './dragHubStream'
+import { createLayoutIdentityBinding, type LayoutIdentityBinding } from './layoutIdBinding'
+import type { MotionComponentId, NativeSeverity } from './motionViewController'
+
+// Null outside a MotionRoot: gesture props use the presence bit, while layoutId Views consume the
+// binding itself. One provider value therefore owns both root-scoped capabilities without parallel
+// root contexts that could skew under nested roots.
+interface MotionRootContextValue {
+  readonly layoutIdentity: LayoutIdentityBinding
+  readonly subscribeLayoutIdentitySettle: (id: string, listener: () => void) => () => void
+  /** R15 D3: the hub touch stream for imperative dragControls.start (Finding 8). */
+  readonly dragHubStream: DragHubStream
+}
+
+const MotionRootContext = createContext<MotionRootContextValue | null>(null)
+
+export function useInsideMotionRoot(): boolean {
+  return useContext(MotionRootContext) !== null
+}
+
+export function useLayoutIdentityRootBinding(): LayoutIdentityBinding | null {
+  return useContext(MotionRootContext)?.layoutIdentity ?? null
+}
+
+// Projection geometry must live on ONE forest under MotionRoot so layoutId's identity driver
+// (writeHolder → setDirectProjection) and host-frame feeds share the same tree. Without this,
+// the first non-layoutId Motion ancestor opens a private useWorkletDriver() forest and a nested
+// layoutId child's projectionComponentId is never registered where the root frame publishes it.
+export function useLayoutIdentityProjectionBinding():
+  | LayoutIdentityBinding['projectionBinding']
+  | null {
+  return useContext(MotionRootContext)?.layoutIdentity.projectionBinding ?? null
+}
+
+// layoutId flights run on MotionRoot's shared driver, while each host owns its ordinary property
+// driver. This subscription delivers the shared driver's PER-IDENTITY settle edge — keyed by the
+// identity id, independent of unrelated driver work — to the mounted host that initiated an
+// identity flight; it never polls or crosses the UI runtime per frame.
+export function useLayoutIdentitySettleSubscription():
+  | ((id: string, listener: () => void) => () => void)
+  | null {
+  return useContext(MotionRootContext)?.subscribeLayoutIdentitySettle ?? null
+}
+
+/** R15 D3: the hub stream for DragControls.start correlation (null outside MotionRoot). */
+export function useDragHubStream(): DragHubStream | null {
+  return useContext(MotionRootContext)?.dragHubStream ?? null
+}
+
+// The REQ-API-022 gate, pure so the suite pins it: true = proceed; development throws naming
+// MotionRoot; production reports and refuses (the caller drops the gesture wiring, fail-closed).
+export function gateMotionRoot(
+  insideRoot: boolean,
+  severity: NativeSeverity,
+  report: (error: Error) => void,
+  componentId: MotionComponentId = '<Motion.View>',
+): boolean {
+  if (insideRoot) return true
+  const error = new Error(
+    `${componentId}: gesture props need a <MotionRoot> above them: MotionRoot owns the platform gesture root ` +
+      "(REQ-API-022). Wrap your app (or the gesture subtree) in MotionRoot from '@unrulysystems/native-motion'.",
+  )
+  if (severity === 'development') throw error
+  report(error)
+  return false
+}
+
+// Children only — deliberately NO style knob on either entry: the web counterpart renders no
+// element, so a style prop would be web-ignored (an accepted-but-ignored prop, REQ-API-016), and
+// no example needs root styling. A layout knob can land ADDITIVELY when an example demands it.
+export interface MotionRootProps {
+  readonly children?: React.ReactNode
+}
+
+// GestureHandlerRootView must span the gesture area; flex: 1 is the substrate's own documented
+// expectation for an app-root mount.
+const ROOT_FILL: ViewStyle = { flex: 1 }
+
+export function MotionRoot({ children }: MotionRootProps) {
+  // The registry lives in the driver's UI-runtime layout slot. Creating this driver here makes the
+  // registry identity root-scoped: every descendant layoutId View exchanges through this ONE
+  // binding, while each View keeps its existing private driver for ordinary animated properties.
+  const driver = useWorkletDriver()
+  const valueRef = useRef<MotionRootContextValue | null>(null)
+  if (valueRef.current === null) {
+    valueRef.current = {
+      layoutIdentity: createLayoutIdentityBinding(driver),
+      subscribeLayoutIdentitySettle: (id, listener) => driver.layout.subscribeSettled(id, listener),
+      dragHubStream: createDragHubStream(),
+    }
+  }
+  const stream = valueRef.current.dragHubStream
+
+  // R15 D3 hub pan: manual-activation, simultaneous with everything (never blocks scroll/child
+  // gestures), records touches, activates only when a hub start has armed the stream.
+  const hubPan = useMemo(
+    () =>
+      Gesture.Pan()
+        .runOnJS(true)
+        .manualActivation(true)
+        // Unarmed touches are never activated — child/scroll recognizers keep the stream.
+        .onTouchesDown((event, manager) => {
+          runNativeEventCallback(() => {
+            for (const touch of event.allTouches) {
+              stream.recordTouch({
+                id: touch.id,
+                absoluteX: touch.absoluteX,
+                absoluteY: touch.absoluteY,
+              })
+            }
+            // U7d tap observation rides CHANGED touches — one notification per physical down
+            // (allTouches re-reports already-active touches on every subsequent down).
+            for (const touch of event.changedTouches) {
+              stream.notifyTapDown({
+                id: touch.id,
+                absoluteX: touch.absoluteX,
+                absoluteY: touch.absoluteY,
+              })
+            }
+            // Stay inert unless already armed by a hub start between down and move.
+            if (stream.armed === null) {
+              // Do not activate — leave the touch for child/scroll recognizers.
+              void manager
+            }
+          })
+        })
+        .onTouchesMove((event, manager) => {
+          runNativeEventCallback(() => {
+            const armed = stream.armed
+            if (armed === null) return
+            // Route ONLY the correlated touchId (seal review r3 — multi-touch ownership).
+            // Synthetic arm id -1 also accepts any touch within correlation (rebound on
+            // recordTouch; seal review r4 major).
+            const touch =
+              armed.touchId === -1
+                ? (event.allTouches[0] ?? event.changedTouches[0])
+                : (event.allTouches.find((t) => t.id === armed.touchId) ??
+                  event.changedTouches.find((t) => t.id === armed.touchId))
+            if (touch === undefined) return
+            // Activate the recognizer so onUpdate/onEnd own velocity (REQ-GESTURE-014).
+            // Once activated, ONLY the recognizer .onUpdate feed drives the session — never
+            // dual-feed onTouchesMove + onUpdate (seal review r4 major / Finding 8).
+            if (!armed.activated) {
+              manager.activate()
+              // Pre-activation bridge: one absolute sample so distanceThreshold can clear
+              // before the first .onUpdate (same-frame Pressable arm race).
+              stream.onPanUpdate({
+                absoluteX: touch.absoluteX,
+                absoluteY: touch.absoluteY,
+                translationX: touch.absoluteX - armed.originAbsoluteX,
+                translationY: touch.absoluteY - armed.originAbsoluteY,
+                velocityX: 0,
+                velocityY: 0,
+              })
+            }
+          })
+        })
+        .onTouchesUp((event) => {
+          runNativeEventCallback(() => {
+            // RNGH Android delivers onTouchesUp BEFORE the handler processes the up event
+            // (GestureHandlerOrchestrator), so onEnd still follows with the real velocity
+            // (REQ-GESTURE-014). Never end/finalize here when activated — that would zero
+            // velocity and disarm before onEnd (seal review r2 major).
+            // Pre-activation: cancel when the CORRELATED touch lifts (not a second finger).
+            // Synthetic arm id -1 (Pressable before recordTouch rebind): any lift correlates —
+            // real changedTouches never carry id -1 (adversarial seal Issue 3).
+            const armed = stream.armed
+            const correlatedUp =
+              armed !== null &&
+              event.changedTouches.length > 0 &&
+              (armed.touchId === -1 || event.changedTouches.some((t) => t.id === armed.touchId))
+            if (armed !== null && !armed.activated && correlatedUp) {
+              stream.terminate(false)
+            }
+            for (const touch of event.changedTouches) {
+              stream.notifyTapUp({
+                id: touch.id,
+                absoluteX: touch.absoluteX,
+                absoluteY: touch.absoluteY,
+              })
+              stream.forgetTouch(touch.id)
+            }
+          })
+        })
+        .onTouchesCancelled((event) => {
+          runNativeEventCallback(() => {
+            // Cancel when the correlated touch is cancelled. Synthetic -1: any cancel
+            // correlates (same as up; Issue 3).
+            const armed = stream.armed
+            const correlated =
+              armed !== null &&
+              event.changedTouches.length > 0 &&
+              (armed.touchId === -1 || event.changedTouches.some((t) => t.id === armed.touchId))
+            if (armed !== null && correlated) {
+              stream.terminate(false)
+            }
+            for (const touch of event.changedTouches) {
+              // U7d: the touch-cancel path is the global press's ONLY cancel source (the R11
+              // touch-steal mapping, reproduced through the stream's own cancel event — F1).
+              stream.notifyTapCancel({
+                id: touch.id,
+                absoluteX: touch.absoluteX,
+                absoluteY: touch.absoluteY,
+              })
+              stream.forgetTouch(touch.id)
+            }
+          })
+        })
+        // Recognizer lifecycle owns velocity when ACTIVE (REQ-GESTURE-014 preferred path).
+        .onStart((event) => runNativeEventCallback(() => stream.onPanStart(event)))
+        .onUpdate((event) => runNativeEventCallback(() => stream.onPanUpdate(event)))
+        .onEnd((event, success) => runNativeEventCallback(() => stream.onPanEnd(event, success)))
+        .onFinalize((event, success) =>
+          runNativeEventCallback(() => stream.onPanFinalize(event, success)),
+        ),
+    [stream],
+  )
+
+  // RNGH GestureDetector requires exactly one child element (Wrap.tsx Children.only).
+  // MotionRootProps still accepts arbitrary ReactNode — wrap so empty/multi-child trees
+  // match the web root (no public API restriction) without crashing (review seal major).
+  // Nested GestureHandlerRootView is a single native host for the detector; mocks already
+  // provide it as a passthrough (no react-native View import required in this module).
+  return (
+    <MotionRootContext.Provider value={valueRef.current}>
+      <GestureHandlerRootView style={ROOT_FILL}>
+        <GestureDetector gesture={hubPan}>
+          <GestureHandlerRootView style={ROOT_FILL} collapsable={false}>
+            {children}
+          </GestureHandlerRootView>
+        </GestureDetector>
+      </GestureHandlerRootView>
+    </MotionRootContext.Provider>
+  )
+}