@everframe/react-native 1.3.0 → 1.4.0

package/EverframeRN.podspec

@@ -40,7 +40,7 @@ package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
 # 1.2.0, so the range already asks for 1.2 while package.json is still 1.1.0.
 # The 1.2.0 release moves package.json to match.
 native_version_override = ENV['EVERFRAME_NATIVE_POD_VERSION'].to_s.strip
-native_minor_range = native_version_override.empty? ? '~> 1.3.0' : native_version_override
+native_minor_range = native_version_override.empty? ? '~> 1.4.0' : native_version_override
 
 Pod::Spec.new do |s|
   s.name         = 'EverframeRN'
@@ -86,7 +86,7 @@ Pod::Spec.new do |s|
   s.dependency 'React-Core'
 
   s.test_spec 'Tests' do |t|
-    t.source_files = 'ios/Tests/**/*.swift'
+    t.source_files = 'ios/Tests/**/*.{swift,m,mm}'
     t.frameworks = ['XCTest', 'UIKit']
   end
 end

package/README.md

@@ -840,3 +840,186 @@ activity recreation.
 ## License
 
 MIT
+
+### Optional interaction target annotations
+
+Phone taps and TV remote interactions automatically use the available native
+control role, accessibility label, test ID, visible text, and screen marker.
+Reporting and automatic breadcrumbs work without app annotations. Logical
+collection positions are included only when known; mounted children are never
+used as the total item count.
+
+Use `useEverframeTarget` on an existing host to add product names or logical
+collection metadata:
+
+```tsx
+import { useEverframeTarget } from '@everframe/react-native';
+
+const targetRef = useEverframeTarget({
+  testId: 'poster-low-orbit', role: 'button', name: 'Low Orbit',
+  container: { testId: 'home-originals', name: 'Originals', role: 'list', index: 0, count: 12 },
+});
+return <Pressable ref={targetRef} onPress={openTitle}><Text>Low Orbit</Text></Pressable>;
+```
+
+Indices are zero-based logical positions in the collection. An explicit
+container replaces the automatic container as a unit. Updating the annotation
+updates the existing host without waiting for `onLayout`; passing `undefined`
+removes it. Strings are bounded to 256 UTF-16 units (roles: 64). Do not put
+secrets or user-entered values into annotations. Existing sensitive-view masking
+takes precedence and suppresses names, IDs, containers, and screen metadata.
+
+Compose with an existing ref using a stable callback (return no value):
+
+```tsx
+const ref = React.useCallback((node: React.ElementRef<typeof View> | null) => {
+  existingRef.current = node;
+  targetRef(node);
+}, [targetRef]);
+```
+
+Custom components must forward the ref to their native host. For a layout-only
+`View`, use `collapsable={false}` so a host exists. Unsupported custom refs,
+missing providers, and older native binaries fail softly. This feature requires
+a native rebuild to enable annotation registration; it cannot be enabled by a
+JavaScript-only update. The web export accepts the same type and is a no-op.
+No wrapper, `onPress` replacement, or manual breadcrumb is needed.
+
+Native registrations use weak host references and cancel stale ref generations.
+After 4096 distinct registrations in one native session, optional annotations
+fail closed until SDK restart; automatic target extraction continues. This
+bound prevents delayed work from resurrecting evicted registration ownership.
+
+Native target qualification uses the installed Fabric fixture under
+`__tests__/fixtures/interaction-targets`. Rebuild native binaries after upgrading.
+The iOS sensitive wrapper retains its native host and resolves it through the
+Fabric view registry, so masked descendants stay excluded from target labels.
+
+### State labels (iOS and Android)
+
+`setState(key, value)` records a string, finite number, or boolean diagnostic label;
+`clearState(key)` removes it. Both are also available from `useEverframe()`.
+Call after the provider mounts. State is redacted, bounded, and frozen with report
+evidence. See [State API](../../docs/state.md) for lifecycle, privacy, limits and
+native recovery freshness.
+
+## Semantic interaction evidence
+
+On iOS, Android and their TV variants, supported native controls record text edits,
+control changes and completed scroll gestures automatically. Existing taps and
+reporting continue to work without hooks. Programmatic text/control updates do not
+represent user interaction. TV focus movement only counts as scrolling when the
+native content offset changes.
+
+Text evidence contains its UTF-16 length by default. Secure or sensitive fields
+produce no text evidence, including length. To permit a value locally, configure
+an exact native `testID`:
+
+```tsx
+<EverframeProvider config={{
+  sdkKey: 'txx_…',
+  interactions: { valueTestIds: ['search-input'] },
+}}>
+  <App />
+</EverframeProvider>
+```
+
+Optional values are redacted and limited to 256 UTF-16 units. Allowlisting a name
+only in hook metadata never grants permission: the live native host must carry
+that exact `testID`. Setting `interactions: { disabled: true }` disables these
+semantic events without changing existing tap/error capture.
+
+Use `useEverframeInteraction` to add target metadata to an existing native host.
+Its ref adds no wrapper or app handler. Compose it with any existing app ref:
+
+```tsx
+import { useEverframeInteraction } from '@everframe/react-native';
+import type { ElementRef } from 'react';
+import { TextInput } from 'react-native';
+
+function SearchField() {
+  const interaction = useEverframeInteraction<ElementRef<typeof TextInput>>({
+    target: { testId: 'search-input', name: 'Search' },
+  });
+  return <TextInput testID="search-input" ref={interaction.ref} />;
+}
+```
+
+Native observation owns text, control and scroll evidence. `helperTypes` is
+retained for source compatibility and always registers an empty list, including
+legacy declarations. Each native bridge also strips helper ownership from older
+JavaScript callers, so these declarations never suppress automatic observation.
+Existing tap evidence is preserved. Missing providers, unsupported refs, older
+native binaries and the web entry safely leave metadata registration inactive.
+
+`textChanged(text, options?)`, `controlChanged(change)` and
+`scrollSettled(change)` are compatibility no-ops. They never inspect their
+payloads or send values, lengths or state across the bridge. JavaScript callbacks
+cannot prove whether a host was sensitive when the observation originated;
+checking after it is unmasked would be too late. Custom JavaScript controls
+without a supported native observation point produce missing semantic evidence.
+
+Clearing evidence, signing out or changing native capture configuration revokes
+pending work. A queued callback keeps its original ownership and cannot renew it.
+An unchanged mounted hook does not replay old metadata; a fresh committed host
+attachment or metadata change can register again.
+
+Text coalesces after 750 ms of inactivity, editing end, submission or safe report
+freeze. An unfinished native composition retains only the last observed user-edit
+length, without its value. If the keyboard ends composition without another text
+change after the idle check, that summary waits for editing end or safe report
+freeze. Its length describes the observed edit, including when the app later
+replaces the text; it is not a newly sampled final value.
+Scrolls coalesce at gesture completion or after 200 ms of inactivity.
+Semantic events share a 20-per-10-second budget; text and scroll also share a
+one-per-second budget per host. Values are bounded again after final redaction.
+
+Incoming links are observed through React Native's existing `Linking` channel while the provider is mounted. The SDK does not route links. By default, evidence contains only scheme and host; valid opaque or hostless links retain only their scheme (for example `myapp:`). Parsing works in bare React Native without a global URL patch. Declare known route templates (for example `/watch/:id`) and exact query keys in `interactions.urlRules` to include more. Credentials, fragments and actual dynamic path segments are omitted; ambiguous encoded separators and dot segments are rejected. The initial URL is considered once per JS process. If capture is disabled at that first mount, it is omitted permanently; later mounts and re-enabling capture observe only fresh URL callbacks. The mounted subscription stays active while local policy enables it, and each new callback checks the current native capture lease. Distinct URL callbacks remain distinct observations even when their URLs match, because React Native supplies no delivery ID.
+
+Observe an existing permission operation without changing its result:
+
+```ts
+import { observePermissionRequest, recordLaunchContext } from '@everframe/react-native';
+import { PermissionsAndroid } from 'react-native';
+
+const result = await observePermissionRequest('android.permission.CAMERA', () =>
+  PermissionsAndroid.request(PermissionsAndroid.PERMISSIONS.CAMERA),
+);
+
+// For an existing notification integration; call during the matching foreground entry.
+recordLaunchContext({ trigger: 'notification', arguments: { campaign: 'autumn' } });
+```
+
+Without a mapper, the permission observer recognizes Android's `granted`, `denied` and `never_ask_again` results. Supply a mapper returning `granted`, `denied`, `blocked`, `limited`, `unavailable` or `unknown` for iOS or third-party APIs. The operation runs exactly once; its original value or rejection is preserved. A mapper failure or rejected request is recorded as `unknown`, never inferred as denial. A result does not prove a system dialog was shown. TV APIs that do not support a permission should map their actual result to `unavailable`.
+
+Launch context enriches only a native foreground entry that is still pending (up to 250 ms, ending earlier on report freeze or background). It cannot create a launch, change cold/warm classification, or alter a frozen report. Late context is omitted. Only exact `interactions.launchArgumentKeys` allowlisted primitive values are accepted, at most 16 entries and 128 UTF-16 units per string. URLs belong to link evidence and are omitted from launch arguments. No arguments are captured by default.
+
+Permission operations still run without a provider, with older native binaries and on web. Launch context is a no-op in those cases. A clear, sign-out or native configuration change revokes in-flight observations; it does not cancel the app's operation.
+
+Target annotations enrich supported automatic native observations, including IME composition and optional allowlisted values. Native integrations that observe controls directly on the UI thread can supply native helpers with original privacy proof; the JavaScript compatibility methods cannot provide that proof.
+
+### Reporter boundaries and developer tools
+
+Native phone reporter opens and companion report requests add this custom breadcrumb before freezing evidence:
+
+```json
+{"kind":"custom","message":"reporter_opened","data":{"source":"everframe_reporter","trigger":"button"}}
+```
+
+`trigger` is `button`, `shake`, `menu`, or `companion`. Pending text/scroll summaries are flushed before this boundary. Native shake uses `shake`; companion report requests use `companion`; existing `open()` calls use `button`. To identify a host menu entry explicitly, call `open({ trigger: 'menu' })`. Closing or cancelling the native flow adds `reporter_closed` with `data.source: 'everframe_reporter'` to the live trail. Both events retain breadcrumb capture/config gates.
+
+A reporter call crosses the React Native bridge after its native input can already have been recorded. It cannot prove that the previous tap or remote key opened the reporter. For a button, annotate its native host ref before interaction:
+
+```tsx
+const reporterRef = useEverframeTarget({ reporterTrigger: 'button' });
+const { open } = useEverframe();
+return <Pressable ref={reporterRef} onPress={() => void open()}><Text>Report</Text></Pressable>;
+```
+
+That target's tap/activation carries `data.origin: 'reporter'` and `data.trigger: 'button'`. On a remote, only Select/Enter activation is attributed to a `button` target; arrows, Menu and Play/Pause retain their ordinary meaning. An explicitly annotated `reporterTrigger: 'menu'` target attributes only its Menu activation. Attribution survives masking without retaining the target's text. Removing/recycling the bound ref removes attribution.
+
+Hosts owning a reporting flow outside `open()` can `await markReporterOpened('menu')` before showing their reporter UI and `await markReporterClosed()` when it closes. These promises resolve after the native UI-thread boundary work; await them before adding subsequent host breadcrumbs or changing reporter UI. These explicit markers do not claim or remove earlier native keys: a TV event callback may run after native key capture. Use companion report-request boundaries when a host cannot attribute the original remote trigger. Never infer reporter intent from a button label, a Menu/Play/Pause key, or proximity to `open()`.
+
+Native target capture adds `data.origin: 'devtools'` to supported taps and structured text/control/scroll observations whose native ancestry belongs to React Native LogBox, the native development menu, or Expo development-client UI. This comes from framework view/window/controller identity, an RN-owned development-menu controller, or a framework root module identity. In a development host, the inline LogBox notification/inspector is also registered by the exact React Native component exports through the existing React DevTools commit hook; application components with the same name are not attributed. This observer reads component identity and native refs, never warning text or component props, and removes registrations when their committed hosts disappear or the provider unmounts. Production JavaScript leaves this observer inert. A development JavaScript host can still attribute LogBox when its native SDK was built in Release mode. Display text such as “Dismiss” never grants an origin. A missing React DevTools hook, unavailable RN private module exports at runtime, initial asynchronous module loading, unknown framework versions and surfaces outside the native capture adapters leave attribution unavailable; origin tagging does not install a new dialog capture mechanism. The observer depends on the LogBox module paths in supported React Native versions; a future version removing those paths requires an SDK compatibility update before Metro can bundle it.
+
+Consumers should use the latest active reporter interval (matching `reporter_opened`/`reporter_closed` markers by ordered trail), cut before its explicitly attributed triggering interaction when present, and otherwise before its opened marker. Closed reporter intervals can also be excluded while preserving application actions after their closing marker. Developer-tool observations can be excluded by their explicit `data.origin`. A cancelled earlier report must not become the boundary for a later report. Legacy trails lacking these fields remain valid and supply no new attribution evidence.

package/android/build.gradle.kts

@@ -153,7 +153,7 @@ val rnSdkPkg = groovy.json.JsonSlurper()
 val rnSdkVersion = rnSdkPkg["version"] as String
 // Native 1.2.0 is the release that renamed the SDK key to `sdkKey`; the
 // bridge moves with it, ahead of package.json, which the 1.2.0 release bumps.
-val nativeMinorRange: String = nativeVersionOverride ?: "[1.3.0,1.4.0)"
+val nativeMinorRange: String = nativeVersionOverride ?: "[1.4.0,1.5.0)"
 if (nativeVersionOverride != null) {
     logger.lifecycle(
         "[everframe-rn] native AAR pinned to $nativeVersionOverride via everframeNativeVersion " +

package/android/src/main/java/dev/everframe/rn/EverframeModule.kt

@@ -106,6 +106,44 @@ class EverframeModule(
     private val reactContext: ReactApplicationContext,
 ) : NativeEverframeSpec(reactContext) {
 
+    private val interactionTargetAdapter = dev.everframe.capture.InteractionTargetViewAdapters.register(RnInteractionTargetAdapter)
+    private val interactionEvents = RnInteractionEventRegistration(
+        { tag -> com.facebook.react.uimanager.UIManagerHelper.getUIManagerForReactTag(reactContext, tag)?.resolveView(tag) },
+        { action -> com.facebook.react.bridge.UiThreadUtil.runOnUiThread { action() } },
+    )
+    private val interactionEventObserver = RnInteractionEventObserver.install(reactContext) { interactionEvents.active() }
+    private val interactionTargets = RnInteractionTargetRegistration(
+        { tag -> UIManagerHelper.getUIManagerForReactTag(reactContext, tag)?.resolveView(tag)?.takeIf { it.isAttachedToWindow } },
+        { block -> UiThreadUtil.runOnUiThread { block() } },
+    )
+
+    private var interactionMountsClosed = false
+    private var interactionTargetUIManager: com.facebook.react.bridge.UIManager? = null
+    @OptIn(com.facebook.react.common.annotations.UnstableReactNativeAPI::class)
+    private val interactionMountListener = object : com.facebook.react.bridge.UIManagerListener {
+        override fun willDispatchViewUpdates(uiManager: com.facebook.react.bridge.UIManager) = Unit
+        override fun willMountItems(uiManager: com.facebook.react.bridge.UIManager) = Unit
+        override fun didMountItems(uiManager: com.facebook.react.bridge.UIManager) { interactionTargets.onMount(); interactionEvents.onMount() }
+        override fun didDispatchMountItems(uiManager: com.facebook.react.bridge.UIManager) { interactionTargets.onMount(); interactionEvents.onMount() }
+        override fun didScheduleMountItems(uiManager: com.facebook.react.bridge.UIManager) = Unit
+    }
+    @OptIn(com.facebook.react.common.annotations.UnstableReactNativeAPI::class)
+    @Synchronized private fun observeInteractionMounts(tag: Int) {
+        if (interactionMountsClosed) return
+        val manager = UIManagerHelper.getUIManagerForReactTag(reactContext, tag) ?: return
+        if (interactionTargetUIManager === manager) return
+        interactionTargetUIManager?.removeUIManagerEventListener(interactionMountListener)
+        interactionTargetUIManager = manager
+        manager.addUIManagerEventListener(interactionMountListener)
+    }
+
+    @OptIn(com.facebook.react.common.annotations.UnstableReactNativeAPI::class)
+    @Synchronized private fun stopObservingInteractionMounts() {
+        interactionMountsClosed = true
+        interactionTargetUIManager?.removeUIManagerEventListener(interactionMountListener)
+        interactionTargetUIManager = null
+    }
+
     private val reporterBridge = ReporterBridge()
 
     private val videoPrivacyAdapter = Everframe.__registerVideoPrivacyAdapter(RnVideoPrivacyAdapter)
@@ -290,6 +328,9 @@ class EverframeModule(
                 release = sdkVersion,
                 capture = CaptureConfig(networkBodies = !networkBodiesDisabled, crash = !crashReportingDisabled),
                 installIdentifierEnabled = !installIdentifierDisabled,
+                interactions = dev.everframe.capture.InteractionEventPolicy.parse(opts.takeIfHasString("interactionsJson")),
+                loadedJsBundle = dev.everframe.config.LoadedJsBundle.create(
+                    opts.takeIfHasString("jsBundleBuildId"), opts.takeIfHasString("jsBundleName")),
                 releaseHealth = parseReleaseHealth(opts),
                 // The JS facade always sends React Native's `__DEV__` (or the host's override). A missing
                 // or null key stays null so the native SDK decides for itself, as for any other caller.
@@ -369,6 +410,7 @@ class EverframeModule(
             //     or the host is left with a dead SDK and no way to revive it.
             //   • `attachPinUi` — the one bridge option that lands in module state instead of
             //     in `EverframeConfig`, so config equality alone cannot see it change.
+            interactionEventObserver.refresh(reactContext)
             if (Everframe.captureGate &&
                 Everframe.currentConfig == config &&
                 companionAttachPinUi == attachPinUi
@@ -392,6 +434,7 @@ class EverframeModule(
             // Window.Callback wrapper is never installed on the current screen
             // and the session ships zero tap crumbs (field bug 2026-07-10).
             Everframe.start(reactContext.applicationContext, config, reactContext.currentActivity)
+            interactionTargets.onStarted()
 
             // Codex round-5, G1 — the registry is NOT renewed here any more. The live players
             // this start just orphaned are re-registered from JS instead: `mount()` bumps the
@@ -427,6 +470,45 @@ class EverframeModule(
      */
     @ReactMethod
     override fun openReporter(promise: Promise) {
+        openReporterInternal(null,promise)
+    }
+
+    @ReactMethod
+    override fun openReporterWithTrigger(trigger: String, promise: Promise) {
+        val value = dev.everframe.config.ReporterTrigger.fromValue(trigger)
+        if (value == null) {
+            promise.reject(REJECT_OPEN_REPORTER_FAILED,"Invalid reporter trigger")
+            return
+        }
+        openReporterInternal(value,promise)
+    }
+
+    @ReactMethod
+    override fun markReporterOpened(trigger: String, promise: Promise) {
+        runReporterMarker(Everframe.__prepareReporterOpened(trigger),promise)
+    }
+
+    @ReactMethod
+    override fun markReporterClosed(promise: Promise) {
+        runReporterMarker(Everframe.__prepareReporterClosed(),promise)
+    }
+
+    private fun runReporterMarker(action: Runnable, promise: Promise) {
+        try {
+            UiThreadUtil.runOnUiThread {
+                try {
+                    action.run()
+                    promise.resolve(null)
+                } catch (_: Throwable) {
+                    promise.reject("reporter_marker_failed","Could not record reporter marker")
+                }
+            }
+        } catch (_: Throwable) {
+            promise.reject("reporter_marker_failed","Could not schedule reporter marker")
+        }
+    }
+
+    private fun openReporterInternal(trigger: dev.everframe.config.ReporterTrigger?, promise: Promise) {
         if (!Everframe.captureGate) {
             promise.reject(REJECT_CAPTURE_DISABLED, "Everframe not started (captureGate=false). Call configure() first.")
             return
@@ -439,7 +521,10 @@ class EverframeModule(
         }
         MainScope().launch {
             try {
-                val result: ReportResult = reporterBridge.open(reactContext)
+                val result: ReportResult = if (trigger == null) reporterBridge.open(reactContext)
+                    else kotlinx.coroutines.withContext(dev.everframe.config.ReporterTriggerContext(trigger)) {
+                        reporterBridge.open(reactContext)
+                    }
                 val dict = Arguments.createMap().apply {
                     when (result) {
                         is ReportResult.Submitted -> {
@@ -602,7 +687,13 @@ class EverframeModule(
      * BEFORE the Provider's configure-on-mount, so clearing there would drop
      * legitimate registrations that had already landed.
      */
+    @OptIn(com.facebook.react.common.annotations.UnstableReactNativeAPI::class)
     override fun invalidate() {
+        interactionEventObserver.close()
+        interactionEvents.close()
+        stopObservingInteractionMounts()
+        interactionTargets.close()
+        interactionTargetAdapter.close()
         sensitiveRegistration.close()
         videoPrivacyAdapter.close()
         super.invalidate()
@@ -623,6 +714,16 @@ class EverframeModule(
         extraResolverActive = false
     }
 
+    @ReactMethod(isBlockingSynchronousMethod = true)
+    override fun setStateSync(key: String, valueJson: String): Boolean {
+        if (valueJson.length > 2048) return false
+        val value = try { kotlinx.serialization.json.Json.decodeFromString(dev.everframe.protocol.generated.StateValue.serializer(), valueJson) }
+                    catch (_: Exception) { return false }
+        return Everframe.setState(key, value)
+    }
+    @ReactMethod(isBlockingSynchronousMethod = true)
+    override fun clearStateSync(key: String): Boolean = Everframe.clearState(key)
+
     // ---------------- setUser (self-declared identity — spec 2026-08-12) ----------------
 
     /**
@@ -760,6 +861,26 @@ class EverframeModule(
      */
     internal var __drainRequester: () -> Unit = { Everframe.requestOutboxDrain() }
 
+    @ReactMethod(isBlockingSynchronousMethod = true)
+    override fun setInteractionTarget(viewTag: Double, registrationId: String, generation: Double, annotation: ReadableMap): Boolean =
+        runCatching {
+            if (viewTag.isFinite() && viewTag > 0 && viewTag <= Int.MAX_VALUE && viewTag == viewTag.toInt().toDouble()) observeInteractionMounts(viewTag.toInt())
+            interactionTargets.set(viewTag, registrationId, generation, annotation.toHashMap())
+        }.getOrDefault(false)
+
+    @ReactMethod(isBlockingSynchronousMethod = true)
+    override fun getInteractionLease(): String = interactionEvents.lease()
+    override fun setInteractionObserver(viewTag: Double, id: String, generation: Double, lease: String, optionsJson: String): Boolean =
+        runCatching {
+            if (viewTag.isFinite() && viewTag > 0 && viewTag <= Int.MAX_VALUE && viewTag == viewTag.toInt().toDouble()) observeInteractionMounts(viewTag.toInt())
+            interactionEvents.set(viewTag,id,generation,lease,optionsJson)
+        }.getOrDefault(false)
+    override fun clearInteractionObserver(id: String, generation: Double): Boolean = runCatching { interactionEvents.clear(id,generation) }.getOrDefault(false)
+    override fun recordInteraction(lease: String, id: String, generation: Double, eventJson: String): Boolean = runCatching { interactionEvents.record(lease,id,generation,eventJson) }.getOrDefault(false)
+
+    override fun clearInteractionTarget(registrationId: String, generation: Double): Boolean =
+        runCatching { interactionTargets.clear(registrationId, generation) }.getOrDefault(false)
+
     // ---------------- registerSensitiveRect ----------------
 
     @ReactMethod

package/android/src/main/java/dev/everframe/rn/RnInteractionEventObserver.kt

@@ -0,0 +1,69 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 ScriptX
+package dev.everframe.rn
+
+import android.os.Looper
+import android.view.View
+import android.widget.CompoundButton
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.UiThreadUtil
+import com.facebook.react.uimanager.UIManagerHelper
+import com.facebook.react.uimanager.events.Event
+import com.facebook.react.uimanager.events.EventDispatcher
+import com.facebook.react.uimanager.events.EventDispatcherListener
+import com.facebook.react.views.textinput.ReactEditText
+import dev.everframe.capture.InteractionTextAdapter
+import dev.everframe.capture.InteractionControlAdapter
+import dev.everframe.capture.InteractionScrollAdapter
+
+/** Observes before JS dispatch. Never reads protected event payloads or replaces app callbacks. */
+internal class RnInteractionEventObserver(private val resolve: (Int, Int) -> View?, private val active: () -> Boolean = { true }) : EventDispatcherListener, AutoCloseable {
+    private var dispatcher: EventDispatcher? = null
+    @Volatile private var closed = false
+    fun attach(value: EventDispatcher) {
+        if (closed || dispatcher === value) return
+        dispatcher?.removeListener(this); dispatcher = value; value.addListener(this)
+    }
+    fun refresh(context: ReactApplicationContext) {
+        UiThreadUtil.runOnUiThread { runCatching { UIManagerHelper.getEventDispatcher(context)?.let(::attach) } }
+    }
+    override fun onEventDispatch(event: Event<*>) {
+        // Queuing an event would acquire ownership after a possible clear and retain raw payload.
+        if (closed || !active() || Looper.myLooper() != Looper.getMainLooper()) return
+        runCatching {
+            val name = event.getEventName()
+            if (name !in names) return
+            val view = resolve(event.viewTag, event.surfaceId) ?: return
+            if (!view.isAttachedToWindow || UIManagerHelper.getSurfaceId(view) != event.surfaceId) return
+            when {
+                view is ReactEditText -> when (name) {
+                    "topChange" -> InteractionTextAdapter.shared.changed(view)
+                    "topEndEditing" -> InteractionTextAdapter.shared.ended(view)
+                    "topSubmitEditing" -> InteractionTextAdapter.shared.ended(view, submit = true)
+                    else -> Unit
+                }
+                view is CompoundButton && view.javaClass.name == "com.facebook.react.views.switchview.ReactSwitch" && name == "topChange" -> InteractionControlAdapter.shared.changed(view)
+                view.javaClass.name in scrollHosts -> when (name) {
+                    "topScrollBeginDrag" -> InteractionScrollAdapter.shared.began(view, if (view is android.widget.HorizontalScrollView) "x" else "y")
+                    "topScroll" -> InteractionScrollAdapter.shared.moved(view)
+                    "topScrollEndDrag" -> InteractionScrollAdapter.shared.endDrag(view)
+                    "topMomentumScrollEnd" -> InteractionScrollAdapter.shared.finished(view)
+                    else -> Unit
+                }
+            }
+        }
+    }
+    override fun close() {
+        closed = true
+        dispatcher?.removeListener(this); dispatcher = null
+    }
+    companion object {
+        private val names = setOf("topChange", "topEndEditing", "topSubmitEditing", "topScrollBeginDrag", "topScroll", "topScrollEndDrag", "topMomentumScrollEnd")
+        private val scrollHosts = setOf("com.facebook.react.views.scroll.ReactScrollView", "com.facebook.react.views.scroll.ReactHorizontalScrollView")
+        fun install(context: ReactApplicationContext, active: () -> Boolean): RnInteractionEventObserver {
+            val observer = RnInteractionEventObserver({ tag, _ -> UIManagerHelper.getUIManagerForReactTag(context, tag)?.resolveView(tag) }, active)
+            observer.refresh(context)
+            return observer
+        }
+    }
+}

package/android/src/main/java/dev/everframe/rn/RnInteractionEventRegistration.kt

@@ -0,0 +1,127 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 ScriptX
+package dev.everframe.rn
+
+import android.view.View
+import dev.everframe.capture.InteractionEvents
+import dev.everframe.capture.PreparedInteraction
+import java.lang.ref.WeakReference
+import kotlinx.serialization.json.*
+
+/** Queued work owns the original lease. A new runtime cannot renew old refs or callbacks. */
+internal class RnInteractionEventRegistration(
+    private val resolve: (Int) -> View?,
+    private val dispatch: (() -> Unit) -> Unit,
+) : AutoCloseable {
+    private class Request(val tag: Int, val generation: Long, val lease: String, val types: Set<String>) {
+        var view: WeakReference<View>? = null
+        var resolved = false
+        var listener: View.OnAttachStateChangeListener? = null
+    }
+    val runtime = InteractionEvents.openRuntime()
+    private val namespace = "$runtime:"
+    private val requests = mutableMapOf<String, Request>()
+    private class PendingRecord(val item: PreparedInteraction, val id: String, val generation: Long)
+    private val records = ArrayDeque<PendingRecord>()
+    private var recordDrainScheduled = false
+    @Volatile private var closed = false
+    fun active(): Boolean = !closed && InteractionEvents.ownsRuntime(runtime)
+    fun lease(): String = if (active()) InteractionEvents.lease() ?: "" else ""
+    private fun integer(value: Double, max: Double) = value.isFinite() && value >= 0 && value <= max && value == value.toLong().toDouble()
+    private fun validId(id: String) = id.isNotEmpty() && id.length <= 128 && id.none { it.code < 32 || it.code == 127 }
+    @Synchronized fun set(tag: Double, id: String, generation: Double, lease: String, json: String): Boolean {
+        if (!active() || !validId(id) || tag <= 0 || !integer(tag,Int.MAX_VALUE.toDouble()) || !integer(generation,9007199254740990.0) || lease.isEmpty() || lease != lease()) return false
+        if (json.toByteArray(Charsets.UTF_8).size > 8192) return false
+        val options = runCatching { Json.parseToJsonElement(json) as? JsonObject }.getOrNull() ?: return false
+        val list = options["helperTypes"] as? JsonArray ?: return false
+        if (list.size > 3) return false
+        val types = list.map { (it as? JsonPrimitive)?.takeIf { it.isString }?.content ?: return false }.toSet()
+        if (!setOf("text_edit","control_change","scroll").containsAll(types)) return false
+        // JS callbacks have no immutable native privacy proof at observation.
+        // Keep annotations while leaving all native automatic observation active.
+        requests.filterValues { it.lease != lease }.values.forEach(::detachListener)
+        requests.entries.removeAll { it.value.lease != lease }
+        if (requests.size >= 4096 && !requests.containsKey(id)) return false
+        if (!InteractionEvents.beginRegistration(namespace+id,generation.toLong(),lease,json)) return false
+        val request = Request(tag.toInt(),generation.toLong(),lease,emptySet())
+        requests.put(id,request)?.let(::detachListener); enqueue(id,request)
+        return true
+    }
+    private fun enqueue(id: String, request: Request) {
+        dispatch {
+            synchronized(this) {
+                if (!active() || request.lease != lease() || requests[id] !== request || request.resolved) return@dispatch
+                val view = runCatching { resolve(request.tag) }.getOrNull() ?: return@dispatch
+                if (!view.isAttachedToWindow || view.id != request.tag) return@dispatch
+                request.view = WeakReference(view); request.resolved = true
+                if (InteractionEvents.completeRegistration(view,namespace+id,request.generation,request.lease,request.types)) {
+                    val owner = WeakReference(this)
+                    val nativeId = namespace+id
+                    val listener = object : View.OnAttachStateChangeListener {
+                        override fun onViewAttachedToWindow(view: View) = Unit
+                        override fun onViewDetachedFromWindow(view: View) {
+                            view.removeOnAttachStateChangeListener(this)
+                            InteractionEvents.cancelRegistration(nativeId,request.generation)
+                            owner.get()?.let { bridge -> synchronized(bridge) { if (bridge.requests[id] === request) bridge.requests.remove(id) } }
+                        }
+                    }
+                    request.listener = listener; view.addOnAttachStateChangeListener(listener)
+                }
+            }
+        }
+    }
+    private fun detachListener(request: Request) {
+        dispatch { request.listener?.let { request.view?.get()?.removeOnAttachStateChangeListener(it) }; request.listener = null }
+    }
+    @Synchronized fun onMount() {
+        if (!active()) return
+        requests.filterValues { it.lease != lease() }.values.forEach(::detachListener)
+        requests.entries.removeAll { it.value.lease != lease() }
+        requests.filterValues { !it.resolved }.forEach { (id,request) -> enqueue(id,request) }
+    }
+    @Synchronized fun clear(id: String, generation: Double): Boolean {
+        if (!active() || !validId(id) || !integer(generation,9007199254740991.0)) return false
+        if (!InteractionEvents.clearRegistration(namespace+id,generation.toLong())) return false
+        requests.remove(id)?.let(::detachListener); return true
+    }
+    @Synchronized fun record(lease: String, id: String, generation: Double, json: String): Boolean {
+        if (!active() || !integer(generation,9007199254740991.0) || (id.isNotEmpty() && !validId(id))) return false
+        val prepared = InteractionEvents.prepare(lease,if (id.isEmpty()) "" else namespace+id,generation.toLong(),json) ?: return false
+        // Native coalescing/revocation can empty a prepared cell before main runs.
+        // Bound those cells too, and enqueue only one callback for the mailbox.
+        if (records.size == 64) InteractionEvents.discardPrepared(records.removeFirst().item)
+        records.addLast(PendingRecord(prepared,id,generation.toLong()))
+        if (!recordDrainScheduled) { recordDrainScheduled = true; scheduleRecordDrain() }
+        return true
+    }
+    private fun scheduleRecordDrain() {
+        val owner = WeakReference(this)
+        dispatch { owner.get()?.drainRecords() }
+    }
+    private fun drainRecords() {
+        // Yield after a bounded batch even if producers keep refilling the mailbox.
+        repeat(64) {
+            synchronized(this) {
+                if (records.isEmpty()) return@repeat
+                val pending = records.removeFirst()
+                try {
+                    if (!active()) return@repeat
+                    if (pending.id.isNotEmpty()) {
+                        val request = requests[pending.id] ?: return@repeat
+                        val view = request.view?.get() ?: return@repeat
+                        if (request.generation != pending.generation || resolve(request.tag) !== view) return@repeat
+                    }
+                    InteractionEvents.recordPrepared(pending.item)
+                } finally { InteractionEvents.discardPrepared(pending.item) }
+            }
+        }
+        synchronized(this) {
+            if (records.isEmpty()) recordDrainScheduled = false else scheduleRecordDrain()
+        }
+    }
+    @Synchronized override fun close() {
+        closed = true
+        records.forEach { InteractionEvents.discardPrepared(it.item) }; records.clear()
+        requests.values.forEach(::detachListener); requests.clear(); InteractionEvents.closeRuntime(runtime)
+    }
+}

package/android/src/main/java/dev/everframe/rn/RnInteractionTargetAdapter.kt

@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 ScriptX
+package dev.everframe.rn
+
+import android.view.View
+import com.facebook.react.ReactRootView
+import com.facebook.react.uimanager.ReactAccessibilityDelegate.AccessibilityRole
+import com.facebook.react.uimanager.ReactAccessibilityDelegate.Role
+import dev.everframe.capture.InteractionTargetViewAdapter
+import dev.everframe.capture.InteractionTargetViewHints
+import java.util.Locale
+
+internal object RnInteractionTargetAdapter : InteractionTargetViewAdapter {
+    override fun describe(view: View): InteractionTargetViewHints? {
+        val testId = view.getTag(com.facebook.react.R.id.react_test_id) as? String
+        val rawRole = ((view.getTag(com.facebook.react.R.id.role) as? Role)?.name
+            ?: (view.getTag(com.facebook.react.R.id.accessibility_role) as? AccessibilityRole)?.name)?.lowercase(Locale.ROOT)
+        val role = when (rawRole) {
+            "imagebutton" -> "button"
+            "adjustable" -> "slider"
+            "edittext", "search", "searchbox", "textbox" -> "textfield"
+            "heading" -> "header"
+            "img" -> "image"
+            "none", null -> null
+            else -> rawRole
+        }
+        return InteractionTargetViewHints(testId = testId, role = role,
+            // ReactSurfaceView (Fabric) also extends ReactRootView. The module
+            // identity is assigned by the framework, independent of rendered labels.
+            devtools = view is ReactRootView && runCatching { view.jsModuleName in setOf("LogBox", "DevMenu") }.getOrDefault(false),
+            actionable = role in setOf("button", "tab", "link", "switch", "checkbox", "radio", "slider", "menuitem", "textfield"))
+    }
+}