IframeEmbed
A security-vetted iframe wrapper for static demos and live tools. HTTPS-only, optional host allowlist, typed sandbox / allow / referrerpolicy.
What it is
<IframeEmbed> is a small Astro component shipped by @portfolio-engine/editorial-theme for putting static interactive demos directly inside writing posts or pages. It enforces several rules at render time so a misconfigured embed fails the build instead of silently loading something unsafe.
Validation rules
srcmust either be a same-origin path starting with/, or an absolutehttps://URL.http://,javascript:,data:, and protocol-relative//hostare all rejected.- Backslashes in same-origin paths are rejected (WHATWG URL parsers normalize
\to/and can redirect cross-origin). - Control characters in the
srcare rejected. - If
allowedHostsis provided, absolute URLs must match the hostname (case-insensitive, port intentionally ignored). heightandaspectRatioaccept only narrow CSS forms — no semicolons, no whitespace, no escape sequences.
How to use it
---
import IframeEmbed from '@portfolio-engine/editorial-theme/components/IframeEmbed.astro';
import { getBase, resolveAssetUrl } from '@portfolio-engine/editorial-theme';
// resolveAssetUrl prefixes the site's Astro `base` (BASE_URL) onto same-origin
// paths, so deployments under e.g. `/portfolio/` still resolve correctly.
const base = getBase();
const demoSrc =
resolveAssetUrl('/assets/demos/architecture/', base) ??
'/assets/demos/architecture/';
---
<IframeEmbed
src={demoSrc}
title="Four-layer architecture diagram"
height={520}
loading="lazy"
sandbox="allow-scripts"
caption="Click any layer to highlight its dependencies."
/>
A note on sandbox: the iframe sandbox is restrictive by default. allow-scripts enables JS inside the embedded document (needed for the interactive diagram). Leave allow-same-origin off for same-origin demos — adding it back alongside allow-scripts effectively defeats the sandbox, since the embedded page can then reach into the parent’s storage and DOM. For a fully passive embed (e.g. a static SVG diagram with no JS), you can omit sandbox entirely.
For Markdown posts that can’t import a helper, write the path relative to the rendered page (e.g. src="../../assets/demos/architecture/" from /writing/<slug>/) — this is a recommended convention to stay same-origin and BASE_URL-portable, but it’s not enforced: a raw <iframe> in Markdown bypasses the theme component entirely, so none of the build-time validation listed above runs on it. Anything Markdown can express, the browser will render. Prefer the <IframeEmbed> component (via MDX) whenever you need the validation guarantees; reserve raw iframes for embeds whose src you have full control over.
This site embeds the self-contained interactive diagram on the architecture page and inside the four-layer architecture writing post.