feat: ecology as gameplay content layer

[aliciapaz]

Context

Beetle Rush is being turned into a pay-once, ad-free mobile game whose proceeds fund agroecology and ecological restoration research, designed to be fun rather than addictive. A generic endless runner has no path to buyers under that model; the durable edge is what the game is about. This change makes the ecology the game itself instead of flavor: the score stops being an arbitrary number and becomes the real reason dung beetles matter.

Implements idea 3 ("the mission is the product") from the ideation, per the requirements in docs/brainstorms/2026-07-18-ecology-as-gameplay-requirements.md and the plan in docs/plans/2026-07-19-001-feat-ecology-as-gameplay-plan.md.

What Changed

• Per-run soil-health meter replaces the point score and the player-health bar. Recycling clean dung raises soil health; pesticide-contaminated dung (renamed from "toxic dung") lowers it; a run ends when the ecosystem collapses to the floor. The final value is shown on the GameOver screen and sent to the leaderboard.
• In-context ecology notes. A note is enqueued the first time the player recycles clean dung, hits pesticide dung, or meets a frog, and the queue is flushed only at run-end so notes never interrupt play. Ignoring notes never blocks the game.
• Placeholder "why this exists" mission screen reachable from the title menu. Copy is a placeholder pending the parallel pledge effort.
• Testable pure-logic modules extracted so behavior is unit-tested without a headless Phaser harness: src/config/soilHealth.js, src/objects/noteQueue.js, src/config/ecologyNotes.js.

Notable decisions: soil health is per-run only (no cross-run persistence, keeping it a grind-free arcade game); the score and player-health systems are merged into one meaningful meter; new predators (birds, toads) are deferred because they need art.

How to Test

1. npm install (needs the cairo/pangocairo system libraries for the canvas dependency), then npm test — 14 unit tests should pass (soil-health, note-queue). npx eslint src should be clean.
2. npm start and play a run:
   • Collecting clean dung raises the soil-health meter; pesticide dung lowers it.
   • A run ends on frog contact or when soil health bottoms out.
   • On GameOver, the ecology notes for what you encountered this run appear once. Nothing pops up mid-run.
   • The title menu "Why" button opens the mission screen; the Help screen shows the pesticide dung icon (not a missing-texture box).
3. Edge cases: enter GameOver without dying repeatedly (verify notes are not lost to a double-flush); ignore all notes and confirm the game stays fully playable.

Note: the Phaser scene layer was not runtime-verified in CI here because the canvas native dependency could not build (missing system libs). The extracted logic is unit-tested; the in-game wiring should get one manual playthrough before release.

Deployment Tasks

None.

Known follow-ups (not in this PR)

• Birds and toads predators (need art).
• Ecological-accuracy review of note content with a specialist before release.
• Real mission-screen copy and the leaderboard-metric decision (old point-scores currently share the board with soil-health values), both from the parallel pledge effort.