feat: ShadowDOM composition edge case bugs are fixed, and thus it is …

…finally and officially fully supported!

# Massive cleanup:

Factor out some old code from a few years back, making the tree structure
easier to understand and less error prone. This allowed us to make more sense
of the ShadowDOM composition stuff and to be able to finally polish the
remaining rough edges. 🎉

# BREAKING CHANGES:

To clean up the code and finish ShadowDOM composition, we removed some APIs:

- Removed the TreeNode APIs `add`, `addChildren`, `removeNode`,
  `removeChildren`, `removeAllChildren`, `childCount`, `subnodes`, and
  `parent`. You must now simply use the actual DOM APIs like `append`,
  `appendChild`, `remove`, `removeChild`, `parentElement`, `children`, etc.
- Removed `Scene.mount()` and `Scene.unmount()`. Just use regular DOM APIs to
  append or remove a `Scene` from the DOM.

Unrelated to ShadowDOM composition, we cleaned up some other things too:

- Removed the old `imperativeCounterpart` property.
- Renamed `_render()` to `update()` because it is called from the outside in
  the `Motor` class.

The stuff we removed existed for two reasons:

1. The TreeNode APIs (`add`, `removeChild`, etc) existed from before we were
   using Custom Elements, just plain JS objects, so we needed our own tree API
   in order to create our scene graph
2. When we added support for Custom Elements, we initially had two trees, the
   DOM tree and our own scene graph tree. Our tree had all the logic and the
   DOM tree was merely an interface that proxied data to/from our tree. The
   idea was that a plain JS user could use our tree APIs in non-DOM
   environments, and DOM users could use the custom element tree. We have since
   merged the two trees so our LUME objects are also the custom elements
   themselves. With removal of our old TreeNode APIs, we can later support
   non-DOM environments by instead polyfilling some of the DOM tree APIs as
   needed in those environments.

# Other new features:

feat: Added new APIs that are LUME-specific and complementary to DOM APIs:

- `.lumeParent` - Get the parent element of the current LUME element only if
  the parent is a LUME element. Returns null if there is no DOM parent, or if
  the DOM parent is not a LUME element.
- `.lumeChildren` - Get the child LUME elements of the current LUME element.
  This ignores any DOM children that are not LUME elements; those elements will
  not be included in the result array.
- `.lumeChildCount` - Get the count of child LUME elements of the current LUME
  element. This ignores child elements that are not LUME elements.
- `composedLumeParent` - The composed parent LUME element (based on the composed tree) of the current LUME element.
- `composedLumeChildren` - The composed child LUME elements (based on the composed tree) of the current LUME element.
- `.traverseSceneGraph(visitorFn)` - Traverses the composed tree of LUME
  elements in pre-order. The tree that this traverses is the tree that is
  composed from the hierarchy of ShadowRoot trees with elements distributed
  through those trees via slot elements.

In these new APIs, non-LUME elements are ignored similarly to how some regular
DOM APIs ignore text nodes (`.children`, `.parentElement`, `.assignedElements`,
etc). To certain LUME elements like `<lume-node>` or `<lume-mixed-plane>`,
non-LUME HTML elements and text nodes are merely content that render on their
rectangular flat surface, and those non-LUME elements are not part of the
hierarchy of 3D objects.

packages/lume/docs/examples/autolayout-imperative.md

@@ -38,13 +38,13 @@
                   webgl: true,
               })
 
-              scene.mount(document.body)
+              document.body.append(scene)
 
               const ambientLight = new AmbientLight().set({
                   intensity: 0.1,
               })
 
-              scene.add(ambientLight)
+              scene.append(ambientLight)
 
               const pointLight = new PointLight().set({
                   color: "white",
@@ -54,7 +54,7 @@
                   intensity: "0.5",
               })
 
-              scene.add(pointLight)
+              scene.append(pointLight)
 
               const sphere = new Sphere().set({
                   size: [10, 10, 10],
@@ -66,7 +66,7 @@
               })
 
               sphere.setAttribute('has', 'basic-material')
-              pointLight.add(sphere)
+              pointLight.append(sphere)
 
               const vfl1 = \`
                   //viewport aspect-ratio:3/1 max-height:300
@@ -131,7 +131,7 @@
               child5.textContent = text
               layout.addToLayout(child5, 'child5')
 
-              scene.add(layout); // add layout to the scene
+              scene.append(layout);
 
               layout.size = (x,y,z,t) => [ 600+200*Math.sin(t/1000), 400+200*Math.sin(t/1000), z ]
 

packages/lume/docs/examples/ripple-flip.md

@@ -61,7 +61,7 @@
       perspective: 800
     })
 
-    scene.mount('body')
+    document.body.append(scene)
 
     const gridSizeX = 13
     const gridSizeY = 13
@@ -75,7 +75,7 @@
       position: {z: -600},
     })
 
-    scene.add(grid)
+    scene.append(grid)
 
     console.log('grid size', grid.calculatedSize)
 
@@ -100,7 +100,7 @@
         node.style.background = ''+mainColor.clone().darken(10)
         node.style.border = '1px solid ' + mainColor.clone().darken(35)
 
-        grid.add(node)
+        grid.append(node)
       }
     }
 

packages/lume/docs/guide/install.md

@@ -302,8 +302,8 @@ code:
   })
 
   node.style.background = 'cornflowerblue'
-  scene.add(node)
-  scene.mount(document.body)
+  scene.append(node)
+  document.body.append(scene)
   node.rotation = (x, y, z) => [x, y + 1, z]
 
   // The code outputs these elements to the DOM:
@@ -367,8 +367,8 @@ code:
   })
 
   node.style.background = 'cornflowerblue'
-  scene.add(node)
-  scene.mount(document.body)
+  scene.append(node)
+  document.body.append(scene)
   node.rotation = (x, y, z) => [x, y + 1, z]
 
   // The code outputs these elements to the DOM:

packages/lume/docs/workflows.md

@@ -131,8 +131,8 @@ const node = new Node({
 
 node.innerHTML = '<div>Hello 3D</div>'
 
-scene.add(node)
-scene.mount(document.body)
+scene.append(node)
+document.body.append(scene)
 
 node.rotation = (x, y, z) => [x, ++y, z]
 ```