@coralogix/react-native-plugin 0.10.2 → 0.11.0

package/ios/CxSdk.swift

@@ -189,21 +189,111 @@ class CxSdk: RCTEventEmitter {
     if let targetId = interaction["target_id"] as? String { dictionary["element_id"] = targetId }
     if let innerText = interaction["inner_text"] as? String { dictionary["target_element_inner_text"] = innerText }
     if let direction = interaction["direction"] as? String { dictionary["scroll_direction"] = direction }
+    // Present only when JS resolved masking from the component tree. The native SDK
+    // treats a present value as authoritative and otherwise resolves the coordinates
+    // itself, which is why JS omits the key rather than sending false.
+    if let isMasked = interaction["is_masked"] as? Bool { dictionary["is_masked"] = isMasked }
     if let attributes = interaction["attributes"] as? [String: Any] {
       if let x = attributes["x"] as? Double { dictionary["x"] = x }
       if let y = attributes["y"] as? Double { dictionary["y"] = y }
     }
 
-    let payload = dictionary
+    // The tapped control's view tag, present only when JS could not answer for
+    // itself. It is what lets the walk below see an imperative maskView: that
+    // marks a native view and leaves nothing in the component tree, so JS is
+    // blind to it, while the SDK's own coordinate test cannot tell where the
+    // control begins and ends.
+    let viewTag = interaction["view_tag"] as? NSNumber
+
     DispatchQueue.main.async { [weak self] in
-      guard let rum = self?.coralogixRum else {
+      guard let self = self, let rum = self.coralogixRum else {
         print("[CxSdk] reportUserInteraction called before CoralogixRum is initialized, dropping interaction")
         return
       }
+      var payload = dictionary
+
+      // Already on the main thread, which is where resolving a view and reading
+      // its masking state has to happen.
+      //
+      // Set only when the walk finds a mask; never set to false. An explicit
+      // value is authoritative in the SDK, so a false here would suppress its
+      // coordinate resolution and lose masks the walk cannot see — a masked
+      // overlay that is neither ancestor nor descendant of the control. The SDK
+      // redacts the reported inner text off this flag, so nothing else is needed.
+      //
+      // Descendants count for a click only. A click reports the control's whole
+      // concatenated text, so a masked descendant has to mask the click to keep
+      // the verdict and the text consistent. A scroll reports no text at all, so
+      // the descendant half would buy nothing there and cost plenty: one masked
+      // row anywhere in a list would report every scroll of that list as masked.
+      let isClick = (payload["event_name"] as? String) == "click"
+      if let viewTag = viewTag,
+         payload["is_masked"] == nil,
+         let view = self.resolveReactView(tag: viewTag),
+         self.controlIsMasked(view, includeDescendants: isClick) {
+        payload["is_masked"] = true
+      }
+
       rum.setUserInteraction(payload)
     }
   }
 
+  /// Node budget for the descendant half of ``controlIsMasked(_:)``.
+  ///
+  /// The walk runs on the main thread for every interaction, so a deep subtree —
+  /// a long list row, a heavily nested design-system component — must not be able
+  /// to cause jank. Exhausting the budget answers "not masked", which omits the
+  /// key and leaves the SDK's coordinate resolution as the backstop, rather than
+  /// claiming an answer the walk never reached.
+  private static let maskWalkNodeBudget = 512
+
+  /// Whether anything in the tapped control is masked: the view itself, an
+  /// ancestor, or any descendant.
+  ///
+  /// Ancestors always count — masking is inherited, so a control inside a masked
+  /// panel is masked. Descendants count only when `includeDescendants` is set,
+  /// because React Native renders one logical control as several native views:
+  /// `<TouchableOpacity><Text/></TouchableOpacity>` puts the mask on a child and
+  /// leaves the tapped container itself unmarked.
+  private func controlIsMasked(_ view: UIView, includeDescendants: Bool) -> Bool {
+    // Self and ancestors, through the SDK's own accessor so the definition of
+    // masked lives in one place.
+    if view.isInsideMaskedSubtree { return true }
+    guard includeDescendants else { return false }
+
+    // Descendants, breadth-first and iteratively: recursion on an app-controlled
+    // depth is a stack overflow waiting to happen.
+    var queue = view.subviews
+    var index = 0
+    while index < queue.count {
+      if index >= Self.maskWalkNodeBudget { return false }
+      let current = queue[index]
+      index += 1
+      if current.cxMask { return true }
+      queue.append(contentsOf: current.subviews)
+    }
+    return false
+  }
+
+  /// Resolves a React view tag to its native view. Main thread only.
+  ///
+  /// New Architecture (Fabric): mounted views live in the component-view
+  /// registry, not the legacy RCTUIManager registry, and are reachable only
+  /// through the surface presenter — which is typed non-null but absent on the
+  /// legacy architecture, so it is bound through an optional before use.
+  private func resolveReactView(tag: NSNumber) -> UIView? {
+    guard let bridge = RCTBridge.current() else { return nil }
+
+    let surfacePresenter: (any RCTSurfacePresenterStub)? = bridge.surfacePresenter()
+    if let surfacePresenter = surfacePresenter,
+       let view = surfacePresenter.findComponentView(withTag_DO_NOT_USE_DEPRECATED: tag.intValue) {
+      return view
+    }
+
+    // Legacy (Paper) architecture.
+    return bridge.uiManager?.view(forReactTag: tag)
+  }
+
   @objc(shutdown:withRejecter:)
   func shutdown(resolve:RCTPromiseResolveBlock,
                 reject:RCTPromiseRejectBlock) -> Void {
@@ -370,34 +460,19 @@ class CxSdk: RCTEventEmitter {
   func maskViewByTag(viewTag: NSNumber,
                      resolve:@escaping RCTPromiseResolveBlock,
                      reject:@escaping RCTPromiseRejectBlock) -> Void {
-    guard let bridge = RCTBridge.current() else {
+    guard RCTBridge.current() != nil else {
       reject("MASK_VIEW_ERROR", "no bridge found, aborting maskViewByTag", nil)
       return
     }
 
     // View resolution and the cxMask mutation must happen on the main thread.
-    DispatchQueue.main.async {
-      // New Architecture (Fabric): mounted views live in the component-view
-      // registry, not the legacy RCTUIManager registry. Resolve them via the
-      // surface presenter; without this, masking silently no-ops on Fabric.
-      // The presenter is typed non-null but is absent on the legacy
-      // architecture, so bind it through an optional before use.
-      let surfacePresenter: (any RCTSurfacePresenterStub)? = bridge.surfacePresenter()
-      if let surfacePresenter = surfacePresenter,
-         let view = surfacePresenter.findComponentView(withTag_DO_NOT_USE_DEPRECATED: viewTag.intValue) {
-        view.cxMask = true
-        resolve("view with tag \(viewTag) marked for masking")
-        return
-      }
-
-      // Legacy (Paper) architecture.
-      if let view = bridge.uiManager?.view(forReactTag: viewTag) {
-        view.cxMask = true
-        resolve("view with tag \(viewTag) marked for masking")
+    DispatchQueue.main.async { [weak self] in
+      guard let view = self?.resolveReactView(tag: viewTag) else {
+        reject("MASK_VIEW_ERROR", "view with tag \(viewTag) not found, aborting maskViewByTag", nil)
         return
       }
-
-      reject("MASK_VIEW_ERROR", "view with tag \(viewTag) not found, aborting maskViewByTag", nil)
+      view.cxMask = true
+      resolve("view with tag \(viewTag) marked for masking")
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coralogix/react-native-plugin",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "description": "Official Coralogix React Native plugin",
   "license": "Apache-2.0",
   "author": "Coralogix",

package/src/index.d.ts

@@ -6,7 +6,13 @@ import { CoralogixLogSeverity } from './model/Types';
 import type { NetworkRequestDetails } from './model/NetworkRequestDetails';
 import type { CustomMeasurement } from './model/CustomMeasurement';
 import { SessionReplayOptions, SessionReplayType } from './model/SessionReplayType';
-interface CxSdkClient {
+/**
+ * The bridge contract, and the source of truth for it: every method here must
+ * exist in `ios/CxSdk.swift` and in the Android module with a matching
+ * signature. Exported as a type so `nativeModule.ts` can hold the instance
+ * without the declaration leaving this file.
+ */
+export interface CxSdkClient {
     initialize(options: CoralogixBrowserSdkConfig & {
         frameworkVersion?: string;
         hasBeforeSend?: boolean;
@@ -48,7 +54,7 @@ interface CxSdkClient {
     startSessionRecording(): void;
     stopSessionRecording(): void;
     captureScreenshot(): void;
-    maskViewByTag(viewTag: number): void;
+    maskViewByTag(viewTag: number): Promise<string>;
     reportUserInteraction(interaction: InteractionContext): void;
     startGlobalSpan(name: string, labels: Record<string, any> | null, ignoredInstruments: string[]): Promise<{
         spanId: string;
@@ -60,7 +66,6 @@ interface CxSdkClient {
     } | null>;
     endSpan(spanId: string): Promise<void>;
 }
-export declare const CxSdk: CxSdkClient;
 export declare const CoralogixRum: CoralogixOtelWebType;
 export declare const SessionReplay: SessionReplayType;
 export declare const parseErrorStack: (error: Error) => CoralogixStackFrame[];
@@ -79,7 +84,7 @@ export { type ApplicationContextConfig } from './model/ApplicationContextConfig'
 export { type ViewContextConfig } from './model/ViewContextConfig';
 export { CoralogixDomain } from './model/CoralogixDomain';
 export { type UserContextConfig } from './model/UserContextConfig';
-export { type CoralogixBrowserSdkConfig, type CoralogixIgnoredInstrument, type ExcludableInstrumentation, type NetworkCaptureRule, type TraceExporterData, type EditableCxRumEvent, type BeforeSendResult, CoralogixEventType, CoralogixLogSeverity, } from './model/Types';
+export { type CoralogixBrowserSdkConfig, type CoralogixIgnoredInstrument, type ExcludableInstrumentation, type NetworkCaptureRule, type TraceExporterData, type EditableCxRumEvent, type BeforeSendResult, type InteractionEventContext, CoralogixEventType, CoralogixLogSeverity, } from './model/Types';
 export { type CoralogixOtelWebOptionsInstrumentations } from './model/CoralogixOtelWebOptionsInstrumentations';
 export { type CustomMeasurement } from './model/CustomMeasurement';
 export { type NetworkRequestDetails } from './model/NetworkRequestDetails';
@@ -88,3 +93,5 @@ export { attachReactNavigationObserver } from './instrumentations/navigation/Nav
 export { CoralogixCustomTracer } from './custom-spans/CoralogixCustomTracer';
 export { CoralogixGlobalSpan } from './custom-spans/CoralogixGlobalSpan';
 export { CoralogixCustomSpan } from './custom-spans/CoralogixCustomSpan';
+export { CxSdk } from './nativeModule';
+export { Masked, type MaskedProps } from './masking/Masked';

package/src/instrumentations/user-interaction/UserInteractionInstrumentation.d.ts

@@ -1,6 +1,16 @@
 import { InstrumentationBase } from '@opentelemetry/instrumentation';
 import type { InteractionContext } from '../../model/Types';
+/**
+ * Puts the original RN components back.
+ *
+ * For one caller: a customer who opted out with
+ * `instrumentations: { user_interaction: false }`. Patching happens at module
+ * load, before any options exist to consult, so the opt-out is honored by undoing
+ * it once the options are known. `disable()` deliberately does not do this.
+ */
+export declare function restoreUserInteractionComponents(): void;
 export declare class UserInteractionInstrumentation extends InstrumentationBase {
+    private readonly report;
     constructor(config: {
         onInteraction: (ctx: InteractionContext) => void;
     });

package/src/instrumentations/user-interaction/consts.d.ts

@@ -1,4 +1,5 @@
 export declare const USER_INTERACTION_INSTRUMENTATION_NAME = "user-interaction";
 export declare const USER_INTERACTION_INSTRUMENTATION_VERSION = "1";
 export declare const SWIPE_MOMENTUM_TIMEOUT_MS = 80;
+export declare const MASKED_INNER_TEXT = "***";
 export declare const SWIPE_VELOCITY_THRESHOLD = 0.5;

package/src/instrumentations/user-interaction/gestureUtils.d.ts

@@ -1,3 +1,9 @@
 export type Direction = 'up' | 'down' | 'left' | 'right';
 export declare function inferDirectionFromDelta(dx: number, dy: number): Direction;
-export declare function extractInnerText(children: any): string | undefined;
+export type InnerTextExtraction = {
+    /** Visible text harvested from the subtree, unredacted. */
+    text?: string;
+    /** Whether a `Masked` wrapper was found anywhere in the walked subtree. */
+    masked: boolean;
+};
+export declare function extractInnerTextWithMasking(children: any): InnerTextExtraction;

package/src/instrumentations/user-interaction/index.d.ts

@@ -1 +1 @@
-export { UserInteractionInstrumentation } from './UserInteractionInstrumentation';
+export { restoreUserInteractionComponents, UserInteractionInstrumentation, } from './UserInteractionInstrumentation';

package/src/logger.d.ts

@@ -10,6 +10,14 @@ declare class Logger {
     debug(message: string, ...args: unknown[]): void;
     info(message: string, ...args: unknown[]): void;
     warn(message: string, ...args: unknown[]): void;
+    /**
+     * Warns even when debug logging is off.
+     *
+     * For failures the developer has to know about because nothing else in their
+     * app reveals them — masking that did not apply, say, where the cost of
+     * staying quiet is sensitive data reaching the backend.
+     */
+    alwaysWarn(message: string, ...args: unknown[]): void;
     error(message: string, ...args: unknown[]): void;
 }
 export declare const logger: Logger;

package/src/masking/Masked.d.ts

@@ -0,0 +1,39 @@
+import React from 'react';
+import { View, ViewProps } from 'react-native';
+import type { PropsWithChildren } from 'react';
+/**
+ * Props of `Masked`. It renders a real `View`, so it accepts everything a
+ * `View` does — `style` included. `onLayout` is chained, not replaced: the
+ * handler runs after the view is registered for masking.
+ *
+ * `collapsable` is not among them: masking depends on this view surviving RN's
+ * view flattening, so the component pins it to `false` and the prop would be
+ * ignored. Omitted rather than accepted-and-dropped, so the type says so.
+ */
+export type MaskedProps = PropsWithChildren<Omit<ViewProps, 'collapsable'>>;
+/**
+ * Masks its subtree in session replay, and tells the user-interaction
+ * instrumentation that everything inside is masked.
+ *
+ * The imperative `SessionReplay.maskView` masks pixels just as well, but it can
+ * only be resolved by coordinate: native sees `<Pressable><Text>5</Text></Pressable>`
+ * as a ReactViewGroup wrapping a ReactTextView, so masking the inner `<Text>`
+ * alone leaves a tap on the pressable's padding resolving as unmasked, shipping
+ * the real text. This wrapper closes that gap by making the verdict visible in
+ * JS, where the component tree is.
+ *
+ * Renders a real `View` — it participates in layout, and forwards `style` and
+ * the rest of its props. `collapsable={false}` keeps RN view flattening from
+ * removing the very view being masked.
+ *
+ * ```tsx
+ * <Pressable onPress={pay}>
+ *   <Masked>
+ *     <Text>{cardNumber}</Text>
+ *   </Masked>
+ * </Pressable>
+ * ```
+ */
+export declare const Masked: React.ForwardRefExoticComponent<Omit<ViewProps, "collapsable"> & {
+    children?: React.ReactNode | undefined;
+} & React.RefAttributes<View>>;

package/src/masking/maskView.d.ts

@@ -0,0 +1,9 @@
+import { LayoutChangeEvent } from 'react-native';
+/**
+ * Registers the view that fired the layout event for masking.
+ *
+ * Failures warn rather than pass silently: masking that does not apply leaves
+ * sensitive content in the replay, which is not something a caller can notice
+ * by looking at their own code.
+ */
+export declare function maskView(event: LayoutChangeEvent): void;

package/src/masking/maskedContext.d.ts

@@ -0,0 +1,90 @@
+import React from 'react';
+/**
+ * Brands a component type as the `Masked` wrapper.
+ *
+ * Keyed on a `Symbol.for` rather than element identity (`type === Masked`) so
+ * recognition survives a consuming app resolving two copies of the plugin: the
+ * symbol comes from the global registry, so a `Masked` rendered by one copy is
+ * still recognized by the instrumentation of another.
+ */
+export declare const MASKED_COMPONENT_MARKER: unique symbol;
+/**
+ * True anywhere inside a `Masked` subtree.
+ *
+ * Read it with `MaskedContext.Consumer`, never `useContext`: the plugin's React
+ * and the renderer's React are different instances in a consuming app, and hooks
+ * resolve through the instance-specific ReactCurrentDispatcher. Non-hook APIs
+ * (`createContext`, `forwardRef`, `createElement`) are safe under that
+ * constraint — the same one the user-interaction wrappers already work under.
+ *
+ * Cached on the global registry rather than created per module, for the same
+ * reason {@link MASKED_COMPONENT_MARKER} is a `Symbol.for`: an app that resolves
+ * two copies of the plugin would otherwise get two distinct context objects, and
+ * a `Consumer` from one copy reads its own default `false` no matter what a
+ * `Masked` from the other copy provided. That fails open — masking dropped and
+ * the real text reported — so the two copies have to share one object.
+ */
+export declare const MaskedContext: React.Context<boolean>;
+/**
+ * A pressable's record of whether masked content rendered anywhere inside it.
+ *
+ * The children walk in `extractInnerTextWithMasking` reads the *element* tree —
+ * what the caller passed — so it cannot see a `Masked` that a composite renders
+ * internally. `<Pressable><SensitiveValue>{card}</SensitiveValue></Pressable>`,
+ * where `SensitiveValue` renders `<Masked>` around its children, harvests the
+ * card number through `props.children` and never meets the `Masked`. That fails
+ * open: the real value ships with the flag omitted.
+ *
+ * This closes it from the other end. Each instrumented pressable owns one scope,
+ * and every `Masked` marks the scope it renders inside, whoever rendered it. The
+ * press handler reads the mark, so the verdict comes from what actually
+ * rendered rather than from what was passed in.
+ *
+ * `masked` is sticky. React can re-render a pressable without re-rendering
+ * children that did not change, so clearing the mark per render would drop a
+ * verdict that nothing goes on to re-assert. Over-masking after a `Masked`
+ * genuinely goes away is the direction that leaks nothing.
+ */
+export type MaskScope = {
+    masked: boolean;
+    /** The enclosing pressable's scope, so a nested `Masked` marks both. */
+    parent: MaskScope | null;
+};
+/**
+ * The nearest enclosing pressable's {@link MaskScope}, or null outside one.
+ *
+ * Cached on the global registry for the same reason {@link MaskedContext} is.
+ */
+export declare const MaskScopeContext: React.Context<MaskScope | null>;
+/** Marks `scope` and every scope enclosing it as containing masked content. */
+export declare function markScopeMasked(scope: MaskScope | null): void;
+/**
+ * Owns one {@link MaskScope} and provides it to its subtree.
+ *
+ * A class, not a function component: the scope has to be the same object across
+ * re-renders for a mark made during one render to still be readable at press
+ * time, and `useRef` is unavailable here — the plugin's React and the renderer's
+ * React are different instances in a consuming app, and hooks resolve through
+ * the instance-specific ReactCurrentDispatcher. A class instance needs no
+ * dispatcher.
+ */
+export declare class MaskScopeBoundary extends React.Component<{
+    children: (scope: MaskScope) => React.ReactNode;
+    /**
+     * Called after every commit, with this boundary's scope.
+     *
+     * The render callback above is the only place a caller can reach the scope,
+     * and it runs during render — so anything with a side effect the app can
+     * observe, such as writing a node into a ref the app passed, has to be
+     * recorded there and performed here instead.
+     */
+    onCommit?: (scope: MaskScope) => void;
+}> {
+    static contextType: React.Context<MaskScope | null>;
+    private readonly scope;
+    componentDidMount(): void;
+    componentDidUpdate(): void;
+    render(): React.ReactNode;
+}
+/** Whether a React element's `type` is the `Masked` wrapper. */
+export declare function isMaskedComponentType(type: unknown): boolean;

package/src/model/Types.d.ts

@@ -129,6 +129,57 @@ export interface NetworkRequestContext {
     response_content_length: string;
     duration: number;
 }
+/**
+ * `interaction_context` as it appears on a user-interaction RUM event — the
+ * shape `beforeSend` receives. Built natively (field names differ from the
+ * {@link InteractionContext} payload JS hands to the bridge).
+ *
+ * Intentionally editable in `beforeSend` (except `is_masked_element`): a
+ * callback may blank the coordinates in `attributes`, redact text fields, or
+ * drop the whole event to enforce a masking policy stricter than the default.
+ */
+export interface InteractionEventContext {
+    event_name: 'click' | 'scroll' | 'swipe';
+    target_element: string;
+    /**
+     * Whether the interaction targeted content masked in session replay.
+     *
+     * Resolved from whichever source knows, in order: JS, when a `Masked` wrapper
+     * makes the answer visible in the component tree; the plugin's native module,
+     * walking the tapped control's own view tree for a `maskView` mark on it, an
+     * ancestor or a descendant; and finally the SDK, testing the tap coordinates
+     * against the frame's mask geometry — the backstop for masks only it can see,
+     * such as a native view layered under the RN tree.
+     * `false` is the documented default whenever none of them can resolve it — the
+     * SDK under-reports rather than guesses. Scroll and swipe carry no coordinates,
+     * so they depend entirely on the second source.
+     *
+     * Optional because a native SDK older than the version this plugin pins does
+     * not stamp it, and the SDK never fabricates a value it did not receive — the
+     * same reason `session_context.isSessionSampledIn` is optional. Treat
+     * `undefined` as `false`, which is what the native SDKs report when they
+     * cannot resolve masking either.
+     *
+     * Read-only: the SDK's value is restored after `beforeSend` returns, so
+     * assigning to it has no effect on the sent event.
+     */
+    readonly is_masked_element?: boolean;
+    element_classes?: string;
+    element_id?: string;
+    /** Visible text of the tapped element. `'***'` when the element is masked. */
+    target_element_inner_text?: string;
+    scroll_direction?: 'up' | 'down' | 'left' | 'right';
+    /**
+     * Tap coordinates (clicks only). Open-shaped on purpose: a `beforeSend`
+     * callback may blank the coordinates or add its own keys (e.g. a
+     * masking-strategy stamp) — the native wire type is an arbitrary JSON object.
+     */
+    attributes?: {
+        x?: number;
+        y?: number;
+        [key: string]: unknown;
+    };
+}
 export interface SnapshotContext {
     timestamp: number;
     errorCount: number;
@@ -164,6 +215,13 @@ export interface CxRumEvent {
     error_context?: ErrorContext;
     log_context?: LogContext;
     network_request_context?: NetworkRequestContext;
+    /**
+     * Present on user-interaction events. Editable in `beforeSend` — the escape
+     * hatch for masking policies stricter than the default (blank the
+     * coordinates, or return `null` to drop the event) — except for
+     * `is_masked_element`, whose SDK value is restored after the callback.
+     */
+    interaction_context?: InteractionEventContext;
     readonly snapshot_context?: SnapshotContext;
     labels: CoralogixRumLabels;
     readonly spanId: string;
@@ -319,6 +377,21 @@ export type ExcludableInstrumentation = 'errors' | 'logs' | 'network' | 'userInt
 export interface TraceExporterData {
     resource_spans: Record<string, unknown>[];
 }
+/**
+ * Interaction payload JS hands to the native bridge.
+ *
+ * Masking is resolved from three sources whose knowledge is unioned:
+ * `is_masked` below, when JS can see the answer in the component tree;
+ * {@link InteractionContext.view_tag}, which lets the plugin's native module
+ * walk the tapped control's own view tree for a `maskView` mark; and finally
+ * the tap coordinates in `attributes`, tested by the SDK against the frame's
+ * mask geometry.
+ *
+ * Scroll and swipe carry no coordinates, so the third source cannot answer for
+ * them — but they do carry `view_tag`, so a scroll inside a masked container
+ * resolves through the second and reports
+ * `interaction_context.is_masked_element: true`.
+ */
 export interface InteractionContext {
     type: 'click' | 'scroll' | 'swipe';
     /** Required. Element identifier: accessibilityLabel ?? componentName for clicks; 'ScrollView' for scroll/swipe. */
@@ -326,7 +399,43 @@ export interface InteractionContext {
     direction?: 'up' | 'down' | 'left' | 'right';
     element_classes?: string;
     target_id?: string;
+    /**
+     * Extracted string content, click only. Already `'***'` when JS resolved the
+     * element as masked — the unredacted text never crosses the bridge.
+     */
     inner_text?: string;
+    /**
+     * JS's masking verdict, set only when a `Masked` wrapper puts it beyond
+     * doubt: a `Masked` ancestor or descendant of the tapped element.
+     *
+     * Typed `true` because the wire contract is true-or-omit, never false. The key
+     * is authoritative in both native SDKs, so sending `false` would suppress
+     * their coordinate resolution and lose masks only they can see (an imperative
+     * `maskView`, or a native view layered under the RN tree). Absence means "JS
+     * doesn't know", which is what lets native decide.
+     */
+    is_masked?: true;
+    /**
+     * The tapped control's native view tag, so the plugin's native module can
+     * resolve masking from the control's own view tree.
+     *
+     * `SessionReplay.maskView` marks a view natively and leaves no trace in the
+     * component tree, so JS cannot see it — and native, resolving by coordinate,
+     * cannot tell where a control begins and ends, because React Native presses
+     * go through the JS responder system and leave no native clickable marker.
+     * The tag is the one thing that joins the two: JS knows which component is
+     * the control, native knows which views are masked.
+     *
+     * The *control's* tag, from our own ref, not `nativeEvent.target` — the
+     * event's target is the deepest hit-tested view, which scopes the native walk
+     * to the wrong subtree when the tap lands on a sibling inside the control.
+     * Scroll and swipe are the exception: their events are emitted by the scroll
+     * view itself, so there the target is the control.
+     *
+     * Omitted when {@link is_masked} is already set: the `Masked` path answers in
+     * JS and needs no native walk.
+     */
+    view_tag?: number;
     attributes?: {
         x?: number;
         y?: number;

package/src/nativeModule.d.ts

@@ -0,0 +1,2 @@
+import type { CxSdkClient } from './index';
+export declare const CxSdk: CxSdkClient;