pmndrs
diff --git a/‎.changeset/pre.json
+9 b/‎.changeset/pre.json
+9
diff --git a/‎.changeset/tender-deers-swim.md
+6 b/‎.changeset/tender-deers-swim.md
+6
diff --git a/‎.eslintrc.json
+7-8 b/‎.eslintrc.json
+7-8
diff --git a/‎.gitignore
+20-20 b/‎.gitignore
+20-20
diff --git a/‎docs/API/additional-exports.mdx
+14-15 b/‎docs/API/additional-exports.mdx
+14-15
diff --git a/‎docs/API/canvas.mdx
+95-18 b/‎docs/API/canvas.mdx
+95-18
diff --git a/‎docs/API/hooks.mdx
+1-2 b/‎docs/API/hooks.mdx
+1-2
diff --git a/‎docs/API/objects.mdx
+19-53 b/‎docs/API/objects.mdx
+19-53
@@ -0,0 +1,9 @@
+{
+  "mode": "pre",
+  "tag": "beta",
+  "initialVersions": {
+    "@react-three/fiber": "8.0.0-beta-05",
+    "@react-three/test-renderer": "8.0.0-beta-00"
+  },
+  "changesets": ["tender-deers-swim"]
+}
@@ -0,0 +1,6 @@
+---
+'@react-three/fiber': patch
+'@react-three/test-renderer': patch
+---
+
+new beta for library testing
@@ -4,13 +4,7 @@
     "es6": true,
     "node": true
   },
-  "extends": [
-    "prettier",
-    "plugin:prettier/recommended",
-    "plugin:react-hooks/recommended",
-    "plugin:import/errors",
-    "plugin:import/warnings"
-  ],
+  "extends": ["prettier", "plugin:prettier/recommended", "plugin:react-hooks/recommended", "plugin:import/recommended"],
   "plugins": ["@typescript-eslint", "react", "react-hooks", "import", "jest", "prettier"],
   "parser": "@typescript-eslint/parser",
   "parserOptions": {
@@ -66,5 +60,10 @@
         "project": "./tsconfig.json"
       }
     }
-  ]
+  ],
+  "rules": {
+    "import/no-unresolved": "off",
+    "import/named": "off",
+    "import/namespace": "off"
+  }
 }
@@ -1,20 +1,20 @@
-node_modules/
-coverage/
-dist/
-build/
-types/
-# commit types in src
-!packages/*/src/types/
-Thumbs.db
-ehthumbs.db
-Desktop.ini
-$RECYCLE.BIN/
-.DS_Store
-.vscode
-.docz/
-package-lock.json
-coverage/
-.idea
-yarn-error.log
-.size-snapshot.json
-__tests__/__image_snapshots__/__diff_output__
+node_modules/
+coverage/
+dist/
+build/
+types/
+# commit types in src
+!packages/*/src/types/
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+$RECYCLE.BIN/
+.DS_Store
+.vscode
+.docz/
+package-lock.json
+coverage/
+.idea
+yarn-error.log
+.size-snapshot.json
+__tests__/__image_snapshots__/__diff_output__
@@ -3,18 +3,17 @@ 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)       |
-| render                 | Renders three JSX into a canvas                                |
-| unmountComponentAtNode | Unmounts root scene                                            |
-| 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    |
+| 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                                       |
+|                |                                                                |
@@ -21,7 +21,7 @@ const App = () => (
 )
 ```
 
-### Render Props
+## Render Props
 
 | Prop            | Description                                                                                                                                       | Default                                                  |
 | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
@@ -30,20 +30,18 @@ const App = () => (
 | 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                                                                                                          | `{}`                                                     |
-| vr              | Switches renderer to VR mode, then uses `gl.setAnimationLoop`                                                                                     | `false`                                                  |
-| mode            | React mode: legacy, blocking, concurrent                                                                                                          | `blocking`                                               |
 | 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]                                                                              | `undefined`                                              |
+| dpr             | Pixel-ratio, use `window.devicePixelRatio`, or automatic: [min, max]                                                                              | `[1, 2]`                                                 |
 | 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) => {}`                                          |
 
-### Render defaults
+## Render defaults
 
-Canvas uses the [render function](/react-three-fiber/api/render-function) which will create a translucent `THREE.WebGLRenderer` with the following constructor args:
+Canvas uses [createRoot](#createroot) which will create a translucent `THREE.WebGLRenderer` with the following constructor args:
 
 - antialias=true
 - alpha=true
@@ -61,21 +59,100 @@ 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`
 
-<Hint>
+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).
 
-The colorspace will be set to sRGB (unless "linear" is true), all colors and textures will be
-auto-converted. Consult [donmccurdy.com: Color Management in
-three.js](https://www.donmccurdy.com/2020/06/17/color-management-in-threejs) for more information
-about this. Unless "flat" is true it will set up `THREE.ACESFilmicToneMapping` for slightly more
-contrast.
+## Custom Canvas
 
-</Hint>
+R3F can render to a root, similar to how `react-dom` and all the other React renderers work. This allows you to shave off `react-dom` (~40kb), `react-use-measure` (~3kb) and, if you don't need them, `pointer-events` (~7kb) (you need to explicitly import `events` and add them to the config otherwise).
 
-<Hint>
+Roots have the same options and properties as `Canvas`, but you are responsible for resizing it. It requires an existing DOM `<canvas>` object into which it renders.
 
-Canvas creates a [resize observer](https://github.com/pmndrs/react-use-measure) to update the canvas size.
+### CreateRoot
 
-Consider Resize-Observer polyfills for older Safari browsers. We recommend
-[juggle/resize-observer](https://github.com/juggle/resize-observer).
+Creates a root targeting a canvas, rendering JSX.
 
-</Hint>
+```jsx
+import { createRoot, events } from '@react-three/fiber'
+
+let root
+
+const handleResize = () => {
+  const size = { width: window.innerWidth, height: window.innerHeight }
+
+  // Create root with a size, events
+  root = createRoot(document.querySelector('canvas'), {
+    events,
+    size,
+  })
+
+  // Render JSX
+  root.render(<mesh />)
+
+  // Can also tweak root root options after creation:
+  root.configure({ size })
+
+  // Or to unmount and dispose of memory:
+  root.unmount()
+}
+handleResize()
+
+window.addEventListener('resize', handleResize)
+
+// to unmount
+root.unmount()
+```
+
+## Tree-shaking
+
+New with v8, the underlying reconciler no longer pulls in the THREE namespace automatically.
+
+This enables a granular catalogue which also enables tree-shaking via the `extend` API:
+
+```jsx
+import { extend, createRoot } from '@react-three/fiber'
+import { Mesh, BoxGeometry, MeshStandardMaterial } from 'three'
+
+extend({ Mesh, BoxGeometry, MeshStandardMaterial })
+
+createRoot(canvas).render(
+  <>
+    <mesh>
+      <boxGeometry />
+      <meshStandardMaterial />
+    </mesh>
+  </>,
+)
+```
+
+There's an [official babel plugin](https://github.com/pmndrs/react-three-babel) which will do this for you automatically:
+
+```jsx
+// In:
+
+import { createRoot } from '@react-three/fiber'
+
+createRoot(canvasNode).render(
+  <mesh>
+    <boxGeometry />
+    <meshStandardMaterial />
+  </mesh>,
+)
+
+// Out:
+
+import { createRoot, extend } from '@react-three/fiber'
+import { Mesh as _Mesh, BoxGeometry as _BoxGeometry, MeshStandardMaterial as _MeshStandardMaterial } from 'three'
+
+extend({
+  Mesh: _Mesh,
+  BoxGeometry: _BoxGeometry,
+  MeshStandardMaterial: _MeshStandardMaterial,
+})
+
+createRoot(canvasNode).render(
+  <mesh>
+    <boxGeometry />
+    <meshStandardMaterial />
+  </mesh>,
+)
+```
@@ -54,7 +54,6 @@ The hook is reactive, if you resize the browser for instance, you get fresh meas
 | camera          | Camera                                                    | `THREE.PerspectiveCamera`                                                                                                                                                                                      |
 | mouse           | Contains updated, normalized, centric pointer coordinates | `THREE.Vector2`                                                                                                                                                                                                |
 | clock           | Running system clock                                      | `THREE.Clock`                                                                                                                                                                                                  |
-| vr              | True when the system is in VR mode                        | `boolean`                                                                                                                                                                                                      |
 | linear          | True when the colorspace is linear                        | `boolean`                                                                                                                                                                                                      |
 | flat            | True when no tonemapping is used                          | `boolean`                                                                                                                                                                                                      |
 | frameloop       | React render-mode                                         | `always`, `demand`, `never`                                                                                                                                                                                    |
@@ -111,7 +110,7 @@ This hook allows you to execute code on every rendered frame, like running effec
 import { useFrame } from '@react-three/fiber'
 
 function Foo() {
-  useFrame((state, delta) => {
+  useFrame((state, delta, xrFrame) => {
     // This function runs at the native refresh rate inside of a shared render-loop
   })
 ```
 
@@ -65,6 +65,14 @@ Properties that have a `setScalar` method (for instance `Vector3`) can be set li
 <mesh scale={1} />
 ```
 
+## Piercing into nested properties
+
+If you want to reach into nested attributes (for instance: `mesh.rotation.x`), just use dash-case.
+
+```jsx
+<mesh rotation-x={1} material-uniforms-resolution-value={[512, 512]} />
+```
+
 ## Dealing with non-scene objects
 
 You can put non-Object3D primitives (geometries, materials, etc) into the render tree as well. They take the same properties and constructor arguments they normally would.
@@ -94,44 +102,20 @@ The following attaches a material to the `material` property of a mesh and a geo
   <boxGeometry />
 ```
 
-### Nesting
-
-You can nest primitive objects, too:
-
-```jsx
-<mesh>
-  <meshBasicMaterial attach="material">
-    <texture attach="map" image={img} onUpdate={self => (self.needsUpdate = true)} />
-```
-
-### AttachArray
-
-Sometimes attaching isn't enough. The following example attaches effects to an array called "passes" of the parent `effectComposer`. `attachArray` adds the object to the target array and takes it out on unmount:
-
-```jsx
-<effectComposer>
-  <renderPass attachArray="passes" scene={scene} camera={camera} />
-  <glitchPass attachArray="passes" renderToScreen />
-```
-
-### AttachObject
-
-You can also attach to named parent properties using `attachObject={[target, name]}`, which adds the object and takes it out on unmount. The following adds a buffer-attribute to `parent.attributes.position`.
+You can also deeply nest attach through piercing. The following adds a buffer-attribute to `parent.attributes.position`.
 
 ```jsx
 <bufferGeometry attach="geometry">
-  <bufferAttribute attachObject={['attributes', 'position']} count={v.length / 3} array={v} itemSize={3} />
+  <bufferAttribute attach="attributes-position" count={v.length / 3} array={v} itemSize={3} />
 ```
 
-### AttachFns
-
-Some objects have special add/remove function, you can't easily attach objects. In that case `attachFns` gives you full control.
+Some objects have special add/remove function, you can't easily attach objects. In that case `attach` gives you full control.
 
 The following uses the effect composer from the [vanruesc/postprocessing](https://github.com/vanruesc/postprocessing) library, which works differently than three/examples/jsm. You need to call `Composer.addPass` to add an effect and `Composer.removePass` to remove it.
 
 ```jsx
 <effectComposer>
-  <renderPass attachFns={["addPass", "removePass"]} args={[scene, camera]} />
+  <renderPass args={[scene, camera]} attach={["addPass", "removePass"]} />
 ```
 
 And in the case the add/remove functions are more complex:
@@ -140,18 +124,20 @@ And in the case the add/remove functions are more complex:
 <effectComposer>
   <renderPass
     args={[scene, camera]}
-    attachFns={[
+    attach={[
       (parent, self) => parent.addPass(self),
       (parent, self) => parent.removePass(self)
     ]} />
 ```
 
-## Piercing into nested properties
+### Nesting
 
-If you want to reach into nested attributes (for instance: `mesh.rotation.x`), just use dash-case.
+You can nest primitive objects, too:
 
 ```jsx
-<mesh rotation-x={1} material-uniforms-resolution-value={[512, 512]} />
+<mesh>
+  <meshBasicMaterial attach="material">
+    <texture attach="map" image={img} onUpdate={self => (self.needsUpdate = true)} />
 ```
 
 ## Putting already existing objects into the scene-graph
@@ -181,27 +167,7 @@ return (
     <transformControls />
 ```
 
-If you are using Typescript, it is important to let Typescript be aware of the new elements.
-
-```tsx
-import { extend, ReactThreeFiber } from '@react-three/fiber'
-import { OrbitControls } from 'three-stdlib'
-
-extend({ OrbitControls })
-
-declare global {
-  namespace JSX {
-    interface IntrinsicElements {
-      orbitControls: ReactThreeFiber.Object3DNode<
-        OrbitControls,
-        typeof OrbitControls
-      >
-    }
-  }
-}
-```
-
-
+If you're using TypeScript, you'll also need to [extend the JSX namespace](/react-three-fiber/tutorials/typescript#extending-jsx-intrinsic-elements).
 
 ## Disposal