From 2291b0ba4f1ae60ffad8ccd118e5fb7b3602f4e3 Mon Sep 17 00:00:00 2001
From: Chris Harrelson <3453258+chrishtr@users.noreply.github.com>
Date: Mon, 19 May 2025 15:11:11 -0700
Subject: [PATCH] Create responsive-iframes-explainer.md

---
 css-sizing-4/responsive-iframes-explainer.md | 51 ++++++++++++++++++++
 1 file changed, 51 insertions(+)
 create mode 100644 css-sizing-4/responsive-iframes-explainer.md

diff --git a/css-sizing-4/responsive-iframes-explainer.md b/css-sizing-4/responsive-iframes-explainer.md
new file mode 100644
index 000000000000..12f9f298ee10
--- /dev/null
+++ b/css-sizing-4/responsive-iframes-explainer.md
@@ -0,0 +1,51 @@
+# Responsive iframes
+
+## Problem description
+
+[Iframes]([url](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/iframe)) are very useful for sandboxing web content into different documents. The options currently available are:
+ 1. A [same-origin]([url](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy)) iframe, which provides full style & 
+layout isolation, and by-default script isolation. This prevents the parent and child documents from accidentally interfering with each other.
+ 2. A cross-origin iframe, which additionally provides robust security against untrusted embedders or embedees.
+
+In addition, iframes participate in the layout of the parent document, via the style and layout of their owning `<iframe>` element.
+However, unlike other HTML elements such as `<div>`, iframe elements do not have the ability to support *responsive layout*, i.e. size themselves automatically to contain the [natural dimensions]([url](https://drafts.csswg.org/css-images-3/#natural-dimensions)) of the contents of the iframe. Instead, browser automatically add scrollbars to ifrmaes as necessary, so that users can access the content.
+
+This is a problem:
+ * From a user's perspective, iframe scrollbars are a worse UX in cases where the iframe contents are important to them and can fit reasonably in the visible viewport without these additional scrollbars.
+ * From a developer's perspective, they are forced to use script to communicate natural dimensions, in order to help the user have better UX without scrollbars. 
+
+Embedded SVG documents already support responsive layout. *Responsive iframes* add responsive layout to iframes, as long as the embedding and embedded document both opt into do so. This allows supporting responsive layout without losing any of the advantages of iframes in (1) and (2) above.
+
+## Use cases
+
+Use cases include:
+ * 3P comment widgets ([example]([url](https://github.com/whatwg/html/issues/555#issuecomment-177836009)))
+ * Embedding self-contained worked examples in teaching UI ([example]([url](https://browser.engineering/layout.html))).
+
+In general, there is a lot of demand for this feature, as evidenced by:
+ * [Stack overflow]([url](https://stackoverflow.com/search?q=resize+iframe))
+ * Many comments and positive reactions on the [issue proposing the feature for HTML]([url](https://github.com/whatwg/html/issues/555)), and [the same for CSS]([url](https://github.com/w3c/csswg-drafts/issues/1771)).
+ * Existence of multiple polyfills
+
+## Solution
+
+
+The embedding document does so via the `contain-intrinsic-size: from-element` CSS property on the `<iframe>` element, and the embedded document via a new `<meta>` tag with name `responsive-embedded-sizing`.
+
+When both are set, then at the time the `load` event on the embedded document fires, the embedding document is notified with the new [natural height]([url](https://drafts.csswg.org/css-images-3/#natural-height)) of the embedded (iframe) document. This height is then taken into account in the final size of the `<iframe>` element, along with other constraints specified by the HTML and CSS of the embedding document. Subsequent changes to content, styling or layout fo the embedded document do not affect the `<iframe>` sizing.
+
+The double opt-in preserves:
+ * Backward compatibility for existing content.
+ * Privacy and security guarantees of cross-origin content.
+
+The "one-shot" sizing to natural dimensions avoids:
+ * Performance issues and CLS due to changing iframe sizing. (To further mitigatge performance risks, limitations on levels of `<iframe>` nesting may be imposed.)
+ * Potential infinite layout loops.
+
+## Future extensions
+
+A JavaScript API could be added in the future that would allow embedded documents to request relayout in their embedding document context.
+
+## Privacy and security
+
+Information about the contents of a cross-origin iframe can be exfiltrated by an embedding malicious document that observes the laid-out size of the iframe. This can be mitigated through use of the the `X-Frame-Options` HTTP header to allow embedding into only trusted embedding documents, plus the `responsive-embedded-sizing` `<meta>` tag to further opt into responsive layout. Additional restrictions could be put in place through contents of the `<meta>` tag that would restrict to only explicitly allowed origins.