UI States
Make the embedded shell predictable across loading, sizing, expiration, and errors
Build your shell around these states. For the exact session fields, see the session contract and the API reference.
| State | Shell behavior |
|---|---|
| Session loading | Show product-owned loading UI; do not mount an unauthenticated iframe |
| Iframe loading | Keep stable dimensions and show a loading layer |
| Channel connecting | Validate iframe window and exact origin before port transfer |
| Ready | Remove loading only after the authenticated channel sends ready |
| Sizing | Apply positive integer heights from resize, or retain fixed dimensions |
| Bootstrap expiring | Mount before bootstrapExpiresAt, 60 seconds after issuance |
| Session expiring | Request a successor and send its complete URL through session.renew |
| Session renewed | Keep iframe mounted with its current route, filters, and report state |
| Session expired | Show an expired state and create a new identity-bound iframe session |
| Access denied | Stop retries and show an account/team access action |
| Network failure | Offer bounded retry without changing team or credential |
A missing, malformed, replayed, expired, or access-denied initial session
renders an explicit error screen inside the iframe because no authenticated
channel exists yet. After channel connection, branch on the strict error
code and recoverable value instead of parsing display text.
If the selected team changes, revoke the old session and create a new one for the new team. Never reuse a token from another team merely because the iframe URL is still open.
Log correlation IDs and structured error codes in your backend diagnostics, but do not expose bootstrap URLs, codes, partner secrets, or bearer tokens in browser telemetry.