@proveanything/smartlinks 2.1.7 → 2.1.10

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.10  |  Generated: 2026-11-03T16:21:02.896Z
 
 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/theme-tokens.md

@@ -99,6 +99,14 @@ renders correctly even against a host that sets none of them.
 
 Dark mode is a *theme* (a different value-set), not a separate token set — the host swaps the values.
 
+- **Host:** in dark mode, send a dark value-set — in the iframe address (`#slt=` with `theme: "dark"`, and the
+  legacy `theme=` payload with `m: "d"`) or on the mount root. Sending only the hook (`dark=1`, `.dark`)
+  leaves the app to guess.
+- **App:** `theme.css` has dark fallbacks under `.dark` / `[data-theme="dark"]`, so an app built on it stays
+  readable even when a host sends the hook and no values. An app with its own CSS variables should do the
+  same: a light fallback at the root, a dark one under the hook — never a light colour that also stands
+  in for dark.
+
 ---
 
 ## 3. Theme value-sets (what the AI emits, what the lookbook stores)

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/idbConnection.d.ts

@@ -0,0 +1,14 @@
+export interface IdbConnection {
+    /** The open connection, opening one if needed. */
+    open(): Promise<IDBDatabase>;
+    /** Forget the current connection so the next call re-opens. */
+    drop(closed?: IDBDatabase): void;
+    /**
+     * Run one transaction against the object store. If the connection is
+     * closed, re-open it and try once more. Errors from `body` are not retried.
+     */
+    run<T>(mode: IDBTransactionMode, body: (store: IDBObjectStore, tx: IDBTransaction) => T | Promise<T>): Promise<T>;
+}
+/** True for the error a transaction throws on a connection the browser closed. */
+export declare function isClosedConnectionError(error: unknown): boolean;
+export declare function createIdbConnection(dbName: string, storeName: string, version?: number): IdbConnection;

package/dist/idbConnection.js

@@ -0,0 +1,91 @@
+// src/idbConnection.ts
+// Shared IndexedDB connection handling for the SDK's caches.
+//
+// The browser may close an IndexedDB connection behind our back: iOS Safari
+// does it when the tab goes to the background, and any browser does it on
+// storage eviction or a version change. A transaction on a closed connection
+// throws "The database connection is closing", so a cache that keeps one
+// connection for the life of the page silently stops working after that.
+//
+// createIdbConnection() forgets a connection the browser closes and re-opens
+// on the next call; run() retries a transaction once when the connection
+// turns out to be closed.
+/** True for the error a transaction throws on a connection the browser closed. */
+export function isClosedConnectionError(error) {
+    const e = error;
+    if (!e)
+        return false;
+    if (e.name === 'InvalidStateError')
+        return true;
+    const msg = String(e.message || '');
+    return /connection is closing|database connection|closed/i.test(msg);
+}
+export function createIdbConnection(dbName, storeName, version = 1) {
+    let db = null;
+    let opening = null;
+    const drop = (closed) => {
+        // A newer connection may already have replaced the one that closed.
+        if (closed && db && db !== closed)
+            return;
+        db = null;
+        opening = null;
+    };
+    const open = () => {
+        if (db)
+            return Promise.resolve(db);
+        if (opening)
+            return opening;
+        opening = new Promise((resolve, reject) => {
+            try {
+                const req = indexedDB.open(dbName, version);
+                req.onupgradeneeded = (event) => {
+                    const upgrading = event.target.result;
+                    if (!upgrading.objectStoreNames.contains(storeName)) {
+                        upgrading.createObjectStore(storeName);
+                    }
+                };
+                req.onsuccess = () => {
+                    const opened = req.result;
+                    opened.onclose = () => drop(opened);
+                    opened.onversionchange = () => {
+                        opened.close();
+                        drop(opened);
+                    };
+                    db = opened;
+                    resolve(opened);
+                };
+                req.onerror = () => {
+                    opening = null;
+                    reject(req.error);
+                };
+                req.onblocked = () => {
+                    opening = null;
+                    reject(new Error(`[smartlinks] IndexedDB open blocked (${dbName})`));
+                };
+            }
+            catch (err) {
+                opening = null;
+                reject(err);
+            }
+        });
+        return opening;
+    };
+    const run = async (mode, body) => {
+        for (let attempt = 0;; attempt++) {
+            const current = await open();
+            let tx;
+            try {
+                tx = current.transaction(storeName, mode);
+            }
+            catch (err) {
+                if (attempt === 0 && isClosedConnectionError(err)) {
+                    drop(current);
+                    continue;
+                }
+                throw err;
+            }
+            return await body(tx.objectStore(storeName), tx);
+        }
+    };
+    return { open, drop, run };
+}

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/persistentCache.js

@@ -5,10 +5,15 @@
 // isIdbAvailable() and wrapped in try/catch so that failures in private-
 // browsing, quota-exceeded situations, or server-side environments are always
 // silent — they never propagate errors to the caller.
+//
+// The connection itself is managed by idbConnection.ts, which re-opens it when
+// the browser closes it behind our back (iOS Safari does this when the tab is
+// backgrounded) instead of leaving the cache dead for the rest of the page.
+import { createIdbConnection } from './idbConnection.js';
 const DB_NAME = 'smartlinks-sdk-cache';
 const STORE_NAME = 'responses';
 const DB_VERSION = 1;
-let dbPromise = null;
+const connection = createIdbConnection(DB_NAME, STORE_NAME, DB_VERSION);
 /**
  * Returns true only in environments where IndexedDB is genuinely available.
  * False in Node.js, and in some private-browsing contexts that stub indexedDB
@@ -22,36 +27,13 @@ export function isIdbAvailable() {
         return false;
     }
 }
-function openDb() {
-    if (dbPromise)
-        return dbPromise;
-    dbPromise = new Promise((resolve, reject) => {
-        try {
-            const req = indexedDB.open(DB_NAME, DB_VERSION);
-            req.onupgradeneeded = (event) => {
-                const db = event.target.result;
-                if (!db.objectStoreNames.contains(STORE_NAME)) {
-                    db.createObjectStore(STORE_NAME);
-                }
-            };
-            req.onsuccess = (event) => {
-                resolve(event.target.result);
-            };
-            req.onerror = () => {
-                dbPromise = null;
-                reject(req.error);
-            };
-            req.onblocked = () => {
-                dbPromise = null;
-                reject(new Error('[smartlinks] IndexedDB open blocked'));
-            };
-        }
-        catch (err) {
-            dbPromise = null;
-            reject(err);
-        }
+/** Resolve when the transaction settles, whatever the outcome. */
+function settled(tx) {
+    return new Promise((resolve) => {
+        tx.oncomplete = () => resolve();
+        tx.onerror = () => resolve(); // quota exceeded etc — fail silently
+        tx.onabort = () => resolve();
     });
-    return dbPromise;
 }
 /**
  * Read an entry from IndexedDB.
@@ -62,18 +44,11 @@ export async function idbGet(key) {
     if (!isIdbAvailable())
         return null;
     try {
-        const db = await openDb();
-        return new Promise((resolve) => {
-            try {
-                const tx = db.transaction(STORE_NAME, 'readonly');
-                const req = tx.objectStore(STORE_NAME).get(key);
-                req.onsuccess = () => { var _a; return resolve((_a = req.result) !== null && _a !== void 0 ? _a : null); };
-                req.onerror = () => resolve(null);
-            }
-            catch (_a) {
-                resolve(null);
-            }
-        });
+        return await connection.run('readonly', (store) => new Promise((resolve) => {
+            const req = store.get(key);
+            req.onsuccess = () => { var _a; return resolve((_a = req.result) !== null && _a !== void 0 ? _a : null); };
+            req.onerror = () => resolve(null);
+        }));
     }
     catch (_a) {
         return null;
@@ -88,18 +63,9 @@ export async function idbSet(key, entry) {
     if (!isIdbAvailable())
         return;
     try {
-        const db = await openDb();
-        await new Promise((resolve) => {
-            try {
-                const tx = db.transaction(STORE_NAME, 'readwrite');
-                tx.objectStore(STORE_NAME).put(entry, key);
-                tx.oncomplete = () => resolve();
-                tx.onerror = () => resolve(); // quota exceeded etc — fail silently
-                tx.onabort = () => resolve();
-            }
-            catch (_a) {
-                resolve();
-            }
+        await connection.run('readwrite', (store, tx) => {
+            store.put(entry, key);
+            return settled(tx);
         });
     }
     catch (_a) {
@@ -114,18 +80,9 @@ export async function idbDelete(key) {
     if (!isIdbAvailable())
         return;
     try {
-        const db = await openDb();
-        await new Promise((resolve) => {
-            try {
-                const tx = db.transaction(STORE_NAME, 'readwrite');
-                tx.objectStore(STORE_NAME).delete(key);
-                tx.oncomplete = () => resolve();
-                tx.onerror = () => resolve();
-                tx.onabort = () => resolve();
-            }
-            catch (_a) {
-                resolve();
-            }
+        await connection.run('readwrite', (store, tx) => {
+            store.delete(key);
+            return settled(tx);
         });
     }
     catch (_a) { }
@@ -138,41 +95,25 @@ export async function idbClear(pattern) {
     if (!isIdbAvailable())
         return;
     try {
-        const db = await openDb();
         if (!pattern) {
-            await new Promise((resolve) => {
-                try {
-                    const tx = db.transaction(STORE_NAME, 'readwrite');
-                    tx.objectStore(STORE_NAME).clear();
-                    tx.oncomplete = () => resolve();
-                    tx.onerror = () => resolve();
-                    tx.onabort = () => resolve();
-                }
-                catch (_a) {
-                    resolve();
-                }
+            await connection.run('readwrite', (store, tx) => {
+                store.clear();
+                return settled(tx);
             });
             return;
         }
         // Pattern-based: enumerate all keys and delete matching ones.
-        await new Promise((resolve) => {
-            try {
-                const tx = db.transaction(STORE_NAME, 'readwrite');
-                const store = tx.objectStore(STORE_NAME);
-                const req = store.getAllKeys();
-                req.onsuccess = () => {
-                    for (const key of req.result) {
-                        if (key.includes(pattern))
-                            store.delete(key);
-                    }
-                    resolve();
-                };
-                req.onerror = () => resolve();
-            }
-            catch (_a) {
+        await connection.run('readwrite', (store) => new Promise((resolve) => {
+            const req = store.getAllKeys();
+            req.onsuccess = () => {
+                for (const key of req.result) {
+                    if (key.includes(pattern))
+                        store.delete(key);
+                }
                 resolve();
-            }
-        });
+            };
+            req.onerror = () => resolve();
+        }));
     }
     catch (_a) { }
 }

package/dist/theme.css

@@ -41,6 +41,26 @@
   --shadow-md: var(--sl-shadow-md, 0 0 #0000);
 }
 
+/* Dark mode without values. A host in dark mode should send a dark value-set (the --sl-* tokens); one
+ * that only sets the hook (.dark / data-theme="dark") left every colour on its light fallback — white
+ * cards and near-black text on a dark page. Under the hook the fallbacks are dark too; whatever the host
+ * does send still wins. (Re-declared on the hook's element, so it works wherever the host puts it.) */
+.dark,
+[data-theme="dark"] {
+  --color-background:    var(--sl-color-bg, #09090b);
+  --color-surface:       var(--sl-color-surface, #18181b);
+  --color-surface-raised:var(--sl-color-surface-raised, var(--sl-color-surface, #27272a));
+  --color-foreground:    var(--sl-color-fg, #fafafa);
+  --color-muted:         var(--sl-color-muted, #a1a1aa);
+  --color-border:        var(--sl-color-border, #3f3f46);
+  --color-primary:       var(--sl-color-accent, #6366f1);
+  --color-on-primary:    var(--sl-color-on-accent, #ffffff);
+  --color-primary-soft:  var(--sl-color-accent-soft, color-mix(in oklab, var(--sl-color-accent, #6366f1) 20%, transparent));
+  --color-success:       var(--sl-color-success, #22c55e);
+  --color-danger:        var(--sl-color-danger, #f87171);
+  color-scheme: dark;
+}
+
 /* shadcn bridge (optional): if the app uses shadcn's --primary/--background/etc. HSL variables,
  * uncomment to drive them from the SmartLinks tokens too. Left commented so it never overrides an
  * app that has deliberately customised its shadcn palette — opt in per app (see migration step 17).

package/dist/translationCache.js

@@ -1,8 +1,9 @@
+import { createIdbConnection } from './idbConnection.js';
 const DB_NAME = 'smartlinks-sdk-translations';
 const STORE_NAME = 'translations';
 const DB_VERSION = 1;
 const DEFAULT_LOCAL_TRANSLATION_TTL_MS = 90 * 24 * 60 * 60000;
-let dbPromise = null;
+const connection = createIdbConnection(DB_NAME, STORE_NAME, DB_VERSION);
 const memoryTranslationCache = new Map();
 export function getDefaultTranslationCacheTtlMs() {
     return DEFAULT_LOCAL_TRANSLATION_TTL_MS;
@@ -15,36 +16,13 @@ function isIndexedDbAvailable() {
         return false;
     }
 }
-function openDb() {
-    if (dbPromise)
-        return dbPromise;
-    dbPromise = new Promise((resolve, reject) => {
-        try {
-            const request = indexedDB.open(DB_NAME, DB_VERSION);
-            request.onupgradeneeded = (event) => {
-                const db = event.target.result;
-                if (!db.objectStoreNames.contains(STORE_NAME)) {
-                    db.createObjectStore(STORE_NAME);
-                }
-            };
-            request.onsuccess = (event) => {
-                resolve(event.target.result);
-            };
-            request.onerror = () => {
-                dbPromise = null;
-                reject(request.error);
-            };
-            request.onblocked = () => {
-                dbPromise = null;
-                reject(new Error('[smartlinks] Translation IndexedDB open blocked'));
-            };
-        }
-        catch (error) {
-            dbPromise = null;
-            reject(error);
-        }
+/** Resolve when the transaction settles, whatever the outcome. */
+function settled(tx) {
+    return new Promise((resolve) => {
+        tx.oncomplete = () => resolve();
+        tx.onerror = () => resolve();
+        tx.onabort = () => resolve();
     });
-    return dbPromise;
 }
 function stableContextKey(context) {
     if (!context)
@@ -123,33 +101,26 @@ async function getEntry(key) {
     if (!isIndexedDbAvailable())
         return null;
     try {
-        const db = await openDb();
-        return await new Promise((resolve) => {
-            try {
-                const tx = db.transaction(STORE_NAME, 'readonly');
-                const request = tx.objectStore(STORE_NAME).get(key);
-                request.onsuccess = () => {
-                    var _a;
-                    const result = (_a = request.result) !== null && _a !== void 0 ? _a : null;
-                    if (!result) {
-                        resolve(null);
-                        return;
-                    }
-                    if (isExpired(result)) {
-                        memoryTranslationCache.delete(key);
-                        void deleteEntries([key]);
-                        resolve(null);
-                        return;
-                    }
-                    memoryTranslationCache.set(key, result);
-                    resolve(result);
-                };
-                request.onerror = () => resolve(null);
-            }
-            catch (_a) {
-                resolve(null);
-            }
-        });
+        return await connection.run('readonly', (store) => new Promise((resolve) => {
+            const request = store.get(key);
+            request.onsuccess = () => {
+                var _a;
+                const result = (_a = request.result) !== null && _a !== void 0 ? _a : null;
+                if (!result) {
+                    resolve(null);
+                    return;
+                }
+                if (isExpired(result)) {
+                    memoryTranslationCache.delete(key);
+                    void deleteEntries([key]);
+                    resolve(null);
+                    return;
+                }
+                memoryTranslationCache.set(key, result);
+                resolve(result);
+            };
+            request.onerror = () => resolve(null);
+        }));
     }
     catch (_a) {
         return null;
@@ -170,21 +141,11 @@ async function setEntries(entries) {
     if (!isIndexedDbAvailable())
         return;
     try {
-        const db = await openDb();
-        await new Promise((resolve) => {
-            try {
-                const tx = db.transaction(STORE_NAME, 'readwrite');
-                const store = tx.objectStore(STORE_NAME);
-                for (const [key, entry] of entries) {
-                    store.put(entry, key);
-                }
-                tx.oncomplete = () => resolve();
-                tx.onerror = () => resolve();
-                tx.onabort = () => resolve();
-            }
-            catch (_a) {
-                resolve();
+        await connection.run('readwrite', (store, tx) => {
+            for (const [key, entry] of entries) {
+                store.put(entry, key);
             }
+            return settled(tx);
         });
     }
     catch (_a) {
@@ -226,21 +187,11 @@ async function deleteEntries(keys) {
     if (!isIndexedDbAvailable() || keys.length === 0)
         return;
     try {
-        const db = await openDb();
-        await new Promise((resolve) => {
-            try {
-                const tx = db.transaction(STORE_NAME, 'readwrite');
-                const store = tx.objectStore(STORE_NAME);
-                for (const key of keys) {
-                    store.delete(key);
-                }
-                tx.oncomplete = () => resolve();
-                tx.onerror = () => resolve();
-                tx.onabort = () => resolve();
-            }
-            catch (_a) {
-                resolve();
+        await connection.run('readwrite', (store, tx) => {
+            for (const key of keys) {
+                store.delete(key);
             }
+            return settled(tx);
         });
     }
     catch (_a) {
@@ -256,41 +207,25 @@ export async function clearCachedTranslations(collectionId) {
     if (!isIndexedDbAvailable())
         return;
     try {
-        const db = await openDb();
         if (!collectionId) {
-            await new Promise((resolve) => {
-                try {
-                    const tx = db.transaction(STORE_NAME, 'readwrite');
-                    tx.objectStore(STORE_NAME).clear();
-                    tx.oncomplete = () => resolve();
-                    tx.onerror = () => resolve();
-                    tx.onabort = () => resolve();
-                }
-                catch (_a) {
-                    resolve();
-                }
+            await connection.run('readwrite', (store, tx) => {
+                store.clear();
+                return settled(tx);
             });
             return;
         }
-        await new Promise((resolve) => {
-            try {
-                const tx = db.transaction(STORE_NAME, 'readwrite');
-                const store = tx.objectStore(STORE_NAME);
-                const request = store.getAllKeys();
-                request.onsuccess = () => {
-                    for (const key of request.result) {
-                        if (key.startsWith(`${collectionId}::`)) {
-                            store.delete(key);
-                        }
+        await connection.run('readwrite', (store) => new Promise((resolve) => {
+            const request = store.getAllKeys();
+            request.onsuccess = () => {
+                for (const key of request.result) {
+                    if (key.startsWith(`${collectionId}::`)) {
+                        store.delete(key);
                     }
-                    resolve();
-                };
-                request.onerror = () => resolve();
-            }
-            catch (_a) {
+                }
                 resolve();
-            }
-        });
+            };
+            request.onerror = () => resolve();
+        }));
     }
     catch (_a) {
         // Ignore deletion failures.

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.10  |  Generated: 2026-11-03T16:21:02.896Z
 
 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/theme-tokens.md

@@ -99,6 +99,14 @@ renders correctly even against a host that sets none of them.
 
 Dark mode is a *theme* (a different value-set), not a separate token set — the host swaps the values.
 
+- **Host:** in dark mode, send a dark value-set — in the iframe address (`#slt=` with `theme: "dark"`, and the
+  legacy `theme=` payload with `m: "d"`) or on the mount root. Sending only the hook (`dark=1`, `.dark`)
+  leaves the app to guess.
+- **App:** `theme.css` has dark fallbacks under `.dark` / `[data-theme="dark"]`, so an app built on it stays
+  readable even when a host sends the hook and no values. An app with its own CSS variables should do the
+  same: a light fallback at the root, a dark one under the hook — never a light colour that also stands
+  in for dark.
+
 ---
 
 ## 3. Theme value-sets (what the AI emits, what the lookbook stores)

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,87 +1,87 @@
-{
-  "name": "@proveanything/smartlinks",
-  "version": "2.1.7",
-  "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
-  "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "default": "./dist/index.js"
-    },
-    "./testing": {
-      "types": "./dist/testing/index.d.ts",
-      "import": "./dist/testing/index.js",
-      "default": "./dist/testing/index.js"
-    },
-    "./*": {
-      "types": "./dist/*.d.ts",
-      "import": "./dist/*.js",
-      "default": "./dist/*.js"
-    },
-    "./baseline.css": "./dist/baseline.css",
-    "./baseline.classes.json": "./dist/baseline.classes.json",
-    "./theme.css": "./dist/theme.css",
-    "./theme-boot.js": "./dist/theme-boot.js",
-    "./package.json": "./package.json"
-  },
-  "bin": {
-    "smartlinks-register-release": "scripts/register-release.mjs",
-    "smartlinks-publish": "scripts/publish.mjs",
-    "smartlinks-doctor": "scripts/doctor.mjs",
-    "smartlinks-headless": "scripts/headless-check.mjs"
-  },
-  "files": [
-    "dist/",
-    "docs/",
-    "scripts/register-release.mjs",
-    "scripts/publish.mjs",
-    "scripts/doctor.mjs",
-    "scripts/headless-check.mjs",
-    "scripts/lib/",
-    "openapi.yaml",
-    "README.md"
-  ],
-  "scripts": {
-    "test": "node test/run.cjs",
-    "build": "tsc && node scripts/fix-esm-extensions.mjs && node generate-api-summary.cjs && node generate-openapi.cjs && node scripts/copy-docs-to-dist.cjs && node scripts/build-baseline.mjs",
-    "docs": "typedoc",
-    "docs:summary": "node generate-api-summary.cjs",
-    "docs:openapi": "node generate-openapi.cjs",
-    "docs:openapi:lint": "npx --yes @redocly/cli@latest lint openapi.yaml",
-    "docs:openapi:check": "node generate-openapi.cjs && npx --yes @redocly/cli@latest lint openapi.yaml",
-    "build:docs": "tsc build-docs.ts --outDir dist && node dist/build-docs.js",
-    "prepublishOnly": "npm run build"
-  },
-  "keywords": [
-    "smartlinks",
-    "api",
-    "authentication",
-    "traceability",
-    "blockchain",
-    "typescript",
-    "sdk"
-  ],
-  "author": "Glenn Shoosmith",
-  "license": "MIT",
-  "publishConfig": {
-    "access": "public"
-  },
-  "dependencies": {
-    "cross-fetch": "^3.1.5",
-    "es-module-lexer": "^1.7.0"
-  },
-  "devDependencies": {
-    "ts-node": "^10.9.1",
-    "typedoc": "^0.25.13",
-    "typedoc-plugin-markdown": "^3.17.1",
-    "typescript": "^4.9.0"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/Prove-Anything/smartlinks.git"
-  },
-  "homepage": "https://smartlinks.app"
-}
+{
+  "name": "@proveanything/smartlinks",
+  "version": "2.1.10",
+  "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js",
+      "default": "./dist/testing/index.js"
+    },
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "import": "./dist/*.js",
+      "default": "./dist/*.js"
+    },
+    "./baseline.css": "./dist/baseline.css",
+    "./baseline.classes.json": "./dist/baseline.classes.json",
+    "./theme.css": "./dist/theme.css",
+    "./theme-boot.js": "./dist/theme-boot.js",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "smartlinks-register-release": "scripts/register-release.mjs",
+    "smartlinks-publish": "scripts/publish.mjs",
+    "smartlinks-doctor": "scripts/doctor.mjs",
+    "smartlinks-headless": "scripts/headless-check.mjs"
+  },
+  "files": [
+    "dist/",
+    "docs/",
+    "scripts/register-release.mjs",
+    "scripts/publish.mjs",
+    "scripts/doctor.mjs",
+    "scripts/headless-check.mjs",
+    "scripts/lib/",
+    "openapi.yaml",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node test/run.cjs",
+    "build": "tsc && node scripts/fix-esm-extensions.mjs && node generate-api-summary.cjs && node generate-openapi.cjs && node scripts/copy-docs-to-dist.cjs && node scripts/build-baseline.mjs",
+    "docs": "typedoc",
+    "docs:summary": "node generate-api-summary.cjs",
+    "docs:openapi": "node generate-openapi.cjs",
+    "docs:openapi:lint": "npx --yes @redocly/cli@latest lint openapi.yaml",
+    "docs:openapi:check": "node generate-openapi.cjs && npx --yes @redocly/cli@latest lint openapi.yaml",
+    "build:docs": "tsc build-docs.ts --outDir dist && node dist/build-docs.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "smartlinks",
+    "api",
+    "authentication",
+    "traceability",
+    "blockchain",
+    "typescript",
+    "sdk"
+  ],
+  "author": "Glenn Shoosmith",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "cross-fetch": "^3.1.5",
+    "es-module-lexer": "^1.7.0"
+  },
+  "devDependencies": {
+    "ts-node": "^10.9.1",
+    "typedoc": "^0.25.13",
+    "typedoc-plugin-markdown": "^3.17.1",
+    "typescript": "^4.9.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Prove-Anything/smartlinks.git"
+  },
+  "homepage": "https://smartlinks.app"
+}