mujoco-react 10.6.0 → 10.7.0

package/README.md

@@ -372,28 +372,59 @@ function ResetButton() {
 
 ## Map Controls to Joints
 
-Use control groups when a robot's actuator order does not match a simple `qpos[0..n]` layout:
+Use named controls when a controller should write actuator commands without
+hard-coding `data.ctrl` offsets:
 
 ```tsx
-import { useRef } from "react";
-import { resolveControlGroup, ModelSites, useBeforePhysicsStep } from "mujoco-react";
-import type { ControlGroupInfo } from "mujoco-react";
+import {
+  ModelActuators,
+  defineControls,
+  useBeforePhysicsStep,
+  useControls,
+} from "mujoco-react";
 
-function HoldTcpPose() {
-  const armRef = useRef<ControlGroupInfo | null>(null);
+const arm = defineControls({
+  shoulder: ModelActuators.so101.shoulder_pan,
+  lift: ModelActuators.so101.shoulder_lift,
+  elbow: ModelActuators.so101.elbow_flex,
+});
 
-  useBeforePhysicsStep(({ model, data }) => {
-    armRef.current ??= resolveControlGroup(model, { siteName: ModelSites.franka.tcp });
-    if (!armRef.current) return;
+function PolicyDriver({ action }: { action: number[] }) {
+  const controls = useControls(arm);
 
-    armRef.current.writeCtrl(data, armRef.current.readQpos(data));
+  useBeforePhysicsStep(() => {
+    controls.write(action);
+    controls.patch({ elbow: 1.2 });
   });
 
   return null;
 }
 ```
 
-`resolveControlGroup()` accepts `{ siteName }`, `{ bodyName }`, `{ joints }`, or `{ actuators }`. Selectors can be a name, ordered name array, regex, or predicate.
+`defineControls()` preserves the alias keys for `set()`, `patch()`, `get()`,
+and `read()`, while `write()` accepts an ordered vector in the same order as the
+object. The Vite plugin injects the generated register module automatically, so
+application code imports generated names from `mujoco-react`, not from
+`src/mujoco-register.gen.ts`.
+
+Use lower-level control groups when a robot's actuator order does not match a
+simple `qpos[0..n]` layout or you want actuator-name keys directly:
+
+```tsx
+import { controlGroup, ModelActuators, useControlGroup } from "mujoco-react";
+
+const gripper = controlGroup([ModelActuators.so101.gripper]);
+
+function HoldGripper() {
+  const controls = useControlGroup(gripper);
+  controls.set(ModelActuators.so101.gripper, -0.17453);
+  return null;
+}
+```
+
+For selector-based introspection, `resolveControlGroup()` accepts `{ siteName }`,
+`{ bodyName }`, `{ joints }`, or `{ actuators }`. Selectors can be a name,
+ordered name array, regex, or predicate.
 
 ## Build Observations
 

package/dist/index.d.ts

@@ -795,6 +795,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 +813,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 +826,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 +842,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 +1631,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

@@ -6759,19 +6759,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 +6807,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 +6824,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 +8929,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