@sceneview-sdk/react-native 4.25.0 → 4.27.0

package/README.md

@@ -7,8 +7,14 @@
 React Native bindings for [SceneView](https://sceneview.github.io) — 3D and AR scenes powered by Filament (Android) and RealityKit (iOS).
 
 > **Status:** Alpha — 3D model loading works on both platforms. AR scene is
-> functional on Android. The iOS native bridge compiles against the real
-> `SceneViewSwift` API and is CI-verified (`.github/workflows/rn-ios-compile.yml`).
+> functional on Android. The iOS native bridge is CI-verified against the real
+> `SceneViewSwift` API **and the real React Native API**
+> (`.github/workflows/rn-ios-compile.yml`): both modules come from an actual
+> build — SceneViewSwift from SwiftPM, React from the demo's `pod install` —
+> and the job proves each import is load-bearing before trusting the result.
+> It type-checks `ios/*.swift` only: it does not link, does not run, and does
+> not compile the Obj-C `RCT_EXTERN_MODULE` glue in `ios/RNSceneViewManager.m`
+> that exposes the module to JS.
 
 ## Features
 
@@ -21,25 +27,17 @@ React Native bindings for [SceneView](https://sceneview.github.io) — 3D and AR
 
 ## Installation
 
-> **Status note (May 2026):** the npm registry currently has
-> `@sceneview-sdk/react-native@3.6.1` as `latest`. The 4.0.x line of this
-> bridge — including the type-safe `unlit` prop and the v4 SceneView
-> bindings — has not yet been published to npm. Tracked in
-> [#924](https://github.com/sceneview/sceneview/issues/924) and
-> [#962](https://github.com/sceneview/sceneview/issues/962) (publish-rn
-> GitHub Actions job lands automatically on the next `v4.0.x` tag).
-> To pin against the latest source today, prefer the GitHub-package
-> snippet at the bottom of this section.
-
 ```sh
 npm install @sceneview-sdk/react-native
 ```
 
-…or to ride main directly until the 4.0.x publish lands:
+The `publish-rn` job publishes this bridge on every `vX.Y.Z` tag, so `latest`
+on npm tracks the current SceneView release (#924, #962).
 
-```sh
-npm install github:sceneview/sceneview#v4.0.9 --save  # path includes react-native/react-native-sceneview/
-```
+There is no GitHub-install fallback: this is a monorepo with no root
+`package.json`, so `npm install github:sceneview/sceneview` cannot resolve the
+module at `react-native/react-native-sceneview/`. To build against unreleased
+source, clone the repo and `npm install <path-to-clone>/react-native/react-native-sceneview`.
 
 ### iOS
 
@@ -47,15 +45,32 @@ npm install github:sceneview/sceneview#v4.0.9 --save  # path includes react-nati
 cd ios && pod install
 ```
 
-Requires iOS 17+ and Xcode 15+.
+Requires iOS 18+ and Xcode 16+ — `SceneViewSwift`'s own floor is iOS 18.0
+(`SceneViewSwift/Package.swift`), so the host app's `Podfile` must declare
+`platform :ios, '18.0'` rather than React Native's `min_ios_version_supported`
+(13.4), or `pod install` fails to resolve this module.
 
 **The host app must add `SceneViewSwift` via Swift Package Manager.**
 `SceneViewSwift` ships as a SwiftPM package only (no CocoaPods spec), so this
 module's podspec deliberately does **not** declare it as a `s.dependency` —
 add it once in Xcode (*File ▸ Add Package Dependencies…*):
 
-- URL: `https://github.com/sceneview/SceneViewSwift`
-- Version: `4.14.0` (or *Up to Next Major*)
+- URL: `https://github.com/sceneview/sceneview`
+- Version: `4.27.0` (or *Up to Next Major*)
+
+Unlike the Flutter plugin's pub.dev range, this version tracks the SDK release
+directly: SwiftPM resolves against a git tag in this same repository, which the
+release creates, so it is never ahead of something that does not exist yet.
+
+> **Keep the two versions in step.** npm `4.27.0`'s Swift requires SPM tag
+> `v4.27.0` or newer: this module's `ios/*.swift` builds on
+> `SceneViewerHostView` — which landed *after* `v4.26.0`, so no `SceneViewer*`
+> type exists at that tag or any earlier one — and it calls the two-parameter
+> `onTapEntity` (the tapped model root is the second parameter). A mismatch is a
+> loud Swift compile error at build time, not a runtime surprise, but no CI job
+> here will catch it for you: `rn-ios-compile.yml` type-checks against the
+> `SceneViewSwift` sources *in this repo*, not against the tag your app
+> resolves.
 
 The module's `ios/*.swift` `import SceneViewSwift` resolves against that
 app-level package at build time.
@@ -84,7 +99,7 @@ import { SceneView } from '@sceneview-sdk/react-native';
   style={{ flex: 1 }}
   environment="environments/studio_small.hdr"
   modelNodes={[{ src: 'models/damaged_helmet.glb', position: [0, 0, -2] }]}
-  cameraOrbit
+  cameraControlMode="orbit"
 />
 ```
 
@@ -109,15 +124,23 @@ import { ARSceneView } from '@sceneview-sdk/react-native';
 | `modelNodes`        | `ModelNode[]`        | `[]`      | Models to render                         |
 | `geometryNodes`     | `GeometryNode[]`     | `[]`      | Geometry nodes (forward-compatible)      |
 | `lightNodes`        | `LightNode[]`        | `[]`      | Light nodes (forward-compatible)         |
-| `cameraOrbit`       | `boolean`            | `true`    | Enable orbit camera controls             |
+| `cameraOrbit`       | `boolean`            | `true`    | **Deprecated**, inert on iOS — use `cameraControlMode` |
 | `cameraControlMode` | `CameraControlMode`  | `'orbit'` | Camera mode (v4.3.0). `'pan'`/`'firstPerson'` are iOS-only |
 | `autoCenterContent` | `boolean`            | `true`    | Auto-centre content on first frame (v4.3.0, iOS-first) |
-| `onTap`             | `function`           | —         | Tap callback (event pending)             |
+| `onTap`             | `function`           | —         | Tap callback — `{ x, y, z, nodeName }`   |
 
 `cameraControlMode` `'pan'` and `'firstPerson'` are iOS-only in v4.3.0; on
 Android they fall back to orbit. `autoCenterContent` is iOS-first — the
 Android side is tracked in issue #1051.
 
+`cameraOrbit` is **deprecated and inert on iOS**. It predates
+`cameraControlMode`, and the two contradict each other — nothing can say which
+should win for `cameraOrbit: false, cameraControlMode: 'orbit'` — so the iOS
+bridge reads only `cameraControlMode`. Note this leaves **no** way to freeze the
+camera from this bridge on iOS: `SceneViewSwift` has `cameraGesturesEnabled`,
+but the React Native surface does not expose it yet. `cameraOrbit: false` still
+works on Android.
+
 ### Props — ARSceneView (extends SceneView)
 
 | Prop                | Type       | Default | Description                               |
@@ -176,8 +199,12 @@ requireNativeComponent('RNSceneView' / 'RNARSceneView')
     +---> Android: ViewManager -> ComposeView -> SceneView { } / ARSceneView { }
     |                              (Filament, SceneView SDK)
     |
-    +---> iOS: RCTViewManager -> UIHostingController -> SceneView / ARSceneView
-                                  (RealityKit, SceneViewSwift)
+    +---> iOS 3D: RCTViewManager -> SceneViewerHostView -> SceneView
+    |                                (RealityKit, SceneViewSwift — the same host
+    |                                 the Flutter plugin and sceneview-compose use)
+    |
+    +---> iOS AR: RCTViewManager -> UIHostingController -> ARSceneView
+                                     (RealityKit, SceneViewSwift)
 ```
 
 Props are mapped from the React Native bridge to native view parameters on each platform.
@@ -191,8 +218,22 @@ coverage map (tracked in [#909](https://github.com/sceneview/sceneview/issues/90
   the iOS RealityKit port is not yet bridged.
 - **`depthOcclusion` / `instantPlacement`** — declared as props but **not
   configured natively** on either platform. Setting them has no effect today.
-- **`onTap` / `onPlaneDetected`** — declared, but the native side does not yet
-  dispatch these events, so the callbacks never fire.
+- **`onPlaneDetected`** — dispatched on **Android** only; SceneViewSwift's
+  `ARSceneView` exposes no plane-detection callback, so it never fires on iOS.
+- **`onTap`** — dispatched on both platforms and on both views. On `SceneView`
+  (3D) it carries the tapped model's world position and its file base name
+  without extension as `nodeName`, identically on Android and iOS. On
+  `ARSceneView` *what a hit reports* differs: **Android** hit-tests the AR
+  scene, so a tap on a model reports that model's file base name just as
+  `SceneView` does and a plane hit or a miss reports `null`; **iOS** always
+  reports `null`, because SceneViewSwift's `ARSceneView` exposes no entity
+  hit-test hook and its tap can only resolve the surface point
+  ([#2051](https://github.com/sceneview/sceneview/issues/2051)). Every dispatch
+  path still writes the key, so `nodeName == null` is the single "the tap hit no
+  model" test — it is never `undefined`. *How often* it dispatches differs
+  though: on iOS a tap that hits no entity fires no `onTap` at all (RealityKit's
+  gesture is entity-targeted), where Android dispatches a `0, 0, 0` miss — so
+  the two platforms do not deliver the same number of tap events.
 - **`environment` on `ARSceneView`** — AR scenes use the camera feed; the HDR
   environment is accepted but not applied.
 - **`ModelNode.scale`** — parsed as a uniform float; the per-axis `[x, y, z]`
@@ -208,6 +249,38 @@ coverage map (tracked in [#909](https://github.com/sceneview/sceneview/issues/90
 
 See [CONTRIBUTING.md](https://github.com/sceneview/sceneview/blob/main/.github/CONTRIBUTING.md).
 
+### Local checks
+
+From this directory, after `npm ci`:
+
+```bash
+npm run lint        # Biome (repo-root biome.json) — lint + format + import assists
+npm run lint:fix    # same, applying the safe fixes
+npm run typescript  # tsc --noEmit
+npm test            # jest
+```
+
+All four run on every PR that touches this package's TypeScript, via
+[`.github/workflows/rn-ts-check.yml`](https://github.com/sceneview/sceneview/blob/main/.github/workflows/rn-ts-check.yml).
+They do not all cover the same files:
+
+| check | covers |
+|---|---|
+| `lint` | `src/`, `__tests__/`, `example/src/` |
+| `typescript` | `src/` only — that is `tsconfig.json`'s `include` |
+| `test` | `__tests__/` |
+
+The linter is **Biome**, not ESLint — the repo has a single JS/TS rule set in
+the root `biome.json`, and those three directories are listed in its
+`files.includes`. The `lint` scripts `cd` to the repo root before invoking
+Biome, mirroring `mcp/package.json`'s script; Biome also walks up and finds the
+root config on its own, so calling `./node_modules/.bin/biome check .` from
+this directory works too.
+
+Note that most rules in `biome.json` are **warning** severity, so `npm run
+lint` can exit 0 with findings still printed. Read its output, don't just read
+its exit code.
+
 ## License
 
 Apache-2.0 — see [LICENSE](LICENSE) for details.

package/android/build.gradle.kts

@@ -18,11 +18,32 @@ android {
         minSdk = 24
     }
 
+    // Explicit and REQUIRED — not boilerplate. Without it AGP defaults Java to
+    // 1.8 while the Kotlin plugin picks the toolchain JDK, and the build dies
+    // with "Inconsistent JVM-target compatibility detected for tasks
+    // 'compileReleaseJavaWithJavac' (1.8) and 'compileReleaseKotlin' (22)".
+    // A host RN app does NOT fix this for us: React Native's Gradle plugin
+    // supplies plugin versions, never a library module's JVM target. 17 matches
+    // the Flutter plugin (`flutter/sceneview_flutter/android/build.gradle`) and
+    // React Native's own JDK 17 requirement. Caught by the standalone compile
+    // gate (`tools/rn-android-compile`, #3042) the first time this module was
+    // ever compiled by CI.
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+
     buildFeatures {
         compose = true
     }
 }
 
+kotlin {
+    compilerOptions {
+        jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17)
+    }
+}
+
 dependencies {
     // SceneView — track the last PUBLISHED release on Maven Central (4.7.0).
     // The bridge Kotlin already targets the 4.x API surface (the `SceneView { }`

package/android/src/main/java/io/github/sceneview/reactnative/ARSceneViewManager.kt

@@ -191,6 +191,11 @@ class ARSceneViewManager : SimpleViewManager<FrameLayout>() {
                                 autoAnimate = model.animate,
                                 position = model.position,
                                 rotation = model.rotation,
+                                apply = {
+                                    // The tap payload's `nodeName` — see
+                                    // [ModelNodeData.nodeName] (PR #3037).
+                                    name = model.nodeName()
+                                },
                             )
                         }
                     }

package/android/src/main/java/io/github/sceneview/reactnative/SceneViewEvents.kt

@@ -13,8 +13,14 @@ import io.github.sceneview.node.Node
  * RN Fabric event delivered to the JS `onTap` prop of `<SceneView>` / `<ARSceneView>`.
  *
  * Payload mirrors the TypeScript `TapEvent` interface in `src/index.tsx`:
- * `{ x, y, z, nodeName? }`. Wired in [SceneViewManager] / [ARSceneViewManager]
- * via `getExportedCustomDirectEventTypeConstants` (issue #2053).
+ * `{ x, y, z, nodeName }` — the key is never optional. [getEventData] writes it
+ * on every dispatch, `putNull` when no node was hit, so JS sees `null` and never
+ * `undefined`. Wired in [SceneViewManager] / [ARSceneViewManager] via
+ * `getExportedCustomDirectEventTypeConstants` (issue #2053).
+ *
+ * Both managers share this event, so an AR tap that lands on a model reports
+ * that model's name exactly as the 3D view does. iOS AR cannot: its
+ * `ARSceneView` has no entity hit-test hook and always reports `null` (#2051).
  */
 class TapEvent(
     surfaceId: Int,

package/android/src/main/java/io/github/sceneview/reactnative/SceneViewManager.kt

@@ -151,6 +151,13 @@ class SceneViewManager : SimpleViewManager<FrameLayout>() {
                                 autoAnimate = model.animate,
                                 position = model.position,
                                 rotation = model.rotation,
+                                apply = {
+                                    // The tap payload's `nodeName`. Without a name the
+                                    // hit-tested ModelNode reports `null` for every model
+                                    // tap, while iOS reports the model file's base name —
+                                    // so name the node the same way here (PR #3037).
+                                    name = model.nodeName()
+                                },
                             )
                         }
                     }
@@ -383,7 +390,28 @@ data class ModelNodeData(
     val animate: Boolean = true,
     val position: Position = Position(x = 0f),
     val rotation: Rotation = Rotation(x = 0f),
-)
+) {
+    /**
+     * The name reported as the tap payload's `nodeName`: the model file's base
+     * name without extension, matching the iOS bridge (which names each loaded
+     * model root after its file and strips the extension on tap).
+     *
+     * [src] is documented as an "asset path **or URL**", and `ModelLoader`
+     * really does load `https://` sources, so the query and fragment are
+     * stripped FIRST. Cutting at the last `.` on a raw URL only works when the
+     * extension is the last dot in the whole string: for
+     * `https://cdn/robot.glb?sig=SIG&v=1.2` it yields
+     * `robot.glb?sig=SIG&v=1` — a CDN signature leaking into a payload that
+     * apps routinely put in a label or an analytics event.
+     *
+     * `null` for a path with no usable base name, so the payload stays
+     * `nodeName: null` rather than an empty string.
+     */
+    fun nodeName(): String? =
+        src.substringBefore('?').substringBefore('#')
+            .substringAfterLast('/').substringBeforeLast('.')
+            .takeIf { it.isNotEmpty() }
+}
 
 data class GeometryNodeData(
     val type: String,

package/ios/SceneViewModule.swift

@@ -18,6 +18,48 @@ struct RNModelData: Identifiable, Equatable {
     }
 }
 
+// MARK: - Tap payload
+
+/// Builds the JS `onTap` payload — the iOS counterpart of Android's single
+/// `TapEvent.getEventData()`.
+///
+/// Both iOS views go through here so `nodeName` is written on *every* dispatch
+/// path, never merely on the ones that happen to have a name: a missed tap
+/// reports `NSNull()`, which crosses the bridge as the same JS `null` Android
+/// emits via `putNull`. That is what lets the public `TapEvent.nodeName` be
+/// typed `string | null` instead of `string | null | undefined` — a consumer
+/// writes one `nodeName == null` guard.
+///
+/// This iOS `ARSceneView` can only resolve a surface point, never an entity, so
+/// it always passes `nil`. That is a platform limitation, not the contract:
+/// Android's AR view hit-tests the scene and does name the tapped model. Naming
+/// it here needs an entity hit-test hook on `SceneViewSwift.ARSceneView`, which
+/// does not exist yet (#2051).
+///
+/// Keeping this a single function (rather than a comment asking each call site
+/// to remember the key) is the guard: a new tap source cannot omit `nodeName`
+/// without skipping the only payload builder in the bridge.
+func rnTapPayload(worldPosition: SIMD3<Float>, nodeName: String?) -> [String: Any] {
+    // Seeded with the null sentinel, then overwritten — so the key exists
+    // before any branch runs and no path can drop it.
+    var payload: [String: Any] = [
+        "x": worldPosition.x,
+        "y": worldPosition.y,
+        "z": worldPosition.z,
+        "nodeName": NSNull(),
+    ]
+    // An empty name is "no model", not a model called "". Android already
+    // collapses it (`SceneViewManager.nodeName()` ends in
+    // `takeIf { it.isNotEmpty() }`); collapsing it here rather than at the call
+    // sites is what keeps the two platforms on ONE sentinel, for the same
+    // reason the key is seeded above — a future tap source cannot reintroduce
+    // the empty string without going around the only payload builder.
+    if let nodeName, !nodeName.isEmpty {
+        payload["nodeName"] = nodeName
+    }
+    return payload
+}
+
 // MARK: - SceneView (3D)
 
 /// RCTViewManager subclass that bridges React Native's `<RNSceneView>`
@@ -34,35 +76,43 @@ class RNSceneViewManager: RCTViewManager {
     }
 }
 
-/// Maps the wire string sent from JS to a `CameraControlMode` (v4.3.0).
-/// Unknown values fall back to `.orbit`.
-func rnCameraControlMode(_ raw: String?) -> CameraControlMode {
-    switch raw {
-    case "pan": return .pan
-    case "firstPerson": return .firstPerson
-    default: return .orbit
-    }
-}
-
-/// Observable state model shared between React props and SwiftUI view.
+/// State model backing the React props.
+///
+/// Still an `ObservableObject` for shape consistency with `RNARSceneState`, which
+/// genuinely drives SwiftUI; nothing observes this one since the 3D scene moved
+/// onto `SceneViewerHostView`.
 @MainActor
 class RNSceneState: ObservableObject {
     @Published var models: [RNModelData] = []
     @Published var environmentPath: String?
+
+    /// Accepted, stored, and deliberately not applied — as before this bridge
+    /// moved onto the shared host.
+    ///
+    /// `cameraControlMode` supersedes it and the two would contradict each other
+    /// (which wins for `cameraOrbit: false, cameraControlMode: "orbit"`?). Wiring
+    /// it up here would be a behaviour change dressed as a refactor, so it stays
+    /// inert; the TypeScript surface deprecates it.
     @Published var cameraOrbit: Bool = true
-    @Published var cameraControlMode: CameraControlMode = .orbit
-    @Published var autoCenterContent: Bool = true
 
-    /// Invoked from the SwiftUI content's `onEntityTapped` modifier so the
-    /// wrapper can forward the tap to React Native's `onTap` prop (issue #2053).
-    /// Not `@Published` — it is plumbing, not rendered state.
-    var onTap: ((Entity) -> Void)?
+    /// Wire name as it arrives from JS: `"orbit"`, `"pan"` or `"firstPerson"`.
+    /// `SceneViewerConfiguration` normalises an unrecognised value to `"orbit"`,
+    /// which is what the local mapping this replaces did.
+    @Published var cameraControlMode: String = "orbit"
+
+    @Published var autoCenterContent: Bool = true
 }
 
-/// UIView wrapper that hosts a SwiftUI `SceneView` via UIHostingController.
+/// UIView wrapper hosting the shared `SceneViewerHostView`.
+///
+/// This class owns the React prop bag; the scene itself — hosting SwiftUI in
+/// UIKit, loading models, reconciling them — belongs to `SceneViewerHostView`
+/// and is shared with the Flutter plugin and `sceneview-compose`. The AR wrapper
+/// below keeps its own SwiftUI content: `ARSceneView` is anchor-driven and
+/// shares nothing with the 3D viewer.
 class RNSceneViewWrapper: UIView {
 
-    private var hostingController: UIHostingController<RNSceneViewContent>?
+    private let hostView = SceneViewerHostView()
     private let sceneState = RNSceneState()
 
     /// Event callback for tap events.
@@ -70,16 +120,21 @@ class RNSceneViewWrapper: UIView {
         didSet {
             let block = onTap
             Task { @MainActor in
-                sceneState.onTap = { entity in
+                // `onTapEntity` rather than the host's flattened `onTap`: this
+                // prop reports the tapped *model* — its own origin and its file
+                // base name — where the flattened callback carries the hit's
+                // bounds centre and no name at all.
+                //
+                // The model root is what the host resolves, so a tap inside a
+                // USDZ that names its meshes reports the model, not `skin0`.
+                hostView.onTapEntity = { _, modelRoot in
                     // Mirrors the Android `TapEvent` payload: world-space
-                    // coordinates of the tapped entity + its node name.
-                    let p = entity.position(relativeTo: nil)
-                    block?([
-                        "x": p.x,
-                        "y": p.y,
-                        "z": p.z,
-                        "nodeName": entity.name,
-                    ])
+                    // coordinates of the tapped model (`node.worldPosition`
+                    // there) + its node name, `null` when nothing was hit.
+                    block?(rnTapPayload(
+                        worldPosition: modelRoot?.position(relativeTo: nil) ?? .zero,
+                        nodeName: modelRoot.map { ($0.name as NSString).deletingPathExtension }
+                    ))
                 }
             }
         }
@@ -96,12 +151,55 @@ class RNSceneViewWrapper: UIView {
     }
 
     private func setupView() {
-        let content = RNSceneViewContent(state: sceneState)
-        let hosting = UIHostingController(rootView: content)
-        hosting.view.frame = bounds
-        hosting.view.autoresizingMask = [.flexibleWidth, .flexibleHeight]
-        addSubview(hosting.view)
-        hostingController = hosting
+        hostView.frame = bounds
+        hostView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
+        addSubview(hostView)
+    }
+
+    /// Pushes the current props into the host view.
+    ///
+    /// Called after every prop change. `applyConfiguration` compares field by
+    /// field and touches only what changed, so re-sending everything on each
+    /// prop update costs nothing.
+    @MainActor
+    private func applyState() {
+        let configuration = SceneViewerConfiguration()
+
+        configuration.models = sceneState.models.map { data in
+            let model = SceneViewerModel()
+            model.assetPath = data.path
+            // The per-entry id minted when the prop was decoded. A new
+            // `modelNodes` value mints new ids, which is what gives this prop
+            // its replace-the-whole-list semantics.
+            model.identity = data.id.uuidString
+            model.setScale(data.scale.x, data.scale.y, data.scale.z)
+            model.setPosition(data.position.x, data.position.y, data.position.z)
+            model.animationName = data.animation
+            // No named animation means play them all, which is this bridge's
+            // behaviour and not the Flutter one's.
+            model.autoPlayAllAnimations = true
+            // The file's name — with its extension, which the tap report
+            // strips. This is the only entity the bridge names, and the host
+            // resolves a tap to exactly it, so it is what JS receives as
+            // `nodeName`. Matches Android's `ModelNodeData.nodeName()`.
+            model.nodeName = sceneViewerModelFileName(data.path)
+            return model
+        }
+
+        configuration.cameraControlMode = sceneState.cameraControlMode
+        configuration.autoCenterContent = sceneState.autoCenterContent
+        // This bridge exposes no camera prop, so it authors no pose: without
+        // this, every prop change would re-assert the configuration's default
+        // pose and snap the camera back out of the auto-centre framing and away
+        // from wherever the user had orbited to.
+        configuration.cameraPoseAuthored = false
+
+        if let path = sceneState.environmentPath, !path.isEmpty {
+            configuration.environmentKind = "hdr"
+            configuration.environmentHdrPath = path
+        }
+
+        hostView.applyConfiguration(configuration)
     }
 
     // MARK: - React props
@@ -110,6 +208,7 @@ class RNSceneViewWrapper: UIView {
         didSet {
             Task { @MainActor in
                 sceneState.environmentPath = environment
+                applyState()
             }
         }
     }
@@ -136,10 +235,12 @@ class RNSceneViewWrapper: UIView {
                     let animation = dict["animation"] as? String
                     return RNModelData(path: src, scale: scale, position: position, animation: animation)
                 } ?? []
+                applyState()
             }
         }
     }
 
+    /// **Deprecated.** Superseded by `cameraControlMode`; see `RNSceneState.cameraOrbit`.
     @objc var cameraOrbit: Bool = true {
         didSet {
             Task { @MainActor in
@@ -151,9 +252,10 @@ class RNSceneViewWrapper: UIView {
     /// Camera interaction mode (v4.3.0, issue #1053).
     @objc var cameraControlMode: String? {
         didSet {
-            let mode = rnCameraControlMode(cameraControlMode)
+            let raw = cameraControlMode
             Task { @MainActor in
-                sceneState.cameraControlMode = mode
+                sceneState.cameraControlMode = raw ?? "orbit"
+                applyState()
             }
         }
     }
@@ -163,78 +265,7 @@ class RNSceneViewWrapper: UIView {
         didSet {
             Task { @MainActor in
                 sceneState.autoCenterContent = autoCenterContent
-            }
-        }
-    }
-}
-
-/// SwiftUI content view rendering `SceneViewSwift.SceneView` (issue #2067).
-///
-/// `SceneViewSwift` loads models **asynchronously** (`ModelNode.load(_:)` is
-/// `async throws`) — there is no synchronous `ModelNode(String)` initialiser,
-/// and the `@NodeBuilder` content builder composes static `EntityProvider`
-/// values, not a SwiftUI `ForEach`. So the bridge loads each `RNModelData`
-/// off the main actor's `Task`, wraps the resulting `ModelEntity`s in a
-/// stable holder entity, and feeds that holder to `SceneView`'s **imperative**
-/// `init(_ content: (Entity) -> Void)`.
-///
-/// `SceneView`'s content closure runs once when the underlying `RealityView`
-/// is created, so the holder entity is built up front and re-populated in a
-/// `.task(id:)` whenever the JS `modelNodes` prop changes — RealityKit picks
-/// up the new children on its next render frame without recreating the view.
-struct RNSceneViewContent: View {
-    @ObservedObject var state: RNSceneState
-
-    /// Stable parent entity handed to `SceneView`. Its children are the
-    /// loaded model entities; rebuilt by `loadModels()` on every prop change.
-    @State private var modelRoot = Entity()
-
-    var body: some View {
-        SceneView { root in
-            root.addChild(modelRoot)
-        }
-        .cameraControls(state.cameraControlMode)
-        .autoCenterContent(state.autoCenterContent)
-        // Forward entity taps to React Native's `onTap` prop (issue #2053).
-        .onEntityTapped { entity in
-            state.onTap?(entity)
-        }
-        // Reload whenever the JS `modelNodes` prop changes. Keyed on the
-        // model identities so an unrelated re-render does not re-download.
-        .task(id: state.models.map(\.id)) {
-            await loadModels()
-        }
-    }
-
-    /// Loads every model in `state.models` and replaces `modelRoot`'s
-    /// children with the freshly loaded entities. `ModelNode.load(_:)` is
-    /// `@MainActor`-isolated, so this runs on the main actor as required by
-    /// RealityKit. A failed load is skipped (the others still render).
-    @MainActor
-    private func loadModels() async {
-        // Clear previous content before reloading.
-        for child in modelRoot.children {
-            child.removeFromParent()
-        }
-        for model in state.models {
-            do {
-                let node = try await ModelNode.load(model.path)
-                // `.task(id:)` cancels this task when the `modelNodes` prop
-                // changes mid-load. A cancelled task still resumes past the
-                // `await`, so bail out before mutating the scene — otherwise a
-                // superseded load leaks a stale model into `modelRoot`.
-                guard !Task.isCancelled else { return }
-                node.position(model.position)
-                node.scale(model.scale)
-                if let animation = model.animation {
-                    node.playAnimation(named: animation)
-                } else if node.animationCount > 0 {
-                    node.playAllAnimations()
-                }
-                modelRoot.addChild(node.entity)
-            } catch {
-                // A single bad path must not break the whole scene.
-                print("[RNSceneView] Failed to load model '\(model.path)': \(error)")
+                applyState()
             }
         }
     }
@@ -284,12 +315,14 @@ class RNARSceneViewWrapper: UIView {
                 sceneState.onTap = { worldPosition in
                     // Mirrors the Android `TapEvent` payload. `ARSceneView`'s
                     // `onTapOnPlane` reports the tapped surface point, not a
-                    // node, so `nodeName` is left absent.
-                    block?([
-                        "x": worldPosition.x,
-                        "y": worldPosition.y,
-                        "z": worldPosition.z,
-                    ])
+                    // node, so `nodeName` is always `null` here — the same JS
+                    // `null` Android emits via `putNull` and the 3D view emits
+                    // for a tap that hit no model. It used to omit the key,
+                    // which made JS see `undefined` on this one view.
+                    //
+                    // Android's AR view names the tapped model instead; this
+                    // side cannot until #2051 adds an entity hit-test hook.
+                    block?(rnTapPayload(worldPosition: worldPosition, nodeName: nil))
                 }
             }
         }

package/lib/commonjs/index.js

@@ -7,6 +7,13 @@ exports.SceneView = exports.ARSceneView = exports.ARRecorder = void 0;
 var _react = _interopRequireDefault(require("react"));
 var _reactNative = require("react-native");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+// `tsconfig.json` sets `"jsx": "react"` — the CLASSIC runtime — so every JSX
+// element below compiles to `React.createElement(...)` (verified in the
+// published `lib/commonjs/index.js`). Biome's `useImportType` only sees the
+// `React.FC` type annotations, not the JSX lowering, so it offers a "safe fix"
+// that would erase this import and break the shipped bundle at runtime.
+// biome-ignore lint/style/useImportType: React is a VALUE import — see above.
+
 // ---------------------------------------------------------------------------
 // Node type interfaces
 // ---------------------------------------------------------------------------
@@ -55,9 +62,9 @@ function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e
 // Native components (only available on Android and iOS)
 // ---------------------------------------------------------------------------
 
-const isNativeAvailable = _reactNative.Platform.OS === 'android' || _reactNative.Platform.OS === 'ios';
-const NativeSceneView = isNativeAvailable ? (0, _reactNative.requireNativeComponent)('RNSceneView') : null;
-const NativeARSceneView = isNativeAvailable ? (0, _reactNative.requireNativeComponent)('RNARSceneView') : null;
+const isNativeAvailable = _reactNative.Platform.OS === "android" || _reactNative.Platform.OS === "ios";
+const NativeSceneView = isNativeAvailable ? (0, _reactNative.requireNativeComponent)("RNSceneView") : null;
+const NativeARSceneView = isNativeAvailable ? (0, _reactNative.requireNativeComponent)("RNARSceneView") : null;
 
 // ---------------------------------------------------------------------------
 // Fallback for unsupported platforms
@@ -73,12 +80,12 @@ const UnsupportedView = ({
 const fallbackStyles = _reactNative.StyleSheet.create({
   container: {
     flex: 1,
-    justifyContent: 'center',
-    alignItems: 'center',
-    backgroundColor: '#1a1a2e'
+    justifyContent: "center",
+    alignItems: "center",
+    backgroundColor: "#1a1a2e"
   },
   text: {
-    color: '#aaa',
+    color: "#aaa",
     fontSize: 16
   }
 });
@@ -158,10 +165,10 @@ const NativeARRecorder = _reactNative.NativeModules.RNARRecorder;
 class ARRecorder {
   /** `true` when {@link ARRecorder} is supported on the current platform. */
   static get isSupported() {
-    return _reactNative.Platform.OS === 'ios' && NativeARRecorder != null;
+    return _reactNative.Platform.OS === "ios" && NativeARRecorder != null;
   }
   rejectUnsupported() {
-    return Promise.reject(new Error('ARRecorder is currently only supported on iOS. Android AR session ' + 'recording is tracked in issue #1051.'));
+    return Promise.reject(new Error("ARRecorder is currently only supported on iOS. Android AR session " + "recording is tracked in issue #1051."));
   }
 
   /** Starts an AR session recording. */

package/lib/commonjs/index.js.map

@@ -1 +1 @@
-{"version":3,"names":["_react","_interopRequireDefault","require","_reactNative","e","__esModule","default","isNativeAvailable","Platform","OS","NativeSceneView","requireNativeComponent","NativeARSceneView","UnsupportedView","name","createElement","View","style","fallbackStyles","container","Text","text","StyleSheet","create","flex","justifyContent","alignItems","backgroundColor","color","fontSize","SceneView","props","exports","ARSceneView","NativeARRecorder","NativeModules","RNARRecorder","ARRecorder","isSupported","rejectUnsupported","Promise","reject","Error","start","stop","outputPath","saveToPhotoLibrary","movPath"],"sourceRoot":"../../src","sources":["index.tsx"],"mappings":"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","ignoreList":[]}
+{"version":3,"names":["_react","_interopRequireDefault","require","_reactNative","e","__esModule","default","isNativeAvailable","Platform","OS","NativeSceneView","requireNativeComponent","NativeARSceneView","UnsupportedView","name","createElement","View","style","fallbackStyles","container","Text","text","StyleSheet","create","flex","justifyContent","alignItems","backgroundColor","color","fontSize","SceneView","props","exports","ARSceneView","NativeARRecorder","NativeModules","RNARRecorder","ARRecorder","isSupported","rejectUnsupported","Promise","reject","Error","start","stop","outputPath","saveToPhotoLibrary","movPath"],"sourceRoot":"../../src","sources":["index.tsx"],"mappings":"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","ignoreList":[]}

package/lib/module/index.js

@@ -1,5 +1,11 @@
-import React from 'react';
-import { requireNativeComponent, NativeModules, Platform, View, Text, StyleSheet } from 'react-native';
+// `tsconfig.json` sets `"jsx": "react"` — the CLASSIC runtime — so every JSX
+// element below compiles to `React.createElement(...)` (verified in the
+// published `lib/commonjs/index.js`). Biome's `useImportType` only sees the
+// `React.FC` type annotations, not the JSX lowering, so it offers a "safe fix"
+// that would erase this import and break the shipped bundle at runtime.
+// biome-ignore lint/style/useImportType: React is a VALUE import — see above.
+import React from "react";
+import { NativeModules, Platform, requireNativeComponent, StyleSheet, Text, View } from "react-native";
 
 // ---------------------------------------------------------------------------
 // Node type interfaces
@@ -49,9 +55,9 @@ import { requireNativeComponent, NativeModules, Platform, View, Text, StyleSheet
 // Native components (only available on Android and iOS)
 // ---------------------------------------------------------------------------
 
-const isNativeAvailable = Platform.OS === 'android' || Platform.OS === 'ios';
-const NativeSceneView = isNativeAvailable ? requireNativeComponent('RNSceneView') : null;
-const NativeARSceneView = isNativeAvailable ? requireNativeComponent('RNARSceneView') : null;
+const isNativeAvailable = Platform.OS === "android" || Platform.OS === "ios";
+const NativeSceneView = isNativeAvailable ? requireNativeComponent("RNSceneView") : null;
+const NativeARSceneView = isNativeAvailable ? requireNativeComponent("RNARSceneView") : null;
 
 // ---------------------------------------------------------------------------
 // Fallback for unsupported platforms
@@ -67,12 +73,12 @@ const UnsupportedView = ({
 const fallbackStyles = StyleSheet.create({
   container: {
     flex: 1,
-    justifyContent: 'center',
-    alignItems: 'center',
-    backgroundColor: '#1a1a2e'
+    justifyContent: "center",
+    alignItems: "center",
+    backgroundColor: "#1a1a2e"
   },
   text: {
-    color: '#aaa',
+    color: "#aaa",
     fontSize: 16
   }
 });
@@ -151,10 +157,10 @@ const NativeARRecorder = NativeModules.RNARRecorder;
 export class ARRecorder {
   /** `true` when {@link ARRecorder} is supported on the current platform. */
   static get isSupported() {
-    return Platform.OS === 'ios' && NativeARRecorder != null;
+    return Platform.OS === "ios" && NativeARRecorder != null;
   }
   rejectUnsupported() {
-    return Promise.reject(new Error('ARRecorder is currently only supported on iOS. Android AR session ' + 'recording is tracked in issue #1051.'));
+    return Promise.reject(new Error("ARRecorder is currently only supported on iOS. Android AR session " + "recording is tracked in issue #1051."));
   }
 
   /** Starts an AR session recording. */

package/lib/module/index.js.map

@@ -1 +1 @@
-{"version":3,"names":["React","requireNativeComponent","NativeModules","Platform","View","Text","StyleSheet","isNativeAvailable","OS","NativeSceneView","NativeARSceneView","UnsupportedView","name","createElement","style","fallbackStyles","container","text","create","flex","justifyContent","alignItems","backgroundColor","color","fontSize","SceneView","props","ARSceneView","NativeARRecorder","RNARRecorder","ARRecorder","isSupported","rejectUnsupported","Promise","reject","Error","start","stop","outputPath","saveToPhotoLibrary","movPath"],"sourceRoot":"../../src","sources":["index.tsx"],"mappings":"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","ignoreList":[]}
+{"version":3,"names":["React","NativeModules","Platform","requireNativeComponent","StyleSheet","Text","View","isNativeAvailable","OS","NativeSceneView","NativeARSceneView","UnsupportedView","name","createElement","style","fallbackStyles","container","text","create","flex","justifyContent","alignItems","backgroundColor","color","fontSize","SceneView","props","ARSceneView","NativeARRecorder","RNARRecorder","ARRecorder","isSupported","rejectUnsupported","Promise","reject","Error","start","stop","outputPath","saveToPhotoLibrary","movPath"],"sourceRoot":"../../src","sources":["index.tsx"],"mappings":"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","ignoreList":[]}

package/lib/typescript/src/index.d.ts

@@ -1,5 +1,5 @@
-import React from 'react';
-import { type ViewStyle, type NativeSyntheticEvent } from 'react-native';
+import React from "react";
+import { type NativeSyntheticEvent, type ViewStyle } from "react-native";
 /** A 3D model loaded from a .glb / .gltf file. */
 export interface ModelNode {
     /** Asset path or URL to the glTF/GLB model. */
@@ -26,7 +26,7 @@ export interface ModelNode {
  *   cross-platform bridge-parity umbrella (#909). Use `modelNodes` on iOS.
  */
 export interface GeometryNode {
-    type: 'box' | 'cube' | 'sphere' | 'cylinder' | 'plane';
+    type: "box" | "cube" | "sphere" | "cylinder" | "plane";
     size?: [number, number, number];
     position?: [number, number, number];
     rotation?: [number, number, number];
@@ -52,7 +52,7 @@ export interface GeometryNode {
  *   cross-platform bridge-parity umbrella (#909).
  */
 export interface LightNode {
-    type: 'directional' | 'point' | 'spot';
+    type: "directional" | "point" | "spot";
     intensity?: number;
     color?: string;
     position?: [number, number, number];
@@ -63,12 +63,25 @@ export interface TapEvent {
     x: number;
     y: number;
     z: number;
-    /** Name of the tapped node, if any. */
-    nodeName?: string;
+    /**
+     * Name of the tapped model: its file's base name without extension
+     * (`models/robot.glb` → `robot`), identical on Android and iOS. Never an
+     * asset-internal mesh name — a tap inside a model always reports the model.
+     *
+     * `null` — never `undefined` — when the tap hit no model: an untitled
+     * geometry node or nothing at all on Android, a plane or a miss in Android
+     * AR, and *every* `ARSceneView` tap on iOS, where `SceneViewSwift`'s
+     * `ARSceneView` exposes no entity hit-test hook and so can only resolve the
+     * surface point (#2051).
+     *
+     * Every native dispatch path writes the key, so `nodeName == null` is the one
+     * guard that covers both views on both platforms.
+     */
+    nodeName: string | null;
 }
 export interface PlaneDetectedEvent {
     id: string;
-    type: 'horizontal' | 'vertical';
+    type: "horizontal" | "vertical";
     center: [number, number, number];
     extent: [number, number];
 }
@@ -81,7 +94,7 @@ export interface PlaneDetectedEvent {
  *   back to orbit (the per-mode switch is an iOS-first v4.3.0 addition —
  *   the Android side is tracked in issue #1051).
  */
-export type CameraControlMode = 'orbit' | 'pan' | 'firstPerson';
+export type CameraControlMode = "orbit" | "pan" | "firstPerson";
 export interface SceneViewProps {
     style?: ViewStyle;
     /** HDR environment asset path (e.g. "environments/studio.hdr"). */
@@ -100,7 +113,17 @@ export interface SceneViewProps {
      * **iOS:** acknowledged but not yet rendered — see {@link LightNode}.
      */
     lightNodes?: LightNode[];
-    /** Enable default orbit camera controls. Default: true. */
+    /**
+     * Enable default orbit camera controls. Default: `true`.
+     *
+     * @deprecated Superseded by {@link SceneViewProps.cameraControlMode}, and
+     * **inert on iOS**: the two would contradict each other — nothing can say
+     * which wins for `cameraOrbit: false, cameraControlMode: 'orbit'` — so the
+     * iOS bridge deliberately reads only `cameraControlMode`. Still honoured on
+     * Android. There is currently no way to freeze the camera from this bridge
+     * on iOS; `SceneViewSwift` has `cameraGesturesEnabled` but it is not exposed
+     * here yet.
+     */
     cameraOrbit?: boolean;
     /**
      * Camera interaction mode (v4.3.0). Default: `'orbit'`.
@@ -118,9 +141,30 @@ export interface SceneViewProps {
     /**
      * Called when the user taps inside the scene.
      *
-     * The event payload carries the world-space tap coordinates. On Android the
-     * tapped node's `nodeName` is included when the tap hits a node; on iOS AR
-     * the tap reports the surface point only, so `nodeName` is absent there.
+     * The event payload carries the world-space position of the tapped model and
+     * its `nodeName` (the model file's base name without extension) on both
+     * Android and iOS. A tap that hits no model reports `nodeName: null` — with
+     * the tapped node's real world position on Android when it landed on an
+     * (unnamed) geometry node, and `0, 0, 0` when it hit nothing at all. That
+     * `0, 0, 0` miss is **in practice Android-only**: iOS resolves the tap
+     * through RealityKit's entity-targeted gesture, which fires only on a hit,
+     * so a tap on empty space dispatches no `onTap` event at all — count taps
+     * and you will see fewer events on iOS, not a `0, 0, 0` one. (iOS emits
+     * `0, 0, 0` only if a hit entity resolves outside every loaded model, which
+     * the content root's contents make unreachable today.)
+     *
+     * On {@link ARSceneViewProps | `ARSceneView`} *what a hit reports* differs by
+     * platform:
+     * - **Android**: the AR view hit-tests the scene, so a tap on a model reports
+     *   that model's file base name exactly as `SceneView` does; a tap on a plane
+     *   or on nothing reports `null`.
+     * - **iOS**: always `null` — `SceneViewSwift.ARSceneView` exposes no entity
+     *   hit-test hook, so the AR tap can only resolve the surface point. Tracked
+     *   under {@link https://github.com/sceneview/sceneview/issues/2051 | #2051}.
+     *
+     * The *key* is written on every dispatch path of both views on both
+     * platforms, so one `nodeName == null` check remains the correct "the tap hit
+     * no model" test everywhere; it is never omitted and never `undefined`.
      */
     onTap?: (event: NativeSyntheticEvent<TapEvent>) => void;
 }

package/lib/typescript/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.tsx"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sceneview-sdk/react-native",
-  "version": "4.25.0",
+  "version": "4.27.0",
   "description": "React Native bindings for SceneView — 3D and AR scenes powered by Filament (Android) and RealityKit (iOS)",
   "main": "lib/commonjs/index",
   "module": "lib/module/index",
@@ -17,7 +17,8 @@
   ],
   "scripts": {
     "typescript": "tsc --noEmit",
-    "lint": "eslint \"src/**/*.{ts,tsx}\"",
+    "lint": "cd ../.. && react-native/react-native-sceneview/node_modules/.bin/biome check react-native/react-native-sceneview/src react-native/react-native-sceneview/__tests__ react-native/react-native-sceneview/example/src",
+    "lint:fix": "cd ../.. && react-native/react-native-sceneview/node_modules/.bin/biome check --write react-native/react-native-sceneview/src react-native/react-native-sceneview/__tests__ react-native/react-native-sceneview/example/src",
     "test": "jest",
     "build": "bob build",
     "prepare": "bob build"
@@ -51,6 +52,7 @@
     "react-native": ">=0.72.0"
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.0.0",
     "@types/jest": "^29.5.0",
     "@types/react": "^18.2.0",
     "@types/react-native": "^0.72.0",

package/react-native-sceneview.podspec

@@ -6,11 +6,18 @@ Pod::Spec.new do |s|
   s.name         = "react-native-sceneview"
   s.version      = package["version"]
   s.summary      = package["description"]
-  s.homepage     = package["repository"]
+  # `package["repository"]` is an OBJECT ({type, url, directory}), and CocoaPods
+  # rejects a Hash here ("Unacceptable type `Hash` for `homepage`"), which made
+  # `pod install` fail outright for any host app consuming this module. Use the
+  # string `homepage` field instead.
+  s.homepage     = package["homepage"]
   s.license      = package["license"]
   s.authors      = "SceneView contributors"
 
-  s.platforms    = { :ios => "17.0" }
+  # Must match `SceneViewSwift/Package.swift`'s `.iOS("18.0")` floor — the
+  # bridge's `ios/*.swift` imports SceneViewSwift, so a lower value here is a
+  # lie CocoaPods cannot catch until a host app fails to link.
+  s.platforms    = { :ios => "18.0" }
   s.source       = { :git => "https://github.com/sceneview/sceneview.git", :tag => "v#{s.version}" }
   s.source_files = "ios/**/*.{swift,m}"
 
@@ -20,7 +27,7 @@ Pod::Spec.new do |s|
   # no published CocoaPods spec for it — so it CANNOT be declared as a
   # `s.dependency` here (CocoaPods would fail `pod install` resolving it).
   # The host app must add it once via Xcode's SwiftPM integration:
-  #   File ▸ Add Package Dependencies… ▸ https://github.com/sceneview/SceneViewSwift
+  #   File ▸ Add Package Dependencies… ▸ https://github.com/sceneview/sceneview
   # The module's `ios/*.swift` `import SceneViewSwift` then resolves at the
   # app build, exactly like any RN native module with a SwiftPM dependency.
   # See this module's README "iOS" section.

package/src/index.tsx

@@ -1,14 +1,20 @@
-import React from 'react';
+// `tsconfig.json` sets `"jsx": "react"` — the CLASSIC runtime — so every JSX
+// element below compiles to `React.createElement(...)` (verified in the
+// published `lib/commonjs/index.js`). Biome's `useImportType` only sees the
+// `React.FC` type annotations, not the JSX lowering, so it offers a "safe fix"
+// that would erase this import and break the shipped bundle at runtime.
+// biome-ignore lint/style/useImportType: React is a VALUE import — see above.
+import React from "react";
 import {
-  requireNativeComponent,
   NativeModules,
-  Platform,
-  type ViewStyle,
   type NativeSyntheticEvent,
-  View,
-  Text,
+  Platform,
+  requireNativeComponent,
   StyleSheet,
-} from 'react-native';
+  Text,
+  View,
+  type ViewStyle,
+} from "react-native";
 
 // ---------------------------------------------------------------------------
 // Node type interfaces
@@ -41,7 +47,7 @@ export interface ModelNode {
  *   cross-platform bridge-parity umbrella (#909). Use `modelNodes` on iOS.
  */
 export interface GeometryNode {
-  type: 'box' | 'cube' | 'sphere' | 'cylinder' | 'plane';
+  type: "box" | "cube" | "sphere" | "cylinder" | "plane";
   size?: [number, number, number];
   position?: [number, number, number];
   rotation?: [number, number, number];
@@ -68,7 +74,7 @@ export interface GeometryNode {
  *   cross-platform bridge-parity umbrella (#909).
  */
 export interface LightNode {
-  type: 'directional' | 'point' | 'spot';
+  type: "directional" | "point" | "spot";
   intensity?: number;
   color?: string;
   position?: [number, number, number];
@@ -84,13 +90,26 @@ export interface TapEvent {
   x: number;
   y: number;
   z: number;
-  /** Name of the tapped node, if any. */
-  nodeName?: string;
+  /**
+   * Name of the tapped model: its file's base name without extension
+   * (`models/robot.glb` → `robot`), identical on Android and iOS. Never an
+   * asset-internal mesh name — a tap inside a model always reports the model.
+   *
+   * `null` — never `undefined` — when the tap hit no model: an untitled
+   * geometry node or nothing at all on Android, a plane or a miss in Android
+   * AR, and *every* `ARSceneView` tap on iOS, where `SceneViewSwift`'s
+   * `ARSceneView` exposes no entity hit-test hook and so can only resolve the
+   * surface point (#2051).
+   *
+   * Every native dispatch path writes the key, so `nodeName == null` is the one
+   * guard that covers both views on both platforms.
+   */
+  nodeName: string | null;
 }
 
 export interface PlaneDetectedEvent {
   id: string;
-  type: 'horizontal' | 'vertical';
+  type: "horizontal" | "vertical";
   center: [number, number, number];
   extent: [number, number];
 }
@@ -108,7 +127,7 @@ export interface PlaneDetectedEvent {
  *   back to orbit (the per-mode switch is an iOS-first v4.3.0 addition —
  *   the Android side is tracked in issue #1051).
  */
-export type CameraControlMode = 'orbit' | 'pan' | 'firstPerson';
+export type CameraControlMode = "orbit" | "pan" | "firstPerson";
 
 export interface SceneViewProps {
   style?: ViewStyle;
@@ -131,7 +150,17 @@ export interface SceneViewProps {
    */
   lightNodes?: LightNode[];
 
-  /** Enable default orbit camera controls. Default: true. */
+  /**
+   * Enable default orbit camera controls. Default: `true`.
+   *
+   * @deprecated Superseded by {@link SceneViewProps.cameraControlMode}, and
+   * **inert on iOS**: the two would contradict each other — nothing can say
+   * which wins for `cameraOrbit: false, cameraControlMode: 'orbit'` — so the
+   * iOS bridge deliberately reads only `cameraControlMode`. Still honoured on
+   * Android. There is currently no way to freeze the camera from this bridge
+   * on iOS; `SceneViewSwift` has `cameraGesturesEnabled` but it is not exposed
+   * here yet.
+   */
   cameraOrbit?: boolean;
 
   /**
@@ -152,9 +181,30 @@ export interface SceneViewProps {
   /**
    * Called when the user taps inside the scene.
    *
-   * The event payload carries the world-space tap coordinates. On Android the
-   * tapped node's `nodeName` is included when the tap hits a node; on iOS AR
-   * the tap reports the surface point only, so `nodeName` is absent there.
+   * The event payload carries the world-space position of the tapped model and
+   * its `nodeName` (the model file's base name without extension) on both
+   * Android and iOS. A tap that hits no model reports `nodeName: null` — with
+   * the tapped node's real world position on Android when it landed on an
+   * (unnamed) geometry node, and `0, 0, 0` when it hit nothing at all. That
+   * `0, 0, 0` miss is **in practice Android-only**: iOS resolves the tap
+   * through RealityKit's entity-targeted gesture, which fires only on a hit,
+   * so a tap on empty space dispatches no `onTap` event at all — count taps
+   * and you will see fewer events on iOS, not a `0, 0, 0` one. (iOS emits
+   * `0, 0, 0` only if a hit entity resolves outside every loaded model, which
+   * the content root's contents make unreachable today.)
+   *
+   * On {@link ARSceneViewProps | `ARSceneView`} *what a hit reports* differs by
+   * platform:
+   * - **Android**: the AR view hit-tests the scene, so a tap on a model reports
+   *   that model's file base name exactly as `SceneView` does; a tap on a plane
+   *   or on nothing reports `null`.
+   * - **iOS**: always `null` — `SceneViewSwift.ARSceneView` exposes no entity
+   *   hit-test hook, so the AR tap can only resolve the surface point. Tracked
+   *   under {@link https://github.com/sceneview/sceneview/issues/2051 | #2051}.
+   *
+   * The *key* is written on every dispatch path of both views on both
+   * platforms, so one `nodeName == null` check remains the correct "the tap hit
+   * no model" test everywhere; it is never omitted and never `undefined`.
    */
   onTap?: (event: NativeSyntheticEvent<TapEvent>) => void;
 }
@@ -200,14 +250,14 @@ export interface ARSceneViewProps extends SceneViewProps {
 // Native components (only available on Android and iOS)
 // ---------------------------------------------------------------------------
 
-const isNativeAvailable = Platform.OS === 'android' || Platform.OS === 'ios';
+const isNativeAvailable = Platform.OS === "android" || Platform.OS === "ios";
 
 const NativeSceneView = isNativeAvailable
-  ? requireNativeComponent<SceneViewProps>('RNSceneView')
+  ? requireNativeComponent<SceneViewProps>("RNSceneView")
   : null;
 
 const NativeARSceneView = isNativeAvailable
-  ? requireNativeComponent<ARSceneViewProps>('RNARSceneView')
+  ? requireNativeComponent<ARSceneViewProps>("RNARSceneView")
   : null;
 
 // ---------------------------------------------------------------------------
@@ -223,12 +273,12 @@ const UnsupportedView: React.FC<{ name: string }> = ({ name }) => (
 const fallbackStyles = StyleSheet.create({
   container: {
     flex: 1,
-    justifyContent: 'center',
-    alignItems: 'center',
-    backgroundColor: '#1a1a2e',
+    justifyContent: "center",
+    alignItems: "center",
+    backgroundColor: "#1a1a2e",
   },
   text: {
-    color: '#aaa',
+    color: "#aaa",
     fontSize: 16,
   },
 });
@@ -282,8 +332,7 @@ interface RNARRecorderModule {
   saveToPhotoLibrary(movPath: string): Promise<void>;
 }
 
-const NativeARRecorder: RNARRecorderModule | undefined =
-  NativeModules.RNARRecorder;
+const NativeARRecorder: RNARRecorderModule | undefined = NativeModules.RNARRecorder;
 
 /**
  * Records an AR session to a video file (v4.3.0).
@@ -309,14 +358,14 @@ const NativeARRecorder: RNARRecorderModule | undefined =
 export class ARRecorder {
   /** `true` when {@link ARRecorder} is supported on the current platform. */
   static get isSupported(): boolean {
-    return Platform.OS === 'ios' && NativeARRecorder != null;
+    return Platform.OS === "ios" && NativeARRecorder != null;
   }
 
   private rejectUnsupported(): Promise<never> {
     return Promise.reject(
       new Error(
-        'ARRecorder is currently only supported on iOS. Android AR session ' +
-          'recording is tracked in issue #1051.'
+        "ARRecorder is currently only supported on iOS. Android AR session " +
+          "recording is tracked in issue #1051."
       )
     );
   }