@alien_org/react 0.2.2 → 0.2.4

package/dist/index.cjs

@@ -6,6 +6,17 @@ let react_jsx_runtime = require("react/jsx-runtime");
 //#region src/context.tsx
 const useIsomorphicLayoutEffect$1 = typeof window !== "undefined" ? react.useLayoutEffect : react.useEffect;
 const AlienContext = (0, react.createContext)(null);
+const SAFE_AREA_EDGES = [
+	"top",
+	"right",
+	"bottom",
+	"left"
+];
+function setSafeAreaCssVars(insets) {
+	if (typeof document === "undefined") return;
+	const root = document.documentElement;
+	for (const edge of SAFE_AREA_EDGES) root.style.setProperty(`--alien-safe-area-inset-${edge}`, `${insets?.[edge] ?? 0}px`);
+}
 /**
 * Provider component that initializes the Alien miniapp context.
 * Must wrap your app to use Alien hooks.
@@ -23,7 +34,7 @@ const AlienContext = (0, react.createContext)(null);
 * }
 * ```
 */
-function AlienProvider({ children, autoReady = true }) {
+function AlienProvider({ children, autoReady = true, interceptLinks = true }) {
 	const readySent = (0, react.useRef)(false);
 	const ready = (0, react.useCallback)(() => {
 		if (readySent.current) return;
@@ -45,11 +56,15 @@ function AlienProvider({ children, autoReady = true }) {
 			isBridgeAvailable: bridgeAvailable,
 			ready
 		});
+		setSafeAreaCssVars(launchParams?.safeAreaInsets);
 		if (!bridgeAvailable) console.warn("[@alien_org/react] Bridge is not available. Running in dev mode? The SDK will handle errors gracefully, but bridge communication will not work.");
 	}, [ready]);
 	(0, react.useEffect)(() => {
 		if (autoReady) ready();
 	}, [autoReady, ready]);
+	(0, react.useEffect)(() => {
+		if (interceptLinks) return (0, _alien_org_bridge.enableLinkInterceptor)();
+	}, [interceptLinks]);
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(AlienContext.Provider, {
 		value,
 		children
@@ -293,6 +308,29 @@ function useLaunchParams() {
 	return params;
 }
 
+//#endregion
+//#region src/hooks/useLinkInterceptor.ts
+/**
+* Intercepts external link clicks and routes them through the bridge.
+* Activates when the bridge is available, cleans up on unmount.
+*
+* @example
+* ```tsx
+* function App() {
+*   useLinkInterceptor();
+*   return <a href="https://external.com">Opens via host app</a>;
+* }
+* ```
+*/
+function useLinkInterceptor(options = {}) {
+	const { isBridgeAvailable: isBridgeAvailable$1 } = useAlien();
+	const { openMode } = options;
+	(0, react.useEffect)(() => {
+		if (!isBridgeAvailable$1) return;
+		return (0, _alien_org_bridge.enableLinkInterceptor)({ openMode });
+	}, [isBridgeAvailable$1, openMode]);
+}
+
 //#endregion
 //#region src/hooks/useMethod.ts
 /**
@@ -639,5 +677,6 @@ exports.useClipboard = useClipboard;
 exports.useEvent = useEvent;
 exports.useIsMethodSupported = useIsMethodSupported;
 exports.useLaunchParams = useLaunchParams;
+exports.useLinkInterceptor = useLinkInterceptor;
 exports.useMethod = useMethod;
 exports.usePayment = usePayment;

package/dist/index.d.cts

@@ -178,6 +178,16 @@ declare const PLATFORMS: readonly ["ios", "android"];
  * Platform the miniapp is running on.
  */
 type Platform = (typeof PLATFORMS)[number];
+/**
+ * Safe area insets in CSS pixels, injected by the host app.
+ * Accounts for system UI (status bar, notch, home indicator, nav bar).
+ */
+interface SafeAreaInsets {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+}
 /**
  * Launch parameters injected by the host app.
  */
@@ -190,6 +200,8 @@ interface LaunchParams {
   hostAppVersion: string | undefined;
   /** Platform the miniapp is running on */
   platform: Platform | undefined;
+  /** Safe area insets for the webview in CSS pixels */
+  safeAreaInsets: SafeAreaInsets | undefined;
   /**
    * Custom start parameter injected by host app.
    * Used for referral codes, campaign tracking, or custom routing.
@@ -470,6 +482,7 @@ declare global {
     __ALIEN_CONTRACT_VERSION__?: string;
     __ALIEN_HOST_VERSION__?: string;
     __ALIEN_PLATFORM__?: string;
+    __ALIEN_SAFE_AREA_INSETS__?: SafeAreaInsets;
     __ALIEN_START_PARAM__?: string;
   }
 }
@@ -477,6 +490,17 @@ declare global {
  * Error thrown when launch params cannot be retrieved.
  */
 //#endregion
+//#region ../bridge/src/link-interceptor.d.ts
+interface LinkInterceptorOptions {
+  /**
+   * Where to open intercepted links.
+   * - `external` (default): System browser or app handler
+   * - `internal`: Within the host app
+   * @default 'external'
+   */
+  openMode?: 'external' | 'internal';
+}
+//#endregion
 //#region ../bridge/src/request.d.ts
 interface RequestOptions {
   reqId?: string;
@@ -565,6 +589,12 @@ interface AlienProviderProps {
    * ```
    */
   autoReady?: boolean;
+  /**
+   * Whether to intercept external link clicks and route them through the
+   * bridge's `link:open` method. Same-origin links are unaffected.
+   * @default true
+   */
+  interceptLinks?: boolean;
 }
 /**
  * Provider component that initializes the Alien miniapp context.
@@ -585,7 +615,8 @@ interface AlienProviderProps {
  */
 declare function AlienProvider({
   children,
-  autoReady
+  autoReady,
+  interceptLinks
 }: AlienProviderProps): ReactNode;
 //#endregion
 //#region src/errors.d.ts
@@ -763,6 +794,21 @@ declare function useIsMethodSupported(method: MethodName): MethodSupportResult;
  */
 declare function useLaunchParams(): LaunchParams | undefined;
 //#endregion
+//#region src/hooks/useLinkInterceptor.d.ts
+/**
+ * Intercepts external link clicks and routes them through the bridge.
+ * Activates when the bridge is available, cleans up on unmount.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   useLinkInterceptor();
+ *   return <a href="https://external.com">Opens via host app</a>;
+ * }
+ * ```
+ */
+declare function useLinkInterceptor(options?: LinkInterceptorOptions): void;
+//#endregion
 //#region src/hooks/useMethod.d.ts
 interface UseMethodExecuteResult<E extends EventName> {
   data: EventPayload<E> | undefined;
@@ -955,4 +1001,4 @@ interface UsePaymentReturn {
  */
 declare function usePayment(options?: UsePaymentOptions): UsePaymentReturn;
 //#endregion
-export { AlienProvider, type AlienProviderProps, BridgeError, BridgeTimeoutError, BridgeUnavailableError, BridgeWindowUnavailableError, type ClipboardErrorCode, type EventName, type EventPayload, type MethodName, MethodNotSupportedError, type MethodPayload, type MethodSupportResult, type PaymentCallbacks, type PaymentErrorCode, type PaymentParams, type PaymentResponseStatus, type PaymentResult, type PaymentStatus, ReactSDKError, type RequestOptions, type UseClipboardOptions, type UseClipboardReturn, type UseMethodExecuteResult, type UseMethodOptions, type UsePaymentOptions, type UsePaymentReturn, type Version, getMethodMinVersion, isMethodSupported, send, useAlien, useClipboard, useEvent, useIsMethodSupported, useLaunchParams, useMethod, usePayment };
+export { AlienProvider, type AlienProviderProps, BridgeError, BridgeTimeoutError, BridgeUnavailableError, BridgeWindowUnavailableError, type ClipboardErrorCode, type EventName, type EventPayload, type LinkInterceptorOptions, type MethodName, MethodNotSupportedError, type MethodPayload, type MethodSupportResult, type PaymentCallbacks, type PaymentErrorCode, type PaymentParams, type PaymentResponseStatus, type PaymentResult, type PaymentStatus, ReactSDKError, type RequestOptions, type UseClipboardOptions, type UseClipboardReturn, type UseMethodExecuteResult, type UseMethodOptions, type UsePaymentOptions, type UsePaymentReturn, type Version, getMethodMinVersion, isMethodSupported, send, useAlien, useClipboard, useEvent, useIsMethodSupported, useLaunchParams, useLinkInterceptor, useMethod, usePayment };

package/dist/index.d.mts

@@ -178,6 +178,16 @@ declare const PLATFORMS: readonly ["ios", "android"];
  * Platform the miniapp is running on.
  */
 type Platform = (typeof PLATFORMS)[number];
+/**
+ * Safe area insets in CSS pixels, injected by the host app.
+ * Accounts for system UI (status bar, notch, home indicator, nav bar).
+ */
+interface SafeAreaInsets {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+}
 /**
  * Launch parameters injected by the host app.
  */
@@ -190,6 +200,8 @@ interface LaunchParams {
   hostAppVersion: string | undefined;
   /** Platform the miniapp is running on */
   platform: Platform | undefined;
+  /** Safe area insets for the webview in CSS pixels */
+  safeAreaInsets: SafeAreaInsets | undefined;
   /**
    * Custom start parameter injected by host app.
    * Used for referral codes, campaign tracking, or custom routing.
@@ -470,6 +482,7 @@ declare global {
     __ALIEN_CONTRACT_VERSION__?: string;
     __ALIEN_HOST_VERSION__?: string;
     __ALIEN_PLATFORM__?: string;
+    __ALIEN_SAFE_AREA_INSETS__?: SafeAreaInsets;
     __ALIEN_START_PARAM__?: string;
   }
 }
@@ -477,6 +490,17 @@ declare global {
  * Error thrown when launch params cannot be retrieved.
  */
 //#endregion
+//#region ../bridge/src/link-interceptor.d.ts
+interface LinkInterceptorOptions {
+  /**
+   * Where to open intercepted links.
+   * - `external` (default): System browser or app handler
+   * - `internal`: Within the host app
+   * @default 'external'
+   */
+  openMode?: 'external' | 'internal';
+}
+//#endregion
 //#region ../bridge/src/request.d.ts
 interface RequestOptions {
   reqId?: string;
@@ -565,6 +589,12 @@ interface AlienProviderProps {
    * ```
    */
   autoReady?: boolean;
+  /**
+   * Whether to intercept external link clicks and route them through the
+   * bridge's `link:open` method. Same-origin links are unaffected.
+   * @default true
+   */
+  interceptLinks?: boolean;
 }
 /**
  * Provider component that initializes the Alien miniapp context.
@@ -585,7 +615,8 @@ interface AlienProviderProps {
  */
 declare function AlienProvider({
   children,
-  autoReady
+  autoReady,
+  interceptLinks
 }: AlienProviderProps): ReactNode;
 //#endregion
 //#region src/errors.d.ts
@@ -763,6 +794,21 @@ declare function useIsMethodSupported(method: MethodName): MethodSupportResult;
  */
 declare function useLaunchParams(): LaunchParams | undefined;
 //#endregion
+//#region src/hooks/useLinkInterceptor.d.ts
+/**
+ * Intercepts external link clicks and routes them through the bridge.
+ * Activates when the bridge is available, cleans up on unmount.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   useLinkInterceptor();
+ *   return <a href="https://external.com">Opens via host app</a>;
+ * }
+ * ```
+ */
+declare function useLinkInterceptor(options?: LinkInterceptorOptions): void;
+//#endregion
 //#region src/hooks/useMethod.d.ts
 interface UseMethodExecuteResult<E extends EventName> {
   data: EventPayload<E> | undefined;
@@ -955,4 +1001,4 @@ interface UsePaymentReturn {
  */
 declare function usePayment(options?: UsePaymentOptions): UsePaymentReturn;
 //#endregion
-export { AlienProvider, type AlienProviderProps, BridgeError, BridgeTimeoutError, BridgeUnavailableError, BridgeWindowUnavailableError, type ClipboardErrorCode, type EventName, type EventPayload, type MethodName, MethodNotSupportedError, type MethodPayload, type MethodSupportResult, type PaymentCallbacks, type PaymentErrorCode, type PaymentParams, type PaymentResponseStatus, type PaymentResult, type PaymentStatus, ReactSDKError, type RequestOptions, type UseClipboardOptions, type UseClipboardReturn, type UseMethodExecuteResult, type UseMethodOptions, type UsePaymentOptions, type UsePaymentReturn, type Version, getMethodMinVersion, isMethodSupported, send, useAlien, useClipboard, useEvent, useIsMethodSupported, useLaunchParams, useMethod, usePayment };
+export { AlienProvider, type AlienProviderProps, BridgeError, BridgeTimeoutError, BridgeUnavailableError, BridgeWindowUnavailableError, type ClipboardErrorCode, type EventName, type EventPayload, type LinkInterceptorOptions, type MethodName, MethodNotSupportedError, type MethodPayload, type MethodSupportResult, type PaymentCallbacks, type PaymentErrorCode, type PaymentParams, type PaymentResponseStatus, type PaymentResult, type PaymentStatus, ReactSDKError, type RequestOptions, type UseClipboardOptions, type UseClipboardReturn, type UseMethodExecuteResult, type UseMethodOptions, type UsePaymentOptions, type UsePaymentReturn, type Version, getMethodMinVersion, isMethodSupported, send, useAlien, useClipboard, useEvent, useIsMethodSupported, useLaunchParams, useLinkInterceptor, useMethod, usePayment };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { BridgeError, BridgeTimeoutError, BridgeUnavailableError, BridgeWindowUnavailableError, getLaunchParams, isBridgeAvailable, on, request, send, send as send$1 } from "@alien_org/bridge";
+import { BridgeError, BridgeTimeoutError, BridgeUnavailableError, BridgeWindowUnavailableError, enableLinkInterceptor, getLaunchParams, isBridgeAvailable, on, request, send, send as send$1 } from "@alien_org/bridge";
 import { getMethodMinVersion, getMethodMinVersion as getMethodMinVersion$1, isMethodSupported, isMethodSupported as isMethodSupported$1 } from "@alien_org/contract";
 import { createContext, useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
 import { jsx } from "react/jsx-runtime";
@@ -6,6 +6,17 @@ import { jsx } from "react/jsx-runtime";
 //#region src/context.tsx
 const useIsomorphicLayoutEffect$1 = typeof window !== "undefined" ? useLayoutEffect : useEffect;
 const AlienContext = createContext(null);
+const SAFE_AREA_EDGES = [
+	"top",
+	"right",
+	"bottom",
+	"left"
+];
+function setSafeAreaCssVars(insets) {
+	if (typeof document === "undefined") return;
+	const root = document.documentElement;
+	for (const edge of SAFE_AREA_EDGES) root.style.setProperty(`--alien-safe-area-inset-${edge}`, `${insets?.[edge] ?? 0}px`);
+}
 /**
 * Provider component that initializes the Alien miniapp context.
 * Must wrap your app to use Alien hooks.
@@ -23,7 +34,7 @@ const AlienContext = createContext(null);
 * }
 * ```
 */
-function AlienProvider({ children, autoReady = true }) {
+function AlienProvider({ children, autoReady = true, interceptLinks = true }) {
 	const readySent = useRef(false);
 	const ready = useCallback(() => {
 		if (readySent.current) return;
@@ -45,11 +56,15 @@ function AlienProvider({ children, autoReady = true }) {
 			isBridgeAvailable: bridgeAvailable,
 			ready
 		});
+		setSafeAreaCssVars(launchParams?.safeAreaInsets);
 		if (!bridgeAvailable) console.warn("[@alien_org/react] Bridge is not available. Running in dev mode? The SDK will handle errors gracefully, but bridge communication will not work.");
 	}, [ready]);
 	useEffect(() => {
 		if (autoReady) ready();
 	}, [autoReady, ready]);
+	useEffect(() => {
+		if (interceptLinks) return enableLinkInterceptor();
+	}, [interceptLinks]);
 	return /* @__PURE__ */ jsx(AlienContext.Provider, {
 		value,
 		children
@@ -293,6 +308,29 @@ function useLaunchParams() {
 	return params;
 }
 
+//#endregion
+//#region src/hooks/useLinkInterceptor.ts
+/**
+* Intercepts external link clicks and routes them through the bridge.
+* Activates when the bridge is available, cleans up on unmount.
+*
+* @example
+* ```tsx
+* function App() {
+*   useLinkInterceptor();
+*   return <a href="https://external.com">Opens via host app</a>;
+* }
+* ```
+*/
+function useLinkInterceptor(options = {}) {
+	const { isBridgeAvailable: isBridgeAvailable$1 } = useAlien();
+	const { openMode } = options;
+	useEffect(() => {
+		if (!isBridgeAvailable$1) return;
+		return enableLinkInterceptor({ openMode });
+	}, [isBridgeAvailable$1, openMode]);
+}
+
 //#endregion
 //#region src/hooks/useMethod.ts
 /**
@@ -609,4 +647,4 @@ function usePayment(options = {}) {
 }
 
 //#endregion
-export { AlienProvider, BridgeError, BridgeTimeoutError, BridgeUnavailableError, BridgeWindowUnavailableError, MethodNotSupportedError, ReactSDKError, getMethodMinVersion, isMethodSupported, send, useAlien, useClipboard, useEvent, useIsMethodSupported, useLaunchParams, useMethod, usePayment };
+export { AlienProvider, BridgeError, BridgeTimeoutError, BridgeUnavailableError, BridgeWindowUnavailableError, MethodNotSupportedError, ReactSDKError, getMethodMinVersion, isMethodSupported, send, useAlien, useClipboard, useEvent, useIsMethodSupported, useLaunchParams, useLinkInterceptor, useMethod, usePayment };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alien_org/react",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
@@ -34,8 +34,8 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@alien_org/bridge": "0.2.1",
-    "@alien_org/contract": "0.2.1"
+    "@alien_org/bridge": "0.2.3",
+    "@alien_org/contract": "0.2.2"
   },
   "peerDependencies": {
     "react": "^18 || ^19",