Add example: Enter a 360° photosphere (#4428)

[clement-igonet]

Fixes #4428 with a documentation example: click a marker to "enter" a 360° photosphere at that location. A custom layer ray-casts each screen pixel into panorama UV space; entering animates a real fly-in with parallax (ray-sphere intersection until the eye reaches the center). Photo: Alexandre Duret-Lutz, CC BY-SA 2.0.

Launch Checklist

• Confirm your changes do not include backports from Mapbox projects
• Link to related issues
• Include before/after visuals (gallery thumbnail)
• Confirm you have read our AI policy

Assisted-By: Claude Sonnet 5 (claude-sonnet-5)

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.38%. Comparing base (14dfbcf) to head (9c12057).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #7942      +/-   ##
==========================================
- Coverage   93.39%   93.38%   -0.01%     
==========================================
  Files         290      290              
  Lines       24579    24579              
  Branches     6471     6471              
==========================================
- Hits        22955    22953       -2     
- Misses       1624     1626       +2     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[CommanderStorm]

very buggy and too much code for me to debug.
Also does not work correctly, since the photosphere does never show:

[clement-igonet]

Found two causes for the photosphere never showing and fixed both:

1. The example used the openfreemap liberty style, which crashes the map in some environments (symbol placement errors), so the marker click never worked. The basemap is now plain OpenStreetMap raster tiles.
2. The Map lacked centerClampedToGround: false, so the eye-height elevation passed during the enter/exit animations was re-clamped to the ground.

Verified end to end (marker click, panorama shown, drag to look around, exit) and regenerated the thumbnail.

[CommanderStorm]

So, I read over #4428 what you said is the problem and what you are now adding is a bit different.
In that isue, you asked for an simple way to add photospheres, so a plugin, but here you are adding an custom layer..

I think this should be a plugin and the example should show how to use said plugin.
This way, we can properly test it in the plugin and not have the issues here.
Examples should be relatively simple imo, otherwise it is very hard to understand.
At 500 lines, I think this is a bit too complex for an example.

[clement-igonet]

Agreed, moved the implementation to a plugin: the Photosphere class (shaders, enter/exit transitions, look controls) now lives in a maplibre-gl-photosphere package with its own unit tests, and this example is down to 135 lines of plugin usage. Converting back to draft until the package is published on npm so the unpkg import in the example resolves.

[HarelM]

This file should be in assets, but not inside the examples folder. this folder is kept for the examples "thumbnail" image.

[HarelM]

I think this looks fine now.
I've added a small comment regarding moving a file to a different place, otherwise looks good.

[CommanderStorm]

assuming Harels move is done