Shell vs embed

Scenaven ships as two related frontends. Most day-to-day visualization happens in the embed; the shell is the sign-in entry point.

Auth shell

What you may see at login:

  • Scenaven branding and sign-in
  • AntiNode authentication
  • An iframe that loads the production viewer after sign-in

The shell does not render simulation data itself. It:

  1. Confirms your identity
  2. Loads the embed from your deployed viewer-ui URL
  3. Passes your session token and infrastructure settings to the embed via a secure channel

Developers run the shell locally (npm run dev on index.html) while the embed may point at a cloud or local viewer-ui deployment.

Embed (production viewer)

What you use to visualize data:

  • Full Three.js viewport
  • Sidebar cards, HUD, agent rail, help overlay
  • Direct communication with mesh-api (through viewer-ui proxy)

The embed bundle is built with build:embed and served by viewer-ui in both cloud and on-prem Docker. This is the same code whether you open it from the shell iframe or a direct embed URL.

viewer-ui service

Sits between browser and mesh-api:

  • Serves the embed static files (embed.html, assets, /help/*)
  • Reverse-proxies /api/mesh/* to mesh-api
  • Keeps a single origin so auth cookies, CORS, and relative API paths work in the iframe

You typically do not interact with viewer-ui directly — you use the viewer UI it serves.

Which one am I using?

Situation What you see
Signed in at the Scenaven landing page Shell → iframe → embed
Direct link to /embed or /embed/session Embed only
Embedded in Dash, Streamlit, or a custom app Embed only (parent passes auth)

In all cases the visualization experience inside the embed is identical.

Third-party embedding

If you embed Scenaven in your own application, you load the embed URL in an iframe and use the documented postMessage protocol for auth and mesh configuration. See §1.10 in docs/PLATFORM.md in the repository.