resize-iframe 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # resize-iframe
 
+## 0.3.0
+
+### Minor Changes
+
+- e0996b5: `srcdoc` support, for inline HTML the host owns.
+
+  `withResizeChild(html)` from `resize-iframe/inject` inlines the child script into
+  HTML you generate — report embeds, quizzes, model output — so the document you hand
+  to `srcdoc` stays self-contained: no CDN, no relative path back to the package. It
+  is idempotent, and wraps a fragment in a minimal document with a measurable box, so
+  anything from a bare string of text upwards sizes correctly. `childScriptTag()` and
+  `childScriptSource` are exported too, for hosts that place the script themselves.
+
+  The `<resize-iframe>` element now accepts `srcdoc` alongside `src`, applies
+  `sandbox` and `allow` before either so the first load carries them, and takes a
+  `warning-timeout` attribute (`0` silences the missing-child warning).
+
 ## 0.2.0
 
 ### Minor Changes

package/README.md

@@ -7,8 +7,11 @@ each page, no build step, no dependencies, MIT.
 - ↔️ Vertical, horizontal, or both
 - 🔒 Messages matched against the frame's own window, which cannot be forged
 - 🍪 Storage Access API support for third-party embeds
-- 🧩 Use `iframeResize()` or the `<resize-iframe>` element
-- 📦 ~5KB unminified, across both files
+- 🧩 Use `iframeResize()`, `<resize-iframe>`, or `withResizeChild` for srcdoc
+- 📦 ~6KB unminified, across the files you ship
+
+**[Live demo →](https://jagreehal.github.io/resize-iframe/)** — sandboxed, opaque-origin frames
+resizing, messaging, and refusing to be read from the parent.
 
 ## Installation
 
@@ -66,6 +69,35 @@ That alone auto-resizes the frame. A cross-origin parent cannot measure your
 content, so without this script nothing happens — the parent logs a warning after
 five seconds saying exactly that.
 
+### Inline HTML (`srcdoc`) the host owns
+
+When you build the framed HTML yourself — a report embed, a quiz, skill output —
+put the child script inside it with `withResizeChild` and pass the result as
+`srcdoc`. No CDN, no relative path, the document stays self-contained:
+
+```html
+<script type="module">
+  import 'resize-iframe';
+  import { withResizeChild } from 'resize-iframe/inject';
+
+  const frame = document.createElement('resize-iframe');
+  frame.setAttribute('sandbox', 'allow-scripts'); // opaque origin; keep it
+  frame.setAttribute('min-h', '200px');
+  frame.setAttribute('srcdoc', withResizeChild(generatedHtml));
+  document.body.append(frame);
+</script>
+```
+
+`withResizeChild` is idempotent, inserts the script before `</body>`, and wraps
+fragments in a minimal document — margin zeroed, content in a box — so even a bare
+string of text has something measurable around it. The same module exports
+`childScriptTag()` and `childScriptSource` if you would rather place the script
+yourself. Remote `src` pages are unchanged: only that page's author can include the
+child script.
+
+Working with an AI agent? `.claude/skills/resize-iframe/` teaches it which of these
+shapes to reach for.
+
 The script tag takes two optional attributes:
 
 | Attribute            | Default              | Description                                          |
@@ -162,11 +194,13 @@ turned off for.
 | Attribute     | Default            | Description                              |
 | ------------- | ------------------ | ---------------------------------------- |
 | `src`         | —                  | URL to embed                             |
+| `srcdoc`      | —                  | Inline HTML (prefer `withResizeChild`)   |
 | `title`       | `Embedded content` | Accessible name for the iframe           |
 | `direction`   | `vertical`         | As above                                 |
 | `offset-size` | `0`                | As above                                 |
 | `min-h`       | —                  | Minimum height constraint                |
 | `max-h`       | —                  | Maximum height constraint                |
+| `warning-timeout` | `5000`         | Ms before missing-child warning; `0` off |
 | `allow`       | —                  | Passed through, e.g. `storage-access`    |
 | `sandbox`     | —                  | Passed through                           |
 
@@ -233,7 +267,7 @@ pnpm exec playwright install
 pnpm test
 ```
 
-34 Playwright specs across Chromium, Firefox and WebKit. The suite serves the
+42 Playwright specs across Chromium, Firefox and WebKit. The suite serves the
 parent page and the child pages from two different origins — `localhost` and
 `127.0.0.1`, which are cross-*site*, not merely cross-origin — so every test runs
 against the same partitioning and `contentDocument` restrictions as production.

package/child-source.js

@@ -0,0 +1,2 @@
+// Generated by scripts/embed-child.mjs — do not edit.
+export const childScriptSource = "// Load this inside the framed page as a classic script, e.g.\n//   <script src=\".../resize-iframe-child.js\"><\\/script>\n// (Written with an escaped closer so the file can also be inlined into a\n// parent <script> without the HTML parser cutting the tag short.)\n// Optional attributes on that script tag:\n//   data-parent-origin=\"https://parent.example\"  report size only to that embedder\n//   data-size-selector=\".content\"                measure these elements instead\n// Or mark elements in the page with data-iframe-size to the same effect.\nconst config = document.currentScript?.dataset ?? {};\nconst targetOrigin = config.parentOrigin || '*';\nconst sizeSelector = config.sizeSelector || '[data-iframe-size]';\n\nconst start = () => {\n  let last = { height: 0, width: 0 };\n  let queued = false;\n  let auto = true;\n  let inbound = null;\n\n  // Measure the bottom and right edges of the marked elements, or of body's\n  // children. Never body itself: it stretches to fill the frame in quirks mode\n  // or under `body { height: 100% }`, which ratchets the frame larger and never\n  // lets it shrink back.\n  // Body's own bottom/right padding and margin fall outside the measurement —\n  // zero them if that gap matters, or mark a wrapper with data-iframe-size.\n  const measure = () => {\n    const marked = document.querySelectorAll(sizeSelector);\n    const elements = marked.length ? marked : document.body.children;\n    if (!elements.length) {\n      const body = document.body.getBoundingClientRect();\n      return { height: Math.ceil(body.bottom), width: Math.ceil(body.right) };\n    }\n    let height = 0;\n    let width = 0;\n    for (const element of elements) {\n      const box = element.getBoundingClientRect();\n      height = Math.max(height, box.bottom);\n      width = Math.max(width, box.right);\n    }\n    return { height: Math.ceil(height), width: Math.ceil(width) };\n  };\n\n  const post = () => {\n    queued = false;\n    const size = measure();\n    if (size.height === last.height && size.width === last.width) return;\n    last = size;\n    parent.postMessage({ 'resize-iframe': size }, targetOrigin);\n  };\n\n  // Batch to one measurement per frame: mutations arrive in bursts and every\n  // measure() forces a layout.\n  const schedule = () => {\n    if (queued || !auto) return;\n    queued = true;\n    requestAnimationFrame(post);\n  };\n\n  // ResizeObserver catches reflow (images, fonts, viewport). MutationObserver\n  // catches DOM and style changes, which the observer misses entirely whenever\n  // body is stretched to the frame and so never changes size itself.\n  new ResizeObserver(schedule).observe(document.body);\n  new MutationObserver(schedule).observe(document.body, {\n    subtree: true,\n    childList: true,\n    attributes: true,\n    characterData: true,\n  });\n  addEventListener('load', schedule); // images and fonts landing late\n\n  // Messages from the embedder. event.source is set by the browser and cannot be\n  // forged, so this is the same guard the parent uses in the other direction, and\n  // the envelope keeps unrelated postMessage traffic (analytics, wallets, other\n  // embeds) out of the callback.\n  addEventListener('message', (event) => {\n    if (event.source !== parent) return;\n    const data = event.data;\n    if (data && typeof data === 'object' && 'resize-iframe-message' in data) {\n      inbound?.(data['resize-iframe-message']);\n    }\n  });\n\n  // Third-party cookies: an embedded page gets partitioned storage until the user\n  // grants access. Probe the API rather than sniffing the browser — Safari and\n  // Chrome both partition, and which browsers do is not a stable list.\n  const hasStorageAccess = () =>\n    document.hasStorageAccess?.().catch(() => false) ?? Promise.resolve(true);\n\n  const reportStorageAccess = async () => {\n    const access = await hasStorageAccess();\n    parent.postMessage({ 'resize-iframe-storage': { hasAccess: access } }, targetOrigin);\n    return access;\n  };\n\n  window.parentIframe = {\n    // Assign a function to receive what the parent sends with sendMessage().\n    get onMessage() {\n      return inbound;\n    },\n    set onMessage(fn) {\n      inbound = fn;\n    },\n    autoResize(state) {\n      if (state !== undefined) auto = state;\n      if (auto) schedule();\n      return auto;\n    },\n    resize() {\n      post(); // nudge, for the rare change neither observer sees\n    },\n    sendMessage(message, origin = targetOrigin) {\n      parent.postMessage({ 'resize-iframe-message': message }, origin);\n    },\n    hasStorageAccess,\n    // MUST be called from a click or tap handler in this page: the browser denies\n    // the request without a user gesture here, and the parent cannot supply one.\n    // Reload afterwards if your page reads cookies during startup.\n    async requestStorageAccess() {\n      if (!document.requestStorageAccess) return true;\n      try {\n        await document.requestStorageAccess();\n      } catch {\n        // Denied, or the user has never visited this site first-party.\n      }\n      return reportStorageAccess();\n    },\n  };\n\n  reportStorageAccess();\n  post();\n};\n\nif (parent !== window) {\n  if (document.body) start();\n  else addEventListener('DOMContentLoaded', start);\n}\n";

package/inject.d.ts

@@ -0,0 +1,11 @@
+/** Source of resize-iframe-child.js, for hosts that want to inject it themselves. */
+export const childScriptSource: string;
+
+/** The inline `<script data-resize-iframe-child>…</script>` tag. */
+export function childScriptTag(): string;
+
+/**
+ * Returns HTML that includes the child script exactly once, ready for srcdoc.
+ * Fragments are wrapped in a minimal document with a measurable box to sit in.
+ */
+export function withResizeChild(html: string): string;

package/inject.js

@@ -0,0 +1,47 @@
+/**
+ * Prepare HTML so a parent using resize-iframe can size a srcdoc frame.
+ *
+ * A cross-origin (or opaque-origin sandboxed) parent cannot measure the framed
+ * page. The child script has to run inside it. For HTML the host owns — skill
+ * output, quizzes, inlined report fragments — call this before setting srcdoc
+ * and the script is inlined, so the report stays self-contained: no CDN, no
+ * relative path to the package.
+ *
+ * Remote `src` pages are not covered: only that page's author can include
+ * resize-iframe-child.js.
+ */
+import { childScriptSource } from "./child-source.js";
+
+export { childScriptSource };
+
+const MARKER = "data-resize-iframe-child";
+
+/** The inline script tag `withResizeChild` inserts. */
+export function childScriptTag() {
+  // A literal </script> anywhere in the source — even inside a JS comment —
+  // closes an HTML <script> element. Break the sequence for the parser; JS
+  // still sees <\/script> as </script>.
+  const safe = childScriptSource.replace(/<\/(script)/gi, "<\\/$1");
+  return `<script ${MARKER}>${safe}</script>`;
+}
+
+/**
+ * Returns HTML that includes the child script exactly once.
+ *
+ * - Full documents: script inserted before `</body>` (or `</html>`).
+ * - Fragments: wrapped in a minimal document so `document.body` exists for
+ *   the child (it waits on body before measuring).
+ * - Idempotent: HTML that already carries the marker is returned unchanged.
+ */
+export function withResizeChild(html) {
+  const source = typeof html === "string" ? html : String(html ?? "");
+  if (source.includes(MARKER)) return source;
+
+  const tag = childScriptTag();
+  if (/<\/body>/i.test(source)) return source.replace(/<\/body>/i, `${tag}</body>`);
+  if (/<\/html>/i.test(source)) return source.replace(/<\/html>/i, `${tag}</html>`);
+  // The child measures body's element children, so bare text needs a box around
+  // it, and the default body margin would land inside the measured top edge
+  // while its counterpart fell outside the bottom one.
+  return `<!doctype html><html><head><style>body{margin:0}</style></head><body><div>${source}</div>${tag}</body></html>`;
+}

package/package.json

@@ -1,15 +1,31 @@
 {
   "name": "resize-iframe",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Iframes that size themselves to their content, cross-origin included. No build step, no dependencies.",
   "type": "module",
   "main": "resize-iframe.js",
   "module": "resize-iframe.js",
   "types": "resize-iframe.d.ts",
+  "exports": {
+    ".": {
+      "types": "./resize-iframe.d.ts",
+      "import": "./resize-iframe.js",
+      "default": "./resize-iframe.js"
+    },
+    "./inject": {
+      "types": "./inject.d.ts",
+      "import": "./inject.js",
+      "default": "./inject.js"
+    },
+    "./resize-iframe-child.js": "./resize-iframe-child.js"
+  },
   "files": [
     "resize-iframe.js",
     "resize-iframe-child.js",
     "resize-iframe.d.ts",
+    "inject.js",
+    "inject.d.ts",
+    "child-source.js",
     "CHANGELOG.md"
   ],
   "publishConfig": {
@@ -41,9 +57,11 @@
     "typescript": "6.0.3"
   },
   "scripts": {
+    "embed-child": "node scripts/embed-child.mjs",
+    "pretest": "pnpm embed-child",
     "test": "playwright test",
     "test:ui": "playwright test --ui",
-    "typecheck": "tsc --noEmit --strict --lib es2022,dom resize-iframe.d.ts",
+    "typecheck": "tsc --noEmit --strict --lib es2022,dom resize-iframe.d.ts inject.d.ts",
     "changeset": "changeset",
     "version-packages": "changeset version",
     "release": "changeset publish"

package/resize-iframe-child.js

@@ -1,5 +1,7 @@
-// Load this inside the framed page:
-//   <script src=".../resize-iframe-child.js"></script>
+// Load this inside the framed page as a classic script, e.g.
+//   <script src=".../resize-iframe-child.js"><\/script>
+// (Written with an escaped closer so the file can also be inlined into a
+// parent <script> without the HTML parser cutting the tag short.)
 // Optional attributes on that script tag:
 //   data-parent-origin="https://parent.example"  report size only to that embedder
 //   data-size-selector=".content"                measure these elements instead
@@ -18,8 +20,8 @@ const start = () => {
   // children. Never body itself: it stretches to fill the frame in quirks mode
   // or under `body { height: 100% }`, which ratchets the frame larger and never
   // lets it shrink back.
-  // ponytail: body's own bottom/right padding and margin are ignored — zero them
-  // if that gap matters, or wrap your content and mark it with data-iframe-size.
+  // Body's own bottom/right padding and margin fall outside the measurement —
+  // zero them if that gap matters, or mark a wrapper with data-iframe-size.
   const measure = () => {
     const marked = document.querySelectorAll(sizeSelector);
     const elements = marked.length ? marked : document.body.children;

package/resize-iframe.d.ts

@@ -45,11 +45,15 @@ export interface ParentIframe {
 /** Attributes of the <resize-iframe> element. */
 export interface ResizeIframeAttributes {
   src?: string;
+  /** Inline HTML. Prefer `withResizeChild(html)` from `resize-iframe/inject` so the frame can report its size. */
+  srcdoc?: string;
   title?: string;
   direction?: 'vertical' | 'horizontal' | 'both' | 'none';
   'offset-size'?: number | string;
   'min-h'?: string;
   'max-h'?: string;
+  /** Ms to wait before warning that the child script is missing. `0` silences. */
+  'warning-timeout'?: number | string;
   allow?: string;
   sandbox?: string;
   /** Whatever else the host framework puts on an element: class, ref, key. */

package/resize-iframe.js

@@ -99,7 +99,9 @@ function connect(iframe, settings) {
 
 class ResizeIframe extends HTMLElement {
   static get observedAttributes() {
-    return ['src', 'min-h', 'max-h', 'allow', 'sandbox'];
+    // src / srcdoc last: setting either starts the navigation, and sandbox/allow
+    // have to be on the element before that or the first load runs without them.
+    return ['min-h', 'max-h', 'allow', 'sandbox', 'warning-timeout', 'srcdoc', 'src'];
   }
 
   connectedCallback() {
@@ -117,10 +119,14 @@ class ResizeIframe extends HTMLElement {
         this.attributeChangedCallback(name, null, this.getAttribute(name));
       }
     }
+    const warningTimeoutAttr = this.getAttribute('warning-timeout');
     iframeResize(
       {
         direction: this.getAttribute('direction') || DEFAULTS.direction,
         offsetSize: Number(this.getAttribute('offset-size')) || 0,
+        ...(warningTimeoutAttr !== null
+          ? { warningTimeout: Number(warningTimeoutAttr) }
+          : {}),
       },
       this.iframe
     );
@@ -132,6 +138,8 @@ class ResizeIframe extends HTMLElement {
 
   attributeChangedCallback(name, oldValue, newValue) {
     if (!this.iframe || newValue === null) return;
+    // srcdoc wins over src when both are set (HTML behaviour). Prefer one.
+    if (name === 'srcdoc') this.iframe.srcdoc = newValue;
     if (name === 'src') this.iframe.src = newValue;
     if (name === 'min-h') this.iframe.style.minHeight = newValue;
     if (name === 'max-h') this.iframe.style.maxHeight = newValue;
@@ -139,6 +147,7 @@ class ResizeIframe extends HTMLElement {
     // denied outright unless the frame carries allow="storage-access", and a
     // sandboxed frame also needs allow-storage-access-by-user-activation.
     if (name === 'allow' || name === 'sandbox') this.iframe.setAttribute(name, newValue);
+    // warning-timeout is read once, in connectedCallback.
   }
 
   get height() {