feat: add runtime safe margin controls (#464)

* feat: add runtime safe margin controls

* fix: harden runtime safe-margin APIs

Require explicit boolean input for Android runtime safe-margin toggles instead of silently defaulting, preventing hidden client-side bugs.

Guard iOS runtime safe-margin constraint updates when webView is detached from self.view to avoid no-common-ancestor Auto Layout crashes.

Document that web implementations of runtime safe-margin APIs are no-ops in generated API docs.

Author: Albermonte

README.md

@@ -275,6 +275,8 @@ window.mobileApp.close();
 * [`removeAllListeners()`](#removealllisteners)
 * [`reload(...)`](#reload)
 * [`updateDimensions(...)`](#updatedimensions)
+* [`setEnabledSafeTopMargin(...)`](#setenabledsafetopmargin)
+* [`setEnabledSafeBottomMargin(...)`](#setenabledsafebottommargin)
 * [`openSecureWindow(...)`](#opensecurewindow)
 * [Interfaces](#interfaces)
 * [Type Aliases](#type-aliases)
@@ -705,6 +707,40 @@ When `id` is omitted, targets the active webview.
 --------------------
 
 
+### setEnabledSafeTopMargin(...)
+
+```typescript
+setEnabledSafeTopMargin(options: { enabled: boolean; id?: string; }) => Promise<void>
+```
+
+Sets the enabled safe top margin of the webview at runtime.
+When `id` is omitted, targets the active webview.
+On Web, this method is a no-op and resolves without changing layout.
+
+| Param         | Type                                            |
+| ------------- | ----------------------------------------------- |
+| **`options`** | <code>{ enabled: boolean; id?: string; }</code> |
+
+--------------------
+
+
+### setEnabledSafeBottomMargin(...)
+
+```typescript
+setEnabledSafeBottomMargin(options: { enabled: boolean; id?: string; }) => Promise<void>
+```
+
+Sets the enabled safe bottom margin of the webview at runtime.
+When `id` is omitted, targets the active webview.
+On Web, this method is a no-op and resolves without changing layout.
+
+| Param         | Type                                            |
+| ------------- | ----------------------------------------------- |
+| **`options`** | <code>{ enabled: boolean; id?: string; }</code> |
+
+--------------------
+
+
 ### openSecureWindow(...)
 
 ```typescript

android/src/main/java/ee/forgr/capacitor_inappbrowser/InAppBrowserPlugin.java

@@ -1286,6 +1286,56 @@ public void run() {
         );
     }
 
+    @PluginMethod
+    public void setEnabledSafeTopMargin(PluginCall call) {
+        Boolean enabledValue = call.getBoolean("enabled");
+        if (enabledValue == null) {
+            call.reject("'enabled' (boolean) is required");
+            return;
+        }
+        boolean enabled = enabledValue;
+        String targetId = resolveTargetId(call);
+        WebViewDialog dialog = resolveDialog(targetId);
+        if (dialog == null) {
+            call.reject("WebView is not initialized");
+            return;
+        }
+        this.getActivity().runOnUiThread(() -> {
+            try {
+                dialog.setEnabledSafeTopMargin(enabled);
+                call.resolve();
+            } catch (Exception e) {
+                Log.e("InAppBrowser", "Error setting safe top margin: " + e.getMessage());
+                call.reject("Failed to set safe top margin: " + e.getMessage());
+            }
+        });
+    }
+
+    @PluginMethod
+    public void setEnabledSafeBottomMargin(PluginCall call) {
+        Boolean enabledValue = call.getBoolean("enabled");
+        if (enabledValue == null) {
+            call.reject("'enabled' (boolean) is required");
+            return;
+        }
+        boolean enabled = enabledValue;
+        String targetId = resolveTargetId(call);
+        WebViewDialog dialog = resolveDialog(targetId);
+        if (dialog == null) {
+            call.reject("WebView is not initialized");
+            return;
+        }
+        this.getActivity().runOnUiThread(() -> {
+            try {
+                dialog.setEnabledSafeBottomMargin(enabled);
+                call.resolve();
+            } catch (Exception e) {
+                Log.e("InAppBrowser", "Error setting safe bottom margin: " + e.getMessage());
+                call.reject("Failed to set safe bottom margin: " + e.getMessage());
+            }
+        });
+    }
+
     @PluginMethod
     public void openSecureWindow(PluginCall call) {
         String authEndpoint = call.getString("authEndpoint");

android/src/main/java/ee/forgr/capacitor_inappbrowser/WebViewDialog.java

@@ -3323,6 +3323,22 @@ public void updateDimensions(Integer width, Integer height, Integer x, Integer y
         applyDimensions();
     }
 
+    public void setEnabledSafeTopMargin(boolean enabled) {
+        if (_options.getEnabledSafeTopMargin() == enabled) return;
+        _options.setEnabledSafeTopMargin(enabled);
+        if (_webView != null) {
+            ViewCompat.requestApplyInsets(_webView);
+        }
+    }
+
+    public void setEnabledSafeBottomMargin(boolean enabled) {
+        if (_options.getEnabledSafeMargin() == enabled) return;
+        _options.setEnabledSafeMargin(enabled);
+        if (_webView != null) {
+            ViewCompat.requestApplyInsets(_webView);
+        }
+    }
+
     /**
      * Convert density-independent pixels (dp) to actual pixels
      */

ios/Sources/InAppBrowserPlugin/InAppBrowserPlugin.swift

@@ -48,6 +48,8 @@ public class InAppBrowserPlugin: CAPPlugin, CAPBridgedPlugin {
         CAPPluginMethod(name: "executeScript", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "postMessage", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "updateDimensions", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "setEnabledSafeTopMargin", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "setEnabledSafeBottomMargin", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "getPluginVersion", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "openSecureWindow", returnType: CAPPluginReturnPromise),
     ]
@@ -1368,6 +1370,38 @@ public class InAppBrowserPlugin: CAPPlugin, CAPBridgedPlugin {
         }
     }
 
+    @objc func setEnabledSafeTopMargin(_ call: CAPPluginCall) {
+        if call.options["enabled"] == nil {
+            print("[InAppBrowser][Warning] setEnabledSafeTopMargin called without 'enabled'; defaulting to true")
+        }
+        let enabled = call.getBool("enabled", true)
+        DispatchQueue.main.async {
+            let targetId = call.getString("id") ?? self.activeWebViewId
+            guard let webViewController = self.resolveWebViewController(for: targetId) else {
+                call.reject("WebView is not initialized")
+                return
+            }
+            webViewController.updateSafeTopMargin(enabled)
+            call.resolve()
+        }
+    }
+
+    @objc func setEnabledSafeBottomMargin(_ call: CAPPluginCall) {
+        if call.options["enabled"] == nil {
+            print("[InAppBrowser][Warning] setEnabledSafeBottomMargin called without 'enabled'; defaulting to false")
+        }
+        let enabled = call.getBool("enabled", false)
+        DispatchQueue.main.async {
+            let targetId = call.getString("id") ?? self.activeWebViewId
+            guard let webViewController = self.resolveWebViewController(for: targetId) else {
+                call.reject("WebView is not initialized")
+                return
+            }
+            webViewController.updateSafeBottomMargin(enabled)
+            call.resolve()
+        }
+    }
+
     @objc func openSecureWindow(_ call: CAPPluginCall) {
         guard let urlString = call.getString("authEndpoint") else {
             call.reject("authEndpoint is required")

ios/Sources/InAppBrowserPlugin/WKWebViewController.swift

@@ -2046,6 +2046,46 @@ extension WKWebViewController: WKNavigationDelegate {
         // Apply the new dimensions
         applyCustomDimensions()
     }
+
+    open func updateSafeTopMargin(_ enabled: Bool) {
+        guard enabled != self.enabledSafeTopMargin else { return }
+        self.enabledSafeTopMargin = enabled
+        guard let webView = self.webView else { return }
+        guard webView.superview === self.view else { return }
+
+        // Find and deactivate the existing top constraint
+        let existingTopConstraints = self.view.constraints.filter {
+            ($0.firstItem as? WKWebView) == webView && $0.firstAttribute == .top
+        }
+        NSLayoutConstraint.deactivate(existingTopConstraints)
+
+        // Create new top constraint based on enabled value
+        let topAnchor = enabled ? self.view.safeAreaLayoutGuide.topAnchor : self.view.topAnchor
+        NSLayoutConstraint.activate([
+            webView.topAnchor.constraint(equalTo: topAnchor)
+        ])
+        self.view.layoutIfNeeded()
+    }
+
+    open func updateSafeBottomMargin(_ enabled: Bool) {
+        guard enabled != self.enabledSafeBottomMargin else { return }
+        self.enabledSafeBottomMargin = enabled
+        guard let webView = self.webView else { return }
+        guard webView.superview === self.view else { return }
+
+        // Find and deactivate the existing bottom constraint
+        let existingBottomConstraints = self.view.constraints.filter {
+            ($0.firstItem as? WKWebView) == webView && $0.firstAttribute == .bottom
+        }
+        NSLayoutConstraint.deactivate(existingBottomConstraints)
+
+        // Create new bottom constraint based on enabled value
+        let bottomAnchor = enabled ? self.view.safeAreaLayoutGuide.bottomAnchor : self.view.bottomAnchor
+        NSLayoutConstraint.activate([
+            webView.bottomAnchor.constraint(equalTo: bottomAnchor)
+        ])
+        self.view.layoutIfNeeded()
+    }
 }
 
 class BlockBarButtonItem: UIBarButtonItem {

src/definitions.ts

@@ -946,6 +946,20 @@ export interface InAppBrowserPlugin {
    */
   updateDimensions(options: DimensionOptions & { id?: string }): Promise<void>;
 
+  /**
+   * Sets the enabled safe top margin of the webview at runtime.
+   * When `id` is omitted, targets the active webview.
+   * On Web, this method is a no-op and resolves without changing layout.
+   */
+  setEnabledSafeTopMargin(options: { enabled: boolean; id?: string }): Promise<void>;
+
+  /**
+   * Sets the enabled safe bottom margin of the webview at runtime.
+   * When `id` is omitted, targets the active webview.
+   * On Web, this method is a no-op and resolves without changing layout.
+   */
+  setEnabledSafeBottomMargin(options: { enabled: boolean; id?: string }): Promise<void>;
+
   /**
    * Opens a secured window for OAuth2 authentication.
    * For web, you should have the code in the redirected page to use a broadcast channel to send the redirected url to the app

src/web.ts

@@ -89,6 +89,16 @@ export class InAppBrowserWeb extends WebPlugin implements InAppBrowserPlugin {
     return;
   }
 
+  async setEnabledSafeTopMargin(_options: { enabled: boolean; id?: string }): Promise<void> {
+    console.log('setEnabledSafeTopMargin not supported on web');
+    return;
+  }
+
+  async setEnabledSafeBottomMargin(_options: { enabled: boolean; id?: string }): Promise<void> {
+    console.log('setEnabledSafeBottomMargin not supported on web');
+    return;
+  }
+
   async openSecureWindow(options: OpenSecureWindowOptions): Promise<OpenSecureWindowResponse> {
     const w = 600;
     const h = 550;