@digia-engage/core 1.1.0 → 2.0.0-rc.1

package/README.md

@@ -1,203 +1,133 @@
-# @digia/engage-react-native
+# @digia-engage/core
 
-React Native bridge for the **Digia Engage SDK** – renders native Android
-Jetpack Compose UI (dialogs, bottom-sheets) inside React Native applications.
+React Native SDK for **Digia Engage** – renders native Android (Jetpack Compose) and iOS campaign UI (bottom sheets, dialogs, inline banners, tooltips, spotlights) inside React Native applications.
 
 > **Platform support**
 > | Platform | Status |
 > |---|---|
 > | Android | ✅ Full support |
-> | iOS | 🚧 Stub (no-op – coming soon) |
-
----
-
-## How it works
-
-The Digia Engage Android SDK is built entirely with Jetpack Compose. In a
-pure-Android app you wrap your content with the `DigiaHost { }` composable; it
-then manages campaign-driven overlays (dialogs, bottom sheets) on top of your
-content.
-
-In a React Native app we cannot embed a Composable directly in the JS tree, so
-the bridge uses two complementary mechanisms:
-
-```
-┌─────────────────────────────────────────┐
-│  Android Activity (ReactActivity)       │
-│                                         │
-│  ┌─────────────────────────────────┐    │
-│  │  Android content FrameLayout    │    │
-│  │                                 │    │
-│  │  ┌─────────────────────────┐    │    │
-│  │  │  React Native RootView  │    │    │
-│  │  │  (your JS UI)           │    │    │
-│  │  └─────────────────────────┘    │    │
-│  │                                 │    │
-│  │  ┌─────────────────────────┐    │    │
-│  │  │  DigiaHostComposeView   │    │    │
-│  │  │  (AbstractComposeView)  │    │    │
-│  │  │  hosts DigiaHost { }   │    │    │
-│  │  │  ← transparent, no     │    │    │
-│  │  │    touch interception  │    │    │
-│  │  └─────────────────────────┘    │    │
-│  └─────────────────────────────────┘    │
-│                                         │
-│  ┌──────────────────────────────────┐   │
-│  │  Compose Dialog window (overlay) │   │
-│  │  Triggered by CEP campaign       │   │
-│  └──────────────────────────────────┘   │
-└─────────────────────────────────────────┘
-```
-
-1. **`Digia.initialize()`** initialises the SDK and calls `addContentView()`
-   to attach a transparent `DigiaHostComposeView` on top of the React Native
-   view hierarchy.  This is the anchor for the Compose composition.
-
-2. **`DigiaHost { }`** inside the `ComposeView` manages `DialogManager` and
-   `BottomSheetManager`.  When a CEP plugin triggers a campaign, Compose
-   renders a `Dialog` or `ModalBottomSheet` – these are **separate Android
-   windows** that appear on top of everything, including React Native content.
-
-3. **`<DigiaHostView>`** is an optional React Native component you can place in
-   your component tree (e.g. as `StyleSheet.absoluteFill`) if you prefer a
-   declarative, component-based mount point instead of the auto-mount.
-
----
-
-## Installation
+> | iOS | ✅ Guide overlays (JS renderer); native bridge (surveys, inline) |
 
 ```sh
-# npm
-npm install @digia/engage-react-native
-
-# yarn
-yarn add @digia/engage-react-native
+npm install @digia-engage/core
 ```
 
-React Native CLI auto-linking handles the rest.  Rebuild the native app:
+React Native CLI auto-linking handles the rest. Rebuild the native app after installing:
 
 ```sh
-npx react-native build-android
+npx react-native run-android
 # or
 cd android && ./gradlew assembleDebug
 ```
 
-### Android – host app dependencies
+### Android – host app dependency
 
-Your app's `android/app/build.gradle` must declare the Digia Engage AAR
-(or include it via your local Maven / private registry):
+Add the Digia Engage Android SDK to `android/app/build.gradle.kts`:
 
-```groovy
+```kotlin
 dependencies {
-    implementation 'com.digia:digia-ui:1.0.0'
+    implementation("tech.digia:engage:2.0.0-rc.1")
 }
 ```
 
-If you are working inside the monorepo and building locally, add the `:digia-ui`
-project instead:
+---
 
-```groovy
-implementation(project(':digia-ui'))
-```
+## Usage
 
-### iOS
+### 1 — Initialize the SDK
 
-iOS is a no-op stub.  All methods resolve immediately without error.
+Call `Digia.initialize()` once, as early as possible (top of `App.tsx`):
 
----
+```tsx
+import { Digia } from '@digia-engage/core';
 
-## Usage
+await Digia.initialize({
+  projectId: 'digia_YOUR_PROJECT_ID',
+  environment: 'production', // or 'sandbox'
+  logLevel: 'error',
+});
+```
 
-### 1 – Initialise the SDK
+### 2 — Mount `<DigiaHost />`
 
-Call `Digia.initialize()` once, as early as possible (e.g. the top of
-`App.tsx`):
+Place `<DigiaHost />` at the root of your component tree. It renders the JS-side guide/tooltip/spotlight overlays via a `Modal`.
 
 ```tsx
-import React, { useEffect } from 'react';
-import { NavigationContainer } from '@react-navigation/native';
-import { Digia } from '@digia/engage-react-native';
-
-export default function App() {
-  useEffect(() => {
-    Digia.initialize({
-      apiKey: 'YOUR_DIGIA_API_KEY',
-      environment: 'production', // or 'sandbox'
-      logLevel: 'error',
-    });
-  }, []);
-
-  return <NavigationContainer>{/* … */}</NavigationContainer>;
+// app/_layout.tsx (Expo Router) or App.tsx
+import { DigiaHost } from '@digia-engage/core';
+
+export default function RootLayout() {
+  return (
+    <>
+      <Stack />
+      <DigiaHost />
+    </>
+  );
 }
 ```
 
-`initialize()` returns a `Promise<void>` and automatically attaches the Compose
-overlay host to the Activity.  You do **not** need to add `<DigiaHostView>`
-unless you want an explicit component-based mount point.
-
-### 2 – Track screen changes
-
-Wire `setCurrentScreen()` to your navigation state so the SDK can trigger
-campaigns based on the active screen:
+### 3 — Track screen changes
 
 ```tsx
-import { useNavigationContainerRef } from '@react-navigation/native';
-import { Digia } from '@digia/engage-react-native';
-
-// Inside your App component:
-const navRef = useNavigationContainerRef();
+import { Digia } from '@digia-engage/core';
 
 <NavigationContainer
-  ref={navRef}
   onStateChange={() => {
-    const currentRoute = navRef.getCurrentRoute();
-    if (currentRoute) {
-      Digia.setCurrentScreen(currentRoute.name);
-    }
+    const route = navRef.getCurrentRoute();
+    if (route) Digia.setCurrentScreen(route.name);
   }}
 >
 ```
 
-### 3 – Open the Digia UI navigation flow
+### 4 — Register anchors for guide campaigns
 
-Launch the full-screen native SDUI stack:
+Wrap any UI element you want a tooltip or spotlight to point at:
 
 ```tsx
-import { Digia } from '@digia/engage-react-native';
+import { DigiaAnchorView } from '@digia-engage/core';
 
-function MyScreen() {
-  return (
-    <Button
-      title="Open Digia Experience"
-      onPress={() => Digia.createInitialPage()}
-    />
-  );
-}
+<DigiaAnchorView anchorKey="home_banner_btn">
+  <Button title="Banner" />
+</DigiaAnchorView>
 ```
 
-### 4 – (Optional) Declarative overlay mount via `<DigiaHostView>`
+### 5 — Add slots for inline campaigns
+
+```tsx
+import { DigiaSlotView } from '@digia-engage/core';
+
+// Auto-sizes to native content height
+<DigiaSlotView placementKey="home_banner" />
+```
 
-If you prefer an explicit React component instead of the auto-mount, skip the
-`initialize()` auto-mount and place `<DigiaHostView>` at the root of your
-component tree:
+### 6 — Register a CEP plugin
 
 ```tsx
-import React from 'react';
-import { StyleSheet, View } from 'react-native';
-import { DigiaHostView } from '@digia/engage-react-native';
+import { DigiaCleverTapPlugin, createCleverTapClient } from '@digia-engage/clevertap';
+import CleverTap from 'clevertap-react-native';
 
-export default function App() {
-  return (
-    <View style={styles.root}>
-      {/* DigiaHostView must be above all other content in z-order */}
-      <DigiaHostView style={StyleSheet.absoluteFill} />
+Digia.register(new DigiaCleverTapPlugin({
+  cleverTap: createCleverTapClient(CleverTap),
+}));
+```
 
-      {/* Your navigation / content here */}
-    </View>
-  );
-}
+### 7 — (Optional) Handle actions
+
+Override or observe every action the SDK fires:
 
-const styles = StyleSheet.create({ root: { flex: 1 } });
+```tsx
+await Digia.initialize({
+  projectId: '...',
+  onAction: (action, context) => {
+    if (action.type === 'deep_link') {
+      // return true to suppress SDK default; false/void to let SDK handle it
+    }
+  },
+  linking: {
+    routeViaSystemLinking: true,
+    inAppBrowser: defaultInAppBrowser, // requires react-native-inappbrowser-reborn
+  },
+});
 ```
 
 ---
@@ -208,57 +138,97 @@ const styles = StyleSheet.create({ root: { flex: 1 } });
 
 | Method | Signature | Description |
 |---|---|---|
-| `initialize` | `(config: DigiaConfig) => Promise<void>` | Initialise the SDK and mount the Compose overlay host. |
-| `setCurrentScreen` | `(name: string) => void` | Notify the SDK of the current screen. |
-| `createInitialPage` | `() => void` | Full-screen Digia SDUI (Android: `DigiaUINavigationActivity`; iOS: modal `DigiaNavigationView`). |
+| `initialize` | `(config: DigiaConfig) => Promise<void>` | Initialize the SDK. Call once before anything else. |
+| `register` | `(plugin: DigiaPlugin) => void` | Register a CEP plugin (CleverTap, MoEngage, etc.). |
+| `unregister` | `(plugin: DigiaPlugin \| string) => void` | Remove a previously registered plugin. |
+| `setCurrentScreen` | `(name: string) => void` | Notify the SDK of the active screen. |
+| `registerAnchor` | `(key: string, screen?: string) => void` | Manually register an anchor key. |
+| `unregisterAnchor` | `(key: string) => void` | Remove an anchor registration. |
 
 ### `DigiaConfig`
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `apiKey` | `string` | — | **Required.** Your Digia project API key. |
+| `projectId` | `string` | — | **Required.** Your Digia project ID (format: `digia_…`). Sent as `x-digia-project-id` on all SDK requests. |
 | `environment` | `'production' \| 'sandbox'` | `'production'` | Target environment. |
 | `logLevel` | `'none' \| 'error' \| 'verbose'` | `'error'` | Log verbosity. |
+| `onAction` | `OnAction` | — | Override hook for all actions. Return `true` to suppress SDK default. |
+| `linking.routeViaSystemLinking` | `boolean` | `true` | Use `Linking.openURL` for URL actions. |
+| `linking.inAppBrowser` | `InAppBrowserAdapter` | — | Required for `open_url` with `presentation: 'in_app'`. |
+| `baseUrl` | `string` | — | Override the Digia API base URL. |
 
-### `CreateInitialPageOptions`
+### `<DigiaHost />`
 
-Empty interface — reserved for future optional arguments.
+No props. Renders the JS guide overlay runtime (`TooltipOverlay`, `SpotlightOverlay`).
+Place it once, anywhere in the root view — `Modal` handles z-ordering.
 
-### `<DigiaHostView>`
+### `<DigiaAnchorView>`
 
-A transparent React Native view that hosts the Compose overlay anchor.
+| Prop | Type | Description |
+|---|---|---|
+| `anchorKey` | `string` | **Required.** Must match the step's `anchorKey` in the campaign config. |
+| `...ViewProps` | — | All standard React Native `View` props are forwarded. |
+
+### `<DigiaSlotView>`
+
+Renders inline campaign content (banners, cards) at a named placement. Collapses to zero height when no campaign is active for the slot.
 
 | Prop | Type | Description |
 |---|---|---|
-| `style` | `ViewStyle?` | Custom style (defaults to `absoluteFill` behaviour). |
+| `placementKey` | `string` | **Required.** Must match the campaign's `slotKey`. |
+| `style` | `ViewStyle?` | Pass an explicit `height` to fix size; otherwise auto-sizes. |
+
+### `<DigiaHostView>`
+
+Low-level transparent native overlay view (Android/iOS). Use `<DigiaHost />` instead
+unless you need the native Compose/SwiftUI overlay host explicitly.
+
+---
+
+## Campaign types
+
+| Type | Trigger | JS or Native |
+|---|---|---|
+| `guide` (tooltip) | `DigiaGuideController` → `DigiaHost` | **JS** — `TooltipOverlay` via `Modal` |
+| `guide` (spotlight) | `DigiaGuideController` → `DigiaHost` | **JS** — `SpotlightOverlay` via `Modal` |
+| `inline` | `nativeDigiaModule.triggerCampaign()` | **Native** — Android Compose `VWCarousel` |
+| `survey` | `nativeDigiaModule.triggerCampaign()` | **Native** — Android Compose `SurveyRenderer` |
+| `nudge` | `nativeDigiaModule.triggerCampaign()` | **Native** — Android Compose dialog / bottom-sheet |
 
 ---
 
-## Architecture overview
+## Architecture
 
 ```
-react-native/
-├── src/
-│   ├── index.ts                  ← Public API exports
-│   ├── types.ts                  ← TypeScript interfaces
-│   ├── Digia.ts                  ← High-level JS SDK wrapper
-│   ├── NativeDigiaEngage.ts      ← Low-level native module binding
-│   └── DigiaHostView.tsx         ← <DigiaHostView> React component
-│
-├── android/
-│   ├── build.gradle              ← Android library build config
-│   └── src/main/java/com/digia/engage/rn/
-│       ├── DigiaPackage.kt       ← ReactPackage (registers module + view)
-│       ├── DigiaModule.kt        ← NativeModule (initialize, setCurrentScreen, createInitialPage)
-│       ├── DigiaViewManager.kt   ← ViewManager for <DigiaHostView>
-│       └── DigiaHostComposeView.kt ← AbstractComposeView hosting DigiaHost { }
-│
-├── ios/
-│   └── DigiaEngageModule.m       ← iOS no-op stub
-│
-├── DigiaEngageReactNative.podspec
-├── react-native.config.js        ← Auto-linking config
-└── package.json
+react-native/src/
+  index.ts                  Public API exports
+  Digia.ts                  SDK singleton — initialize, register, setCurrentScreen,
+                            campaign routing, campaign store (fetched from backend)
+  DigiaProvider.tsx         JS guide renderer — TooltipOverlay + SpotlightOverlay + DigiaHost
+  DigiaGuideController.ts   Event bus for guide start/cancel; queues if DigiaHost not mounted
+  digiaAnchorRegistry.ts    In-memory anchor position store with subscriber pattern
+  DigiaAnchorView.tsx       Wraps UI elements; measures position via ref.measure
+  DigiaSlotView.tsx         Native slot view wrapper; auto-sizes to content height
+  DigiaHostView.tsx         Low-level native overlay host (transparent, pointer-events none)
+  NativeDigiaEngage.ts      Codegen native module spec (TurboModule)
+  actionHandler.ts          Action execution — deep link, open URL, next/prev/dismiss;
+                            onAction override; cold-start queue
+  defaultInAppBrowser.ts    Lazily loads react-native-inappbrowser-reborn
+  templateTypes.ts          TypeScript types for TooltipConfig, SpotlightConfig,
+                            CarouselConfig, SurveyTemplateConfig
+  types.ts                  DigiaConfig, DigiaPlugin, DigiaDelegate, InAppPayload,
+                            DigiaAction, ActionContext, DigiaExperienceEvent
+
+react-native/android/       Android bridge
+  DigiaModule.kt            initialize, registerBridge, triggerCampaign, registerAnchor, …
+  DigiaSlotViewManager.kt   DigiaSlotView native view manager
+  DigiaAnchorViewManager.kt DigiaAnchorView native view manager
+  DigiaViewManager.kt       DigiaHostView native view manager
+
+react-native/ios/           iOS bridge
+  DigiaModule.swift         initialize, registerBridge, triggerCampaign, …
+  DigiaHostViewManager.swift
+  DigiaAnchorViewManager.swift
 ```
 
 ---

package/android/build.gradle

@@ -2,13 +2,13 @@
  * Android Gradle build file for the @digia/engage-react-native library module.
  *
  * This module is a thin bridge layer that:
- *   • Depends on the Digia Engage Android AAR (digia-ui)
+ *   • Depends on the Digia Engage Android AAR
  *   • Depends on the React Native SDK
  *   • Exposes a ReactPackage (DigiaPackage) that registers the native module
  *     and native view to React Native's bridge
  *
  * The Compose runtime/tooling dependencies are inherited transitively from
- * the digia-ui AAR via `api` declarations; we only add what is needed for
+ * the Digia Engage AAR via `api` declarations; we only add what is needed for
  * the bridge code itself.
  */
 

package/android/src/main/java/com/digia/engage/rn/DigiaModule.kt

@@ -22,7 +22,6 @@
  */
 package com.digia.engage.rn
 
-import android.widget.FrameLayout
 import androidx.lifecycle.LifecycleOwner
 import androidx.lifecycle.ViewModelStoreOwner
 import androidx.lifecycle.setViewTreeLifecycleOwner
@@ -59,7 +58,14 @@ internal class DigiaModule(
     // ─── initialize ───────────────────────────────────────────────────────────
 
     @ReactMethod
-    fun initialize(apiKey: String, environment: String, logLevel: String, promise: Promise) {
+    fun initialize(
+            apiKey: String,
+            environment: String,
+            logLevel: String,
+            baseUrl: String?,
+            fontFamily: String?,
+            promise: Promise
+    ) {
         try {
             val config =
                     DigiaConfig(
@@ -75,10 +81,18 @@ internal class DigiaModule(
                                         "none" -> DigiaLogLevel.NONE
                                         else -> DigiaLogLevel.ERROR
                                     },
+                            baseUrl = baseUrl?.takeIf { it.isNotBlank() },
+                            fontFamily = fontFamily?.takeIf { it.isNotBlank() },
                     )
             Digia.initialize(reactContext.applicationContext, config)
 
             UiThreadUtil.runOnUiThread {
+                // Mount the Compose overlay ABOVE the ReactRootView via addContentView().
+                // This keeps it outside Fabric's shadow tree entirely so Fabric hit-testing
+                // never sees it. Touch pass-through is handled by DigiaHostView.dispatchTouchEvent
+                // returning false at the native Android level — which works correctly at this
+                // level of the hierarchy, unlike inside Fabric where pointerEvents="none" on
+                // non-ReactViewGroup views is not respected during shadow-tree hit-testing.
                 mountDigiaHost()
                 promise.resolve(null)
             }
@@ -138,13 +152,42 @@ internal class DigiaModule(
         rnPlugin.delegate?.onCampaignInvalidated(campaignId)
     }
 
+    // ─── Anchor registration ──────────────────────────────────────────────────
+
+    @ReactMethod
+    fun registerAnchor(key: String, x: Int, y: Int, width: Int, height: Int) {
+        Digia.registerAnchor(key, x, y, width, height)
+    }
+
+    @ReactMethod
+    fun unregisterAnchor(key: String) {
+        Digia.unregisterAnchor(key)
+    }
+
     // ─── Internal: mount the Compose overlay host ─────────────────────────────
 
     private fun mountDigiaHost() {
-        val activity = reactContext.currentActivity ?: return
+        val activity = reactContext.currentActivity ?: run {
+            android.util.Log.w("DigiaHost", "[mountDigiaHost] no current activity — skipping")
+            return
+        }
 
         val contentRoot = activity.window.decorView.findViewWithTag<DigiaHostView>(DIGIA_HOST_TAG)
-        if (contentRoot != null) return
+        if (contentRoot != null) {
+            android.util.Log.d("DigiaHost", "[mountDigiaHost] already mounted (tag found) — skipping")
+            return
+        }
+
+        android.util.Log.d("DigiaHost", "[mountDigiaHost] mounting native overlay on DecorView")
+
+        // Mount on the DecorView (not content area) so the overlay covers the full screen
+        // including status bar and navigation bar. This also ensures the Compose Popup's
+        // canvas y=0 aligns with the absolute screen y=0, matching getLocationOnScreen()
+        // coordinates used by DigiaAnchorView.
+        val decorView = activity.window.decorView as? android.view.ViewGroup ?: run {
+            android.util.Log.w("DigiaHost", "[mountDigiaHost] decorView not a ViewGroup — skipping")
+            return
+        }
 
         val composeView =
                 DigiaHostView(activity).apply {
@@ -155,13 +198,14 @@ internal class DigiaModule(
                             setViewTreeSavedStateRegistryOwner(activity)
                 }
 
-        activity.addContentView(
+        decorView.addView(
                 composeView,
-                FrameLayout.LayoutParams(
-                        FrameLayout.LayoutParams.MATCH_PARENT,
-                        FrameLayout.LayoutParams.MATCH_PARENT,
+                android.view.ViewGroup.LayoutParams(
+                        android.view.ViewGroup.LayoutParams.MATCH_PARENT,
+                        android.view.ViewGroup.LayoutParams.MATCH_PARENT,
                 ),
         )
+        android.util.Log.d("DigiaHost", "[mountDigiaHost] done — DecorView child count: ${decorView.childCount}")
     }
 
     companion object {

package/android/src/main/java/com/digia/engage/rn/DigiaSlotViewManager.kt

@@ -26,10 +26,14 @@ private class ContentSizeChangeEvent(
     surfaceId: Int,
     viewTag: Int,
     private val heightDp: Double,
+    private val widthDp: Double,
 ) : Event<ContentSizeChangeEvent>(surfaceId, viewTag) {
     override fun getEventName(): String = "onContentSizeChange"
     override fun getEventData(): WritableMap =
-        Arguments.createMap().apply { putDouble("height", heightDp) }
+        Arguments.createMap().apply {
+            putDouble("height", heightDp)
+            putDouble("width", widthDp)
+        }
 }
 
 // ── DigiaSlotContainerView ────────────────────────────────────────────────────
@@ -141,7 +145,7 @@ internal class DigiaSlotContainerView(context: Context) : FrameLayout(context) {
 
         val dispatcher = UIManagerHelper.getEventDispatcherForReactTag(ctx, id) ?: return
         val surfaceId = UIManagerHelper.getSurfaceId(this)
-        dispatcher.dispatchEvent(ContentSizeChangeEvent(surfaceId, id, heightDp.toDouble()))
+        dispatcher.dispatchEvent(ContentSizeChangeEvent(surfaceId, id, heightDp.toDouble(), 0.0))
     }
 
     companion object {

package/android/src/main/java/com/digia/engage/rn/DigiaViewManager.kt

@@ -54,6 +54,7 @@ internal class DigiaViewManager : SimpleViewManager<DigiaHostView>() {
                         FrameLayout.LayoutParams.MATCH_PARENT,
                 )
 
+        android.util.Log.d("DigiaHost", "[DigiaViewManager] RN-side NativeDigiaHostView instance created (id=${view.id})")
         return view
     }
 

package/ios/DigiaEngageModule.m

@@ -22,9 +22,11 @@
 
 @interface RCT_EXTERN_MODULE(DigiaEngageModule, RCTEventEmitter)
 
-RCT_EXTERN_METHOD(initialize:(NSString *)apiKey
+RCT_EXTERN_METHOD(initialize:(NSString *)projectId
                   environment:(NSString *)environment
                   logLevel:(NSString *)logLevel
+                  baseUrl:(NSString *)baseUrl
+                  fontFamily:(NSString *)fontFamily
                   resolve:(RCTPromiseResolveBlock)resolve
                   reject:(RCTPromiseRejectBlock)reject)
 
@@ -62,3 +64,7 @@ RCT_EXPORT_VIEW_PROPERTY(onContentSizeChange, RCTDirectEventBlock)
 @interface RCT_EXTERN_MODULE(DigiaAnchorView, RCTViewManager)
 RCT_EXPORT_VIEW_PROPERTY(anchorKey, NSString)
 @end
+
+@interface RCT_EXTERN_MODULE(DigiaAnchorView, RCTViewManager)
+RCT_EXPORT_VIEW_PROPERTY(anchorKey, NSString)
+@end

package/ios/DigiaHostViewManager.swift

@@ -48,30 +48,27 @@ final class DigiaHostUIView: UIView {
     }
 
     private func mountHostingController() {
-        guard let parentVC = parentViewController() else { return}
+        let parentVC = parentViewController()
 
         let swiftUIView = DigiaHostWrapperView()
         let hc = UIHostingController(rootView: swiftUIView)
         hc.view.translatesAutoresizingMaskIntoConstraints = false
         hc.view.backgroundColor = .clear
 
-        parentVC.addChild(hc)
-        // Mount onto parentVC.view (full-screen) rather than self, because
-        // DigiaHostView is intentionally sized 0×0 in React Native (it takes no
-        // screen space). A zero-size UIHostingController frame prevents SwiftUI
-        // from rendering its body, which means @ObservedObject subscriptions and
-        // .onChange(of:) modifiers are never established — so activePayload
-        // changes are silently dropped and no overlay is ever shown.
-        // Anchoring to parentVC.view guarantees a non-zero frame so SwiftUI's
-        // rendering loop runs and reacts to SDK state changes.
-        parentVC.view.addSubview(hc.view)
-        hc.didMove(toParent: parentVC)
+        if let parentVC { parentVC.addChild(hc) }
+        // Mount onto self rather than parentVC.view. DigiaHostView is given
+        // absoluteFillObject style from JS so self IS full-screen, and SwiftUI
+        // will render normally. Mounting here means hitTest below is the single
+        // control point for touch dispatch — parentVC.view never has a rogue
+        // full-screen sibling that intercepts all RN touches.
+        addSubview(hc.view)
+        if let parentVC { hc.didMove(toParent: parentVC) }
 
         NSLayoutConstraint.activate([
-            hc.view.leadingAnchor.constraint(equalTo: parentVC.view.leadingAnchor),
-            hc.view.trailingAnchor.constraint(equalTo: parentVC.view.trailingAnchor),
-            hc.view.topAnchor.constraint(equalTo: parentVC.view.topAnchor),
-            hc.view.bottomAnchor.constraint(equalTo: parentVC.view.bottomAnchor),
+            hc.view.leadingAnchor.constraint(equalTo: leadingAnchor),
+            hc.view.trailingAnchor.constraint(equalTo: trailingAnchor),
+            hc.view.topAnchor.constraint(equalTo: topAnchor),
+            hc.view.bottomAnchor.constraint(equalTo: bottomAnchor),
         ])
 
         hostingController = hc
@@ -79,11 +76,14 @@ final class DigiaHostUIView: UIView {
 
     // Pass touches through to RN when no overlay is active.
     // When an overlay renders in-host (bottom sheet / dialog inside DigiaHost's ZStack),
-    // SwiftUI's hit test returns the overlay view and we forward that — making the
-    // overlay fully interactive. When nothing is rendered (EmptyView), SwiftUI returns
-    // nil and we return nil, so UIKit falls through to RN content below.
+    // SwiftUI's hit test returns the overlay view — making the overlay interactive.
+    // When nothing is rendered, _UIHostingView.hitTest returns nil or itself; either
+    // way we return nil so UIKit falls through to RN content below.
     override func hitTest(_ point: CGPoint, with event: UIEvent?) -> UIView? {
-        return hostingController?.view.hitTest(point, with: event)
+        guard let hcView = hostingController?.view else { return nil }
+        let hit = hcView.hitTest(point, with: event)
+        if hit == nil || hit === hcView { return nil }
+        return hit
     }
 
     /// Prefer React Native’s `UIView.reactViewController`, then walk `next` from each view’s `.next`.