lunchboxjs 0.2.1001-beta.0 → 0.2.1001-beta.301

package/dist/lunchboxjs.js

@@ -124,242 +124,11 @@
       return node;
     }
 
-    const globalsInjectionKey = Symbol();
-    const updateGlobalsInjectionKey = Symbol();
-    const setCustomRenderKey = Symbol();
-    const clearCustomRenderKey = Symbol();
-    const beforeRenderKey = Symbol();
-    const onBeforeRenderKey = Symbol();
-    const offBeforeRenderKey = Symbol();
-    const afterRenderKey = Symbol();
-    const onAfterRenderKey = Symbol();
-    const offAfterRenderKey = Symbol();
-    const frameIdKey = Symbol();
-    const watchStopHandleKey = Symbol();
-    const appRootNodeKey = Symbol();
-    const appKey = Symbol();
-    const appRenderersKey = Symbol();
-    const appSceneKey = Symbol();
-    const appCameraKey = Symbol();
-    const startCallbackKey = Symbol();
-
-    const ensuredCamera = () => vue.inject(appCameraKey); // ENSURE RENDERER
-    // ====================
-
-    const ensureRenderer = () => vue.inject(appRenderersKey); // ENSURE SCENE
-    // ====================
-
-    const ensuredScene = () => vue.inject(appSceneKey);
-
-    const interactables = [];
-    const addInteractable = target => {
-      interactables.push(target);
-    };
-    const removeInteractable = target => {
-      const idx = interactables.indexOf(target);
-
-      if (idx !== -1) {
-        interactables.splice(idx, 1);
-      }
-    };
-
-    /** Mouse is down, touch is pressed, etc */
-
-    const inputActive = vue.ref(false);
-
-    // let mouseDownListener: (event: MouseEvent) => void
-    // let mouseUpListener: (event: MouseEvent) => void
-
-    const mousePos = vue.ref({
-      x: Infinity,
-      y: Infinity
-    }); // let autoRaycasterEventsInitialized = false
-    // let frameID: number
-    // export const setupAutoRaycaster = (node: Lunch.Node<THREE.Raycaster>) => {
-    //     const instance = node.instance
-    //     if (!instance) return
-    //     // TODO: inject doesn't work here. replace this raycaster with a component so we can
-    //     // `inject` in `setup`?
-    //     const appLevelGlobals = { dpr: window.devicePixelRatio } //useGlobals()
-    //     // add mouse events once renderer is ready
-    //     let stopWatcher: WatchStopHandle | null = null
-    //     stopWatcher = watch(
-    //         () => ensureRenderer.value,
-    //         (renderer) => {
-    //             // make sure renderer exists
-    //             if (!renderer?.instance) return
-    //             // cancel early if autoraycaster exists
-    //             if (autoRaycasterEventsInitialized) {
-    //                 if (stopWatcher) stopWatcher()
-    //                 return
-    //             }
-    //             // create mouse events
-    //             mouseMoveListener = (evt) => {
-    //                 const screenWidth =
-    //                     (renderer.instance!.domElement.width ?? 1) /
-    //                     appLevelGlobals.dpr
-    //                 const screenHeight =
-    //                     (renderer.instance!.domElement.height ?? 1) /
-    //                     appLevelGlobals.dpr
-    //                 mousePos.value.x = (evt.offsetX / screenWidth) * 2 - 1
-    //                 mousePos.value.y = -(evt.offsetY / screenHeight) * 2 + 1
-    //             }
-    //             mouseDownListener = () => (inputActive.value = true)
-    //             mouseUpListener = () => (inputActive.value = false)
-    //             // add mouse events
-    //             renderer.instance.domElement.addEventListener(
-    //                 'mousemove',
-    //                 mouseMoveListener
-    //             )
-    //             renderer.instance.domElement.addEventListener(
-    //                 'mousedown',
-    //                 mouseDownListener
-    //             )
-    //             renderer.instance.domElement.addEventListener(
-    //                 'mouseup',
-    //                 mouseUpListener
-    //             )
-    //             // TODO: add touch events
-    //             // process mouse events asynchronously, whenever the mouse state changes
-    //             watch(
-    //                 () => [inputActive.value, mousePos.value.x, mousePos.value.y],
-    //                 () => {
-    //                     if (frameID) cancelAnimationFrame(frameID)
-    //                     frameID = requestAnimationFrame(() => {
-    //                         autoRaycasterBeforeRender()
-    //                     })
-    //                 }
-    //             )
-    //             // mark complete
-    //             autoRaycasterEventsInitialized = true
-    //             // cancel setup watcher
-    //             if (stopWatcher) {
-    //                 stopWatcher()
-    //             }
-    //         },
-    //         { immediate: true }
-    //     )
-    // }
-    // AUTO-RAYCASTER CALLBACK
-    // ====================
-
-    let currentIntersections = []; // const autoRaycasterBeforeRender = () => {
-    //     // setup
-    //     const raycaster = ensuredRaycaster.value?.instance
-    //     const camera = ensuredCamera.value?.instance
-    //     if (!raycaster || !camera) return
-    //     raycaster.setFromCamera(globals.mousePos.value, camera)
-    //     const intersections = raycaster.intersectObjects(
-    //         interactables.map((v) => v.instance as any as THREE.Object3D)
-    //     )
-    //     let enterValues: Array<Intersection<THREE.Object3D>> = [],
-    //         sameValues: Array<Intersection<THREE.Object3D>> = [],
-    //         leaveValues: Array<Intersection<THREE.Object3D>> = [],
-    //         entering: Array<{
-    //             element: Lunch.Node
-    //             intersection: Intersection<THREE.Object3D>
-    //         }> = [],
-    //         staying: Array<{
-    //             element: Lunch.Node
-    //             intersection: Intersection<THREE.Object3D>
-    //         }> = []
-    //     // intersection arrays
-    //     leaveValues = currentIntersections.map((v) => v.intersection)
-    //     // element arrays
-    //     intersections?.forEach((intersection) => {
-    //         const currentIdx = currentIntersections.findIndex(
-    //             (v) => v.intersection.object === intersection.object
-    //         )
-    //         if (currentIdx === -1) {
-    //             // new intersection
-    //             enterValues.push(intersection)
-    //             const found = interactables.find(
-    //                 (v) => v.instance?.uuid === intersection.object.uuid
-    //             )
-    //             if (found) {
-    //                 entering.push({ element: found, intersection })
-    //             }
-    //         } else {
-    //             // existing intersection
-    //             sameValues.push(intersection)
-    //             const found = interactables.find(
-    //                 (v) => v.instance?.uuid === intersection.object.uuid
-    //             )
-    //             if (found) {
-    //                 staying.push({ element: found, intersection })
-    //             }
-    //         }
-    //         // this is a current intersection, so it won't be in our `leave` array
-    //         const leaveIdx = leaveValues.findIndex(
-    //             (v) => v.object.uuid === intersection.object.uuid
-    //         )
-    //         if (leaveIdx !== -1) {
-    //             leaveValues.splice(leaveIdx, 1)
-    //         }
-    //     })
-    //     const leaving: Array<{
-    //         element: Lunch.Node
-    //         intersection: Intersection<THREE.Object3D>
-    //     }> = leaveValues.map((intersection) => {
-    //         return {
-    //             element: interactables.find(
-    //                 (interactable) =>
-    //                     interactable.instance?.uuid === intersection.object.uuid
-    //             ) as any as Lunch.Node,
-    //             intersection,
-    //         }
-    //     })
-    //     // new interactions
-    //     entering.forEach(({ element, intersection }) => {
-    //         fireEventsFromIntersections({
-    //             element,
-    //             eventKeys: ['onPointerEnter'],
-    //             intersection,
-    //         })
-    //     })
-    //     // unchanged interactions
-    //     staying.forEach(({ element, intersection }) => {
-    //         const eventKeys: Array<Lunch.EventKey> = [
-    //             'onPointerOver',
-    //             'onPointerMove',
-    //         ]
-    //         fireEventsFromIntersections({ element, eventKeys, intersection })
-    //     })
-    //     // exited interactions
-    //     leaving.forEach(({ element, intersection }) => {
-    //         const eventKeys: Array<Lunch.EventKey> = [
-    //             'onPointerLeave',
-    //             'onPointerOut',
-    //         ]
-    //         fireEventsFromIntersections({ element, eventKeys, intersection })
-    //     })
-    //     currentIntersections = ([] as any).concat(entering, staying)
-    // }
-    // utility function for firing multiple callbacks and multiple events on a Lunchbox.Element
-    // const fireEventsFromIntersections = ({
-    //     element,
-    //     eventKeys,
-    //     intersection,
-    // }: {
-    //     element: Lunch.Node
-    //     eventKeys: Array<Lunch.EventKey>
-    //     intersection: Intersection<THREE.Object3D>
-    // }) => {
-    //     if (!element) return
-    //     eventKeys.forEach((eventKey) => {
-    //         if (element.eventListeners[eventKey]) {
-    //             element.eventListeners[eventKey].forEach((cb) => {
-    //                 cb({ intersection })
-    //             })
-    //         }
-    //     })
-    // }
-
     /** Add an event listener to the given node. Also creates the event teardown function and any necessary raycaster/interaction dictionary updates. */
-
     function addEventListener({
       node,
       key,
+      interactables,
       value
     }) {
       // create new records for this key if needed
@@ -375,37 +144,18 @@
       node.eventListeners[key].push(value); // if we need it, let's get/create the main raycaster
 
       if (interactionsRequiringRaycaster.includes(key)) {
-        // we're not using `v` here, we're just making sure the raycaster has been created
-        // TODO: is this necessary?
-        // const v = ensuredRaycaster.value
-        if (node.instance && !interactables.includes(node)) {
-          addInteractable(node);
-          node.eventListenerRemoveFunctions[key].push(() => removeInteractable(node));
-        }
-      } // register click, pointerdown, pointerup
-
-
-      if (key === 'onClick' || key === 'onPointerDown' || key === 'onPointerUp') {
-        const stop = vue.watch(() => inputActive.value, isDown => {
-          const idx = currentIntersections.map(v => v.element).findIndex(v => v.instance && v.instance.uuid === node.instance?.uuid);
-
-          if (idx !== -1) {
-            if (isDown && (key === 'onClick' || key === 'onPointerDown')) {
-              node.eventListeners[key].forEach(func => {
-                func({
-                  intersection: currentIntersections[idx].intersection
-                });
-              });
-            } else if (!isDown && key === 'onPointerUp') {
-              node.eventListeners[key].forEach(func => {
-                func({
-                  intersection: currentIntersections[idx].intersection
-                });
-              });
+        if (node.instance && !interactables.value.includes(node)) {
+          // add to interactables
+          interactables.value.push(node);
+          node.eventListenerRemoveFunctions[key].push(() => {
+            // remove from interactables
+            const idx = interactables.value.indexOf(node);
+
+            if (idx !== -1) {
+              interactables.value.splice(idx, 1);
             }
-          }
-        });
-        node.eventListenerRemoveFunctions[key].push(stop);
+          });
+        }
       }
 
       return node;
@@ -499,6 +249,194 @@
 
     });
 
+    const LunchboxEventHandlers = vue.defineComponent({
+      name: 'LunchboxEventHandlers',
+
+      setup() {
+        const interactables = useLunchboxInteractables();
+        const globals = useGlobals();
+        const mousePos = vue.ref({
+          x: Infinity,
+          y: Infinity
+        });
+        const inputActive = vue.ref(false);
+        let currentIntersections = [];
+        const raycaster = new THREE__namespace.Raycaster(new THREE__namespace.Vector3(), new THREE__namespace.Vector3(0, 0, -1));
+
+        const fireEventsFromIntersections = ({
+          element,
+          eventKeys,
+          intersection
+        }) => {
+          if (!element) return;
+          eventKeys.forEach(eventKey => {
+            if (element.eventListeners[eventKey]) {
+              element.eventListeners[eventKey].forEach(cb => {
+                cb({
+                  intersection
+                });
+              });
+            }
+          });
+        }; // add mouse listener to renderer DOM element when the element is ready
+
+
+        onRendererReady(v => {
+          if (!v?.domElement) return; // we have a DOM element, so let's add mouse listeners
+
+          const {
+            domElement
+          } = v;
+
+          const mouseMoveListener = evt => {
+            const screenWidth = (domElement.width ?? 1) / globals.dpr;
+            const screenHeight = (domElement.height ?? 1) / globals.dpr;
+            mousePos.value.x = evt.offsetX / screenWidth * 2 - 1;
+            mousePos.value.y = -(evt.offsetY / screenHeight) * 2 + 1;
+          };
+
+          const mouseDownListener = () => inputActive.value = true;
+
+          const mouseUpListener = () => inputActive.value = false; // add mouse events
+
+
+          domElement.addEventListener('pointermove', mouseMoveListener);
+          domElement.addEventListener('pointerdown', mouseDownListener);
+          domElement.addEventListener('pointerup', mouseUpListener);
+        });
+        const camera = useCamera();
+
+        const update = () => {
+          const c = camera.value;
+          if (!c) return; // console.log(camera.value)
+
+          raycaster.setFromCamera(mousePos.value, c);
+          const intersections = raycaster.intersectObjects(interactables?.value.map(v => v.instance) ?? []);
+          let leaveValues = [],
+              entering = [],
+              staying = []; // intersection arrays
+
+          leaveValues = currentIntersections.map(v => v.intersection); // element arrays
+
+          intersections?.forEach(intersection => {
+            const currentIdx = currentIntersections.findIndex(v => v.intersection.object === intersection.object);
+
+            if (currentIdx === -1) {
+              const found = interactables?.value.find(v => v.instance?.uuid === intersection.object.uuid);
+
+              if (found) {
+                entering.push({
+                  element: found,
+                  intersection
+                });
+              }
+            } else {
+              const found = interactables?.value.find(v => v.instance?.uuid === intersection.object.uuid);
+
+              if (found) {
+                staying.push({
+                  element: found,
+                  intersection
+                });
+              }
+            } // this is a current intersection, so it won't be in our `leave` array
+
+
+            const leaveIdx = leaveValues.findIndex(v => v.object.uuid === intersection.object.uuid);
+
+            if (leaveIdx !== -1) {
+              leaveValues.splice(leaveIdx, 1);
+            }
+          });
+          const leaving = leaveValues.map(intersection => {
+            return {
+              element: interactables?.value.find(interactable => interactable.instance?.uuid === intersection.object.uuid),
+              intersection
+            };
+          }); // new interactions
+
+          entering.forEach(({
+            element,
+            intersection
+          }) => {
+            fireEventsFromIntersections({
+              element,
+              eventKeys: ['onPointerEnter'],
+              intersection
+            });
+          }); // unchanged interactions
+
+          staying.forEach(({
+            element,
+            intersection
+          }) => {
+            const eventKeys = ['onPointerOver', 'onPointerMove'];
+            fireEventsFromIntersections({
+              element,
+              eventKeys,
+              intersection
+            });
+          }); // exited interactions
+
+          leaving.forEach(({
+            element,
+            intersection
+          }) => {
+            const eventKeys = ['onPointerLeave', 'onPointerOut'];
+            fireEventsFromIntersections({
+              element,
+              eventKeys,
+              intersection
+            });
+          });
+          currentIntersections = [].concat(entering, staying);
+        }; // update function
+
+
+        onBeforeRender(update);
+
+        const teardown = () => offBeforeRender(update);
+
+        vue.onBeforeUnmount(teardown);
+        const clickEventKeys = ['onClick', 'onPointerDown', 'onPointerUp'];
+        vue.watch(inputActive, isDown => {
+          // run raycaster on click (necessary when `update` is not automatically called,
+          // for example in `updateSource` functions)
+          update(); // meshes with multiple intersections receive multiple callbacks by default -
+          // let's make it so they only receive one callback of each type per frame.
+          // (ie usually when you click on a mesh, you expect only one click event to fire, even
+          // if there are technically multiple intersections with that mesh)
+
+          const uuidsInteractedWithThisFrame = [];
+          currentIntersections.forEach(v => {
+            clickEventKeys.forEach(key => {
+              const id = v.element.uuid + key;
+
+              if (isDown && (key === 'onClick' || key === 'onPointerDown')) {
+                if (!uuidsInteractedWithThisFrame.includes(id)) {
+                  v.element.eventListeners[key]?.forEach(cb => cb({
+                    intersection: v.intersection
+                  }));
+                  uuidsInteractedWithThisFrame.push(id);
+                }
+              } else if (!isDown && key === 'onPointerUp') {
+                if (!uuidsInteractedWithThisFrame.includes(id)) {
+                  v.element.eventListeners[key]?.forEach(cb => cb({
+                    intersection: v.intersection
+                  }));
+                  uuidsInteractedWithThisFrame.push(id);
+                }
+              }
+            });
+          });
+        }); // return arbitrary object to ensure instantiation
+        // TODO: why can't we return a <raycaster/> here?
+
+        return () => vue.createVNode(vue.resolveComponent("object3D"), null, null);
+      }
+
+    });
+
     /** fixed & fill styling for container */
 
     const fillStyle = position => {
@@ -551,9 +489,10 @@
 
         if (props.r3f && THREE__namespace?.ColorManagement) {
           THREE__namespace.ColorManagement.legacyMode = false;
-        } // MOUNT
-        // ====================
+        }
 
+        const interactables = useLunchboxInteractables(); // MOUNT
+        // ====================
 
         vue.onMounted(async () => {
           // canvas needs to exist (or user needs to handle it on their own)
@@ -589,23 +528,17 @@
           updateGlobals?.({
             dpr
           });
-          console.log(1);
 
           while (!renderer.value?.$el?.instance && // TODO: remove `as any`
           !renderer.value?.component?.ctx.$el?.instance) {
-            console.log(2);
             await new Promise(r => requestAnimationFrame(r));
           }
 
-          console.log(3);
-
           while (!scene.value?.$el?.instance && // TODO: remove `as any`
           !scene.value?.component?.ctx.$el?.instance) {
-            console.log(4);
             await new Promise(r => requestAnimationFrame(r));
           }
 
-          console.log(5);
           const normalizedRenderer = renderer.value?.$el?.instance ?? renderer.value?.component?.ctx.$el?.instance;
           normalizedRenderer.setPixelRatio(globals.dpr);
           const normalizedScene = scene.value?.$el?.instance ?? scene.value?.component?.ctx.$el?.instance;
@@ -675,7 +608,37 @@
         // ====================
 
         const containerFillStyle = props.sizePolicy === 'container' ? 'static' : 'absolute';
-        const canvasFillStyle = props.sizePolicy === 'container' ? 'static' : 'fixed';
+        const canvasFillStyle = props.sizePolicy === 'container' ? 'static' : 'fixed'; // REACTIVE CUSTOM CAMERAS
+        // ====================
+        // find first camera with `type.name` property
+        // (which indicates a Lunch.Node)
+
+        const activeCamera = vue.computed(() => {
+          const output = context.slots?.camera?.().find(c => c.type?.name);
+
+          if (output) {
+            return output;
+          }
+
+          return output;
+        }); // TODO: make custom cameras reactive
+
+        vue.watch(activeCamera, async (newVal, oldVal) => {
+          // console.log('got camera', newVal)
+          if (newVal && newVal?.props?.key !== oldVal?.props?.key) {
+            // TODO: remove cast
+            camera.value = newVal; // TODO: why isn't this updating app camera?
+            // const el = await waitFor(() => newVal.el)
+            // console.log(el)
+            // camera.value = el
+            // console.log(newVal.uuid)
+            // updateGlobals?.({ camera: el })
+          }
+        }, {
+          immediate: true
+        }); // RENDER FUNCTION
+        // ====================
+
         return () => vue.createVNode(vue.Fragment, null, [context.slots?.renderer?.()?.length ? // TODO: remove `as any` cast
         renderer.value = context.slots?.renderer?.()[0] : // ...otherwise, add canvas...
         vue.createVNode(vue.Fragment, null, [vue.createVNode("div", {
@@ -705,13 +668,13 @@
         }, {
           default: () => [context.slots?.default?.()]
         }), context.slots?.camera?.()?.length ? // TODO: remove `any` cast
-        camera.value = context.slots?.camera?.()[0] : props.ortho || props.orthographic ? vue.createVNode(vue.resolveComponent("orthographicCamera"), vue.mergeProps({
+        camera.value : props.ortho || props.orthographic ? vue.createVNode(vue.resolveComponent("orthographicCamera"), vue.mergeProps({
           "ref": camera,
           "args": props.cameraArgs ?? []
         }, consolidatedCameraProperties), null) : vue.createVNode(vue.resolveComponent("perspectiveCamera"), vue.mergeProps({
           "ref": camera,
           "args": props.cameraArgs ?? [props.r3f ? 75 : 45, 0.5625, 1, 1000]
-        }, consolidatedCameraProperties), null)]);
+        }, consolidatedCameraProperties), null), interactables?.value.length && vue.createVNode(LunchboxEventHandlers, null, null)]);
       }
 
     });
@@ -726,7 +689,7 @@
     'light', 'spotLightShadow', 'spotLight', 'pointLight', 'rectAreaLight', 'hemisphereLight', 'directionalLightShadow', 'directionalLight', 'ambientLight', 'lightShadow', 'ambientLightProbe', 'hemisphereLightProbe', 'lightProbe', // textures
     'texture', 'videoTexture', 'dataTexture', 'dataTexture3D', 'compressedTexture', 'cubeTexture', 'canvasTexture', 'depthTexture', // Texture loaders
     'textureLoader', // misc
-    'group', 'catmullRomCurve3', 'points', // helpers
+    'group', 'catmullRomCurve3', 'points', 'raycaster', // helpers
     'cameraHelper', // cameras
     'camera', 'perspectiveCamera', 'orthographicCamera', 'cubeCamera', 'arrayCamera', // renderers
     'webGLRenderer'
@@ -761,7 +724,6 @@
     arrowHelper: ArrowHelperProps
     axesHelper: AxesHelperProps
       // misc
-    raycaster: RaycasterProps
     vector2: Vector2Props
     vector3: Vector3Props
     vector4: Vector4Props
@@ -778,7 +740,7 @@
     */
     ];
 
-    const catalogue = {};
+    const catalogue = {}; // component creation utility
 
     const createComponent$1 = tag => vue.defineComponent({
       inheritAttrs: false,
@@ -1174,9 +1136,25 @@
       return item?.minidomType === 'RendererNode';
     }
 
-    // let watchStopHandle: WatchStopHandle
-    // export const beforeRender = [] as Lunch.UpdateCallback[]
-    // export const afterRender = [] as Lunch.UpdateCallback[]
+    const globalsInjectionKey = Symbol();
+    const updateGlobalsInjectionKey = Symbol();
+    const setCustomRenderKey = Symbol();
+    const clearCustomRenderKey = Symbol();
+    const beforeRenderKey = Symbol();
+    const onBeforeRenderKey = Symbol();
+    const offBeforeRenderKey = Symbol();
+    const afterRenderKey = Symbol();
+    const onAfterRenderKey = Symbol();
+    const offAfterRenderKey = Symbol();
+    const frameIdKey = Symbol();
+    const watchStopHandleKey = Symbol();
+    const appRootNodeKey = Symbol();
+    const appKey = Symbol();
+    const appRenderersKey = Symbol();
+    const appSceneKey = Symbol();
+    const appCameraKey = Symbol();
+    const lunchboxInteractables = Symbol();
+    const startCallbackKey = Symbol();
 
     const requestUpdate = opts => {
       if (typeof opts.app.config.globalProperties.lunchbox.frameId === 'number') {
@@ -1211,20 +1189,19 @@
       const {
         app,
         renderer,
-        scene,
-        camera
+        scene
       } = opts; // BEFORE RENDER
 
       app.config.globalProperties.lunchbox.beforeRender.forEach(cb => {
         cb?.(opts);
       }); // RENDER
 
-      if (renderer && scene && camera) {
+      if (renderer && scene && opts.app.config.globalProperties.lunchbox.camera) {
         if (app.customRender) {
           app.customRender(opts);
         } else {
-          renderer.render(vue.toRaw(scene), // opts.app.config.globalProperties.lunchbox.camera!
-          vue.toRaw(camera));
+          renderer.render(vue.toRaw(scene), opts.app.config.globalProperties.lunchbox.camera // toRaw(camera)
+          );
         }
       } // AFTER RENDER
 
@@ -1234,97 +1211,92 @@
       });
     }; // before render
     // ====================
-    // TODO: document
+
+    /** Obtain callback methods for `onBeforeRender` and `offBeforeRender`. Usually used internally by Lunchbox. */
 
     const useBeforeRender = () => {
       return {
         onBeforeRender: vue.inject(onBeforeRenderKey),
         offBeforeRender: vue.inject(offBeforeRenderKey)
       };
-    }; // TODO: document
+    };
+    /** Run a function before every render.
+     *
+     * Note that if `updateSource` is set in the Lunchbox wrapper component, this will **only** run
+     * before a render triggered by that `updateSource`. Normally, the function should run every frame.
+     */
 
     const onBeforeRender = (cb, index = Infinity) => {
       useBeforeRender().onBeforeRender?.(cb, index);
-    }; // TODO: document
+    };
+    /** Remove a function from the `beforeRender` callback list. Useful for tearing down functions added
+     * by `onBeforeRender`.
+     */
 
     const offBeforeRender = cb => {
       useBeforeRender().offBeforeRender?.(cb);
     }; // after render
     // ====================
-    // TODO: document
+
+    /** Obtain callback methods for `onAfterRender` and `offAfterRender`. Usually used internally by Lunchbox. */
 
     const useAfterRender = () => {
       return {
         onAfterRender: vue.inject(onBeforeRenderKey),
         offAfterRender: vue.inject(offBeforeRenderKey)
       };
-    }; // TODO: document
+    };
+    /** Run a function after every render.
+     *
+     * Note that if `updateSource` is set in the Lunchbox wrapper component, this will **only** run
+     * after a render triggered by that `updateSource`. Normally, the function should run every frame.
+     */
 
     const onAfterRender = (cb, index = Infinity) => {
       useBeforeRender().onBeforeRender?.(cb, index);
-    }; // TODO: document
+    };
+    /** Remove a function from the `afterRender` callback list. Useful for tearing down functions added
+     * by `onAfterRender`.
+     */
 
     const offAfterRender = cb => {
       useBeforeRender().offBeforeRender?.(cb);
-    }; // export const onAfterRender = (cb: Lunch.UpdateCallback, index = Infinity) => {
-    //     if (index === Infinity) {
-    //         afterRender.push(cb)
-    //     } else {
-    //         afterRender.splice(index, 0, cb)
-    //     }
-    // }
-    // export const offAfterRender = (cb: Lunch.UpdateCallback | number) => {
-    //     if (isFinite(cb as number)) {
-    //         afterRender.splice(cb as number, 1)
-    //     } else {
-    //         const idx = afterRender.findIndex((v) => v == cb)
-    //         afterRender.splice(idx, 1)
-    //     }
-    // }
-    // TODO: document
+    };
+    /** Obtain a function used to cancel the current update frame. Use `cancelUpdate` if you wish
+     * to immediately invoke the cancellation function. Usually used internally by Lunchbox.
+     */
 
     const useCancelUpdate = () => {
       const frameId = vue.inject(frameIdKey);
       return () => {
         if (frameId !== undefined) cancelAnimationFrame(frameId);
       };
-    }; // TODO: document
+    };
+    /** Cancel the current update frame. Usually used internally by Lunchbox. */
 
     const cancelUpdate = () => {
       useCancelUpdate()?.();
-    }; // TODO: document
+    };
+    /** Obtain a function used to cancel an update source. Use `cancelUpdateSource` if you wish to
+     * immediately invoke the cancellation function. Usually used internally by Lunchbox.
+     */
 
     const useCancelUpdateSource = () => {
       const cancel = vue.inject(watchStopHandleKey);
       return () => cancel?.();
-    }; // TODO: document
+    };
+    /** Cancel an update source. Usually used internally by Lunchbox. */
 
     const cancelUpdateSource = () => {
       useCancelUpdateSource()?.();
     };
 
-    /** Update the given node so all of its props are current. */
-
-    function updateAllObjectProps({
-      node
-    }) {
-      // set props
-      const props = node.props || {};
-      let output = node;
-      Object.keys(props).forEach(key => {
-        output = updateObjectProp({
-          node,
-          key,
-          value: props[key]
-        });
-      });
-      return output;
-    }
     /** Update a single prop on a given node. */
 
     function updateObjectProp({
       node,
       key,
+      interactables,
       value
     }) {
       // handle and return early if prop is an event
@@ -1333,6 +1305,7 @@
         return addEventListener({
           node,
           key,
+          interactables,
           value
         });
       } // update THREE property
@@ -1363,6 +1336,7 @@
         const fullPath = [nestedProperty, finalKey].filter(Boolean).join('.');
         liveProperty = liveProperty = lodash.get(target, fullPath);
       } // change property
+      // first, save as array in case we need to spread it
 
 
       if (liveProperty && lodash.isNumber(value) && liveProperty.setScalar) {
@@ -1373,14 +1347,24 @@
         const nextValueAsArray = Array.isArray(value) ? value : [value];
         target[finalKey].set(...nextValueAsArray);
       } else if (typeof liveProperty === 'function') {
-        // if property is a function, let's try calling it
-        liveProperty.bind(node.instance)(...value); // pass the result to the parent
+        // some function properties are set rather than called, so let's handle them
+        if (finalKey.toLowerCase() === 'onbeforerender' || finalKey.toLowerCase() === 'onafterrender') {
+          target[finalKey] = value;
+        } else {
+          if (!Array.isArray(value)) {
+            throw new Error('Arguments on a declarative method must be wrapped in an array.\nWorks:\n<example :methodCall="[256]" />\nDoesn\'t work:\n<example :methodCall="256" />');
+          } // if property is a function, let's try calling it
+
+
+          liveProperty.bind(node.instance)(...value);
+        } // pass the result to the parent
         // const parent = node.parentNode
         // if (parent) {
         //     const parentAsLunchboxNode = parent as Lunchbox.Node
         //     parentAsLunchboxNode.attached[finalKey] = result
         //         ; (parentAsLunchboxNode.instance as any)[finalKey] = result
         // }
+
       } else if (lodash.get(target, finalKey, undefined) !== undefined) {
         // blank strings evaluate to `true`
         // <mesh castShadow receiveShadow /> will work the same as
@@ -1588,101 +1572,133 @@
         Elements are `create`d from the outside in, then `insert`ed from the inside out.
     */
 
-    const nodeOps = {
-      createElement,
-
-      createText(text) {
-        return createTextNode({
-          text
-        });
-      },
-
-      createComment(text) {
-        return createCommentNode({
-          text
-        });
-      },
-
-      insert,
+    const createNodeOps = () => {
+      // APP-LEVEL GLOBALS
+      // ====================
+      // These need to exist at the app level in a place where the node ops can access them.
+      // It'd be better to set these via `app.provide` at app creation, but the node ops need access
+      // to these values before the app is instantiated, so this is the next-best place for them to exist.
+      const interactables = vue.ref([]); // NODE OPS
+      // ====================
 
-      nextSibling(node) {
-        const result = node.nextSibling; // console.log('found', result)
+      const nodeOps = {
+        createElement,
 
-        if (!result) return null;
-        return result;
-      },
-
-      parentNode(node) {
-        const result = node.parentNode;
-        if (!result) return null;
-        return result;
-      },
+        createText(text) {
+          return createTextNode({
+            text
+          });
+        },
 
-      patchProp(node, key, prevValue, nextValue) {
-        if (isLunchboxDomComponent(node)) {
-          // handle DOM node
-          if (key === 'style') {
-            // special handling for style
-            Object.keys(nextValue).forEach(k => {
-              node.domElement.style[k] = nextValue[k];
-            });
-          } else {
-            node.domElement.setAttribute(key, nextValue);
-          }
+        createComment(text) {
+          return createCommentNode({
+            text
+          });
+        },
+
+        insert,
+
+        nextSibling(node) {
+          const result = node.nextSibling;
+          if (!result) return null;
+          return result;
+        },
+
+        parentNode(node) {
+          const result = node.parentNode;
+          if (!result) return null;
+          return result;
+        },
+
+        patchProp(node, key, prevValue, nextValue) {
+          if (isLunchboxDomComponent(node)) {
+            // handle DOM node
+            if (key === 'style') {
+              // special handling for style
+              Object.keys(nextValue).forEach(k => {
+                node.domElement.style[k] = nextValue[k];
+              });
+            } else {
+              node.domElement.setAttribute(key, nextValue);
+            }
 
-          return;
-        } // ignore if root node, or Lunchbox internal prop
+            return;
+          } // ignore if root node, or Lunchbox internal prop
 
 
-        if (isLunchboxRootNode(node) || key.startsWith('$')) {
-          return;
-        } // otherwise, update prop
+          if (isLunchboxRootNode(node) || key.startsWith('$')) {
+            return;
+          } // otherwise, update prop
 
 
-        updateObjectProp({
-          node: node,
-          key,
-          value: nextValue
-        });
-      },
+          updateObjectProp({
+            node: node,
+            key,
+            interactables,
+            value: nextValue
+          });
+        },
 
-      remove,
+        remove,
 
-      setElementText() {// noop
-      },
+        setElementText() {// noop
+        },
 
-      setText() {// noop
-      }
+        setText() {// noop
+        }
 
+      };
+      return {
+        nodeOps,
+        interactables
+      };
     };
 
-    /** The current camera. Often easier to use `useCamera` instead of this. */
-    // TODO: update docs
+    /** The current camera as a computed value. */
 
-    const camera = ensuredCamera; // TODO: update docs
+    const useCamera = () => vue.inject(appCameraKey);
+    /** Run a function using the current camera when it's present. */
 
-    const useCamera = () => ensuredCamera();
-    /** The current renderer as a computed value. Often easier to use `useRenderer` instead of this. */
+    const onCameraReady = cb => {
+      const stopWatch = vue.watch(useCamera(), newVal => {
+        if (newVal) {
+          cb(newVal);
+          stopWatch();
+        }
+      }, {
+        immediate: true
+      });
+    };
+    /** The current renderer as a computed value. */
 
-    const renderer = ensureRenderer;
+    const useRenderer = () => vue.inject(appRenderersKey);
     /** Run a function using the current renderer when it's present. */
 
-    const useRenderer = () => ensureRenderer();
-    /** The current scene. Often easier to use `useScene` instead of this. */
-    // TODO: update docs
+    const onRendererReady = cb => {
+      const stopWatch = vue.watch(useRenderer(), newVal => {
+        if (newVal) {
+          cb(newVal);
+          stopWatch();
+        }
+      }, {
+        immediate: true
+      });
+    };
+    /** The current scene as a computed value. */
 
-    const scene = ensuredScene;
+    const useScene = () => vue.inject(appSceneKey);
     /** Run a function using the current scene when it's present. */
-    // TODO: update docs
 
-    function useScene(callback) {
-      return vue.watch(scene, newVal => {
-        if (!newVal) return;
-        callback(newVal.value);
+    const onSceneReady = cb => {
+      const stopWatch = vue.watch(useScene(), newVal => {
+        if (newVal) {
+          cb(newVal);
+          stopWatch();
+        }
       }, {
         immediate: true
       });
-    } // CUSTOM RENDER SUPPORT
+    }; // CUSTOM RENDER SUPPORT
     // ====================
 
     /** Set a custom render function, overriding the Lunchbox app's default render function.
@@ -1739,14 +1755,15 @@
 
     const updateGlobals = newValue => {
       useUpdateGlobals()?.(newValue);
-    }; // TODO: document
-
-    const useRootNode = () => vue.inject(appRootNodeKey); // TODO: document
+    };
+    /** Use the current Lunchbox app. Usually used internally by Lunchbox. */
 
-    const useApp = () => vue.inject(appKey); // TODO: document
+    const useApp = () => vue.inject(appKey);
+    /** Obtain a list of the start callback functions. Usually used internally by Lunchbox. */
 
-    const useStartCallbacks = () => vue.inject(startCallbackKey); //[] as Lunch.UpdateCallback[]
-    // TODO: document
+    const useStartCallbacks = () => vue.inject(startCallbackKey);
+    /** Run a given callback once when the Lunchbox app starts. Include an index to
+     * splice the callback at that index in the callback queue. */
 
     const onStart = (cb, index = Infinity) => {
       const callbacks = useStartCallbacks();
@@ -1756,11 +1773,21 @@
       } else {
         callbacks?.splice(index, 0, cb);
       }
-    }; // CREATE APP
+    };
+    /** Obtain a list of interactable objects (registered via onClick, onHover, etc events). Usually used internally by Lunchbox. */
+
+    const useLunchboxInteractables = () => vue.inject(lunchboxInteractables); // CREATE APP
     // ====================
 
     const createApp = root => {
-      const app = vue.createRenderer(nodeOps).createApp(root); // register all components
+      const {
+        nodeOps,
+        interactables
+      } = createNodeOps();
+      const app = vue.createRenderer(nodeOps).createApp(root); // provide Lunchbox interaction handlers flag (modified when user references events via
+      // @click, etc)
+
+      app.provide(lunchboxInteractables, interactables); // register all components
       // ====================
 
       Object.keys(components).forEach(key => {
@@ -1911,7 +1938,6 @@
     };
 
     exports.addEventListener = addEventListener;
-    exports.addInteractable = addInteractable;
     exports.afterRenderKey = afterRenderKey;
     exports.appCameraKey = appCameraKey;
     exports.appKey = appKey;
@@ -1919,7 +1945,6 @@
     exports.appRootNodeKey = appRootNodeKey;
     exports.appSceneKey = appSceneKey;
     exports.beforeRenderKey = beforeRenderKey;
-    exports.camera = camera;
     exports.cancelUpdate = cancelUpdate;
     exports.cancelUpdateSource = cancelUpdateSource;
     exports.clearCustomRender = clearCustomRender;
@@ -1929,19 +1954,13 @@
     exports.createDomNode = createDomNode;
     exports.createNode = createNode;
     exports.createTextNode = createTextNode;
-    exports.currentIntersections = currentIntersections;
-    exports.ensureRenderer = ensureRenderer;
-    exports.ensuredCamera = ensuredCamera;
-    exports.ensuredScene = ensuredScene;
     exports.extend = extend;
     exports.find = find;
     exports.frameIdKey = frameIdKey;
     exports.globalsInjectionKey = globalsInjectionKey;
-    exports.inputActive = inputActive;
     exports.instantiateThreeObject = instantiateThreeObject;
-    exports.interactables = interactables;
     exports.isMinidomNode = isMinidomNode;
-    exports.mousePos = mousePos;
+    exports.lunchboxInteractables = lunchboxInteractables;
     exports.nestedPropertiesToCheck = nestedPropertiesToCheck;
     exports.offAfterRender = offAfterRender;
     exports.offAfterRenderKey = offAfterRenderKey;
@@ -1951,15 +1970,14 @@
     exports.onAfterRenderKey = onAfterRenderKey;
     exports.onBeforeRender = onBeforeRender;
     exports.onBeforeRenderKey = onBeforeRenderKey;
+    exports.onCameraReady = onCameraReady;
+    exports.onRendererReady = onRendererReady;
+    exports.onSceneReady = onSceneReady;
     exports.onStart = onStart;
-    exports.removeInteractable = removeInteractable;
-    exports.renderer = renderer;
-    exports.scene = scene;
     exports.setCustomRender = setCustomRender;
     exports.setCustomRenderKey = setCustomRenderKey;
     exports.startCallbackKey = startCallbackKey;
     exports.update = update;
-    exports.updateAllObjectProps = updateAllObjectProps;
     exports.updateGlobals = updateGlobals;
     exports.updateGlobalsInjectionKey = updateGlobalsInjectionKey;
     exports.updateObjectProp = updateObjectProp;
@@ -1971,8 +1989,8 @@
     exports.useCancelUpdateSource = useCancelUpdateSource;
     exports.useCustomRender = useCustomRender;
     exports.useGlobals = useGlobals;
+    exports.useLunchboxInteractables = useLunchboxInteractables;
     exports.useRenderer = useRenderer;
-    exports.useRootNode = useRootNode;
     exports.useScene = useScene;
     exports.useStartCallbacks = useStartCallbacks;
     exports.useUpdateGlobals = useUpdateGlobals;