resize-iframe 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # 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
+
+- f2e12a7: Give the framed page a way to receive what the parent sends.
+
+  `parentIframe.onMessage = (message) => …` delivers whatever the embedder posted with `sendMessage`. Until now the channel was send-only: the parent could post into the frame, but the child script never listened, so every embedded page had to hand-roll a `message` listener and work out for itself which messages came from the embedder.
+
+  Both directions now travel in the same `resize-iframe-message` envelope, and the child checks `event.source === parent` the same way the parent checks the frame's own window. Unrelated postMessage traffic aimed at your frame no longer reaches the callback.
+
+  **Breaking for hand-rolled child listeners.** A child page reading `event.data` directly now sees `{ 'resize-iframe-message': … }` rather than the bare payload. Use `parentIframe.onMessage` instead.
+
+### Patch Changes
+
+- f2e12a7: Document the third-party embedding flow and cover the library with a Playwright suite.
+
+  - README: Storage Access API setup for cross-site embeds, including the `allow="storage-access"` and `allow-storage-access-by-user-activation` requirements, and why the request has to come from a click inside the frame.
+  - README: note that `sendMessage` is dropped if the frame is still on `about:blank`, so send it after `ready`.
+  - 33 specs across Chromium, Firefox and WebKit, served from two origins so they run against real cross-site restrictions rather than same-document shortcuts.
+
 ## 0.1.1
 
 ### Patch 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                           |
 
@@ -181,9 +215,15 @@ frame.sendMessage({ hello: 'world' }, 'https://anotherdomain.com');
 frame.disconnect(); // call before removing the iframe from the page
 ```
 
+Both directions travel in the same envelope, so `parentIframe.onMessage` only ever
+sees what the embedder sent — not the postMessage traffic every other script on the
+page also aims at your frame. A plain `addEventListener('message', …)` in the child
+would have to sort that out itself.
+
 Child, on `window.parentIframe`:
 
 ```javascript
+parentIframe.onMessage = (message) => { … }; // ← parent's sendMessage
 parentIframe.sendMessage('ping'); // → parent's onMessage / 'frame-message' event
 parentIframe.autoResize(false); // pause resizing; returns the current state
 parentIframe.resize(); // nudge, for a change neither observer sees
@@ -227,21 +267,11 @@ pnpm exec playwright install
 pnpm test
 ```
 
-33 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.
 
-## Testing
-
-```bash
-pnpm install
-pnpm exec playwright install
-pnpm test
-```
-
-21 Playwright specs, run across Chromium, Firefox and WebKit.
-
 ## Browser Support
 
 - Chrome/Edge 80+

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.1.1",
+  "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
@@ -12,13 +14,14 @@ const start = () => {
   let last = { height: 0, width: 0 };
   let queued = false;
   let auto = true;
+  let inbound = null;
 
   // Measure the bottom and right edges of the marked elements, or of body's
   // 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;
@@ -64,6 +67,18 @@ const start = () => {
   });
   addEventListener('load', schedule); // images and fonts landing late
 
+  // Messages from the embedder. event.source is set by the browser and cannot be
+  // forged, so this is the same guard the parent uses in the other direction, and
+  // the envelope keeps unrelated postMessage traffic (analytics, wallets, other
+  // embeds) out of the callback.
+  addEventListener('message', (event) => {
+    if (event.source !== parent) return;
+    const data = event.data;
+    if (data && typeof data === 'object' && 'resize-iframe-message' in data) {
+      inbound?.(data['resize-iframe-message']);
+    }
+  });
+
   // Third-party cookies: an embedded page gets partitioned storage until the user
   // grants access. Probe the API rather than sniffing the browser — Safari and
   // Chrome both partition, and which browsers do is not a stable list.
@@ -77,6 +92,13 @@ const start = () => {
   };
 
   window.parentIframe = {
+    // Assign a function to receive what the parent sends with sendMessage().
+    get onMessage() {
+      return inbound;
+    },
+    set onMessage(fn) {
+      inbound = fn;
+    },
     autoResize(state) {
       if (state !== undefined) auto = state;
       if (auto) schedule();

package/resize-iframe.d.ts

@@ -32,6 +32,8 @@ export function iframeResize(
 
 /** Available inside the framed page once resize-iframe-child.js has loaded. */
 export interface ParentIframe {
+  /** Called with whatever the parent sends via `sendMessage`. Assign to subscribe. */
+  onMessage: ((message: unknown) => void) | null;
   autoResize(state?: boolean): boolean;
   resize(): void;
   sendMessage(message: unknown, targetOrigin?: string): void;
@@ -43,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

@@ -88,8 +88,10 @@ function connect(iframe, settings) {
       clearTimeout(warning);
       delete iframe.iframeResizer;
     },
+    // Same envelope the child sends back in, so the framed page can tell an
+    // embedder message from every other script posting at it.
     sendMessage(message, targetOrigin = '*') {
-      iframe.contentWindow?.postMessage(message, targetOrigin);
+      iframe.contentWindow?.postMessage({ 'resize-iframe-message': message }, targetOrigin);
     },
   };
   return iframe.iframeResizer;
@@ -97,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() {
@@ -115,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
     );
@@ -130,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;
@@ -137,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() {