OpenParable
Skip to content
← Back to skills

Inline Embeds

Development
inline-embeds

Inline Embeds is an Agent Skill for development published in the BuilderIO/agent-native repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

How to render interactive previews of app screens inline in agent chat via sandboxed iframes. Covers the `embed` fence syntax, the `postNavigate` pop-out helper, and when to prefer an embed over prose / a static image.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/BuilderIO/agent-native/blob/HEAD/packages/core/src/templates/default/.agents/skills/inline-embeds/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/inline-embeds, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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:

KeyRequiredNotes
srcyesSame-origin path beginning with /. Cross-origin URLs are blocked
aspectno16/9 (default), 4/3, 3/2, 2/1, 21/9, 1/1
titlenoAccessible label + hover tooltip
heightnoFixed 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.