The isolation model

Your app does not run in the same page as the shell. It runs in its own iframe, on its own origin, and talks to the shell only through postMessage. The SDK exists to make that boundary feel like an ordinary client API.

Why an iframe

• Fault isolation. A crash, an unhandled exception, or a runaway script in your app cannot take down the shell or a sibling app. The blast radius is your own frame.
• Framework freedom. You ship whatever framework and version you like. The shell is zoneless Angular; your app can be a different Angular version, or not Angular at all. Nothing is shared in the page, so nothing collides.
• Independent deploys. Your app is loaded by URL at runtime. You deploy on your cadence; the shell picks up the new version without redeploying itself.
• A real security boundary. The shell cannot read your DOM and you cannot read the shell’s. Every message crosses an origin-checked channel, and every payload is structured-clone serializable — there are no shared object references to leak.

The handshake

connect (or bootstrap, which wraps it) runs inside your iframe and performs a fixed handshake:

1. It reads the shell’s origin and your app id from the query params the shell stamped on your entry URL.
2. It postMessages a hello to the shell, carrying your contract.
3. The shell replies with a welcome: a channel id, the session, the active theme, and the initial route.
4. connect resolves to a Platform — and applies the theme’s design tokens to your iframe before it resolves, so your first paint is already themed.

Both sides validate the other’s origin on every message, so nothing but the shell can drive your app.

The readiness barrier

The shell queues traffic to your app until you call platform.ready(). That is deliberate: it gives you a window to register intent handlers and event subscriptions before anything is delivered, so you never miss an early message. Wire your handlers, then call ready() once. Forgetting it is the most common reason an app appears to connect but never receives anything.