@ajuarezso/capacitor-liquid-glass 0.3.7 → 0.4.0

package/dist/plugin.js

@@ -1,9 +1,222 @@
 var capacitorLiquidGlass = (function (exports, core) {
     'use strict';
 
-    const LiquidGlass = core.registerPlugin('LiquidGlass', {
+    /**
+     * Keeps the native tab bar glued to an HTML element when `containerElement` is
+     * passed to `showTabBar`. Mirrors the measure-and-observe approach of
+     * `@capacitor/google-maps`, but adapted for a **fixed overlay** rather than an
+     * inline view:
+     *
+     *  - Google Maps (iOS) reparents its native view into a `WKChildScrollView` so
+     *    it scrolls *with* page content. A tab bar must stay glued to the element's
+     *    on-screen rect, so we instead push the rect to native, which positions an
+     *    on-top overlay via Auto Layout constraints (never `setFrame` — see the
+     *    iOS 26 Liquid Glass notes in `LiquidGlassTabBarOverlay.swift`).
+     *  - We re-sync on `ResizeObserver` + `scroll` (capture phase, catches nested
+     *    scroll containers) + `resize`/`orientationchange` + `visualViewport`
+     *    (keyboard / browser-chrome / pinch-zoom), all **coalesced through a single
+     *    `requestAnimationFrame`** so a 120 Hz scroll fires at most one bridge call
+     *    per frame (the Maps plugin's lack of this is its main jitter source).
+     *
+     * When `containerElement` is omitted, this is a transparent pass-through to the
+     * native bottom-pinned behaviour — zero regression.
+     */
+    class TabBarBinder {
+        constructor(native) {
+            this.native = native;
+            this.element = null;
+            this.resizeObserver = null;
+            this.rafId = null;
+            /** Last rect pushed to native — skip redundant bridge calls when unchanged. */
+            this.lastSent = null;
+            /**
+             * Bumped on every teardown. Async work (the `measure` retry loop, the awaits
+             * in `showTabBar`) snapshots it and bails if a newer call superseded it —
+             * prevents a slow first measurement from clobbering a second `showTabBar`.
+             */
+            this.generation = 0;
+            /** Stable identity so `removeEventListener` actually detaches the listeners. */
+            this.onReflow = () => this.scheduleSync();
+        }
+        async showTabBar(options) {
+            // A fresh call always supersedes any previous binding (bumps generation).
+            this.teardown();
+            const gen = this.generation;
+            const target = options.containerElement;
+            const wantsBinding = core.Capacitor.getPlatform() === 'ios' && target != null;
+            if (!wantsBinding) {
+                return this.native.showTabBar(this.stripElement(options));
+            }
+            const element = this.resolve(target);
+            if (!element) {
+                // Selector didn't match — fall back to bottom-pinned instead of throwing.
+                return this.native.showTabBar(this.stripElement(options));
+            }
+            this.element = element;
+            const bounds = await this.measure(element, gen);
+            if (gen !== this.generation)
+                return; // superseded while measuring
+            await this.native.showTabBar({ ...this.stripElement(options), bounds });
+            if (gen !== this.generation)
+                return; // superseded while the bridge call ran
+            this.lastSent = bounds;
+            this.observe(element);
+        }
+        async hideTabBar() {
+            this.teardown();
+            return this.native.hideTabBar();
+        }
+        // --- internals -----------------------------------------------------------
+        /** Removes the (possibly non-serializable) element ref before crossing the bridge. */
+        stripElement(options) {
+            if (options.containerElement == null)
+                return options;
+            const { containerElement: _drop, ...rest } = options;
+            return rest;
+        }
+        resolve(target) {
+            if (typeof target !== 'string')
+                return target;
+            return document.getElementById(target) ?? document.querySelector(target);
+        }
+        rect(element) {
+            const r = element.getBoundingClientRect();
+            return { x: r.x, y: r.y, width: r.width, height: r.height };
+        }
+        /**
+         * Retry until the element has a non-zero width AND height (guards against
+         * pre-layout reads). Bails early if a newer `showTabBar`/`hideTabBar` bumped
+         * the generation, so a stale interval can't outlive the call that started it.
+         * If it still measures 0 after ~3s, resolves with the zero rect (native falls
+         * back to bottom-pinned) and warns so the misconfig is visible.
+         */
+        measure(element, gen) {
+            const valid = (b) => b.width !== 0 && b.height !== 0;
+            return new Promise((resolve) => {
+                let bounds = this.rect(element);
+                if (valid(bounds)) {
+                    resolve(bounds);
+                    return;
+                }
+                let retries = 0;
+                const id = setInterval(() => {
+                    if (gen !== this.generation) {
+                        clearInterval(id);
+                        resolve(bounds);
+                        return;
+                    }
+                    bounds = this.rect(element);
+                    retries++;
+                    if (valid(bounds) || retries >= 30) {
+                        clearInterval(id);
+                        if (!valid(bounds)) {
+                            console.warn('[LiquidGlass] containerElement still measures 0 after 3s — the native bar will fall back to bottom-pinned.');
+                        }
+                        resolve(bounds);
+                    }
+                }, 100);
+            });
+        }
+        observe(element) {
+            if (typeof ResizeObserver !== 'undefined') {
+                this.resizeObserver = new ResizeObserver(this.onReflow);
+                this.resizeObserver.observe(element);
+            }
+            // Position changes a ResizeObserver won't catch. Capture phase so scrolls in
+            // nested `overflow:auto` containers (which don't bubble to window) re-sync too.
+            window.addEventListener('scroll', this.onReflow, { passive: true, capture: true });
+            window.addEventListener('resize', this.onReflow, { passive: true });
+            window.addEventListener('orientationchange', this.onReflow, { passive: true });
+            const vv = window.visualViewport;
+            if (vv) {
+                vv.addEventListener('resize', this.onReflow);
+                vv.addEventListener('scroll', this.onReflow);
+            }
+        }
+        scheduleSync() {
+            if (this.rafId != null)
+                return;
+            this.rafId = requestAnimationFrame(() => {
+                this.rafId = null;
+                if (!this.element)
+                    return;
+                const bounds = this.rect(this.element);
+                // Hidden / collapsed (display:none, detached, off-screen with 0 width):
+                // keep the last position, don't push a degenerate rect. A zero in EITHER
+                // dimension is useless — matches the native guard (rect.width/height > 0).
+                if (bounds.width === 0 || bounds.height === 0)
+                    return;
+                // Skip redundant bridge calls when the rect didn't actually move (e.g. a
+                // scroll in an unrelated container, or a position:fixed element). Each
+                // skipped call also saves a native `layoutIfNeeded`.
+                if (this.sameRect(bounds, this.lastSent))
+                    return;
+                this.lastSent = bounds;
+                void this.native.setTabBarBounds({ bounds });
+            });
+        }
+        sameRect(a, b) {
+            if (!b)
+                return false;
+            return (Math.abs(a.x - b.x) < 0.5 &&
+                Math.abs(a.y - b.y) < 0.5 &&
+                Math.abs(a.width - b.width) < 0.5 &&
+                Math.abs(a.height - b.height) < 0.5);
+        }
+        teardown() {
+            // Invalidate any in-flight measure/await chain from a previous call.
+            this.generation++;
+            this.lastSent = null;
+            if (this.rafId != null) {
+                cancelAnimationFrame(this.rafId);
+                this.rafId = null;
+            }
+            this.resizeObserver?.disconnect();
+            this.resizeObserver = null;
+            // `capture` must match the add-time flag for removal to take effect.
+            window.removeEventListener('scroll', this.onReflow, { capture: true });
+            window.removeEventListener('resize', this.onReflow);
+            window.removeEventListener('orientationchange', this.onReflow);
+            const vv = window.visualViewport;
+            if (vv) {
+                vv.removeEventListener('resize', this.onReflow);
+                vv.removeEventListener('scroll', this.onReflow);
+            }
+            this.element = null;
+        }
+    }
+
+    const native = core.registerPlugin('LiquidGlass', {
         web: () => Promise.resolve().then(function () { return web; }).then((m) => new m.LiquidGlassWeb()),
     });
+    /**
+     * Drives the HTML-element binding lifecycle (measure + observe) on top of the
+     * native bridge. When `showTabBar` is called without `containerElement` it is a
+     * transparent pass-through, so existing callers behave exactly as before.
+     */
+    const binder = new TabBarBinder(native);
+    /**
+     * Public plugin façade. Everything delegates straight to the native bridge
+     * except `showTabBar`/`hideTabBar`, which route through {@link TabBarBinder} so
+     * the optional `containerElement` binding works without any consumer wiring.
+     */
+    const LiquidGlass = {
+        showTabBar: (options) => binder.showTabBar(options),
+        hideTabBar: () => binder.hideTabBar(),
+        // iOS-only: the native method only exists on iOS. On Android the bridge would
+        // throw "not implemented"; resolve quietly instead (the binding layer already
+        // gates on getPlatform() === 'ios', this guards direct low-level callers).
+        setTabBarBounds: (options) => core.Capacitor.getPlatform() === 'ios' ? native.setTabBarBounds(options) : Promise.resolve(),
+        setSelectedTab: (options) => native.setSelectedTab(options),
+        updateTabBadge: (options) => native.updateTabBadge(options),
+        getTabBarLayout: () => native.getTabBarLayout(),
+        showSearchBar: (options) => native.showSearchBar(options),
+        hideSearchBar: () => native.hideSearchBar(),
+        clearSearchText: () => native.clearSearchText(),
+        // Preserve the overloaded signature for consumers (the bind keeps `this`).
+        addListener: native.addListener.bind(native),
+        removeAllListeners: () => native.removeAllListeners(),
+    };
 
     /**
      * Web fallback — real Liquid Glass requires native iOS 26. On the web we
@@ -27,6 +240,9 @@ var capacitorLiquidGlass = (function (exports, core) {
         async getTabBarLayout() {
             return { height: 0, bottomSafeArea: 0 };
         }
+        async setTabBarBounds(_options) {
+            // no-op on web — native-only positioning.
+        }
         async showSearchBar(_options) {
             // no-op on web — caller should render its own DOM search input.
         }

package/dist/plugin.js.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.js","sources":["esm/index.js","esm/web.js"],"sourcesContent":["import { registerPlugin } from '@capacitor/core';\nconst LiquidGlass = registerPlugin('LiquidGlass', {\n    web: () => import('./web').then((m) => new m.LiquidGlassWeb()),\n});\nexport * from './definitions';\nexport { LiquidGlass };\n","import { WebPlugin } from '@capacitor/core';\n/**\n * Web fallback — real Liquid Glass requires native iOS 26. On the web we\n * resolve no-ops so the app can run in the browser during development; the\n * Angular shell is expected to render its own CSS glassmorphism tab bar when\n * `isNativePlatform()` is false.\n */\nexport class LiquidGlassWeb extends WebPlugin {\n    async showTabBar(_options) {\n        // no-op on web\n    }\n    async hideTabBar() {\n        // no-op on web\n    }\n    async setSelectedTab(_options) {\n        // no-op on web\n    }\n    async updateTabBadge(_options) {\n        // no-op on web\n    }\n    async getTabBarLayout() {\n        return { height: 0, bottomSafeArea: 0 };\n    }\n    async showSearchBar(_options) {\n        // no-op on web — caller should render its own DOM search input.\n    }\n    async hideSearchBar() {\n        // no-op on web\n    }\n    async clearSearchText() {\n        // no-op on web\n    }\n}\n"],"names":["registerPlugin","WebPlugin"],"mappings":";;;AACK,UAAC,WAAW,GAAGA,mBAAc,CAAC,aAAa,EAAE;IAClD,IAAI,GAAG,EAAE,MAAM,mDAAe,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,cAAc,EAAE,CAAC;IAClE,CAAC;;ICFD;IACA;IACA;IACA;IACA;IACA;IACO,MAAM,cAAc,SAASC,cAAS,CAAC;IAC9C,IAAI,MAAM,UAAU,CAAC,QAAQ,EAAE;IAC/B;IACA,IAAI;IACJ,IAAI,MAAM,UAAU,GAAG;IACvB;IACA,IAAI;IACJ,IAAI,MAAM,cAAc,CAAC,QAAQ,EAAE;IACnC;IACA,IAAI;IACJ,IAAI,MAAM,cAAc,CAAC,QAAQ,EAAE;IACnC;IACA,IAAI;IACJ,IAAI,MAAM,eAAe,GAAG;IAC5B,QAAQ,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,cAAc,EAAE,CAAC,EAAE;IAC/C,IAAI;IACJ,IAAI,MAAM,aAAa,CAAC,QAAQ,EAAE;IAClC;IACA,IAAI;IACJ,IAAI,MAAM,aAAa,GAAG;IAC1B;IACA,IAAI;IACJ,IAAI,MAAM,eAAe,GAAG;IAC5B;IACA,IAAI;IACJ;;;;;;;;;;;;;;;"}
+{"version":3,"file":"plugin.js","sources":["esm/tab-bar-binder.js","esm/index.js","esm/web.js"],"sourcesContent":["import { Capacitor } from '@capacitor/core';\n/**\n * Keeps the native tab bar glued to an HTML element when `containerElement` is\n * passed to `showTabBar`. Mirrors the measure-and-observe approach of\n * `@capacitor/google-maps`, but adapted for a **fixed overlay** rather than an\n * inline view:\n *\n *  - Google Maps (iOS) reparents its native view into a `WKChildScrollView` so\n *    it scrolls *with* page content. A tab bar must stay glued to the element's\n *    on-screen rect, so we instead push the rect to native, which positions an\n *    on-top overlay via Auto Layout constraints (never `setFrame` — see the\n *    iOS 26 Liquid Glass notes in `LiquidGlassTabBarOverlay.swift`).\n *  - We re-sync on `ResizeObserver` + `scroll` (capture phase, catches nested\n *    scroll containers) + `resize`/`orientationchange` + `visualViewport`\n *    (keyboard / browser-chrome / pinch-zoom), all **coalesced through a single\n *    `requestAnimationFrame`** so a 120 Hz scroll fires at most one bridge call\n *    per frame (the Maps plugin's lack of this is its main jitter source).\n *\n * When `containerElement` is omitted, this is a transparent pass-through to the\n * native bottom-pinned behaviour — zero regression.\n */\nexport class TabBarBinder {\n    constructor(native) {\n        this.native = native;\n        this.element = null;\n        this.resizeObserver = null;\n        this.rafId = null;\n        /** Last rect pushed to native — skip redundant bridge calls when unchanged. */\n        this.lastSent = null;\n        /**\n         * Bumped on every teardown. Async work (the `measure` retry loop, the awaits\n         * in `showTabBar`) snapshots it and bails if a newer call superseded it —\n         * prevents a slow first measurement from clobbering a second `showTabBar`.\n         */\n        this.generation = 0;\n        /** Stable identity so `removeEventListener` actually detaches the listeners. */\n        this.onReflow = () => this.scheduleSync();\n    }\n    async showTabBar(options) {\n        // A fresh call always supersedes any previous binding (bumps generation).\n        this.teardown();\n        const gen = this.generation;\n        const target = options.containerElement;\n        const wantsBinding = Capacitor.getPlatform() === 'ios' && target != null;\n        if (!wantsBinding) {\n            return this.native.showTabBar(this.stripElement(options));\n        }\n        const element = this.resolve(target);\n        if (!element) {\n            // Selector didn't match — fall back to bottom-pinned instead of throwing.\n            return this.native.showTabBar(this.stripElement(options));\n        }\n        this.element = element;\n        const bounds = await this.measure(element, gen);\n        if (gen !== this.generation)\n            return; // superseded while measuring\n        await this.native.showTabBar({ ...this.stripElement(options), bounds });\n        if (gen !== this.generation)\n            return; // superseded while the bridge call ran\n        this.lastSent = bounds;\n        this.observe(element);\n    }\n    async hideTabBar() {\n        this.teardown();\n        return this.native.hideTabBar();\n    }\n    // --- internals -----------------------------------------------------------\n    /** Removes the (possibly non-serializable) element ref before crossing the bridge. */\n    stripElement(options) {\n        if (options.containerElement == null)\n            return options;\n        const { containerElement: _drop, ...rest } = options;\n        void _drop;\n        return rest;\n    }\n    resolve(target) {\n        if (typeof target !== 'string')\n            return target;\n        return document.getElementById(target) ?? document.querySelector(target);\n    }\n    rect(element) {\n        const r = element.getBoundingClientRect();\n        return { x: r.x, y: r.y, width: r.width, height: r.height };\n    }\n    /**\n     * Retry until the element has a non-zero width AND height (guards against\n     * pre-layout reads). Bails early if a newer `showTabBar`/`hideTabBar` bumped\n     * the generation, so a stale interval can't outlive the call that started it.\n     * If it still measures 0 after ~3s, resolves with the zero rect (native falls\n     * back to bottom-pinned) and warns so the misconfig is visible.\n     */\n    measure(element, gen) {\n        const valid = (b) => b.width !== 0 && b.height !== 0;\n        return new Promise((resolve) => {\n            let bounds = this.rect(element);\n            if (valid(bounds)) {\n                resolve(bounds);\n                return;\n            }\n            let retries = 0;\n            const id = setInterval(() => {\n                if (gen !== this.generation) {\n                    clearInterval(id);\n                    resolve(bounds);\n                    return;\n                }\n                bounds = this.rect(element);\n                retries++;\n                if (valid(bounds) || retries >= 30) {\n                    clearInterval(id);\n                    if (!valid(bounds)) {\n                        console.warn('[LiquidGlass] containerElement still measures 0 after 3s — the native bar will fall back to bottom-pinned.');\n                    }\n                    resolve(bounds);\n                }\n            }, 100);\n        });\n    }\n    observe(element) {\n        if (typeof ResizeObserver !== 'undefined') {\n            this.resizeObserver = new ResizeObserver(this.onReflow);\n            this.resizeObserver.observe(element);\n        }\n        // Position changes a ResizeObserver won't catch. Capture phase so scrolls in\n        // nested `overflow:auto` containers (which don't bubble to window) re-sync too.\n        window.addEventListener('scroll', this.onReflow, { passive: true, capture: true });\n        window.addEventListener('resize', this.onReflow, { passive: true });\n        window.addEventListener('orientationchange', this.onReflow, { passive: true });\n        const vv = window.visualViewport;\n        if (vv) {\n            vv.addEventListener('resize', this.onReflow);\n            vv.addEventListener('scroll', this.onReflow);\n        }\n    }\n    scheduleSync() {\n        if (this.rafId != null)\n            return;\n        this.rafId = requestAnimationFrame(() => {\n            this.rafId = null;\n            if (!this.element)\n                return;\n            const bounds = this.rect(this.element);\n            // Hidden / collapsed (display:none, detached, off-screen with 0 width):\n            // keep the last position, don't push a degenerate rect. A zero in EITHER\n            // dimension is useless — matches the native guard (rect.width/height > 0).\n            if (bounds.width === 0 || bounds.height === 0)\n                return;\n            // Skip redundant bridge calls when the rect didn't actually move (e.g. a\n            // scroll in an unrelated container, or a position:fixed element). Each\n            // skipped call also saves a native `layoutIfNeeded`.\n            if (this.sameRect(bounds, this.lastSent))\n                return;\n            this.lastSent = bounds;\n            void this.native.setTabBarBounds({ bounds });\n        });\n    }\n    sameRect(a, b) {\n        if (!b)\n            return false;\n        return (Math.abs(a.x - b.x) < 0.5 &&\n            Math.abs(a.y - b.y) < 0.5 &&\n            Math.abs(a.width - b.width) < 0.5 &&\n            Math.abs(a.height - b.height) < 0.5);\n    }\n    teardown() {\n        // Invalidate any in-flight measure/await chain from a previous call.\n        this.generation++;\n        this.lastSent = null;\n        if (this.rafId != null) {\n            cancelAnimationFrame(this.rafId);\n            this.rafId = null;\n        }\n        this.resizeObserver?.disconnect();\n        this.resizeObserver = null;\n        // `capture` must match the add-time flag for removal to take effect.\n        window.removeEventListener('scroll', this.onReflow, { capture: true });\n        window.removeEventListener('resize', this.onReflow);\n        window.removeEventListener('orientationchange', this.onReflow);\n        const vv = window.visualViewport;\n        if (vv) {\n            vv.removeEventListener('resize', this.onReflow);\n            vv.removeEventListener('scroll', this.onReflow);\n        }\n        this.element = null;\n    }\n}\n","import { Capacitor, registerPlugin } from '@capacitor/core';\nimport { TabBarBinder } from './tab-bar-binder';\nconst native = registerPlugin('LiquidGlass', {\n    web: () => import('./web').then((m) => new m.LiquidGlassWeb()),\n});\n/**\n * Drives the HTML-element binding lifecycle (measure + observe) on top of the\n * native bridge. When `showTabBar` is called without `containerElement` it is a\n * transparent pass-through, so existing callers behave exactly as before.\n */\nconst binder = new TabBarBinder(native);\n/**\n * Public plugin façade. Everything delegates straight to the native bridge\n * except `showTabBar`/`hideTabBar`, which route through {@link TabBarBinder} so\n * the optional `containerElement` binding works without any consumer wiring.\n */\nconst LiquidGlass = {\n    showTabBar: (options) => binder.showTabBar(options),\n    hideTabBar: () => binder.hideTabBar(),\n    // iOS-only: the native method only exists on iOS. On Android the bridge would\n    // throw \"not implemented\"; resolve quietly instead (the binding layer already\n    // gates on getPlatform() === 'ios', this guards direct low-level callers).\n    setTabBarBounds: (options) => Capacitor.getPlatform() === 'ios' ? native.setTabBarBounds(options) : Promise.resolve(),\n    setSelectedTab: (options) => native.setSelectedTab(options),\n    updateTabBadge: (options) => native.updateTabBadge(options),\n    getTabBarLayout: () => native.getTabBarLayout(),\n    showSearchBar: (options) => native.showSearchBar(options),\n    hideSearchBar: () => native.hideSearchBar(),\n    clearSearchText: () => native.clearSearchText(),\n    // Preserve the overloaded signature for consumers (the bind keeps `this`).\n    addListener: native.addListener.bind(native),\n    removeAllListeners: () => native.removeAllListeners(),\n};\nexport * from './definitions';\nexport { LiquidGlass };\n","import { WebPlugin } from '@capacitor/core';\n/**\n * Web fallback — real Liquid Glass requires native iOS 26. On the web we\n * resolve no-ops so the app can run in the browser during development; the\n * Angular shell is expected to render its own CSS glassmorphism tab bar when\n * `isNativePlatform()` is false.\n */\nexport class LiquidGlassWeb extends WebPlugin {\n    async showTabBar(_options) {\n        // no-op on web\n    }\n    async hideTabBar() {\n        // no-op on web\n    }\n    async setSelectedTab(_options) {\n        // no-op on web\n    }\n    async updateTabBadge(_options) {\n        // no-op on web\n    }\n    async getTabBarLayout() {\n        return { height: 0, bottomSafeArea: 0 };\n    }\n    async setTabBarBounds(_options) {\n        // no-op on web — native-only positioning.\n    }\n    async showSearchBar(_options) {\n        // no-op on web — caller should render its own DOM search input.\n    }\n    async hideSearchBar() {\n        // no-op on web\n    }\n    async clearSearchText() {\n        // no-op on web\n    }\n}\n"],"names":["Capacitor","registerPlugin","WebPlugin"],"mappings":"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"}

package/ios/Sources/LiquidGlassPlugin/LiquidGlassPlugin.swift

@@ -12,6 +12,7 @@ public class LiquidGlassPlugin: CAPPlugin, CAPBridgedPlugin {
         CAPPluginMethod(name: "setSelectedTab", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "updateTabBadge", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "getTabBarLayout", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "setTabBarBounds", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "showSearchBar", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "hideSearchBar", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "clearSearchText", returnType: CAPPluginReturnPromise),
@@ -28,6 +29,10 @@ public class LiquidGlassPlugin: CAPPlugin, CAPBridgedPlugin {
         let selectedIndex = call.getInt("selectedIndex") ?? 0
         let tintHex = call.getString("tintColor")
         let styleRaw = call.getString("tabBarStyle") ?? "default"
+        // Optional binding rect. When present the bar is positioned to match an
+        // HTML element instead of being pinned to the bottom (the JS layer
+        // measures the element and injects this). Invalid/absent → bottom-pinned.
+        let bounds = call.getObject("bounds").flatMap { Self.rect(from: $0) }
 
         let items = rawItems.compactMap { LiquidGlassTabItem(dictionary: $0) }
         guard !items.isEmpty else {
@@ -37,11 +42,36 @@ public class LiquidGlassPlugin: CAPPlugin, CAPBridgedPlugin {
 
         DispatchQueue.main.async { [weak self] in
             guard let self else { return }
-            self.presentTabBar(items: items, selectedIndex: selectedIndex, tintHex: tintHex, styleRaw: styleRaw)
+            self.presentTabBar(items: items, selectedIndex: selectedIndex, tintHex: tintHex, styleRaw: styleRaw, bounds: bounds)
             call.resolve()
         }
     }
 
+    @objc func setTabBarBounds(_ call: CAPPluginCall) {
+        guard let boundsDict = call.getObject("bounds"), let rect = Self.rect(from: boundsDict) else {
+            call.reject("bounds {x, y, width, height} is required")
+            return
+        }
+        DispatchQueue.main.async { [weak self] in
+            self?.tabBarOverlay?.setBounds(rect)
+            call.resolve()
+        }
+    }
+
+    /// Parses a `{x, y, width, height}` JS object into a `CGRect`. Tolerates
+    /// numbers arriving as `Double`, `Int` or `NSNumber` across the bridge.
+    private static func rect(from dict: JSObject) -> CGRect? {
+        func num(_ value: Any?) -> Double? {
+            if let d = value as? Double { return d }
+            if let n = value as? NSNumber { return n.doubleValue }
+            if let i = value as? Int { return Double(i) }
+            return nil
+        }
+        guard let x = num(dict["x"]), let y = num(dict["y"]),
+              let w = num(dict["width"]), let h = num(dict["height"]) else { return nil }
+        return CGRect(x: x, y: y, width: w, height: h)
+    }
+
     @objc func hideTabBar(_ call: CAPPluginCall) {
         DispatchQueue.main.async { [weak self] in
             self?.tabBarOverlay?.hide()
@@ -151,7 +181,7 @@ public class LiquidGlassPlugin: CAPPlugin, CAPBridgedPlugin {
         searchOverlay?.show(on: window)
     }
 
-    private func presentTabBar(items: [LiquidGlassTabItem], selectedIndex: Int, tintHex: String?, styleRaw: String) {
+    private func presentTabBar(items: [LiquidGlassTabItem], selectedIndex: Int, tintHex: String?, styleRaw: String, bounds: CGRect?) {
         // CRÍTICO: usar `bridge?.viewController` (el VC que contiene el
         // WKWebView de Capacitor) en lugar del `rootViewController` del
         // window. iOS 26 aplica Liquid Glass automáticamente al UITabBar
@@ -174,7 +204,9 @@ public class LiquidGlassPlugin: CAPPlugin, CAPBridgedPlugin {
         }
 
         let style = LiquidGlassTabBarStyle(rawValue: styleRaw) ?? .default
-        tabBarOverlay?.attach(to: hostVC)
+        // `bridge?.webView` is needed to convert the JS rect (viewport CSS px)
+        // into the host VC's coordinate space when binding to an HTML element.
+        tabBarOverlay?.attach(to: hostVC, bounds: bounds, webView: bridge?.webView)
         tabBarOverlay?.configure(items: items, selectedIndex: selectedIndex, tintHex: tintHex, style: style)
         tabBarOverlay?.show()
     }

package/ios/Sources/LiquidGlassPlugin/LiquidGlassTabBarOverlay.swift

@@ -66,6 +66,23 @@ final class LiquidGlassTabBarOverlay: UIViewController {
     private let tabBar = UITabBar()
     private var items: [LiquidGlassTabItem] = []
     private weak var hostVC: UIViewController?
+    /// WKWebView of the Capacitor bridge — used to convert the JS rect (viewport
+    /// CSS px) into the host VC's coordinate space when bound to an HTML element.
+    private weak var webView: UIView?
+
+    /// Currently-active container constraints (bottom-pinned OR bound), so a
+    /// re-`attach`/mode-switch can deactivate the previous set cleanly.
+    private var activeConstraints: [NSLayoutConstraint] = []
+    /// Mutable bound-mode geometry. Kept as properties so `setBounds` mutates
+    /// `.constant` (no detach/reattach → VC hierarchy stays intact and the iOS
+    /// 26 Liquid Glass auto-adopt is never re-triggered/lost).
+    private var boundTop: NSLayoutConstraint?
+    private var boundLeading: NSLayoutConstraint?
+    private var boundWidth: NSLayoutConstraint?
+    private var boundHeight: NSLayoutConstraint?
+    /// `true` when the container tracks an HTML element rect; `false` when
+    /// pinned to the bottom of the host (default).
+    private var isBoundMode = false
 
     override func viewDidLoad() {
         super.viewDidLoad()
@@ -101,37 +118,144 @@ final class LiquidGlassTabBarOverlay: UIViewController {
 
     /// Adjunta este view controller como child del view controller que
     /// contiene el WKWebView de Capacitor (`bridge?.viewController`).
-    /// Idempotente: si ya está adjuntado al mismo host, no-op.
-    func attach(to hostVC: UIViewController?) {
+    ///
+    /// - `bounds == nil` → **bottom-pinned** (comportamiento default histórico):
+    ///   leading/trailing/bottom al host, sin top — la altura sale del intrinsic
+    ///   content size del UITabBar (~50pt + safe-area-bottom).
+    /// - `bounds != nil` (y válido) → **bound mode**: el container se posiciona
+    ///   para coincidir con el rect de un elemento HTML, vía constraints
+    ///   mutables top/leading/width/height (NUNCA `setFrame` — ver `setBounds`).
+    ///
+    /// Idempotente respecto al parenting: si ya es child del mismo host no
+    /// re-adjunta, pero SÍ re-evalúa el layout (permite cambiar de modo o de
+    /// rect entre llamadas a `showTabBar`).
+    func attach(to hostVC: UIViewController?, bounds: CGRect?, webView: UIView?) {
         guard let hostVC else { return }
-        if self.parent === hostVC { return }
-        // Si está adjuntado a otro VC (cambio de host entre sesiones),
-        // detachar primero antes de re-adjuntar.
-        if self.parent != nil {
-            self.willMove(toParent: nil)
-            self.view.removeFromSuperview()
-            self.removeFromParent()
+        self.webView = webView
+
+        let wantsBound = bounds.map { $0.width > 0 && $0.height > 0 } ?? false
+
+        // No-op idempotente del PATH DEFAULT (bottom-pinned): re-mostrar el bar
+        // en el MISMO host sin binding (re-config de badge / cambio de route /
+        // liberación de modal — el consumer lo dispara agresivamente) debe NO
+        // tocar el layout del container, exactamente como antes de que existiera
+        // bound mode. Sin este early-return cada re-llamada haría
+        // deactivate+activate de las 3 constraints + un tabBarLayoutChanged de
+        // más (regresión detectada en review). Solo aplica cuando ya estamos
+        // bottom-pinned con constraints activas y NO se pide binding.
+        if self.parent === hostVC, !wantsBound, !isBoundMode, !activeConstraints.isEmpty {
+            return
         }
 
-        hostVC.addChild(self)
-        hostVC.view.addSubview(self.view)
-        self.view.translatesAutoresizingMaskIntoConstraints = false
-        // CRÍTICO: `didMove(toParent:)` ANTES de activar constraints. iOS 26
-        // ejecuta el primer layout pass al didMove; tener el parenting
-        // completo antes de que el sistema mida el UITabBar es lo que el
-        // heurístico de Liquid Glass auto-adopt espera (patrón stay-liquid).
-        self.didMove(toParent: hostVC)
-        // SIN top constraint — la altura del view se deriva del intrinsic
-        // content size del UITabBar dentro (~50pt + safe-area-bottom).
-        NSLayoutConstraint.activate([
-            self.view.leadingAnchor.constraint(equalTo: hostVC.view.leadingAnchor),
-            self.view.trailingAnchor.constraint(equalTo: hostVC.view.trailingAnchor),
-            self.view.bottomAnchor.constraint(equalTo: hostVC.view.bottomAnchor),
-        ])
+        if self.parent !== hostVC {
+            // Si está adjuntado a otro VC (cambio de host entre sesiones),
+            // detachar primero antes de re-adjuntar. Reseteamos TODO el estado
+            // de modo/constraints para no quedar apuntando a constraints muertas
+            // del host viejo (defensa en profundidad — review).
+            if self.parent != nil {
+                NSLayoutConstraint.deactivate(activeConstraints)
+                activeConstraints = []
+                boundTop = nil; boundLeading = nil; boundWidth = nil; boundHeight = nil
+                isBoundMode = false
+                self.willMove(toParent: nil)
+                self.view.removeFromSuperview()
+                self.removeFromParent()
+            }
+            hostVC.addChild(self)
+            hostVC.view.addSubview(self.view)
+            self.view.translatesAutoresizingMaskIntoConstraints = false
+            // CRÍTICO: `didMove(toParent:)` ANTES de activar constraints. iOS 26
+            // ejecuta el primer layout pass al didMove; tener el parenting
+            // completo antes de que el sistema mida el UITabBar es lo que el
+            // heurístico de Liquid Glass auto-adopt espera (patrón stay-liquid).
+            self.didMove(toParent: hostVC)
+        }
         self.hostVC = hostVC
+
+        // `width > 0 && height > 0` es obligatorio: un container medido en 0×0 en
+        // el primer layout pass es la única forma realista de PERDER el adopt de
+        // Liquid Glass. Si el rect llega vacío caemos a bottom-pinned y el
+        // siguiente `setBounds` con rect válido cambia a bound mode.
+        if let bounds, wantsBound {
+            applyBoundConstraints(bounds, hostVC: hostVC)
+        } else {
+            applyBottomPinned(hostVC: hostVC)
+        }
         emitLayout()
     }
 
+    /// Default: container pegado al bottom del host, ancho completo, altura
+    /// intrínseca del UITabBar. Idéntico al comportamiento previo a bound mode.
+    private func applyBottomPinned(hostVC: UIViewController) {
+        NSLayoutConstraint.deactivate(activeConstraints)
+        boundTop = nil; boundLeading = nil; boundWidth = nil; boundHeight = nil
+        isBoundMode = false
+        let constraints = [
+            view.leadingAnchor.constraint(equalTo: hostVC.view.leadingAnchor),
+            view.trailingAnchor.constraint(equalTo: hostVC.view.trailingAnchor),
+            view.bottomAnchor.constraint(equalTo: hostVC.view.bottomAnchor),
+        ]
+        NSLayoutConstraint.activate(constraints)
+        activeConstraints = constraints
+    }
+
+    /// Bound mode: posiciona el container al rect del elemento HTML mediante 4
+    /// constraints mutables (top/leading/width/height). Se usan CONSTRAINTS y no
+    /// `setFrame` a propósito: un `setFrame` pelea contra el Auto Layout pass del
+    /// host y puede resolver a `.zero` justo en el primer layout pass que iOS 26
+    /// inspecciona para el adopt → bar medido 0×0 → sin Liquid Glass.
+    private func applyBoundConstraints(_ rect: CGRect, hostVC: UIViewController) {
+        NSLayoutConstraint.deactivate(activeConstraints)
+        isBoundMode = true
+        let r = convertRectToHost(rect, hostVC: hostVC)
+        let top = view.topAnchor.constraint(equalTo: hostVC.view.topAnchor, constant: r.origin.y)
+        let leading = view.leadingAnchor.constraint(equalTo: hostVC.view.leadingAnchor, constant: r.origin.x)
+        let width = view.widthAnchor.constraint(equalToConstant: r.size.width)
+        let height = view.heightAnchor.constraint(equalToConstant: r.size.height)
+        NSLayoutConstraint.activate([top, leading, width, height])
+        boundTop = top; boundLeading = leading; boundWidth = width; boundHeight = height
+        activeConstraints = [top, leading, width, height]
+    }
+
+    /// Reposiciona el container a un nuevo rect (driven por el ResizeObserver/
+    /// scroll del lado JS). Solo muta `.constant` de las constraints existentes
+    /// — sin re-parenting, sin tocar el UITabBar — envuelto en `CATransaction`
+    /// con acciones implícitas desactivadas para que el movimiento sea snap (no
+    /// un lerp animado que se vería como jitter al scrollear).
+    func setBounds(_ rect: CGRect) {
+        // Bar oculto (post hideTabBar): no mutar constraints ni emitir layout de
+        // un bar que no se ve — evita estado inconsistente si un rAF en vuelo o
+        // una llamada low-level llega tras el hide (review).
+        guard !view.isHidden else { return }
+        guard rect.width > 0, rect.height > 0, let hostVC else { return }
+        // Primer rect válido tras un fallback a bottom-pinned → entrar a bound mode.
+        guard isBoundMode, let boundTop, let boundLeading, let boundWidth, let boundHeight else {
+            applyBoundConstraints(rect, hostVC: hostVC)
+            emitLayout()
+            return
+        }
+        let r = convertRectToHost(rect, hostVC: hostVC)
+        CATransaction.begin()
+        CATransaction.setDisableActions(true)
+        boundTop.constant = r.origin.y
+        boundLeading.constant = r.origin.x
+        boundWidth.constant = r.size.width
+        boundHeight.constant = r.size.height
+        hostVC.view.layoutIfNeeded()
+        CATransaction.commit()
+        emitLayout()
+    }
+
+    /// Convierte el rect COMPLETO (viewport CSS px == puntos del bounds del
+    /// webView) al espacio de coordenadas del host VC. Convertir el rect entero
+    /// — no solo el origen — cubre el caso de un webView insetado o escalado
+    /// respecto al host (sin esto, origen y tamaño quedarían en espacios
+    /// distintos; review). Con webView nil, fallback al rect crudo.
+    private func convertRectToHost(_ rect: CGRect, hostVC: UIViewController) -> CGRect {
+        guard let webView else { return rect }
+        return webView.convert(rect, to: hostVC.view)
+    }
+
     /// Aplica el appearance correspondiente al estilo solicitado.
     /// - `default` / `liquidGlass`: **NO-OP** — el UITabBar mantiene su
     ///   appearance default sin tocar para que iOS 26 aplique Liquid Glass
@@ -206,13 +330,11 @@ final class LiquidGlassTabBarOverlay: UIViewController {
             tabBar.selectedItem = uiItems[selectedIndex]
         }
 
-        // tintColor SOLO se aplica para estilos override (`.ultraThin`,
-        // `.transparent`). En `.default` / `.liquidGlass` iOS 26 aplica su
-        // propio tint nativo automático como parte del material Liquid Glass.
-        // Sobreescribirlo con un color custom (incluso brand) rompe el balance
-        // del material y produce un look híbrido en vez del adopt puro.
-        if style == .ultraThin || style == .transparent,
-           let tintHex, let tint = UIColor(hex: tintHex) {
+        // tintColor aplicado siempre — el A/B test contra stay-liquid confirmó
+        // que el adopt del material Liquid Glass NO se logra en este proyecto
+        // independientemente del tintColor, así que mantenerlo solo aporta
+        // identidad de marca (naranja brand) sin perder nada.
+        if let tintHex, let tint = UIColor(hex: tintHex) {
             tabBar.tintColor = tint
         }
         emitLayout()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ajuarezso/capacitor-liquid-glass",
-  "version": "0.3.7",
+  "version": "0.4.0",
   "description": "iOS 26 Liquid Glass native chrome (TabBar, NavigationBar, Alerts, Sheets) for Capacitor apps. Falls back gracefully on iOS < 26 and Android.",
   "main": "dist/plugin.cjs.js",
   "module": "dist/esm/index.js",