Merge branch 'main' into bugfix/use-loader-types

docs/.vitepress/theme/components/LocalOrbitControls.vue

@@ -1,7 +1,7 @@
 <script lang="ts" setup>
 import type { Camera } from 'three'
 import { OrbitControls } from 'three-stdlib'
-import { onMounted, onUnmounted, ref, unref } from 'vue'
+import { onMounted, onUnmounted, shallowRef, unref } from 'vue'
 import type { TresVector3 } from '@tresjs/core'
 import { extend, useRenderLoop, useTresContext } from '@tresjs/core'
 import { useEventListener } from '@vueuse/core'
@@ -257,7 +257,7 @@ const emit = defineEmits(['change', 'start', 'end'])
 
 const { renderer, camera: activeCamera } = useTresContext()
 
-const controls = ref<OrbitControls | null>(null)
+const controls = shallowRef<OrbitControls | null>(null)
 
 extend({ OrbitControls })
 

docs/.vitepress/theme/components/LoveVueThreeJS.vue

@@ -1,14 +1,14 @@
 <script setup lang="ts">
 /// <reference types="vite-svg-loader" />
 import { gsap } from 'gsap'
-import { onMounted, ref } from 'vue'
+import { onMounted, shallowRef } from 'vue'
 import Triangle from '../assets/triangle.svg'
 import SecondRow from '../assets/second-row.svg'
 import ThirdRow from '../assets/third-row.svg'
 
-const triangleRef = ref()
-const secondRowRef = ref()
-const thirdRowRef = ref()
+const triangleRef = shallowRef()
+const secondRowRef = shallowRef()
+const thirdRowRef = shallowRef()
 
 const tl2r = gsap.timeline()
 const tl3r = gsap.timeline()

docs/advanced/caveats.md

@@ -14,11 +14,11 @@ Hot module replacement (HMR) is a feature that allows you to update your code wi
 
 Why? Because Tres builds the scene in a declarative way. This means that it creates the instance and add it to the scene when the component is mounted. The complexity comes to know when to remove the instance from the scene and when to add it again.
 
-Although a minimal disposal workflow is implemented, it is not perfect. This means that sometimes you will have to reload the page to see the changes correctly, specially when you are referencing an instances using [Template Refs](https://v3.vuejs.org/guide/component-template-refs.html)
+Although a minimal disposal workflow is implemented, it is not perfect. This means that sometimes you will have to reload the page to see the changes correctly, especially when you are referencing an instances using [Template Refs](https://v3.vuejs.org/guide/component-template-refs.html)
 
 ```vue
 <script setup lang="ts">
-const boxRef: Ref<TresInstance | null> = ref(null)
+const boxRef: ShallowRef<TresInstance | null> = shallowRef(null)
 
 onLoop(({ _delta, elapsed }) => {
   if (boxRef.value) {

docs/advanced/performance.md

@@ -78,13 +78,16 @@ import Scene from './Scene.vue'
 
 ```vue [Scene.vue]
 <script setup>
+import { shallowRef, watch } from 'vue'
 import { useTres } from '@tresjs/core'
 
-const boxRef = ref()
+const boxRef = shallowRef(null)
 const { invalidate } = useTres()
 
-watch(boxRef.value, () => {
-  boxRef.value.position.x = 1
+watch(boxRef, () => {
+  if (boxRef.value?.position) {
+    boxRef.value.position.x = 1
+  }
   invalidate()
 })
 </script>

docs/api/composables.md

@@ -91,9 +91,10 @@ import AnimatedBox from './AnimatedBox.vue'
 
 ```vue [AnimatedBox.vue]
 <script setup>
+import { shallowRef } from 'vue'
 import { useLoop } from '@tresjs/core'
 
-const boxRef = ref()
+const boxRef = shallowRef()
 
 const { onBeforeRender } = useLoop()
 
@@ -313,7 +314,7 @@ The seek function accepts three parameters:
 The `seek` and `seekByName` function traverses the object and returns the child object with the specified property and value. If no child with the given property and value is found, it returns null and logs a warning.
 
 ```ts
-const carRef = ref(null)
+const carRef = shallowRef(null)
 
 watch(carRef, ({ model }) => {
   if (model) {
@@ -328,7 +329,7 @@ watch(carRef, ({ model }) => {
 Similarly, the `seekAll` and `seekAllByName` functions return an array of child objects whose property includes the given value. If no matches are found, then they return an empty array and a warning is logged.
 
 ```ts
-const character = ref(null)
+const character = shallowRef(null)
 
 watch(character, ({ model }) => {
   if (model) {

docs/blog/announcing-v-3-1-0.md

@@ -56,7 +56,7 @@ Another important caveheat of Tres was that it was not possible to reactively ch
 const color = ref('#ffffff')
 const intensity = ref(1)
 
-const lightRef = ref<THREE.DirectionalLight>()
+const lightRef = shallowRef<THREE.DirectionalLight>()
 
 watch([color, intensity], ([color, intensity]) => {
     // this will not work

docs/cookbook/basic-animations.md

@@ -39,9 +39,9 @@ To animate the cube, we need to get a reference to it. We can do it by passing a
 
 ```vue [Scene.vue]
 <script setup>
-import { ref } from 'vue'
+import { shallowRef } from 'vue'
 
-const boxRef = ref()
+const boxRef = shallowRef()
 </script>
 
 <template>

docs/cookbook/groups.md

@@ -14,7 +14,7 @@ A `<TresGroup>` is an instance of the [THREE.Group](https://threejs.org/docs/#ap
 
 ```vue{13,22}
 <script setup lang="ts">
-const groupRef = ref()
+const groupRef = shallowRef()
 const { onLoop } = useRenderLoop()
 
 onLoop(() => {