feat: add configurable masterclass panel with event bus for external integration

[rx18-eng]

Closes #824 #826

Adds a configurable masterclass panel for tagging particles and computing
invariant masses, designed to be reusable across experiments.

What it does

Students can select tracks from any collection, tag them as particle types,
see kinematic values in a table, and compute invariant masses. Results can be
recorded across events and exported as a text file.

Architecture

The panel is experiment-agnostic. All experiment-specific details
(particle types, masses, hints, event classification) are defined in a
MasterclassConfig interface and passed as an input — not hardcoded.

• MasterclassConfig — defines particle tags (id, symbol, color, mass),
  educational hints, and a classification callback
• ATLAS_MASTERCLASS_CONFIG — default config for ATLAS Z-path exercises
  (e±/μ±/γ, Z/Higgs/J/ψ hints)
• Adding a new experiment's masterclass (e.g. LHCb D0 → Kπ) requires only a
  config object — no component changes

Integration API

A lightweight event bus (on/emit) is added to EventDisplay, enabling
external frameworks to subscribe to live data:

typescript
eventDisplay.on('particle-tagged', (data) => { /* tag, uuid, fourMomentum, pT,
 eta, phi */ });
eventDisplay.on('result-recorded', (data) => { /* eventType, mass,
particleCount */ });

This allows external tools (e.g. histogram frameworks) to react to user
actions without modifying Phoenix.

Files

Core library (phoenix-event-display):

• helpers/invariant-mass.ts — generic 4-momentum math +
  MasterclassConfig/ParticleTagDef types + ATLAS default config
• event-display.ts — on(event, callback) / emit(event, data) event bus

UI components (phoenix-ui-components):

• masterclass-panel/ — toolbar toggle + overlay panel, config-driven via
  @input()
• ui-menu.component — threads masterclassConfig input to panel

App (phoenix-app):

• atlas.component — passes ATLAS_MASTERCLASS_CONFIG to ui-menu

Test plan

• Load ATLAS section with default JiveXML event
• Open masterclass panel (atom icon), select tracks, tag particles
• Verify invariant mass computation and hints display
• Record results and export file
• Verify no console errors on LHCb/other sections

Recording.2026-03-13.160329.mp4

[rx18-eng]

Hey @EdwardMoyse @sponce , this account is my temporary replacement for my previous account remo-lab .
Also this pr was made based on my discussions with @sponce , please let me know your thoughts on this!

[sponce]

Hi @rx18-eng, good to see you back ! I did not have time to look carefully to this PR yet, but I'll do it next week for sure.

[rx18-eng]

Thanks @sponce for your review ! it really means a lot coming from you. I was honestly a bit worried due to the overnight GitHub situation, so I really appreciate your feedback!

[rx18-eng]

@sponce does this feature looks good to you?

[sponce]

Sorry, I thought I had commented about this, but I must have lost myself.
So I'm not really the one able to judge here, I have to ask the people dealing more directly with the LHCb master class what are the needs. @bcouturi what do you think ?

[EdwardMoyse]

@rx18-eng this has picked up conflicts. Could you have a look? I think it looks really good, but like Sebastien I'm not an expert - maybe we can schedule a chat about this @bcouturi?

[rx18-eng]

@EdwardMoyse I have fixed the merge conflicts let me know if i need to tweak anything else !

[sponce]

I've pinged @bcouturi, let's try to discuss it with him

[bcouturi]

That's very cool !
The difference with the LHCb masterclass is that:

• in the masterclass the particle information is already known (there is no "tagging" phase)
• the selection of the particles is done in the 3D display, by looking for displaced vertices (i.e. pairs of tracks that seem to appear our of nowhere, from a point displaced from the proton collision point)

Furthermore, to simplify the exercise, the user interface only has the features needed to perform the exercise.

[EdwardMoyse]

Hi @bcouturi did you also see #848?

Also - I think you can click in the 3D view and the tracks are selected.

[bcouturi]

Hi have not seen #848.

I see that it is merged, I will try and start an instance of Phoenix with LHCb and those features enabled to give it a go to get a better feeling.