.changeset/config.json

@@ -6,5 +6,8 @@
   "access": "public",
   "baseBranch": "master",
   "updateInternalDependencies": "minor",
-  "ignore": []
+  "ignore": [],
+  "___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH": {
+    "onlyUpdatePeerDependentsWhenOutOfRange": true
+  }
 }

.eslintrc.json

@@ -4,8 +4,14 @@
     "es6": true,
     "node": true
   },
-  "extends": ["prettier", "plugin:prettier/recommended", "plugin:react-hooks/recommended", "plugin:import/recommended"],
-  "plugins": ["@typescript-eslint", "react", "react-hooks", "import", "jest", "prettier"],
+  "extends": [
+    "prettier",
+    "plugin:prettier/recommended",
+    "plugin:react-hooks/recommended",
+    "plugin:import/recommended",
+    "plugin:@react-three/recommended"
+  ],
+  "plugins": ["@typescript-eslint", "react", "react-hooks", "import", "jest", "prettier", "@react-three"],
   "parser": "@typescript-eslint/parser",
   "parserOptions": {
     "ecmaFeatures": {
@@ -64,6 +70,7 @@
   "rules": {
     "import/no-unresolved": "off",
     "import/named": "off",
-    "import/namespace": "off"
+    "import/namespace": "off",
+    "import/no-named-as-default-member": "off"
   }
 }

.github/workflows/test.yml

@@ -24,16 +24,19 @@ jobs:
           install-command: yarn --immutable --silent
 
       - name: Check types
-        run: yarn typecheck
+        run: yarn run typecheck
+
+      - name: Check lint
+        run: yarn run eslint
 
       - name: Build
-        run: yarn build
+        run: yarn run build
 
       - name: Jest run
-        run: yarn test
+        run: yarn run test
 
       - name: Report Fiber size
-        run: yarn analyze-fiber
+        run: yarn run analyze-fiber
 
       - name: Report Test Renderer size
-        run: yarn analyze-test
+        run: yarn run analyze-test

CONTRIBUTING.md

@@ -0,0 +1,79 @@
+## Contributing
+
+This project uses [semantic commits](https://conventionalcommits.org) and [semver](https://semver.org).
+
+To get started, make sure you have [Node](https://nodejs.org) and [Yarn 1](https://classic.yarnpkg.com) (newer versions of Yarn do not work) installed. Install dependencies with:
+
+```bash
+yarn
+```
+
+[Preconstruct](https://github.com/preconstruct/preconstruct) will automatically build and link packages for local development via symlinks. If you ever need to do this manually, try running:
+
+```bash
+yarn dev
+```
+
+> **Note**: Some Windows users may need to [enable developer mode](https://howtogeek.com/292914/what-is-developer-mode-in-windows-10) if experiencing `EPERM: operation not permitted, symlink` with Preconstruct. If this persists, you might be running on an unsupported drive/format. In which case, consider using [Docker](https://docs.docker.com/docker-for-windows).
+
+### Development
+
+Locally run examples against the library with:
+
+```bash
+yarn examples
+```
+
+### Testing
+
+Run test suites against the library with:
+
+```bash
+yarn test
+
+# or, to test live against changes
+yarn test:watch
+```
+
+If your code invalidates a snapshot, you can update it with:
+
+```bash
+yarn test -u
+```
+
+> **Note**: Use discretion when updating snapshots, as they represent the integrity of the package.
+>
+> If the difference is complex or you're unsure of the changes, leave it for review and we'll unblock it.
+
+### Publishing
+
+We use [atlassian/changesets](https://github.com/atlassian/changesets) to publish our packages, which will automatically document and version changes.
+
+To publish a release on NPM, run the following and complete the dialog (see [FAQ](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)):
+
+```bash
+# Describe the changes you've made as you would semantic commits for CHANGELOG.md
+yarn changeset:add
+
+# Tag which packages should receive an update and be published.
+yarn vers
+
+# Commit and publish changes to NPM.
+yarn release
+```
+
+We don't have automatic CI deployments yet, so make sure to [create a release](https://github.com/pmndrs/react-three-fiber/releases/new) on GitHub to notify people when it's ready. Choose or create the version generated by your changeset, and you can leave the rest to auto-fill via the "Generate release notes" button to describe PRs since the last release.
+
+### Prerelease
+
+Follow the same steps as before, but specify a tag for [prerelease mode](https://github.com/changesets/changesets/blob/main/docs/prereleases.md) with:
+
+```bash
+yarn changeset pre enter <alpha | beta | rc>
+```
+
+To cancel or leave prerelease mode, try running:
+
+```bash
+yarn changeset pre exit
+```

babel.config.js

@@ -5,6 +5,7 @@ module.exports = {
       '@babel/preset-env',
       {
         include: [
+          '@babel/plugin-proposal-class-properties',
           '@babel/plugin-proposal-optional-chaining',
           '@babel/plugin-proposal-nullish-coalescing-operator',
           '@babel/plugin-proposal-numeric-separator',

docs/API/additional-exports.mdx

@@ -3,17 +3,19 @@ title: Additional Exports
 nav: 9
 ---
 
-| export         | usage                                                          |
-| -------------- | -------------------------------------------------------------- |
-| addEffect      | Adds a global render callback which is called each frame       |
-| addAfterEffect | Adds a global after-render callback which is called each frame |
-| addTail        | Adds a global callback which is called when rendering stops    |
-| invalidate     | Forces view global invalidation                                |
-| advance        | Advances the frameloop (given that it's set to 'never')        |
-| extend         | Extends the native-object catalogue                            |
-| createPortal   | Creates a portal (it's a React feature for re-parenting)       |
-| createRoot     | Creates a root that can render three JSX into a canvas         |
-| events         | Dom pointer-event system                                       |
-| applyProps     | `applyProps(element, props)` sets element properties,          |
-| act            | usage with react-testing                                       |
-|                |                                                                |
+| export             | usage                                                          |
+| ------------------ | -------------------------------------------------------------- |
+| addEffect          | Adds a global render callback which is called each frame       |
+| addAfterEffect     | Adds a global after-render callback which is called each frame |
+| addTail            | Adds a global callback which is called when rendering stops    |
+| flushGlobalEffects | Flushes global render-effects for when manually driving a loop |
+| invalidate         | Forces view global invalidation                                |
+| advance            | Advances the frameloop (given that it's set to 'never')        |
+| extend             | Extends the native-object catalogue                            |
+| createPortal       | Creates a portal (it's a React feature for re-parenting)       |
+| createRoot         | Creates a root that can render three JSX into a canvas         |
+| events             | Dom pointer-event system                                       |
+| applyProps         | `applyProps(element, props)` sets element properties,          |
+| act                | usage with react-testing                                       |
+| useInstanceHandle  | Exposes react-internal local state from `instance.__r3f`       |
+|                    |                                                                |

docs/API/canvas.mdx

@@ -14,7 +14,7 @@ const App = () => (
   <Canvas>
     <pointLight position={[10, 10, 10]} />
     <mesh>
-      <sphereBufferGeometry />
+      <sphereGeometry />
       <meshStandardMaterial color="hotpink" />
     </mesh>
   </Canvas>
@@ -23,22 +23,26 @@ const App = () => (
 
 ## Render Props
 
-| Prop            | Description                                                                                                                                       | Default                                                  |
-| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
-| children        | three.js JSX elements or regular components                                                                                                       |                                                          |
-| gl              | Props that go into the default renderer, or your own renderer. Also accepts a synchronous callback like `gl={canvas => new Renderer({ canvas })}` | `{}`                                                     |
-| camera          | Props that go into the default camera, or your own `THREE.Camera`                                                                                 | `{ fov: 75, near: 0.1, far: 1000, position: [0, 0, 5] }` |
-| shadows         | Props that go into `gl.shadowMap`, can also be set true for `PCFsoft`                                                                             | `false`                                                  |
-| raycaster       | Props that go into the default raycaster                                                                                                          | `{}`                                                     |
-| frameloop       | Render mode: always, demand, never                                                                                                                | `always`                                                 |
-| resize          | Resize config, see react-use-measure's options                                                                                                    | `{ scroll: true, debounce: { scroll: 50, resize: 0 } }`  |
-| orthographic    | Creates an orthographic camera                                                                                                                    | `false`                                                  |
-| dpr             | Pixel-ratio, use `window.devicePixelRatio`, or automatic: [min, max]                                                                              | `[1, 2]`                                                 |
-| legacy          | Enables THREE.ColorManagement.legacyMode in three r139 or later                                                                                   | `false`                                                  |
-| linear          | Switch off automatic sRGB encoding and gamma correction                                                                                           | `false`                                                  |
-| flat            | Use `THREE.NoToneMapping` instead of `THREE.ACESFilmicToneMapping`                                                                                | `false`                                                  |
-| onCreated       | Callback after the canvas has rendered (but not yet committed)                                                                                    | `(state) => {}`                                          |
-| onPointerMissed | Response for pointer clicks that have missed any target                                                                                           | `(event) => {}`                                          |
+| Prop            | Description                                                                                                                                       | Default                                                           |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| children        | three.js JSX elements or regular components                                                                                                       |                                                                   |
+| gl              | Props that go into the default renderer, or your own renderer. Also accepts a synchronous callback like `gl={canvas => new Renderer({ canvas })}` | `{}`                                                              |
+| camera          | Props that go into the default camera, or your own `THREE.Camera`                                                                                 | `{ fov: 75, near: 0.1, far: 1000, position: [0, 0, 5] }`          |
+| scene           | Props that go into the default scene, or your own `THREE.Scene`                                                                                   | `{}`                                                              |
+| shadows         | Props that go into `gl.shadowMap`, can be set true for `PCFsoft` or one of the following: 'basic', 'percentage', 'soft', 'variance'               | `false`                                                           |
+| raycaster       | Props that go into the default raycaster                                                                                                          | `{}`                                                              |
+| frameloop       | Render mode: always, demand, never                                                                                                                | `always`                                                          |
+| resize          | Resize config, see react-use-measure's options                                                                                                    | `{ scroll: true, debounce: { scroll: 50, resize: 0 } }`           |
+| orthographic    | Creates an orthographic camera                                                                                                                    | `false`                                                           |
+| dpr             | Pixel-ratio, use `window.devicePixelRatio`, or automatic: [min, max]                                                                              | `[1, 2]`                                                          |
+| legacy          | Enables THREE.ColorManagement in three r139 or later                                                                                              | `false`                                                           |
+| linear          | Switch off automatic sRGB color space and gamma correction                                                                                        | `false`                                                           |
+| events          | Configuration for the event manager, as a function of state                                                                                       | `import { events } from "@react-three/fiber"`                     |
+| eventSource     | The source where events are being subscribed to, HTMLElement                                                                                      | `React.MutableRefObject<HTMLElement>`, `gl.domElement.parentNode` |
+| eventPrefix     | The event prefix that is cast into canvas pointer x/y events                                                                                      | `offset`                                                          |
+| flat            | Use `THREE.NoToneMapping` instead of `THREE.ACESFilmicToneMapping`                                                                                | `false`                                                           |
+| onCreated       | Callback after the canvas has rendered (but not yet committed)                                                                                    | `(state) => {}`                                                   |
+| onPointerMissed | Response for pointer clicks that have missed any target                                                                                           | `(event) => {}`                                                   |
 
 ## Render defaults
 
@@ -50,7 +54,7 @@ Canvas uses [createRoot](#createroot) which will create a translucent `THREE.Web
 
 and with the following properties:
 
-- outputEncoding = THREE.sRGBEncoding
+- outputColorSpace = THREE.SRGBColorSpace
 - toneMapping = THREE.ACESFilmicToneMapping
 
 It will also create the following scene internals:
@@ -60,7 +64,7 @@ It will also create the following scene internals:
 - A `THREE.PCFSoftShadowMap` if `shadows` is true
 - A `THREE.Scene` (into which all the JSX is rendered) and a `THREE.Raycaster`
 
-In recent versions of threejs, `THREE.ColorManagement.legacy` will be set to false to enable automatic conversion of colors according to the renderer's configured color space. R3F will handle texture encoding conversion. For more on this topic, see [https://threejs.org/docs/#manual/en/introduction/Color-management](https://threejs.org/docs/#manual/en/introduction/Color-management).
+In recent versions of threejs, `THREE.ColorManagement.enabled` will be set to `true` to enable automatic conversion of colors according to the renderer's configured color space. R3F will handle texture color space conversion. For more on this topic, see [https://threejs.org/docs/#manual/en/introduction/Color-management](https://threejs.org/docs/#manual/en/introduction/Color-management).
 
 ## Custom Canvas
 
@@ -73,34 +77,32 @@ Roots have the same options and properties as `Canvas`, but you are responsible
 Creates a root targeting a canvas, rendering JSX.
 
 ```jsx
-import { createRoot, events } from '@react-three/fiber'
+import * as THREE from 'three'
+import { extend, createRoot, events } from '@react-three/fiber'
 
-let root
+// Register the THREE namespace as native JSX elements.
+// See below for notes on tree-shaking
+extend(THREE)
 
-const handleResize = () => {
-  const size = { width: window.innerWidth, height: window.innerHeight }
+// Create a react root
+const root = createRoot(document.querySelector('canvas'))
 
-  // Create root with a size, events
-  root = createRoot(document.querySelector('canvas'), {
-    events,
-    size,
-  })
+// Configure the root, inject events optionally, set camera, etc
+root.configure({ events, camera: { position: [0, 0, 50] } })
 
-  // Render JSX
-  root.render(<mesh />)
-
-  // Can also tweak root root options after creation:
-  root.configure({ size })
+// createRoot by design is not responsive, you have to take care of resize yourself
+window.addEventListener('resize', () => {
+  root.configure({ size: { width: window.innerWidth, height: window.innerHeight } })
+})
 
-  // Or to unmount and dispose of memory:
-  root.unmount()
-}
-handleResize()
+// Trigger resize
+window.dispatchEvent(new Event('resize'))
 
-window.addEventListener('resize', handleResize)
+// Render entry point
+root.render(<App />)
 
-// to unmount
-root.unmount()
+// Unmount and dispose of memory
+// root.unmount()
 ```
 
 ## Tree-shaking