feat(editor): Iframe embed component for remote URLs

Adds a new atomic component `Iframe` (slash menu icon 🔗) that embeds an
arbitrary remote URL via `<iframe src=...>` instead of inlining HTML
from the embed store. Use case: integrating widget Spaces (e.g. carbon-
tokenization-widgets) without having to download and adapt their HTML
to the strict create-html-embed conventions.

- Shared component def (atomic, fields: src, title, desc, height, wide)
- Custom NodeView with live iframe preview, Settings + Reload buttons,
auto-resize when the remote page emits postMessage({type:"embedResize"})
- Publisher transformer emits <figure class="html-embed"> reusing the
existing iframe/figcaption markup so styling and figure numbering
carry over for free
- llms.txt renderer surfaces the URL as a Markdown link
- 3 publisher tests covering happy path, empty-src drop, and wide flag

Co-authored-by: Cursor <cursoragent@cursor.com>

backend/src/publisher/markdown-renderer.ts

@@ -279,6 +279,16 @@ function renderBlock(node: JSONNode, ctx: RenderCtx): string {
       return `*[Interactive visualization: ${label}]*`;
     }
 
+    case "iframe": {
+      const src = String(node.attrs?.src || "").trim();
+      const title = String(node.attrs?.title || "").trim();
+      const desc = String(node.attrs?.desc || "").trim();
+      if (!src) return "";
+      const label = title || desc || src;
+      // Surface the URL so LLM agents and crawlers can follow it.
+      return `*[Embedded page: [${label}](${src})]*`;
+    }
+
     case "hfUser": {
       const username = String(node.attrs?.username || "").trim();
       if (!username) return "";

backend/src/publisher/transformers/iframe-embed.ts

@@ -0,0 +1,92 @@
+import type { Transformer } from "./types.js";
+
+/**
+ * Transforms `<div data-component="iframe" src="..." title="..." desc="..." height="..." wide="true">`
+ * into:
+ *   <figure class="html-embed" data-iframe-src="...">
+ *     <div class="html-embed-container">
+ *       <iframe src="..." title="..." ... />
+ *     </div>
+ *     <figcaption class="html-embed__desc">...</figcaption>
+ *   </figure>
+ *
+ * Reuses the same outer markup as `html-embed.ts` so the existing publisher
+ * CSS (`figure.html-embed`, `.html-embed-container`, `.html-embed__desc`)
+ * styles the figure, numbers it, and lays it out responsively.
+ *
+ * Differences with htmlEmbed:
+ *   - `src=` is a remote URL, not a Y.Map key, so we never inline `srcdoc`.
+ *   - No sandbox attribute: arbitrary third-party pages often need cookies,
+ *     popups, or storage. Authors who need to lock things down can use
+ *     RawHtml with a hand-rolled iframe.
+ *   - `wide` toggles the `html-embed--wide` modifier (full-bleed layout).
+ */
+const DEFAULT_IFRAME_HEIGHT = 600;
+const SAFETY_MIN_HEIGHT = 80;
+
+export const iframeEmbedTransformer: Transformer = {
+  name: "iframe",
+  apply(document) {
+    for (const div of [...document.querySelectorAll('div[data-component="iframe"]')]) {
+      const src = (div.getAttribute("src") || div.getAttribute("data-src") || "").trim();
+      const title = div.getAttribute("title") || div.getAttribute("data-title") || "";
+      const desc = div.getAttribute("desc") || div.getAttribute("data-desc") || "";
+      const rawHeight = div.getAttribute("height") || div.getAttribute("data-height");
+      const wide =
+        div.getAttribute("wide") === "true" ||
+        div.getAttribute("data-wide") === "true";
+
+      const initialHeight = Math.max(
+        parseInt(rawHeight || "", 10) || DEFAULT_IFRAME_HEIGHT,
+        SAFETY_MIN_HEIGHT,
+      );
+
+      // Drop iframes without a src - publishing a broken empty frame is worse
+      // than silently omitting the placeholder.
+      if (!src) {
+        div.remove();
+        continue;
+      }
+
+      const figure = document.createElement("figure");
+      figure.className = wide ? "html-embed html-embed--wide" : "html-embed";
+      figure.setAttribute("data-iframe-src", src);
+
+      const container = document.createElement("div");
+      container.className = "html-embed-container";
+
+      const iframe = document.createElement("iframe");
+      iframe.setAttribute("src", src);
+      iframe.setAttribute(
+        "style",
+        `width:100%;border:none;display:block;height:${initialHeight}px;min-height:${SAFETY_MIN_HEIGHT}px;background:transparent;`,
+      );
+      iframe.setAttribute("loading", "lazy");
+      iframe.setAttribute("referrerpolicy", "no-referrer-when-downgrade");
+      iframe.setAttribute(
+        "allow",
+        "accelerometer; autoplay; clipboard-write; encrypted-media; fullscreen; gyroscope; picture-in-picture",
+      );
+      if (title) iframe.setAttribute("title", title);
+
+      container.appendChild(iframe);
+      figure.appendChild(container);
+
+      if (title || desc) {
+        const caption = document.createElement("figcaption");
+        caption.className = "html-embed__desc";
+        if (title && desc) {
+          const strong = document.createElement("strong");
+          strong.textContent = title;
+          caption.appendChild(strong);
+          caption.appendChild(document.createTextNode(" " + desc));
+        } else {
+          caption.textContent = title || desc;
+        }
+        figure.appendChild(caption);
+      }
+
+      div.replaceWith(figure);
+    }
+  },
+};

backend/src/publisher/transformers/index.ts

@@ -14,9 +14,11 @@
  *                      the mermaid source.
  *  5. HighlightCode  — runs Shiki over every remaining `<pre><code>`.
  *  6. HtmlEmbed      — independent; converts placeholder divs into iframes.
- *  7. HfUser         — independent; converts atomic placeholder divs into
+ *  7. IframeEmbed    — independent; converts placeholder divs pointing at a
+ *                      remote URL into a standard `<figure><iframe src=...>`.
+ *  8. HfUser         — independent; converts atomic placeholder divs into
  *                      Hugging Face user profile cards.
- *  8. Footnote       — runs last so collected texts include those inside every
+ *  9. Footnote       — runs last so collected texts include those inside every
  *                      other transformed block (tables, callouts, accordions...).
  */
 import type { Transformer } from "./types.js";
@@ -26,6 +28,7 @@ import { bibliographyTransformer } from "./bibliography.js";
 import { mermaidTransformer } from "./mermaid.js";
 import { highlightCodeTransformer } from "./highlight-code.js";
 import { htmlEmbedTransformer } from "./html-embed.js";
+import { iframeEmbedTransformer } from "./iframe-embed.js";
 import { hfUserTransformer } from "./hf-user.js";
 import { footnoteTransformer } from "./footnote.js";
 
@@ -36,6 +39,7 @@ export const transformers: Transformer[] = [
   mermaidTransformer,
   highlightCodeTransformer,
   htmlEmbedTransformer,
+  iframeEmbedTransformer,
   hfUserTransformer,
   footnoteTransformer,
 ];

backend/src/shared/component-defs.ts

@@ -78,6 +78,17 @@ export const SHARED_COMPONENT_DEFS: SharedComponentDef[] = [
       { name: "url", type: "string", default: "" },
     ],
   },
+  {
+    name: "iframe",
+    kind: "atomic",
+    fields: [
+      { name: "src", type: "string", default: "" },
+      { name: "title", type: "string", default: "" },
+      { name: "desc", type: "string", default: "" },
+      { name: "height", type: "string", default: "600" },
+      { name: "wide", type: "boolean", default: false },
+    ],
+  },
   {
     name: "rawHtml",
     kind: "atomic",

backend/tests/publisher.test.ts

@@ -171,6 +171,62 @@ describe("1.3 Post-processing", () => {
     expect(html).toContain("chart.html");
   });
 
+  it("1.3.2b transforms iframe component to figure + iframe with src", async () => {
+    const docJson = {
+      type: "doc",
+      content: [
+        {
+          type: "iframe",
+          attrs: {
+            src: "https://my-space.hf.space/",
+            title: "Tokenization demo",
+            desc: "Interactive widget",
+            height: "500",
+            wide: false,
+          },
+        },
+      ],
+    };
+    const html = await renderArticleHTML(docJson, simpleMeta, EMPTY_CSS);
+    expect(html).toMatch(/<figure[^>]*\bclass="html-embed"/);
+    expect(html).toContain('data-iframe-src="https://my-space.hf.space/"');
+    expect(html).toContain('src="https://my-space.hf.space/"');
+    expect(html).toContain('height:500px');
+    expect(html).toContain('title="Tokenization demo"');
+    expect(html).toContain("Interactive widget");
+    // Placeholder div must be gone
+    expect(html).not.toContain('data-component="iframe"');
+  });
+
+  it("1.3.2c drops iframe component without src", async () => {
+    const docJson = {
+      type: "doc",
+      content: [
+        {
+          type: "iframe",
+          attrs: { src: "", title: "Empty", desc: "", height: "600", wide: false },
+        },
+      ],
+    };
+    const html = await renderArticleHTML(docJson, simpleMeta, EMPTY_CSS);
+    expect(html).not.toContain('data-component="iframe"');
+    expect(html).not.toContain('<iframe');
+  });
+
+  it("1.3.2d iframe with wide flag gets the wide modifier class", async () => {
+    const docJson = {
+      type: "doc",
+      content: [
+        {
+          type: "iframe",
+          attrs: { src: "https://example.com", title: "", desc: "", height: "600", wide: true },
+        },
+      ],
+    };
+    const html = await renderArticleHTML(docJson, simpleMeta, EMPTY_CSS);
+    expect(html).toMatch(/<figure[^>]*\bclass="html-embed html-embed--wide"/);
+  });
+
   it("1.3.3 transforms mermaid to pre block", async () => {
     const docJson = {
       type: "doc",

frontend/src/editor/components/factory.ts

@@ -14,6 +14,7 @@ import { makeAtomicView } from "./AtomicView";
 import { MermaidNodeView } from "./MermaidView";
 import { HfUserNodeView } from "./HfUserView";
 import { makeHtmlEmbedView } from "../embeds/HtmlEmbedView";
+import { makeIframeEmbedView } from "../embeds/IframeEmbedView";
 
 function buildAttrSchema(fields: ComponentDef["fields"]) {
   const attrs: Record<string, { default: unknown }> = {};
@@ -81,6 +82,7 @@ export function createComponentExtension(def: ComponentDef) {
       if (def.name === "mermaid") View = MermaidNodeView;
       else if (def.name === "hfUser") View = HfUserNodeView;
       else if (def.name === "htmlEmbed") View = makeHtmlEmbedView(def);
+      else if (def.name === "iframe") View = makeIframeEmbedView(def);
       else View = makeAtomicView(def);
       return ReactNodeViewRenderer(View);
     },

frontend/src/editor/components/registry.ts

@@ -85,6 +85,16 @@ const UI_META: Record<string, UIMeta> = {
     tag: "HfUser", icon: "👤", label: "HF User card", description: "Hugging Face user profile card",
     fieldMeta: { username: { label: "Username", placeholder: "username" }, name: { label: "Display name", placeholder: "Full Name" }, url: { label: "URL", placeholder: "https://huggingface.co/username" } },
   },
+  iframe: {
+    tag: "Iframe", icon: "🔗", label: "Iframe", description: "Embed a remote URL (Space, widget, demo…)",
+    fieldMeta: {
+      src: { label: "URL", placeholder: "https://my-space.hf.space/" },
+      title: { label: "Title", placeholder: "Embed title…" },
+      desc: { label: "Description", placeholder: "Caption shown below…" },
+      height: { label: "Height (px)", placeholder: "600" },
+      wide: { label: "Wide" },
+    },
+  },
   rawHtml: {
     tag: "RawHtml", icon: "</>", label: "Raw HTML", description: "Inject raw HTML content",
     fieldMeta: { html: { label: "HTML", placeholder: "<div>…</div>" } },

frontend/src/editor/embeds/IframeEmbedView.tsx

@@ -0,0 +1,207 @@
+import { useState, useEffect, useRef, useCallback, useMemo } from "react";
+import { NodeViewWrapper } from "@tiptap/react";
+import type { NodeViewProps } from "@tiptap/react";
+import type { ComponentDef, ComponentField } from "../components/registry";
+
+const DEFAULT_IFRAME_HEIGHT = 600;
+const SAFETY_MIN_HEIGHT = 80;
+
+function FieldRow({
+  field,
+  value,
+  onChange,
+}: {
+  field: ComponentField;
+  value: unknown;
+  onChange: (val: unknown) => void;
+}) {
+  if (field.type === "boolean") {
+    return (
+      <label className="embed-field-row embed-field-checkbox">
+        <input
+          type="checkbox"
+          checked={!!value}
+          onChange={(e) => onChange(e.target.checked)}
+        />
+        {field.label}
+      </label>
+    );
+  }
+  return (
+    <div className="embed-field-row">
+      <span className="embed-field-label">{field.label}</span>
+      <input
+        type="text"
+        value={String(value ?? "")}
+        placeholder={field.placeholder || field.label}
+        onChange={(e) => onChange(e.target.value)}
+        className="embed-field-input"
+      />
+    </div>
+  );
+}
+
+function parseStoredHeight(raw: unknown): number {
+  if (typeof raw === "number" && raw > 0) return Math.round(raw);
+  const n = parseInt(String(raw ?? ""), 10);
+  return Number.isFinite(n) && n > 0 ? n : DEFAULT_IFRAME_HEIGHT;
+}
+
+/**
+ * NodeView for `<div data-component="iframe">`.
+ *
+ * Renders a live preview of the remote URL inside an `<iframe src="...">`.
+ * Auto-resizes when the embedded page sends `postMessage({ type: "embedResize", height })`
+ * (same protocol as `HtmlEmbedView` so our own widgets work out of the box),
+ * otherwise falls back to the manual `height` attribute.
+ *
+ * No content is stored in `Y.Map("embeds")` because the HTML lives at the
+ * remote URL; only node attributes (src, title, desc, height, wide) travel
+ * through the document.
+ */
+export function makeIframeEmbedView(def: ComponentDef) {
+  function IframeEmbedNodeView({ node, updateAttributes }: NodeViewProps) {
+    const src = String(node.attrs.src || "").trim();
+    const title = String(node.attrs.title || "");
+    const storedHeight = parseStoredHeight(node.attrs.height);
+
+    const [iframeHeight, setIframeHeight] = useState(storedHeight);
+    const [showSettings, setShowSettings] = useState(!src);
+    const [reloadToken, setReloadToken] = useState(0);
+    const iframeRef = useRef<HTMLIFrameElement>(null);
+
+    // Keep iframe height in sync with the stored attribute when it changes
+    // from elsewhere (undo/redo, settings panel edit).
+    useEffect(() => {
+      setIframeHeight(storedHeight);
+    }, [storedHeight]);
+
+    // Listen for height reports from same-origin/cooperating iframes.
+    const lastPersistedRef = useRef<number>(storedHeight);
+    const persistTimerRef = useRef(0);
+    useEffect(() => {
+      const handler = (e: MessageEvent) => {
+        if (e.data?.type !== "embedResize") return;
+        const frame = iframeRef.current;
+        if (!frame || e.source !== frame.contentWindow) return;
+        const h = Math.max(0, Math.ceil(e.data.height));
+        if (!h) return;
+        setIframeHeight((prev) => (prev === h ? prev : h));
+        if (h !== lastPersistedRef.current) {
+          clearTimeout(persistTimerRef.current);
+          persistTimerRef.current = window.setTimeout(() => {
+            if (h !== lastPersistedRef.current) {
+              lastPersistedRef.current = h;
+              updateAttributes({ height: String(h) });
+            }
+          }, 800);
+        }
+      };
+      window.addEventListener("message", handler);
+      return () => {
+        window.removeEventListener("message", handler);
+        clearTimeout(persistTimerRef.current);
+      };
+    }, [updateAttributes]);
+
+    const handleFieldChange = useCallback(
+      (fieldName: string, value: unknown) => {
+        updateAttributes({ [fieldName]: value });
+      },
+      [updateAttributes],
+    );
+
+    const reload = useCallback(() => setReloadToken((n) => n + 1), []);
+
+    // `key` on the iframe forces a remount when src changes or on reload,
+    // which works around cross-origin pages that don't expose the History API.
+    const iframeKey = useMemo(() => `${src}#${reloadToken}`, [src, reloadToken]);
+
+    const hasSrc = !!src;
+
+    return (
+      <NodeViewWrapper data-component="iframe">
+        <div contentEditable={false} className="embed-view">
+          {/* Header */}
+          <div className="embed-header">
+            <div className="embed-header-left">
+              <span className="embed-header-icon">{def.icon}</span>
+              <span className="embed-header-label">
+                {title || src || "Iframe"}
+              </span>
+              {src && title && (
+                <span className="embed-header-src">{src}</span>
+              )}
+            </div>
+            <div className="embed-header-actions">
+              {hasSrc && (
+                <button
+                  className="embed-btn"
+                  onClick={reload}
+                  title="Reload iframe"
+                  aria-label="Reload iframe"
+                >
+                  Reload
+                </button>
+              )}
+              <button
+                className="embed-btn"
+                onClick={() => setShowSettings(!showSettings)}
+                title="Settings"
+              >
+                {showSettings ? "Close" : "Settings"}
+              </button>
+            </div>
+          </div>
+
+          {/* Settings panel */}
+          {showSettings && (
+            <div className="embed-settings">
+              {def.fields.map((f) => (
+                <FieldRow
+                  key={f.name}
+                  field={f}
+                  value={node.attrs[f.name]}
+                  onChange={(v) => handleFieldChange(f.name, v)}
+                />
+              ))}
+            </div>
+          )}
+
+          {/* Preview */}
+          {hasSrc ? (
+            <div className="embed-preview">
+              <iframe
+                key={iframeKey}
+                ref={iframeRef}
+                src={src}
+                title={title || src}
+                className="embed-iframe"
+                referrerPolicy="no-referrer-when-downgrade"
+                allow="accelerometer; autoplay; clipboard-write; encrypted-media; fullscreen; gyroscope; picture-in-picture"
+                style={{
+                  height: iframeHeight,
+                  minHeight: Math.min(storedHeight, SAFETY_MIN_HEIGHT),
+                }}
+              />
+            </div>
+          ) : (
+            <div className="embed-empty">
+              <span className="embed-empty-icon">{def.icon}</span>
+              <span>Enter a URL in settings to embed a page</span>
+              <button
+                className="embed-btn embed-btn-primary"
+                onClick={() => setShowSettings(true)}
+              >
+                Open Settings
+              </button>
+            </div>
+          )}
+        </div>
+      </NodeViewWrapper>
+    );
+  }
+
+  IframeEmbedNodeView.displayName = "IframeEmbedView";
+  return IframeEmbedNodeView;
+}