mujoco-react 10.5.0 → 10.7.0

package/dist/onnx.d.ts

@@ -1,5 +1,5 @@
 import * as ort from 'onnxruntime-web';
-import { bq as PolicyActionChunk } from './types-CViUme8D.js';
+import { bq as PolicyActionChunk } from './types-Dvtm4I0o.js';
 import 'react';
 import '@react-three/fiber';
 import 'three';

package/dist/spark.d.ts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as _sparkjsdev_spark from '@sparkjsdev/spark';
-import { o as SplatEnvironmentProps, r as PairedSplatEnvironmentConfig, S as SceneConfig, u as SplatEnvironmentReadiness, p as VisualScenarioConfig } from './types-CViUme8D.js';
+import { o as SplatEnvironmentProps, r as PairedSplatEnvironmentConfig, S as SceneConfig, u as SplatEnvironmentReadiness, p as VisualScenarioConfig } from './types-Dvtm4I0o.js';
 import 'react';
 import '@react-three/fiber';
 import 'three';

package/dist/spark.js

@@ -1,4 +1,4 @@
-import { useSplatSceneConfig, useSplatEnvironment, SplatEnvironment, CAMERA_FRAME_CAPTURE_RENDER_USER_DATA_KEY } from './chunk-KHZ5U36J.js';
+import { useSplatSceneConfig, useSplatEnvironment, SplatEnvironment, CAMERA_FRAME_CAPTURE_RENDER_USER_DATA_KEY } from './chunk-EN55TTGH.js';
 import { useThree } from '@react-three/fiber';
 import { useMemo, useState, useEffect, useCallback, useRef } from 'react';
 import * as THREE from 'three';

package/dist/{types-CViUme8D.d.ts → types-Dvtm4I0o.d.ts}

@@ -540,7 +540,7 @@ interface IkContextValue {
     ikTargetRef: React__default.RefObject<THREE.Group>;
     siteIdRef: React__default.RefObject<number>;
     setIkEnabled: (enabled: boolean) => void;
-    moveTarget: (pos: THREE.Vector3, duration?: number) => void;
+    moveTarget: (pos: IkTargetPosition, duration?: number) => void;
     syncTargetToSite: () => void;
     solveIK: (input: IkSolveInput) => number[] | null;
     getGizmoStats: () => {
@@ -561,9 +561,20 @@ interface PhysicsConfig {
     speed?: number;
 }
 type IKSolveFn = (input: IkSolveInput) => number[] | null;
+type IkTargetPosition = THREE.Vector3 | readonly [number, number, number] | {
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+};
+type IkTargetQuaternion = THREE.Quaternion | readonly [number, number, number, number] | {
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+    readonly w: number;
+};
 interface IkSolveInput {
-    position: THREE.Vector3;
-    quaternion: THREE.Quaternion;
+    position: IkTargetPosition;
+    quaternion: IkTargetQuaternion;
     currentQ: number[];
     context?: IKSolveContext;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mujoco-react",
-  "version": "10.5.0",
+  "version": "10.7.0",
   "description": "Composable React Three Fiber building blocks for MuJoCo WASM simulations",
   "type": "module",
   "main": "./dist/index.js",

package/src/core/GenericIK.ts

@@ -40,13 +40,6 @@ function resolveOptions(opts?: Partial<GenericIKOptions>): ResolvedGenericIKOpti
     };
 }
 
-function clampJoint(value: number, limit: readonly [number, number] | null | undefined) {
-    if (!limit) return value;
-    const [min, max] = limit;
-    if (!Number.isFinite(min) || !Number.isFinite(max) || min >= max) return value;
-    return Math.max(min, Math.min(max, value));
-}
-
 /**
  * Generic Damped Least-Squares IK solver.
  * Uses finite-difference Jacobian via MuJoCo's mj_forward.
@@ -93,7 +86,7 @@ export class GenericIK {
 
         // Working joint angles — start from current configuration
         const q = new Float64Array(n);
-        for (let i = 0; i < n; i++) q[i] = clampJoint(currentQ[i], o.jointLimits?.[i]);
+        for (let i = 0; i < n; i++) q[i] = currentQ[i];
 
         // Pre-allocate work arrays
         const J = new Float64Array(6 * n);       // 6×n Jacobian (row-major)
@@ -108,6 +101,14 @@ export class GenericIK {
 
         let bestQ: number[] | null = null;
         let bestErr = Infinity;
+        // Stop early once the error stops improving. The solver always returns the
+        // best configuration it has seen, so when it stalls or diverges (an
+        // unreachable target, e.g. a near-singular wrist orientation) further
+        // iterations can't beat bestQ — they only burn (1 + n) mj_forward calls
+        // each and feed jitter into ctrl. This is what bounds the cost of dragging
+        // the target into an unreachable region.
+        const patience = 4;
+        let noImprove = 0;
 
         if (n === 0) return null;
 
@@ -145,14 +146,20 @@ export class GenericIK {
             );
 
             // Track best solution
-            if (errNorm < bestErr) {
+            if (errNorm < bestErr - 1e-9) {
                 bestErr = errNorm;
                 bestQ = Array.from(q);
+                noImprove = 0;
+            } else {
+                noImprove++;
             }
 
             // Converged
             if (errNorm < o.tolerance) break;
 
+            // Stalled or diverging — bestQ can no longer improve, so stop.
+            if (noImprove >= patience) break;
+
             // Compute Jacobian via finite differences
             for (let j = 0; j < n; j++) {
                 const adr = qposAdr[j];
@@ -208,7 +215,7 @@ export class GenericIK {
             }
 
             // Update joints
-            for (let i = 0; i < n; i++) q[i] = clampJoint(q[i] + dq[i], o.jointLimits?.[i]);
+            for (let i = 0; i < n; i++) q[i] += dq[i];
         }
 
         // Restore original qpos

package/src/hooks/useIkController.ts

@@ -10,11 +10,31 @@ import { createControllerHook } from '../core/createController';
 import { useMujocoContext, useBeforePhysicsStep } from '../core/MujocoSimProvider';
 import { GenericIK } from '../core/GenericIK';
 import { createContiguousControlGroup, findSiteByName, resolveControlGroup } from '../core/SceneLoader';
-import type { ControlGroupInfo, IkConfig, IkContextValue, IKSolveFn, IkSolveInput, MujocoData } from '../types';
+import type {
+  ControlGroupInfo,
+  IkConfig,
+  IkContextValue,
+  IKSolveFn,
+  IkSolveInput,
+  IkTargetPosition,
+  MujocoData,
+} from '../types';
 
 // Preallocated temp for syncGizmoToSite
 const _syncMat4 = new THREE.Matrix4();
 
+function toIkVector3(value: IkSolveInput['position']): THREE.Vector3 {
+  return 'x' in value
+    ? new THREE.Vector3(value.x, value.y, value.z)
+    : new THREE.Vector3(value[0], value[1], value[2]);
+}
+
+function toIkQuaternion(value: IkSolveInput['quaternion']): THREE.Quaternion {
+  return 'x' in value
+    ? new THREE.Quaternion(value.x, value.y, value.z, value.w)
+    : new THREE.Quaternion(value[0], value[1], value[2], value[3]);
+}
+
 function syncGizmoToSite(data: MujocoData, siteId: number, target: THREE.Group) {
   if (siteId === -1) return;
   const sitePos = data.site_xpos.subarray(siteId * 3, siteId * 3 + 3);
@@ -86,14 +106,22 @@ export const useIkController = createControllerHook<IkConfig, IkContextValue>(
     const ikSolveFn = useCallback(
       ({ position, quaternion, currentQ, context }: IkSolveInput): number[] | null => {
         if (!config) return null;
-        if (config.ikSolveFn) return config.ikSolveFn({ position, quaternion, currentQ, context });
+        const targetPosition = toIkVector3(position);
+        const targetQuaternion = toIkQuaternion(quaternion);
+        const normalizedInput: IkSolveInput = {
+          position: targetPosition,
+          quaternion: targetQuaternion,
+          currentQ,
+          context,
+        };
+        if (config.ikSolveFn) return config.ikSolveFn(normalizedInput);
         const model = mjModelRef.current;
         const data = mjDataRef.current;
         const controlGroup = controlGroupRef.current;
         if (!model || !data || !controlGroup || siteIdRef.current === -1) return null;
         return genericIkRef.current.solve(
           model, data, siteIdRef.current, controlGroup.qposAdr,
-          position, quaternion, currentQ,
+          targetPosition, targetQuaternion, currentQ,
           {
             damping: config.damping,
             epsilon: config.epsilon,
@@ -218,12 +246,12 @@ export const useIkController = createControllerHook<IkConfig, IkContextValue>(
     );
 
     const moveTarget = useCallback(
-      (pos: THREE.Vector3, duration = 0) => {
+      (pos: IkTargetPosition, duration = 0) => {
         if (!ikEnabledRef.current) setIkEnabled(true);
         const target = ikTargetRef.current;
         if (!target) return;
 
-        const targetPos = pos.clone();
+        const targetPos = toIkVector3(pos);
         const targetRot = new THREE.Quaternion().setFromEuler(
           new THREE.Euler(Math.PI, 0, 0),
         );

package/src/index.ts

@@ -97,11 +97,13 @@ export { useBodyState } from './hooks/useBodyState';
 export { useBodyPose, useGeomPose, useSitePose } from './hooks/usePose';
 export type { PoseReadout, PoseResourceKind } from './hooks/usePose';
 export { useCtrl } from './hooks/useCtrl';
-export { controlGroup, useControlGroup } from './hooks/useControlGroup';
+export { controlGroup, defineControls, useControlGroup, useControls } from './hooks/useControlGroup';
 export type {
   ControlGroup,
   ControlGroupHandle,
   ControlGroupSetOptions,
+  ControlsHandle,
+  DefinedControls,
   UseControlGroupOptions,
 } from './hooks/useControlGroup';
 export { useControlWriter } from './hooks/useControlWriter';

package/src/types.ts

@@ -564,7 +564,7 @@ export interface IkContextValue {
   ikTargetRef: React.RefObject<THREE.Group>;
   siteIdRef: React.RefObject<number>;
   setIkEnabled: (enabled: boolean) => void;
-  moveTarget: (pos: THREE.Vector3, duration?: number) => void;
+  moveTarget: (pos: IkTargetPosition, duration?: number) => void;
   syncTargetToSite: () => void;
   solveIK: (input: IkSolveInput) => number[] | null;
   getGizmoStats: () => { pos: THREE.Vector3; rot: THREE.Euler } | null;
@@ -592,9 +592,28 @@ export type IKSolveFn = (
   input: IkSolveInput
 ) => number[] | null;
 
+export type IkTargetPosition =
+  | THREE.Vector3
+  | readonly [number, number, number]
+  | {
+      readonly x: number;
+      readonly y: number;
+      readonly z: number;
+    };
+
+export type IkTargetQuaternion =
+  | THREE.Quaternion
+  | readonly [number, number, number, number]
+  | {
+      readonly x: number;
+      readonly y: number;
+      readonly z: number;
+      readonly w: number;
+    };
+
 export interface IkSolveInput {
-  position: THREE.Vector3;
-  quaternion: THREE.Quaternion;
+  position: IkTargetPosition;
+  quaternion: IkTargetQuaternion;
   currentQ: number[];
   context?: IKSolveContext;
 }