@sceneview-sdk/react-native 4.26.0 → 4.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sceneview-sdk/react-native",
-  "version": "4.26.0",
+  "version": "4.28.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,24 +6,49 @@ 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}"
 
   s.dependency "React-Core"
 
-  # `SceneViewSwift` is distributed via Swift Package Manager only — there is
-  # 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
-  # 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.
+  # This module's `ios/*.swift` files `import SceneViewSwift`, so the module has
+  # to arrive as a POD, not as a Swift package on the host app's project: this
+  # source compiles inside the generated `Pods.xcodeproj`, which does not see
+  # the host project's SwiftPM packages ("Unable to find module dependency:
+  # 'SceneViewSwift'"). The SwiftPM route this spec used to document was never
+  # measured — the demo app was scaffolded and never built — and the first real
+  # `xcodebuild` against it failed exactly that way. Closes the RN half of #3072.
+  #
+  # `SceneViewSwift` is NOT on the CocoaPods trunk, so a host app must give the
+  # dependency a coordinate of its own — one of:
+  #   pod 'SceneViewSwift',
+  #       :podspec => 'https://raw.githubusercontent.com/sceneview/sceneview/main/SceneViewSwift.podspec'
+  #   pod 'SceneViewSwift', :path => '<repo-root>'   # in-repo consumers
+  # `main`, not a tag, and not `:git =>, :tag =>`: the root podspec landed after
+  # v4.26.0 was cut, so no existing tag carries it and a tagged coordinate 404s
+  # (`git cat-file -e v4.27.0:SceneViewSwift.podspec`). `flutter_sceneview.podspec`
+  # says `main` for the same reason; both move to a tag once a release carries
+  # the file. Supply the coordinate always — the name is unclaimed on the trunk,
+  # so a Podfile that leaves it out does not fail closed, it resolves to
+  # whatever someone else publishes under that name.
+  # `samples/react-native-demo/ios/Podfile` takes the `:path` route, exactly as
+  # `samples/flutter-demo/ios/Podfile` does. See this module's README "iOS".
+  #
+  # Loose `~> 4.27` rather than `= s.version`: an app pinned to an older
+  # SceneViewSwift still resolves, mirroring `flutter_sceneview.podspec`.
+  s.dependency "SceneViewSwift", "~> 4.28"
 
   s.swift_version = "5.9"
 end

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,29 @@ 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`). Never an asset-internal mesh name — a tap
+   * inside a model always reports the model.
+   *
+   * **Measured on Android and iOS** (#3086) — the iOS run named the
+   * tapped model on every dispatch; see {@link SceneViewProps.onTap | `onTap`}.
+   *
+   * `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 +130,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 +153,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 +184,39 @@ 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.
+   * Dispatched on **Android and iOS**. The iOS half was measured on an iPhone
+   * 17 Pro Max simulator — 5 taps on a rendering model, 5 dispatches, the
+   * model's name every time
+   * ({@link https://github.com/sceneview/sceneview/issues/3086 | #3086}).
+   * The sibling Flutter bridge still never fires its 3D `onTap` on iOS
+   * ({@link https://github.com/sceneview/sceneview/issues/3045 | #3045}); the
+   * same run showed that is Flutter's platform-view touch delivery, not this
+   * shared RealityKit path, so it does not apply here.
+   *
+   * The event payload carries the world-space position of the tapped model and
+   * its `nodeName` (the model file's base name without extension). 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 +262,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 +285,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 +344,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 +370,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."
       )
     );
   }