From 7ad2e316499d4ed8bc4d0f0a3fb5e66b2aed18fe Mon Sep 17 00:00:00 2001
From: alvarosabu <alvaro.saburido@gmail.com>
Date: Fri, 5 Jan 2024 07:17:06 +0100
Subject: [PATCH 01/15] feat: conditional rendering

---
 .../src/pages/rendering-modes/index.vue       | 14 ++++
 .../src/pages/rendering-modes/scene.vue       | 22 ++++++
 playground/src/router.ts                      |  5 ++
 src/components/TresCanvas.vue                 |  6 +-
 src/composables/useRenderer/index.ts          | 46 +++++++++---
 .../useTresContextProvider/index.ts           | 70 +++++++++++++++----
 6 files changed, 137 insertions(+), 26 deletions(-)
 create mode 100644 playground/src/pages/rendering-modes/index.vue
 create mode 100644 playground/src/pages/rendering-modes/scene.vue

diff --git a/playground/src/pages/rendering-modes/index.vue b/playground/src/pages/rendering-modes/index.vue
new file mode 100644
index 000000000..4916464b5
--- /dev/null
+++ b/playground/src/pages/rendering-modes/index.vue
@@ -0,0 +1,14 @@
+<script setup lang="ts">
+import { TresCanvas } from '@tresjs/core'
+
+import Scene from './scene.vue'
+</script>
+
+<template>
+  <TresCanvas
+    clear-color="#82DBC5"
+    render-mode="on-demand"
+  >
+    <Scene />
+  </TresCanvas>
+</template>
\ No newline at end of file
diff --git a/playground/src/pages/rendering-modes/scene.vue b/playground/src/pages/rendering-modes/scene.vue
new file mode 100644
index 000000000..52db82e1e
--- /dev/null
+++ b/playground/src/pages/rendering-modes/scene.vue
@@ -0,0 +1,22 @@
+<script setup lang="ts">
+import { useRenderLoop, useTres } from '@tresjs/core'
+import { OrbitControls } from '@tresjs/cientos'
+
+const { invalidate } = useTres()
+
+function onControlChange() {
+  invalidate()
+}
+
+invalidate()
+</script>
+
+<template>
+  <OrbitControls @change="onControlChange" />
+  <TresGridHelper />
+  <TresMesh>
+    <TresBoxGeometry />
+    <TresMeshNormalMaterial />
+  </TresMesh>
+  <TresAmbientLight :intensity="1" />
+</template>
\ No newline at end of file
diff --git a/playground/src/router.ts b/playground/src/router.ts
index 7c4aad550..e14cfa4e8 100644
--- a/playground/src/router.ts
+++ b/playground/src/router.ts
@@ -76,6 +76,11 @@ const routes = [
     name: 'Perf',
     component: () => import('./pages/perf/index.vue'),
   },
+  {
+    path: '/rendering-modes',
+    name: 'Rendering Modes',
+    component: () => import('./pages/rendering-modes/index.vue'),
+  },
   {
     path: '/empty',
     name: 'empty',
diff --git a/src/components/TresCanvas.vue b/src/components/TresCanvas.vue
index fa86b472e..7da51c636 100644
--- a/src/components/TresCanvas.vue
+++ b/src/components/TresCanvas.vue
@@ -45,6 +45,7 @@ export interface TresCanvasProps
   useLegacyLights?: boolean
   outputColorSpace?: ColorSpace
   toneMappingExposure?: number
+  renderMode?: 'always' | 'on-demand' 
 
   // required by useTresContextProvider
   camera?: TresCamera
@@ -65,6 +66,7 @@ const props = withDefaults(defineProps<TresCanvasProps>(), {
   preserveDrawingBuffer: undefined,
   logarithmicDepthBuffer: undefined,
   failIfMajorPerformanceCaveat: undefined,
+  renderMode: 'always',
 })
 
 const { logWarning } = useLogger()
@@ -129,8 +131,8 @@ onMounted(() => {
   context.value = useTresContextProvider({
     scene: scene.value,
     canvas: existingCanvas,
-    windowSize: props.windowSize,
-    disableRender,
+    windowSize: props.windowSize ?? true,
+    disableRender: disableRender.value ?? false,
     rendererOptions: props,
   })
 
diff --git a/src/composables/useRenderer/index.ts b/src/composables/useRenderer/index.ts
index a073ad326..b8062ea9d 100644
--- a/src/composables/useRenderer/index.ts
+++ b/src/composables/useRenderer/index.ts
@@ -96,6 +96,7 @@ export interface UseRendererOptions extends TransformToMaybeRefOrGetter<WebGLRen
   clearColor?: MaybeRefOrGetter<TresColor>
   windowSize?: MaybeRefOrGetter<boolean | string>
   preset?: MaybeRefOrGetter<RendererPresetsType>
+  renderMode?: MaybeRefOrGetter<'always' | 'on-demand'>
 }
 
 /**
@@ -110,7 +111,7 @@ export function useRenderer(
     canvas,
     options,
     disableRender,
-    contextParts: { sizes, camera },
+    contextParts: { sizes, camera, internal },
   }:
   {
     canvas: MaybeRef<HTMLCanvasElement>
@@ -159,6 +160,30 @@ export function useRenderer(
 
   const { logError } = useLogger()
 
+  // TheLoop
+
+  const { resume, onLoop } = useRenderLoop()
+
+  onLoop(() => {
+    if (camera.value && !toValue(disableRender) && internal.frames.value > 0)
+      renderer.value.render(scene, camera.value)
+
+    // Call subscribers' render callbacks
+    internal.subscribers.value.forEach(({ callback }) => callback())
+
+    // Reset priority
+    internal.priority.value = 0
+
+    internal.frames.value = Math.max(0, internal.frames.value - 1)
+
+    if (toValue(options.renderMode) === 'always') {
+      internal.frames.value = 1
+    }
+
+  })
+
+  resume()
+
   const getThreeRendererDefaults = () => {
 
     const plainRenderer = new WebGLRenderer()
@@ -189,6 +214,15 @@ export function useRenderer(
       merge(renderer.value, rendererPresets[rendererPreset])
     }
 
+    // Render mode
+
+    const renderMode = toValue(options.renderMode)
+
+    if (renderMode === 'always') {
+      // If the render mode is 'always', ensure there's always a frame pending
+      internal.frames.value = Math.max(1, internal.frames.value)
+    } 
+
     const getValue = <T>(option: MaybeRefOrGetter<T>, pathInThree: string): T | undefined => {
       const value = toValue(option)
 
@@ -234,17 +268,7 @@ export function useRenderer(
 
   })
 
-  const { pause, resume, onLoop } = useRenderLoop()
-
-  onLoop(() => {
-    if (camera.value && !toValue(disableRender))
-      renderer.value.render(scene, camera.value)
-  })
-
-  resume()
-
   onUnmounted(() => {
-    pause() // TODO should the render loop pause itself if there is no more renderer? 🤔 What if there is another renderer which needs the loop?
     renderer.value.dispose()
     renderer.value.forceContextLoss()
   })
diff --git a/src/composables/useTresContextProvider/index.ts b/src/composables/useTresContextProvider/index.ts
index 378814eb2..7af6abeba 100644
--- a/src/composables/useTresContextProvider/index.ts
+++ b/src/composables/useTresContextProvider/index.ts
@@ -9,6 +9,32 @@ import type { UseRendererOptions } from '../useRenderer'
 import { useRenderer } from '../useRenderer'
 import { extend } from '../../core/catalogue'
 
+export interface InternalSubscriber {
+  callback: (timestamp: number) => void
+  priority: number
+}
+
+export interface InternalState {
+  priority: Ref<number>
+  frames: Ref<number>
+  subscribers: Ref<InternalSubscriber[]>
+  maxFrames: number
+  subscribe: (callback: (timestamp: number) => void, priority: number) => () => void
+}
+
+export interface PerformanceState {
+  maxFrames: number
+  fps: {
+    value: number
+    accumulator: number[]
+  }
+  memory: {
+    currentMem: number
+    allocatedMem: number
+    accumulator: number[]
+  }
+}
+
 export interface TresContext {
   scene: ShallowRef<Scene>
   sizes: { height: Ref<number>; width: Ref<number>; aspectRatio: ComputedRef<number> }
@@ -18,18 +44,9 @@ export interface TresContext {
   controls: Ref<(EventDispatcher & { enabled: boolean }) | null>
   renderer: ShallowRef<WebGLRenderer>
   raycaster: ShallowRef<Raycaster>
-  perf: {
-    maxFrames: number
-    fps: {
-      value: number
-      accumulator: number[]
-    }
-    memory: {
-      currentMem: number
-      allocatedMem: number
-      accumulator: number[]
-    }
-  }
+  perf: PerformanceState
+  internal: InternalState
+  invalidate: () => void
   registerCamera: (camera: Camera) => void
   setCameraActive: (cameraOrUuid: Camera | string) => void
   deregisterCamera: (camera: Camera) => void
@@ -74,15 +91,40 @@ export function useTresContextProvider({
     setCameraActive,
   } = useCamera({ sizes, scene })
 
+  // Initialize internal state
+  const internal: InternalState = {
+    priority: ref(0),
+    frames: ref(0),
+    subscribers: ref([]),
+    maxFrames: 60,
+    subscribe: (callback, priority) => {
+      const subscription = { callback, priority }
+      internal.subscribers.value.push(subscription)
+      // Sort subscribers based on priority
+      internal.subscribers.value.sort((a, b) => b.priority - a.priority)
+  
+      // Return an unsubscribe function
+      return () => {
+        const index = internal.subscribers.value.indexOf(subscription)
+        if (index > -1) internal.subscribers.value.splice(index, 1)
+      }
+    },
+  }
+
   const { renderer } = useRenderer(
     {
       scene,
       canvas,
       options: rendererOptions,
-      contextParts: { sizes, camera },
+      contextParts: { sizes, camera, internal },
       disableRender,
     })
 
+  function invalidate(frames = 1) {
+    // Increase the frame count, ensuring not to exceed a maximum if desired
+    internal.frames.value = Math.min(internal.maxFrames, internal.frames.value + frames)
+  }
+
   const toProvide: TresContext = {
     sizes,
     scene: localScene,
@@ -103,7 +145,9 @@ export function useTresContextProvider({
         accumulator: [],
       },
     },
+    internal,
     extend,
+    invalidate,
     registerCamera,
     setCameraActive,
     deregisterCamera,

From 5d72244ff92c18a02db7b1425232b9223a2c4196 Mon Sep 17 00:00:00 2001
From: alvarosabu <alvaro.saburido@gmail.com>
Date: Fri, 5 Jan 2024 10:39:22 +0100
Subject: [PATCH 02/15] chore: remove subscribe system

---
 src/composables/useRenderer/index.ts          |  3 ---
 .../useTresContextProvider/index.ts           | 20 -------------------
 2 files changed, 23 deletions(-)

diff --git a/src/composables/useRenderer/index.ts b/src/composables/useRenderer/index.ts
index b8062ea9d..9370d7e91 100644
--- a/src/composables/useRenderer/index.ts
+++ b/src/composables/useRenderer/index.ts
@@ -168,9 +168,6 @@ export function useRenderer(
     if (camera.value && !toValue(disableRender) && internal.frames.value > 0)
       renderer.value.render(scene, camera.value)
 
-    // Call subscribers' render callbacks
-    internal.subscribers.value.forEach(({ callback }) => callback())
-
     // Reset priority
     internal.priority.value = 0
 
diff --git a/src/composables/useTresContextProvider/index.ts b/src/composables/useTresContextProvider/index.ts
index 7af6abeba..f293ef801 100644
--- a/src/composables/useTresContextProvider/index.ts
+++ b/src/composables/useTresContextProvider/index.ts
@@ -9,17 +9,10 @@ import type { UseRendererOptions } from '../useRenderer'
 import { useRenderer } from '../useRenderer'
 import { extend } from '../../core/catalogue'
 
-export interface InternalSubscriber {
-  callback: (timestamp: number) => void
-  priority: number
-}
-
 export interface InternalState {
   priority: Ref<number>
   frames: Ref<number>
-  subscribers: Ref<InternalSubscriber[]>
   maxFrames: number
-  subscribe: (callback: (timestamp: number) => void, priority: number) => () => void
 }
 
 export interface PerformanceState {
@@ -95,20 +88,7 @@ export function useTresContextProvider({
   const internal: InternalState = {
     priority: ref(0),
     frames: ref(0),
-    subscribers: ref([]),
     maxFrames: 60,
-    subscribe: (callback, priority) => {
-      const subscription = { callback, priority }
-      internal.subscribers.value.push(subscription)
-      // Sort subscribers based on priority
-      internal.subscribers.value.sort((a, b) => b.priority - a.priority)
-  
-      // Return an unsubscribe function
-      return () => {
-        const index = internal.subscribers.value.indexOf(subscription)
-        if (index > -1) internal.subscribers.value.splice(index, 1)
-      }
-    },
   }
 
   const { renderer } = useRenderer(

From b2cfa4a92b4af49c988a849c6f2b4a92e9a93328 Mon Sep 17 00:00:00 2001
From: alvarosabu <alvaro.saburido@gmail.com>
Date: Fri, 5 Jan 2024 11:44:00 +0100
Subject: [PATCH 03/15] feat: on-demand automatic invalidation with prop
 changes

---
 .../src/pages/rendering-modes/scene.vue       |  8 ++++++-
 src/components/TresCanvas.vue                 |  2 +-
 src/composables/useRenderer/index.ts          |  2 +-
 .../useTresContextProvider/index.ts           |  7 +++++-
 src/core/nodeOps.ts                           | 22 ++++++++++++++++++-
 src/devtools/plugin.ts                        |  5 ++++-
 6 files changed, 40 insertions(+), 6 deletions(-)

diff --git a/playground/src/pages/rendering-modes/scene.vue b/playground/src/pages/rendering-modes/scene.vue
index 52db82e1e..91bded00c 100644
--- a/playground/src/pages/rendering-modes/scene.vue
+++ b/playground/src/pages/rendering-modes/scene.vue
@@ -8,13 +8,19 @@ function onControlChange() {
   invalidate()
 }
 
+const positionX = ref(0)
+
+setTimeout(() => {
+  positionX.value = 1
+}, 3000)
+
 invalidate()
 </script>
 
 <template>
   <OrbitControls @change="onControlChange" />
   <TresGridHelper />
-  <TresMesh>
+  <TresMesh :position-x="positionX">
     <TresBoxGeometry />
     <TresMeshNormalMaterial />
   </TresMesh>
diff --git a/src/components/TresCanvas.vue b/src/components/TresCanvas.vue
index 7da51c636..dbcefa87e 100644
--- a/src/components/TresCanvas.vue
+++ b/src/components/TresCanvas.vue
@@ -45,7 +45,7 @@ export interface TresCanvasProps
   useLegacyLights?: boolean
   outputColorSpace?: ColorSpace
   toneMappingExposure?: number
-  renderMode?: 'always' | 'on-demand' 
+  renderMode?: 'always' | 'on-demand' | 'manual' 
 
   // required by useTresContextProvider
   camera?: TresCamera
diff --git a/src/composables/useRenderer/index.ts b/src/composables/useRenderer/index.ts
index 9370d7e91..df509156e 100644
--- a/src/composables/useRenderer/index.ts
+++ b/src/composables/useRenderer/index.ts
@@ -96,7 +96,7 @@ export interface UseRendererOptions extends TransformToMaybeRefOrGetter<WebGLRen
   clearColor?: MaybeRefOrGetter<TresColor>
   windowSize?: MaybeRefOrGetter<boolean | string>
   preset?: MaybeRefOrGetter<RendererPresetsType>
-  renderMode?: MaybeRefOrGetter<'always' | 'on-demand'>
+  renderMode?: MaybeRefOrGetter<'always' | 'on-demand' | 'manual'>
 }
 
 /**
diff --git a/src/composables/useTresContextProvider/index.ts b/src/composables/useTresContextProvider/index.ts
index f293ef801..0a6c8b8fd 100644
--- a/src/composables/useTresContextProvider/index.ts
+++ b/src/composables/useTresContextProvider/index.ts
@@ -38,6 +38,7 @@ export interface TresContext {
   renderer: ShallowRef<WebGLRenderer>
   raycaster: ShallowRef<Raycaster>
   perf: PerformanceState
+  renderMode: MaybeRefOrGetter<'always' | 'on-demand' | 'manual'>
   internal: InternalState
   invalidate: () => void
   registerCamera: (camera: Camera) => void
@@ -125,6 +126,7 @@ export function useTresContextProvider({
         accumulator: [],
       },
     },
+    renderMode: ref(rendererOptions.renderMode || 'always'),
     internal,
     extend,
     invalidate,
@@ -135,6 +137,9 @@ export function useTresContextProvider({
 
   provide('useTres', toProvide)
 
+  // Add context to scene.userData
+  toProvide.scene.value.userData.tres__context = toProvide
+
   // Performance
   const updateInterval = 100 // Update interval in milliseconds
   const fps = useFps({ every: updateInterval }) 
@@ -182,7 +187,7 @@ export function useTresContextProvider({
   let accumulatedTime = 0
   const interval = 1 // Interval in milliseconds, e.g., 1000 ms = 1 second
     
-  const { pause, resume } = useRafFn(({ delta }) => {
+  const { pause } = useRafFn(({ delta }) => {
     if (!window.__TRES__DEVTOOLS__) return
 
     updatePerformanceData({ timestamp: performance.now() })
diff --git a/src/core/nodeOps.ts b/src/core/nodeOps.ts
index 6b614c9a9..814d80574 100644
--- a/src/core/nodeOps.ts
+++ b/src/core/nodeOps.ts
@@ -23,6 +23,17 @@ const supportedPointerEvents = [
   'onPointerLeave',
 ]
 
+export function invalidateInstance(instance: TresObject) {
+  const ctx = instance.userData.tres__root?.userData?.tres__context
+  
+  if (!ctx) return
+  
+  if (ctx.renderMode.value === 'on-demand' && ctx.internal.frames.value === 0) {
+    ctx.invalidate()
+  }
+
+}
+
 export const nodeOps: RendererOptions<TresObject, TresObject> = {
   createElement(tag, _isSVG, _anchor, props) {
     if (!props) props = {}
@@ -81,11 +92,17 @@ export const nodeOps: RendererOptions<TresObject, TresObject> = {
     return instance
   },
   insert(child, parent) {
-    if (parent && parent.isScene) scene = parent as unknown as TresScene
+    if (parent && parent.isScene) {
+      scene = parent as unknown as TresScene
+      if (child) {
+        child.userData.tres__root = scene
+      }
+    }
 
     const parentObject = parent || scene
 
     if (child?.isObject3D) {
+
       if (child?.isCamera) {
         if (!scene?.userData.tres__registerCamera)
           throw 'could not find tres__registerCamera on scene\'s userData'
@@ -180,6 +197,7 @@ export const nodeOps: RendererOptions<TresObject, TresObject> = {
       deregisterAtPointerEventHandlerIfRequired?.(object3D as TresObject)
     }
 
+    invalidateInstance(node as TresObject)
     node.dispose?.()
   },
   patchProp(node, prop, _prevValue, nextValue) {
@@ -243,6 +261,8 @@ export const nodeOps: RendererOptions<TresObject, TresObject> = {
       else if (Array.isArray(value)) target.set(...value)
       else if (!target.isColor && target.setScalar) target.setScalar(value)
       else target.set(value)
+
+      invalidateInstance(node as TresObject)
     }
   },
 
diff --git a/src/devtools/plugin.ts b/src/devtools/plugin.ts
index 45cae64e9..b12d2b858 100644
--- a/src/devtools/plugin.ts
+++ b/src/devtools/plugin.ts
@@ -271,12 +271,15 @@ export function registerTresDevtools(app: DevtoolsApp, tres: TresContext) {
                 key: 'matrixWorld',
                 value: instance.matrixWorld,
               },
-                
               {
                 key: 'visible',
                 editable: true,
                 value: instance.visible,
               },
+              {
+                key: 'userData',
+                value: instance.userData,
+              },
             ],
           }
         }

From 97921a52a628ea1f0d2f148ac21f37d9c1e8aaed Mon Sep 17 00:00:00 2001
From: alvarosabu <alvaro.saburido@gmail.com>
Date: Fri, 5 Jan 2024 12:02:08 +0100
Subject: [PATCH 04/15] feat: invalidate once first when is `renderMode !==
 'always'`

---
 playground/src/pages/rendering-modes/index.vue  |  4 +++-
 playground/src/pages/rendering-modes/scene.vue  | 11 ++++++++---
 src/composables/useRenderer/index.ts            |  8 ++++++--
 src/composables/useTresContextProvider/index.ts |  2 +-
 4 files changed, 18 insertions(+), 7 deletions(-)

diff --git a/playground/src/pages/rendering-modes/index.vue b/playground/src/pages/rendering-modes/index.vue
index 4916464b5..e2888af07 100644
--- a/playground/src/pages/rendering-modes/index.vue
+++ b/playground/src/pages/rendering-modes/index.vue
@@ -2,11 +2,13 @@
 import { TresCanvas } from '@tresjs/core'
 
 import Scene from './scene.vue'
+
+const clearColor = ref('#82DBC5')
 </script>
 
 <template>
   <TresCanvas
-    clear-color="#82DBC5"
+    :clear-color="clearColor"
     render-mode="on-demand"
   >
     <Scene />
diff --git a/playground/src/pages/rendering-modes/scene.vue b/playground/src/pages/rendering-modes/scene.vue
index 91bded00c..323cb9ddb 100644
--- a/playground/src/pages/rendering-modes/scene.vue
+++ b/playground/src/pages/rendering-modes/scene.vue
@@ -9,18 +9,23 @@ function onControlChange() {
 }
 
 const positionX = ref(0)
+const showMesh = ref(true)
 
 setTimeout(() => {
-  positionX.value = 1
+  /*  positionX.value = 1 */
+  showMesh.value = false
 }, 3000)
 
-invalidate()
+/* invalidate() */
 </script>
 
 <template>
   <OrbitControls @change="onControlChange" />
   <TresGridHelper />
-  <TresMesh :position-x="positionX">
+  <TresMesh
+    v-if="showMesh"
+    :position-x="positionX"
+  >
     <TresBoxGeometry />
     <TresMeshNormalMaterial />
   </TresMesh>
diff --git a/src/composables/useRenderer/index.ts b/src/composables/useRenderer/index.ts
index df509156e..05a9ac6ef 100644
--- a/src/composables/useRenderer/index.ts
+++ b/src/composables/useRenderer/index.ts
@@ -111,7 +111,7 @@ export function useRenderer(
     canvas,
     options,
     disableRender,
-    contextParts: { sizes, camera, internal },
+    contextParts: { sizes, camera, internal, invalidate },
   }:
   {
     canvas: MaybeRef<HTMLCanvasElement>
@@ -218,7 +218,11 @@ export function useRenderer(
     if (renderMode === 'always') {
       // If the render mode is 'always', ensure there's always a frame pending
       internal.frames.value = Math.max(1, internal.frames.value)
-    } 
+    }
+    else {
+      // Invalidate for the first time
+      invalidate()
+    }
 
     const getValue = <T>(option: MaybeRefOrGetter<T>, pathInThree: string): T | undefined => {
       const value = toValue(option)
diff --git a/src/composables/useTresContextProvider/index.ts b/src/composables/useTresContextProvider/index.ts
index 0a6c8b8fd..4a54d0a8b 100644
--- a/src/composables/useTresContextProvider/index.ts
+++ b/src/composables/useTresContextProvider/index.ts
@@ -97,7 +97,7 @@ export function useTresContextProvider({
       scene,
       canvas,
       options: rendererOptions,
-      contextParts: { sizes, camera, internal },
+      contextParts: { sizes, camera, internal, invalidate },
       disableRender,
     })
 

From d5efdf48c94c2310bc4c6e942421f88f87c027a8 Mon Sep 17 00:00:00 2001
From: alvarosabu <alvaro.saburido@gmail.com>
Date: Fri, 5 Jan 2024 20:59:19 +0100
Subject: [PATCH 05/15] docs: performance page, on-demand rendering

---
 docs/.vitepress/config.ts                     |  1 +
 .../theme/components/BlenderCube.vue          | 17 ++++
 .../.vitepress/theme/components/GraphPane.vue | 87 +++++++++++++++++++
 .../theme/components/OnDemandRendering.vue    | 40 +++++++++
 .../theme/components/RenderingLogger.vue      | 24 +++++
 docs/.vitepress/theme/composables/state.ts    | 11 +++
 docs/advanced/performance.md                  | 34 ++++++++
 docs/api/tres-canvas.md                       |  5 +-
 docs/components.d.ts                          |  4 +
 docs/package.json                             |  2 +-
 .../src/pages/rendering-modes/index.vue       |  5 ++
 .../src/pages/rendering-modes/scene.vue       |  2 +-
 pnpm-lock.yaml                                |  2 +-
 src/components/TresCanvas.vue                 |  4 +-
 src/composables/useRenderer/index.ts          | 27 ++++--
 .../useTresContextProvider/index.ts           |  3 +
 16 files changed, 256 insertions(+), 12 deletions(-)
 create mode 100644 docs/.vitepress/theme/components/BlenderCube.vue
 create mode 100644 docs/.vitepress/theme/components/GraphPane.vue
 create mode 100644 docs/.vitepress/theme/components/OnDemandRendering.vue
 create mode 100644 docs/.vitepress/theme/components/RenderingLogger.vue
 create mode 100644 docs/.vitepress/theme/composables/state.ts
 create mode 100644 docs/advanced/performance.md

diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index 9fd4c4c6b..e9316bbd3 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -81,6 +81,7 @@ export default defineConfig({
         items: [
           { text: 'Extending', link: '/advanced/extending' },
           { text: 'primitive', link: '/advanced/primitive' },
+          { text: 'Performance', link: '/advanced/performance' },
           {
             text: 'Caveats',
             link: '/advanced/caveats',
diff --git a/docs/.vitepress/theme/components/BlenderCube.vue b/docs/.vitepress/theme/components/BlenderCube.vue
new file mode 100644
index 000000000..c3fb58554
--- /dev/null
+++ b/docs/.vitepress/theme/components/BlenderCube.vue
@@ -0,0 +1,17 @@
+<script setup lang="ts">
+import { useTresContext } from '@tresjs/core'
+import { useGLTF } from '@tresjs/cientos'
+
+const { nodes } = await useGLTF('https://raw.githubusercontent.com/Tresjs/assets/main/models/gltf/blender-cube.glb', { draco: true })
+const model = nodes.Cube
+
+model.position.set(0, 1, 0)
+
+const state = useTresContext()
+
+state.invalidate()
+</script>
+
+<template>
+  <primitive :object="model" />
+</template>
\ No newline at end of file
diff --git a/docs/.vitepress/theme/components/GraphPane.vue b/docs/.vitepress/theme/components/GraphPane.vue
new file mode 100644
index 000000000..9403f990b
--- /dev/null
+++ b/docs/.vitepress/theme/components/GraphPane.vue
@@ -0,0 +1,87 @@
+<script lang="ts" setup>
+import { ref } from 'vue'
+import { useRafFn } from '@vueuse/core'
+import { useState } from '../composables/state'
+
+const width = 160
+const height = 40
+const strokeWidth = 2
+const updateInterval = 100 // Update interval in milliseconds
+const topOffset = 0 // Offset from the top
+
+const points = ref('')
+const frameTimes = ref([])
+const maxFrames = ref(width / strokeWidth)
+
+let lastUpdateTime = performance.now()
+
+const { renderingTimes } = useState()
+
+useRafFn(({ timestamp }) => {
+  if (timestamp - lastUpdateTime >= updateInterval) {
+    lastUpdateTime = timestamp
+
+    frameTimes.value.push(renderingTimes?.value)
+    renderingTimes.value = 0
+
+    if (frameTimes.value.length > maxFrames.value) {
+      frameTimes.value.shift()
+    }
+
+    points.value = frameTimes.value
+      .map(
+        (value, index) =>
+          `${index * strokeWidth},${
+            height + topOffset - strokeWidth / 2 - (value * (height + topOffset - strokeWidth)) / 2
+          }`,
+      )
+      .join(' ')
+  }
+})
+</script>
+
+<template>
+  <div
+    class="absolute right-2 top-2 flex px-4 py-1 justify-between gap-4 items-center mb-2 z-10 bg-white shadow-xl
+      rounded 
+      border-4 
+      border-solid 
+      bg-primary 
+      border-primary 
+      pointer-events-none
+      overflow-hidden"
+  >
+    <label class="text-secondary text-xs w-1/3">Rendering Activity</label>
+
+    <div
+      class="
+        bg-gray-100
+        relative
+        w-2/3
+        p-1
+        rounded
+        text-right
+        text-xs
+        focus:border-gray-200
+        outline-none
+        border-none
+        font-sans
+      "
+    >
+      <svg
+        :width="width"
+        :height="height"
+        xmlns="http://www.w3.org/2000/svg"
+        fill="none"
+      >
+        <polyline
+          :points="points"
+          stroke="lightgray"
+          :stroke-width="strokeWidth"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+        />
+      </svg>
+    </div>
+  </div>
+</template>
\ No newline at end of file
diff --git a/docs/.vitepress/theme/components/OnDemandRendering.vue b/docs/.vitepress/theme/components/OnDemandRendering.vue
new file mode 100644
index 000000000..3f7a07a6b
--- /dev/null
+++ b/docs/.vitepress/theme/components/OnDemandRendering.vue
@@ -0,0 +1,40 @@
+<script setup lang="ts">
+import { TresCanvas } from '@tresjs/core'
+import { BasicShadowMap, SRGBColorSpace, NoToneMapping } from 'three'
+import { OrbitControls } from '@tresjs/cientos'
+import { useState } from '../composables/state'
+import BlenderCube from './BlenderCube.vue'
+import GraphPane from './GraphPane.vue'
+import RenderingLogger from './RenderingLogger.vue'
+
+const { renderingTimes } = useState()
+
+function onRender() {
+  renderingTimes.value = 1
+
+}
+</script>
+
+<template>
+  <GraphPane />
+  <TresCanvas
+    render-mode="on-demand"
+    clear-color="#82DBC5"
+    @render="onRender"
+  >
+    <TresPerspectiveCamera
+      :position="[5, 5, 5]"
+      :look-at="[0, 0, 0]"
+    />
+    <Suspense>
+      <BlenderCube />
+    </Suspense>
+    <TresGridHelper />
+    <RenderingLogger />
+    <TresAmbientLight :intensity="1" />
+    <TresDirectionalLight
+      :position="[0, 8, 4]"
+      :intensity="0.7"
+    />
+  </TresCanvas>
+</template>
\ No newline at end of file
diff --git a/docs/.vitepress/theme/components/RenderingLogger.vue b/docs/.vitepress/theme/components/RenderingLogger.vue
new file mode 100644
index 000000000..eddb08648
--- /dev/null
+++ b/docs/.vitepress/theme/components/RenderingLogger.vue
@@ -0,0 +1,24 @@
+<script setup lang="ts">
+import { useRenderLoop, useTresContext } from '@tresjs/core'
+import { OrbitControls } from '@tresjs/cientos'
+import { onMounted } from 'vue'
+import { useState } from '../composables/state'
+
+const { renderingTimes } = useState()
+
+const state = useTresContext()
+
+function manualInvalidate() {
+  state.invalidate()
+}
+
+onMounted(() => {
+  manualInvalidate()
+})
+</script>
+
+<template>
+  <OrbitControls
+    @change="manualInvalidate"
+  />
+</template>
\ No newline at end of file
diff --git a/docs/.vitepress/theme/composables/state.ts b/docs/.vitepress/theme/composables/state.ts
new file mode 100644
index 000000000..70bf5769e
--- /dev/null
+++ b/docs/.vitepress/theme/composables/state.ts
@@ -0,0 +1,11 @@
+import { reactive, toRefs } from 'vue'
+
+const state = reactive({
+  renderingTimes: 0,
+})
+export function useState() {
+  return {
+    ...toRefs(state),
+    
+  }
+}
\ No newline at end of file
diff --git a/docs/advanced/performance.md b/docs/advanced/performance.md
new file mode 100644
index 000000000..f82306243
--- /dev/null
+++ b/docs/advanced/performance.md
@@ -0,0 +1,34 @@
+# Scaling performance 🚀
+
+> Quick guide with tips to improve performance of your Tres.js application.
+
+We are running WebGL on the browser, which can be quite expensive and it will depend on how powerful the user's device is. To make 3D accessible to everyone, we need to make sure our applications are optimized to run also on low-end devices. This guide will provide some tips to improve the performance of your Tres.js application.
+
+## On-demand rendering
+
+By default, Tres.js will render your scene on every frame. This is great for most applications, but if you are building a game or a complex application, you might want to control when the scene is rendered. 
+
+Otherwise it might drain your device battery 🔋 🔜 🪫 and make your computer sound like an airplane 🛫.
+
+Ideally, you only want to **render the scene when necessary**, for example when the user interacts with the scene and the camera moves, or when objects in the scene are animated.
+
+You can do that by setting the `renderMode` prop to `on-demand` or `manual`:
+
+
+### Mode `on-demand`
+
+<ClientOnly>
+  <div style="position: relative; aspect-ratio: 16/9; height: auto; margin: 2rem 0; border-radius: 8px; overflow:hidden;">
+    <onDemandRendering />
+  </div>
+</ClientOnly>
+
+
+```vue
+<TresCanvas render-mode="on-demand">
+  <!-- Your scene goes here -->
+</TresCanvas>
+```
+
+
+
diff --git a/docs/api/tres-canvas.md b/docs/api/tres-canvas.md
index 0eefef975..8b2120d14 100644
--- a/docs/api/tres-canvas.md
+++ b/docs/api/tres-canvas.md
@@ -77,12 +77,13 @@ renderer.shadowMap.type = PCFSoftShadowMap
 | **clearColor** | The color the renderer will use to clear the canvas. | `#000000` |
 | **context** | This can be used to attach the renderer to an existing [RenderingContext](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext) | |
 | **depth** | Whether the drawing buffer has a [depth buffer](https://en.wikipedia.org/wiki/Z-buffering) of at least 16 bits. | `true` |
+| **renderMode** | Render mode, can be `always`, `on-demand` or `manual`. See [Performance](../advanced/performance)  | `always` |
 | **disableRender** | Disable render on requestAnimationFrame, useful for PostProcessing | `false` |
 | **failIfMajorPerformanceCaveat** | Whether the renderer creation will fail upon low performance is detected. See [WebGL spec](https://registry.khronos.org/webgl/specs/latest/1.0/#5.2) for details. | `false` |
 | **logarithmicDepthBuffer** | Whether to use a logarithmic depth buffer. It may be necessary to use this if dealing with huge differences in scale in a single scene. Note that this setting uses gl_FragDepth if available which disables the [Early Fragment Test](https://www.khronos.org/opengl/wiki/Early_Fragment_Test) optimization and can cause a decrease in performance. | `false` |
 | **outputColorSpace** | Defines the output encoding | `LinearEncoding` |
-| **powerPreference** | Provides a hint to the user agent indicating what configuration of GPU is suitable for this WebGL context. Can be "high-performance", "low-power" or "default". | `default` |
-| **precision** | Shader precision. Can be "highp", "mediump" or "lowp". | "highp" if supported by the device |
+| **powerPreference** | Provides a hint to the user agent indicating what configuration of GPU is suitable for this WebGL context. Can be `high-performance`, `low-power` or `default`. | `default` |
+| **precision** | Shader precision. Can be `highp`, `mediump` or `lowp`. | "highp" if supported by the device |
 | **premultipliedAlpha** | Whether the renderer will assume that colors have [premultiplied alpha](https://en.wikipedia.org/wiki/Glossary_of_computer_graphics#premultiplied_alpha). | `true` |
 | **preserveDrawingBuffer** | Whether to preserve the buffers until manually cleared or overwritten.. | `false` |
 | **shadows** | Enable shadows in the renderer | `false` |
diff --git a/docs/components.d.ts b/docs/components.d.ts
index 8ffba3ba5..9231857f3 100644
--- a/docs/components.d.ts
+++ b/docs/components.d.ts
@@ -7,14 +7,18 @@ export {}
 
 declare module 'vue' {
   export interface GlobalComponents {
+    BlenderCube: typeof import('./.vitepress/theme/components/BlenderCube.vue')['default']
     DonutExample: typeof import('./.vitepress/theme/components/DonutExample.vue')['default']
     EmbedExperiment: typeof import('./.vitepress/theme/components/EmbedExperiment.vue')['default']
     ExtendExample: typeof import('./.vitepress/theme/components/ExtendExample.vue')['default']
     FirstScene: typeof import('./.vitepress/theme/components/FirstScene.vue')['default']
     FirstSceneLightToon: typeof import('./.vitepress/theme/components/FirstSceneLightToon.vue')['default']
+    GraphPane: typeof import('./.vitepress/theme/components/GraphPane.vue')['default']
     HomeSponsors: typeof import('./.vitepress/theme/components/HomeSponsors.vue')['default']
     LocalOrbitControls: typeof import('./.vitepress/theme/components/LocalOrbitControls.vue')['default']
     LoveVueThreeJS: typeof import('./.vitepress/theme/components/LoveVueThreeJS.vue')['default']
+    OnDemandRendering: typeof import('./.vitepress/theme/components/OnDemandRendering.vue')['default']
+    RenderingLogger: typeof import('./.vitepress/theme/components/RenderingLogger.vue')['default']
     RouterLink: typeof import('vue-router')['RouterLink']
     RouterView: typeof import('vue-router')['RouterView']
     SandboxDemo: typeof import('./.vitepress/theme/components/SandboxDemo.vue')['default']
diff --git a/docs/package.json b/docs/package.json
index 7f7584928..bc5226afd 100644
--- a/docs/package.json
+++ b/docs/package.json
@@ -9,7 +9,7 @@
     "preview": "vitepress preview"
   },
   "dependencies": {
-    "@tresjs/core": "workspace:*"
+    "@tresjs/core": "workspace:^"
   },
   "devDependencies": {
     "unocss": "^0.58.3",
diff --git a/playground/src/pages/rendering-modes/index.vue b/playground/src/pages/rendering-modes/index.vue
index e2888af07..014366a1a 100644
--- a/playground/src/pages/rendering-modes/index.vue
+++ b/playground/src/pages/rendering-modes/index.vue
@@ -4,12 +4,17 @@ import { TresCanvas } from '@tresjs/core'
 import Scene from './scene.vue'
 
 const clearColor = ref('#82DBC5')
+
+setTimeout(() => {
+  clearColor.value = '#000000'
+}, 3000)
 </script>
 
 <template>
   <TresCanvas
     :clear-color="clearColor"
     render-mode="on-demand"
+    @render="() => console.log('onRender')"
   >
     <Scene />
   </TresCanvas>
diff --git a/playground/src/pages/rendering-modes/scene.vue b/playground/src/pages/rendering-modes/scene.vue
index 323cb9ddb..cd8fe5bb6 100644
--- a/playground/src/pages/rendering-modes/scene.vue
+++ b/playground/src/pages/rendering-modes/scene.vue
@@ -13,7 +13,7 @@ const showMesh = ref(true)
 
 setTimeout(() => {
   /*  positionX.value = 1 */
-  showMesh.value = false
+/*   showMesh.value = false */
 }, 3000)
 
 /* invalidate() */
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 00df05e3d..71f6b70b4 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -130,7 +130,7 @@ importers:
   docs:
     dependencies:
       '@tresjs/core':
-        specifier: workspace:*
+        specifier: workspace:^
         version: link:..
     devDependencies:
       unocss:
diff --git a/src/components/TresCanvas.vue b/src/components/TresCanvas.vue
index dbcefa87e..132e94e34 100644
--- a/src/components/TresCanvas.vue
+++ b/src/components/TresCanvas.vue
@@ -69,6 +69,8 @@ const props = withDefaults(defineProps<TresCanvasProps>(), {
   renderMode: 'always',
 })
 
+const emit = defineEmits(['render'])
+
 const { logWarning } = useLogger()
 
 const canvas = ref<HTMLCanvasElement>()
@@ -124,7 +126,6 @@ const disableRender = computed(() => props.disableRender)
 const context = shallowRef<TresContext | null>(null)
 
 defineExpose({ context, dispose: () => dispose(context.value as TresContext, true) })
-
 onMounted(() => {
   const existingCanvas = canvas as Ref<HTMLCanvasElement>
 
@@ -134,6 +135,7 @@ onMounted(() => {
     windowSize: props.windowSize ?? true,
     disableRender: disableRender.value ?? false,
     rendererOptions: props,
+    emit,
   })
 
   usePointerEventHandler({ scene: scene.value, contextParts: context.value })
diff --git a/src/composables/useRenderer/index.ts b/src/composables/useRenderer/index.ts
index 05a9ac6ef..38ac5b266 100644
--- a/src/composables/useRenderer/index.ts
+++ b/src/composables/useRenderer/index.ts
@@ -98,7 +98,6 @@ export interface UseRendererOptions extends TransformToMaybeRefOrGetter<WebGLRen
   preset?: MaybeRefOrGetter<RendererPresetsType>
   renderMode?: MaybeRefOrGetter<'always' | 'on-demand' | 'manual'>
 }
-
 /**
  * Reactive three.js WebGLRenderer instance
  *
@@ -111,6 +110,7 @@ export function useRenderer(
     canvas,
     options,
     disableRender,
+    emit,
     contextParts: { sizes, camera, internal, invalidate },
   }:
   {
@@ -146,12 +146,22 @@ export function useRenderer(
   watch(webGLRendererConstructorParameters, () => {
     renderer.value.dispose()
     renderer.value = new WebGLRenderer(webGLRendererConstructorParameters.value)
+
+    if (options.renderMode === 'on-demand') {
+      invalidate()
+    }
   })
 
   watchEffect(() => {
     renderer.value.setSize(sizes.width.value, sizes.height.value)
   })
 
+  watch(() => options.clearColor, () => {
+    if (options.renderMode === 'on-demand') {
+      invalidate()
+    }
+  })
+
   const { pixelRatio } = useDevicePixelRatio()
 
   watchEffect(() => {
@@ -165,8 +175,10 @@ export function useRenderer(
   const { resume, onLoop } = useRenderLoop()
 
   onLoop(() => {
-    if (camera.value && !toValue(disableRender) && internal.frames.value > 0)
+    if (camera.value && !toValue(disableRender) && internal.frames.value > 0) {
       renderer.value.render(scene, camera.value)
+      emit('render', renderer.value)
+    }
 
     // Reset priority
     internal.priority.value = 0
@@ -201,6 +213,13 @@ export function useRenderer(
 
   const threeDefaults = getThreeRendererDefaults()
 
+  const renderMode = toValue(options.renderMode)
+
+  if (renderMode !== 'always') { 
+    // Invalidate for the first time
+    invalidate()
+  }
+
   watchEffect(() => {
     const rendererPreset = toValue(options.preset)
 
@@ -219,10 +238,6 @@ export function useRenderer(
       // If the render mode is 'always', ensure there's always a frame pending
       internal.frames.value = Math.max(1, internal.frames.value)
     }
-    else {
-      // Invalidate for the first time
-      invalidate()
-    }
 
     const getValue = <T>(option: MaybeRefOrGetter<T>, pathInThree: string): T | undefined => {
       const value = toValue(option)
diff --git a/src/composables/useTresContextProvider/index.ts b/src/composables/useTresContextProvider/index.ts
index 4a54d0a8b..cbb1b0962 100644
--- a/src/composables/useTresContextProvider/index.ts
+++ b/src/composables/useTresContextProvider/index.ts
@@ -52,12 +52,14 @@ export function useTresContextProvider({
   windowSize,
   disableRender,
   rendererOptions,
+  emit,
 }: {
   scene: Scene
   canvas: MaybeRef<HTMLCanvasElement>
   windowSize: MaybeRefOrGetter<boolean>
   disableRender: MaybeRefOrGetter<boolean>
   rendererOptions: UseRendererOptions
+  emit: (event: string, ...args: any[]) => void
 }): TresContext {
 
   const elementSize = computed(() =>
@@ -97,6 +99,7 @@ export function useTresContextProvider({
       scene,
       canvas,
       options: rendererOptions,
+      emit,
       contextParts: { sizes, camera, internal, invalidate },
       disableRender,
     })

From a0d534403975d287f49f0a39c44e9ada70513f99 Mon Sep 17 00:00:00 2001
From: alvarosabu <alvaro.saburido@gmail.com>
Date: Sat, 6 Jan 2024 10:37:51 +0100
Subject: [PATCH 06/15] chore: fix windowsize issue

---
 src/components/TresCanvas.vue | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/components/TresCanvas.vue b/src/components/TresCanvas.vue
index 132e94e34..4242c0c8c 100644
--- a/src/components/TresCanvas.vue
+++ b/src/components/TresCanvas.vue
@@ -132,7 +132,7 @@ onMounted(() => {
   context.value = useTresContextProvider({
     scene: scene.value,
     canvas: existingCanvas,
-    windowSize: props.windowSize ?? true,
+    windowSize: props.windowSize ?? false,
     disableRender: disableRender.value ?? false,
     rendererOptions: props,
     emit,

From ecec472edccbd5d0c05c9f1151bad4279524429c Mon Sep 17 00:00:00 2001
From: alvarosabu <alvaro.saburido@gmail.com>
Date: Sat, 6 Jan 2024 10:38:04 +0100
Subject: [PATCH 07/15] chore(lint): fix maximum line length issues

---
 docs/.vitepress/theme/components/BlenderCube.vue |  3 ++-
 docs/.vitepress/theme/components/GraphPane.vue   | 16 +++++++++++++++-
 2 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/docs/.vitepress/theme/components/BlenderCube.vue b/docs/.vitepress/theme/components/BlenderCube.vue
index c3fb58554..8ce1fd809 100644
--- a/docs/.vitepress/theme/components/BlenderCube.vue
+++ b/docs/.vitepress/theme/components/BlenderCube.vue
@@ -2,7 +2,8 @@
 import { useTresContext } from '@tresjs/core'
 import { useGLTF } from '@tresjs/cientos'
 
-const { nodes } = await useGLTF('https://raw.githubusercontent.com/Tresjs/assets/main/models/gltf/blender-cube.glb', { draco: true })
+const { nodes } = await useGLTF('https://raw.githubusercontent.com/Tresjs/assets/main/models/gltf/blender-cube.glb', 
+  { draco: true })
 const model = nodes.Cube
 
 model.position.set(0, 1, 0)
diff --git a/docs/.vitepress/theme/components/GraphPane.vue b/docs/.vitepress/theme/components/GraphPane.vue
index 9403f990b..410b927c8 100644
--- a/docs/.vitepress/theme/components/GraphPane.vue
+++ b/docs/.vitepress/theme/components/GraphPane.vue
@@ -42,7 +42,20 @@ useRafFn(({ timestamp }) => {
 
 <template>
   <div
-    class="absolute right-2 top-2 flex px-4 py-1 justify-between gap-4 items-center mb-2 z-10 bg-white shadow-xl
+    class="absolute
+      right-2
+      top-2
+      flex
+      px-4
+      py-1
+      justify-between
+      gap-4
+      items-center
+      mb-2
+      z-10
+      bg-white
+      dark:bg-dark
+      shadow-xl
       rounded 
       border-4 
       border-solid 
@@ -56,6 +69,7 @@ useRafFn(({ timestamp }) => {
     <div
       class="
         bg-gray-100
+        dark:bg-gray-600
         relative
         w-2/3
         p-1

From fccc50d99533d5e90a0c56e05c87c2b07309ee41 Mon Sep 17 00:00:00 2001
From: alvarosabu <alvaro.saburido@gmail.com>
Date: Sat, 6 Jan 2024 13:50:32 +0100
Subject: [PATCH 08/15] feat: invalidate on-demand on window resize

---
 src/composables/useRenderer/index.ts | 22 ++++++++++++----------
 1 file changed, 12 insertions(+), 10 deletions(-)

diff --git a/src/composables/useRenderer/index.ts b/src/composables/useRenderer/index.ts
index 38ac5b266..6428bdbb3 100644
--- a/src/composables/useRenderer/index.ts
+++ b/src/composables/useRenderer/index.ts
@@ -141,30 +141,32 @@ export function useRenderer(
 
   const renderer = shallowRef<WebGLRenderer>(new WebGLRenderer(webGLRendererConstructorParameters.value))
 
+  function invalidateOnDemand() {
+    if (options.renderMode === 'on-demand') {
+      invalidate()
+    }
+  }
   // since the properties set via the constructor can't be updated dynamically,
   // the renderer is recreated once they change
   watch(webGLRendererConstructorParameters, () => {
     renderer.value.dispose()
     renderer.value = new WebGLRenderer(webGLRendererConstructorParameters.value)
 
-    if (options.renderMode === 'on-demand') {
-      invalidate()
-    }
+    invalidateOnDemand()
   })
 
-  watchEffect(() => {
+  watch([sizes.width, sizes.height], () => {
     renderer.value.setSize(sizes.width.value, sizes.height.value)
+    invalidateOnDemand()
+  }, {
+    immediate: true,
   })
 
-  watch(() => options.clearColor, () => {
-    if (options.renderMode === 'on-demand') {
-      invalidate()
-    }
-  })
+  watch(() => options.clearColor, invalidateOnDemand)
 
   const { pixelRatio } = useDevicePixelRatio()
 
-  watchEffect(() => {
+  watch(pixelRatio, () => {
     renderer.value.setPixelRatio(pixelRatio.value)
   })
 

From 82e9264925bd8d30dbd47d7b57fb076ac9143ed2 Mon Sep 17 00:00:00 2001
From: alvarosabu <alvaro.saburido@gmail.com>
Date: Sun, 7 Jan 2024 11:45:22 +0100
Subject: [PATCH 09/15] feat: add advance method for manual mode

---
 src/composables/useRenderer/index.ts          | 11 +++++--
 .../useTresContextProvider/index.ts           | 33 +++++++++++++++----
 2 files changed, 34 insertions(+), 10 deletions(-)

diff --git a/src/composables/useRenderer/index.ts b/src/composables/useRenderer/index.ts
index 6428bdbb3..91db4aff3 100644
--- a/src/composables/useRenderer/index.ts
+++ b/src/composables/useRenderer/index.ts
@@ -111,13 +111,14 @@ export function useRenderer(
     options,
     disableRender,
     emit,
-    contextParts: { sizes, camera, internal, invalidate },
+    contextParts: { sizes, camera, internal, invalidate, advance },
   }:
   {
     canvas: MaybeRef<HTMLCanvasElement>
     scene: Scene
     options: UseRendererOptions
-    contextParts: Pick<TresContext, 'sizes' | 'camera'>
+    emit: (event: string, ...args: any[]) => void
+    contextParts: Pick<TresContext, 'sizes' | 'camera' | 'internal'> & { invalidate: () => void; advance: () => void }
     disableRender: MaybeRefOrGetter<boolean>
   },
 ) {
@@ -185,7 +186,11 @@ export function useRenderer(
     // Reset priority
     internal.priority.value = 0
 
-    internal.frames.value = Math.max(0, internal.frames.value - 1)
+    // If renderMode is not 'manual', auto-decrement frames
+    // If it is 'manual', frames will be managed by the advance function
+    if (renderMode !== 'manual') {
+      internal.frames.value = Math.max(0, internal.frames.value - 1)
+    }
 
     if (toValue(options.renderMode) === 'always') {
       internal.frames.value = 1
diff --git a/src/composables/useTresContextProvider/index.ts b/src/composables/useTresContextProvider/index.ts
index cbb1b0962..6a814410a 100644
--- a/src/composables/useTresContextProvider/index.ts
+++ b/src/composables/useTresContextProvider/index.ts
@@ -38,9 +38,21 @@ export interface TresContext {
   renderer: ShallowRef<WebGLRenderer>
   raycaster: ShallowRef<Raycaster>
   perf: PerformanceState
-  renderMode: MaybeRefOrGetter<'always' | 'on-demand' | 'manual'>
+  /**
+   * If set to 'on-demand', the scene will only be rendered when the current frame is invalidated
+   * If set to 'manual', the scene will only be rendered when advance() is called
+   * If set to 'always', the scene will be rendered every frame
+   */
+  renderMode: Ref<'always' | 'on-demand' | 'manual'>
   internal: InternalState
+  /**
+   * Invalidates the current frame when renderMode === 'on-demand'
+   */
   invalidate: () => void
+  /**
+   * Advance one frame when renderMode === 'manual'
+   */
+  advance: () => void
   registerCamera: (camera: Camera) => void
   setCameraActive: (cameraOrUuid: Camera | string) => void
   deregisterCamera: (camera: Camera) => void
@@ -94,21 +106,27 @@ export function useTresContextProvider({
     maxFrames: 60,
   }
 
+  function invalidate(frames = 1) {
+    // Increase the frame count, ensuring not to exceed a maximum if desired
+    internal.frames.value = Math.min(internal.maxFrames, internal.frames.value + frames)
+  }
+
+  function advance() {
+    if (rendererOptions.renderMode === 'manual') {
+      invalidate()
+    }
+  }
+
   const { renderer } = useRenderer(
     {
       scene,
       canvas,
       options: rendererOptions,
       emit,
-      contextParts: { sizes, camera, internal, invalidate },
+      contextParts: { sizes, camera, internal, invalidate, advance },
       disableRender,
     })
 
-  function invalidate(frames = 1) {
-    // Increase the frame count, ensuring not to exceed a maximum if desired
-    internal.frames.value = Math.min(internal.maxFrames, internal.frames.value + frames)
-  }
-
   const toProvide: TresContext = {
     sizes,
     scene: localScene,
@@ -131,6 +149,7 @@ export function useTresContextProvider({
     },
     renderMode: ref(rendererOptions.renderMode || 'always'),
     internal,
+    advance,
     extend,
     invalidate,
     registerCamera,

From 2ae56241d46e8958da2e67c9f4a7d732bb74a07e Mon Sep 17 00:00:00 2001
From: alvarosabu <alvaro.saburido@gmail.com>
Date: Sun, 7 Jan 2024 12:49:13 +0100
Subject: [PATCH 10/15] feat: fix manual first render with advance

---
 .../src/pages/rendering-modes/index.vue       |  2 +-
 .../src/pages/rendering-modes/scene.vue       | 11 +++++-----
 src/composables/useRenderer/index.ts          | 22 ++++++++++---------
 .../useTresContextProvider/index.ts           | 15 +++++++++++--
 4 files changed, 31 insertions(+), 19 deletions(-)

diff --git a/playground/src/pages/rendering-modes/index.vue b/playground/src/pages/rendering-modes/index.vue
index 014366a1a..7c4beb53e 100644
--- a/playground/src/pages/rendering-modes/index.vue
+++ b/playground/src/pages/rendering-modes/index.vue
@@ -13,7 +13,7 @@ setTimeout(() => {
 <template>
   <TresCanvas
     :clear-color="clearColor"
-    render-mode="on-demand"
+    render-mode="manual"
     @render="() => console.log('onRender')"
   >
     <Scene />
diff --git a/playground/src/pages/rendering-modes/scene.vue b/playground/src/pages/rendering-modes/scene.vue
index cd8fe5bb6..c076335c2 100644
--- a/playground/src/pages/rendering-modes/scene.vue
+++ b/playground/src/pages/rendering-modes/scene.vue
@@ -2,21 +2,20 @@
 import { useRenderLoop, useTres } from '@tresjs/core'
 import { OrbitControls } from '@tresjs/cientos'
 
-const { invalidate } = useTres()
+const { invalidate, advance } = useTres()
 
 function onControlChange() {
-  invalidate()
+  advance()
 }
 
 const positionX = ref(0)
 const showMesh = ref(true)
 
 setTimeout(() => {
-  /*  positionX.value = 1 */
-/*   showMesh.value = false */
-}, 3000)
+  positionX.value = 1
+  /*   showMesh.value = false */
 
-/* invalidate() */
+}, 3000)
 </script>
 
 <template>
diff --git a/src/composables/useRenderer/index.ts b/src/composables/useRenderer/index.ts
index 91db4aff3..6f44c8742 100644
--- a/src/composables/useRenderer/index.ts
+++ b/src/composables/useRenderer/index.ts
@@ -1,5 +1,5 @@
 import { Color, WebGLRenderer } from 'three'
-import { shallowRef, watchEffect, onUnmounted, type MaybeRef, computed, watch } from 'vue'
+import { shallowRef, watchEffect, onUnmounted, type MaybeRef, computed, watch, nextTick } from 'vue'
 import {
   toValue,
   unrefElement,
@@ -186,15 +186,12 @@ export function useRenderer(
     // Reset priority
     internal.priority.value = 0
 
-    // If renderMode is not 'manual', auto-decrement frames
-    // If it is 'manual', frames will be managed by the advance function
-    if (renderMode !== 'manual') {
-      internal.frames.value = Math.max(0, internal.frames.value - 1)
-    }
-
     if (toValue(options.renderMode) === 'always') {
       internal.frames.value = 1
     }
+    else {
+      internal.frames.value = Math.max(0, internal.frames.value - 1)
+    }
 
   })
 
@@ -222,11 +219,18 @@ export function useRenderer(
 
   const renderMode = toValue(options.renderMode)
 
-  if (renderMode !== 'always') { 
+  if (renderMode === 'on-demand') { 
     // Invalidate for the first time
     invalidate()
   }
 
+  if (renderMode === 'manual') {
+    // Advance for the first time, setTimeout to make sure there is something to render
+    setTimeout(() => {
+      advance()
+    }, 1)
+  }
+
   watchEffect(() => {
     const rendererPreset = toValue(options.preset)
 
@@ -239,8 +243,6 @@ export function useRenderer(
 
     // Render mode
 
-    const renderMode = toValue(options.renderMode)
-
     if (renderMode === 'always') {
       // If the render mode is 'always', ensure there's always a frame pending
       internal.frames.value = Math.max(1, internal.frames.value)
diff --git a/src/composables/useTresContextProvider/index.ts b/src/composables/useTresContextProvider/index.ts
index 6a814410a..cd5d299de 100644
--- a/src/composables/useTresContextProvider/index.ts
+++ b/src/composables/useTresContextProvider/index.ts
@@ -8,6 +8,7 @@ import { useCamera } from '../useCamera'
 import type { UseRendererOptions } from '../useRenderer'
 import { useRenderer } from '../useRenderer'
 import { extend } from '../../core/catalogue'
+import { useLogger } from '../useLogger'
 
 export interface InternalState {
   priority: Ref<number>
@@ -74,6 +75,8 @@ export function useTresContextProvider({
   emit: (event: string, ...args: any[]) => void
 }): TresContext {
 
+  const { logWarning } = useLogger()
+
   const elementSize = computed(() =>
     toValue(windowSize)
       ? useWindowSize()
@@ -108,12 +111,20 @@ export function useTresContextProvider({
 
   function invalidate(frames = 1) {
     // Increase the frame count, ensuring not to exceed a maximum if desired
-    internal.frames.value = Math.min(internal.maxFrames, internal.frames.value + frames)
+    if (rendererOptions.renderMode === 'on-demand') {
+      internal.frames.value = Math.min(internal.maxFrames, internal.frames.value + frames)
+    }
+    else {
+      logWarning('`invalidate` can only be used when `renderMode` is set to `on-demand`')
+    }
   }
 
   function advance() {
     if (rendererOptions.renderMode === 'manual') {
-      invalidate()
+      internal.frames.value = 1
+    }
+    else {
+      logWarning('`advance` can only be used when `renderMode` is set to `manual`')
     }
   }
 

From 42cefab1ba4a986cc0094f96987379348fffb067 Mon Sep 17 00:00:00 2001
From: alvarosabu <alvaro.saburido@gmail.com>
Date: Sun, 7 Jan 2024 12:49:28 +0100
Subject: [PATCH 11/15] docs: performance manual mode

---
 docs/advanced/performance.md | 97 ++++++++++++++++++++++++++++++++++++
 docs/api/composables.md      |  3 ++
 2 files changed, 100 insertions(+)

diff --git a/docs/advanced/performance.md b/docs/advanced/performance.md
index f82306243..89793e0bf 100644
--- a/docs/advanced/performance.md
+++ b/docs/advanced/performance.md
@@ -30,5 +30,102 @@ You can do that by setting the `renderMode` prop to `on-demand` or `manual`:
 </TresCanvas>
 ```
 
+#### Automatic Invalidation
 
+When using `render-mode="on-demand"`, Tres.js will automatically invalidate the current frame by observing component props and lyfecycle hooks like `onMounted` and `onUnmounted`. It will also invalidate the frame when resizing the window or change any prop from the `<TresCanvas>` component like `clearColor` or `antialias`.
+
+This will trigger a new render: 
+
+```vue
+<script setup>
+import { ref } from 'vue'
+
+const positionX = ref(0)
+
+setTimeout(() => {
+  positionX.value = 1
+}, 1000)
+</script>
+
+<template>
+  <TresCanvas render-mode="on-demand">
+    <TresMesh :position-x="positionX">
+      <TresBoxGeometry />
+      <TresMeshBasicMaterial color="teal" />
+    </TresMesh>
+  </TresCanvas>
+</template>
+```
+
+#### Manual Invalidation
+
+Since is not really possible to observe all the possible changes in your application, you can also manually invalidate the frame by calling the `invalidate()` method from the [`useTresContext` composable](../api/composables.md#usetrescontext):
+
+
+::: code-group
+
+```vue [App.vue]
+<script setup>
+import { TresCanvas } from '@tresjs/core'
+import Scene from './Scene.vue'
+</script>
+
+<template>
+  <TresCanvas
+    render-mode="manual"
+  >
+    <Scene />
+  </TresCanvas>
+</template>
+```
+
+```vue [Scene.vue]
+<script setup>
+import { useTres } from '@tresjs/core'
+
+const boxRef = ref()
+const { invalidate } = useTres()
+
+watch(boxRef.value, () => {
+  boxRef.value.position.x = 1
+  invalidate()
+})
+</script>
+
+<template>
+  <TresMesh ref="boxRef">
+    <TresBoxGeometry />
+    <TresMeshBasicMaterial color="teal" />
+  </TresMesh>
+</template>
+```
+
+:::
+
+### Mode `always` 
+
+In this rendering mode, Tres will continously render the scene on every frame. This is the default mode and the easiest to use, but it's also the most resource expensive one.
+
+
+### Mode `manual`
+
+If you want to have full control of when the scene is rendered, you can set the `render-mode` prop to `manual`:
+
+```vue
+<TresCanvas render-mode="manual">
+  <!-- Your scene goes here -->
+</TresCanvas>
+```
+
+In this mode, Tres will not render the scene automatically. You will need to call the `advance()` method from the [`useTresContext` composable](../api/composables.md#usetrescontext) to render the scene:
+
+```vue
+<script setup>
+import { useTres } from '@tresjs/core'
+
+const { advance } = useTres()
+
+advance()
+</script>
+```
 
diff --git a/docs/api/composables.md b/docs/api/composables.md
index 1f4bdd605..1bc0df8b2 100644
--- a/docs/api/composables.md
+++ b/docs/api/composables.md
@@ -233,4 +233,7 @@ const context = useTresContext()
 | **scene** | the [scene](https://threejs.org/docs/?q=sce#api/en/scenes/Scene). |
 | **setCameraActive** | a method to set a camera active |
 | **sizes** | contains width, height and aspect ratio of your canvas |
+| **invalidate** | a method to invalidate the render loop. This is only required if you set the `render-mode` prop to `on-demand`. |
+| **advance** | a method to advance the render loop. This is only required if you set the `render-mode` prop to `manual`. |
+
 

From 331ee15d1fe8eab87473a3b7ad86f64b951c01a6 Mon Sep 17 00:00:00 2001
From: alvarosabu <alvaro.saburido@gmail.com>
Date: Sun, 7 Jan 2024 12:57:19 +0100
Subject: [PATCH 12/15] docs: add badge with version

---
 docs/advanced/performance.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/advanced/performance.md b/docs/advanced/performance.md
index 89793e0bf..04e783ab0 100644
--- a/docs/advanced/performance.md
+++ b/docs/advanced/performance.md
@@ -4,7 +4,7 @@
 
 We are running WebGL on the browser, which can be quite expensive and it will depend on how powerful the user's device is. To make 3D accessible to everyone, we need to make sure our applications are optimized to run also on low-end devices. This guide will provide some tips to improve the performance of your Tres.js application.
 
-## On-demand rendering
+## On-demand rendering <Badge type="tip" text="^4.0.0" />
 
 By default, Tres.js will render your scene on every frame. This is great for most applications, but if you are building a game or a complex application, you might want to control when the scene is rendered. 
 

From f196a38f378dcc9abf12adf2cf26e6edbc5a855f Mon Sep 17 00:00:00 2001
From: alvarosabu <alvaro.saburido@gmail.com>
Date: Mon, 22 Jan 2024 10:03:30 +0100
Subject: [PATCH 13/15] chore: correct typos and PR suggestions

---
 docs/advanced/performance.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/advanced/performance.md b/docs/advanced/performance.md
index 04e783ab0..6e406eea2 100644
--- a/docs/advanced/performance.md
+++ b/docs/advanced/performance.md
@@ -32,9 +32,9 @@ You can do that by setting the `renderMode` prop to `on-demand` or `manual`:
 
 #### Automatic Invalidation
 
-When using `render-mode="on-demand"`, Tres.js will automatically invalidate the current frame by observing component props and lyfecycle hooks like `onMounted` and `onUnmounted`. It will also invalidate the frame when resizing the window or change any prop from the `<TresCanvas>` component like `clearColor` or `antialias`.
+When using `render-mode="on-demand"`, Tres.js will automatically invalidate the current frame by observing component props and lifecycle hooks like `onMounted` and `onUnmounted`. It will also invalidate the frame when resizing the window or changing any prop from the `<TresCanvas>` component like `clearColor` or `antialias`.
 
-This will trigger a new render: 
+The code below updates TresMesh's position-x prop every second, triggering a new render.
 
 ```vue
 <script setup>
@@ -59,7 +59,7 @@ setTimeout(() => {
 
 #### Manual Invalidation
 
-Since is not really possible to observe all the possible changes in your application, you can also manually invalidate the frame by calling the `invalidate()` method from the [`useTresContext` composable](../api/composables.md#usetrescontext):
+Since it is not really possible to observe all the possible changes in your application, you can also manually invalidate the frame by calling the `invalidate()` method from the [`useTresContext` composable](../api/composables.md#usetrescontext):
 
 
 ::: code-group

From 64268560892637a44b36609ea1ec3931c5ec1b75 Mon Sep 17 00:00:00 2001
From: alvarosabu <alvaro.saburido@gmail.com>
Date: Mon, 22 Jan 2024 10:11:43 +0100
Subject: [PATCH 14/15] chore: tell dont ask fix

---
 playground/src/pages/rendering-modes/index.vue  | 2 +-
 playground/src/pages/rendering-modes/scene.vue  | 2 +-
 src/composables/useTresContextProvider/index.ts | 6 +++++-
 src/core/nodeOps.ts                             | 2 +-
 4 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/playground/src/pages/rendering-modes/index.vue b/playground/src/pages/rendering-modes/index.vue
index 7c4beb53e..014366a1a 100644
--- a/playground/src/pages/rendering-modes/index.vue
+++ b/playground/src/pages/rendering-modes/index.vue
@@ -13,7 +13,7 @@ setTimeout(() => {
 <template>
   <TresCanvas
     :clear-color="clearColor"
-    render-mode="manual"
+    render-mode="on-demand"
     @render="() => console.log('onRender')"
   >
     <Scene />
diff --git a/playground/src/pages/rendering-modes/scene.vue b/playground/src/pages/rendering-modes/scene.vue
index c076335c2..c44e5d194 100644
--- a/playground/src/pages/rendering-modes/scene.vue
+++ b/playground/src/pages/rendering-modes/scene.vue
@@ -5,7 +5,7 @@ import { OrbitControls } from '@tresjs/cientos'
 const { invalidate, advance } = useTres()
 
 function onControlChange() {
-  advance()
+  invalidate()
 }
 
 const positionX = ref(0)
diff --git a/src/composables/useTresContextProvider/index.ts b/src/composables/useTresContextProvider/index.ts
index 7828f9bf6..935ba527d 100644
--- a/src/composables/useTresContextProvider/index.ts
+++ b/src/composables/useTresContextProvider/index.ts
@@ -45,6 +45,7 @@ export interface TresContext {
    * If set to 'always', the scene will be rendered every frame
    */
   renderMode: Ref<'always' | 'on-demand' | 'manual'>
+  canBeInvalidated: ComputedRef<boolean>
   internal: InternalState
   /**
    * Invalidates the current frame when renderMode === 'on-demand'
@@ -147,6 +148,8 @@ export function useTresContextProvider({
       disableRender,
     })
 
+  const renderMode = ref<'always' | 'on-demand' | 'manual'>(rendererOptions.renderMode || 'always')
+
   const toProvide: TresContext = {
     sizes,
     scene: localScene,
@@ -167,7 +170,8 @@ export function useTresContextProvider({
         accumulator: [],
       },
     },
-    renderMode: ref(rendererOptions.renderMode || 'always'),
+    renderMode,
+    canBeInvalidated: computed(() => renderMode.value === 'on-demand' && internal.frames.value === 0),
     internal,
     advance,
     extend,
diff --git a/src/core/nodeOps.ts b/src/core/nodeOps.ts
index 814d80574..8301306b0 100644
--- a/src/core/nodeOps.ts
+++ b/src/core/nodeOps.ts
@@ -28,7 +28,7 @@ export function invalidateInstance(instance: TresObject) {
   
   if (!ctx) return
   
-  if (ctx.renderMode.value === 'on-demand' && ctx.internal.frames.value === 0) {
+  if (ctx.canBeInvalidated.value) {
     ctx.invalidate()
   }
 

From 8b648a7198f8f74272fea10ef212aff395e59fc0 Mon Sep 17 00:00:00 2001
From: alvarosabu <alvaro.saburido@gmail.com>
Date: Mon, 22 Jan 2024 16:29:44 +0100
Subject: [PATCH 15/15] feat: render state instead of internal

---
 src/composables/useRenderer/index.ts          | 14 ++--
 .../useTresContextProvider/index.ts           | 78 ++++++++++---------
 src/core/nodeOps.ts                           |  2 +-
 3 files changed, 50 insertions(+), 44 deletions(-)

diff --git a/src/composables/useRenderer/index.ts b/src/composables/useRenderer/index.ts
index 6f44c8742..93242a0f0 100644
--- a/src/composables/useRenderer/index.ts
+++ b/src/composables/useRenderer/index.ts
@@ -111,14 +111,14 @@ export function useRenderer(
     options,
     disableRender,
     emit,
-    contextParts: { sizes, camera, internal, invalidate, advance },
+    contextParts: { sizes, camera, render, invalidate, advance },
   }:
   {
     canvas: MaybeRef<HTMLCanvasElement>
     scene: Scene
     options: UseRendererOptions
     emit: (event: string, ...args: any[]) => void
-    contextParts: Pick<TresContext, 'sizes' | 'camera' | 'internal'> & { invalidate: () => void; advance: () => void }
+    contextParts: Pick<TresContext, 'sizes' | 'camera' | 'render'> & { invalidate: () => void; advance: () => void }
     disableRender: MaybeRefOrGetter<boolean>
   },
 ) {
@@ -178,19 +178,19 @@ export function useRenderer(
   const { resume, onLoop } = useRenderLoop()
 
   onLoop(() => {
-    if (camera.value && !toValue(disableRender) && internal.frames.value > 0) {
+    if (camera.value && !toValue(disableRender) && render.frames.value > 0) {
       renderer.value.render(scene, camera.value)
       emit('render', renderer.value)
     }
 
     // Reset priority
-    internal.priority.value = 0
+    render.priority.value = 0
 
     if (toValue(options.renderMode) === 'always') {
-      internal.frames.value = 1
+      render.frames.value = 1
     }
     else {
-      internal.frames.value = Math.max(0, internal.frames.value - 1)
+      render.frames.value = Math.max(0, render.frames.value - 1)
     }
 
   })
@@ -245,7 +245,7 @@ export function useRenderer(
 
     if (renderMode === 'always') {
       // If the render mode is 'always', ensure there's always a frame pending
-      internal.frames.value = Math.max(1, internal.frames.value)
+      render.frames.value = Math.max(1, render.frames.value)
     }
 
     const getValue = <T>(option: MaybeRefOrGetter<T>, pathInThree: string): T | undefined => {
diff --git a/src/composables/useTresContextProvider/index.ts b/src/composables/useTresContextProvider/index.ts
index 935ba527d..1052f4735 100644
--- a/src/composables/useTresContextProvider/index.ts
+++ b/src/composables/useTresContextProvider/index.ts
@@ -16,6 +16,19 @@ export interface InternalState {
   maxFrames: number
 }
 
+export interface RenderState {
+  /**
+   * If set to 'on-demand', the scene will only be rendered when the current frame is invalidated
+   * If set to 'manual', the scene will only be rendered when advance() is called
+   * If set to 'always', the scene will be rendered every frame
+   */
+  mode: Ref<'always' | 'on-demand' | 'manual'>
+  priority: Ref<number>
+  frames: Ref<number>
+  maxFrames: number
+  canBeInvalidated: ComputedRef<boolean>
+}
+
 export interface PerformanceState {
   maxFrames: number
   fps: {
@@ -39,21 +52,14 @@ export interface TresContext {
   renderer: ShallowRef<WebGLRenderer>
   raycaster: ShallowRef<Raycaster>
   perf: PerformanceState
-  /**
-   * If set to 'on-demand', the scene will only be rendered when the current frame is invalidated
-   * If set to 'manual', the scene will only be rendered when advance() is called
-   * If set to 'always', the scene will be rendered every frame
-   */
-  renderMode: Ref<'always' | 'on-demand' | 'manual'>
-  canBeInvalidated: ComputedRef<boolean>
-  internal: InternalState
+  render: RenderState
   /**
    * Invalidates the current frame when renderMode === 'on-demand'
    */
   invalidate: () => void
   /**
-   * Advance one frame when renderMode === 'manual'
-   */
+     * Advance one frame when renderMode === 'manual'
+     */
   advance: () => void
   registerCamera: (camera: Camera) => void
   setCameraActive: (cameraOrUuid: Camera | string) => void
@@ -112,17 +118,20 @@ export function useTresContextProvider({
     setCameraActive,
   } = useCamera({ sizes, scene })
 
-  // Initialize internal state
-  const internal: InternalState = {
+  // Render state
+
+  const render: RenderState = {
+    mode: ref<'always' | 'on-demand' | 'manual'>(rendererOptions.renderMode || 'always'),
     priority: ref(0),
     frames: ref(0),
     maxFrames: 60,
+    canBeInvalidated: computed(() => render.mode.value === 'on-demand' && render.frames.value === 0),
   }
 
   function invalidate(frames = 1) {
     // Increase the frame count, ensuring not to exceed a maximum if desired
     if (rendererOptions.renderMode === 'on-demand') {
-      internal.frames.value = Math.min(internal.maxFrames, internal.frames.value + frames)
+      render.frames.value = Math.min(render.maxFrames, render.frames.value + frames)
     }
     else {
       logWarning('`invalidate` can only be used when `renderMode` is set to `on-demand`')
@@ -131,7 +140,7 @@ export function useTresContextProvider({
 
   function advance() {
     if (rendererOptions.renderMode === 'manual') {
-      internal.frames.value = 1
+      render.frames.value = 1
     }
     else {
       logWarning('`advance` can only be used when `renderMode` is set to `manual`')
@@ -144,13 +153,12 @@ export function useTresContextProvider({
       canvas,
       options: rendererOptions,
       emit,
-      contextParts: { sizes, camera, internal, invalidate, advance },
+      // TODO: replace contextParts with full ctx at https://github.com/Tresjs/tres/issues/516
+      contextParts: { sizes, camera, render, invalidate, advance },
       disableRender,
     })
 
-  const renderMode = ref<'always' | 'on-demand' | 'manual'>(rendererOptions.renderMode || 'always')
-
-  const toProvide: TresContext = {
+  const ctx: TresContext = {
     sizes,
     scene: localScene,
     camera,
@@ -170,9 +178,7 @@ export function useTresContextProvider({
         accumulator: [],
       },
     },
-    renderMode,
-    canBeInvalidated: computed(() => renderMode.value === 'on-demand' && internal.frames.value === 0),
-    internal,
+    render,
     advance,
     extend,
     invalidate,
@@ -181,10 +187,10 @@ export function useTresContextProvider({
     deregisterCamera,
   }
 
-  provide('useTres', toProvide)
+  provide('useTres', ctx)
 
   // Add context to scene.userData
-  toProvide.scene.value.userData.tres__context = toProvide
+  ctx.scene.value.userData.tres__context = ctx
 
   // Performance
   const updateInterval = 100 // Update interval in milliseconds
@@ -197,8 +203,8 @@ export function useTresContextProvider({
 
     // Update WebGL Memory Usage (Placeholder for actual logic)
     // perf.memory.value = calculateMemoryUsage(gl)
-    if (toProvide.scene.value) {
-      toProvide.perf.memory.allocatedMem = calculateMemoryUsage(toProvide.scene.value as unknown as TresObject)
+    if (ctx.scene.value) {
+      ctx.perf.memory.allocatedMem = calculateMemoryUsage(ctx.scene.value as unknown as TresObject)
     }
 
     // Update memory usage
@@ -206,24 +212,24 @@ export function useTresContextProvider({
       lastUpdateTime = timestamp
 
       // Update FPS
-      toProvide.perf.fps.accumulator.push(fps.value as never)
+      ctx.perf.fps.accumulator.push(fps.value as never)
 
-      if (toProvide.perf.fps.accumulator.length > maxFrames) {
-        toProvide.perf.fps.accumulator.shift()
+      if (ctx.perf.fps.accumulator.length > maxFrames) {
+        ctx.perf.fps.accumulator.shift()
       }
 
-      toProvide.perf.fps.value = fps.value
+      ctx.perf.fps.value = fps.value
 
       // Update memory
       if (isSupported.value && memory.value) {
-        toProvide.perf.memory.accumulator.push(memory.value.usedJSHeapSize / 1024 / 1024 as never)
+        ctx.perf.memory.accumulator.push(memory.value.usedJSHeapSize / 1024 / 1024 as never)
 
-        if (toProvide.perf.memory.accumulator.length > maxFrames) {
-          toProvide.perf.memory.accumulator.shift()
+        if (ctx.perf.memory.accumulator.length > maxFrames) {
+          ctx.perf.memory.accumulator.shift()
         }
 
-        toProvide.perf.memory.currentMem
-        = toProvide.perf.memory.accumulator.reduce((a, b) => a + b, 0) / toProvide.perf.memory.accumulator.length
+        ctx.perf.memory.currentMem
+        = ctx.perf.memory.accumulator.reduce((a, b) => a + b, 0) / ctx.perf.memory.accumulator.length
 
       }
     }
@@ -243,7 +249,7 @@ export function useTresContextProvider({
 
     // Check if the accumulated time is greater than or equal to the interval
     if (accumulatedTime >= interval) {
-      window.__TRES__DEVTOOLS__.cb(toProvide)
+      window.__TRES__DEVTOOLS__.cb(ctx)
 
       // Reset the accumulated time
       accumulatedTime = 0
@@ -255,7 +261,7 @@ export function useTresContextProvider({
     pause()
   })
 
-  return toProvide
+  return ctx
 }
 
 export function useTresContext(): TresContext {
diff --git a/src/core/nodeOps.ts b/src/core/nodeOps.ts
index 8301306b0..e5e671331 100644
--- a/src/core/nodeOps.ts
+++ b/src/core/nodeOps.ts
@@ -28,7 +28,7 @@ export function invalidateInstance(instance: TresObject) {
   
   if (!ctx) return
   
-  if (ctx.canBeInvalidated.value) {
+  if (ctx.render && ctx.render.canBeInvalidated.value) {
     ctx.invalidate()
   }