v3.1.0

sscbirrt becomes effortless to start with. pip install "sscbirrt[demo]"
then sscbirrt-demo renders MuJoCo demos with no Menagerie clone: the robot
models come from the new sscbirrt-assets wheel. sscbirrt.mujoco plans for
an arm in a MuJoCo world in one call:
plan(model, data, Arm(model, joints, site, mjcf=...), goal=...). Errors
name what exists and how to fix it. Names are consistent across the API, and
the README opens with something you can run.

Migrating from 3.0.0: nothing breaks. Renamed names keep working with a
DeprecationWarning until 4.0:

• ik_solver → ik;
• tsr_samples / max_ik_per_pose → sample_draws / max_per_draw;
• angular_joints → continuous_joints;
• seeds → explicit_samples;
• plan_native → sscbirrt.mujoco.plan.

Two behaviours tighten:

• A MuJoCo model with free bodies now needs explicit joint_names.
• A malformed start or goal raises a ValueError. Seeded TSR plans on
  arms whose IK enumerates many solutions per pose (SSIK on the UR5e) take
  different, equally valid paths, because roots are now a random subset of
  each draw (#168).

Added

• sscbirrt-demo (pip install "sscbirrt[demo]"): rendered MuJoCo demos on
  sscbirrt.mujoco, with no Menagerie clone and no system ffmpeg (#163-#165).
  • pick: a goal set of every side grasp of three cans among obstacles.
  • transport: a can carried upright over a box by a path constraint.
  • door: a door opened along its handle's arc by a TSR chain.
  • The README shows them as GIFs, regenerated by tools/readme_gifs.py.
• sscbirrt-assets, a separate data wheel in assets/ that packages the
  MuJoCo Menagerie UR5e and Robotiq 2F-85 models (pinned upstream commit,
  SHA-256 manifest, upstream BSD licenses kept), released by its own
  assets-v* tag pipeline. It is the first step toward
  pip install "sscbirrt[demo]" running the demos without a Menagerie
  clone (#162).
• sscbirrt.mujoco, the one-call MuJoCo API (#175).
  • Arm(model, joints, ee_site, mjcf=...) describes the arm once and
    builds analytical IK from its MJCF. The frames that relate SSIK to the
    world are computed from the model, so an arm attached anywhere, with a
    name prefix, just works, and they are checked.
  • plan(model, data, arm, goal=..., start=..., constraint=..., holding=...)
    always returns a PlanResult.
  • start defaults to where the arm is now.
  • start, goal and constraint each take a configuration,
    configurations, a TSR, TSRs, or any set.
  • holding="can" takes the grasp from the current poses.

Changed

• Errors name what exists: a missing site or joint lists the model's sites
  or joints, and the unlimited-joint error names the joint and both fixes.
  MuJoCoRobotModel(joint_limits=(lower, upper)) gives finite planning
  limits. Install hints match pyproject. NativeUnsupported is exported
  from sscbirrt (#174).
• CBiRRTConfig's set tolerances are documented as applying to the sets
  plan(...) builds (#177).

Deprecated

• Consistent names; the old ones keep working, with a DeprecationWarning,
  until 4.0 (#176).
  • CBiRRT(ik_solver=) is now ik=. ik is optional: planning between
    configurations never uses it, and TSRs without it raise a clear error.
  • CBiRRTConfig.tsr_samples / max_ik_per_pose are now sample_draws /
    max_per_draw, the names the native core already used. The budgets
    apply to any sampleable set, not only TSRs.
  • CBiRRTConfig.angular_joints and JointSpace(angular_joints=) are now
    continuous_joints. Every revolute joint is angular; the flag means
    unlimited.
  • sscbirrt.seeds is now explicit_samples, because seed means an RNG
    seed everywhere else.
• sscbirrt.backends.native_mujoco.plan_native: use sscbirrt.mujoco.plan.
  It keeps working, with a DeprecationWarning, until 4.0 (#175).

Removed

• The UR5e examples (ur5e_mujoco.py, ur5e_transport.py,
  tsr_union_demo.py), superseded by sscbirrt-demo on sscbirrt.mujoco.
  Their scene, which the reference artifact and the UR5e tests plan in, moved
  unchanged to sscbirrt.testing.ur5e; the artifact is bit-for-bit
  identical. multi_config_demo.py is now planar_arm.py -e 4, and
  planar_arm.py uses sscbirrt.testing's arm and IK. The examples extra
  no longer installs mediapy (#166).

Fixed

• Roots kept from one sampling draw are now a random subset of its
  candidates, as max_ik_per_pose's "for diversity" promised, on both
  backends. Previously the first max_ik_per_pose candidates were kept,
  in the sampler's order. An IK solver that enumerates branches and joint
  windings (SSIK on the UR5e returns 256 solutions per pose) lists them in
  a fixed order, so every draw contributed near-duplicates from one
  corner of the solution set. Draws at or under the cap consume no
  randomness: the planar reference cases are bit-for-bit unchanged, and
  the three UR5e cases have new paths that pass every validation (#168).

• dataclasses.replace(config, membership_tolerance=x) kept the old value,
  because the deprecated tsr_tolerance was a stored field mirroring it.
  Deprecated names are no longer fields (#176).

• The native backend's "All N start/goal configuration(s)" count matches
  Python's; it counted each rejected explicit candidate twice (#170).

• plan(start=[0.1, 0.2]): a flat list is one configuration on every
  backend, and a malformed start/goal raises a ValueError naming the
  argument and the expected shape. It used to crash under the default
  backend with TypeError: iteration over a 0-d array (#171).

• plan_native checks its arguments before doing any work. Pose regions
  without ik raise a ValueError naming ik, instead of leaking _NoIK
  or claiming there are no pose regions. A wrong site or joint is reported
  before the scene is built. A missing native scene says that fallback
  cannot cover it (#172).

• MuJoCoRobotModel, MuJoCoCollisionChecker and MuJoCoIKSolver no
  longer take every joint by default when the model has free or ball joints,
  which silently gave the wrong DOF; they ask for the arm's joints and list
  them (#173).

Documentation

• README images and links use relative paths, so they render on every
  branch, in pull requests and in local previews. The release build pins
  them to the release tag in the PyPI description (tools/pypi_readme.py),
  so PyPI shows each release's own images; before this, relative images
  were broken on PyPI.
• The README starts with installing and a runnable MuJoCo plan
  (sscbirrt.mujoco with the packaged UR5e), then the concepts. The
  PlanResult table lists backend, backend_reasons, provenance and
  stats. The MuJoCo snippets use real site names, and the tsr hand models
  are introduced for grasp regions. tests/test_readme.py runs the snippets
  (#178).
• The README starts with installing and a runnable MuJoCo plan
  (sscbirrt.mujoco with the packaged UR5e), then the concepts. The
  PlanResult table lists backend, backend_reasons, provenance and
  stats. The MuJoCo snippets use real site names, and the tsr hand models
  are introduced for grasp regions. tests/test_readme.py runs the snippets
  (#178).