Merge branch 'master' into fix/2514-update-types-three-webglprogram

creativoma · web-flow · commit 83d632ab9b28 · 2025-12-03T09:58:47.000+01:00
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -22,6 +22,15 @@ jobs:
       credentials:
         username: ${{ github.actor }}
         password: ${{ secrets.GITHUB_TOKEN }}
+
+    # 0.159.0 is mandatory; others are informational
+    strategy:
+      fail-fast: false
+      matrix:
+        three-version: ['0.159.0', '0.180.0', 'latest']
+    continue-on-error: ${{ matrix.three-version != '0.159.0' }}
+    name: test (w/ three@${{ matrix['three-version'] }})
+
     steps:
       - uses: actions/checkout@v4
       - run: corepack enable
@@ -30,7 +39,19 @@ jobs:
           cache: 'yarn'
       - run: yarn install
       - run: yarn build
-      - run: yarn test
+      - run: yarn eslint:ci
+      - run: yarn typecheck
+      - run: yarn prettier
+      - run: (cd test/e2e; ./e2e.sh ${{ matrix.three-version }})
+      - name: Upload Playwright screenshots
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-screenshots-${{ matrix.three-version }}
+          path: |
+            test-results/**
+          if-no-files-found: ignore
+          retention-days: 7
 
   build-and-release:
     needs: test
diff --git a/docs/abstractions/positional-audio.mdx b/docs/abstractions/positional-audio.mdx
@@ -9,7 +9,8 @@ sourcecode: src/core/PositionalAudio.tsx
   </li>
 </Grid>
 
-[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.vercel.app/?path=/story/abstractions-positionalaudio--positional-audio-scene-st) ![](https://img.shields.io/badge/-suspense-brightgreen)
+[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.vercel.app/?path=/story/abstractions-positionalaudio--positional-audio-scene-st)
+[![](https://img.shields.io/badge/-suspense-brightgreen)](https://r3f.docs.pmnd.rs/api/hooks#useloader)
 
 A wrapper around [THREE.PositionalAudio](https://threejs.org/docs/#api/en/audio/PositionalAudio). Add this to groups or meshes to tie them to a sound that plays when the camera comes near.
 
diff --git a/docs/abstractions/splat.mdx b/docs/abstractions/splat.mdx
@@ -3,6 +3,8 @@ title: Splat
 sourcecode: src/core/Splat.tsx
 ---
 
+[![](https://img.shields.io/badge/-suspense-brightgreen)](https://r3f.docs.pmnd.rs/api/hooks#useloader)
+
 <Grid cols={4}>
   <li>
     <Codesandbox id="qp4jmf" />
diff --git a/docs/abstractions/svg.mdx b/docs/abstractions/svg.mdx
@@ -4,6 +4,7 @@ sourcecode: src/core/Svg.tsx
 ---
 
 [![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.pmnd.rs/?path=/story/abstractions-svg--svg-st)
+[![](https://img.shields.io/badge/-suspense-brightgreen)](https://r3f.docs.pmnd.rs/api/hooks#useloader)
 
 Wrapper around the `three` [svg loader](https://threejs.org/examples/?q=sv#webgl_loader_svg) demo.
 
diff --git a/docs/abstractions/text.mdx b/docs/abstractions/text.mdx
@@ -3,7 +3,8 @@ title: Text
 sourcecode: src/core/Text.tsx
 ---
 
-[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.vercel.app/?path=/story/abstractions-text--text-st) ![](https://img.shields.io/badge/-suspense-brightgreen)
+[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.vercel.app/?path=/story/abstractions-text--text-st)
+[![](https://img.shields.io/badge/-suspense-brightgreen)](https://r3f.docs.pmnd.rs/api/hooks#useloader)
 
 <Grid cols={4}>
   <li>
diff --git a/docs/abstractions/text3d.mdx b/docs/abstractions/text3d.mdx
@@ -3,7 +3,8 @@ title: Text3D
 sourcecode: src/core/Text3D.tsx
 ---
 
-[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.vercel.app/?path=/story/abstractions-text3d--text-3-d-st) ![](https://img.shields.io/badge/-suspense-brightgreen)
+[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.vercel.app/?path=/story/abstractions-text3d--text-3-d-st)
+[![](https://img.shields.io/badge/-suspense-brightgreen)](https://r3f.docs.pmnd.rs/api/hooks#useloader)
 
 <Grid cols={4}>
   <li>
diff --git a/docs/gizmos/grid.mdx b/docs/gizmos/grid.mdx
@@ -3,7 +3,7 @@ title: Grid
 sourcecode: src/core/Grid.tsx
 ---
 
-[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.vercel.app/?path=/story/gizmos-grid--use-grid-scene-st)
+[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.pmnd.rs/?path=/docs/gizmos-grid--docs)
 
 <Grid cols={4}>
   <li>
diff --git a/docs/gizmos/pivot-controls.mdx b/docs/gizmos/pivot-controls.mdx
@@ -59,6 +59,8 @@ type PivotControlsProps = {
   onDragEnd?: () => void
   /** Set this to false if you want the gizmo to be visible through faces */
   depthTest?: boolean
+  /** Render order of pivot control - default is 500 */
+  renderOrder?: number
   opacity?: number
   visible?: boolean
   userData?: { [key: string]: any }
diff --git a/docs/loaders/cube-texture-use-cube-texture.mdx b/docs/loaders/cube-texture-use-cube-texture.mdx
@@ -4,6 +4,7 @@ sourcecode: src/core/CubeTexture.tsx
 ---
 
 [![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.pmnd.rs/?path=/story/abstractions-cubetexture)
+[![](https://img.shields.io/badge/-suspense-brightgreen)](https://r3f.docs.pmnd.rs/api/hooks#useloader)
 
 A convenience hook that uses `useLoader` and `CubeTextureLoader`
 
diff --git a/docs/loaders/fbx-use-fbx.mdx b/docs/loaders/fbx-use-fbx.mdx
@@ -4,6 +4,7 @@ sourcecode: src/core/Fbx.tsx
 ---
 
 [![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.pmnd.rs/?path=/story/loaders-fbx)
+[![](https://img.shields.io/badge/-suspense-brightgreen)](https://r3f.docs.pmnd.rs/api/hooks#useloader)
 
 A convenience hook that uses `useLoader` and `FBXLoader`:
 
diff --git a/docs/loaders/gltf-use-gltf.mdx b/docs/loaders/gltf-use-gltf.mdx
@@ -4,6 +4,7 @@ sourcecode: src/core/Gltf.tsx
 ---
 
 [![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.pmnd.rs/?path=/story/loaders-gltf)
+[![](https://img.shields.io/badge/-suspense-brightgreen)](https://r3f.docs.pmnd.rs/api/hooks#useloader)
 
 <Grid cols={4}>
   <li>
diff --git a/docs/loaders/ktx2-use-ktx2.mdx b/docs/loaders/ktx2-use-ktx2.mdx
@@ -4,6 +4,7 @@ sourcecode: src/core/Ktx2.tsx
 ---
 
 [![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.pmnd.rs/?path=/story/loaders-ktx2)
+[![](https://img.shields.io/badge/-suspense-brightgreen)](https://r3f.docs.pmnd.rs/api/hooks#useloader)
 
 A convenience hook that uses `useLoader` and `KTX2Loader`
 
diff --git a/docs/loaders/screen-video-texture.mdx b/docs/loaders/screen-video-texture.mdx
@@ -3,7 +3,8 @@ title: ScreenVideoTexture
 sourcecode: src/web/ScreenVideoTexture.tsx
 ---
 
-[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.pmnd.rs/?path=/story/misc-screenvideotexture) ![](https://img.shields.io/badge/-suspense-brightgreen)
+[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.pmnd.rs/?path=/story/misc-screenvideotexture)
+[![](https://img.shields.io/badge/-suspense-brightgreen)](https://r3f.docs.pmnd.rs/api/hooks#useloader)
 
 <Intro>Create a video texture from [`getDisplayMedia`](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getDisplayMedia)</Intro>
 
diff --git a/docs/loaders/texture-use-texture.mdx b/docs/loaders/texture-use-texture.mdx
@@ -4,6 +4,7 @@ sourcecode: src/core/Texture.tsx
 ---
 
 [![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.pmnd.rs/?path=/story/loaders-texture)
+[![](https://img.shields.io/badge/-suspense-brightgreen)](https://r3f.docs.pmnd.rs/api/hooks#useloader)
 
 A convenience hook that uses `useLoader` and `TextureLoader`
 
diff --git a/docs/loaders/video-texture-use-video-texture.mdx b/docs/loaders/video-texture-use-video-texture.mdx
@@ -3,7 +3,8 @@ title: VideoTexture / useVideoTexture
 sourcecode: src/core/VideoTexture.tsx
 ---
 
-[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.pmnd.rs/?path=/story/misc-videotexture) ![](https://img.shields.io/badge/-suspense-brightgreen)
+[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.pmnd.rs/?path=/story/misc-videotexture)
+[![](https://img.shields.io/badge/-suspense-brightgreen)](https://r3f.docs.pmnd.rs/api/hooks#useloader)
 
 <Grid cols={4}>
   <li>
diff --git a/docs/loaders/webcam-video-texture.mdx b/docs/loaders/webcam-video-texture.mdx
@@ -3,7 +3,8 @@ title: WebcamVideoTexture
 sourcecode: src/web/WebcamVideoTexture.tsx
 ---
 
-[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.pmnd.rs/?path=/story/misc-webcamvideotexture) ![](https://img.shields.io/badge/-suspense-brightgreen)
+[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.pmnd.rs/?path=/story/misc-webcamvideotexture)
+[![](https://img.shields.io/badge/-suspense-brightgreen)](https://r3f.docs.pmnd.rs/api/hooks#useloader)
 
 <Intro>Create a video texture from [`getUserMedia`](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia)</Intro>
 
diff --git a/docs/misc/face-landmarker.mdx b/docs/misc/face-landmarker.mdx
@@ -3,7 +3,7 @@ title: FaceLandmarker
 sourcecode: src/web/FaceLandmarker.tsx
 ---
 
-![](https://img.shields.io/badge/-suspense-brightgreen)
+[![](https://img.shields.io/badge/-suspense-brightgreen)](https://r3f.docs.pmnd.rs/api/hooks#useloader)
 
 A @mediapipe/tasks-vision [`FaceLandmarker`](https://developers.google.com/mediapipe/api/solutions/js/tasks-vision.facelandmarker) provider, as well as a `useFaceLandmarker` hook.
 
diff --git a/docs/staging/center.mdx b/docs/staging/center.mdx
@@ -14,7 +14,9 @@ sourcecode: src/core/Center.tsx
   </li>
 </Grid>
 
-Calculates a boundary box and centers its children accordingly.
+<Intro>
+  Group `children` together and -offset them by half of their bounding box.
+</Intro>
 
 ```tsx
 export type Props = ThreeElements['group'] & {
diff --git a/docs/staging/cloud.mdx b/docs/staging/cloud.mdx
@@ -3,7 +3,8 @@ title: Cloud
 sourcecode: src/core/Cloud.tsx
 ---
 
-[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.pmnd.rs/?path=/story/staging-cloud--cloud-st) ![](https://img.shields.io/badge/-suspense-brightgreen)
+[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.pmnd.rs/?path=/story/staging-cloud--cloud-st)
+[![](https://img.shields.io/badge/-suspense-brightgreen)](https://r3f.docs.pmnd.rs/api/hooks#useloader)
 
 <Grid cols={4}>
 
diff --git a/docs/staging/environment.mdx b/docs/staging/environment.mdx
@@ -4,6 +4,7 @@ sourcecode: src/core/Environment.tsx
 ---
 
 [![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.pmnd.rs/?path=/story/staging-environment--environment-story)
+[![](https://img.shields.io/badge/-suspense-brightgreen)](https://r3f.docs.pmnd.rs/api/hooks#useloader)
 
 <Grid cols={4}>
   <li>
diff --git a/docs/staging/matcap-texture-use-matcap-texture.mdx b/docs/staging/matcap-texture-use-matcap-texture.mdx
@@ -3,7 +3,8 @@ title: MatcapTexture / useMatcapTexture
 sourcecode: src/core/MatcapTexture.tsx
 ---
 
-[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.pmnd.rs/?path=/story/staging-matcaptexture) ![](https://img.shields.io/badge/-suspense-brightgreen)
+[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.pmnd.rs/?path=/story/staging-matcaptexture)
+[![](https://img.shields.io/badge/-suspense-brightgreen)](https://r3f.docs.pmnd.rs/api/hooks#useloader)
 
 Loads matcap textures from this repository: https://github.com/emmelleppi/matcaps
 
diff --git a/docs/staging/normal-texture-use-normal-texture.mdx b/docs/staging/normal-texture-use-normal-texture.mdx
@@ -3,7 +3,8 @@ title: NormalTexture / useNormalTexture
 sourcecode: src/core/NormalTexture.tsx
 ---
 
-[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.pmnd.rs/?path=/story/staging-normaltexture) ![](https://img.shields.io/badge/-suspense-brightgreen)
+[![](https://img.shields.io/badge/-storybook-%23ff69b4)](https://drei.pmnd.rs/?path=/story/staging-normaltexture)
+[![](https://img.shields.io/badge/-suspense-brightgreen)](https://r3f.docs.pmnd.rs/api/hooks#useloader)
 
 Loads normal textures from this repository: https://github.com/emmelleppi/normal-maps
 
diff --git a/package.json b/package.json
@@ -36,7 +36,7 @@
     "eslint:ci": "eslint .",
     "prettier": "prettier --check .",
     "prettier-fix": "prettier --write .",
-    "test": "yarn eslint:ci && yarn typecheck && yarn prettier && (cd test/e2e; ./e2e.sh)",
+    "test": "yarn eslint:ci && yarn typecheck && yarn prettier && (cd test/e2e; ./e2e.sh 0.180)",
     "typecheck": "tsc --noEmit --emitDeclarationOnly false --strict --jsx react",
     "typegen": "tsc --emitDeclarationOnly",
     "storybook": "cross-env NODE_OPTIONS=\"--openssl-legacy-provider\" storybook dev -p 6006",
@@ -77,7 +77,7 @@
     "@babel/preset-env": "^7.26.0",
     "@babel/preset-react": "^7.25.9",
     "@babel/preset-typescript": "^7.26.0",
-    "@chromatic-com/storybook": "^4.0.0",
+    "@chromatic-com/storybook": "^4.1.0",
     "@eslint/compat": "^1.2.3",
     "@eslint/eslintrc": "^3.2.0",
     "@eslint/js": "^9.15.0",
@@ -87,8 +87,8 @@
     "@rollup/plugin-commonjs": "^19.0.0",
     "@rollup/plugin-json": "^4.1.0",
     "@rollup/plugin-node-resolve": "^13.0.0",
-    "@storybook/addon-docs": "^9.0.0",
-    "@storybook/react-vite": "^9.0.0",
+    "@storybook/addon-docs": "^9.1.2",
+    "@storybook/react-vite": "^9.1.2",
     "@types/react": "^19.0.2",
     "@types/react-dom": "^19.0.2",
     "@types/three": "^0.161.0",
@@ -102,7 +102,7 @@
     "eslint-config-prettier": "^9.1.0",
     "eslint-plugin-react": "^7.37.2",
     "eslint-plugin-react-hooks": "^5.0.0",
-    "eslint-plugin-storybook": "^9.0.0",
+    "eslint-plugin-storybook": "^9.1.2",
     "husky": "^9.1.7",
     "json": "^11.0.0",
     "prettier": "^3.3.3",
@@ -116,7 +116,7 @@
     "rollup-plugin-terser": "^7.0.2",
     "semantic-release": "^24.2.0",
     "serve": "^14.2.4",
-    "storybook": "^9.0.0",
+    "storybook": "^9.1.2",
     "three": "^0.159.0",
     "ts-node": "^10.9.2",
     "typescript": "^5.6.3",
diff --git a/src/core/Center.tsx b/src/core/Center.tsx
@@ -36,7 +36,7 @@ export type CenterProps = Omit<ThreeElements['group'], 'ref'> & {
   /** Disable z-axis centering */
   disableZ?: boolean
   /** object to compute box3 from */
-  object?: THREE.Object3D | null
+  object?: Object3D | null
   /** See https://threejs.org/docs/index.html?q=box3#api/en/math/Box3.setFromObject */
   precise?: boolean
   /** Callback, fires in the useLayoutEffect phase, after measurement */
diff --git a/src/web/pivotControls/AxisArrow.tsx b/src/web/pivotControls/AxisArrow.tsx
@@ -52,6 +52,7 @@ export const AxisArrow: React.FC<{ direction: THREE.Vector3; axis: 0 | 1 | 2 }>
     axisColors,
     hoveredColor,
     opacity,
+    renderOrder,
     onDragStart,
     onDrag,
     onDragEnd,
@@ -185,11 +186,11 @@ export const AxisArrow: React.FC<{ direction: THREE.Vector3; axis: 0 | 1 | 2 }>
           color={color_ as any}
           opacity={opacity}
           polygonOffset
-          renderOrder={1}
+          renderOrder={renderOrder}
           polygonOffsetFactor={-10}
           fog={false}
         />
-        <mesh raycast={() => null} position={[0, cylinderLength + coneLength / 2.0, 0]} renderOrder={500}>
+        <mesh raycast={() => null} position={[0, cylinderLength + coneLength / 2.0, 0]} renderOrder={renderOrder}>
           <coneGeometry args={[coneWidth, coneLength, 24, 1]} />
           <meshBasicMaterial
             transparent
diff --git a/src/web/pivotControls/AxisRotator.tsx b/src/web/pivotControls/AxisRotator.tsx
@@ -72,6 +72,7 @@ export const AxisRotator: React.FC<{ dir1: THREE.Vector3; dir2: THREE.Vector3; a
     fixed,
     axisColors,
     hoveredColor,
+    renderOrder,
     opacity,
     onDragStart,
     onDrag,
@@ -239,6 +240,7 @@ export const AxisRotator: React.FC<{ dir1: THREE.Vector3; dir2: THREE.Vector3; a
         opacity={opacity}
         polygonOffset
         polygonOffsetFactor={-10}
+        renderOrder={renderOrder}
         fog={false}
       />
     </group>
diff --git a/src/web/pivotControls/PlaneSlider.tsx b/src/web/pivotControls/PlaneSlider.tsx
@@ -48,6 +48,7 @@ export const PlaneSlider: React.FC<{ dir1: THREE.Vector3; dir2: THREE.Vector3; a
     axisColors,
     hoveredColor,
     opacity,
+    renderOrder,
     onDragStart,
     onDrag,
     onDragEnd,
@@ -209,6 +210,7 @@ export const PlaneSlider: React.FC<{ dir1: THREE.Vector3; dir2: THREE.Vector3; a
           onPointerOut={onPointerOut}
           scale={length}
           userData={userData}
+          renderOrder={renderOrder}
         >
           <planeGeometry />
           <meshBasicMaterial
@@ -233,6 +235,7 @@ export const PlaneSlider: React.FC<{ dir1: THREE.Vector3; dir2: THREE.Vector3; a
           polygonOffsetFactor={-10}
           userData={userData}
           fog={false}
+          renderOrder={renderOrder}
         />
       </group>
     </group>
diff --git a/src/web/pivotControls/ScalingSphere.tsx b/src/web/pivotControls/ScalingSphere.tsx
@@ -53,6 +53,7 @@ export const ScalingSphere: React.FC<{ direction: THREE.Vector3; axis: 0 | 1 | 2
     axisColors,
     hoveredColor,
     opacity,
+    renderOrder,
     onDragStart,
     onDrag,
     onDragEnd,
@@ -196,7 +197,7 @@ export const ScalingSphere: React.FC<{ direction: THREE.Vector3; axis: 0 | 1 | 2
             />
           </Html>
         )}
-        <mesh ref={meshRef} position={[0, position, 0]} renderOrder={500} userData={userData}>
+        <mesh ref={meshRef} position={[0, position, 0]} renderOrder={renderOrder} userData={userData}>
           <sphereGeometry args={[radius, 12, 12]} />
           <meshBasicMaterial
             transparent
diff --git a/src/web/pivotControls/context.ts b/src/web/pivotControls/context.ts
@@ -23,6 +23,7 @@ export type PivotContext = {
   lineWidth: number
   fixed: boolean
   depthTest: boolean
+  renderOrder: number
   userData?: { [key: string]: any }
   annotations?: boolean
   annotationsClass?: string
diff --git a/src/web/pivotControls/index.tsx b/src/web/pivotControls/index.tsx
@@ -82,6 +82,7 @@ export type PivotControlsProps = {
   onDragEnd?: () => void
   /** Set this to false if you want the gizmo to be visible through faces */
   depthTest?: boolean
+  renderOrder?: number
   opacity?: number
   visible?: boolean
   userData?: { [key: string]: any }
@@ -115,6 +116,7 @@ export const PivotControls: ForwardRefComponent<PivotControlsProps, THREE.Group>
       rotationLimits,
       scaleLimits,
       depthTest = true,
+      renderOrder = 500,
       axisColors = ['#ff2060', '#20df80', '#2080ff'],
       hoveredColor = '#ffff40',
       annotations = false,
@@ -197,6 +199,7 @@ export const PivotControls: ForwardRefComponent<PivotControlsProps, THREE.Group>
         lineWidth,
         fixed,
         depthTest,
+        renderOrder,
         userData,
         annotations,
         annotationsClass,
diff --git a/test/e2e/e2e.sh b/test/e2e/e2e.sh
diff --git a/yarn.lock b/yarn.lock
