Add coupler constraint support and example

[jslee02]

• add CouplerConstraint so mimic joints can optionally be enforced bilaterally and ensure the constraint solver instantiates it only when Joint::setUseCouplerConstraint(true) is set
• expose the flag through dartpy, add integration coverage, and ship a GUI example so downstream code (e.g., gz-sim mimic joints) can exercise the new constraint
• resolves Add Coupler Constraint (similar to a gearbox constaint from Gazebo) #1756 and supersedes the exploratory work in Added coupler constraint #1835 by documenting the intended gearbox use case and providing a pixi-friendly example

Testing

• pixi run test-all
• pixi run ex coupler_constraint

Screencast.from.2025-11-18.06-16-25.mp4

Closes #1835

---

Before creating a pull request

• Run pixi run test-all to lint, build, and test your changes
• Add unit tests for new functionality
• Document new methods and classes
• Add Python bindings (dartpy) if applicable

[codecov]

Codecov Report

❌ Patch coverage is 77.33990% with 46 lines in your changes missing coverage. Please review.
✅ Project coverage is 61.24%. Comparing base (59b6bdc) to head (ef990a8).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
dart/constraint/CouplerConstraint.cpp	76.57%	41 Missing ⚠️
dart/constraint/MimicMotorConstraint.cpp	0.00%	4 Missing ⚠️
dart/dynamics/Joint.cpp	93.33%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2212      +/-   ##
==========================================
+ Coverage   61.14%   61.24%   +0.09%     
==========================================
  Files         351      352       +1     
  Lines       31317    31515     +198     
  Branches     4050     4078      +28     
==========================================
+ Hits        19148    19300     +152     
- Misses      12169    12215      +46     

Flag	Coverage Δ
unittests	61.24% <77.33%> (+0.09%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
dart/constraint/ConstraintSolver.cpp	79.62% <100.00%> (+0.62%)	⬆️
dart/constraint/ConstraintSolver.hpp	100.00% <ø> (ø)
dart/dynamics/Joint.hpp	100.00% <ø> (ø)
dart/dynamics/Joint.cpp	76.58% <93.33%> (+1.79%)	⬆️
dart/constraint/MimicMotorConstraint.cpp	81.45% <0.00%> (-0.67%)	⬇️
dart/constraint/CouplerConstraint.cpp	76.57% <76.57%> (ø)

... and 2 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[jslee02]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[jslee02]

Merging now. If anything still isn't working or you hit new issues, let me know and I'll fix it forward. Thanks!