@reactvision/react-viro 2.43.0 → 2.43.1

package/fabric-interop/NativeViro.ts

@@ -0,0 +1,335 @@
+/**
+ * NativeViro - JSI Bridge Functions
+ *
+ * This module provides direct JSI functions to communicate with the native Viro implementation.
+ * These functions bypass the React Native bridge and codegen, providing direct access to
+ * the existing native implementation.
+ */
+
+// Type definitions for props and events
+export type ViroNodeProps = Record<string, any>;
+export type ViroNodeType =
+  | "box"
+  | "sphere"
+  | "text"
+  | "image"
+  | "animatedImage"
+  | "animatedComponent"
+  | "object"
+  | "scene"
+  | "arScene"
+  | "camera"
+  | "arCamera"
+  | "orbitCamera"
+  | "light"
+  | "ambientLight"
+  | "directionalLight"
+  | "spotLight"
+  | "omniLight"
+  | "sound"
+  | "soundField"
+  | "spatialSound"
+  | "video"
+  | "materialVideo"
+  | "portal"
+  | "portalScene"
+  | "plane"
+  | "arPlane"
+  | "arImageMarker"
+  | "arObjectMarker"
+  | "quad"
+  | "polygon"
+  | "polyline"
+  | "geometry"
+  | "particle"
+  | "flexView"
+  | "surface"
+  | "360Image"
+  | "360Video"
+  | "skyBox"
+  | "lightingEnvironment"
+  | "button"
+  | "controller"
+  | "node";
+
+export type ViroEventCallback = (event: any) => void;
+
+// The global NativeViro object is injected by the native code
+// Note: The type declaration is in the generated .d.ts file
+// We don't redeclare it here to avoid conflicts
+
+// Additional methods that may not be in the type declaration
+// These are accessed using type assertions in the components
+// - recenterTracking(nodeId: string): void
+// - project(nodeId: string, point: [number, number, number]): Promise<[number, number, number]>
+// - unproject(nodeId: string, point: [number, number, number]): Promise<[number, number, number]>
+
+// Event callback registry
+const eventCallbacks: Record<string, ViroEventCallback> = {};
+
+// Generate a unique ID for nodes
+let nextNodeId = 1;
+export const generateNodeId = (): string => `viro_node_${nextNodeId++}`;
+
+// Generate a unique ID for callbacks
+let nextCallbackId = 1;
+export const generateCallbackId = (): string =>
+  `viro_callback_${nextCallbackId++}`;
+
+// Event handler that receives events from native code
+export function handleViroEvent(callbackId: string, event: any): void {
+  const callback = eventCallbacks[callbackId];
+  if (callback) {
+    callback(event);
+  } else {
+    console.warn(`No callback found for ID: ${callbackId}`);
+  }
+}
+
+// Set up the global event handler
+if (typeof global !== "undefined") {
+  // @ts-ignore - This property will be added by the native code
+  global.handleViroEvent = handleViroEvent;
+}
+
+import { getNativeViro, isNativeViroAvailable } from "./components/ViroGlobal";
+
+// Register a JS callback for native events
+export function registerEventListener(
+  nodeId: string,
+  eventName: string,
+  callback: ViroEventCallback
+): string {
+  const callbackId = generateCallbackId();
+  eventCallbacks[callbackId] = callback;
+
+  // Register with native code
+  const nativeViro = getNativeViro();
+  if (nativeViro) {
+    nativeViro.registerEventCallback(nodeId, eventName, callbackId);
+  }
+
+  return callbackId;
+}
+
+// Unregister a callback
+export function unregisterEventListener(
+  nodeId: string,
+  eventName: string,
+  callbackId: string
+): void {
+  delete eventCallbacks[callbackId];
+
+  // Unregister with native code
+  const nativeViro = getNativeViro();
+  if (nativeViro) {
+    nativeViro.unregisterEventCallback(nodeId, eventName, callbackId);
+  }
+}
+
+// Initialize the Viro platform
+export function initializeViro(config?: {
+  debug?: boolean;
+  arEnabled?: boolean;
+  worldAlignment?: string;
+}): Promise<boolean> {
+  const nativeViro = getNativeViro();
+  if (nativeViro) {
+    return nativeViro.initialize(config);
+  }
+  return Promise.reject(new Error("NativeViro not available"));
+}
+
+// Scene Management Functions
+export function createScene(
+  sceneId: string,
+  sceneType: string,
+  props: ViroNodeProps = {}
+): void {
+  const nativeViro = getNativeViro();
+  if (nativeViro && nativeViro.createViroScene) {
+    nativeViro.createViroScene(sceneId, sceneType, props);
+  } else {
+    console.warn("Scene management not available - createScene");
+  }
+}
+
+export function activateScene(sceneId: string): void {
+  const nativeViro = getNativeViro();
+  if (nativeViro && nativeViro.activateViroScene) {
+    nativeViro.activateViroScene(sceneId);
+  } else {
+    console.warn("Scene management not available - activateScene");
+  }
+}
+
+export function deactivateScene(sceneId: string): void {
+  const nativeViro = getNativeViro();
+  if (nativeViro && nativeViro.deactivateViroScene) {
+    nativeViro.deactivateViroScene(sceneId);
+  } else {
+    console.warn("Scene management not available - deactivateScene");
+  }
+}
+
+export function destroyScene(sceneId: string): void {
+  const nativeViro = getNativeViro();
+  if (nativeViro && nativeViro.destroyViroScene) {
+    nativeViro.destroyViroScene(sceneId);
+  } else {
+    console.warn("Scene management not available - destroyScene");
+  }
+}
+
+export function getSceneState(sceneId: string): string | null {
+  const nativeViro = getNativeViro();
+  if (nativeViro && nativeViro.getViroSceneState) {
+    return nativeViro.getViroSceneState(sceneId);
+  }
+  return null;
+}
+
+export function getMemoryStats(): Record<string, any> | null {
+  const nativeViro = getNativeViro();
+  if (nativeViro && nativeViro.getViroMemoryStats) {
+    return nativeViro.getViroMemoryStats();
+  }
+  return null;
+}
+
+export function performMemoryCleanup(): void {
+  const nativeViro = getNativeViro();
+  if (nativeViro && nativeViro.performViroMemoryCleanup) {
+    nativeViro.performViroMemoryCleanup();
+  } else {
+    console.warn("Memory management not available - performMemoryCleanup");
+  }
+}
+
+// Node Management Functions (enhanced)
+export function createNode(
+  nodeId: string,
+  nodeType: ViroNodeType,
+  props: ViroNodeProps = {}
+): void {
+  const nativeViro = getNativeViro();
+  if (nativeViro) {
+    nativeViro.createViroNode(nodeId, nodeType, props);
+  } else {
+    console.warn("NativeViro not available - createNode");
+  }
+}
+
+export function updateNode(nodeId: string, props: ViroNodeProps): void {
+  const nativeViro = getNativeViro();
+  if (nativeViro) {
+    nativeViro.updateViroNode(nodeId, props);
+  } else {
+    console.warn("NativeViro not available - updateNode");
+  }
+}
+
+export function deleteNode(nodeId: string): void {
+  const nativeViro = getNativeViro();
+  if (nativeViro) {
+    nativeViro.deleteViroNode(nodeId);
+  } else {
+    console.warn("NativeViro not available - deleteNode");
+  }
+}
+
+export function addChild(parentId: string, childId: string): void {
+  const nativeViro = getNativeViro();
+  if (nativeViro) {
+    nativeViro.addViroNodeChild(parentId, childId);
+  } else {
+    console.warn("NativeViro not available - addChild");
+  }
+}
+
+export function removeChild(parentId: string, childId: string): void {
+  const nativeViro = getNativeViro();
+  if (nativeViro) {
+    nativeViro.removeViroNodeChild(parentId, childId);
+  } else {
+    console.warn("NativeViro not available - removeChild");
+  }
+}
+
+// Material Management Functions (enhanced)
+export function createMaterial(
+  materialName: string,
+  properties: Record<string, any>
+): void {
+  const nativeViro = getNativeViro();
+  if (nativeViro) {
+    nativeViro.createViroMaterial(materialName, properties);
+  } else {
+    console.warn("NativeViro not available - createMaterial");
+  }
+}
+
+export function updateMaterial(
+  materialName: string,
+  properties: Record<string, any>
+): void {
+  const nativeViro = getNativeViro();
+  if (nativeViro) {
+    nativeViro.updateViroMaterial(materialName, properties);
+  } else {
+    console.warn("NativeViro not available - updateMaterial");
+  }
+}
+
+// Animation Management Functions (enhanced)
+export function createAnimation(
+  animationName: string,
+  properties: Record<string, any>
+): void {
+  const nativeViro = getNativeViro();
+  if (nativeViro) {
+    nativeViro.createViroAnimation(animationName, properties);
+  } else {
+    console.warn("NativeViro not available - createAnimation");
+  }
+}
+
+export function executeAnimation(
+  nodeId: string,
+  animationName: string,
+  options: Record<string, any> = {}
+): void {
+  const nativeViro = getNativeViro();
+  if (nativeViro) {
+    nativeViro.executeViroAnimation(nodeId, animationName, options);
+  } else {
+    console.warn("NativeViro not available - executeAnimation");
+  }
+}
+
+// AR Configuration Functions (enhanced)
+export function setARPlaneDetection(config: {
+  enabled?: boolean;
+  alignment?: string;
+}): void {
+  const nativeViro = getNativeViro();
+  if (nativeViro) {
+    nativeViro.setViroARPlaneDetection(config);
+  } else {
+    console.warn("NativeViro not available - setARPlaneDetection");
+  }
+}
+
+export function setARImageTargets(targets: Record<string, any>): void {
+  const nativeViro = getNativeViro();
+  if (nativeViro) {
+    nativeViro.setViroARImageTargets(targets);
+  } else {
+    console.warn("NativeViro not available - setARImageTargets");
+  }
+}
+
+// Check if the JSI interface is available
+export function isViroJSIAvailable(): boolean {
+  return isNativeViroAvailable();
+}

package/fabric-interop/README.md

@@ -0,0 +1,282 @@
+# ViroReact Fabric Interop Layer
+
+This directory contains the **New Architecture (Fabric) interop layer** for ViroReact. As of version 2.43.1, ViroReact **requires React Native New Architecture** to be enabled.
+
+## 🚀 **New Architecture Required**
+
+**IMPORTANT:** This library only works with React Native's New Architecture (Fabric). Legacy architecture support has been removed.
+
+### **Minimum Requirements:**
+
+- **React Native 0.76.9+**
+- **New Architecture enabled** (`newArchEnabled=true`)
+- **Fabric UI Manager** available at runtime
+
+## 📦 **What's Included**
+
+### **JavaScript Layer**
+
+- **`NativeViro.ts`** - JSI bridge functions for direct native communication
+- **`ViroGlobal.ts`** - Type-safe access to the global NativeViro object
+- **`ViroFabricContainer.tsx`** - Main container component for Fabric
+- **`components/`** - All 42+ ViroReact components updated for New Architecture
+
+### **Native iOS Implementation**
+
+- **`ViroFabricJSI.h/.mm`** - JSI bridge implementation
+- **`ViroFabricContainer.mm`** - iOS Fabric container
+- **`ViroFabricSceneManager.mm`** - Scene lifecycle management
+- **`ViroFabricManager.mm`** - Event handling system
+- **`ViroFabric.podspec`** - CocoaPods specification
+
+### **Native Android Implementation**
+
+- **`ViroFabricContainerJSI.cpp`** - JSI bridge with JNI
+- **`ViroFabricContainer.java`** - Android Fabric container
+- **`ViroFabricSceneManager.java`** - Scene lifecycle management
+- **`build.gradle`** - Android build configuration
+- **`CMakeLists.txt`** - C++ build configuration
+
+## 🔧 **Setup Instructions**
+
+### **1. Enable New Architecture**
+
+#### **Android:**
+
+Add to `android/gradle.properties`:
+
+```properties
+newArchEnabled=true
+```
+
+#### **iOS:**
+
+Add to `ios/.xcode.env`:
+
+```bash
+export RCT_NEW_ARCH_ENABLED=1
+```
+
+**For Firebase or Static Library Integration:**
+
+See the [Static Library Integration Guide](./STATIC_LIBRARY_INTEGRATION.md) for detailed Podfile configuration when using Firebase or encountering folly header issues.
+
+### **2. Install Dependencies**
+
+```bash
+npm install @reactvision/react-viro
+cd ios && pod install
+```
+
+**Note:** If you encounter folly header issues or need Firebase compatibility, see the [Static Library Integration Guide](./STATIC_LIBRARY_INTEGRATION.md) for the recommended static library approach.
+
+### **3. Usage**
+
+```typescript
+import { ViroARScene, ViroBox } from '@reactvision/react-viro';
+
+// Components automatically use the Fabric implementation
+function MyARScene() {
+  return (
+    <ViroARScene>
+      <ViroBox position={[0, 0, -1]} />
+    </ViroARScene>
+  );
+}
+```
+
+## 🏗️ **Architecture Overview**
+
+### **Component Flow:**
+
+```
+React Component → ViroFabricContainer → JSI Bridge → Native ViroReact
+```
+
+### **Event Flow:**
+
+```
+Native Event → JSI Callback → JavaScript Handler → React Component
+```
+
+### **Memory Management:**
+
+- Automatic cleanup on component unmount
+- Scene lifecycle management
+- Memory monitoring and optimization
+
+## 🔍 **Key Features**
+
+### **✅ Performance Benefits**
+
+- **Direct JSI communication** - No bridge serialization overhead
+- **Individual property updates** - Only changed properties are sent
+- **Optimized rendering** - Fabric's concurrent rendering support
+
+### **✅ Developer Experience**
+
+- **Zero breaking changes** - Existing ViroReact code works unchanged
+- **Enhanced debugging** - Better error messages and logging
+- **Type safety** - Complete TypeScript support
+
+### **✅ Future-Proof**
+
+- **New Architecture first** - Aligned with React Native's direction
+- **Fabric optimized** - Built specifically for the new renderer
+- **Maintainable** - Single implementation path
+
+## 📋 **Component Support**
+
+All ViroReact components are supported:
+
+### **Basic Components**
+
+- ViroNode, ViroScene, ViroARScene, ViroFlexView
+
+### **3D Primitives**
+
+- ViroBox, ViroSphere, Viro3DObject, ViroGeometry, ViroQuad, ViroPolygon, ViroPolyline, ViroSurface
+
+### **2D Components**
+
+- ViroText, ViroImage, ViroVideo, ViroAnimatedImage
+
+### **360 Components**
+
+- Viro360Image, Viro360Video, ViroSkyBox
+
+### **Lighting**
+
+- ViroAmbientLight, ViroDirectionalLight, ViroSpotLight, ViroOmniLight, ViroLightingEnvironment
+
+### **Audio**
+
+- ViroSound, ViroSoundField, ViroSpatialSound
+
+### **Interactive**
+
+- ViroButton, ViroController, ViroSpinner
+
+### **Effects**
+
+- ViroParticleEmitter, ViroAnimatedComponent, ViroMaterialVideo
+
+### **Scene Navigators**
+
+- ViroSceneNavigator, ViroVRSceneNavigator, ViroARSceneNavigator, Viro3DSceneNavigator
+
+### **AR Components**
+
+- ViroARCamera, ViroARPlane, ViroARPlaneSelector, ViroARImageMarker, ViroARObjectMarker
+
+## 🛠️ **Build Configuration**
+
+### **Package.json Integration**
+
+The main package now points directly to fabric-interop:
+
+```json
+{
+  "main": "fabric-interop/dist/index.js",
+  "types": "fabric-interop/dist/index.d.ts"
+}
+```
+
+### **Expo Plugin Support**
+
+The Expo plugin automatically:
+
+- Validates New Architecture is enabled
+- Configures native dependencies
+- Sets up proper build flags
+
+### **Metro Configuration**
+
+No special Metro configuration required - the fabric-interop layer is automatically used.
+
+## 🔧 **Troubleshooting**
+
+### **"folly/folly-config.h file not found" Error**
+
+**Solution:** Use the static library approach for better compatibility:
+
+1. See the [Static Library Integration Guide](./STATIC_LIBRARY_INTEGRATION.md)
+2. Configure your Podfile with `use_frameworks! :linkage => :static`
+3. The ViroFabric pod is now configured as a static library by default
+
+### **Firebase Integration Issues**
+
+**Solution:** The static library approach resolves Firebase compatibility:
+
+1. Follow the [Static Library Integration Guide](./STATIC_LIBRARY_INTEGRATION.md)
+2. Add `$RNFirebaseAsStaticFramework = true` to your Podfile
+3. Use `use_frameworks! :linkage => :static`
+
+### **"New Architecture not detected" Error**
+
+**Solution:** Ensure New Architecture is properly enabled:
+
+1. Check `android/gradle.properties` has `newArchEnabled=true`
+2. Check `ios/.xcode.env` has `export RCT_NEW_ARCH_ENABLED=1`
+3. Clean and rebuild your project
+
+### **"ViroFabricContainerView not available" Error**
+
+**Solution:** The native module wasn't properly linked:
+
+1. Run `cd ios && pod install`
+2. For Android, ensure the module is in `settings.gradle`
+3. Clean and rebuild
+
+### **JSI Functions Not Available**
+
+**Solution:** The JSI bridge wasn't initialized:
+
+1. Ensure ViroFabricContainer is rendered
+2. Check that New Architecture is actually enabled
+3. Verify React Native version is 0.76.9+
+
+## 📚 **API Reference**
+
+### **Core Functions**
+
+- `createNode(nodeId, nodeType, props)` - Create a new Viro node
+- `updateNode(nodeId, props)` - Update node properties
+- `deleteNode(nodeId)` - Remove a node
+- `addChild(parentId, childId)` - Add child to parent
+- `removeChild(parentId, childId)` - Remove child from parent
+
+### **Scene Management**
+
+- `createScene(sceneId, sceneType, props)` - Create a new scene
+- `activateScene(sceneId)` - Activate a scene
+- `destroyScene(sceneId)` - Destroy a scene
+- `getSceneState(sceneId)` - Get scene state
+
+### **Event Handling**
+
+- `registerEventListener(nodeId, eventName, callback)` - Register event handler
+- `unregisterEventListener(nodeId, eventName, callbackId)` - Remove event handler
+
+### **Memory Management**
+
+- `getMemoryStats()` - Get current memory usage
+- `performMemoryCleanup()` - Force memory cleanup
+
+## 🤝 **Contributing**
+
+When contributing to the fabric-interop layer:
+
+1. **Test both platforms** - Ensure changes work on iOS and Android
+2. **Maintain API compatibility** - Don't break existing ViroReact code
+3. **Update documentation** - Keep this README current
+4. **Add TypeScript types** - Ensure type safety
+5. **Test memory management** - Verify no leaks are introduced
+
+## 📄 **License**
+
+MIT License - see the main project LICENSE file.
+
+---
+
+**ViroReact Fabric Interop** - Bringing ViroReact into the New Architecture era! 🚀