BuilderIO/inline-embeds

Inline Embeds

The chat renderer lets you embed a sandboxed iframe pointing at any same-origin route of this app, rendered inline with your reply. Use this when a live, interactive preview communicates more than prose or a static screenshot — a chart, an email thread, a slide, a form, a ticket.

The embed fence

Emit a fenced code block with the language embed:

```embed
src: /email?id=msg_123
aspect: 4/3
title: Re: Q4 planning
```

Keys:

| Key | Required | Notes | | -------- | -------- | ------------------------------------------------------------------ | | src | yes | Same-origin path beginning with /. Cross-origin URLs are blocked | | aspect | no | 16/9 (default), 4/3, 3/2, 2/1, 21/9, 1/1 | | title | no | Accessible label + hover tooltip | | height | no | Fixed pixel height when aspect ratio doesn't fit |

The rendered iframe is sandboxed (allow-scripts allow-same-origin allow-forms allow-popups) and referrerpolicy="same-origin". The browser enforces that the iframe can't navigate the parent window.

When to reach for an embed

• A chart or visualization that benefits from tooltips / hover.
• A detail view the user might want to scan (email, ticket, event, slide).
• Anything where "here's a link to it" would force an extra click.

Don't embed when plain prose, a bulleted list, or a small table is enough. Don't embed external sites — the renderer blocks cross-origin URLs.

"Open in main window" button — postNavigate

Every embed route should include a small "Open" button so the user can pop the view out of the chat and into the full app. Import the helper from @agent-native/core/client:

import { postNavigate, isInAgentEmbed } from "@agent-native/core/client";

export function OpenButton({ path }: { path: string }) {
  if (!isInAgentEmbed()) return null;
  return (
    <button onClick={() => postNavigate(path)}>Open</button>
  );
}

postNavigate sends a postMessage to the parent chat window. The chat renderer validates the message is same-origin, same-iframe, and the path is relative, then updates the parent URL via history.pushState so react-router navigates without a page reload.

When the page is loaded directly (not in an iframe), postNavigate falls back to a same-window navigation, so the button works both ways.

Adding an embed route to a template

1. Create a chromeless route (e.g. app/routes/email.tsx) that renders the detail view without the app shell.
2. Mark the route path as bare in app/components/layout/Layout.tsx so the sidebar / header don't render inside the iframe.
3. Render the existing detail component with a transparent background so it blends into the chat theme.
4. Include an <OpenButton> that calls postNavigate("/path/to/detail").
5. Document the embed URL in this template's AGENTS.md so the agent knows what's embeddable.

The framework-level fence renderer and security enforcement apply automatically — no per-template wiring beyond the route and layout bypass.