@unrulysystems/native-motion 0.1.0-alpha.0

package/src/native/motion/nativeHostMarker.ts

@@ -0,0 +1,22 @@
+const NATIVE_MOTION_HOST = Symbol.for('unrulysystems.native-motion.host')
+
+type MarkedHost = {
+  readonly [NATIVE_MOTION_HOST]?: true
+}
+
+export function markNativeMotionHost<T extends object>(component: T): T {
+  Object.defineProperty(component, NATIVE_MOTION_HOST, {
+    configurable: false,
+    enumerable: false,
+    value: true,
+    writable: false,
+  })
+  return component
+}
+
+export function isNativeMotionHost(component: unknown): boolean {
+  if ((typeof component !== 'function' && typeof component !== 'object') || component === null) {
+    return false
+  }
+  return (component as MarkedHost)[NATIVE_MOTION_HOST] === true
+}

package/src/native/motion/panSessionWiring.ts

@@ -0,0 +1,127 @@
+// R15 D6 (REQ-API-047 / REQ-GESTURE-029): observation-only pan session callbacks.
+// Mounted when any onPan* is present without a drag surface. Never writes the motion graph.
+
+import { describeValue, type DragInfo } from '@unrulysystems/native-motion-core'
+import type { DragPanEventShape } from './dragHandoffBinding'
+
+/** RNGH pan event fields the session reads (translation + absolute for point). */
+type PanEventShape = DragPanEventShape & {
+  readonly absoluteX?: unknown
+  readonly absoluteY?: unknown
+}
+
+export type PanEventCallback = (event: unknown, info: DragInfo) => void
+// Pin's onPanSessionStart carries EventInfo (point only); we pass the same shape.
+export type PanSessionStartCallback = (
+  event: unknown,
+  info: { point: { x: number; y: number } },
+) => void
+
+export interface PanSessionCallbacks {
+  readonly onPanSessionStart?: PanSessionStartCallback | undefined
+  readonly onPanStart?: PanEventCallback | undefined
+  readonly onPan?: PanEventCallback | undefined
+  readonly onPanEnd?: PanEventCallback | undefined
+}
+
+// Pin PanSession activates after ~3px movement (distanceThreshold default).
+export const PAN_ACTIVATION_THRESHOLD_PX = 3
+
+function requireNumber(value: unknown, field: string): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    throw new Error(
+      `pan session: field '${field}' is ${describeValue(value)} — a finite number is required (REQ-API-047).`,
+    )
+  }
+  return value
+}
+
+export interface PanSessionWiring {
+  handlePanStart(event: PanEventShape): void
+  handlePanUpdate(event: PanEventShape): void
+  handlePanEnd(event: PanEventShape, success: boolean): void
+  handlePanFinalize(event: PanEventShape, success: boolean): void
+  dispose(): void
+}
+
+export function createPanSessionWiring(callbacks: PanSessionCallbacks): PanSessionWiring {
+  let disposed = false
+  let sessionStarted = false
+  let panActivated = false
+  let endFired = false
+  let lastTranslation: { x: number; y: number } | null = null
+
+  function buildInfo(event: PanEventShape): DragInfo {
+    const tx = requireNumber(event.translationX, 'translationX')
+    const ty = requireNumber(event.translationY, 'translationY')
+    const vx = requireNumber(event.velocityX, 'velocityX')
+    const vy = requireNumber(event.velocityY, 'velocityY')
+    const ax = requireNumber(event.absoluteX, 'absoluteX')
+    const ay = requireNumber(event.absoluteY, 'absoluteY')
+    const prev = lastTranslation
+    return {
+      point: { x: ax, y: ay },
+      delta: { x: tx - (prev?.x ?? 0), y: ty - (prev?.y ?? 0) },
+      offset: { x: tx, y: ty },
+      velocity: { x: vx, y: vy },
+    }
+  }
+
+  function reset(): void {
+    sessionStarted = false
+    panActivated = false
+    endFired = false
+    lastTranslation = null
+  }
+
+  return {
+    handlePanStart(event) {
+      if (disposed) return
+      reset()
+      sessionStarted = true
+      const ax = requireNumber(event.absoluteX, 'absoluteX')
+      const ay = requireNumber(event.absoluteY, 'absoluteY')
+      callbacks.onPanSessionStart?.(event, { point: { x: ax, y: ay } })
+    },
+    handlePanUpdate(event) {
+      if (disposed || !sessionStarted) return
+      const info = buildInfo(event)
+      lastTranslation = { x: info.offset.x, y: info.offset.y }
+      if (!panActivated) {
+        const dist = Math.hypot(info.offset.x, info.offset.y)
+        if (dist < PAN_ACTIVATION_THRESHOLD_PX) return
+        panActivated = true
+        callbacks.onPanStart?.(event, info)
+      }
+      callbacks.onPan?.(event, info)
+    },
+    handlePanEnd(event, _success) {
+      // Pin PanSession: onEnd only when startEvent is set (past distanceThreshold).
+      // Pure taps under threshold get session start only — never onPanEnd.
+      if (disposed || !sessionStarted || endFired || !panActivated) return
+      endFired = true
+      try {
+        const info = buildInfo(event)
+        callbacks.onPanEnd?.(event, info)
+      } catch {
+        // Malformed end fields — once-gate still holds; finalize will not re-fire.
+      }
+    },
+    handlePanFinalize(event, _success) {
+      if (disposed) return
+      if (sessionStarted && panActivated && !endFired) {
+        endFired = true
+        try {
+          callbacks.onPanEnd?.(event, buildInfo(event))
+        } catch {
+          // Malformed finalize after abort — session is over.
+        }
+      }
+      reset()
+    },
+    dispose() {
+      disposed = true
+      reset()
+    },
+  }
+}

package/src/native/motion/pathTransition.ts

@@ -0,0 +1,101 @@
+// U8 (REQ-API-059) — claim x/y from a start/retarget when `transition.path` is `arc()`.
+import { type DriverCommand, type Transition } from '@unrulysystems/native-motion-core'
+import {
+  isNativeArcPath,
+  resolveTransitionForKey,
+} from '@unrulysystems/native-motion-core/internal-driver'
+
+function stripPath(transition: Transition): Transition {
+  const { path: _path, ...rest } = transition as Transition & { path?: unknown }
+  return rest
+}
+
+function lastNumeric(value: unknown, fallback: number): number {
+  if (typeof value === 'number') return value
+  if (Array.isArray(value) && value.length > 0) {
+    const last = value[value.length - 1]
+    if (typeof last === 'number') return last
+  }
+  return fallback
+}
+
+function firstNumeric(value: unknown, fallback: number): number {
+  if (Array.isArray(value) && typeof value[0] === 'number') return value[0]
+  return fallback
+}
+
+export function seedPathRotationKey(
+  registered: Record<string, number>,
+  transition: Transition | undefined,
+): void {
+  const path = (transition as { path?: unknown } | undefined)?.path
+  if (!isNativeArcPath(path)) return
+  const geometry = path.resolve({ x: 0, y: 0 }, { x: 0, y: 0 })
+  if (geometry.rotationScale) registered.pathRotation = 0
+}
+
+export function rewritePathCommands(
+  command: DriverCommand,
+  committed: () => Readonly<Record<string, number>>,
+): DriverCommand[] {
+  if (command.kind !== 'start' && command.kind !== 'retarget') return [command]
+  const rawPath = (command.transition as { path?: unknown } | undefined)?.path
+  if (!isNativeArcPath(rawPath)) return [command]
+  const hasX = Object.prototype.hasOwnProperty.call(command.targets, 'x')
+  const hasY = Object.prototype.hasOwnProperty.call(command.targets, 'y')
+  if (!hasX && !hasY) return [command]
+
+  // Lazy: the committed snapshot is read only once a path command actually claims x/y — an
+  // unconditional read here added a second removal-boundary snapshot to every presence exit
+  // (REQ-PRESENCE-020's one-read floor).
+  const live = committed()
+  const liveX = live.x ?? 0
+  const liveY = live.y ?? 0
+  let fromX = liveX
+  let fromY = liveY
+  let toX = liveX
+  let toY = liveY
+  if (command.kind === 'start') {
+    const xt = command.targets.x
+    const yt = command.targets.y
+    if (xt !== undefined) {
+      fromX = firstNumeric(xt.to, xt.from)
+      toX = lastNumeric(xt.to, fromX)
+    }
+    if (yt !== undefined) {
+      fromY = firstNumeric(yt.to, yt.from)
+      toY = lastNumeric(yt.to, fromY)
+    }
+  } else {
+    if (hasX) toX = command.targets.x as number
+    if (hasY) toY = command.targets.y as number
+  }
+
+  const geometry = rawPath.resolve({ x: fromX, y: fromY }, { x: toX, y: toY })
+  const progressTransition = resolveTransitionForKey(stripPath(command.transition), 'x')
+  const restTargets = { ...command.targets } as Record<string, never>
+  delete restTargets.x
+  delete restTargets.y
+  const pathStart: DriverCommand = {
+    kind: 'start',
+    targets: command.kind === 'start' ? restTargets : {},
+    transition: stripPath(command.transition),
+    path: { ...geometry, transition: progressTransition },
+    ...(command.kind === 'start' && command.releasesGesture !== undefined
+      ? { releasesGesture: command.releasesGesture }
+      : {}),
+  }
+  if (command.kind === 'start') return [pathStart]
+  if (Object.keys(restTargets).length === 0) return [pathStart]
+  return [
+    pathStart,
+    {
+      kind: 'retarget',
+      targets: restTargets as unknown as Record<string, number>,
+      transition: stripPath(command.transition),
+      ...(command.targetTransitions === undefined
+        ? {}
+        : { targetTransitions: command.targetTransitions }),
+    },
+  ]
+}

package/src/native/motion/popLayout.ts

@@ -0,0 +1,176 @@
+// T24 P — the native PopChild geometry seam. React Native reports parent-relative layout boxes;
+// the presence renderer captures the last committed one and composes the temporary absolute
+// override on the retained exit clone. No layout math or driver crossing belongs here.
+
+export interface PopLayoutRect {
+  readonly x: number
+  readonly y: number
+  readonly width: number
+  readonly height: number
+  readonly parentWidth: number
+  readonly parentHeight: number
+  readonly direction: 'ltr' | 'rtl'
+}
+
+type PopLayoutStyle = Readonly<{
+  position: 'absolute'
+  width: number
+  height: number
+  left?: number | undefined
+  right?: number | undefined
+  top?: number | undefined
+  bottom?: number | undefined
+}>
+
+export interface PopLayoutHostHandle {
+  readonly parentElement?: {
+    readonly clientWidth?: unknown
+    readonly clientHeight?: unknown
+  } | null
+}
+
+let defaultDirection: 'ltr' | 'rtl' = 'ltr'
+
+/** The native public entry binds the platform's inherited writing direction once at startup. */
+export function configurePopLayoutDefaultDirection(direction: 'ltr' | 'rtl'): void {
+  defaultDirection = direction
+}
+
+function authoredDirection(style: unknown): 'ltr' | 'rtl' | undefined {
+  if (Array.isArray(style)) {
+    for (let index = style.length - 1; index >= 0; index--) {
+      const resolved = authoredDirection(style[index])
+      if (resolved !== undefined) return resolved
+    }
+    return undefined
+  }
+  if (typeof style !== 'object' || style === null) return undefined
+  const direction = (style as { readonly direction?: unknown }).direction
+  return direction === 'ltr' || direction === 'rtl' ? direction : undefined
+}
+
+export function resolvePopLayoutDirection(style: unknown): 'ltr' | 'rtl' {
+  return authoredDirection(style) ?? defaultDirection
+}
+
+function describeLayoutField(value: unknown): string {
+  if (typeof value === 'bigint') return `${value}n`
+  try {
+    const serialized = JSON.stringify(value)
+    return serialized === undefined ? String(value) : serialized
+  } catch {
+    return Object.prototype.toString.call(value)
+  }
+}
+
+function finiteLayoutField(value: unknown, field: string): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    throw new Error(
+      `popLayout onLayout field '${field}' is ${describeLayoutField(value)}; expected a finite number`,
+    )
+  }
+  return value
+}
+
+function parentDimension(value: unknown): number {
+  return typeof value === 'number' && Number.isFinite(value) ? value : 0
+}
+
+function readParentBox(host: PopLayoutHostHandle | null | undefined): {
+  readonly parentWidth: number
+  readonly parentHeight: number
+} {
+  const parent = host?.parentElement
+  return {
+    parentWidth: parentDimension(parent?.clientWidth),
+    parentHeight: parentDimension(parent?.clientHeight),
+  }
+}
+
+/** Read one native layout event; absent layout is the pin's unmeasured-child no-op. */
+export function readPopLayoutRect(
+  event: unknown,
+  host?: PopLayoutHostHandle | null,
+  direction: 'ltr' | 'rtl' = 'ltr',
+): PopLayoutRect | undefined {
+  if (typeof event !== 'object' || event === null) return undefined
+  const nativeEvent = (event as { readonly nativeEvent?: unknown }).nativeEvent
+  if (typeof nativeEvent !== 'object' || nativeEvent === null) return undefined
+  const layout = (nativeEvent as { readonly layout?: unknown }).layout
+  if (layout === undefined) return undefined
+  if (typeof layout !== 'object' || layout === null) {
+    throw new Error('popLayout onLayout layout must be an object with x, y, width, and height')
+  }
+  const shape = layout as Record<string, unknown>
+  return Object.freeze({
+    x: finiteLayoutField(shape['x'], 'x'),
+    y: finiteLayoutField(shape['y'], 'y'),
+    width: finiteLayoutField(shape['width'], 'width'),
+    height: finiteLayoutField(shape['height'], 'height'),
+    ...readParentBox(host),
+    direction,
+  })
+}
+
+/** Refresh the parent box at the removal boundary, matching the pin's snapshot timing. */
+export function refreshPopLayoutRect(
+  rect: PopLayoutRect,
+  host: PopLayoutHostHandle | null | undefined,
+  direction: 'ltr' | 'rtl' = rect.direction,
+): PopLayoutRect {
+  return Object.freeze({ ...rect, ...readParentBox(host), direction })
+}
+
+function popLayoutOverride(
+  rect: PopLayoutRect | undefined,
+  anchorX: 'left' | 'right' = 'left',
+  anchorY: 'top' | 'bottom' = 'top',
+): PopLayoutStyle | undefined {
+  if (rect === undefined || rect.width === 0 || rect.height === 0) return undefined
+  const isRTL = rect.direction === 'rtl'
+  const horizontal =
+    anchorX === 'left'
+      ? isRTL
+        ? { left: undefined, right: rect.parentWidth - rect.width - rect.x }
+        : { left: rect.x, right: undefined }
+      : isRTL
+        ? { left: rect.x, right: undefined }
+        : { left: undefined, right: rect.parentWidth - rect.width - rect.x }
+  const vertical =
+    anchorY === 'bottom'
+      ? { top: undefined, bottom: rect.parentHeight - rect.height - rect.y }
+      : { top: rect.y, bottom: undefined }
+  return {
+    position: 'absolute',
+    ...horizontal,
+    ...vertical,
+    width: rect.width,
+    height: rect.height,
+  }
+}
+
+/** Compose after authored style so the temporary pop box has override precedence. */
+export function composePopLayoutStyle(
+  authoredStyle: unknown,
+  rect: PopLayoutRect | undefined,
+  anchorX: 'left' | 'right' = 'left',
+  anchorY: 'top' | 'bottom' = 'top',
+): unknown {
+  const override = popLayoutOverride(rect, anchorX, anchorY)
+  if (override === undefined) return authoredStyle
+  if (authoredStyle === undefined || authoredStyle === null) return override
+  return [authoredStyle, override]
+}
+
+export function composePopLayoutOnLayout(
+  authoredOnLayout: unknown,
+  capture: (event: unknown) => void,
+): ((event: unknown) => void) | undefined {
+  if (authoredOnLayout !== undefined && typeof authoredOnLayout !== 'function') {
+    throw new Error('popLayout onLayout must be a function when supplied')
+  }
+  return (event: unknown): void => {
+    capture(event)
+    ;(authoredOnLayout as ((event: unknown) => void) | undefined)?.(event)
+  }
+}