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

.github/workflows/build-filament.yml

@@ -488,7 +488,7 @@ jobs:
       - name: Setup Emscripten
         uses: mymindstorm/setup-emsdk@v14
         with:
-          version: '3.1.60'
+          version: '6.0.4'
 
       - name: Build Filament
         run: |

.github/workflows/generate-artifacts.yml

@@ -69,6 +69,11 @@ jobs:
             materials-changed:
               - 'materials/**'
               - 'examples/assets/*.mat'
+              # A Filament version bump can change the material package format
+              # (MaterialDefinition panics on version mismatch), so the
+              # materials must be recompiled with the new matc even when no
+              # .mat source changed.
+              - 'filament.version'
 
       - name: Setup CMake
         if: steps.changes.outputs.native-changed == 'true'
@@ -200,7 +205,7 @@ jobs:
         uses: actions/cache@v4
         with:
           path: thermion_dart/native/web/lib/release
-          key: filament-web-${{ hashFiles('Makefile') }}
+          key: filament-web-${{ hashFiles('filament.version') }}
           restore-keys: |
             filament-web-
 

.tickets/the-0rkw.md

@@ -0,0 +1,72 @@
+---
+id: the-0rkw
+status: open
+deps: []
+links: []
+created: 2026-08-14T10:09:54Z
+type: task
+priority: 2
+assignee: Nick Fisher
+tags: [build, cmake, binary-size, proposal]
+---
+# Proposal: compile-time opt-in/out of optional libraries (libpng, libz, etc.) to reduce binary size
+
+Plan how to make optional native libraries (e.g. libpng, libz) opt-in/opt-out at compile time so consumers who don't need them get smaller binaries. PROPOSAL-ONLY: analysis + proposal document, no code changes.
+
+## Sandbox brief (for the agent — read this first)
+
+You are a coding agent writing a PROPOSAL for the thermion native build.
+This task is PROPOSAL-ONLY: analyze and write a proposal document. Make NO
+code, build, or test changes. Do not run builds.
+
+### Goal
+
+Plan how to make optional native libraries opt-in/opt-out at compile time,
+so consumers who do not need them get smaller binaries. Examples Nick
+named: libpng, libz. The question: are these always needed, and can we
+compile them out to reduce binary sizes?
+
+### Context (verified on the host)
+
+- Per-platform build scripts in scripts/: build_android.sh, build_ios.sh,
+  build_linux.sh, build_macos.sh, build_web.sh, build_windows.bat.
+- Linux/macOS builds add Filament third_party include dirs, e.g.
+  -I$FILAMENT_BASE_DIR/third_party/libpng, tinyexr, basisu/encoder
+  (build_linux.sh:210/226, build_macos.sh:184/197/243/256).
+- Web CMakeLists (thermion_dart/native/web/CMakeLists.txt) imports static
+  libs: filament, gltfio_core, image, uberzlib, z, zstd, mikktspace,
+  filameshio, etc. (lines ~157-278).
+- Filament itself bundles these third_party libs; thermion_dart/native
+  holds the Dart FFI bindings + native wrapper.
+
+### Deliverable — proposal document (docs/optional-libs-proposal.md or similar)
+
+Cover:
+1. Which native libraries are linked today, per platform, and what they
+   are used for (find actual usage in thermion_dart/native source —
+   e.g. where does the wrapper touch png/zlib/image decoding?).
+2. Which libraries could plausibly be optional (not needed by every
+   consumer) vs which are core (Filament runtime deps).
+3. The mechanism: CMake options (e.g. THERMION_ENABLE_IMAGE_IO=OFF),
+   feature flags, preprocessor guards, per-platform wiring in the build
+   scripts, and how the Dart side would expose the capability at runtime
+   (e.g. capability query so the app knows what is compiled in).
+4. Realistic binary-size impact per library (estimate; note that static
+   linking only includes referenced symbols, so dead-code elimination may
+   already shrink much of it — be honest about expected gains).
+5. Risks: what breaks if a lib is removed (gltfio needs image decoding?
+   assets need png?), API surface changes, test impact.
+6. Recommended first step(s) and an ordered plan.
+
+### Rules
+
+- Update this ticket with tk: start the-0rkw when you begin, close it when
+  done (tk may not be installed — edit the status field directly).
+- Commit the proposal document locally on the asb/ branch.
+- DO NOT raise a PR. DO NOT push the branch. This is LOCAL PLANNING ONLY —
+  Nick will review the proposal document in the sandbox volume.
+- Do NOT close this ticket (the-0rkw) — leave it open until Nick reviews.
+- Keep the sandbox/volume alive: commit locally, that is all.
+- Simplified technical English: short sentences, plain words.
+- PROPOSAL-ONLY: no code/test/build changes. Ever. This is a plan.
+

.tickets/the-c8d3.md

@@ -0,0 +1,161 @@
+---
+id: the-c8d3
+status: closed
+deps: []
+links: []
+created: 2026-08-14T11:21:35Z
+type: bug
+priority: 2
+assignee: Nick Fisher
+tags: [build, linux, debug, filament]
+---
+# Fix Linux v1.75.0 debug artifact problem (debug hook builds fail)
+
+Linux debug hook builds fail: the v1.75.0 linux debug R2 artifact has an issue (found during the-0rkw lib-stripping work). Pre-existing, not caused by the stripping change. Investigate the artifact and fix the debug build.
+
+
+## Details (from the-0rkw proposal work, 2026-08-14)
+
+### The problem
+
+Linux **debug** hook builds fail: the v1.75.0 linux *debug* R2 artifact's
+`include/` directory lacks `bluevk/BlueVK.h` (the release artifact has
+it). This was seen before any of the lib-stripping edits — it is a
+pre-existing problem with the downloaded Filament debug artifact, not
+caused by the-0rkw.
+
+### Context
+
+- Filament prebuilt artifacts are downloaded by version (R2 = v1.75.0
+  debug in this case). Release has the header, debug does not.
+- The debug build fails at compile time when the hook includes
+  `<bluevk/BlueVK.h>` (via vulkan headers, e.g. LinuxVulkanContext /
+  LinuxVulkanUtils under thermion_dart/native/include/vulkan/linux/).
+
+### What to do
+
+1. Confirm the exact failing include and where it comes from.
+2. Fix the debug build. Options to evaluate:
+   - Patch/copy the missing header from the release artifact (if the
+     debug artifact is just missing a file).
+   - Check whether the debug artifact download is corrupted/incomplete
+     and re-fetch.
+   - Adjust the build hook to tolerate the missing header.
+   - Bump/pin the artifact version if the upstream artifact is broken.
+3. Verify: `scripts/build_linux.sh --debug` completes; the debug `.so`
+   builds and links (ldd -r clean).
+4. Note any relationship to the-0rkw's `libraries:` placement change —
+   the debug failure predates it, but confirm the debug build works with
+   the new hook either way.
+
+### Rules
+
+- Standard: branch + PR (or local-only if Nick says so), never push to
+  master/develop directly, never merge.
+- Simplified technical English.
+
+## Sandbox brief (for the agent — read this first)
+
+You are a coding agent fixing the Linux debug build. Work on the asb/
+branch (e.g. asb/linux-debug-artifact). The ticket above is the spec.
+
+### Steps
+
+1. Reproduce: run `scripts/build_linux.sh --debug` (or the failing hook
+   step) and confirm the exact error (missing bluevk/BlueVK.h).
+2. Investigate the v1.75.0 linux debug R2 artifact — where it comes
+   from, whether it is genuinely missing the header or the download is
+   incomplete/corrupted.
+3. Fix it, evaluating the options in the ticket (patch header from
+   release artifact / re-fetch / tolerate in hook / bump-pin version).
+   Pick the safest fix that works for other machines too (do NOT rely on
+   local state).
+4. Verify: `scripts/build_linux.sh --debug` completes and the debug
+   `.so` links clean (ldd -r). Also confirm the release build still
+   works (the-0rkw hook changes are on asb/optional-libs-proposal — if
+   that branch's hook is not merged, build against the current branch's
+   hook and note the interaction).
+5. Report: root cause, the fix, verification output.
+
+### Rules
+
+- Update this ticket with tk: start the-c8d3 when you begin, close when
+  done (tk may not be installed — edit the status field directly).
+- Commit all work locally on the asb/ branch.
+- Push + open a PR when finished (if git push is blocked, commit and
+  report — the main agent will push).
+- Never merge the PR. Never commit or push directly to master/develop.
+- Simplified technical English: short sentences, plain words.
+
+## Resolution (2026-08-14, asb/linux-debug-artifact)
+
+### Root cause
+
+The download was NOT corrupted. The debug zip itself is missing the
+headers. `scripts/build_linux.sh`'s debug block copied the bluevk
+headers to `$TARGET_RELEASE_DIR/include/` instead of
+`$TARGET_DEBUG_DIR/include/` (copy-paste typo). So the debug zip ships
+`libbluevk.a` but no `bluevk/`, `vulkan/`, or `vk_video/` headers, and
+the release zip just got them twice.
+
+Verified by downloading both R2 zips and diffing their `include/`
+trees: the debug zip is missing exactly the `libs/bluevk/include/`
+tree. Reproduced the compile failure with clang against the extracted
+debug include dir (`fatal error: 'bluevk/BlueVK.h' file not found`).
+
+Same typo existed in the debug blocks of `build_macos.sh` and
+`build_ios.sh` (Android was already correct). Fixed all three.
+
+### Second bug found (masked by the first)
+
+After the headers were fixed, Linux debug linking failed: `libmatdbg.a`
+and `libfgviewer.a` both bundle civetweb, and the hook linked them
+inside `-Wl,--whole-archive`, so every member of both was pulled in ->
+"multiple definition of `mg_*`". Fixed in `hook/build.dart`: on Linux,
+`matdbg`/`fgviewer` now link AFTER `--no-whole-archive` (normal archive
+semantics pull only needed members; `libfilament.a` is whole-archived
+so its references still resolve).
+
+### Fix (2 parts)
+
+1. `scripts/build_linux.sh` (+ macos/ios): debug block now copies
+   bluevk headers to `$TARGET_DEBUG_DIR`. Future artifacts are correct.
+2. `thermion_dart/hook/build.dart` (`getLibDir`): after extraction, if
+   `include/bluevk/BlueVK.h` is missing, fetch the release zip of the
+   same version/platform and merge `bluevk/`, `vulkan/`, `vk_video/`
+   into the cache. Headers are build-mode-independent. Checked outside
+   the success-token guard, so caches extracted from a broken zip heal
+   too. No-op once artifacts are re-uploaded correctly. Skipped on iOS
+   (never compiles vulkan sources). This makes existing machines work
+   without waiting for an R2 re-upload.
+
+NOTE for Nick: the v1.75.0 linux (x64 + arm64), macOS and iOS DEBUG
+zips on R2 are still missing the bluevk headers. Rebuild/re-upload when
+convenient (the hook repair covers users in the meantime; sandbox had
+no R2 credentials so re-upload was not possible from here).
+
+### Verification
+
+- Reproduced original failure (missing `<bluevk/BlueVK.h>`), confirmed
+  repair logs fire and build proceeds.
+- `examples/dart/cli_headless` with `mode: debug` (aarch64 host,
+  linux-arm64 debug artifact): hook compiles + links
+  `libthermion_dart.so` (347 MB). `ldd -r` reports the same 48
+  undefined symbols as the RELEASE build (png_*/mz_*/basisu encoder
+  symbols, pre-existing, identical set in both modes — not a debug
+  regression; both also behave the same under `dlopen` RTLD_NOW).
+- Release build with the same modified hook: completes fine (bluevk
+  repair is a no-op there).
+- `dart analyze hook/build.dart`: clean. `flutter analyze`: 0 errors
+  (51 pre-existing infos). `bash -n` on all three scripts: OK.
+- Full `scripts/build_linux.sh --debug` (Filament from source) not run:
+  no filament checkout in the sandbox. The script fix is the one-line
+  target-dir correction; verified by inspection + parse.
+- the-0rkw interaction: built against the current branch's hook (the
+  asb/optional-libs-proposal hook is not merged here). The debug
+  failure predates it and the fix is independent of `libraries:`
+  placement.
+- Example's own Dart code has pre-existing API drift errors
+  (`FilamentApp.register`) unrelated to this ticket; the native build
+  hook (the failing step) completes.
+

.tickets/the-tvf4.md

@@ -0,0 +1,39 @@
+---
+id: the-tvf4
+status: closed
+deps: []
+links: []
+created: 2026-08-14T14:54:21Z
+type: feature
+priority: 2
+assignee: Nick Fisher
+tags: [dart, examples, physics]
+---
+# Create a Dart sample demonstrating basic physics
+
+Create a Dart sample (thermion example) showing basic physics. Use reactphysics3d_dart for the physics simulation and thermion_dart for rendering.
+
+## Context
+
+- Reference app: ~/Documents/mixworld (Flutter app, mounted read-only).
+  It already wires thermion_dart + reactphysics3d_dart together. Read it to
+  learn the integration pattern.
+- Physics package: reactphysics3d_dart (mounted read-only at
+  /Volumes/T7/projects/reactphysics3d_dart). It is a git repo on branch
+  master. It has an example/ dir with a heightfield example.
+- The sample lives in this repo (thermion), under examples/dart.
+  Follow the existing example structure (examples_lib / web_gallery).
+- Physics + rendering should run in the browser (WASM), like the other
+  dart examples.
+
+## Acceptance criteria
+
+1. New dart example under examples/dart that shows basic physics:
+   objects falling, bouncing, or colliding, rendered with thermion.
+2. Registered in the example registry so it appears in the web gallery
+   (see examples/dart/examples_lib/lib/src/registry.dart and
+   examples/dart/web_gallery).
+3. Works in the browser (WASM build), verified by building/running it.
+4. Code follows existing example style and passes `flutter analyze` /
+   `dart analyze` where applicable.
+

CHANGELOG.md

@@ -2,12 +2,15 @@
 
 ## 0.6.0
 
+Update to Filament v1.75.0!
+
 ### Breaking changes
 - `LightManager.setShadowCaster`/`setShadowOptions` and
   `RenderableManager.setCastShadows`/`setReceiveShadows` now return `Future`
   instead of `void` (internally, these now correctly run on the
   main Filament thread).
 
+
 ## 0.5.0-pre.5
 
 - Rework the CI release pipeline: releases are cut from `develop` via a manual

Makefile

@@ -1,13 +1,14 @@
 wasm:
-	@if [ ! -f thermion_dart/native/web/lib/release/filament-v1.69.1-web-release.zip ]; then \
-		echo "Downloading filament-v1.69.1-web-release.zip..."; \
+	@if [ ! -f thermion_dart/native/web/lib/release/filament-v1.75.0-web-release.zip ]; then \
+		echo "Downloading filament-v1.75.0-web-release.zip..."; \
 		mkdir -p thermion_dart/native/web/lib/release; \
-		curl -L -o thermion_dart/native/web/lib/release/filament-v1.69.1-web-release.zip \
-			https://pub-c8b6266320924116aaddce03b5313c0a.r2.dev/filament-v1.69.1-web-release.zip; \
-		echo "Extracting filament-v1.69.1-web-release.zip..."; \
-		cd thermion_dart/native/web/lib/release && \
-		unzip filament-v1.69.1-web-release.zip; \
+		curl -L -o thermion_dart/native/web/lib/release/filament-v1.75.0-web-release.zip \
+			https://pub-c8b6266320924116aaddce03b5313c0a.r2.dev/filament-v1.75.0-web-release.zip; \
 	fi
+	@echo "Extracting filament-v1.75.0-web-release.zip..."; \
+	cd thermion_dart/native/web/lib/release && \
+	rm -rf include lib && \
+	unzip -o filament-v1.75.0-web-release.zip
 	cd thermion_dart/native/web && \
 	mkdir -p build && \
 	cd build && \

examples/README.md

@@ -2,4 +2,18 @@
 
 This repository contains example Dart and Flutter projects for the Thermion rendering toolkit.
 
+## Dart examples
+
+Shared scene setups live in `dart/examples_lib`; each is registered in
+`dart/examples_lib/lib/src/registry.dart`. Render any of them offscreen with
+the headless CLI runner:
+
+```sh
+cd dart/headless_runner
+dart run bin/run_example.dart <name> [width] [height]   # PNG lands in output/
+```
+
+`physics_basics` (ReactPhysics3D simulation rendered with Thermion) is
+native/headless only -- it is not wired into the WASM web gallery. See the
+note at the top of `dart/examples_lib/lib/src/physics_basics.dart`.
 

examples/dart/examples_lib/lib/examples_lib.dart

@@ -22,6 +22,7 @@ export 'src/lighting_setup.dart';
 export 'src/load_gltf.dart';
 export 'src/materials_pbr.dart';
 export 'src/morph_targets.dart';
+export 'src/physics_basics.dart';
 export 'src/picking.dart';
 export 'src/post_processing.dart';
 export 'src/render_targets.dart';