@unrulysystems/native-motion 0.1.0-alpha.0

package/src/native/motion/externalDragDriver.ts

@@ -0,0 +1,214 @@
+// R15 D5 (REQ-API-046 / REQ-GESTURE-030): redirect drag session live reads, writes, and release
+// commands to consumer-supplied MotionValues (`_dragX` / `_dragY`) instead of the host's own
+// axis channels. The element's transform is never written by the session on an external axis
+// (the pin's getAxisMotionValue branch).
+
+import {
+  GESTURE_RELEASE_SPRING,
+  inertiaGenerator,
+  resolveSpringGenerator,
+  type DragAxis,
+  type Driver,
+  type ElementHandle,
+  type InertiaTransition,
+  type MotionValue,
+  type PropTransition,
+  type SpringConfig,
+} from '@unrulysystems/native-motion-core'
+import { resolveDefaultValueChannel } from './valueHooks'
+
+export type ExternalDragValues = Partial<Record<DragAxis, MotionValue<number>>>
+
+function springConfigFromRelease(transition: PropTransition): SpringConfig {
+  if (transition.type === 'spring') {
+    return {
+      stiffness: transition.stiffness ?? GESTURE_RELEASE_SPRING.stiffness,
+      damping: transition.damping ?? GESTURE_RELEASE_SPRING.damping,
+    }
+  }
+  return { ...GESTURE_RELEASE_SPRING }
+}
+
+/**
+ * R16 (REQ-GESTURE-023/-030, review major 1): the free-drag release's two-phase inertia
+ * generator on an external MotionValue — host parity with the driver's `kind:'inertia'`
+ * command. The descriptor's physics are used verbatim; the generator recomputes its ideal from
+ * the seed and owns the walls (an out-of-bounds origin boundary-springs from rest — it is
+ * never jumped to the target synchronously, the pin's t=0 latch). An MV the default graph
+ * cannot animate (a hostile/test double) is a consumer error and FAILS LOUD (severity law,
+ * review r2 major 1) — never suppressed into the synchronous jump this path forbids.
+ */
+function inertiaReleaseExternal(
+  value: MotionValue<number>,
+  from: number,
+  velocity: number,
+  transition: InertiaTransition,
+): void {
+  const factory = inertiaGenerator({
+    power: transition.power,
+    timeConstant: transition.timeConstant,
+    bounceStiffness: transition.bounceStiffness,
+    bounceDamping: transition.bounceDamping,
+    restDelta: transition.restDelta,
+    restSpeed: transition.restSpeed,
+    ...(transition.min !== undefined ? { min: transition.min } : {}),
+    ...(transition.max !== undefined ? { max: transition.max } : {}),
+  })
+  value.set(from)
+  resolveDefaultValueChannel().graph.animate(value, () => factory({ from, velocity }))
+}
+
+/**
+ * Velocity-seeded spring on an external MotionValue (REQ-GESTURE-022 parity with host
+ * driver.command release). The MV must belong to the default value-channel graph
+ * (useMotionValue / useSpring followers do).
+ */
+function springReleaseExternal(
+  value: MotionValue<number>,
+  from: number,
+  to: number,
+  velocity: number,
+  transition: PropTransition,
+): void {
+  const config = springConfigFromRelease(transition)
+  const factory = resolveSpringGenerator(to, config)
+  // Seed the handoff origin so the spring starts from the release sample, not a stale MV.
+  value.set(from)
+  try {
+    resolveDefaultValueChannel().graph.animate(value, () => factory({ from, velocity }))
+  } catch {
+    // MV not owned by the default graph (hostile/test double) — land at target fail-closed.
+    value.set(to)
+  }
+}
+
+/**
+ * Wrap a Driver so drag traffic for the named axes lands on external MotionValues.
+ * Other axes and non-handle traffic pass through unchanged.
+ */
+export function wrapDriverForExternalDragValues(
+  driver: Driver,
+  handle: ElementHandle,
+  external: ExternalDragValues,
+): Driver {
+  const hasX = external.x !== undefined
+  const hasY = external.y !== undefined
+  if (!hasX && !hasY) return driver
+
+  return {
+    register: (initial) => driver.register(initial),
+    step: (elapsedMs) => driver.step(elapsedMs),
+    committed: (h) => driver.committed(h),
+    setActive: (h, active) => driver.setActive(h, active),
+    isActive: (h) => driver.isActive(h),
+    liveFor(h, key) {
+      if (h === handle && (key === 'x' || key === 'y')) {
+        const mv = external[key]
+        if (mv !== undefined) {
+          const value = mv.get()
+          if (typeof value !== 'number' || !Number.isFinite(value)) {
+            throw new Error(
+              `external _drag${key.toUpperCase()} must hold a finite number, got ${String(value)} (REQ-API-046).`,
+            )
+          }
+          const velocity = mv.getVelocity()
+          return { value, velocity: Number.isFinite(velocity) ? velocity : 0 }
+        }
+      }
+      return driver.liveFor(h, key)
+    },
+    write(h, values, velocities) {
+      if (h !== handle) {
+        driver.write(h, values, velocities)
+        return
+      }
+      const rest: Record<string, number> = {}
+      const restVel: Record<string, number> = {}
+      for (const [key, value] of Object.entries(values)) {
+        if ((key === 'x' || key === 'y') && external[key] !== undefined) {
+          external[key]!.set(value)
+        } else {
+          rest[key] = value
+          if (velocities !== undefined && velocities[key] !== undefined) {
+            restVel[key] = velocities[key]!
+          }
+        }
+      }
+      if (Object.keys(rest).length > 0) {
+        driver.write(h, rest, Object.keys(restVel).length > 0 ? restVel : undefined)
+      }
+    },
+    command(h, command) {
+      if (h !== handle || command.kind !== 'start') {
+        driver.command(h, command)
+        return
+      }
+      const restTargets: Record<string, (typeof command.targets)[string]> = {}
+      const releaseTransition: PropTransition = command.transition
+      for (const [key, target] of Object.entries(command.targets)) {
+        if ((key === 'x' || key === 'y') && external[key] !== undefined && target !== undefined) {
+          const to = target.to
+          if (typeof to !== 'number' || !Number.isFinite(to)) {
+            throw new Error(
+              `external _drag${key.toUpperCase()} release target must be a finite number (REQ-API-046).`,
+            )
+          }
+          const from = typeof target.from === 'number' ? target.from : external[key]!.get()
+          // R16 review minor 8: `from` is the generator seed origin — a non-finite one (a hostile
+          // MV's get(), or a corrupt descriptor field) would silently NaN the whole trajectory.
+          // Same fail-loud law as the `to` check above and the liveFor value guard.
+          if (!Number.isFinite(from)) {
+            throw new Error(
+              `external _drag${key.toUpperCase()} release origin must be a finite number, got ${String(from)} (REQ-API-046).`,
+            )
+          }
+          // Fix-up review: velocity is the last descriptor field without a finiteness guard —
+          // `typeof NaN === 'number'`, so a bare typeof check launders a non-finite velocity into
+          // a silent NaN trajectory (inertia) or a NaN-seeded spring. Same law as `from`/`to`.
+          const velocity = typeof target.velocity === 'number' ? target.velocity : 0
+          if (!Number.isFinite(velocity)) {
+            throw new Error(
+              `external _drag${key.toUpperCase()} release velocity must be a finite number, got ${String(velocity)} (REQ-API-046).`,
+            )
+          }
+          const targetTransition: PropTransition = target.transition ?? command.transition
+          if (targetTransition.type === 'inertia') {
+            // R16 review minor 7: this channel consumes the raw per-target descriptor WITHOUT
+            // core's prepare validation. A non-positive/non-finite boundary-spring pair
+            // degenerates the solver to a silent NaN trajectory — refuse it here (the config
+            // boundary refuses it at mount on the public path; this guards the direct seam).
+            if (
+              !Number.isFinite(targetTransition.bounceStiffness) ||
+              targetTransition.bounceStiffness <= 0 ||
+              !Number.isFinite(targetTransition.bounceDamping) ||
+              targetTransition.bounceDamping <= 0
+            ) {
+              throw new Error(
+                `external _drag${key.toUpperCase()} inertia release requires finite, greater-than-zero ` +
+                  `bounceStiffness/bounceDamping, got bounceStiffness=${String(targetTransition.bounceStiffness)} ` +
+                  `bounceDamping=${String(targetTransition.bounceDamping)} (REQ-API-046).`,
+              )
+            }
+            // Free-drag release (R16): the per-target inertia descriptor drives the two-phase
+            // generator on the external MV — decay + boundary spring, never the obsolete
+            // clamped spring and never a synchronous jump on an out-of-bounds origin.
+            inertiaReleaseExternal(external[key]!, from, velocity, targetTransition)
+            continue
+          }
+          // Cancel / momentum=false (v=0) on the spring path: land without a spring flight.
+          // Momentum=true: velocity-seeded spring to project-then-snap target (host parity).
+          if (velocity === 0) {
+            external[key]!.set(to)
+          } else {
+            springReleaseExternal(external[key]!, from, to, velocity, releaseTransition)
+          }
+        } else if (target !== undefined) {
+          restTargets[key] = target
+        }
+      }
+      if (Object.keys(restTargets).length > 0) {
+        driver.command(h, { ...command, targets: restTargets })
+      }
+    },
+  }
+}

package/src/native/motion/frameData.ts

@@ -0,0 +1,31 @@
+// REQ-API-058 — public `frameData`, the pin's read-only JS-frame clock.
+// Pin: motion-dom frameloop/batcher.ts state `{delta, timestamp, isProcessing}`,
+// first elapsed 1000/60, subsequent delta clamped [1, 40] ms, frozen at idle.
+// Native timebase is the JS-thread clock (packet F1). The `frame` scheduler is not shipped.
+
+export interface FrameData {
+  delta: number
+  timestamp: number
+  isProcessing: boolean
+}
+
+export function createFrameDataState(): FrameData {
+  return { delta: 0, timestamp: 0, isProcessing: false }
+}
+
+/** The public singleton. Mutated in place like the pin's batcher state; never replaced. */
+export const frameData: FrameData = createFrameDataState()
+
+const MAX_ELAPSED_MS = 40
+const DEFAULT_ELAPSED_MS = 1000 / 60
+
+export function applyFrameDataTick(
+  state: FrameData,
+  timestamp: number,
+  isFirstAfterIdle: boolean,
+): void {
+  state.delta = isFirstAfterIdle
+    ? DEFAULT_ELAPSED_MS
+    : Math.max(Math.min(timestamp - state.timestamp, MAX_ELAPSED_MS), 1)
+  state.timestamp = timestamp
+}

package/src/native/motion/gestureBinding.ts

@@ -0,0 +1,107 @@
+// The gesture binding's brain (specs/M2.4-BUILD-PACKET.md): platform Pan events → validated
+// GestureSamples → session calls. The session owns EVERY semantic (dead-zone, continuity,
+// constraints, snap, cancel targets, release springs); this layer owns only (a) fail-loud event
+// shape validation (never coerce a missing field to 0 — the M2.2/M2.3 boundary lesson) and (b) the
+// clock discipline: samples are timestamped off the SAME injectable clock the stepper advances.
+//
+import {
+  createGestureSession,
+  type Clock,
+  type DragConstraints,
+  type GestureSample,
+  type GestureSession,
+  type MotionGraph,
+  type SnapConfig,
+  type SpringConfig,
+} from '@unrulysystems/native-motion-core'
+
+// The fields this binding reads off a gesture-handler Pan event. Kept loose (unknown) because the
+// validation IS the contract — a malformed event fails loud at this boundary.
+export interface PanEventShape {
+  readonly translationX?: unknown
+  readonly velocityX?: unknown
+}
+
+export interface GestureBindingOptions {
+  readonly graph: MotionGraph
+  // The same clock the stepper advances — never Date.now(), never a second time source.
+  readonly clock: Clock
+  readonly initial?: number
+  readonly constraints?: DragConstraints
+  readonly snap?: SnapConfig
+  readonly releaseSpring?: SpringConfig
+}
+
+export interface GestureBinding {
+  onStart(event: PanEventShape): void
+  onUpdate(event: PanEventShape): void
+  onEnd(event: PanEventShape): void
+  onCancel(): void
+  onFail(): void
+  readonly session: GestureSession
+}
+
+// Fail-loud field extraction (packet §semantics 7): a missing or non-numeric recognizer field is a
+// caller/platform bug — naming the field beats silently coercing to 0 and dragging to the origin.
+function requireNumber(value: unknown, field: string): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    throw new Error(
+      `gesture binding: Pan event field '${field}' is ${JSON.stringify(value)} — a finite number ` +
+        'is required and is never coerced (specs/M2.4-BUILD-PACKET.md §semantics 7).',
+    )
+  }
+  return value
+}
+
+export function createGestureBinding(options: GestureBindingOptions): GestureBinding {
+  const session = createGestureSession({
+    graph: options.graph,
+    ...(options.initial === undefined ? {} : { initial: options.initial }),
+    ...(options.constraints === undefined ? {} : { constraints: options.constraints }),
+    ...(options.snap === undefined ? {} : { snap: options.snap }),
+    ...(options.releaseSpring === undefined ? {} : { releaseSpring: options.releaseSpring }),
+  })
+  const clock = options.clock
+
+  // Validate BEFORE any session call so a malformed event never half-applies, and timestamp off the
+  // injected clock — the platform velocity passes through untouched (§G).
+  function toSample(event: PanEventShape): GestureSample {
+    return {
+      t: clock.now(),
+      translation: requireNumber(event.translationX, 'translationX'),
+      velocity: requireNumber(event.velocityX, 'velocityX'),
+    }
+  }
+
+  return {
+    onStart(event) {
+      session.begin(requireNumber(event.translationX, 'translationX'))
+    },
+    onUpdate(event) {
+      session.active(toSample(event))
+    },
+    onEnd(event) {
+      session.end(toSample(event))
+    },
+    onCancel() {
+      session.cancel()
+    },
+    onFail() {
+      session.fail()
+    },
+    session,
+  }
+}
+
+// RNGH end/finalize routing (review cycle 1 major 1): gesture-handler fires `onEnd(event, false)`
+// for gestures that FAIL or are CANCELLED — before `onFinalize(event, false)`. Only a SUCCESSFUL
+// end is a release; an unsuccessful end must leave the session active so the finalize path can
+// cancel to the pre-grab value (REQ-GESTURE-018 totality). These helpers ARE the screen's wiring,
+// exported so the checks drive the exact routing.
+export function routePanEnd(binding: GestureBinding, event: PanEventShape, success: boolean): void {
+  if (success) binding.onEnd(event)
+}
+
+export function routePanFinalize(binding: GestureBinding, success: boolean): void {
+  if (!success && binding.session.state() === 'active') binding.onCancel()
+}