mujoco-react 10.6.0 → 10.8.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { M as MujocoContextValue, a as MujocoCanvasProps, b as MujocoSimAPI, S as SceneConfig, R as ReadyCallbackInput, c as StepCallbackInput, d as SelectionCallbackInput, e as MujocoModule, f as MujocoRenderOptions, P as PhysicsStepCallback, g as MujocoModel, h as MujocoData, C as ControlGroupInfo, A as ActuatedJointInfo, i as ControlGroupSelector, O as ObservationConfig, j as ObservationResult, I as IkConfig, k as IkContextValue, B as BodyProps, l as IkGizmoProps, D as DragInteractionProps, m as SceneLightsProps, n as ScenarioLightingProps, o as SplatEnvironmentProps, V as VisualScenarioEffectsProps, p as VisualScenarioConfig, q as SplatRendererKind, r as PairedSplatEnvironmentConfig, s as SplatFormat, t as SplatCollisionProxyConfig, u as SplatEnvironmentReadiness, v as SplatCollisionPrimitive, w as SplatEnvironmentReadinessStatus, x as SplatSceneConfigInput, y as SplatSceneConfigState, z as VisualScenarioExecutionContextInput, E as VisualScenarioExecutionContext, F as ScenarioLightingPreset, G as SplatEnvironmentMetadataInput, H as SplatEnvironmentMetadata, J as SplatSceneInput, K as CameraFrameCaptureOptions, L as DebugProps, N as GeomInfo, Q as ContactListenerProps, T as TrajectoryPlayerProps, U as ActuatorInfo, W as Sites, X as SitePositionResult, Y as Sensors, Z as SensorHandle, _ as SensorInfo, $ as Joints, a0 as ScalarJointStateResult, a1 as ArrayJointStateResult, a2 as JointStateOptions, a3 as JointStateResult, a4 as Bodies, a5 as BodyStateResult, a6 as Geoms, a7 as Actuators, a8 as CtrlHandle, a9 as ContactInfo, aa as KeyboardTeleopConfig, ab as KeyboardIkTargetConfig, ac as PolicyConfig, ad as PolicyAPI, ae as RemotePolicyConfig, af as RemotePolicyAPI, ag as ObservationHandle, ah as ObservationOutput, ai as TrajectoryInput, aj as TrajectoryStateChangeInput, ak as PlaybackState, al as TrajectoryFrame, am as FrameCaptureOptions, an as FrameCaptureResult, ao as FrameCaptureBlobResult, ap as FrameCaptureAPI, aq as CameraFrameCaptureAPI, ar as Cameras, as as CameraFrameSequenceCamera, at as CameraFrameCaptureSource, au as CameraFrameSequenceOptions, av as CameraFrameSequenceResult, aw as PolicyCameraFrameStream, ax as PolicyCameraFrameCaptureOptions, ay as PolicyCameraFrameCaptureResult, az as FrameCaptureStatus, aA as PolicyCameraFrameCaptureAPI, aB as CameraFrameCaptureTensorOptions, aC as CameraFrameTensorResult, aD as CameraFrameSequenceRecorderAPI, aE as ImagePointCoordinateSpace, aF as ImagePointProjectionOptions, aG as ImagePointProjectionResult, aH as PolicyVector } from './types-Dvtm4I0o.js';
-export { aI as BodyInfo, aJ as CAMERA_FRAME_CAPTURE_PRE_RENDER_USER_DATA_KEY, aK as CAMERA_FRAME_CAPTURE_RENDER_USER_DATA_KEY, aL as CAPTURE_EXCLUDE_KEY, aM as CameraFrameCaptureBlobResult, aN as CameraFrameCaptureQuaternion, aO as CameraFrameCaptureResult, aP as CameraFrameCaptureSession, aQ as CameraFrameCaptureVector3, aR as CameraFramePixelsResult, aS as CameraFrameSequenceCameraSummary, aT as CameraFrameSequenceFrame, aU as CameraFrameSequenceSampleInput, aV as CameraFrameSequenceStepInput, aW as CameraInfo, aX as ControlJointInfo, aY as DebugVirtualCamera, aZ as FrameCaptureTarget, a_ as FrameCaptureTargetRef, a$ as IKSolveFn, b0 as IkGizmoDragInput, b1 as IkSolveInput, b2 as JointInfo, b3 as JointStateKind, b4 as KeyBinding, b5 as KeyboardIkTargetAction, b6 as KeyboardIkTargetBinding, b7 as Keyframes, b8 as ModelActuators, b9 as ModelBodies, ba as ModelCameras, bb as ModelGeoms, bc as ModelJoints, bd as ModelKeyframes, be as ModelOptions, bf as ModelResource, bg as ModelResources, bh as ModelSensors, bi as ModelSites, bj as Models, bk as MujocoContact, bl as MujocoContactArray, bm as MujocoFrameCaptureOptions, bn as ObservationLayoutItem, bo as PhysicsConfig, bp as PhysicsStepInput, bq as PolicyActionChunk, br as PolicyActionInput, bs as PolicyImageTensorLayout, bt as PolicyImageTensorOptions, bu as PolicyImageTensorPixelOptions, bv as PolicyImageTensorRange, bw as PolicyImageTensorResult, bx as PolicyImageTensorSourceOrigin, by as PolicyInferenceInput, bz as PolicyInferenceOutput, bA as PolicyInferenceResult, bB as PolicyObservationInput, bC as RayHit, bD as Register, bE as RegisteredModelMap, bF as RemotePolicyRequestInfo, bG as RemotePolicyRequestInput, bH as RemotePolicyResponseInfo, bI as RemotePolicyStatus, bJ as ResetCallbackInput, bK as ResolvedScenarioCameraConfig, bL as ResolvedScenarioMaterialConfig, bM as ResourceSelector, bN as ScenarioCameraConfig, bO as ScenarioMaterialConfig, bP as SceneMarker, bQ as SceneObject, bR as SensorResult, bS as SiteInfo, bT as SplatAssetConfig, bU as SplatScenarioConfig, bV as StateSnapshot, bW as TrajectoryData, bX as TrajectoryFrameCallbackInput, bY as VisualScenarioMaterialFilterInput, bZ as XmlPatch, b_ as captureCameraFrame, b$ as captureCameraFrameBlob, c0 as captureCameraFrameTensor, c1 as createCameraFrameCaptureSession, c2 as dataUrlToPolicyImageTensor, c3 as getContact, c4 as imageDataToPolicyImageTensor, c5 as pixelsToPolicyImageTensor, c6 as registerModelResources, c7 as renderCameraFrameToCanvas } from './types-Dvtm4I0o.js';
+import { M as MujocoContextValue, a as MujocoCanvasProps, b as MujocoSimAPI, S as SceneConfig, R as ReadyCallbackInput, c as StepCallbackInput, d as SelectionCallbackInput, e as MujocoModule, f as MujocoRenderOptions, P as PhysicsStepCallback, g as MujocoModel, h as MujocoData, C as ControlGroupInfo, A as ActuatedJointInfo, i as ControlGroupSelector, O as ObservationConfig, j as ObservationResult, I as IkConfig, k as IkContextValue, B as BodyProps, l as IkGizmoProps, D as DragInteractionProps, m as SceneLightsProps, n as ScenarioLightingProps, o as SplatEnvironmentProps, V as VisualScenarioEffectsProps, p as VisualScenarioConfig, q as SplatRendererKind, r as PairedSplatEnvironmentConfig, s as SplatFormat, t as SplatCollisionProxyConfig, u as SplatEnvironmentReadiness, v as SplatCollisionPrimitive, w as SplatEnvironmentReadinessStatus, x as SplatSceneConfigInput, y as SplatSceneConfigState, z as VisualScenarioExecutionContextInput, E as VisualScenarioExecutionContext, F as ScenarioLightingPreset, G as SplatEnvironmentMetadataInput, H as SplatEnvironmentMetadata, J as SplatSceneInput, K as CameraFrameCaptureOptions, L as DebugProps, N as GeomInfo, Q as ContactListenerProps, T as TrajectoryPlayerProps, U as ActuatorInfo, W as Sites, X as SitePositionResult, Y as Sensors, Z as SensorHandle, _ as SensorInfo, $ as Joints, a0 as ScalarJointStateResult, a1 as ArrayJointStateResult, a2 as JointStateOptions, a3 as JointStateResult, a4 as Bodies, a5 as BodyStateResult, a6 as Geoms, a7 as Actuators, a8 as CtrlHandle, a9 as ContactInfo, aa as KeyboardTeleopConfig, ab as KeyboardIkTargetConfig, ac as PolicyConfig, ad as PolicyAPI, ae as RemotePolicyConfig, af as RemotePolicyAPI, ag as ObservationHandle, ah as ObservationOutput, ai as TrajectoryInput, aj as TrajectoryStateChangeInput, ak as PlaybackState, al as TrajectoryFrame, am as FrameCaptureOptions, an as FrameCaptureResult, ao as FrameCaptureBlobResult, ap as FrameCaptureAPI, aq as CameraFrameCaptureAPI, ar as Cameras, as as CameraFrameSequenceCamera, at as CameraFrameCaptureSource, au as CameraFrameSequenceOptions, av as CameraFrameSequenceResult, aw as PolicyCameraFrameStream, ax as PolicyCameraFrameCaptureOptions, ay as PolicyCameraFrameCaptureResult, az as FrameCaptureStatus, aA as PolicyCameraFrameCaptureAPI, aB as CameraFrameCaptureTensorOptions, aC as CameraFrameTensorResult, aD as CameraFrameSequenceRecorderAPI, aE as ImagePointCoordinateSpace, aF as ImagePointProjectionOptions, aG as ImagePointProjectionResult, aH as PolicyVector } from './types-Bu8Aki_j.js';
+export { aI as BodyInfo, aJ as CAMERA_FRAME_CAPTURE_PRE_RENDER_USER_DATA_KEY, aK as CAMERA_FRAME_CAPTURE_RENDER_USER_DATA_KEY, aL as CAPTURE_EXCLUDE_KEY, aM as CameraFrameCaptureBlobResult, aN as CameraFrameCaptureQuaternion, aO as CameraFrameCaptureResult, aP as CameraFrameCaptureSession, aQ as CameraFrameCaptureVector3, aR as CameraFramePixelsResult, aS as CameraFrameSequenceCameraSummary, aT as CameraFrameSequenceFrame, aU as CameraFrameSequenceSampleInput, aV as CameraFrameSequenceStepInput, aW as CameraInfo, aX as ControlJointInfo, aY as DebugVirtualCamera, aZ as FrameCaptureTarget, a_ as FrameCaptureTargetRef, a$ as IKSolveFn, b0 as IkGizmoDragInput, b1 as IkSolveInput, b2 as JointInfo, b3 as JointStateKind, b4 as KeyBinding, b5 as KeyboardIkTargetAction, b6 as KeyboardIkTargetBinding, b7 as Keyframes, b8 as ModelActuators, b9 as ModelBodies, ba as ModelCameras, bb as ModelGeoms, bc as ModelJoints, bd as ModelKeyframes, be as ModelOptions, bf as ModelResource, bg as ModelResources, bh as ModelSensors, bi as ModelSites, bj as Models, bk as MujocoContact, bl as MujocoContactArray, bm as MujocoFrameCaptureOptions, bn as ObservationLayoutItem, bo as PhysicsConfig, bp as PhysicsStepInput, bq as PolicyActionChunk, br as PolicyActionInput, bs as PolicyImageTensorLayout, bt as PolicyImageTensorOptions, bu as PolicyImageTensorPixelOptions, bv as PolicyImageTensorRange, bw as PolicyImageTensorResult, bx as PolicyImageTensorSourceOrigin, by as PolicyInferenceInput, bz as PolicyInferenceOutput, bA as PolicyInferenceResult, bB as PolicyObservationInput, bC as RayHit, bD as Register, bE as RegisteredModelMap, bF as RemotePolicyRequestInfo, bG as RemotePolicyRequestInput, bH as RemotePolicyResponseInfo, bI as RemotePolicyStatus, bJ as ResetCallbackInput, bK as ResolvedScenarioCameraConfig, bL as ResolvedScenarioMaterialConfig, bM as ResourceSelector, bN as ScenarioCameraConfig, bO as ScenarioMaterialConfig, bP as SceneMarker, bQ as SceneObject, bR as SensorResult, bS as SiteInfo, bT as SplatAssetConfig, bU as SplatScenarioConfig, bV as StateSnapshot, bW as TrajectoryData, bX as TrajectoryFrameCallbackInput, bY as VisualScenarioMaterialFilterInput, bZ as XmlPatch, b_ as captureCameraFrame, b$ as captureCameraFrameBlob, c0 as captureCameraFrameTensor, c1 as createCameraFrameCaptureSession, c2 as dataUrlToPolicyImageTensor, c3 as getContact, c4 as imageDataToPolicyImageTensor, c5 as pixelsToPolicyImageTensor, c6 as registerModelResources, c7 as renderCameraFrameToCanvas } from './types-Bu8Aki_j.js';
 import * as React$1 from 'react';
 import { CSSProperties, RefObject } from 'react';
 import * as THREE from 'three';
@@ -144,9 +144,10 @@ interface MujocoSimProviderProps {
     speed?: number;
     interpolate?: boolean;
     renderOptions?: MujocoRenderOptions;
+    hiddenBodies?: readonly string[];
     children: React.ReactNode;
 }
-declare function MujocoSimProvider({ mujoco, config, apiRef: externalApiRef, onReady, onError, onStep, onSelection, gravity, timestep, substeps, paused, speed, interpolate, renderOptions, children, }: MujocoSimProviderProps): react_jsx_runtime.JSX.Element;
+declare function MujocoSimProvider({ mujoco, config, apiRef: externalApiRef, onReady, onError, onStep, onSelection, gravity, timestep, substeps, paused, speed, interpolate, renderOptions, hiddenBodies, children, }: MujocoSimProviderProps): react_jsx_runtime.JSX.Element;
 
 /**
  * @license
@@ -795,6 +796,9 @@ declare function useControlWriter(options: ControlWriterOptions): ControlWriterH
  * positional arrays, no `as const`, no owner bookkeeping.
  */
 
+type StringKeyOf<T> = Extract<keyof T, string>;
+type ControlDefinitionMap = Record<string, Actuators>;
+type ControlValues<K extends string> = Partial<Record<K, number>>;
 /**
  * A typed description of a set of actuators, keyed by name. Create it once with
  * {@link controlGroup} and reuse it across controllers and scripts; the key
@@ -810,6 +814,12 @@ interface ControlGroup<K extends Actuators = Actuators> {
  * no `as const` required (the `const` type parameter captures them).
  */
 declare function controlGroup<const T extends readonly Actuators[]>(names: T): ControlGroup<T[number]>;
+interface DefinedControls<TControls extends ControlDefinitionMap = ControlDefinitionMap> {
+    readonly controls: TControls;
+    readonly aliases: readonly StringKeyOf<TControls>[];
+    readonly keys: readonly TControls[StringKeyOf<TControls>][];
+}
+declare function defineControls<const TControls extends ControlDefinitionMap>(controls: TControls): DefinedControls<TControls>;
 interface ControlGroupSetOptions {
     /** Write even when another control writer owns one of these actuators. */
     force?: boolean;
@@ -817,8 +827,14 @@ interface ControlGroupSetOptions {
 interface ControlGroupHandle<K extends string> {
     /** The cooperative-ownership identity used for conflict detection. */
     owner: string;
+    /** Set a single actuator by name. Returns false if blocked by a conflict. */
+    set(name: K, value: number, options?: ControlGroupSetOptions): boolean;
     /** Set one or more actuators by name. Returns false if blocked by a conflict. */
-    set(values: Partial<Record<K, number>>, options?: ControlGroupSetOptions): boolean;
+    patch(values: ControlValues<K>, options?: ControlGroupSetOptions): boolean;
+    /** Write values in the same order as the declared control group. */
+    write(values: ArrayLike<number>, options?: ControlGroupSetOptions): boolean;
+    /** Read one actuator value by name. */
+    get(name: K): number;
     /** Read the current control value of every actuator in the group, by name. */
     read(): Record<K, number>;
     /** Whether this group can currently write (no unresolved conflicts). */
@@ -827,10 +843,31 @@ interface ControlGroupHandle<K extends string> {
     release(): void;
 }
 type UseControlGroupOptions = Omit<ControlWriterOptions, 'owner' | 'selector'> & {
-    /** Override the auto-generated owner id (useful for readable conflict logs). */
+    /** Human-readable conflict label. */
+    label?: string;
+    /** Override the generated conflict owner id. Prefer `label` for normal use. */
     owner?: string;
 };
+interface ControlsHandle<TControls extends ControlDefinitionMap> {
+    /** The cooperative-ownership identity used for conflict detection. */
+    owner: string;
+    /** Set one alias by name. Returns false if blocked by a conflict. */
+    set(name: StringKeyOf<TControls>, value: number, options?: ControlGroupSetOptions): boolean;
+    /** Set one or more aliases by name. Returns false if blocked by a conflict. */
+    patch(values: ControlValues<StringKeyOf<TControls>>, options?: ControlGroupSetOptions): boolean;
+    /** Write values in the same order as the `defineControls()` object. */
+    write(values: ArrayLike<number>, options?: ControlGroupSetOptions): boolean;
+    /** Read one alias value by name. */
+    get(name: StringKeyOf<TControls>): number;
+    /** Read every alias value. */
+    read(): Record<StringKeyOf<TControls>, number>;
+    /** Whether this group can currently write (no unresolved conflicts). */
+    canWrite(): boolean;
+    /** Release this group's actuator ownership. */
+    release(): void;
+}
 declare function useControlGroup<K extends Actuators>(group: ControlGroup<K>, options?: UseControlGroupOptions): ControlGroupHandle<K>;
+declare function useControls<TControls extends ControlDefinitionMap>(definition: DefinedControls<TControls>, options?: UseControlGroupOptions): ControlsHandle<TControls>;
 
 /**
  * @license
@@ -1595,4 +1632,4 @@ interface CameraAnimationAPI {
  */
 declare function useCameraAnimation(): CameraAnimationAPI;
 
-export { ActuatedJointInfo, ActuatorInfo, Actuators, type ApplyPolicyActionToControlsOptions, type ApplyPolicyActionToControlsResult, ArrayJointStateResult, Bodies, Body, BodyProps, BodyStateResult, type CameraAnimationAPI, CameraFrameCaptureAPI, CameraFrameCaptureOptions, CameraFrameCaptureSource, CameraFrameCaptureTensorOptions, type CameraFrameMountSelector, CameraFrameSequenceCamera, CameraFrameSequenceOptions, CameraFrameSequenceRecorderAPI, CameraFrameSequenceResult, CameraFrameTensorResult, type CameraStreamOptions, CameraView, type CameraViewProps, type CameraViewportOptions, Cameras, type ContactHistoryEntry, type ContactHistoryHandle, type ContactHistoryOptions, ContactInfo, ContactListener, ContactListenerProps, ContactMarkers, type ControlGroup, type ControlGroupHandle, ControlGroupInfo, ControlGroupSelector, type ControlGroupSetOptions, type ControlWriterConflict, type ControlWriterHandle, type ControlWriterOptions, type ControlWriterWriteOptions, type ControllerComponent, type ControllerOptions, type CreateMountedCameraFrameSequenceManifestOptions, type CreateMountedCameraFrameSequencePlanOptions, type CreatePolicyCameraFrameCapturePlanOptions, CtrlHandle, Debug, DebugProps, DragInteraction, DragInteractionProps, FlexRenderer, FrameCaptureAPI, FrameCaptureBlobResult, FrameCaptureOptions, FrameCaptureResult, FrameCaptureStatus, GenericIK, type GenericIKOptions, GeomInfo, Geoms, IkConfig, IkContextValue, IkGizmo, IkGizmoProps, ImagePointCoordinateSpace, ImagePointProjectionOptions, ImagePointProjectionResult, InstancedGeomRenderer, JointStateOptions, JointStateResult, Joints, KeyboardIkTargetConfig, KeyboardTeleopConfig, type MountedCameraFrameCaptureSource, type MountedCameraFrameSequenceCameraOptions, type MountedCameraFrameSequenceDefaults, type MountedCameraFrameSequenceManifest, MountedCameraFrameSequenceManifestStatus, type MountedCameraFrameSequencePlan, type MountedCameraFrameSequencePlanOptions, type MountedCameraFrameSequenceReadiness, MountedCameraFrameSequenceReadinessStatus, type MountedCameraFrameSequenceRecordOptions, type MountedCameraFrameSequenceRecordResult, type MountedCameraFrameSequenceRecorderTarget, type MountedCameraFrameSequenceSourceReadiness, type MountedCameraFrameSequenceStreamSummary, type MountedCameraFrameSourceSuggestion, MountedCameraFrameSourceSuggestionMatch, type MountedCameraSequencePlanOptions, type MountedCameraSequenceReadiness, type MountedCameraSequenceRecordOptions, type MountedCameraSequenceRecordResult, type MountedCameraSequenceRecorderAPI, type MountedPolicyCameraFrameCaptureAPI, type MountedPolicyCameraFrameCaptureOptions, type MountedPolicyCameraTensorOptions, MujocoCanvas, MujocoCanvasProps, MujocoContextValue, MujocoData, type MujocoLoader, type MujocoLoaderOptions, MujocoModel, MujocoModule, MujocoPhysics, type MujocoPhysicsProps, MujocoProvider, type MujocoProviderProps, MujocoSimAPI, MujocoSimProvider, type MujocoWasmVariant, type NamedCameraFrameResource, type NamedObservationField, type NamedObservationHandle, type NamedObservationInput, type NamedObservationLayoutItem, type NamedObservationMissing, type NamedObservationOptions, type NamedObservationResult, ObservationConfig, ObservationHandle, ObservationOutput, ObservationResult, PairedSplatEnvironmentConfig, PhysicsStepCallback, PlaybackState, PolicyAPI, PolicyCameraFrameCaptureAPI, PolicyCameraFrameCaptureOptions, type PolicyCameraFrameCapturePlan, PolicyCameraFrameCaptureResult, type PolicyCameraFrameCaptureTarget, type PolicyCameraFramePlanTarget, PolicyCameraFrameStream, type PolicyCameraFrameStreamOptions, type PolicyCameraTensorStream, type PolicyCameraTensorsAPI, type PolicyCameraTensorsOptions, type PolicyCameraTensorsResult, PolicyConfig, PolicyVector, type PoseReadout, type PoseResourceKind, ReadyCallbackInput, RemotePolicyAPI, RemotePolicyConfig, type ResolveMountedCameraFrameSourceOptions, type ResolvedMountedCameraFrameSource, ScalarJointStateResult, ScenarioLighting, ScenarioLightingPreset, ScenarioLightingProps, SceneConfig, SceneLights, SceneLightsProps, SelectionCallbackInput, SensorHandle, SensorInfo, Sensors, SitePositionResult, Sites, SplatCollisionPrimitive, SplatCollisionProxyConfig, type SplatCollisionProxyGeomPreview, type SplatCollisionProxyGeomsState, SplatCollisionProxyPreview, type SplatCollisionProxyPreviewProps, type SplatCollisionProxyPreviewStatus, type SplatCollisionProxyPreviewVector3, SplatEnvironment, SplatEnvironmentMetadata, SplatEnvironmentMetadataInput, SplatEnvironmentProps, SplatEnvironmentReadiness, SplatEnvironmentReadinessStatus, SplatFormat, SplatRendererKind, SplatSceneConfigInput, SplatSceneConfigState, SplatSceneInput, StepCallbackInput, TendonRenderer, TrajectoryFrame, TrajectoryInput, TrajectoryPlayer, TrajectoryPlayerProps, TrajectoryStateChangeInput, type UseControlGroupOptions, type UseSplatCollisionProxyGeomsOptions, VisualScenarioConfig, VisualScenarioEffects, VisualScenarioEffectsProps, VisualScenarioExecutionContext, VisualScenarioExecutionContextInput, applyPolicyActionToControls, bodyPositionField, buildObservation, canFetchSplatCollisionProxyXml, captureFrame, captureFrameBlob, capturePolicyCameraFrames, capturePolicyCameraFramesFromMountedStreams, clampPolicyActionValue, controlGroup, createContiguousControlGroup, createController, createControllerHook, createMountedCameraFrameSequenceManifest, createMountedCameraFrameSequencePlan, createMountedCameraFrameSequencePlanFromApi, createMountedCameraFrameSequenceReadiness, createMountedCameraFrameSourceSuggestions, createNamedObservationBuilder, createPairedSplatEnvironment, createPolicyCameraFrameCapturePlan, createPolicyCameraFrameCapturePlanFromApi, createSparkSplatViewerUrl, createSplatEnvironmentUserData, createSplatSceneConfig, createVisualScenarioExecutionContext, ctrlField, fetchSplatCollisionProxyXml, findActuatorByName, findBodyByName, findGeomByName, findJointByName, findKeyframeByName, findSensorByName, findSiteByName, findTendonByName, geomPositionField, getActuatedJoints, getCameraFrameCaptureSourceTarget, getControlMap, getMountedCameraFrameCaptureSource, getName, getScenarioBackground, getScenarioCameraPosition, getSplatEnvironmentReadiness, imagePointToNdc, isMountedCameraFrameCaptureSource, loadScene, parseSplatCollisionProxyGeoms, projectImagePointTo3D, qposField, qvelField, readNamedObservation, recordMountedCameraFrameSequence, resolveControlGroup, resolveMountedCameraFrameSource, sitePositionField, useActuators, useAfterPhysicsStep, useBeforePhysicsStep, useBodyMeshes, useBodyPose, useBodyState, useCameraAnimation, useCameraFrameCapture, useCameraSequenceRecorder, useCameraStream, useCameraViewport, useContactEvents, useContactHistory, useContacts, useControlGroup, useControlWriter, useCtrl, useCtrlNoise, useFrameCapture, useGamepad, useGeomPose, useGravityCompensation, useIkController, useJointState, useKeyboardIkTarget, useKeyboardTeleop, useMountedCameraSequenceRecorder, useMujoco, useMujocoWasm, useNamedObservation, useObservation, usePolicy, usePolicyCameraFrames, usePolicyCameraFramesFromMountedStreams, usePolicyCameraTensors, usePolicyCameraTensorsFromMountedStreams, useRemotePolicy, useSceneLights, useSelectionHighlight, useSensor, useSensors, useSitePose, useSitePosition, useSplatCollisionProxyGeoms, useSplatEnvironment, useSplatSceneConfig, useTrajectoryPlayer, useTrajectoryRecorder, useVideoRecorder, useVisualScenarioEffects, useVisualScenarioExecutionContext, withSplatEnvironment };
+export { ActuatedJointInfo, ActuatorInfo, Actuators, type ApplyPolicyActionToControlsOptions, type ApplyPolicyActionToControlsResult, ArrayJointStateResult, Bodies, Body, BodyProps, BodyStateResult, type CameraAnimationAPI, CameraFrameCaptureAPI, CameraFrameCaptureOptions, CameraFrameCaptureSource, CameraFrameCaptureTensorOptions, type CameraFrameMountSelector, CameraFrameSequenceCamera, CameraFrameSequenceOptions, CameraFrameSequenceRecorderAPI, CameraFrameSequenceResult, CameraFrameTensorResult, type CameraStreamOptions, CameraView, type CameraViewProps, type CameraViewportOptions, Cameras, type ContactHistoryEntry, type ContactHistoryHandle, type ContactHistoryOptions, ContactInfo, ContactListener, ContactListenerProps, ContactMarkers, type ControlGroup, type ControlGroupHandle, ControlGroupInfo, ControlGroupSelector, type ControlGroupSetOptions, type ControlWriterConflict, type ControlWriterHandle, type ControlWriterOptions, type ControlWriterWriteOptions, type ControllerComponent, type ControllerOptions, type ControlsHandle, type CreateMountedCameraFrameSequenceManifestOptions, type CreateMountedCameraFrameSequencePlanOptions, type CreatePolicyCameraFrameCapturePlanOptions, CtrlHandle, Debug, DebugProps, type DefinedControls, DragInteraction, DragInteractionProps, FlexRenderer, FrameCaptureAPI, FrameCaptureBlobResult, FrameCaptureOptions, FrameCaptureResult, FrameCaptureStatus, GenericIK, type GenericIKOptions, GeomInfo, Geoms, IkConfig, IkContextValue, IkGizmo, IkGizmoProps, ImagePointCoordinateSpace, ImagePointProjectionOptions, ImagePointProjectionResult, InstancedGeomRenderer, JointStateOptions, JointStateResult, Joints, KeyboardIkTargetConfig, KeyboardTeleopConfig, type MountedCameraFrameCaptureSource, type MountedCameraFrameSequenceCameraOptions, type MountedCameraFrameSequenceDefaults, type MountedCameraFrameSequenceManifest, MountedCameraFrameSequenceManifestStatus, type MountedCameraFrameSequencePlan, type MountedCameraFrameSequencePlanOptions, type MountedCameraFrameSequenceReadiness, MountedCameraFrameSequenceReadinessStatus, type MountedCameraFrameSequenceRecordOptions, type MountedCameraFrameSequenceRecordResult, type MountedCameraFrameSequenceRecorderTarget, type MountedCameraFrameSequenceSourceReadiness, type MountedCameraFrameSequenceStreamSummary, type MountedCameraFrameSourceSuggestion, MountedCameraFrameSourceSuggestionMatch, type MountedCameraSequencePlanOptions, type MountedCameraSequenceReadiness, type MountedCameraSequenceRecordOptions, type MountedCameraSequenceRecordResult, type MountedCameraSequenceRecorderAPI, type MountedPolicyCameraFrameCaptureAPI, type MountedPolicyCameraFrameCaptureOptions, type MountedPolicyCameraTensorOptions, MujocoCanvas, MujocoCanvasProps, MujocoContextValue, MujocoData, type MujocoLoader, type MujocoLoaderOptions, MujocoModel, MujocoModule, MujocoPhysics, type MujocoPhysicsProps, MujocoProvider, type MujocoProviderProps, MujocoSimAPI, MujocoSimProvider, type MujocoWasmVariant, type NamedCameraFrameResource, type NamedObservationField, type NamedObservationHandle, type NamedObservationInput, type NamedObservationLayoutItem, type NamedObservationMissing, type NamedObservationOptions, type NamedObservationResult, ObservationConfig, ObservationHandle, ObservationOutput, ObservationResult, PairedSplatEnvironmentConfig, PhysicsStepCallback, PlaybackState, PolicyAPI, PolicyCameraFrameCaptureAPI, PolicyCameraFrameCaptureOptions, type PolicyCameraFrameCapturePlan, PolicyCameraFrameCaptureResult, type PolicyCameraFrameCaptureTarget, type PolicyCameraFramePlanTarget, PolicyCameraFrameStream, type PolicyCameraFrameStreamOptions, type PolicyCameraTensorStream, type PolicyCameraTensorsAPI, type PolicyCameraTensorsOptions, type PolicyCameraTensorsResult, PolicyConfig, PolicyVector, type PoseReadout, type PoseResourceKind, ReadyCallbackInput, RemotePolicyAPI, RemotePolicyConfig, type ResolveMountedCameraFrameSourceOptions, type ResolvedMountedCameraFrameSource, ScalarJointStateResult, ScenarioLighting, ScenarioLightingPreset, ScenarioLightingProps, SceneConfig, SceneLights, SceneLightsProps, SelectionCallbackInput, SensorHandle, SensorInfo, Sensors, SitePositionResult, Sites, SplatCollisionPrimitive, SplatCollisionProxyConfig, type SplatCollisionProxyGeomPreview, type SplatCollisionProxyGeomsState, SplatCollisionProxyPreview, type SplatCollisionProxyPreviewProps, type SplatCollisionProxyPreviewStatus, type SplatCollisionProxyPreviewVector3, SplatEnvironment, SplatEnvironmentMetadata, SplatEnvironmentMetadataInput, SplatEnvironmentProps, SplatEnvironmentReadiness, SplatEnvironmentReadinessStatus, SplatFormat, SplatRendererKind, SplatSceneConfigInput, SplatSceneConfigState, SplatSceneInput, StepCallbackInput, TendonRenderer, TrajectoryFrame, TrajectoryInput, TrajectoryPlayer, TrajectoryPlayerProps, TrajectoryStateChangeInput, type UseControlGroupOptions, type UseSplatCollisionProxyGeomsOptions, VisualScenarioConfig, VisualScenarioEffects, VisualScenarioEffectsProps, VisualScenarioExecutionContext, VisualScenarioExecutionContextInput, applyPolicyActionToControls, bodyPositionField, buildObservation, canFetchSplatCollisionProxyXml, captureFrame, captureFrameBlob, capturePolicyCameraFrames, capturePolicyCameraFramesFromMountedStreams, clampPolicyActionValue, controlGroup, createContiguousControlGroup, createController, createControllerHook, createMountedCameraFrameSequenceManifest, createMountedCameraFrameSequencePlan, createMountedCameraFrameSequencePlanFromApi, createMountedCameraFrameSequenceReadiness, createMountedCameraFrameSourceSuggestions, createNamedObservationBuilder, createPairedSplatEnvironment, createPolicyCameraFrameCapturePlan, createPolicyCameraFrameCapturePlanFromApi, createSparkSplatViewerUrl, createSplatEnvironmentUserData, createSplatSceneConfig, createVisualScenarioExecutionContext, ctrlField, defineControls, fetchSplatCollisionProxyXml, findActuatorByName, findBodyByName, findGeomByName, findJointByName, findKeyframeByName, findSensorByName, findSiteByName, findTendonByName, geomPositionField, getActuatedJoints, getCameraFrameCaptureSourceTarget, getControlMap, getMountedCameraFrameCaptureSource, getName, getScenarioBackground, getScenarioCameraPosition, getSplatEnvironmentReadiness, imagePointToNdc, isMountedCameraFrameCaptureSource, loadScene, parseSplatCollisionProxyGeoms, projectImagePointTo3D, qposField, qvelField, readNamedObservation, recordMountedCameraFrameSequence, resolveControlGroup, resolveMountedCameraFrameSource, sitePositionField, useActuators, useAfterPhysicsStep, useBeforePhysicsStep, useBodyMeshes, useBodyPose, useBodyState, useCameraAnimation, useCameraFrameCapture, useCameraSequenceRecorder, useCameraStream, useCameraViewport, useContactEvents, useContactHistory, useContacts, useControlGroup, useControlWriter, useControls, useCtrl, useCtrlNoise, useFrameCapture, useGamepad, useGeomPose, useGravityCompensation, useIkController, useJointState, useKeyboardIkTarget, useKeyboardTeleop, useMountedCameraSequenceRecorder, useMujoco, useMujocoWasm, useNamedObservation, useObservation, usePolicy, usePolicyCameraFrames, usePolicyCameraFramesFromMountedStreams, usePolicyCameraTensors, usePolicyCameraTensorsFromMountedStreams, useRemotePolicy, useSceneLights, useSelectionHighlight, useSensor, useSensors, useSitePose, useSitePosition, useSplatCollisionProxyGeoms, useSplatEnvironment, useSplatSceneConfig, useTrajectoryPlayer, useTrajectoryRecorder, useVideoRecorder, useVisualScenarioEffects, useVisualScenarioExecutionContext, withSplatEnvironment };

package/dist/index.js

@@ -1,5 +1,5 @@
-import { withContacts, getContact, captureCameraFrame, captureCameraFrameBlob, createCameraFrameCaptureSession, CAMERA_FRAME_CAPTURE_PRE_RENDER_USER_DATA_KEY, CAPTURE_EXCLUDE_KEY, createCaptureCamera, prepareCaptureCamera } from './chunk-EN55TTGH.js';
-export { CAMERA_FRAME_CAPTURE_PRE_RENDER_USER_DATA_KEY, CAMERA_FRAME_CAPTURE_RENDER_USER_DATA_KEY, CAPTURE_EXCLUDE_KEY, ModelActuators, ModelBodies, ModelCameras, ModelGeoms, ModelJoints, ModelKeyframes, ModelResources, ModelSensors, ModelSites, ScenarioLighting, SplatEnvironment, SplatEnvironmentReadinessStatus, VisualScenarioEffects, captureCameraFrame, captureCameraFrameBlob, captureCameraFrameTensor, createCameraFrameCaptureSession, createPairedSplatEnvironment, createSparkSplatViewerUrl, createSplatEnvironmentUserData, createSplatSceneConfig, createVisualScenarioExecutionContext, dataUrlToPolicyImageTensor, getContact, getScenarioBackground, getScenarioCameraPosition, getSplatEnvironmentReadiness, imageDataToPolicyImageTensor, pixelsToPolicyImageTensor, registerModelResources, renderCameraFrameToCanvas, useSplatEnvironment, useSplatSceneConfig, useVisualScenarioEffects, useVisualScenarioExecutionContext, withSplatEnvironment } from './chunk-EN55TTGH.js';
+import { withContacts, getContact, captureCameraFrame, captureCameraFrameBlob, createCameraFrameCaptureSession, CAMERA_FRAME_CAPTURE_PRE_RENDER_USER_DATA_KEY, CAPTURE_EXCLUDE_KEY, createCaptureCamera, prepareCaptureCamera } from './chunk-5WFYM73E.js';
+export { CAMERA_FRAME_CAPTURE_PRE_RENDER_USER_DATA_KEY, CAMERA_FRAME_CAPTURE_RENDER_USER_DATA_KEY, CAPTURE_EXCLUDE_KEY, ModelActuators, ModelBodies, ModelCameras, ModelGeoms, ModelJoints, ModelKeyframes, ModelResources, ModelSensors, ModelSites, ScenarioLighting, SplatEnvironment, SplatEnvironmentReadinessStatus, VisualScenarioEffects, captureCameraFrame, captureCameraFrameBlob, captureCameraFrameTensor, createCameraFrameCaptureSession, createPairedSplatEnvironment, createSparkSplatViewerUrl, createSplatEnvironmentUserData, createSplatSceneConfig, createVisualScenarioExecutionContext, dataUrlToPolicyImageTensor, getContact, getScenarioBackground, getScenarioCameraPosition, getSplatEnvironmentReadiness, imageDataToPolicyImageTensor, pixelsToPolicyImageTensor, registerModelResources, renderCameraFrameToCanvas, useSplatEnvironment, useSplatSceneConfig, useVisualScenarioEffects, useVisualScenarioExecutionContext, withSplatEnvironment } from './chunk-5WFYM73E.js';
 import loadMujoco from '@mujoco/mujoco';
 import defaultMujocoWasmUrl from '@mujoco/mujoco/mujoco.wasm?url';
 import { createContext, forwardRef, useRef, useEffect, useContext, useState, useCallback, useMemo, useLayoutEffect, useId } from 'react';
@@ -1001,14 +1001,34 @@ var GeomBuilder = class {
       const vNum = mjModel.mesh_vertnum[mId];
       const fAdr = mjModel.mesh_faceadr[mId];
       const fNum = mjModel.mesh_facenum[mId];
-      geo = new THREE11.BufferGeometry();
-      geo.setAttribute("position", new THREE11.Float32BufferAttribute(mjModel.mesh_vert.subarray(vAdr * 3, (vAdr + vNum) * 3), 3));
-      geo.setIndex(Array.from(mjModel.mesh_face.subarray(fAdr * 3, (fAdr + fNum) * 3)));
-      const smoothingTolerance = this.getMeshNormalSmoothingTolerance();
-      if (smoothingTolerance !== null) {
-        geo = mergeVertices(geo, smoothingTolerance);
+      const tAdr = mjModel.mesh_texcoordadr?.[mId] ?? -1;
+      if (map && tAdr >= 0 && mjModel.mesh_texcoord && mjModel.mesh_facetexcoord) {
+        const corners = fNum * 3;
+        const positions = new Float32Array(corners * 3);
+        const uvs = new Float32Array(corners * 2);
+        for (let c = 0; c < corners; c++) {
+          const v = vAdr + mjModel.mesh_face[fAdr * 3 + c];
+          positions[c * 3] = mjModel.mesh_vert[v * 3];
+          positions[c * 3 + 1] = mjModel.mesh_vert[v * 3 + 1];
+          positions[c * 3 + 2] = mjModel.mesh_vert[v * 3 + 2];
+          const t = tAdr + mjModel.mesh_facetexcoord[fAdr * 3 + c];
+          uvs[c * 2] = mjModel.mesh_texcoord[t * 2];
+          uvs[c * 2 + 1] = 1 - mjModel.mesh_texcoord[t * 2 + 1];
+        }
+        geo = new THREE11.BufferGeometry();
+        geo.setAttribute("position", new THREE11.Float32BufferAttribute(positions, 3));
+        geo.setAttribute("uv", new THREE11.Float32BufferAttribute(uvs, 2));
+        geo.computeVertexNormals();
+      } else {
+        geo = new THREE11.BufferGeometry();
+        geo.setAttribute("position", new THREE11.Float32BufferAttribute(mjModel.mesh_vert.subarray(vAdr * 3, (vAdr + vNum) * 3), 3));
+        geo.setIndex(Array.from(mjModel.mesh_face.subarray(fAdr * 3, (fAdr + fNum) * 3)));
+        const smoothingTolerance = this.getMeshNormalSmoothingTolerance();
+        if (smoothingTolerance !== null) {
+          geo = mergeVertices(geo, smoothingTolerance);
+        }
+        geo.computeVertexNormals();
       }
-      geo.computeVertexNormals();
     }
     if (geo) {
       const isPlane = type === getVal(MG.mjGEOM_PLANE);
@@ -1051,6 +1071,7 @@ function SceneRenderer({ renderOptions, ...props }) {
     mujocoRef,
     onSelectionRef,
     hiddenBodiesRef,
+    hiddenBodiesVersion,
     interpolateRef,
     interpolationStateRef,
     status
@@ -1059,6 +1080,7 @@ function SceneRenderer({ renderOptions, ...props }) {
   const bodyRefs = useRef([]);
   const prevModelRef = useRef(null);
   const prevRenderOptionsKeyRef = useRef(null);
+  const prevHiddenVersionRef = useRef(null);
   const renderOptionsKey = getRenderOptionsKey(renderOptions);
   const geomBuilder = useMemo(() => {
     if (status !== "ready") return null;
@@ -1069,11 +1091,12 @@ function SceneRenderer({ renderOptions, ...props }) {
     const model = mjModelRef.current;
     const group = groupRef.current;
     if (!model || !group) return;
-    if (prevModelRef.current === model && prevRenderOptionsKeyRef.current === renderOptionsKey) {
+    if (prevModelRef.current === model && prevRenderOptionsKeyRef.current === renderOptionsKey && prevHiddenVersionRef.current === hiddenBodiesVersion) {
       return;
     }
     prevModelRef.current = model;
     prevRenderOptionsKeyRef.current = renderOptionsKey;
+    prevHiddenVersionRef.current = hiddenBodiesVersion;
     while (group.children.length > 0) {
       group.remove(group.children[0]);
     }
@@ -1094,7 +1117,7 @@ function SceneRenderer({ renderOptions, ...props }) {
       refs.push(bodyGroup);
     }
     bodyRefs.current = refs;
-  }, [status, geomBuilder, mjModelRef, renderOptionsKey]);
+  }, [status, geomBuilder, mjModelRef, renderOptionsKey, hiddenBodiesRef, hiddenBodiesVersion]);
   const syncBodiesToData = useCallback(() => {
     const data = mjDataRef.current;
     if (!data) return;
@@ -2275,6 +2298,7 @@ function MujocoSimProvider({
   speed,
   interpolate,
   renderOptions,
+  hiddenBodies,
   children
 }) {
   const { gl, camera, scene } = useThree();
@@ -2308,6 +2332,8 @@ function MujocoSimProvider({
   const errorRef = useRef(null);
   const bodyRegistryRef = useRef(/* @__PURE__ */ new Map());
   const hiddenBodiesRef = useRef(/* @__PURE__ */ new Set());
+  const providedHiddenBodiesRef = useRef(new Set(hiddenBodies ?? []));
+  const [hiddenBodiesVersion, setHiddenBodiesVersion] = useState(0);
   const bodyReloadTimerRef = useRef(null);
   configRef.current = config;
   mujocoRef.current = mujoco;
@@ -2329,15 +2355,37 @@ function MujocoSimProvider({
     if (!model?.opt) return;
     model.opt.timestep = timestep;
   }, [timestep]);
+  const hiddenBodiesKey = (hiddenBodies ?? []).join("\0");
+  useEffect(() => {
+    const next = new Set(hiddenBodies ?? []);
+    const prev = providedHiddenBodiesRef.current;
+    let unchanged = next.size === prev.size;
+    if (unchanged) {
+      for (const name of next) {
+        if (!prev.has(name)) {
+          unchanged = false;
+          break;
+        }
+      }
+    }
+    if (unchanged) return;
+    providedHiddenBodiesRef.current = next;
+    recomputeHiddenBodies();
+    setHiddenBodiesVersion((v) => v + 1);
+  }, [hiddenBodiesKey]);
+  function recomputeHiddenBodies() {
+    hiddenBodiesRef.current.clear();
+    for (const [name, entry] of bodyRegistryRef.current) {
+      if (entry.hasCustomChildren) hiddenBodiesRef.current.add(name);
+    }
+    for (const name of providedHiddenBodiesRef.current) hiddenBodiesRef.current.add(name);
+  }
   function buildMergedConfig(baseConfig) {
+    recomputeHiddenBodies();
     if (bodyRegistryRef.current.size === 0) return baseConfig;
     const registeredNames = new Set(bodyRegistryRef.current.keys());
     const baseObjects = (baseConfig.sceneObjects ?? []).filter((o) => !registeredNames.has(o.name));
     const registeredBodies = Array.from(bodyRegistryRef.current.values()).map((e) => e.definition);
-    hiddenBodiesRef.current.clear();
-    for (const [name, entry] of bodyRegistryRef.current) {
-      if (entry.hasCustomChildren) hiddenBodiesRef.current.add(name);
-    }
     return { ...baseConfig, sceneObjects: [...baseObjects, ...registeredBodies] };
   }
   useEffect(() => {
@@ -3555,10 +3603,11 @@ function MujocoSimProvider({
       errorRef,
       bodyRegistryRef,
       hiddenBodiesRef,
+      hiddenBodiesVersion,
       requestBodyReload,
       status
     }),
-    [api, status, requestBodyReload]
+    [api, status, requestBodyReload, hiddenBodiesVersion]
   );
   return /* @__PURE__ */ jsxs(MujocoSimContext.Provider, { value: contextValue, children: [
     /* @__PURE__ */ jsx(SceneRenderer, { renderOptions }),
@@ -3580,6 +3629,7 @@ var MujocoCanvas = forwardRef(
     speed,
     interpolate,
     renderOptions,
+    hiddenBodies,
     loadingFallback,
     children,
     ...canvasProps
@@ -3615,6 +3665,7 @@ var MujocoCanvas = forwardRef(
         speed,
         interpolate,
         renderOptions,
+        hiddenBodies,
         children
       }
     ) });
@@ -4058,7 +4109,16 @@ var useIkController = createControllerHook(
     const ikTargetRef = useRef(new THREE11.Group());
     const siteIdRef = useRef(-1);
     const controlGroupRef = useRef(null);
-    const genericIkRef = useRef(new GenericIK(mujocoRef.current));
+    const genericIkRef = useRef(null);
+    const genericIkModuleRef = useRef(null);
+    const getGenericIk = useCallback(() => {
+      const module = mujocoRef.current;
+      if (!genericIkRef.current || genericIkModuleRef.current !== module) {
+        genericIkRef.current = new GenericIK(module);
+        genericIkModuleRef.current = module;
+      }
+      return genericIkRef.current;
+    }, [mujocoRef]);
     const firstIkEnableRef = useRef(true);
     const needsInitialSync = useRef(true);
     const gizmoAnimRef = useRef({
@@ -4109,7 +4169,7 @@ var useIkController = createControllerHook(
         const data = mjDataRef.current;
         const controlGroup2 = controlGroupRef.current;
         if (!model || !data || !controlGroup2 || siteIdRef.current === -1) return null;
-        return genericIkRef.current.solve(
+        return getGenericIk().solve(
           model,
           data,
           siteIdRef.current,
@@ -4128,7 +4188,7 @@ var useIkController = createControllerHook(
           }
         );
       },
-      [config, mjModelRef, mjDataRef]
+      [config, mjModelRef, mjDataRef, getGenericIk]
     );
     const ikSolveFnRef = useRef(ikSolveFn);
     ikSolveFnRef.current = ikSolveFn;
@@ -6759,19 +6819,35 @@ function useControlWriter(options) {
 }
 
 // src/hooks/useControlGroup.ts
+function objectKeys(value) {
+  return Object.keys(value);
+}
+function singleControlValue(name, value) {
+  const values = {};
+  values[name] = value;
+  return values;
+}
 function controlGroup(names) {
   return { keys: names };
 }
+function defineControls(controls) {
+  const aliases = objectKeys(controls);
+  return {
+    controls,
+    aliases,
+    keys: aliases.map((alias) => controls[alias])
+  };
+}
 function useControlGroup(group, options = {}) {
   const generatedOwner = useId();
-  const owner = options.owner ?? `control-group:${generatedOwner}`;
+  const owner = options.owner ?? options.label ?? `control-group:${generatedOwner}`;
   const { mjModelRef, mjDataRef, status } = useMujocoContext();
   const names = group.keys;
   const namesRef = useRef(names);
   namesRef.current = names;
   const namesKey = names.join("\0");
   const selector = useMemo(
-    () => ({ actuators: [...names] }),
+    () => ({ actuators: names }),
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [namesKey]
   );
@@ -6791,15 +6867,15 @@ function useControlGroup(group, options = {}) {
       return id;
     });
   }, [mjModelRef, status, namesKey]);
-  const set = useCallback(
+  const patch = useCallback(
     (values, setOptions = {}) => {
       const data = mjDataRef.current;
       if (!data) return false;
       if (!setOptions.force && !canWrite()) return false;
       const groupNames = namesRef.current;
       const indices = indicesRef.current;
-      for (let i = 0; i < groupNames.length; i += 1) {
-        const value = values[groupNames[i]];
+      for (const [i, name] of groupNames.entries()) {
+        const value = values[name];
         if (value === void 0) continue;
         const adr = indices[i];
         if (adr >= 0) data.ctrl[adr] = value;
@@ -6808,20 +6884,87 @@ function useControlGroup(group, options = {}) {
     },
     [canWrite, mjDataRef]
   );
+  const write = useCallback(
+    (values, setOptions = {}) => {
+      const data = mjDataRef.current;
+      if (!data) return false;
+      if (!setOptions.force && !canWrite()) return false;
+      const groupNames = namesRef.current;
+      const indices = indicesRef.current;
+      for (let i = 0; i < Math.min(groupNames.length, values.length); i += 1) {
+        const adr = indices[i];
+        if (adr >= 0) data.ctrl[adr] = values[i];
+      }
+      return true;
+    },
+    [canWrite, mjDataRef]
+  );
+  const set = useCallback(
+    (name, value, setOptions) => patch(singleControlValue(name, value), setOptions),
+    [patch]
+  );
   const read = useCallback(() => {
     const data = mjDataRef.current;
     const groupNames = namesRef.current;
     const indices = indicesRef.current;
     const result = {};
-    for (let i = 0; i < groupNames.length; i += 1) {
+    for (const [i, name] of groupNames.entries()) {
       const adr = indices[i];
-      result[groupNames[i]] = data && adr >= 0 ? data.ctrl[adr] ?? 0 : 0;
+      result[name] = data && adr >= 0 ? data.ctrl[adr] ?? 0 : 0;
     }
     return result;
   }, [mjDataRef]);
+  const get = useCallback((name) => read()[name], [read]);
   return useMemo(
-    () => ({ owner, set, read, canWrite, release }),
-    [owner, set, read, canWrite, release]
+    () => ({ owner, set, patch, write, get, read, canWrite, release }),
+    [owner, set, patch, write, get, read, canWrite, release]
+  );
+}
+function useControls(definition, options = {}) {
+  const group = useControlGroup(controlGroup(definition.keys), options);
+  const controlsRef = useRef(definition.controls);
+  const aliasesRef = useRef(definition.aliases);
+  controlsRef.current = definition.controls;
+  aliasesRef.current = definition.aliases;
+  const set = useCallback(
+    (name, value, setOptions) => group.set(controlsRef.current[name], value, setOptions),
+    [group]
+  );
+  const patch = useCallback(
+    (values, setOptions) => {
+      const next = {};
+      for (const alias of aliasesRef.current) {
+        const value = values[alias];
+        if (value !== void 0) next[controlsRef.current[alias]] = value;
+      }
+      return group.patch(next, setOptions);
+    },
+    [group]
+  );
+  const get = useCallback(
+    (name) => group.get(controlsRef.current[name]),
+    [group]
+  );
+  const read = useCallback(() => {
+    const values = group.read();
+    const result = {};
+    for (const alias of aliasesRef.current) {
+      result[alias] = values[controlsRef.current[alias]] ?? 0;
+    }
+    return result;
+  }, [group]);
+  return useMemo(
+    () => ({
+      owner: group.owner,
+      set,
+      patch,
+      write: group.write,
+      get,
+      read,
+      canWrite: group.canWrite,
+      release: group.release
+    }),
+    [group, set, patch, get, read]
   );
 }
 var geomNameCacheByModel2 = /* @__PURE__ */ new WeakMap();
@@ -8846,6 +8989,6 @@ function useCameraAnimation() {
  * useCameraAnimation — composable camera animation hook.
  */
 
-export { Body, CameraView, ContactListener, ContactMarkers, Debug, DragInteraction, FlexRenderer, GenericIK, IkGizmo, InstancedGeomRenderer, MountedCameraFrameSequenceManifestStatus, MountedCameraFrameSequenceReadinessStatus, MountedCameraFrameSourceSuggestionMatch, MujocoCanvas, MujocoPhysics, MujocoProvider, MujocoSimProvider, SceneLights, SplatCollisionProxyPreview, TendonRenderer, TrajectoryPlayer, applyPolicyActionToControls, bodyPositionField, buildObservation, canFetchSplatCollisionProxyXml, captureFrame, captureFrameBlob, capturePolicyCameraFrames, capturePolicyCameraFramesFromMountedStreams, clampPolicyActionValue, controlGroup, createContiguousControlGroup, createController, createControllerHook, createMountedCameraFrameSequenceManifest, createMountedCameraFrameSequencePlan, createMountedCameraFrameSequencePlanFromApi, createMountedCameraFrameSequenceReadiness, createMountedCameraFrameSourceSuggestions, createNamedObservationBuilder, createPolicyCameraFrameCapturePlan, createPolicyCameraFrameCapturePlanFromApi, ctrlField, fetchSplatCollisionProxyXml, findActuatorByName, findBodyByName, findGeomByName, findJointByName, findKeyframeByName, findSensorByName, findSiteByName, findTendonByName, geomPositionField, getActuatedJoints, getCameraFrameCaptureSourceTarget, getControlMap, getMountedCameraFrameCaptureSource, getName, imagePointToNdc, isMountedCameraFrameCaptureSource, loadScene, parseSplatCollisionProxyGeoms, projectImagePointTo3D, qposField, qvelField, readNamedObservation, recordMountedCameraFrameSequence, resolveControlGroup, resolveMountedCameraFrameSource, sitePositionField, useActuators, useAfterPhysicsStep, useBeforePhysicsStep, useBodyMeshes, useBodyPose, useBodyState, useCameraAnimation, useCameraFrameCapture, useCameraSequenceRecorder, useCameraStream, useCameraViewport, useContactEvents, useContactHistory, useContacts, useControlGroup, useControlWriter, useCtrl, useCtrlNoise, useFrameCapture, useGamepad, useGeomPose, useGravityCompensation, useIkController, useJointState, useKeyboardIkTarget, useKeyboardTeleop, useMountedCameraSequenceRecorder, useMujoco, useMujocoWasm, useNamedObservation, useObservation, usePolicy, usePolicyCameraFrames, usePolicyCameraFramesFromMountedStreams, usePolicyCameraTensors, usePolicyCameraTensorsFromMountedStreams, useRemotePolicy, useSceneLights, useSelectionHighlight, useSensor, useSensors, useSitePose, useSitePosition, useSplatCollisionProxyGeoms, useTrajectoryPlayer, useTrajectoryRecorder, useVideoRecorder };
+export { Body, CameraView, ContactListener, ContactMarkers, Debug, DragInteraction, FlexRenderer, GenericIK, IkGizmo, InstancedGeomRenderer, MountedCameraFrameSequenceManifestStatus, MountedCameraFrameSequenceReadinessStatus, MountedCameraFrameSourceSuggestionMatch, MujocoCanvas, MujocoPhysics, MujocoProvider, MujocoSimProvider, SceneLights, SplatCollisionProxyPreview, TendonRenderer, TrajectoryPlayer, applyPolicyActionToControls, bodyPositionField, buildObservation, canFetchSplatCollisionProxyXml, captureFrame, captureFrameBlob, capturePolicyCameraFrames, capturePolicyCameraFramesFromMountedStreams, clampPolicyActionValue, controlGroup, createContiguousControlGroup, createController, createControllerHook, createMountedCameraFrameSequenceManifest, createMountedCameraFrameSequencePlan, createMountedCameraFrameSequencePlanFromApi, createMountedCameraFrameSequenceReadiness, createMountedCameraFrameSourceSuggestions, createNamedObservationBuilder, createPolicyCameraFrameCapturePlan, createPolicyCameraFrameCapturePlanFromApi, ctrlField, defineControls, fetchSplatCollisionProxyXml, findActuatorByName, findBodyByName, findGeomByName, findJointByName, findKeyframeByName, findSensorByName, findSiteByName, findTendonByName, geomPositionField, getActuatedJoints, getCameraFrameCaptureSourceTarget, getControlMap, getMountedCameraFrameCaptureSource, getName, imagePointToNdc, isMountedCameraFrameCaptureSource, loadScene, parseSplatCollisionProxyGeoms, projectImagePointTo3D, qposField, qvelField, readNamedObservation, recordMountedCameraFrameSequence, resolveControlGroup, resolveMountedCameraFrameSource, sitePositionField, useActuators, useAfterPhysicsStep, useBeforePhysicsStep, useBodyMeshes, useBodyPose, useBodyState, useCameraAnimation, useCameraFrameCapture, useCameraSequenceRecorder, useCameraStream, useCameraViewport, useContactEvents, useContactHistory, useContacts, useControlGroup, useControlWriter, useControls, useCtrl, useCtrlNoise, useFrameCapture, useGamepad, useGeomPose, useGravityCompensation, useIkController, useJointState, useKeyboardIkTarget, useKeyboardTeleop, useMountedCameraSequenceRecorder, useMujoco, useMujocoWasm, useNamedObservation, useObservation, usePolicy, usePolicyCameraFrames, usePolicyCameraFramesFromMountedStreams, usePolicyCameraTensors, usePolicyCameraTensorsFromMountedStreams, useRemotePolicy, useSceneLights, useSelectionHighlight, useSensor, useSensors, useSitePose, useSitePosition, useSplatCollisionProxyGeoms, useTrajectoryPlayer, useTrajectoryRecorder, useVideoRecorder };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map