feat(dart): physics_basics example (reactphysics3d_dart + thermion)

[nmfisher]

Closes ticket the-tvf4.

Adds a physics_basics example: boxes and spheres dropped into a walled pen, simulated with reactphysics3d_dart and rendered with thermion_dart. Registered in the example registry for the headless CLI runner, and as the physics scene in the web gallery.

Supersedes #238.

Web path (this update)

Implements Option C of docs/research/web-physics-scope.md: ReactPhysics3D is linked into the single thermion_dart.wasm, so there is only one Emscripten module and the NativeLibrary.instance singleton conflict dissolves — the module that the gallery's existing initBindings("thermion_dart") call points at exports the _rp3d_* C API alongside the _Thermion_* one. No Dart-side changes, no ffigen_js work, no second loader.

This PR no longer builds ReactPhysics3D itself. reactphysics3d_dart now publishes prebuilt libraries from its own "Build artifacts" workflow (v* tag pushes), so thermion downloads the published artifact instead:

• scripts/download_reactphysics3d.sh replaces scripts/build_reactphysics3d_web.sh. Pinned to RP3D_DART_TAG=v0.1.0, it stages exactly what the EXTERNAL_PROJECTS hook needs from that release:
  • a reactphysics3d_dart checkout at the tag — this provides native/web/reactphysics3d_dart.cmake (the file EXTERNAL_PROJECTS points at), the C API wrapper that cmake compiles from source, and the headers;
  • libreactphysics3d.a (engine, wasm32) from the reactphysics3d_dart-0.1.0-web-emscripten.zip release asset, dropped next to the cmake file, which imports it as a prebuilt library.
  • The zip's prebuilt wrapper (libreactphysics3d_dart.a) is deliberately not extracted: compiling the wrapper from source keeps the C API matched to the checked-out tag's vendored headers. Checkout and zip come from the same tag, so the bindings and the engine library cannot drift apart.
• make wasm still configures with -DEXTERNAL_PROJECTS=<that .cmake>; the existing -Wl,--whole-archive group keeps the otherwise-unreferenced rp3d objects alive. EXTERNAL_PROJECTS_CMAKE= (empty) still builds a physics-less WASM.
• scripts/verify_web_wasm_exports.sh is also removed: that repository's build-artifacts workflow verifies the exports of what it publishes, so thermion's link step only consumes it. The CI cache and paths-filter now key on the download script, so a tag bump in it re-fetches instead of rebuilding.

Verified locally (emsdk 6.0.4, same as CI): against a local mirror serving the genuine web-emscripten artifact from that workflow, the download script staged the tagged checkout + libreactphysics3d.a, was idempotent on re-run, and a clean make wasm produced thermion_dart.wasm (3.99 MB) with 142 _rp3d_* exports; a node smoke test ran the same create → 300 steps → destroy cycle as setupPhysicsBasics against the built WASM. dart analyze clean on thermion_dart and examples_lib.

One prerequisite: v0.1.0 must exist as a tag + release on reactphysics3d_dart (git tag v0.1.0 && git push origin v0.1.0 there). Until it does, make wasm fails with that exact instruction printed by the download script — it cannot fall back to a silent rp3d-less build.

Remaining blocker: reactphysics3d_dart ref bump

The three ffigen_js dependency_overrides stay — they cannot be deleted yet. At the pinned ref (52eec72e) reactphysics3d_dart still pins ffigen_js 0.0.5-pre, and removing the overrides makes dart pub get fail:

Because every version of reactphysics3d_dart from git depends on ffigen_js 0.0.5-pre
and every version of thermion_dart from path depends on ffigen_js ^0.0.14-pre,
reactphysics3d_dart from git is incompatible with thermion_dart from path.

Additionally, dart compile wasm of the web gallery currently fails inside reactphysics3d_dart (0.0.5-era Pointer operator[], missing generated bindings, a direct dart:ffi import) — note this is independent of the gallery registration here, because examples_lib.dart already exports physics_basics.dart, so the import chain from web_gallery pulls those files in either way.

Once reactphysics3d_dart lands the ffigen_js bump + regenerated web bindings, the follow-up on this repo is: bump the git ref in examples_lib/pubspec.yaml, bump RP3D_DART_TAG in scripts/download_reactphysics3d.sh, and delete the three overrides.

What CI must confirm

• The real GitHub release download works end-to-end (the local verification used a mirror of the genuine artifact): Generate Artifacts → Compile web runs make wasm with rp3d linked — after v0.1.0 is pushed on reactphysics3d_dart.
• On merge to develop, the R2 upload + web.version bump steps produce an artifact that actually contains rp3d — thermion_dart/native/web/web.version still points at 67bfb19 until then, so anything downloading before that still gets the rp3d-less wasm.
• Deploy site (release tag) builds the gallery — blocked on the reactphysics3d_dart ref bump above.

Verified

• headless runner produces output/physics_basics.png, dart analyze clean (from the original PR)
• combined WASM builds from the downloaded release artifact and exports _rp3d_*; rp3d runs inside it (see above)

🤖 Generated with Claude Code