@capgo/capacitor-inappbrowser 8.14.2 → 8.15.0

package/dist/docs.json

@@ -999,9 +999,13 @@
             {
               "text": "0.1.0",
               "name": "since"
+            },
+            {
+              "text": "\"https://capgo.app\"",
+              "name": "example"
             }
           ],
-          "docs": "Target URL to load.",
+          "docs": "Target URL to load.\n\nRemote `http://` and `https://` URLs are loaded as-is. Relative bundled paths\nsuch as `/index.html` are not supported; use `openWebView()` instead.",
           "complexTypes": [],
           "type": "string"
         },
@@ -1403,12 +1407,20 @@
               "text": "0.1.0",
               "name": "since"
             },
+            {
+              "text": "8.15.0 Relative bundled paths (`/index.html`, `assets/page.html`) are supported.",
+              "name": "since"
+            },
             {
               "text": "\"https://capgo.app\"",
               "name": "example"
+            },
+            {
+              "text": "\"/index.html\"",
+              "name": "example"
             }
           ],
-          "docs": "Target URL to load.",
+          "docs": "Target URL to load.\n\nRemote `http://` and `https://` URLs are loaded as-is.\n\nTo open bundled web assets from the app bundle without running a local HTTP server,\npass a relative path such as `/index.html` or `assets/page.html`. The plugin resolves it to\nthe Capacitor local URL for the current platform (defaults: `capacitor://localhost/...` on iOS,\n`https://localhost/...` on Android; actual scheme and host follow the app's configured Capacitor\nlocal URL) and serves files from the packaged `public/` directory, or `www/` on iOS when `public/`\nis absent.",
           "complexTypes": [],
           "type": "string"
         },
@@ -2342,7 +2354,7 @@
               "name": "example"
             }
           ],
-          "docs": "If true, the webView will not take the full height and will have a 20px margin at the bottom.\nThis creates a safe margin area outside the browser view.",
+          "docs": "If true, the webView is inset by the bottom system bar (navigation bar) so bottom-anchored\ncontent stays reachable. On Android 15+ the browser window is always edge-to-edge, so the\nbottom inset is applied there regardless of this option.",
           "complexTypes": [],
           "type": "boolean | undefined"
         },
@@ -2362,7 +2374,7 @@
               "name": "example"
             }
           ],
-          "docs": "If false, the webView will extend behind the status bar for true full-screen immersive content.\nWhen true (default), respects the safe area at the top of the screen.\nWorks independently of toolbarType - use for full-screen video players, games, or immersive web apps.",
+          "docs": "If false, the webView will extend behind the status bar for true full-screen immersive content.\nWhen true (default), respects the safe area at the top of the screen.\nWorks independently of toolbarType - use for full-screen video players, games, or immersive web apps.\nOn Android, when a toolbar is visible the toolbar itself provides that safe area; with\n`toolbarType: 'blank'` on Android 15+ the status bar inset is applied to the webView instead.",
           "complexTypes": [],
           "type": "boolean | undefined"
         },
@@ -2378,7 +2390,7 @@
               "name": "example"
             }
           ],
-          "docs": "When true, applies the system status bar inset as the WebView top margin on Android.\nKeeps the legacy 0px margin by default for apps that handle padding themselves.",
+          "docs": "When true, applies the system status bar inset to the top of the WebView on Android even when\nthe window is not edge-to-edge (before Android 15). Keeps the legacy 0px inset by default for\napps that handle padding themselves. On Android 15+ this is not needed: without a visible\ntoolbar the status bar inset already follows `enabledSafeTopMargin`.",
           "complexTypes": [],
           "type": "boolean | undefined"
         },

package/dist/esm/bundled-asset-support.d.ts

@@ -0,0 +1,40 @@
+export type BundledAssetPlatform = 'ios' | 'android';
+export interface BundledAssetLocalConfig {
+    scheme: string;
+    host: string;
+}
+export interface BundledAssetResolution {
+    url: string;
+}
+/** Default Capacitor local URL settings used when no runtime config is available. */
+export declare const BUNDLED_ASSET_DEFAULTS: Record<BundledAssetPlatform, BundledAssetLocalConfig>;
+/** Returns true when the input looks like an absolute URL (including protocol-relative URLs). */
+export declare function isAbsoluteUrl(url: string): boolean;
+/** Returns true when any path segment is `..`. */
+export declare function containsPathTraversal(path: string): boolean;
+/**
+ * Normalizes a relative bundled asset path to a leading-slash form.
+ * Returns null when the path contains traversal segments.
+ */
+export declare function normalizeBundledPath(path: string): string | null;
+/** Parses a Capacitor local URL into scheme and host components. */
+export declare function parseBundledLocalConfig(localUrl?: string | null): BundledAssetLocalConfig | null;
+/** Returns the scheme WebView navigation should use for bundled assets on a platform. */
+export declare function handlerSchemeForPlatform(platform: BundledAssetPlatform, localConfig: BundledAssetLocalConfig): string;
+/**
+ * Returns true when the URL targets the configured Capacitor local host/scheme
+ * (including the platform handler scheme rewrite).
+ */
+export declare function isBundledLocalUrl(url: string, platform: BundledAssetPlatform, localConfig?: BundledAssetLocalConfig | null): boolean;
+/** Returns true when the input is a non-empty relative bundled asset path. */
+export declare function isRelativeBundledPath(url: string): boolean;
+/**
+ * Resolves a bundled asset URL for the given platform.
+ * Relative paths become platform-local URLs; bundled local URLs may be rewritten to the handler scheme.
+ */
+export declare function resolveBundledAssetUrl(url: string, platform: BundledAssetPlatform, localConfig?: BundledAssetLocalConfig | null): BundledAssetResolution | null;
+/**
+ * Resolves relative bundled paths for legacy native plugins that do not perform native resolution.
+ * Throws when the path is invalid.
+ */
+export declare function resolveLegacyNativeWebViewUrl(url: string, platform: BundledAssetPlatform, localConfig?: BundledAssetLocalConfig | null): string;

package/dist/esm/bundled-asset-support.js

@@ -0,0 +1,157 @@
+/** Default Capacitor local URL settings used when no runtime config is available. */
+export const BUNDLED_ASSET_DEFAULTS = {
+    ios: { scheme: 'capacitor', host: 'localhost' },
+    android: { scheme: 'https', host: 'localhost' },
+};
+const ABSOLUTE_URL_PATTERN = /^[a-zA-Z][a-zA-Z\d+\-.]*:/;
+const RESERVED_WEB_SCHEMES = ['http', 'https'];
+/** Returns true when the input looks like an absolute URL (including protocol-relative URLs). */
+export function isAbsoluteUrl(url) {
+    return ABSOLUTE_URL_PATTERN.test(url) || url.startsWith('//');
+}
+/** Returns true when any path segment is `..`. */
+export function containsPathTraversal(path) {
+    return path.split('/').includes('..');
+}
+/**
+ * Normalizes a relative bundled asset path to a leading-slash form.
+ * Returns null when the path contains traversal segments.
+ */
+export function normalizeBundledPath(path) {
+    const trimmed = path.trim();
+    if (!trimmed || trimmed === '/') {
+        return '/';
+    }
+    if (containsPathTraversal(trimmed)) {
+        return null;
+    }
+    return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+}
+/** Parses a Capacitor local URL into scheme and host components. */
+export function parseBundledLocalConfig(localUrl) {
+    if (!localUrl) {
+        return null;
+    }
+    try {
+        const parsed = new URL(localUrl.endsWith('/') ? localUrl : `${localUrl}/`);
+        if (!parsed.protocol || !parsed.hostname) {
+            return null;
+        }
+        return {
+            scheme: parsed.protocol.replace(/:$/, '').toLowerCase(),
+            host: parsed.hostname.toLowerCase(),
+        };
+    }
+    catch (_a) {
+        return null;
+    }
+}
+/** Returns the scheme WebView navigation should use for bundled assets on a platform. */
+export function handlerSchemeForPlatform(platform, localConfig) {
+    if (platform === 'ios' && RESERVED_WEB_SCHEMES.includes(localConfig.scheme)) {
+        return BUNDLED_ASSET_DEFAULTS.ios.scheme;
+    }
+    if (platform === 'android') {
+        if (localConfig.scheme === 'http' || localConfig.scheme === 'https') {
+            return localConfig.scheme;
+        }
+        return BUNDLED_ASSET_DEFAULTS.android.scheme;
+    }
+    return localConfig.scheme;
+}
+/**
+ * Returns true when the URL targets the configured Capacitor local host/scheme
+ * (including the platform handler scheme rewrite).
+ */
+export function isBundledLocalUrl(url, platform, localConfig) {
+    if (!isAbsoluteUrl(url)) {
+        return false;
+    }
+    try {
+        const parsed = new URL(url);
+        const scheme = parsed.protocol.replace(/:$/, '').toLowerCase();
+        const host = parsed.hostname.toLowerCase();
+        const config = localConfig !== null && localConfig !== void 0 ? localConfig : BUNDLED_ASSET_DEFAULTS[platform];
+        if (host !== config.host) {
+            return false;
+        }
+        if (parsed.port !== '') {
+            return false;
+        }
+        if (scheme === config.scheme || scheme === handlerSchemeForPlatform(platform, config)) {
+            return true;
+        }
+        return RESERVED_WEB_SCHEMES.includes(scheme) && RESERVED_WEB_SCHEMES.includes(config.scheme);
+    }
+    catch (_a) {
+        return false;
+    }
+}
+/** Returns true when the input is a non-empty relative bundled asset path. */
+export function isRelativeBundledPath(url) {
+    const trimmed = url.trim();
+    if (!trimmed) {
+        return false;
+    }
+    return !isAbsoluteUrl(trimmed);
+}
+function rewriteBundledLocalUrl(url, localConfig, navigationScheme) {
+    try {
+        const parsed = new URL(url);
+        const host = parsed.hostname.toLowerCase();
+        const scheme = parsed.protocol.replace(/:$/, '').toLowerCase();
+        if (host !== localConfig.host || scheme === navigationScheme) {
+            return null;
+        }
+        const pathname = parsed.pathname || '/';
+        const search = parsed.search;
+        const hash = parsed.hash;
+        const userinfo = parsed.username.length > 0 ? `${parsed.username}${parsed.password.length > 0 ? `:${parsed.password}` : ''}@` : '';
+        return `${navigationScheme}://${userinfo}${host}${pathname}${search}${hash}`;
+    }
+    catch (_a) {
+        return null;
+    }
+}
+/**
+ * Resolves a bundled asset URL for the given platform.
+ * Relative paths become platform-local URLs; bundled local URLs may be rewritten to the handler scheme.
+ */
+export function resolveBundledAssetUrl(url, platform, localConfig) {
+    const trimmed = url.trim();
+    const config = localConfig !== null && localConfig !== void 0 ? localConfig : BUNDLED_ASSET_DEFAULTS[platform];
+    const navigationScheme = handlerSchemeForPlatform(platform, config);
+    if (isRelativeBundledPath(trimmed)) {
+        const path = normalizeBundledPath(trimmed);
+        if (path === null) {
+            return null;
+        }
+        return {
+            url: `${navigationScheme}://${config.host}${path}`,
+        };
+    }
+    if (isBundledLocalUrl(trimmed, platform, config)) {
+        const rewritten = rewriteBundledLocalUrl(trimmed, config, navigationScheme);
+        return {
+            url: rewritten !== null && rewritten !== void 0 ? rewritten : trimmed,
+        };
+    }
+    return {
+        url: trimmed,
+    };
+}
+/**
+ * Resolves relative bundled paths for legacy native plugins that do not perform native resolution.
+ * Throws when the path is invalid.
+ */
+export function resolveLegacyNativeWebViewUrl(url, platform, localConfig) {
+    if (!isRelativeBundledPath(url)) {
+        return url;
+    }
+    const resolution = resolveBundledAssetUrl(url, platform, localConfig);
+    if (resolution === null) {
+        throw new Error('Invalid bundled asset path');
+    }
+    return resolution.url;
+}
+//# sourceMappingURL=bundled-asset-support.js.map

package/dist/esm/bundled-asset-support.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundled-asset-support.js","sourceRoot":"","sources":["../../src/bundled-asset-support.ts"],"names":[],"mappings":"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","sourcesContent":["export type BundledAssetPlatform = 'ios' | 'android';\n\nexport interface BundledAssetLocalConfig {\n  scheme: string;\n  host: string;\n}\n\nexport interface BundledAssetResolution {\n  url: string;\n}\n\n/** Default Capacitor local URL settings used when no runtime config is available. */\nexport const BUNDLED_ASSET_DEFAULTS: Record<BundledAssetPlatform, BundledAssetLocalConfig> = {\n  ios: { scheme: 'capacitor', host: 'localhost' },\n  android: { scheme: 'https', host: 'localhost' },\n};\n\nconst ABSOLUTE_URL_PATTERN = /^[a-zA-Z][a-zA-Z\\d+\\-.]*:/;\nconst RESERVED_WEB_SCHEMES = ['http', 'https'];\n\n/** Returns true when the input looks like an absolute URL (including protocol-relative URLs). */\nexport function isAbsoluteUrl(url: string): boolean {\n  return ABSOLUTE_URL_PATTERN.test(url) || url.startsWith('//');\n}\n\n/** Returns true when any path segment is `..`. */\nexport function containsPathTraversal(path: string): boolean {\n  return path.split('/').includes('..');\n}\n\n/**\n * Normalizes a relative bundled asset path to a leading-slash form.\n * Returns null when the path contains traversal segments.\n */\nexport function normalizeBundledPath(path: string): string | null {\n  const trimmed = path.trim();\n  if (!trimmed || trimmed === '/') {\n    return '/';\n  }\n\n  if (containsPathTraversal(trimmed)) {\n    return null;\n  }\n\n  return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;\n}\n\n/** Parses a Capacitor local URL into scheme and host components. */\nexport function parseBundledLocalConfig(localUrl?: string | null): BundledAssetLocalConfig | null {\n  if (!localUrl) {\n    return null;\n  }\n\n  try {\n    const parsed = new URL(localUrl.endsWith('/') ? localUrl : `${localUrl}/`);\n    if (!parsed.protocol || !parsed.hostname) {\n      return null;\n    }\n\n    return {\n      scheme: parsed.protocol.replace(/:$/, '').toLowerCase(),\n      host: parsed.hostname.toLowerCase(),\n    };\n  } catch {\n    return null;\n  }\n}\n\n/** Returns the scheme WebView navigation should use for bundled assets on a platform. */\nexport function handlerSchemeForPlatform(platform: BundledAssetPlatform, localConfig: BundledAssetLocalConfig): string {\n  if (platform === 'ios' && RESERVED_WEB_SCHEMES.includes(localConfig.scheme)) {\n    return BUNDLED_ASSET_DEFAULTS.ios.scheme;\n  }\n\n  if (platform === 'android') {\n    if (localConfig.scheme === 'http' || localConfig.scheme === 'https') {\n      return localConfig.scheme;\n    }\n    return BUNDLED_ASSET_DEFAULTS.android.scheme;\n  }\n\n  return localConfig.scheme;\n}\n\n/**\n * Returns true when the URL targets the configured Capacitor local host/scheme\n * (including the platform handler scheme rewrite).\n */\nexport function isBundledLocalUrl(\n  url: string,\n  platform: BundledAssetPlatform,\n  localConfig?: BundledAssetLocalConfig | null,\n): boolean {\n  if (!isAbsoluteUrl(url)) {\n    return false;\n  }\n\n  try {\n    const parsed = new URL(url);\n    const scheme = parsed.protocol.replace(/:$/, '').toLowerCase();\n    const host = parsed.hostname.toLowerCase();\n    const config = localConfig ?? BUNDLED_ASSET_DEFAULTS[platform];\n\n    if (host !== config.host) {\n      return false;\n    }\n\n    if (parsed.port !== '') {\n      return false;\n    }\n\n    if (scheme === config.scheme || scheme === handlerSchemeForPlatform(platform, config)) {\n      return true;\n    }\n\n    return RESERVED_WEB_SCHEMES.includes(scheme) && RESERVED_WEB_SCHEMES.includes(config.scheme);\n  } catch {\n    return false;\n  }\n}\n\n/** Returns true when the input is a non-empty relative bundled asset path. */\nexport function isRelativeBundledPath(url: string): boolean {\n  const trimmed = url.trim();\n  if (!trimmed) {\n    return false;\n  }\n\n  return !isAbsoluteUrl(trimmed);\n}\n\nfunction rewriteBundledLocalUrl(\n  url: string,\n  localConfig: BundledAssetLocalConfig,\n  navigationScheme: string,\n): string | null {\n  try {\n    const parsed = new URL(url);\n    const host = parsed.hostname.toLowerCase();\n    const scheme = parsed.protocol.replace(/:$/, '').toLowerCase();\n\n    if (host !== localConfig.host || scheme === navigationScheme) {\n      return null;\n    }\n\n    const pathname = parsed.pathname || '/';\n    const search = parsed.search;\n    const hash = parsed.hash;\n    const userinfo =\n      parsed.username.length > 0 ? `${parsed.username}${parsed.password.length > 0 ? `:${parsed.password}` : ''}@` : '';\n    return `${navigationScheme}://${userinfo}${host}${pathname}${search}${hash}`;\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Resolves a bundled asset URL for the given platform.\n * Relative paths become platform-local URLs; bundled local URLs may be rewritten to the handler scheme.\n */\nexport function resolveBundledAssetUrl(\n  url: string,\n  platform: BundledAssetPlatform,\n  localConfig?: BundledAssetLocalConfig | null,\n): BundledAssetResolution | null {\n  const trimmed = url.trim();\n  const config = localConfig ?? BUNDLED_ASSET_DEFAULTS[platform];\n  const navigationScheme = handlerSchemeForPlatform(platform, config);\n\n  if (isRelativeBundledPath(trimmed)) {\n    const path = normalizeBundledPath(trimmed);\n    if (path === null) {\n      return null;\n    }\n    return {\n      url: `${navigationScheme}://${config.host}${path}`,\n    };\n  }\n\n  if (isBundledLocalUrl(trimmed, platform, config)) {\n    const rewritten = rewriteBundledLocalUrl(trimmed, config, navigationScheme);\n    return {\n      url: rewritten ?? trimmed,\n    };\n  }\n\n  return {\n    url: trimmed,\n  };\n}\n\n/**\n * Resolves relative bundled paths for legacy native plugins that do not perform native resolution.\n * Throws when the path is invalid.\n */\nexport function resolveLegacyNativeWebViewUrl(\n  url: string,\n  platform: BundledAssetPlatform,\n  localConfig?: BundledAssetLocalConfig | null,\n): string {\n  if (!isRelativeBundledPath(url)) {\n    return url;\n  }\n\n  const resolution = resolveBundledAssetUrl(url, platform, localConfig);\n  if (resolution === null) {\n    throw new Error('Invalid bundled asset path');\n  }\n\n  return resolution.url;\n}\n"]}

package/dist/esm/definitions.d.ts

@@ -419,7 +419,12 @@ export type ProxyHandler = (request: ProxyRequest) => ProxyHandlerResult | Promi
 export interface OpenOptions {
     /**
      * Target URL to load.
+     *
+     * Remote `http://` and `https://` URLs are loaded as-is. Relative bundled paths
+     * such as `/index.html` are not supported; use `openWebView()` instead.
+     *
      * @since 0.1.0
+     * @example "https://capgo.app"
      */
     url: string;
     /**
@@ -595,8 +600,20 @@ export interface CloseWebviewOptions {
 export interface OpenWebViewOptions {
     /**
      * Target URL to load.
+     *
+     * Remote `http://` and `https://` URLs are loaded as-is.
+     *
+     * To open bundled web assets from the app bundle without running a local HTTP server,
+     * pass a relative path such as `/index.html` or `assets/page.html`. The plugin resolves it to
+     * the Capacitor local URL for the current platform (defaults: `capacitor://localhost/...` on iOS,
+     * `https://localhost/...` on Android; actual scheme and host follow the app's configured Capacitor
+     * local URL) and serves files from the packaged `public/` directory, or `www/` on iOS when `public/`
+     * is absent.
+     *
      * @since 0.1.0
+     * @since 8.15.0 Relative bundled paths (`/index.html`, `assets/page.html`) are supported.
      * @example "https://capgo.app"
+     * @example "/index.html"
      */
     url: string;
     /**
@@ -1200,8 +1217,9 @@ export interface OpenWebViewOptions {
      */
     authorizedAppLinks?: string[];
     /**
-     * If true, the webView will not take the full height and will have a 20px margin at the bottom.
-     * This creates a safe margin area outside the browser view.
+     * If true, the webView is inset by the bottom system bar (navigation bar) so bottom-anchored
+     * content stays reachable. On Android 15+ the browser window is always edge-to-edge, so the
+     * bottom inset is applied there regardless of this option.
      * @since 7.13.0
      * @default false
      * @example
@@ -1212,6 +1230,8 @@ export interface OpenWebViewOptions {
      * If false, the webView will extend behind the status bar for true full-screen immersive content.
      * When true (default), respects the safe area at the top of the screen.
      * Works independently of toolbarType - use for full-screen video players, games, or immersive web apps.
+     * On Android, when a toolbar is visible the toolbar itself provides that safe area; with
+     * `toolbarType: 'blank'` on Android 15+ the status bar inset is applied to the webView instead.
      * @since 8.2.0
      * @default true
      * @example
@@ -1219,8 +1239,10 @@ export interface OpenWebViewOptions {
      */
     enabledSafeTopMargin?: boolean;
     /**
-     * When true, applies the system status bar inset as the WebView top margin on Android.
-     * Keeps the legacy 0px margin by default for apps that handle padding themselves.
+     * When true, applies the system status bar inset to the top of the WebView on Android even when
+     * the window is not edge-to-edge (before Android 15). Keeps the legacy 0px inset by default for
+     * apps that handle padding themselves. On Android 15+ this is not needed: without a visible
+     * toolbar the status bar inset already follows `enabledSafeTopMargin`.
      * @default false
      * @example
      * useTopInset: true