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

package/dist/lunchboxjs.module.js

@@ -1,4 +1,4 @@
-import { isRef, isVNode, inject, ref, watch, toRaw, defineComponent, createVNode, resolveComponent, reactive, onMounted, onBeforeUnmount, Fragment, mergeProps, h, createRenderer, computed } from 'vue';
+import { isRef, isVNode, toRaw, defineComponent, createVNode, resolveComponent, ref, onBeforeUnmount, watch, reactive, onMounted, computed, Fragment, mergeProps, h, inject, createRenderer } from 'vue';
 import * as THREE from 'three';
 import { get, isNumber, set } from 'lodash';
 
@@ -102,242 +102,11 @@ function createNode(options = {}, props = {}) {
   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 = () => inject(appCameraKey); // ENSURE RENDERER
-// ====================
-
-const ensureRenderer = () => inject(appRenderersKey); // ENSURE SCENE
-// ====================
-
-const ensuredScene = () => 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 = ref(false);
-
-// let mouseDownListener: (event: MouseEvent) => void
-// let mouseUpListener: (event: MouseEvent) => void
-
-const mousePos = 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
@@ -353,37 +122,18 @@ function addEventListener({
   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 = 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;
@@ -477,6 +227,194 @@ const LunchboxScene = defineComponent({
 
 });
 
+const LunchboxEventHandlers = defineComponent({
+  name: 'LunchboxEventHandlers',
+
+  setup() {
+    const interactables = useLunchboxInteractables();
+    const globals = useGlobals();
+    const mousePos = ref({
+      x: Infinity,
+      y: Infinity
+    });
+    const inputActive = ref(false);
+    let currentIntersections = [];
+    const raycaster = new THREE.Raycaster(new THREE.Vector3(), new THREE.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);
+
+    onBeforeUnmount(teardown);
+    const clickEventKeys = ['onClick', 'onPointerDown', 'onPointerUp'];
+    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 () => createVNode(resolveComponent("object3D"), null, null);
+  }
+
+});
+
 /** fixed & fill styling for container */
 
 const fillStyle = position => {
@@ -529,9 +467,10 @@ const LunchboxWrapper = defineComponent({
 
     if (props.r3f && THREE?.ColorManagement) {
       THREE.ColorManagement.legacyMode = false;
-    } // MOUNT
-    // ====================
+    }
 
+    const interactables = useLunchboxInteractables(); // MOUNT
+    // ====================
 
     onMounted(async () => {
       // canvas needs to exist (or user needs to handle it on their own)
@@ -567,23 +506,17 @@ const LunchboxWrapper = defineComponent({
       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;
@@ -653,7 +586,37 @@ const LunchboxWrapper = defineComponent({
     // ====================
 
     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 = computed(() => {
+      const output = context.slots?.camera?.().find(c => c.type?.name);
+
+      if (output) {
+        return output;
+      }
+
+      return output;
+    }); // TODO: make custom cameras reactive
+
+    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 () => createVNode(Fragment, null, [context.slots?.renderer?.()?.length ? // TODO: remove `as any` cast
     renderer.value = context.slots?.renderer?.()[0] : // ...otherwise, add canvas...
     createVNode(Fragment, null, [createVNode("div", {
@@ -683,13 +646,13 @@ const LunchboxWrapper = defineComponent({
     }, {
       default: () => [context.slots?.default?.()]
     }), context.slots?.camera?.()?.length ? // TODO: remove `any` cast
-    camera.value = context.slots?.camera?.()[0] : props.ortho || props.orthographic ? createVNode(resolveComponent("orthographicCamera"), mergeProps({
+    camera.value : props.ortho || props.orthographic ? createVNode(resolveComponent("orthographicCamera"), mergeProps({
       "ref": camera,
       "args": props.cameraArgs ?? []
     }, consolidatedCameraProperties), null) : createVNode(resolveComponent("perspectiveCamera"), mergeProps({
       "ref": camera,
       "args": props.cameraArgs ?? [props.r3f ? 75 : 45, 0.5625, 1, 1000]
-    }, consolidatedCameraProperties), null)]);
+    }, consolidatedCameraProperties), null), interactables?.value.length && createVNode(LunchboxEventHandlers, null, null)]);
   }
 
 });
@@ -704,7 +667,7 @@ const autoGeneratedComponents = [// ThreeJS basics
 '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'
@@ -739,7 +702,6 @@ planeHelper: PlaneHelperProps
 arrowHelper: ArrowHelperProps
 axesHelper: AxesHelperProps
   // misc
-raycaster: RaycasterProps
 vector2: Vector2Props
 vector3: Vector3Props
 vector4: Vector4Props
@@ -756,7 +718,7 @@ shape: ShapeProps
 */
 ];
 
-const catalogue = {};
+const catalogue = {}; // component creation utility
 
 const createComponent$1 = tag => defineComponent({
   inheritAttrs: false,
@@ -1152,9 +1114,25 @@ function isMinidomNode(item) {
   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') {
@@ -1189,20 +1167,19 @@ const update = opts => {
   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(toRaw(scene), // opts.app.config.globalProperties.lunchbox.camera!
-      toRaw(camera));
+      renderer.render(toRaw(scene), opts.app.config.globalProperties.lunchbox.camera // toRaw(camera)
+      );
     }
   } // AFTER RENDER
 
@@ -1212,97 +1189,92 @@ const update = opts => {
   });
 }; // before render
 // ====================
-// TODO: document
+
+/** Obtain callback methods for `onBeforeRender` and `offBeforeRender`. Usually used internally by Lunchbox. */
 
 const useBeforeRender = () => {
   return {
     onBeforeRender: inject(onBeforeRenderKey),
     offBeforeRender: 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: inject(onBeforeRenderKey),
     offAfterRender: 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 = 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 = 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
@@ -1311,6 +1283,7 @@ function updateObjectProp({
     return addEventListener({
       node,
       key,
+      interactables,
       value
     });
   } // update THREE property
@@ -1341,6 +1314,7 @@ function updateObjectProp({
     const fullPath = [nestedProperty, finalKey].filter(Boolean).join('.');
     liveProperty = liveProperty = get(target, fullPath);
   } // change property
+  // first, save as array in case we need to spread it
 
 
   if (liveProperty && isNumber(value) && liveProperty.setScalar) {
@@ -1351,14 +1325,24 @@ function updateObjectProp({
     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 (get(target, finalKey, undefined) !== undefined) {
     // blank strings evaluate to `true`
     // <mesh castShadow receiveShadow /> will work the same as
@@ -1566,101 +1550,133 @@ const remove = node => {
     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 = 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 = () => 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 = watch(useCamera(), newVal => {
+    if (newVal) {
+      cb(newVal);
+      stopWatch();
+    }
+  }, {
+    immediate: true
+  });
+};
+/** The current renderer as a computed value. */
 
-const renderer = ensureRenderer;
+const useRenderer = () => 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 = watch(useRenderer(), newVal => {
+    if (newVal) {
+      cb(newVal);
+      stopWatch();
+    }
+  }, {
+    immediate: true
+  });
+};
+/** The current scene as a computed value. */
 
-const scene = ensuredScene;
+const useScene = () => inject(appSceneKey);
 /** Run a function using the current scene when it's present. */
-// TODO: update docs
 
-function useScene(callback) {
-  return watch(scene, newVal => {
-    if (!newVal) return;
-    callback(newVal.value);
+const onSceneReady = cb => {
+  const stopWatch = 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.
@@ -1717,14 +1733,15 @@ const useUpdateGlobals = () => inject(updateGlobalsInjectionKey);
 
 const updateGlobals = newValue => {
   useUpdateGlobals()?.(newValue);
-}; // TODO: document
-
-const useRootNode = () => inject(appRootNodeKey); // TODO: document
+};
+/** Use the current Lunchbox app. Usually used internally by Lunchbox. */
 
-const useApp = () => inject(appKey); // TODO: document
+const useApp = () => inject(appKey);
+/** Obtain a list of the start callback functions. Usually used internally by Lunchbox. */
 
-const useStartCallbacks = () => inject(startCallbackKey); //[] as Lunch.UpdateCallback[]
-// TODO: document
+const useStartCallbacks = () => 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();
@@ -1734,11 +1751,21 @@ const onStart = (cb, index = Infinity) => {
   } 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 = () => inject(lunchboxInteractables); // CREATE APP
 // ====================
 
 const createApp = root => {
-  const app = createRenderer(nodeOps).createApp(root); // register all components
+  const {
+    nodeOps,
+    interactables
+  } = createNodeOps();
+  const app = 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 => {
@@ -1888,4 +1915,4 @@ const createApp = root => {
   return app;
 };
 
-export { MiniDom, addEventListener, addInteractable, afterRenderKey, appCameraKey, appKey, appRenderersKey, appRootNodeKey, appSceneKey, beforeRenderKey, camera, cancelUpdate, cancelUpdateSource, clearCustomRender, clearCustomRenderKey, createApp, createCommentNode, createDomNode, createNode, createTextNode, currentIntersections, ensureRenderer, ensuredCamera, ensuredScene, extend, find, frameIdKey, globalsInjectionKey, inputActive, instantiateThreeObject, interactables, isMinidomNode, mousePos, nestedPropertiesToCheck, offAfterRender, offAfterRenderKey, offBeforeRender, offBeforeRenderKey, onAfterRender, onAfterRenderKey, onBeforeRender, onBeforeRenderKey, onStart, removeInteractable, renderer, scene, setCustomRender, setCustomRenderKey, startCallbackKey, update, updateAllObjectProps, updateGlobals, updateGlobalsInjectionKey, updateObjectProp, useAfterRender, useApp, useBeforeRender, useCamera, useCancelUpdate, useCancelUpdateSource, useCustomRender, useGlobals, useRenderer, useRootNode, useScene, useStartCallbacks, useUpdateGlobals, watchStopHandleKey };
+export { MiniDom, addEventListener, afterRenderKey, appCameraKey, appKey, appRenderersKey, appRootNodeKey, appSceneKey, beforeRenderKey, cancelUpdate, cancelUpdateSource, clearCustomRender, clearCustomRenderKey, createApp, createCommentNode, createDomNode, createNode, createTextNode, extend, find, frameIdKey, globalsInjectionKey, instantiateThreeObject, isMinidomNode, lunchboxInteractables, nestedPropertiesToCheck, offAfterRender, offAfterRenderKey, offBeforeRender, offBeforeRenderKey, onAfterRender, onAfterRenderKey, onBeforeRender, onBeforeRenderKey, onCameraReady, onRendererReady, onSceneReady, onStart, setCustomRender, setCustomRenderKey, startCallbackKey, update, updateGlobals, updateGlobalsInjectionKey, updateObjectProp, useAfterRender, useApp, useBeforeRender, useCamera, useCancelUpdate, useCancelUpdateSource, useCustomRender, useGlobals, useLunchboxInteractables, useRenderer, useScene, useStartCallbacks, useUpdateGlobals, watchStopHandleKey };