@proveanything/smartlinks 2.1.7 → 2.1.8

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.1.7  |  Generated: 2026-11-01T12:48:45.040Z
+Version: 2.1.8  |  Generated: 2026-11-02T13:05:01.425Z
 
 This is a concise summary of all available API functions and types.
 
@@ -7539,6 +7539,7 @@ interface IframeResponderOptions {
   ) => Promise<void>;
   onAuthLogout?: () => Promise<void>;
   onRouteChange?: (path: string, state: Record<string, string>) => void;
+  autoHeight?: boolean | { minHeight?: number };
   onResize?: (height: number) => void;
   onError?: (error: Error) => void;
   onReady?: () => void;

package/dist/docs/iframe-responder.md

@@ -35,10 +35,8 @@ const responder = new smartlinks.IframeResponder({
     smartlinks.setBearerToken(token);
     console.log('User logged in:', user);
   },
-  onResize: (height) => {
-    // Update iframe height
-    iframeElement.style.height = `${height}px`;
-  },
+  // An app in a page: the iframe is as tall as the app's content — the page scrolls, never the iframe.
+  autoHeight: { minHeight: 480 },
 });
 
 // Attach to iframe element
@@ -115,9 +113,24 @@ interface IframeResponderOptions {
   onResize?: (height: number) => void;
   onError?: (error: Error) => void;
   onReady?: () => void;
+
+  // Height
+  autoHeight?: boolean | { minHeight?: number }; // size the iframe to the app's content (an app in a page)
 }
 ```
 
+**Height: `autoHeight` or `onResize`.**
+
+- **`autoHeight`** — for an app placed in a page (a website, a section of a dashboard). The responder sets
+  the iframe's height from the height the app reports, adds the iframe's own border and padding (an
+  element with `box-sizing: border-box`, Tailwind's default, otherwise ends up short by its border — a
+  pointless scrollbar), and never uses the window-filling height. The iframe's own scrolling stays on as a
+  fallback for an app on an older SDK that under-reports its height. `minHeight`
+  is the least height it gives. `onResize` still hears each content height.
+- **`onResize`** without `autoHeight` — for a full-screen host that sizes the iframe itself. It receives
+  the app's content height whenever the app reports one, **and** on every window resize the window's
+  height below the iframe's container.
+
 ## Advanced Examples
 
 ### Deep Linking / Route Synchronization
@@ -175,6 +188,8 @@ const responder = new smartlinks.IframeResponder({
 
 ### Responsive Height Management
 
+An app in a page: `autoHeight` (above) does it all. A full-screen host that manages the height itself:
+
 ```typescript
 const responder = new smartlinks.IframeResponder({
   collectionId: 'acme-wines',
@@ -442,7 +457,7 @@ import type {
 3. **Clean up** responder with `destroy()` when unmounting
 4. **Use version control** to test against development versions
 5. **Validate tokens** server-side for security
-6. **Set height dynamically** based on content using `onResize`
+6. **Size the iframe to its content** with `autoHeight` (an app in a page) or `onResize` (a full-screen host)
 7. **Sync routes** with parent navigation for better UX
 8. **Set `parentPath`** for routes that have a meaningful parent screen in the app hierarchy
 
@@ -458,8 +473,9 @@ import type {
 - Verify token is being set with `setBearerToken()`
 - Check that auth messages are being received
 
-### Height not updating
-- Implement `onResize` callback
+### Height not updating, or a scrollbar inside the iframe
+- An app in a page: use `autoHeight` instead of setting the height yourself
+- A full-screen host: implement the `onResize` callback
 - Ensure iframe has CSS styling for height changes
 - Check that iframe is sending resize messages
 

package/dist/docs/websites.md

@@ -80,11 +80,17 @@ const responder = new SL.IframeResponder({
   appId: 'appointments',            // the app's id on this collection
   initialPath: '/my-bookings',      // the page's `path`
   params: { service: 'svc_123' },   // what the page `accepts`
-  onResize: (h) => { iframe.style.height = `${h}px` },
+  autoHeight: { minHeight: 480 },   // the iframe is as tall as the page: your page scrolls, never the iframe
 })
 iframe.src = await responder.attach(iframe)
 ```
 
+- **Size it with `autoHeight`, not by hand.** The responder sets the iframe's height from the page's own
+  height and counts the iframe's border and padding, so there's nothing left to scroll. Setting
+  `iframe.style.height` from `onResize` yourself goes wrong in a site: `onResize` also fires on every
+  window resize with "the window below the iframe" (for a full-screen host), and a bordered iframe
+  (Tailwind's border-box) ends up a few pixels short — a scrollbar inside the frame.
+
 - **The visitor's session goes with it.** The page's API calls are proxied through the site, so it
   acts as whoever is signed in to the site (or as a guest). Never pass a token in the URL.
 - **The app must be installed** on the site's collection; its address comes from there.

package/dist/iframe.js

@@ -36,16 +36,29 @@ export var iframe;
     function sendHeight(height, extra) {
         if (!inIframe())
             return;
-        const h = height !== null && height !== void 0 ? height : document.documentElement.scrollHeight;
+        const h = height !== null && height !== void 0 ? height : measureHeight();
         postParentMessage((resizeOptions === null || resizeOptions === void 0 ? void 0 : resizeOptions.messageType) || 'smartlinks:resize', Object.assign(Object.assign({ height: h }, resizeOptions === null || resizeOptions === void 0 ? void 0 : resizeOptions.extra), extra));
     }
     iframe.sendHeight = sendHeight;
+    /**
+     * The page's own height — not the frame's. scrollHeight and clientHeight are never less than the iframe's
+     * viewport, so a page that got shorter (a step done, a list emptied) was still reported at the frame's old
+     * height and the frame never shrank. When the page overflows the frame, its scrollHeight is the real
+     * height (absolutely positioned content included); when it fits, the document's own box is.
+     */
     function measureHeight() {
         if (!isBrowser())
             return 0;
         const doc = document.documentElement;
-        // Use max of several properties for robustness
-        return Math.max(doc.scrollHeight, doc.offsetHeight, doc.clientHeight, document.body ? document.body.scrollHeight : 0, document.body ? document.body.offsetHeight : 0);
+        if (doc.scrollHeight > doc.clientHeight + 1)
+            return doc.scrollHeight;
+        const body = document.body;
+        let bodyHeight = 0;
+        if (body) {
+            const cs = window.getComputedStyle(body);
+            bodyHeight = body.offsetHeight + (parseFloat(cs.marginTop) || 0) + (parseFloat(cs.marginBottom) || 0);
+        }
+        return Math.ceil(Math.max(doc.offsetHeight, bodyHeight));
     }
     function scheduleManualPolling() {
         var _a;
@@ -61,33 +74,63 @@ export var iframe;
             }
         }, interval);
     }
+    let measureQueued = false;
+    /**
+     * Measure once, a moment after a burst of changes, however many asked for it. A timer, not
+     * requestAnimationFrame: frames are paused in a hidden page and in an off-screen cross-origin iframe (an
+     * app below the fold), so the height wasn't reported until it was scrolled into view; timers only slow down.
+     */
+    function queueMeasure() {
+        if (measureQueued || !isBrowser())
+            return;
+        measureQueued = true;
+        const run = () => {
+            measureQueued = false;
+            if (!resizeOptions)
+                return;
+            const h = measureHeight();
+            if (resizeOptions.alwaysSend || h !== lastHeight) {
+                lastHeight = h;
+                sendHeight(h);
+            }
+        };
+        setTimeout(run, 30);
+    }
+    let lastWidth = 0;
+    /** The frame got wider or narrower: the page reflows. (Its height is ours to set — not a reason.) */
+    function onWindowResize() {
+        if (window.innerWidth === lastWidth)
+            return;
+        lastWidth = window.innerWidth;
+        queueMeasure();
+    }
+    const CONTENT_EVENTS = ['load', 'transitionend', 'animationend'];
+    /**
+     * Re-measure when something that changes the page's height happens: its content (any DOM change — a step
+     * rendered, times loaded), an image or font arriving, a transition or animation ending, the frame's width.
+     * Never the frame's own height: an app held at the frame's height (html/body/root at 100%, a 100vh
+     * wrapper — common in app templates) changes size whenever the host resizes the frame, so watching it
+     * re-measured after every resize and, with a few px beyond 100vh, grew the frame step by step. Content
+     * growing INSIDE such a pinned body never resized it either, so it was never reported (the booking app
+     * said "700" once while loading and nothing after).
+     */
     function setupObservers() {
         if (!isBrowser())
             return;
-        // Prefer ResizeObserver for layout changes
-        if (typeof ResizeObserver !== 'undefined') {
-            resizeObserver = new ResizeObserver(() => {
-                const h = measureHeight();
-                if ((resizeOptions === null || resizeOptions === void 0 ? void 0 : resizeOptions.alwaysSend) || h !== lastHeight) {
-                    lastHeight = h;
-                    sendHeight(h);
-                }
-            });
-            resizeObserver.observe(document.body);
+        if (typeof MutationObserver !== 'undefined') {
+            mutationObserver = new MutationObserver(queueMeasure);
+            mutationObserver.observe(document.documentElement, { childList: true, subtree: true, attributes: true, characterData: true });
         }
         else {
-            // Fallback: MutationObserver for DOM changes
-            mutationObserver = new MutationObserver(() => {
-                const h = measureHeight();
-                if ((resizeOptions === null || resizeOptions === void 0 ? void 0 : resizeOptions.alwaysSend) || h !== lastHeight) {
-                    lastHeight = h;
-                    sendHeight(h);
-                }
-            });
-            mutationObserver.observe(document.body, { childList: true, subtree: true, attributes: true });
-            // Manual polling as additional safeguard
             scheduleManualPolling();
         }
+        for (const e of CONTENT_EVENTS)
+            document.addEventListener(e, queueMeasure, true);
+        const fonts = document.fonts;
+        if (fonts && typeof fonts.addEventListener === 'function')
+            fonts.addEventListener('loadingdone', queueMeasure);
+        lastWidth = window.innerWidth;
+        window.addEventListener('resize', onWindowResize);
     }
     /** Enable automatic height reporting to parent iframe. */
     function enableAutoIframeResize(options) {
@@ -97,10 +140,6 @@ export var iframe;
         lastHeight = measureHeight();
         sendHeight(lastHeight);
         setupObservers();
-        if (!resizeObserver) {
-            // If no ResizeObserver, MutationObserver is active and we also poll
-            scheduleManualPolling();
-        }
     }
     iframe.enableAutoIframeResize = enableAutoIframeResize;
     /** Disable automatic height reporting. */
@@ -109,8 +148,15 @@ export var iframe;
             resizeObserver.disconnect();
         if (mutationObserver)
             mutationObserver.disconnect();
-        if (isBrowser())
+        if (isBrowser()) {
+            for (const e of CONTENT_EVENTS)
+                document.removeEventListener(e, queueMeasure, true);
+            const fonts = document.fonts;
+            if (fonts && typeof fonts.removeEventListener === 'function')
+                fonts.removeEventListener('loadingdone', queueMeasure);
+            window.removeEventListener('resize', onWindowResize);
             clearInterval(autoResizeTimer);
+        }
         resizeObserver = undefined;
         mutationObserver = undefined;
         autoResizeTimer = undefined;

package/dist/iframeResponder.d.ts

@@ -61,6 +61,12 @@ export declare class IframeResponder {
     private resolveAppUrl;
     private getVersionUrl;
     private buildIframeSrc;
+    /**
+     * autoHeight: the iframe exactly as tall as the app's content. The height set on an element with
+     * box-sizing: border-box (Tailwind's default) includes its border and padding, so those are added — a
+     * 1px border otherwise left the page 2px short and the iframe showed a pointless scrollbar.
+     */
+    private applyContentHeight;
     private calculateViewportHeight;
     private handleMessage;
     private handleRouteChange;

package/dist/iframeResponder.js

@@ -77,10 +77,15 @@ export class IframeResponder {
         // Set up message listener
         this.messageHandler = this.handleMessage.bind(this);
         window.addEventListener('message', this.messageHandler);
-        // Set up resize listener for viewport-based calculations
-        this.resizeHandler = this.calculateViewportHeight.bind(this);
-        window.addEventListener('resize', this.resizeHandler);
-        window.addEventListener('orientationchange', this.resizeHandler);
+        // autoHeight: sized to the app's content, so the iframe has nothing to scroll. Its own scrolling is
+        // left on: an app on an older SDK may still under-report its height, and a scrollbar beats content
+        // cut off.
+        if (!this.options.autoHeight) {
+            // Set up resize listener for viewport-based calculations (a full-screen host)
+            this.resizeHandler = this.calculateViewportHeight.bind(this);
+            window.addEventListener('resize', this.resizeHandler);
+            window.addEventListener('orientationchange', this.resizeHandler);
+        }
         const src = this.buildIframeSrc();
         return src;
     }
@@ -239,6 +244,30 @@ export class IframeResponder {
     // ===========================================================================
     // Viewport Resize Calculation
     // ===========================================================================
+    /**
+     * autoHeight: the iframe exactly as tall as the app's content. The height set on an element with
+     * box-sizing: border-box (Tailwind's default) includes its border and padding, so those are added — a
+     * 1px border otherwise left the page 2px short and the iframe showed a pointless scrollbar.
+     */
+    applyContentHeight(contentHeight) {
+        var _a;
+        const iframe = this.iframe;
+        if (!iframe)
+            return;
+        const min = typeof this.options.autoHeight === 'object' ? (_a = this.options.autoHeight.minHeight) !== null && _a !== void 0 ? _a : 0 : 0;
+        let extra = 0;
+        try {
+            const cs = window.getComputedStyle(iframe);
+            if (cs.boxSizing === 'border-box') {
+                extra = ['borderTopWidth', 'borderBottomWidth', 'paddingTop', 'paddingBottom']
+                    .reduce((n, k) => n + (parseFloat(cs[k]) || 0), 0);
+            }
+        }
+        catch (_b) {
+            /* no computed style (not in a document): the content height as it is */
+        }
+        iframe.style.height = `${Math.ceil(Math.max(min, contentHeight + extra))}px`;
+    }
     calculateViewportHeight() {
         var _a, _b;
         if (!this.iframe)
@@ -332,6 +361,8 @@ export class IframeResponder {
             case 'smartlinks:resize': {
                 const contentHeight = (_a = data.payload) === null || _a === void 0 ? void 0 : _a.height;
                 if (typeof contentHeight === 'number' && contentHeight > 0) {
+                    if (this.options.autoHeight)
+                        this.applyContentHeight(contentHeight);
                     (_c = (_b = this.options).onResize) === null || _c === void 0 ? void 0 : _c.call(_b, contentHeight);
                 }
                 break;

package/dist/openapi.yaml

@@ -27729,6 +27729,9 @@ components:
         accountData:
           type: object
           additionalProperties: true
+        autoHeight:
+          type: object
+          additionalProperties: true
       required:
         - collectionId
         - appId

package/dist/types/iframeResponder.d.ts

@@ -36,6 +36,21 @@ export interface IframeResponderOptions {
     onAuthLogin?: (token: string, user: any, accountData?: Record<string, any>) => Promise<void>;
     onAuthLogout?: () => Promise<void>;
     onRouteChange?: (path: string, state: Record<string, string>) => void;
+    /**
+     * Size the iframe to the app's content, for an app placed in a page (a booking form in a website, a
+     * widget in a section): the page scrolls, never the iframe. The responder sets the iframe's height from
+     * the height the app reports, adding the iframe's own border and padding, and never uses the
+     * window-filling height. `minHeight`: the least height (px) it's given.
+     * Leave off for a full-screen host, which sizes the iframe itself from `onResize`.
+     */
+    autoHeight?: boolean | {
+        minHeight?: number;
+    };
+    /**
+     * A height for the iframe: the app's content height whenever the app reports one, and — unless
+     * `autoHeight` is on — the window's height below the iframe's container on every window resize (for a
+     * full-screen host). A page that embeds an app should use `autoHeight` instead.
+     */
     onResize?: (height: number) => void;
     onError?: (error: Error) => void;
     onReady?: () => void;

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.1.7  |  Generated: 2026-11-01T12:48:45.040Z
+Version: 2.1.8  |  Generated: 2026-11-02T13:05:01.425Z
 
 This is a concise summary of all available API functions and types.
 
@@ -7539,6 +7539,7 @@ interface IframeResponderOptions {
   ) => Promise<void>;
   onAuthLogout?: () => Promise<void>;
   onRouteChange?: (path: string, state: Record<string, string>) => void;
+  autoHeight?: boolean | { minHeight?: number };
   onResize?: (height: number) => void;
   onError?: (error: Error) => void;
   onReady?: () => void;

package/docs/iframe-responder.md

@@ -35,10 +35,8 @@ const responder = new smartlinks.IframeResponder({
     smartlinks.setBearerToken(token);
     console.log('User logged in:', user);
   },
-  onResize: (height) => {
-    // Update iframe height
-    iframeElement.style.height = `${height}px`;
-  },
+  // An app in a page: the iframe is as tall as the app's content — the page scrolls, never the iframe.
+  autoHeight: { minHeight: 480 },
 });
 
 // Attach to iframe element
@@ -115,9 +113,24 @@ interface IframeResponderOptions {
   onResize?: (height: number) => void;
   onError?: (error: Error) => void;
   onReady?: () => void;
+
+  // Height
+  autoHeight?: boolean | { minHeight?: number }; // size the iframe to the app's content (an app in a page)
 }
 ```
 
+**Height: `autoHeight` or `onResize`.**
+
+- **`autoHeight`** — for an app placed in a page (a website, a section of a dashboard). The responder sets
+  the iframe's height from the height the app reports, adds the iframe's own border and padding (an
+  element with `box-sizing: border-box`, Tailwind's default, otherwise ends up short by its border — a
+  pointless scrollbar), and never uses the window-filling height. The iframe's own scrolling stays on as a
+  fallback for an app on an older SDK that under-reports its height. `minHeight`
+  is the least height it gives. `onResize` still hears each content height.
+- **`onResize`** without `autoHeight` — for a full-screen host that sizes the iframe itself. It receives
+  the app's content height whenever the app reports one, **and** on every window resize the window's
+  height below the iframe's container.
+
 ## Advanced Examples
 
 ### Deep Linking / Route Synchronization
@@ -175,6 +188,8 @@ const responder = new smartlinks.IframeResponder({
 
 ### Responsive Height Management
 
+An app in a page: `autoHeight` (above) does it all. A full-screen host that manages the height itself:
+
 ```typescript
 const responder = new smartlinks.IframeResponder({
   collectionId: 'acme-wines',
@@ -442,7 +457,7 @@ import type {
 3. **Clean up** responder with `destroy()` when unmounting
 4. **Use version control** to test against development versions
 5. **Validate tokens** server-side for security
-6. **Set height dynamically** based on content using `onResize`
+6. **Size the iframe to its content** with `autoHeight` (an app in a page) or `onResize` (a full-screen host)
 7. **Sync routes** with parent navigation for better UX
 8. **Set `parentPath`** for routes that have a meaningful parent screen in the app hierarchy
 
@@ -458,8 +473,9 @@ import type {
 - Verify token is being set with `setBearerToken()`
 - Check that auth messages are being received
 
-### Height not updating
-- Implement `onResize` callback
+### Height not updating, or a scrollbar inside the iframe
+- An app in a page: use `autoHeight` instead of setting the height yourself
+- A full-screen host: implement the `onResize` callback
 - Ensure iframe has CSS styling for height changes
 - Check that iframe is sending resize messages
 

package/docs/websites.md

@@ -80,11 +80,17 @@ const responder = new SL.IframeResponder({
   appId: 'appointments',            // the app's id on this collection
   initialPath: '/my-bookings',      // the page's `path`
   params: { service: 'svc_123' },   // what the page `accepts`
-  onResize: (h) => { iframe.style.height = `${h}px` },
+  autoHeight: { minHeight: 480 },   // the iframe is as tall as the page: your page scrolls, never the iframe
 })
 iframe.src = await responder.attach(iframe)
 ```
 
+- **Size it with `autoHeight`, not by hand.** The responder sets the iframe's height from the page's own
+  height and counts the iframe's border and padding, so there's nothing left to scroll. Setting
+  `iframe.style.height` from `onResize` yourself goes wrong in a site: `onResize` also fires on every
+  window resize with "the window below the iframe" (for a full-screen host), and a bordered iframe
+  (Tailwind's border-box) ends up a few pixels short — a scrollbar inside the frame.
+
 - **The visitor's session goes with it.** The page's API calls are proxied through the site, so it
   acts as whoever is signed in to the site (or as a guest). Never pass a token in the URL.
 - **The app must be installed** on the site's collection; its address comes from there.

package/openapi.yaml

@@ -27729,6 +27729,9 @@ components:
         accountData:
           type: object
           additionalProperties: true
+        autoHeight:
+          type: object
+          additionalProperties: true
       required:
         - collectionId
         - appId

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "2.1.7",
+  "version": "2.1.8",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "type": "module",
   "main": "dist/index.js",