@unrulysystems/native-motion 0.1.0-alpha.0

package/src/native.ts

@@ -0,0 +1,159 @@
+// Native route of the single public import (REQ-UNIVERSAL-001): Metro resolves here via the
+// `react-native` exports condition (newer Metro) or the top-level `react-native` field (older
+// Metro) — the skew check guarantees both point at this file.
+//
+// The native runtime lives in this package (./native/{driver,motion}, extracted at the dogfood
+// rung — specs/DOGFOOD-MIGRATION-BUILD-PACKET.md) but public runtime exports land example-by-
+// example as the M3 migration pulls them (the dogfood-driven surface). Until a capability is
+// pulled, it is absent here and consumer use is a build error — fail-loud by absence, never an
+// interim shape (BRIEF Decisions). Engine verification mounts via the './verification' subpath,
+// which is NOT the product surface.
+
+export type {
+  MotionTargetProps,
+  Target,
+  Transition,
+  TransitionType,
+} from '@unrulysystems/native-motion-core'
+
+// The public native runtime surface, pulled example-by-example (dogfood law), under the
+// RATIFIED universal names the web entry already ships (`View`/`ViewProps`, `Text`/`TextProps`,
+// `Image`/`ImageProps`, and the presence primitives — SPEC-WEB-SHIM/REQ-UNIVERSAL-001): one
+// import, three host components, two engines. `MotionView`/`MotionText`/`MotionImage` stay
+// engine-internal; only universal names are public.
+// Everything else in ./native is engine-internal — hand-wiring the driver or bindings from
+// consumer code is the escape hatch the ban forbids. Cross-entry identity is asserted in
+// type-identity.assert.ts (universal-subset prop assignability, fail-closed at typecheck).
+export {
+  MotionImage as Image,
+  MotionText as Text,
+  MotionView as View,
+  type MotionImageComponentProps as ImageProps,
+  type MotionTextComponentProps as TextProps,
+  type MotionViewComponentProps as ViewProps,
+} from './native/motion/MotionView'
+// AnimatePresenceProps is deliberately not a standalone native export. The shared component prop
+// contract is checked through ComponentProps in type-identity.assert.ts.
+export {
+  AnimatePresence,
+  useIsPresent,
+  usePresence,
+  usePresenceData,
+} from './native/motion/AnimatePresence'
+// T21 (REQ-API-053): the public stagger() helper — ONE pin-golden implementation (core's,
+// floor-verified against motion-utils) shipped by BOTH entries; on web the produced
+// (index, total) => seconds functions feed motion/react's own delayChildren execution.
+export { stagger } from '@unrulysystems/native-motion-core'
+// T23 A: the public mix() utility — ONE core implementation on BOTH entries (the stagger
+// precedent): pin-polymorphic through the value seam, refuse-loud on the arms core does not
+// execute (arrays, objects, CSS vars) so the entries never skew on refusals.
+export { motionMix as mix } from '@unrulysystems/native-motion-core'
+
+// T24 W: the pin's `wrap` page-domain modulo (motion-utils/wrap via the dom barrel), one core
+// implementation on both entries; degenerate domains refuse loud (G-INV-8 posture).
+export { wrap } from '@unrulysystems/native-motion-core'
+// FLAG 5a (REQ-API-022): the public root primitive — on native it owns the platform gesture
+// root; the web entry ships the name with pass-through children (entry key parity). A gesture-
+// carrying View outside it fails loud, never a silently dead gesture.
+export { MotionRoot, type MotionRootProps } from './native/motion/MotionRoot'
+// R10 M1 (REQ-API-035): tree-wide configuration provider — native context so transition
+// defaults and reducedMotion reach every Motion element in the subtree.
+export {
+  MotionConfig,
+  type MotionConfigProps,
+  type MotionConfigTransition,
+  type ReducedMotionConfig,
+} from './native/motion/MotionConfig'
+// R10 M2 (REQ-API-036): layout-identity namespace — native context prefixes descendant
+// layoutIds (id-namespacing half this rung; pin nodeGroup dirty fan-out deferred).
+export {
+  LayoutGroup,
+  type LayoutGroupInherit,
+  type LayoutGroupProps,
+} from './native/motion/LayoutGroup'
+// The Motion (event, info) drag-callback payload shape (REQ-API-020) — the shared core type,
+// re-exported so both entries expose the same name (namespace parity).
+export type { DragInfo, TapCallback, TapInfo } from '@unrulysystems/native-motion-core'
+// T17 (REQ-API-048): the transformTemplate prop's public types — core's shared declarations,
+// both entries (the pin exports TransformTemplate from motion-dom's public root).
+export type { TransformProperties, TransformTemplate } from '@unrulysystems/native-motion-core'
+// Product dual-authority release helpers (REQ-GESTURE-022 absolute origin + project-then-snap).
+// Gallery/examples retarget controlled animate from the same pure selector the engine uses.
+export { absoluteDragOrigin, selectReleaseTarget } from '@unrulysystems/native-motion-core'
+// R4 — the public value channel (REQ-API-025..027): pinned-oracle hook names over CORE's graph;
+// the web entry re-exports motion/react's own hooks under the same names (namespace parity).
+// The MotionValue TYPE is engine-specific by design (core's here, motion's on web). Explicit
+// native contract probes cover its portable shape; the namespace gate covers value names only.
+export {
+  useMotionTemplate,
+  useMotionValue,
+  useMotionValueEvent,
+  useSpring,
+  useTransform,
+  useVelocity,
+  type SpringValueOptions,
+  type TransformOptions,
+} from './native/motion/valueHooks'
+// R11 M1 (REQ-API-037): scroll-fed motion values — UI-thread binding into the R4 value channel.
+export {
+  useScroll,
+  type ScrollMotionValues,
+  type UseScrollOptions,
+} from './native/motion/useScroll'
+// U7i (REQ-API-037(e)): deprecated zero-arg alias of useScroll(); inherits the
+// container-required refusal. Web re-exports the raw pin.
+export { useViewportScroll } from './native/motion/useViewportScroll'
+// R12 M1 (REQ-API-039): imperative surface — standalone animate + useAnimate through the
+// prepared seam (no parallel engine). Public callables are the SHALLOW AnimateFn pair
+// (web-identical shape) so dual-entry type-identity never expands pin overloads.
+export {
+  animate,
+  type AnimateFn,
+  type AnimationPlaybackControls,
+  type AnimationScope,
+} from './native/motion/imperativeAnimate'
+export { useAnimate } from './native/motion/useAnimate'
+// R13 M1 (REQ-API-040): useCycle — pin-faithful item list cycle; web re-exports motion/react.
+export { useCycle, type Cycle, type CycleState } from './native/motion/useCycle'
+// U7a (the REQ-API-027-adjacent hook row): useReducedMotion — the pin's mount-time SNAPSHOT of
+// the OS reduced-motion preference (frozen for the hook's lifetime; no subscription); web
+// re-exports the raw pin.
+export { useReducedMotion } from './native/motion/useReducedMotion'
+// U7b (the instant-transition lane): useInstantTransition opens the GLOBAL instant window — the
+// MotionGlobalConfig.instantAnimations analogue (every starting transition skips its generator
+// and commits its final keyframe on the next update tick, delay zeroed), relocked two
+// post-render frames later under the token guard; disableInstantTransitions is the pin's
+// sibling flag-clear. Web re-exports the raw pin.
+export {
+  disableInstantTransitions,
+  useInstantTransition,
+} from './native/motion/useInstantTransition'
+// R15 D3 (REQ-API-043 / REQ-GESTURE-026): imperative drag hub — pin-faithful start/cancel/stop
+// fan-out; web re-exports motion/react's useDragControls under the same name.
+// DragControlOptions is the shared core type (namespace key parity with the web entry).
+export { DragControls, useDragControls } from './native/motion/dragControls'
+// U7g (REQ-LAYOUT-024): user scale-corrector channel. Web re-exports the raw pin; native
+// requires workletized `correct` functions (F1) and bindable native style keys.
+export { addScaleCorrector } from './native/motion/addScaleCorrector'
+// U7j (REQ-API-058): read-only JS-frame clock. Web re-exports the raw pin; native is fed
+// by the value-channel rAF stepper. The `frame` scheduler is not this unit.
+export { frameData, type FrameData } from './native/motion/frameData'
+// U8 (REQ-API-059): parametric arc path factory. Web re-exports the raw pin; native is core.
+export { arc, type ArcOptions } from '@unrulysystems/native-motion-core'
+export type { DragControlOptions, DragControlsHandle } from '@unrulysystems/native-motion-core'
+// R13 value-breadth (REQ-VALUETYPE-013): parent/viewport geometry for measure-resolved %/calc.
+// Web entry ships a no-op provider (pin measures itself); namespace key parity.
+export {
+  MotionLengthLayoutProvider,
+  type MotionLengthLayoutProviderProps,
+} from './native/motion/lengthLayoutContext'
+// R13 V2 (REQ-LAYOUT-022(c) live-offset): composition feed for container scroll without a new host.
+export {
+  LayoutScrollOffsetProvider,
+  createLayoutScrollOffsetRef,
+  recordLayoutScrollOffsetFromEvent,
+  type LayoutScrollOffset,
+  type LayoutScrollOffsetProviderProps,
+  type LayoutScrollOffsetRef,
+} from './native/motion/layoutScroll'
+export type { MotionValue } from '@unrulysystems/native-motion-core'

package/src/verification/harnessMetrics.ts

@@ -0,0 +1,78 @@
+declare const process:
+  | {
+      readonly env?: {
+        readonly HARNESS?: string
+        readonly EXPO_PUBLIC_HARNESS?: string
+      }
+    }
+  | undefined
+
+export const HARNESS_FRAME_DT_MS = 16.667
+
+export interface FlipMetricTransform {
+  readonly translateX: number
+  readonly translateY: number
+  readonly scaleX: number
+  readonly scaleY: number
+}
+
+export function isHarnessMode(): boolean {
+  if (typeof process === 'undefined') return false
+  return process.env?.HARNESS === '1' || process.env?.EXPO_PUBLIC_HARNESS === '1'
+}
+
+export function schedulerFrameDelta(previousNow: number, now: number): number {
+  if (isHarnessMode()) return HARNESS_FRAME_DT_MS
+  return previousNow === 0 ? 0 : now - previousNow
+}
+
+export interface FlipMetricsTracker {
+  readonly startFlight: () => void
+  readonly sampleTransform: (transform: FlipMetricTransform) => void
+  readonly emitSettled: () => void
+}
+
+export function createFlipMetricsTracker(id: string): FlipMetricsTracker {
+  let active = false
+  let emittedFlights = 0
+  let peakTx = 0
+  let peakTy = 0
+  let minScaleX = 1
+  let minScaleY = 1
+
+  function reset(): void {
+    peakTx = 0
+    peakTy = 0
+    minScaleX = 1
+    minScaleY = 1
+  }
+
+  return {
+    startFlight() {
+      active = true
+      reset()
+    },
+    sampleTransform(transform) {
+      if (!active) return
+      peakTx = Math.max(peakTx, Math.abs(transform.translateX))
+      peakTy = Math.max(peakTy, Math.abs(transform.translateY))
+      minScaleX = Math.min(minScaleX, transform.scaleX)
+      minScaleY = Math.min(minScaleY, transform.scaleY)
+    },
+    emitSettled() {
+      if (!active) return
+      active = false
+      emittedFlights += 1
+      console.log(
+        `FLIP_METRICS ${JSON.stringify({
+          id,
+          flight: emittedFlights,
+          peakTx,
+          peakTy,
+          minScaleX,
+          minScaleY,
+        })}`,
+      )
+    },
+  }
+}

package/src/verification/probe/LayoutIdentityWorkletProbe.tsx

@@ -0,0 +1,251 @@
+// Layout-identity UI-thread crossing probe. The acceptance floor is a real iOS/Android app process
+// that would have crashed before the dist layout worklet tags existed. The screen self-drives two legs:
+// 1. executeOnUIRuntimeSync parity: the same registry/session trajectory runs on JS and UI and is
+//    compared exactly over a fixed frame grid.
+// 2. useFrameCallback liveness: one live UI frame loop steps a registry/session until settle and
+//    reports the single settle edge back to JS.
+// The RN-free probe engine (graph, trajectory, live-leg state machine) lives in
+// layoutIdentityProbeEngine.ts so its reporting semantics are unit-tested off-device.
+
+import { useEffect, useMemo, useRef, useState } from 'react'
+import { StyleSheet, Text, View } from 'react-native'
+import { useFrameCallback } from 'react-native-reanimated'
+import { executeOnUIRuntimeSync, scheduleOnRN } from 'react-native-worklets'
+import {
+  DT_MS,
+  STEPS_PER_LEG,
+  resetLiveProbe,
+  runLayoutIdentityTrajectory,
+  stepLiveProbe,
+} from './layoutIdentityProbeEngine'
+
+const PROBE_LOG_PREFIX = 'LAYOUT_UITHREAD_PROBE '
+const REACT_NATIVE_INFO_LOG_LEVEL = 1
+
+interface ReactNativeLoggingGlobal {
+  nativeLoggingHook?: (message: string, level: number) => void
+}
+
+function logProbeVerdict(report: {
+  readonly pass: boolean
+  readonly parityPass: boolean
+  readonly parityDetail: string
+  readonly livePass: boolean | null
+  readonly liveDetail: string
+}): void {
+  const message = `${PROBE_LOG_PREFIX}${JSON.stringify(report)}`
+  const nativeLoggingHook = (globalThis as ReactNativeLoggingGlobal).nativeLoggingHook
+  if (nativeLoggingHook !== undefined) {
+    nativeLoggingHook(message, REACT_NATIVE_INFO_LOG_LEVEL)
+    return
+  }
+  console.log(message)
+}
+
+type ProbeReport =
+  | {
+      readonly pass: true
+      readonly detail: string
+      readonly sampleRows: readonly {
+        readonly i: number
+        readonly js: number
+        readonly ui: number
+      }[]
+    }
+  | {
+      readonly pass: false
+      readonly detail: string
+      readonly sampleRows: readonly {
+        readonly i: number
+        readonly js: number
+        readonly ui: number | null
+      }[]
+    }
+
+function runParityProbe(): ProbeReport {
+  const js = runLayoutIdentityTrajectory()
+  let ui: ReturnType<typeof runLayoutIdentityTrajectory>
+  try {
+    ui = executeOnUIRuntimeSync(() => {
+      'worklet'
+      return runLayoutIdentityTrajectory()
+    })()
+  } catch (e) {
+    return {
+      pass: false,
+      detail: `UI runtime threw before settle: ${e instanceof Error ? `${e.name}: ${e.message}` : String(e)}`,
+      sampleRows: [0, 240, 1200, js.values.length - 1].map((i) => ({
+        i,
+        js: js.values[i] as number,
+        ui: null,
+      })),
+    }
+  }
+  if (!ui.enterSettled || !ui.exitReleased) {
+    const last = Math.max(0, Math.min(js.values.length, ui.values.length) - 1)
+    return {
+      pass: false,
+      detail:
+        `UI runtime completed without crash but missed lifecycle floor ` +
+        `(enterSettled=${String(ui.enterSettled)}, exitReleased=${String(ui.exitReleased)}, ` +
+        `active=${ui.activeAnimations}, jsActive=${js.activeAnimations})`,
+      sampleRows: [0, 240, 1200, last].map((i) => ({
+        i,
+        js: js.values[i] as number,
+        ui: ui.values[i] as number,
+      })),
+    }
+  }
+  if (!js.enterSettled || !js.exitReleased) {
+    return {
+      pass: false,
+      detail: `JS reference missed lifecycle floor (enterSettled=${String(js.enterSettled)}, exitReleased=${String(js.exitReleased)})`,
+      sampleRows: [],
+    }
+  }
+  if (ui.values.length !== js.values.length) {
+    return {
+      pass: false,
+      detail: `length mismatch: js=${js.values.length} ui=${ui.values.length}`,
+      sampleRows: [],
+    }
+  }
+  for (let i = 0; i < js.values.length; i++) {
+    if (js.values[i] !== ui.values[i]) {
+      return {
+        pass: false,
+        detail: `first divergence at sample ${i}: js=${String(js.values[i])} ui=${String(ui.values[i])}`,
+        sampleRows: [{ i, js: js.values[i] as number, ui: ui.values[i] as number }],
+      }
+    }
+  }
+  return {
+    pass: true,
+    detail: `${STEPS_PER_LEG * 2} layout-identity frames bit-identical; enter settled and exit releasable`,
+    sampleRows: [0, 240, 1200, js.values.length - 1].map((i) => ({
+      i,
+      js: js.values[i] as number,
+      ui: ui.values[i] as number,
+    })),
+  }
+}
+
+export function LayoutIdentityWorkletProbe() {
+  const parity = useMemo(runParityProbe, [])
+  const loggedParity = useRef(false)
+  const loggedVerdict = useRef(false)
+  const [liveDetail, setLiveDetail] = useState('useFrameCallback live leg pending')
+  const [livePass, setLivePass] = useState<boolean | null>(null)
+
+  const frameCallback = useFrameCallback((frame) => {
+    'worklet'
+    const result = stepLiveProbe(frame.timeSincePreviousFrame ?? DT_MS)
+    if (result.report) scheduleOnRN(reportLiveResult, result.pass, result.detail)
+  }, false)
+
+  const liveReported = useRef(false)
+
+  function reportLiveResult(pass: boolean, detail: string): void {
+    // First verdict wins. scheduleOnRN calls queue while the frame callback is being deactivated;
+    // without this latch a later report would overwrite the recorded verdict.
+    if (liveReported.current) return
+    liveReported.current = true
+    setLivePass(pass)
+    setLiveDetail(detail)
+    frameCallback.setActive(false)
+  }
+
+  useEffect(() => {
+    try {
+      executeOnUIRuntimeSync(() => {
+        'worklet'
+        resetLiveProbe()
+      })()
+      frameCallback.setActive(true)
+    } catch (e) {
+      setLivePass(false)
+      setLiveDetail(
+        `live setup threw: ${e instanceof Error ? `${e.name}: ${e.message}` : String(e)}`,
+      )
+    }
+    return () => frameCallback.setActive(false)
+  }, [frameCallback])
+
+  const liveResolved = livePass !== null
+  const pass = parity.pass && livePass === true
+
+  useEffect(() => {
+    if (loggedParity.current) return
+    loggedParity.current = true
+    logProbeVerdict({
+      pass,
+      parityPass: parity.pass,
+      parityDetail: parity.detail,
+      livePass,
+      liveDetail,
+    })
+  }, [liveDetail, livePass, parity.detail, parity.pass, pass])
+
+  useEffect(() => {
+    if (!liveResolved || loggedVerdict.current) return
+    loggedVerdict.current = true
+    logProbeVerdict({
+      pass,
+      parityPass: parity.pass,
+      parityDetail: parity.detail,
+      livePass,
+      liveDetail,
+    })
+  }, [liveDetail, livePass, liveResolved, parity.detail, parity.pass, pass])
+
+  return (
+    <View style={styles.container}>
+      <Text style={styles.title}>Layout identity worklet probe</Text>
+      <Text style={styles.subtitle}>core registry/session on the UI runtime</Text>
+      <View
+        style={[
+          styles.banner,
+          pass ? styles.pass : parity.pass && !liveResolved ? styles.pending : styles.fail,
+        ]}
+      >
+        <Text style={styles.bannerText}>
+          {pass ? 'PASS' : parity.pass && !liveResolved ? 'RUNNING' : 'FAIL'}
+        </Text>
+      </View>
+      <Text style={styles.detail}>sync parity: {parity.detail}</Text>
+      <Text style={styles.detail}>live frame: {liveDetail}</Text>
+      <View style={styles.table}>
+        {parity.sampleRows.map((row) => (
+          <Text key={row.i} style={styles.row}>
+            sample {row.i}: js={row.js.toFixed(6)} ui={row.ui === null ? '-' : row.ui.toFixed(6)}
+          </Text>
+        ))}
+      </View>
+      <Text style={styles.footer}>
+        Acceptance requires a real device/simulator screenshot showing PASS and the captured
+        verdict.
+      </Text>
+    </View>
+  )
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    backgroundColor: '#0b0b12',
+    alignItems: 'center',
+    justifyContent: 'center',
+    paddingHorizontal: 24,
+  },
+  title: { color: '#fff', fontSize: 23, fontWeight: '700', textAlign: 'center' },
+  subtitle: { color: '#8a8aa0', fontSize: 13, marginTop: 6, marginBottom: 24, textAlign: 'center' },
+  banner: { paddingHorizontal: 40, paddingVertical: 14, borderRadius: 12 },
+  pass: { backgroundColor: '#1d7a3e' },
+  pending: { backgroundColor: '#6b5f1d' },
+  fail: { backgroundColor: '#a32633' },
+  bannerText: { color: '#fff', fontSize: 30, fontWeight: '800', letterSpacing: 2 },
+  detail: { color: '#c9c9d8', fontSize: 13, marginTop: 18, textAlign: 'center' },
+  table: { marginTop: 20 },
+  row: { color: '#6f6f85', fontSize: 12, fontFamily: 'Menlo', marginTop: 4 },
+  footer: { color: '#77778a', fontSize: 11, marginTop: 26, textAlign: 'center' },
+})

package/src/verification/probe/WorkletParityProbe.tsx

@@ -0,0 +1,162 @@
+// M2.1 worklet-parity probe (specs/M2.1-BUILD-PACKET.md, Milestone 2). The same spring trajectory is
+// computed twice over an identical manual sample grid — once on the JS thread, once inside a UI-thread
+// worklet — and compared EXACTLY. Both legs run the same Hermes engine, so any divergence (or a failed
+// crossing) is a finding, not noise. The probe renders its evidence on screen so a device screenshot IS
+// the proof artifact; a crossing error is caught and DISPLAYED (fail-loud on screen — the probe's whole
+// purpose is to capture that exact text), never swallowed.
+
+import { StyleSheet, Text, View } from 'react-native'
+import { executeOnUIRuntimeSync } from 'react-native-worklets'
+import {
+  resolveSpringGenerator,
+  stepProp,
+  type PropStep,
+  type SpringConfig,
+} from '@unrulysystems/native-motion-core'
+
+// The shared grid + spring. Underdamped (motion's default feel) so the trajectory oscillates rather
+// than settling monotonically — the richest of the regime code paths. 120 frames ≈ 2s at 60Hz.
+const FROM = 0
+const TARGET = 220
+const STEPS = 120
+const DT_MS = 16.67
+const SPRING: SpringConfig = { stiffness: 100, damping: 10, mass: 1 }
+
+// One leg of the probe: seed a spring generator and step it across the grid — core's real per-frame
+// path (resolveSpringGenerator → factory → stepProp), no shortcuts. This exact function body must be
+// executable on BOTH runtimes; the UI leg re-states it inside a worklet because the generator closure
+// cannot cross runtimes (it must be constructed where it runs).
+function jsLegTrajectory(): number[] {
+  const factory = resolveSpringGenerator(TARGET, SPRING)
+  const generator = factory({ from: FROM, velocity: 0 })
+  const prop: PropStep = { generator, elapsed: 0, value: FROM, done: false }
+  const values: number[] = []
+  for (let i = 0; i < STEPS; i++) {
+    stepProp(prop, DT_MS)
+    values.push(prop.value)
+  }
+  return values
+}
+
+type UiLegResult =
+  | { readonly ok: true; readonly values: readonly number[] }
+  | { readonly ok: false; readonly error: string }
+
+// The UI-thread leg — packet §The crossing, mechanism 2 (direct import). RED was observed with a
+// sentinel body first (apps/mobile/docs/proof/m21-probe-red-ios.png). The generator is CONSTRUCTED
+// inside the worklet — a JS-built closure cannot cross runtimes — so the crossing under test is the
+// imported core functions themselves (resolveSpringGenerator, stepProp). The try/catch is the probe's
+// evidence capture, not suppression: a failed crossing must render its exact error on screen.
+function uiLegTrajectory(): UiLegResult {
+  try {
+    const values = executeOnUIRuntimeSync((): number[] => {
+      'worklet'
+      const factory = resolveSpringGenerator(TARGET, SPRING)
+      const generator = factory({ from: FROM, velocity: 0 })
+      const prop: PropStep = { generator, elapsed: 0, value: FROM, done: false }
+      const out: number[] = []
+      for (let i = 0; i < STEPS; i++) {
+        stepProp(prop, DT_MS)
+        out.push(prop.value)
+      }
+      return out
+    })()
+    return { ok: true, values }
+  } catch (e) {
+    return { ok: false, error: e instanceof Error ? `${e.name}: ${e.message}` : String(e) }
+  }
+}
+
+interface ProbeReport {
+  readonly pass: boolean
+  readonly detail: string
+  readonly sampleRows: readonly {
+    readonly i: number
+    readonly js: number
+    readonly ui: number | null
+  }[]
+}
+
+// Compare the two legs exactly (===, epsilon 0): same engine, same doubles, same code path — bitwise
+// agreement is the claim under test. First divergence index + both values become the on-screen detail.
+function runProbe(): ProbeReport {
+  const js = jsLegTrajectory()
+  const ui = uiLegTrajectory()
+  if (!ui.ok) {
+    return {
+      pass: false,
+      detail: `UI leg failed to run: ${ui.error}`,
+      sampleRows: [0, 30, 60, 119].map((i) => ({ i, js: js[i] as number, ui: null })),
+    }
+  }
+  if (ui.values.length !== js.length) {
+    return {
+      pass: false,
+      detail: `length mismatch: js=${js.length} ui=${ui.values.length}`,
+      sampleRows: [],
+    }
+  }
+  for (let i = 0; i < js.length; i++) {
+    if (js[i] !== ui.values[i]) {
+      return {
+        pass: false,
+        detail: `first divergence at step ${i}: js=${js[i]} ui=${ui.values[i]}`,
+        sampleRows: [i].map((k) => ({ i: k, js: js[k] as number, ui: ui.values[k] as number })),
+      }
+    }
+  }
+  return {
+    pass: true,
+    detail: `${STEPS} steps bit-identical (dt=${DT_MS}ms, spring k=${SPRING.stiffness} c=${SPRING.damping})`,
+    sampleRows: [0, 30, 60, 119].map((i) => ({
+      i,
+      js: js[i] as number,
+      ui: ui.values[i] as number,
+    })),
+  }
+}
+
+export function WorkletParityProbe() {
+  // Computed synchronously at render: the probe is deterministic and cheap (240 analytic samples), and
+  // a synchronous result guarantees any screenshot shows the final verdict, never a loading state.
+  const report = runProbe()
+
+  return (
+    <View style={styles.container}>
+      <Text style={styles.title}>M2.1 worklet parity probe</Text>
+      <Text style={styles.subtitle}>
+        core stepProp: JS thread vs UI-thread worklet, {STEPS} steps @ {DT_MS}ms
+      </Text>
+      <View style={[styles.banner, report.pass ? styles.pass : styles.fail]}>
+        <Text style={styles.bannerText}>{report.pass ? 'PASS' : 'FAIL'}</Text>
+      </View>
+      <Text style={styles.detail}>{report.detail}</Text>
+      <View style={styles.table}>
+        {report.sampleRows.map((row) => (
+          <Text key={row.i} style={styles.row}>
+            step {row.i}: js={row.js.toFixed(6)} ui={row.ui === null ? '—' : row.ui.toFixed(6)}
+          </Text>
+        ))}
+      </View>
+    </View>
+  )
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    backgroundColor: '#0b0b12',
+    alignItems: 'center',
+    justifyContent: 'center',
+    paddingHorizontal: 24,
+  },
+  title: { color: '#fff', fontSize: 24, fontWeight: '700' },
+  subtitle: { color: '#8a8aa0', fontSize: 13, marginTop: 6, marginBottom: 28, textAlign: 'center' },
+  banner: { paddingHorizontal: 48, paddingVertical: 14, borderRadius: 12 },
+  pass: { backgroundColor: '#1d7a3e' },
+  fail: { backgroundColor: '#a32633' },
+  bannerText: { color: '#fff', fontSize: 32, fontWeight: '800', letterSpacing: 2 },
+  detail: { color: '#c9c9d8', fontSize: 13, marginTop: 20, textAlign: 'center' },
+  table: { marginTop: 24 },
+  row: { color: '#6f6f85', fontSize: 12, fontFamily: 'Menlo', marginTop: 4 },
+})