From e5c32cceaad65b6d0d4725e5a0947ac5a17d1c6c Mon Sep 17 00:00:00 2001
From: Marc Rousavy <me@mrousavy.com>
Date: Thu, 11 Jul 2024 12:48:53 +0200
Subject: [PATCH] chore: change FilamentContext -> FilamentScene + cleanups
 (#222)

---
 README.md                                     | 12 +++---
 package/example/Shared/src/AnimatedRotate.tsx |  6 +--
 .../Shared/src/AnimationTransitions.tsx       |  6 +--
 .../src/AnimationTransitionsRecording.tsx     |  6 +--
 package/example/Shared/src/CameraPan.tsx      |  6 +--
 .../example/Shared/src/ChangeMaterials.tsx    |  6 +--
 package/example/Shared/src/ImageExample.tsx   |  6 +--
 package/example/Shared/src/LoadFromFile.tsx   |  6 +--
 .../example/Shared/src/MultipleInstances.tsx  |  6 +--
 .../example/Shared/src/NoneTransparent.tsx    | 16 ++------
 .../internal/useApplyTransformations.tsx      |  2 +-
 package/src/hooks/useAnimator.ts              |  2 +-
 package/src/hooks/useCameraManipulator.ts     |  2 +-
 package/src/hooks/useConfigureAssetShadow.ts  |  2 +-
 .../useFilamentContext.ts}                    | 13 +++----
 package/src/hooks/useLightEntity.ts           |  2 +-
 package/src/hooks/useModel.ts                 |  2 +-
 package/src/hooks/useRecorder.ts              |  2 +-
 package/src/hooks/useSkybox.ts                |  2 +-
 package/src/hooks/useWorkletCallback.ts       |  2 +-
 package/src/hooks/useWorkletEffect.ts         |  2 +-
 package/src/hooks/useWorkletMemo.ts           |  2 +-
 package/src/index.tsx                         |  4 +-
 package/src/react/BackgroundImage.tsx         |  2 +-
 package/src/react/Camera.tsx                  |  2 +-
 package/src/react/Configurator.tsx            |  4 +-
 package/src/react/DebugBox.tsx                |  2 +-
 package/src/react/EnvironmentalLight.tsx      |  2 +-
 ...{FilamentContext.tsx => FilamentScene.tsx} | 38 +++++++++++++++----
 package/src/react/FilamentView.tsx            | 27 +++++++------
 package/src/react/Light.tsx                   |  2 +-
 package/src/react/Model.tsx                   |  2 +-
 32 files changed, 104 insertions(+), 92 deletions(-)
 rename package/src/{react/Context.tsx => hooks/useFilamentContext.ts} (63%)
 rename package/src/react/{FilamentContext.tsx => FilamentScene.tsx} (73%)

diff --git a/README.md b/README.md
index 82abfe12..753f31f0 100644
--- a/README.md
+++ b/README.md
@@ -39,21 +39,21 @@ cd ios && pod install
 ### Example
 
 ```tsx
-import { FilamentContext, FilamentView, Model, Camera } from 'react-native-filament'
+import { FilamentScene, FilamentView, Model, Camera } from 'react-native-filament'
 
 function App() {
   return (
-    <FilamentContext>
+    <FilamentScene>
       <FilamentView
         style={{ width: 100, height: 100 }}
         model={model}
       >
         // Render with the default camera:
-        <Camera /> 
+        <Camera />
         // Add a model to the scene (only glb supported yet):
         <Model source={require('./duck.glb')}>
       </FilamentView>
-    </FilamentContext>
+    </FilamentScene>
   )
 }
 ```
@@ -85,7 +85,7 @@ yarn build-bullet3
 yarn build-filament:release # or yarn build-filament:debug
 ```
 
-You can then build one of the example apps in `package/example/AppExamplePaper` or `package/example/AppExampleFabric`. 
+You can then build one of the example apps in `package/example/AppExamplePaper` or `package/example/AppExampleFabric`.
 
 ### Adopting at scale
 
@@ -102,4 +102,4 @@ If you need help with integrating react-native-filament in your app or have addi
 
 The example app in this project uses several free assets:
 - <a href="https://www.freepik.com/free-ai-image/space-travel-collage-design_94964745.htm#fromView=search&page=1&position=1&uuid=cf66f9c3-2d56-4228-a3cf-de7c07d418fb">Image by freepik</a>
-- "Buster Drone" (https://skfb.ly/TBnX) by LaVADraGoN is licensed under Creative Commons Attribution-NonCommercial (http://creativecommons.org/licenses/by-nc/4.0/).
\ No newline at end of file
+- "Buster Drone" (https://skfb.ly/TBnX) by LaVADraGoN is licensed under Creative Commons Attribution-NonCommercial (http://creativecommons.org/licenses/by-nc/4.0/).
diff --git a/package/example/Shared/src/AnimatedRotate.tsx b/package/example/Shared/src/AnimatedRotate.tsx
index ff9aa389..b68c8bff 100644
--- a/package/example/Shared/src/AnimatedRotate.tsx
+++ b/package/example/Shared/src/AnimatedRotate.tsx
@@ -1,6 +1,6 @@
 import * as React from 'react'
 import { StyleSheet } from 'react-native'
-import { FilamentContext, FilamentView, Camera, Skybox, Model, DefaultLight, RenderCallback, ModelInstance } from 'react-native-filament'
+import { FilamentScene, FilamentView, Camera, Skybox, Model, DefaultLight, RenderCallback, ModelInstance } from 'react-native-filament'
 import DroneGlb from '~/assets/buster_drone.glb'
 import { useSharedValue } from 'react-native-worklets-core'
 import { useCallback } from 'react'
@@ -45,9 +45,9 @@ function Renderer() {
 
 export function AnimatedRotate() {
   return (
-    <FilamentContext>
+    <FilamentScene>
       <Renderer />
-    </FilamentContext>
+    </FilamentScene>
   )
 }
 
diff --git a/package/example/Shared/src/AnimationTransitions.tsx b/package/example/Shared/src/AnimationTransitions.tsx
index e69ad0a2..ed4fc5ac 100644
--- a/package/example/Shared/src/AnimationTransitions.tsx
+++ b/package/example/Shared/src/AnimationTransitions.tsx
@@ -1,7 +1,7 @@
 import { useNavigation } from '@react-navigation/native'
 import * as React from 'react'
 import { Alert, Button, ScrollView, StyleSheet, View } from 'react-native'
-import { FilamentContext, FilamentView, Camera, Model, Animator, AnimationItem, Entity, DefaultLight } from 'react-native-filament'
+import { FilamentScene, FilamentView, Camera, Model, Animator, AnimationItem, Entity, DefaultLight } from 'react-native-filament'
 import { useSharedValue } from 'react-native-worklets-core'
 import HipHopGirlGlb from '~/assets/hiphopgirl.glb'
 import { SafeAreaView } from 'react-native-safe-area-context'
@@ -60,9 +60,9 @@ export function AnimationTransitions() {
 
   return (
     <SafeAreaView style={styles.container}>
-      <FilamentContext key={count}>
+      <FilamentScene key={count}>
         <Renderer />
-      </FilamentContext>
+      </FilamentScene>
       <Button title="Rerender" onPress={increment} />
     </SafeAreaView>
   )
diff --git a/package/example/Shared/src/AnimationTransitionsRecording.tsx b/package/example/Shared/src/AnimationTransitionsRecording.tsx
index 2818d41d..1fdaabf7 100644
--- a/package/example/Shared/src/AnimationTransitionsRecording.tsx
+++ b/package/example/Shared/src/AnimationTransitionsRecording.tsx
@@ -10,7 +10,7 @@ import {
   useRecorder,
   useRecorderRenderLoop,
   Camera,
-  FilamentContext,
+  FilamentScene,
   DefaultLight,
 } from 'react-native-filament'
 import { useRunOnJS, useSharedValue } from 'react-native-worklets-core'
@@ -160,9 +160,9 @@ function Renderer() {
 export function AnimationTransitionsRecording() {
   return (
     // Provide the API necessary for recording (accessing the RNF apis) in a react context
-    <FilamentContext>
+    <FilamentScene>
       <Renderer />
-    </FilamentContext>
+    </FilamentScene>
   )
 }
 
diff --git a/package/example/Shared/src/CameraPan.tsx b/package/example/Shared/src/CameraPan.tsx
index d0b08e5d..5268f5bc 100644
--- a/package/example/Shared/src/CameraPan.tsx
+++ b/package/example/Shared/src/CameraPan.tsx
@@ -1,5 +1,5 @@
 import React from 'react'
-import { Camera, DefaultLight, FilamentContext, FilamentView, Model, useCameraManipulator } from 'react-native-filament'
+import { Camera, DefaultLight, FilamentScene, FilamentView, Model, useCameraManipulator } from 'react-native-filament'
 import { Gesture, GestureDetector } from 'react-native-gesture-handler'
 import { Dimensions, StyleSheet, View } from 'react-native'
 import { useSharedValue } from 'react-native-worklets-core'
@@ -59,9 +59,9 @@ function Scene() {
 export function CameraPan() {
   return (
     <View style={styles.container}>
-      <FilamentContext>
+      <FilamentScene>
         <Scene />
-      </FilamentContext>
+      </FilamentScene>
     </View>
   )
 }
diff --git a/package/example/Shared/src/ChangeMaterials.tsx b/package/example/Shared/src/ChangeMaterials.tsx
index 83032df8..e9665a7a 100644
--- a/package/example/Shared/src/ChangeMaterials.tsx
+++ b/package/example/Shared/src/ChangeMaterials.tsx
@@ -1,7 +1,7 @@
 import * as React from 'react'
 
 import { Button, StyleSheet, View } from 'react-native'
-import { FilamentView, useBuffer, useModel, useFilamentContext, useWorkletCallback, Camera, FilamentContext } from 'react-native-filament'
+import { FilamentView, useBuffer, useModel, useFilamentContext, useWorkletCallback, Camera, FilamentScene } from 'react-native-filament'
 
 import PenguModel from '~/assets/pengu.glb'
 import LeftEyeTexture from '~/assets/eye_full_texture_left_blue.jpg'
@@ -56,9 +56,9 @@ function Renderer() {
 
 export function ChangeMaterials() {
   return (
-    <FilamentContext>
+    <FilamentScene>
       <Renderer />
-    </FilamentContext>
+    </FilamentScene>
   )
 }
 
diff --git a/package/example/Shared/src/ImageExample.tsx b/package/example/Shared/src/ImageExample.tsx
index 2eb4fffd..001672b4 100644
--- a/package/example/Shared/src/ImageExample.tsx
+++ b/package/example/Shared/src/ImageExample.tsx
@@ -1,6 +1,6 @@
 import React from 'react'
 import { StyleSheet } from 'react-native'
-import { BackgroundImage, Camera, DefaultLight, FilamentContext, FilamentView, Model } from 'react-native-filament'
+import { BackgroundImage, Camera, DefaultLight, FilamentScene, FilamentView, Model } from 'react-native-filament'
 import BackgroundImageMaterial from '~/assets/background_image.matc'
 
 const imageResource = require('~/assets/background.jpg')
@@ -19,9 +19,9 @@ function Renderer() {
 
 export function ImageExample() {
   return (
-    <FilamentContext>
+    <FilamentScene>
       <Renderer />
-    </FilamentContext>
+    </FilamentScene>
   )
 }
 
diff --git a/package/example/Shared/src/LoadFromFile.tsx b/package/example/Shared/src/LoadFromFile.tsx
index d7d7d2e9..74322915 100644
--- a/package/example/Shared/src/LoadFromFile.tsx
+++ b/package/example/Shared/src/LoadFromFile.tsx
@@ -1,7 +1,7 @@
 import * as React from 'react'
 import { useCallback, useState } from 'react'
 import { Button, StyleSheet, View } from 'react-native'
-import { FilamentContext, FilamentView, Camera, Model, DefaultLight } from 'react-native-filament'
+import { FilamentScene, FilamentView, Camera, Model, DefaultLight } from 'react-native-filament'
 import RNFetchBlob from 'rn-fetch-blob'
 
 function Renderer({ assetPath }: { assetPath: string }) {
@@ -41,9 +41,9 @@ export function LoadFromFile() {
     )
   }
   return (
-    <FilamentContext>
+    <FilamentScene>
       <Renderer assetPath={assetPath} />
-    </FilamentContext>
+    </FilamentScene>
   )
 }
 
diff --git a/package/example/Shared/src/MultipleInstances.tsx b/package/example/Shared/src/MultipleInstances.tsx
index dc235708..5ee1fc15 100644
--- a/package/example/Shared/src/MultipleInstances.tsx
+++ b/package/example/Shared/src/MultipleInstances.tsx
@@ -1,6 +1,6 @@
 import React from 'react'
 import { StyleSheet } from 'react-native'
-import { Animator, Camera, DefaultLight, FilamentContext, FilamentView, Model, ModelInstance } from 'react-native-filament'
+import { Animator, Camera, DefaultLight, FilamentScene, FilamentView, Model, ModelInstance } from 'react-native-filament'
 import DroneGlb from '~/assets/buster_drone.glb'
 
 const instances = [0, 1, 2, 3]
@@ -35,9 +35,9 @@ function Renderer() {
 
 export function MultipleInstances() {
   return (
-    <FilamentContext>
+    <FilamentScene>
       <Renderer />
-    </FilamentContext>
+    </FilamentScene>
   )
 }
 
diff --git a/package/example/Shared/src/NoneTransparent.tsx b/package/example/Shared/src/NoneTransparent.tsx
index 966cc772..45c893bf 100644
--- a/package/example/Shared/src/NoneTransparent.tsx
+++ b/package/example/Shared/src/NoneTransparent.tsx
@@ -1,16 +1,6 @@
 import * as React from 'react'
 import { StyleSheet } from 'react-native'
-import {
-  FilamentContext,
-  FilamentView,
-  Camera,
-  Skybox,
-  Model,
-  Animator,
-  AnimationItem,
-  DefaultLight,
-  DebugBox,
-} from 'react-native-filament'
+import { FilamentScene, FilamentView, Camera, Skybox, Model, Animator, AnimationItem, DefaultLight, DebugBox } from 'react-native-filament'
 import DroneGlb from '~/assets/buster_drone.glb'
 import { useCallback } from 'react'
 
@@ -35,9 +25,9 @@ function Renderer() {
 
 export function NoneTransparent() {
   return (
-    <FilamentContext>
+    <FilamentScene>
       <Renderer />
-    </FilamentContext>
+    </FilamentScene>
   )
 }
 
diff --git a/package/src/hooks/internal/useApplyTransformations.tsx b/package/src/hooks/internal/useApplyTransformations.tsx
index 62cfca5d..4aec3a42 100644
--- a/package/src/hooks/internal/useApplyTransformations.tsx
+++ b/package/src/hooks/internal/useApplyTransformations.tsx
@@ -1,6 +1,6 @@
 import { useEffect, useRef } from 'react'
 import { Rotation, TransformationProps } from '../../react/TransformContext'
-import { useFilamentContext } from '../../react/Context'
+import { useFilamentContext } from '../useFilamentContext'
 import { AABB, Entity, Float3 } from '../../types'
 import { areFloat3Equal, isWorkletSharedValue } from '../../utilities/helper'
 import { useWorkletEffect } from '../useWorkletEffect'
diff --git a/package/src/hooks/useAnimator.ts b/package/src/hooks/useAnimator.ts
index c007de0a..0d34b2d5 100644
--- a/package/src/hooks/useAnimator.ts
+++ b/package/src/hooks/useAnimator.ts
@@ -1,6 +1,6 @@
 import { useMemo } from 'react'
 import { FilamentAnimator, FilamentAsset, FilamentInstance } from '../types'
-import { useFilamentContext } from '../react/Context'
+import { useFilamentContext } from './useFilamentContext'
 import { FilamentModel } from './useModel'
 
 function isFilamentModel(asset: FilamentAsset | FilamentInstance | FilamentModel): asset is FilamentModel {
diff --git a/package/src/hooks/useCameraManipulator.ts b/package/src/hooks/useCameraManipulator.ts
index 1d67603e..caaa658f 100644
--- a/package/src/hooks/useCameraManipulator.ts
+++ b/package/src/hooks/useCameraManipulator.ts
@@ -1,4 +1,4 @@
-import { useFilamentContext } from '../react/Context'
+import { useFilamentContext } from './useFilamentContext'
 import { Float3, OrbitCameraManipulatorConfig } from '../types'
 import { useDisposableResource } from './useDisposableResource'
 
diff --git a/package/src/hooks/useConfigureAssetShadow.ts b/package/src/hooks/useConfigureAssetShadow.ts
index 1f684f27..c171b03d 100644
--- a/package/src/hooks/useConfigureAssetShadow.ts
+++ b/package/src/hooks/useConfigureAssetShadow.ts
@@ -1,6 +1,6 @@
 import { useEffect, useMemo, useRef } from 'react'
 import { FilamentAsset, RenderableManager } from '../types'
-import { useFilamentContext } from '../react/Context'
+import { useFilamentContext } from './useFilamentContext'
 
 export type UseAssetShadowProps = {
   renderableManager: RenderableManager
diff --git a/package/src/react/Context.tsx b/package/src/hooks/useFilamentContext.ts
similarity index 63%
rename from package/src/react/Context.tsx
rename to package/src/hooks/useFilamentContext.ts
index 9a07afc2..12dace35 100644
--- a/package/src/react/Context.tsx
+++ b/package/src/hooks/useFilamentContext.ts
@@ -25,20 +25,19 @@ export type FilamentContextType = {
   nameComponentManager: NameComponentManager
   workletContext: IWorkletContext
 
-  // TODO: put this in an "internal" separate context?
   /**
+   * This is a private API, do not use this.
    * @private
+   * @internal
    */
-  _choreographer: Choreographer
+  choreographer: Choreographer
 }
-export const Context = React.createContext<FilamentContextType | undefined>(undefined)
+export const FilamentContext = React.createContext<FilamentContextType | undefined>(undefined)
 
 export function useFilamentContext() {
-  const context = React.useContext(Context)
+  const context = React.useContext(FilamentContext)
   if (context === undefined) {
-    throw new Error(
-      'useFilamentContext (and its hooks such as `useScene()`, components like `<Filament />` etc.) must be used within a `<FilamentProvider>` component!'
-    )
+    throw new Error('You tried to use a Filament hook/component without wrapping your component in a <FilamentScene> component!')
   }
   return context
 }
diff --git a/package/src/hooks/useLightEntity.ts b/package/src/hooks/useLightEntity.ts
index 1d03d02c..11220100 100644
--- a/package/src/hooks/useLightEntity.ts
+++ b/package/src/hooks/useLightEntity.ts
@@ -1,7 +1,7 @@
 import { useEffect, useMemo } from 'react'
 import { LightConfig, LightManager } from '../types'
 import { ISharedValue } from 'react-native-worklets-core'
-import { useFilamentContext } from '../react/Context'
+import { useFilamentContext } from './useFilamentContext'
 
 export type UseLightEntityProps =
   | LightConfig
diff --git a/package/src/hooks/useModel.ts b/package/src/hooks/useModel.ts
index c12bd405..20033a84 100644
--- a/package/src/hooks/useModel.ts
+++ b/package/src/hooks/useModel.ts
@@ -1,6 +1,6 @@
 import { type BufferSource, useBuffer } from './useBuffer'
 import { FilamentAsset } from '../types/FilamentAsset'
-import { useFilamentContext } from '../react/Context'
+import { useFilamentContext } from './useFilamentContext'
 import { useDisposableResource } from './useDisposableResource'
 import usePrevious from './usePrevious'
 import { useWorkletEffect } from './useWorkletEffect'
diff --git a/package/src/hooks/useRecorder.ts b/package/src/hooks/useRecorder.ts
index d3f3c674..e9596882 100644
--- a/package/src/hooks/useRecorder.ts
+++ b/package/src/hooks/useRecorder.ts
@@ -1,5 +1,5 @@
 import { useMemo } from 'react'
-import { useFilamentContext } from '../react/Context'
+import { useFilamentContext } from './useFilamentContext'
 import { FilamentProxy } from '../native/FilamentProxy'
 import { useDisposableResource } from './useDisposableResource'
 import { useWorkletEffect } from './useWorkletEffect'
diff --git a/package/src/hooks/useSkybox.ts b/package/src/hooks/useSkybox.ts
index 00c3f836..d5bc9d15 100644
--- a/package/src/hooks/useSkybox.ts
+++ b/package/src/hooks/useSkybox.ts
@@ -1,4 +1,4 @@
-import { useFilamentContext } from '../react/Context'
+import { useFilamentContext } from './useFilamentContext'
 import { FilamentBuffer } from '../native/FilamentBuffer'
 import { useWorkletEffect } from './useWorkletEffect'
 
diff --git a/package/src/hooks/useWorkletCallback.ts b/package/src/hooks/useWorkletCallback.ts
index d447fb04..febcf203 100644
--- a/package/src/hooks/useWorkletCallback.ts
+++ b/package/src/hooks/useWorkletCallback.ts
@@ -1,5 +1,5 @@
 import { useWorklet } from 'react-native-worklets-core'
-import { useFilamentContext } from '../react/Context'
+import { useFilamentContext } from './useFilamentContext'
 import { wrapWithErrorHandler } from '../ErrorUtils'
 
 /**
diff --git a/package/src/hooks/useWorkletEffect.ts b/package/src/hooks/useWorkletEffect.ts
index 05d1da5e..0b1573c5 100644
--- a/package/src/hooks/useWorkletEffect.ts
+++ b/package/src/hooks/useWorkletEffect.ts
@@ -1,5 +1,5 @@
 import { useEffect } from 'react'
-import { useFilamentContext } from '../react/Context'
+import { useFilamentContext } from './useFilamentContext'
 import { getWorkletDependencies, isWorklet } from 'react-native-worklets-core'
 import { wrapWithErrorHandler } from '../ErrorUtils'
 
diff --git a/package/src/hooks/useWorkletMemo.ts b/package/src/hooks/useWorkletMemo.ts
index 3ab229d2..09b7491e 100644
--- a/package/src/hooks/useWorkletMemo.ts
+++ b/package/src/hooks/useWorkletMemo.ts
@@ -1,5 +1,5 @@
 import { useEffect, useState } from 'react'
-import { useFilamentContext } from '../react/Context'
+import { useFilamentContext } from './useFilamentContext'
 import { wrapWithErrorHandler } from '../ErrorUtils'
 
 export function useWorkletMemo<T>(workletFunction: () => T, dependencies: any[]): T | undefined {
diff --git a/package/src/index.tsx b/package/src/index.tsx
index bcf489c7..cdcbced7 100644
--- a/package/src/index.tsx
+++ b/package/src/index.tsx
@@ -26,7 +26,7 @@ export { setLogger } from './utilities/logger/Logger'
 export * from './bullet'
 
 // React API
-export { useFilamentContext } from './react/Context'
+export { useFilamentContext } from './hooks/useFilamentContext'
 export { FilamentViewWithRenderCallbacks as FilamentView } from './react/FilamentViewWithRenderCallbacks'
 export * from './react/Model'
 export * from './react/ModelInstance'
@@ -38,6 +38,6 @@ export * from './react/EnvironmentalLight'
 export * from './react/Light'
 export * from './react/DefaultLight'
 export * from './react/Skybox'
-export * from './react/FilamentContext'
+export * from './react/FilamentScene'
 export * from './react/BackgroundImage'
 export * from './react/DebugBox'
diff --git a/package/src/react/BackgroundImage.tsx b/package/src/react/BackgroundImage.tsx
index b73465d5..e76001cb 100644
--- a/package/src/react/BackgroundImage.tsx
+++ b/package/src/react/BackgroundImage.tsx
@@ -4,7 +4,7 @@ import { useEntityInScene } from '../hooks/useEntityInScene'
 import { useWorkletCallback } from '../hooks/useWorkletCallback'
 import { useWorkletMemo } from '../hooks/useWorkletMemo'
 import { Mat3f } from '../types'
-import { useFilamentContext } from './Context'
+import { useFilamentContext } from '../hooks/useFilamentContext'
 
 export type BackgroundImageProps = {
   source: BufferSource
diff --git a/package/src/react/Camera.tsx b/package/src/react/Camera.tsx
index 35bb19d8..cea9e35c 100644
--- a/package/src/react/Camera.tsx
+++ b/package/src/react/Camera.tsx
@@ -1,6 +1,6 @@
 import { useSharedValue } from 'react-native-worklets-core'
 import { CameraManipulator, Float3 } from '../types'
-import { useFilamentContext } from './Context'
+import { useFilamentContext } from '../hooks/useFilamentContext'
 import { RenderCallbackContext } from './RenderCallbackContext'
 
 export type CameraProps = {
diff --git a/package/src/react/Configurator.tsx b/package/src/react/Configurator.tsx
index d31814c2..b1d5c02c 100644
--- a/package/src/react/Configurator.tsx
+++ b/package/src/react/Configurator.tsx
@@ -7,7 +7,7 @@ import {
   View,
   optionsToJSI,
 } from '../types'
-import { useFilamentContext } from './Context'
+import { useFilamentContext } from '../hooks/useFilamentContext'
 import { makeAmbientOcclusionHostObject } from '../utilities/makeAmbientOcclusionHostObject'
 import { makeDynamicResolutionHostObject } from '../utilities/makeDynamicResolutionHostObject'
 
@@ -30,7 +30,7 @@ export type ConfiguratorProps = PropsWithChildren<{
 
 /**
  * Takes configurations as props and applies them using the imperative API.
- * Needs to have a valid `FilamentContext` in the tree.
+ * Needs to have a valid `FilamentScene` in the tree.
  *
  * @private
  */
diff --git a/package/src/react/DebugBox.tsx b/package/src/react/DebugBox.tsx
index 60692b35..9198ae23 100644
--- a/package/src/react/DebugBox.tsx
+++ b/package/src/react/DebugBox.tsx
@@ -1,5 +1,5 @@
 import { useContext, useMemo } from 'react'
-import { useFilamentContext } from './Context'
+import { useFilamentContext } from '../hooks/useFilamentContext'
 import { Float3 } from '../types'
 import { TransformationProps } from './TransformContext'
 import { useApplyTransformations } from '../hooks/internal/useApplyTransformations'
diff --git a/package/src/react/EnvironmentalLight.tsx b/package/src/react/EnvironmentalLight.tsx
index b1b45d1c..57d5f399 100644
--- a/package/src/react/EnvironmentalLight.tsx
+++ b/package/src/react/EnvironmentalLight.tsx
@@ -1,5 +1,5 @@
 import { BufferSource, useBuffer } from '../hooks/useBuffer'
-import { useFilamentContext } from './Context'
+import { useFilamentContext } from '../hooks/useFilamentContext'
 import { useWorkletEffect } from '../hooks/useWorkletEffect'
 
 export type EnvironmentalLightProps = {
diff --git a/package/src/react/FilamentContext.tsx b/package/src/react/FilamentScene.tsx
similarity index 73%
rename from package/src/react/FilamentContext.tsx
rename to package/src/react/FilamentScene.tsx
index b446f432..8fd8c9d4 100644
--- a/package/src/react/FilamentContext.tsx
+++ b/package/src/react/FilamentScene.tsx
@@ -5,7 +5,7 @@ import { useDisposableResource } from '../hooks/useDisposableResource'
 import { useWorklet } from 'react-native-worklets-core'
 import React from 'react'
 import { Configurator, RendererConfigProps, ViewConfigProps } from './Configurator'
-import { Context, FilamentContextType } from './Context'
+import { FilamentContext, FilamentContextType } from '../hooks/useFilamentContext'
 import { RenderCallbackContext } from './RenderCallbackContext'
 
 export type FilamentProviderProps = PropsWithChildren<
@@ -17,11 +17,35 @@ export type FilamentProviderProps = PropsWithChildren<
 >
 
 /**
- * Creates an engine and all filament APIs and provides them to the children using the react context.
+ * The `<FilamentScene>` holds contextual values for a Filament rendering scene.
  *
- * @note You only need this for doing offscreen recording. For an on-screen surface use the `Filament` component.
+ * You need to wrap your rendering scene (= a component that uses `<FilamentView>`, hooks or
+ * other Filament components) with a `<FilamentScene>`.
+ *
+ * @note Make sure to wrap your scene in a parent component, otherwise the React context cannot be inferred.
+ * @example
+ * ```tsx
+ * function Scene() {
+ *   // in here you can use Filament's hooks and components
+ *   return (
+ *    <FilamentView style={styles.container}>
+ *      <DefaultLight />
+ *      <Model source={{ uri: modelPath }} />
+ *    </FilamentView>
+ *  )
+ * }
+ *
+ * export function RocketModel() {
+ *   // in here you only need to wrap the child-component with <FilamentScene>
+ *   return (
+ *     <FilamentScene>
+ *       <Scene />
+ *     </FilamentScene>
+ *   )
+ * }
+ * ```
  */
-export function FilamentContext({ children, fallback, config, backend, frameRateOptions, ...viewProps }: FilamentProviderProps) {
+export function FilamentScene({ children, fallback, config, backend, frameRateOptions, ...viewProps }: FilamentProviderProps) {
   // First create the engine, which we need to create (almost) all other filament APIs
   const engine = useEngine({ config, backend, context: FilamentWorkletContext })
 
@@ -71,7 +95,7 @@ export function FilamentContext({ children, fallback, config, backend, frameRate
       renderer,
       nameComponentManager,
       workletContext: FilamentWorkletContext,
-      _choreographer: choreographer,
+      choreographer: choreographer,
     }
   }, [engine, transformManager, renderableManager, scene, lightManager, view, camera, renderer, nameComponentManager, choreographer])
 
@@ -80,10 +104,10 @@ export function FilamentContext({ children, fallback, config, backend, frameRate
   // If the APIs aren't ready yet render the fallback component (or nothing)
   if (value == null) return fallback ?? null
   return (
-    <Context.Provider value={value}>
+    <FilamentContext.Provider value={value}>
       <Configurator rendererProps={rendererProps} viewProps={viewProps}>
         <RenderCallbackContext.RenderContextProvider>{children}</RenderCallbackContext.RenderContextProvider>
       </Configurator>
-    </Context.Provider>
+    </FilamentContext.Provider>
   )
 }
diff --git a/package/src/react/FilamentView.tsx b/package/src/react/FilamentView.tsx
index 0f9891d0..2cd3705a 100644
--- a/package/src/react/FilamentView.tsx
+++ b/package/src/react/FilamentView.tsx
@@ -2,7 +2,7 @@ import React from 'react'
 import { FilamentProxy } from '../native/FilamentProxy'
 import FilamentNativeView, { type FilamentViewNativeType, type NativeProps } from '../native/specs/FilamentViewNativeComponent'
 import { reportWorkletError, wrapWithErrorHandler } from '../ErrorUtils'
-import { Context } from './Context'
+import { FilamentContext } from '../hooks/useFilamentContext'
 import { RenderCallback, SwapChain } from 'react-native-filament'
 import type { SurfaceProvider, FilamentView as RNFFilamentView } from '../native/FilamentViewTypes'
 import { Listener } from '../types/Listener'
@@ -49,9 +49,8 @@ export class FilamentView extends React.PureComponent<FilamentProps> {
    * Uses the context in class.
    * @note Not available in the constructor!
    */
-  static contextType = Context
-  // @ts-ignore
-  context!: React.ContextType<typeof Context>
+  static contextType = FilamentContext
+  declare context: React.ContextType<typeof FilamentContext>
 
   constructor(props: FilamentProps) {
     super(props)
@@ -76,7 +75,7 @@ export class FilamentView extends React.PureComponent<FilamentProps> {
   private latestToken = 0
   private updateRenderCallback = async (callback: RenderCallback, swapChain: SwapChain) => {
     const currentToken = ++this.latestToken
-    const { renderer, view, workletContext, _choreographer } = this.getContext()
+    const { renderer, view, workletContext, choreographer } = this.getContext()
 
     // When requesting to update the render callback we have to assume that the previous one is not valid anymore
     // ie. its pointing to already released resources from useDisposableResource:
@@ -91,7 +90,7 @@ export class FilamentView extends React.PureComponent<FilamentProps> {
         // We need to create the function we pass to addFrameCallbackListener on the worklet thread, so that the
         // underlying JSI function is owned by that thread. Only then can we call it on the worklet thread when
         // the choreographer is calling its listeners.
-        return _choreographer.addFrameCallbackListener((frameInfo) => {
+        return choreographer.addFrameCallbackListener((frameInfo) => {
           'worklet'
 
           if (!swapChain.isValid) {
@@ -137,7 +136,7 @@ export class FilamentView extends React.PureComponent<FilamentProps> {
 
     // Calling this here ensures that only after the latest successful call for attaching a listener, the choreographer is started.
     Logger.debug('Starting choreographer')
-    _choreographer.start()
+    choreographer.start()
   }
 
   private getContext = () => {
@@ -172,8 +171,8 @@ export class FilamentView extends React.PureComponent<FilamentProps> {
    */
   cleanupResources() {
     Logger.debug('Cleaning up resources')
-    const { _choreographer } = this.getContext()
-    _choreographer.stop()
+    const { choreographer } = this.getContext()
+    choreographer.stop()
 
     this.renderCallbackListener?.remove()
     this.isSurfaceAlive.value = false
@@ -209,7 +208,7 @@ export class FilamentView extends React.PureComponent<FilamentProps> {
     Logger.debug('Found FilamentView!')
     // Link the view with the choreographer.
     // When the view gets destroyed, the choreographer will be stopped.
-    this.view.setChoreographer(context._choreographer)
+    this.view.setChoreographer(context.choreographer)
 
     if (this.ref.current == null) {
       throw new Error('Ref is not set!')
@@ -291,8 +290,8 @@ export class FilamentView extends React.PureComponent<FilamentProps> {
    */
   public pause = (): void => {
     Logger.info('Pausing rendering')
-    const { _choreographer } = this.getContext()
-    _choreographer.stop()
+    const { choreographer } = this.getContext()
+    choreographer.stop()
   }
 
   /**
@@ -301,8 +300,8 @@ export class FilamentView extends React.PureComponent<FilamentProps> {
    */
   public resume = (): void => {
     Logger.info('Resuming rendering')
-    const { _choreographer } = this.getContext()
-    _choreographer.start()
+    const { choreographer } = this.getContext()
+    choreographer.start()
   }
 
   private onTouchStart = (event: GestureResponderEvent) => {
diff --git a/package/src/react/Light.tsx b/package/src/react/Light.tsx
index ceb66ef1..bab18886 100644
--- a/package/src/react/Light.tsx
+++ b/package/src/react/Light.tsx
@@ -1,5 +1,5 @@
 import { UseLightEntityProps, useLightEntity } from '../hooks/useLightEntity'
-import { useFilamentContext } from './Context'
+import { useFilamentContext } from '../hooks/useFilamentContext'
 import { useEntityInScene } from '../hooks/useEntityInScene'
 
 export type LightProps = UseLightEntityProps
diff --git a/package/src/react/Model.tsx b/package/src/react/Model.tsx
index 765b0c46..e82ccb70 100644
--- a/package/src/react/Model.tsx
+++ b/package/src/react/Model.tsx
@@ -3,7 +3,7 @@ import { BufferSource } from '../hooks/useBuffer'
 import { ModelProps as UseModelProps, useModel } from '../hooks/useModel'
 import { ParentModelAssetContext } from './ParentModelAssetContext'
 import { getAssetFromModel } from '../utilities/getAssetFromModel'
-import { useFilamentContext } from './Context'
+import { useFilamentContext } from '../hooks/useFilamentContext'
 import { GestureResponderEvent } from 'react-native'
 import { Logger } from '../utilities/logger/Logger'
 import { Entity } from '../types'