@sceneview-sdk/react-native 4.26.0 → 4.28.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,18 +45,64 @@ 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…*):
+**`SceneViewSwift` must arrive as a pod, and your `Podfile` must give it a
+coordinate.** This module's podspec declares `s.dependency "SceneViewSwift",
+"~> 4.27"`, but `SceneViewSwift` is **not published on the CocoaPods trunk**,
+so CocoaPods cannot resolve that name on its own. Add one of these lines to
+your `Podfile`:
 
-- URL: `https://github.com/sceneview/SceneViewSwift`
-- Version: `4.14.0` (or *Up to Next Major*)
+```ruby
+# Released consumers — no monorepo clone
+pod 'SceneViewSwift',
+    :podspec => 'https://raw.githubusercontent.com/sceneview/sceneview/main/SceneViewSwift.podspec'
 
-The module's `ios/*.swift` `import SceneViewSwift` resolves against that
-app-level package at build time.
+# In-repo consumers — resolve from a local checkout
+pod 'SceneViewSwift', :path => '<repo-root>'
+```
+
+`samples/react-native-demo/ios/Podfile` takes the `:path` route, exactly as
+`samples/flutter-demo/ios/Podfile` does.
+
+> **`main`, not a tag — for now.** A tagged coordinate would be the
+> reproducible one, but `SceneViewSwift.podspec` lives at the repo *root* and
+> landed after `v4.26.0` was cut, so no tag that currently exists carries it:
+> `pod install` against `.../v4.27.0/SceneViewSwift.podspec` is a 404, verified
+> with `git cat-file -e v4.27.0:SceneViewSwift.podspec`. The Flutter plugin
+> documents `main` for the same reason. Both move to
+> `:git => …, :tag => 'vX.Y.Z'` the first time a release is cut with that file
+> in it.
+
+> **Always supply the coordinate.** The `SceneViewSwift` name is unclaimed on
+> the CocoaPods trunk, so a `Podfile` that omits the line does not fail closed
+> forever — it would resolve to whatever someone else publishes under that
+> name. The explicit `:podspec` / `:path` line is what makes the source
+> unambiguous.
+
+> **Swift Package Manager does not work for this module.** Adding
+> `SceneViewSwift` to the host *project* in Xcode (*File ▸ Add Package
+> Dependencies…*) leaves it invisible here: this module's `ios/*.swift`
+> compiles inside the generated `Pods.xcodeproj`, which does not see the host
+> project's SwiftPM packages, and `import SceneViewSwift` fails with *"Unable
+> to find module dependency: 'SceneViewSwift'"*. The README used to document
+> the SwiftPM route as the supported one; it had never been built, and the
+> first real `xcodebuild` against it failed exactly that way. This closes the
+> React Native half of
+> [#3072](https://github.com/sceneview/sceneview/issues/3072).
+
+> **Keep the two versions in step.** npm `4.27.0`'s Swift requires
+> `SceneViewSwift` at 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.
 
 ### Android
 
@@ -84,7 +128,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 +153,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 +228,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 +247,40 @@ 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 **Android and iOS** on both views. On `SceneView`
+  (3D) it carries the tapped model's world position and its file base name
+  without extension as `nodeName`.
+  > **Measured, not inferred ([#3086](https://github.com/sceneview/sceneview/issues/3086)).**
+  > The iOS 3D tap was run on an iPhone 17 Pro Max simulator with the Fox USDZ
+  > rendering: 5 taps on the model, 5 dispatches, `nodeName` `khronos_fox` every
+  > time; a tap on empty space dispatched nothing, as documented below. The path
+  > was instrumented at all four stages — gesture arrival, entity resolution,
+  > `SceneViewerHostView.reportTap`, and this module's `onTapEntity` block — and
+  > every stage fired.
+  >
+  > This does **not** clear the sibling bridge: Flutter's 3D `onTap` still never
+  > fires on iOS ([#3045](https://github.com/sceneview/sceneview/issues/3045)).
+  > The same run measured both hosts back to back against the *same*
+  > SceneViewSwift build and the same entity graph (11 entities, 1 collision
+  > shape, 9 input targets in each): 6 taps on the model under Flutter resolved
+  > no entity at all, while the plain, untargeted gesture arrived every time. So
+  > #3045 is a property of Flutter's platform-view touch delivery, not of
+  > RealityKit's entity-targeted hit test — which is what its write-up claims.
+
+  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 +296,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,