[rx18-eng]

Summary

Phoenix actions currently only exist as click handlers inside the Angular app. There's no way to list what Phoenix can do, run something by name, or let another page drive it. This adds one action layer that everything sits on, then three ways to reach it: a keyboard palette, a natural-language Ask box, and a JSON-RPC bridge for other pages and agents.

Closes #826. Implements #942.

Motivation

#826 has been open for a while asking for easier integration of Phoenix into other applications. There was no structured way in, so every embedder had to reach into internals.

Separately, #903 and #916 are about the icon bar getting crowded. A palette gives you a way to reach a feature without hunting for its icon.

What's included

Command registry

A CommandRegistry in phoenix-event-display with 16 commands wrapping actions that already existed:

describe-event, get-object, highlight-object, list-collections, load-event, look-at-object, next-event, preset-view, previous-event, set-clipping, set-geometry-visibility, set-theme, show-axis, toggle-auto-rotate, toggle-camera-projection, zoom

Every command carries a JSON schema and execute() validates arguments before anything runs. No Angular, no rxjs, no new dependencies, so CMS, LHCb and TrackML get it for free.

Command palette

Ctrl/Cmd+K over the registry, plus a toolbar button for people who don't know the shortcut. Commands that take arguments open a small form rather than running blind.

Ask box

Two jobs in one input. It runs commands from plain English, and it answers questions from a vetted knowledge base (156 curated entries covering Phoenix features and masterclass physics).

Answers are extracted from reviewed text, never generated, so it cannot invent physics at a student. When it isn't confident it either says so or offers a "did you mean" instead of guessing.

An in-browser model (Qwen2.5 1.5B via WebLLM) is available for phrasings the keyword matcher misses. It's off by default, lazy loaded, needs WebGPU, and the keyword path works without it. Nothing leaves the browser.

Agent bridge

JSON-RPC 2.0 over postMessage using MCP method names (initialize, tools/list, tools/call, and a phoenix/event stream). Dormant unless an app opts in.

Guide at guides/developers/agent-bridge.md, framework-free demo at examples/agent-bridge-demo.html.

How to test

Palette

Press Ctrl/Cmd+K, stay on the Commands tab, type a few letters and hit Enter:

dark
axis
clip
rotate
ortho

Ask box, running commands

Ctrl/Cmd+K, then the Ask tab:

hide the calorimeter
turn off dark mode
spin the detector
show me the right view
go to the next event
switch to an orthographic camera
zoom in

The awkward ones are worth trying, since they were real bugs caught during testing. "turn off dark mode" used to turn it on, "go back to perspective" used to navigate to another event, and "hide everything except the pixel" used to hide the Pixel. That last one now declines rather than doing the opposite of what you asked.

Ask box, asking questions

what is a jet
what is eta-phi
what is the higgs boson
what is missing energy
how do i use the kinematics panel

Typos are handled:

whats a calorimter
what is altas
define pseudorapidty
explain teh higgs boson

Two deliberate behaviours worth checking. tell me about phnix gives you "Did you mean Phoenix?" rather than a guess. what is the meaning of life tells you it doesn't know instead of making something up.

With the model enabled

Toggle it on in the Ask box (needs WebGPU, roughly a 1 GB one-time download). Try phrasings the keyword matcher won't catch:

could you make the detector spin for me
I'd like to see this from the side please
get rid of the calorimeter geometry

Agent bridge

Serve the repo locally, open examples/agent-bridge-demo.html, and point it at /atlas?agent=1. You can list the tools and call them from the parent page.

Without ?agent=1 there is no listener at all, and it only arms on localhost or on origins an app explicitly configures.

Safety

Only registered, schema-validated commands can run, so neither the model nor an embedding page can reach arbitrary Phoenix internals.

Tutor answers come from reviewed text, with a gate that fails the build if an answer is ever emitted that isn't from a vetted entry.

The bridge is off unless opted in, is origin-allowlisted, and only enrolls a client after a valid initialize, so a malformed message cannot subscribe itself to the event stream.

Testing

796 tests in phoenix-event-display and 359 in phoenix-ng, all passing, each run three times to check for flakes. Documentation coverage is at 100%. AOT production build is clean and the model stays in lazy chunks, so it costs nothing until someone turns it on.

Also checked live in a browser with keyboard-only input (focus trap, ARIA combobox, Escape, focus return to the trigger) in both light and dark themes.

Known limitations

The palette stylesheet is about 420 bytes over the anyComponentStyle warning budget. Warning only, the build passes.

The in-browser model is optional and WebGPU only.

The bridge ships one transport (postMessage). An MCP server adapter would map onto the same method names with no rework.

[github-actions]

🚀 Preview deployed: http://phoenix-pr-1039.surge.sh

Built from dedeee2.

[sponce]

Looks great ! I love it. Now I've tried it a bit on LHCb and I can already report a few bugs :

• the Shift + T shortcut works on the first attempt, but subsequent ones seems to only change the icon, not the mode itself. In my case I was dark to start with, I could switch to normal, but no way to go back to dark
• at the same time, the detector started rotating by itself (so maybe commands are mixed)
• the AI natural language was hard to use. It really understand only few sentences. But it's already nice to have it

[ulekarsiddhant0-boop]

Hi @rx18-eng , I came across #942 while exploring Phoenix and I'm really interested in contributing to the project. The command API, natural-language interface, and agent bridge are exciting additions.

I looked through PR #1039 and noticed the feedback about the theme-switching behaviour and natural-language command accuracy. I'd love to help test and improve this feature.

Would it be useful if I started by reproducing these issues, adding regression tests, or investigating other outstanding problems in the PR? I'm happy to work on a specific task that would be helpful to the project.
Thanks for the work you've put into this!