lunchboxjs 0.1.4001 → 0.1.4005

package/dist/lunchboxjs.module.js

@@ -1,4 +1,4 @@
-import { ref, onMounted, getCurrentInstance, onBeforeUnmount, h, defineComponent, isRef, isVNode, watch, computed, createRenderer } from 'vue';
+import { toRaw, ref, onMounted, getCurrentInstance, onBeforeUnmount, h, defineComponent, isRef, isVNode, watch, reactive, computed, createRenderer } from 'vue';
 import * as THREE from 'three';
 import { Color } from 'three';
 import { set, get, isNumber } from 'lodash';
@@ -7,29 +7,39 @@ import { set, get, isNumber } from 'lodash';
 const allNodes = [];
 
 const resizeCanvas = (width, height) => {
-    const renderer = ensureRenderer().instance;
-    const scene = ensureScene().instance;
+    const renderer = ensureRenderer.value?.instance;
+    const scene = ensuredScene.value.instance;
+    const camera = ensuredCamera.value;
     // ignore if no element
-    if (!renderer?.domElement || !scene)
+    if (!renderer?.domElement || !scene || !camera)
         return;
     width = width ?? window.innerWidth;
     height = height ?? window.innerHeight;
     // update camera
     const aspect = width / height;
-    const camera = ensureCamera();
     if (camera.type?.toLowerCase() === 'perspectivecamera') {
         const perspectiveCamera = camera.instance;
         perspectiveCamera.aspect = aspect;
         perspectiveCamera.updateProjectionMatrix();
     }
+    else if (camera.type?.toLowerCase() === 'orthographiccamera') {
+        // console.log('TODO: ortho camera update')
+        const orthoCamera = camera.instance;
+        const heightInTermsOfWidth = height / width;
+        orthoCamera.top = heightInTermsOfWidth * 10;
+        orthoCamera.bottom = -heightInTermsOfWidth * 10;
+        orthoCamera.right = 10;
+        orthoCamera.left = -10;
+        orthoCamera.updateProjectionMatrix();
+    }
     else {
-        console.log('TODO: ortho camera update');
+        console.log('TODO: non-ortho or perspective camera');
     }
     // update canvas
     renderer.setSize(width, height);
     // render immediately so there's no flicker
     if (scene && camera.instance) {
-        renderer.render(scene, camera.instance);
+        renderer.render(toRaw(scene), toRaw(camera.instance));
     }
 };
 
@@ -73,8 +83,13 @@ const LunchboxWrapper = {
     props: {
         // These should match the Lunchbox.WrapperProps interface
         background: String,
+        cameraArgs: Array,
+        cameraLook: Array,
+        cameraLookAt: Array,
         cameraPosition: Array,
         dpr: Number,
+        ortho: Boolean,
+        orthographic: Boolean,
         rendererProperties: Object,
         shadow: [Boolean, Object],
         transparent: Boolean,
@@ -85,6 +100,7 @@ const LunchboxWrapper = {
         const dpr = ref(props.dpr ?? -1);
         const container = ref();
         let renderer;
+        let camera;
         let scene;
         // MOUNT
         // ====================
@@ -92,40 +108,106 @@ const LunchboxWrapper = {
             // canvas needs to exist
             if (!canvas.value)
                 throw new Error('missing canvas');
-            // ensure camera
-            const camera = ensureCamera().instance;
-            // move camera if needed
-            if (camera && props.cameraPosition) {
-                camera.position.set(...props.cameraPosition);
-            }
             // RENDERER
             // ====================
-            // build renderer args
-            const rendererArgs = {
-                antialias: true,
-                canvas: canvas.value.domElement,
-            };
-            if (props.transparent) {
-                rendererArgs.alpha = true;
-            }
-            const sugar = {
-                shadow: props.shadow,
-            };
-            // ensure renderer
-            renderer = ensureRenderer([rendererArgs], sugar);
-            // set renderer props if needed
-            if (props.rendererProperties) {
-                Object.keys(props.rendererProperties).forEach((key) => {
-                    set(renderer, key, props.rendererProperties[key]);
+            // is there already a renderer?
+            // TODO: allow other renderer types
+            renderer = tryGetNodeWithInstanceType([
+                'WebGLRenderer',
+            ]);
+            // if renderer is missing, initialize with options
+            if (!renderer) {
+                // build renderer args
+                const rendererArgs = {
+                    antialias: true,
+                    canvas: canvas.value.domElement,
+                };
+                if (props.transparent) {
+                    rendererArgs.alpha = true;
+                }
+                // create new renderer
+                ensureRenderer.value = createNode({
+                    type: 'WebGLRenderer',
+                    uuid: fallbackRendererUuid,
+                    props: {
+                        args: [rendererArgs],
+                    },
                 });
+                // we've initialized the renderer, so anything depending on it can execute now
+                rendererReady.value = true;
+                const rendererAsWebGlRenderer = ensureRenderer;
+                // update render sugar
+                const sugar = {
+                    shadow: props.shadow,
+                };
+                if (rendererAsWebGlRenderer.value.instance && sugar?.shadow) {
+                    rendererAsWebGlRenderer.value.instance.shadowMap.enabled =
+                        true;
+                    if (typeof sugar.shadow === 'object') {
+                        rendererAsWebGlRenderer.value.instance.shadowMap.type =
+                            sugar.shadow.type;
+                    }
+                }
+                // set renderer props if needed
+                if (props.rendererProperties) {
+                    Object.keys(props.rendererProperties).forEach((key) => {
+                        set(rendererAsWebGlRenderer.value, key, props.rendererProperties[key]);
+                    });
+                }
+                // update using created renderer
+                renderer = rendererAsWebGlRenderer.value;
             }
-            if (renderer.uuid !== fallbackRendererUuid) {
+            else {
                 useFallbackRenderer.value = false;
+                // the user has initialized the renderer, so anything depending
+                // on the renderer can execute
+                rendererReady.value = true;
                 return;
             }
+            // CAMERA
+            // ====================
+            // is there already a camera?
+            camera = tryGetNodeWithInstanceType([
+                'PerspectiveCamera',
+                'OrthographicCamera',
+            ]);
+            // if not, let's create one
+            if (!camera) {
+                // create ortho camera
+                if (props.ortho || props.orthographic) {
+                    ensuredCamera.value = createNode({
+                        props: { args: props.cameraArgs ?? [] },
+                        type: 'OrthographicCamera',
+                        uuid: fallbackCameraUuid,
+                    });
+                }
+                else {
+                    ensuredCamera.value = createNode({
+                        props: {
+                            args: props.cameraArgs ?? [45, 0.5625, 1, 1000],
+                        },
+                        type: 'PerspectiveCamera',
+                        uuid: fallbackCameraUuid,
+                    });
+                }
+                cameraReady.value = true;
+                camera = ensuredCamera.value;
+            }
+            else {
+                cameraReady.value = true;
+            }
+            // move camera if needed
+            if (camera && props.cameraPosition) {
+                camera.instance?.position.set(...props.cameraPosition);
+            }
+            // angle camera if needed
+            if (camera && (props.cameraLookAt || props.cameraLook)) {
+                const source = (props.cameraLookAt || props.cameraLook);
+                camera.instance?.lookAt(...source);
+            }
             // SCENE
             // ====================
-            scene = ensureScene();
+            scene = ensuredScene.value;
             // set background color
             if (scene && scene.instance && props.background) {
                 scene.instance.background = new Color(props.background);
@@ -135,7 +217,7 @@ const LunchboxWrapper = {
             if (dpr.value === -1) {
                 dpr.value = window.devicePixelRatio;
             }
-            if (renderer.instance) {
+            if (renderer?.instance) {
                 renderer.instance.setPixelRatio(dpr.value);
                 globals.dpr.value = dpr.value;
                 // prep canvas (sizing, observe, unmount, etc)
@@ -146,9 +228,10 @@ const LunchboxWrapper = {
             }
             // KICK UPDATE
             // ====================
+            // console.log(scene)
             update({
                 app: getCurrentInstance().appContext.app,
-                camera,
+                camera: camera.instance,
                 renderer: renderer.instance,
                 scene: scene.instance,
             });
@@ -178,21 +261,6 @@ const LunchboxWrapper = {
     },
 };
 
-const catalogue = {};
-
-const lunchboxDomComponentNames = [
-    'canvas',
-    'div',
-    'LunchboxWrapper',
-];
-// component creation utility
-const createComponent$1 = (tag) => defineComponent({
-    inheritAttrs: false,
-    name: tag,
-    setup(props, context) {
-        return () => h(tag, context.attrs, context.slots?.default?.() || []);
-    },
-});
 // list of all components to register out of the box
 const autoGeneratedComponents = [
     // ThreeJS basics
@@ -305,21 +373,11 @@ const autoGeneratedComponents = [
     'arrayCamera',
     // renderers
     'webGLRenderer',
-].map(createComponent$1).reduce((acc, curr) => {
-    acc[curr.name] = curr;
-    return acc;
-});
-const components = {
-    ...autoGeneratedComponents,
-    'Lunchbox': LunchboxWrapper,
-    // Gltf,
-};
-// console.log(components, Gltf)
-/*
-// List copied from r3f
-// https://github.com/pmndrs/react-three-fiber/blob/master/packages/fiber/src/three-types.ts
+    /*
+    // List copied from r3f:
+    // https://github.com/pmndrs/react-three-fiber/blob/master/packages/fiber/src/three-types.ts
 
-// NOT IMPLEMENTED:
+    // NOT IMPLEMENTED (can be added via Extend - docs.lunchboxjs.com/components/extend/):
     audioListener: AudioListenerProps
     positionalAudio: PositionalAudioProps
 
@@ -367,6 +425,27 @@ const components = {
     fogExp2: FogExp2Props
     shape: ShapeProps
 */
+];
+
+const catalogue = {};
+
+const lunchboxDomComponentNames = ['canvas', 'div', 'LunchboxWrapper'];
+// component creation utility
+const createComponent$1 = (tag) => defineComponent({
+    inheritAttrs: false,
+    name: tag,
+    setup(props, context) {
+        return () => h(tag, context.attrs, context.slots?.default?.() || []);
+    },
+});
+autoGeneratedComponents.map(createComponent$1).reduce((acc, curr) => {
+    acc[curr.name] = curr;
+    return acc;
+});
+const components = {
+    ...autoGeneratedComponents,
+    Lunchbox: LunchboxWrapper,
+};
 
 function find(target) {
     target = isRef(target) ? target.value : target;
@@ -423,7 +502,7 @@ const isLunchboxRootNode = (node) => {
 /** Create a new Lunchbox comment node. */
 function createCommentNode(options = {}) {
     const defaults = {
-        text: options.text ?? ''
+        text: options.text ?? '',
     };
     return new MiniDom.RendererCommentNode({
         ...defaults,
@@ -447,7 +526,7 @@ function createDomNode(options = {}) {
 /** Create a new Lunchbox text node. */
 function createTextNode(options = {}) {
     const defaults = {
-        text: options.text ?? ''
+        text: options.text ?? '',
     };
     return new MiniDom.RendererTextNode({
         ...options,
@@ -460,7 +539,7 @@ function createNode(options = {}, props = {}) {
     const defaults = {
         attached: options.attached ?? [],
         attachedArray: options.attachedArray ?? {},
-        instance: options.instance ?? null
+        instance: options.instance ?? null,
     };
     const node = new MiniDom.RendererStandardNode({
         ...options,
@@ -468,14 +547,25 @@ function createNode(options = {}, props = {}) {
         metaType: 'standardMeta',
     });
     if (node.type && !isLunchboxRootNode(node) && !node.instance) {
+        // if (node.type.includes('Camera')) {
+        //     console.log(node.type, {
+        //         ...node.props,
+        //         ...props,
+        //     })
+        //     console.trace()
+        // }
         node.instance = instantiateThreeObject({
             ...node,
             props: {
                 ...node.props,
                 ...props,
-            }
+            },
         });
     }
+    if (node.type === 'scene') {
+        // manually set scene override
+        ensuredScene.value = node;
+    }
     return node;
 }
 
@@ -506,7 +596,9 @@ function addEventListener({ node, key, value, }) {
     node.eventListeners[key].push(value);
     // if we need it, let's get/create the main raycaster
     if (interactionsRequiringRaycaster.includes(key)) {
-        ensureRaycaster();
+        // we're not using `v` here, we're just making sure the raycaster has been created
+        // TODO: is this necessary?
+        ensuredRaycaster.value;
         if (node.instance && !interactables.includes(node)) {
             addInteractable(node);
             node.eventListenerRemoveFunctions[key].push(() => removeInteractable(node));
@@ -564,7 +656,7 @@ const setupAutoRaycaster = (node) => {
         return;
     // add mouse events once renderer is ready
     let stopWatcher = null;
-    stopWatcher = watch(() => createdRenderer.value, (renderer) => {
+    stopWatcher = watch(() => ensureRenderer.value, (renderer) => {
         // make sure renderer exists
         if (!renderer?.instance)
             return;
@@ -605,8 +697,8 @@ const setupAutoRaycaster = (node) => {
 let currentIntersections = [];
 const autoRaycasterBeforeRender = () => {
     // setup
-    const raycaster = createdRaycaster.value?.instance;
-    const camera = createdCamera.value?.instance;
+    const raycaster = ensuredRaycaster.value?.instance;
+    const camera = ensuredCamera.value?.instance;
     if (!raycaster || !camera)
         return;
     raycaster.setFromCamera(globals.mousePos.value, camera);
@@ -690,119 +782,147 @@ function ensureRootNode(options = {}) {
     }
     return lunchboxRootNode;
 }
-// ENSURE CAMERA
+// This is used in `buildEnsured` below and `LunchboxWrapper`
+/** Search the overrides record and the node tree for a node in the given types */
+function tryGetNodeWithInstanceType(pascalCaseTypes) {
+    if (!Array.isArray(pascalCaseTypes)) {
+        pascalCaseTypes = [pascalCaseTypes];
+    }
+    // default to override if we have one
+    for (let singleType of pascalCaseTypes) {
+        if (overrides[singleType])
+            return overrides[singleType];
+    }
+    // look for auto-created node
+    for (let singleType of pascalCaseTypes) {
+        const found = autoCreated[singleType] ||
+            allNodes.find((node) => node.type?.toLowerCase() ===
+                singleType.toLowerCase());
+        // if we have one, save and return
+        if (found) {
+            const createdAsNode = found;
+            autoCreated[singleType] = createdAsNode;
+            return createdAsNode;
+        }
+    }
+    return null;
+}
+// GENERIC ENSURE FUNCTION
 // ====================
-const fallbackCameraUuid = 'FALLBACK_CAMERA';
-const createdCamera = ref(null);
-const ensureCamera = () => {
-    // look for cameras
-    // TODO: does this need to be more robust?
-    const foundCamera = allNodes.find((node) => node.type
-        ?.toLowerCase()
-        .includes('camera'));
-    // if we have one, return
-    if (foundCamera) {
-        const cameraAsStandardNode = foundCamera;
-        createdCamera.value = cameraAsStandardNode;
-        return cameraAsStandardNode;
+// Problem:
+// I want to make sure an object of type Xyz exists in my Lunchbox app.
+// If it doesn't exist, I want to create it and add it to the root node.
+//
+// Solution:
+// export const ensuredXyz = buildEnsured<Xyz>('Xyz', 'FALLBACK_XYZ')
+//
+// Now in other components, you can do both:
+// import { ensuredXyz }
+// ensuredXyz.value (...)
+// and:
+// ensuredXyz.value = ...
+const autoCreated = reactive({});
+const overrides = reactive({});
+/**
+ * Build a computed ensured value with a getter and setter.
+ * @param pascalCaseTypes List of types this can be. Will autocreate first type if array provided.
+ * @param fallbackUuid Fallback UUID to use.
+ * @param props Props to pass to autocreated element
+ * @returns Computed getter/setter for ensured object.
+ */
+function buildEnsured(pascalCaseTypes, fallbackUuid, props = {}, callback = null) {
+    // make sure we've got an array
+    if (!Array.isArray(pascalCaseTypes)) {
+        pascalCaseTypes = [pascalCaseTypes];
     }
-    // otherwise, create a new camera
-    const root = ensureRootNode();
-    const cameraNode = createNode({
-        type: 'PerspectiveCamera',
-        uuid: fallbackCameraUuid,
-        props: {
-            args: [45, 0.5625, 1, 1000],
+    // add type for autoCreated and overrides
+    for (let singleType of pascalCaseTypes) {
+        if (!autoCreated[singleType]) {
+            autoCreated[singleType] = null;
+        }
+        if (!overrides[singleType]) {
+            overrides[singleType] = null;
+        }
+    }
+    return computed({
+        get() {
+            // try to get existing type
+            const existing = tryGetNodeWithInstanceType(pascalCaseTypes);
+            if (existing)
+                return existing;
+            // otherwise, create a new node
+            const root = ensureRootNode();
+            const node = createNode({
+                type: pascalCaseTypes[0],
+                uuid: fallbackUuid,
+                props,
+            });
+            root.addChild(node);
+            autoCreated[pascalCaseTypes[0]] = node;
+            if (callback) {
+                callback(node);
+            }
+            return node;
+        },
+        set(val) {
+            const t = val.type ?? '';
+            const pascalType = t[0].toUpperCase() + t.slice(1);
+            overrides[pascalType] = val;
         },
     });
-    root.addChild(cameraNode);
-    createdCamera.value = cameraNode;
-    // add camera to scene
-    ensureScene().instance?.add(cameraNode.instance);
-    return cameraNode;
-};
+}
+// ENSURE CAMERA
+// ====================
+const fallbackCameraUuid = 'FALLBACK_CAMERA';
+const defaultCamera = buildEnsured(['PerspectiveCamera', 'OrthographicCamera'], fallbackCameraUuid, { args: [45, 0.5625, 1, 1000] });
+/** Special value to be changed ONLY in `LunchboxWrapper`.
+ * Functions waiting for a Camera need to wait for this to be true.  */
+const cameraReady = ref(false);
+const ensuredCamera = computed({
+    get() {
+        return (cameraReady.value ? defaultCamera.value : null);
+    },
+    set(val) {
+        const t = val.type ?? '';
+        const pascalType = t[0].toUpperCase() + t.slice(1);
+        overrides[pascalType] = val;
+    },
+});
+// export const ensuredCamera = buildEnsured<THREE.Camera>(
+//     ['PerspectiveCamera', 'OrthographicCamera'],
+//     fallbackCameraUuid,
+//     {
+//         args: [45, 0.5625, 1, 1000],
+//     }
+// )
 // ENSURE RENDERER
 // ====================
 const fallbackRendererUuid = 'FALLBACK_RENDERER';
-const createdRenderer = ref(null);
-const ensureRenderer = (fallbackArgs = [], sugar = {}) => {
-    // look for renderers
-    // TODO: does this need to be more robust?
-    const foundRenderer = allNodes.find((node) => node.type
-        ?.toLowerCase()
-        .includes('renderer'));
-    // if we have one, return
-    if (foundRenderer) {
-        const rendererAsStandardNode = foundRenderer;
-        createdRenderer.value = rendererAsStandardNode;
-        return rendererAsStandardNode;
-    }
-    // otherwise, create a new renderer
-    const root = ensureRootNode();
-    const rendererNode = createNode({
-        type: 'WebGLRenderer',
-        uuid: fallbackRendererUuid,
-    }, { args: fallbackArgs });
-    // shadow sugar
-    if (sugar?.shadow) {
-        rendererNode.instance.shadowMap.enabled = true;
-        if (typeof sugar.shadow === 'object') {
-            rendererNode.instance.shadowMap.type = sugar.shadow.type;
-        }
-    }
-    root.addChild(rendererNode);
-    createdRenderer.value = rendererNode;
-    // return created node
-    return rendererNode;
-};
+const v = buildEnsured(
+// TODO: ensure support for css/svg renderers
+['WebGLRenderer'], //, 'CSS2DRenderer', 'CSS3DRenderer', 'SVGRenderer'],
+fallbackRendererUuid, {});
+/** Special value to be changed ONLY in `LunchboxWrapper`.
+ * Functions waiting for a Renderer need to wait for this to be true.  */
+const rendererReady = ref(false);
+const ensureRenderer = computed({
+    get() {
+        return (rendererReady.value ? v.value : null);
+    },
+    set(val) {
+        const t = val.type ?? '';
+        const pascalType = t[0].toUpperCase() + t.slice(1);
+        overrides[pascalType] = val;
+    },
+});
 // ENSURE SCENE
 // ====================
 const fallbackSceneUuid = 'FALLBACK_SCENE';
-const createdScene = ref();
-const ensureScene = () => {
-    // look for scenes
-    const foundScene = allNodes.find((node) => node.type?.toLowerCase() === 'scene');
-    // if we have one, return
-    if (foundScene) {
-        const sceneAsLunchboxNode = foundScene;
-        createdScene.value = sceneAsLunchboxNode;
-        return sceneAsLunchboxNode;
-    }
-    // otherwise, create a new scene
-    const root = ensureRootNode();
-    const sceneNode = createNode({
-        type: 'Scene',
-        uuid: fallbackSceneUuid,
-    });
-    root.addChild(sceneNode);
-    createdScene.value = sceneNode;
-    return sceneNode;
-};
+const ensuredScene = buildEnsured('Scene', fallbackSceneUuid);
 // ENSURE AUTO-RAYCASTER
 const autoRaycasterUuid = 'AUTO_RAYCASTER';
-const createdRaycaster = ref(null);
-const ensureRaycaster = () => {
-    // look for autoraycaster
-    const found = allNodes.find((node) => node.uuid === autoRaycasterUuid);
-    // if we have one, return
-    if (found) {
-        const foundAsNode = found;
-        createdRaycaster.value = foundAsNode;
-        return foundAsNode;
-    }
-    // otherwise, create raycaster
-    const root = ensureRootNode();
-    const raycasterNode = createNode({
-        type: 'Raycaster',
-        uuid: autoRaycasterUuid,
-    });
-    root.addChild(raycasterNode);
-    createdRaycaster.value = raycasterNode;
-    // finish auto-raycaster setup
-    setupAutoRaycaster(raycasterNode);
-    // done with raycaster
-    return raycasterNode;
-};
+// `unknown` is intentional here - we need to typecast the node since Raycaster isn't an Object3D
+const ensuredRaycaster = buildEnsured('Raycaster', autoRaycasterUuid, {}, (node) => setupAutoRaycaster(node));
 
 const createComponent = (tag) => defineComponent({
     inheritAttrs: false,
@@ -850,9 +970,11 @@ function instantiateThreeObject(node) {
     // replace $attached values with their instances
     // we need to guarantee everything comes back as an array so we can spread $attachedArrays,
     // so we'll use processPropAsArray
-    const argsWrappedInArrays = args.map((arg) => { return processPropAsArray({ node, prop: arg }); });
+    const argsWrappedInArrays = args.map((arg) => {
+        return processPropAsArray({ node, prop: arg });
+    });
     let processedArgs = [];
-    argsWrappedInArrays.forEach(arr => {
+    argsWrappedInArrays.forEach((arr) => {
         processedArgs = processedArgs.concat(arr);
     });
     const instance = new targetClass(...processedArgs);
@@ -954,7 +1076,7 @@ var MiniDom;
         get nextSibling() {
             if (!this.parentNode)
                 return null;
-            const idx = this.parentNode.children.findIndex(n => n.uuid === this.uuid);
+            const idx = this.parentNode.children.findIndex((n) => n.uuid === this.uuid);
             // return next sibling if we're present and not the last child of the parent
             if (idx !== -1 && idx < this.parentNode.children.length - 1) {
                 return this.parentNode.children[idx + 1];
@@ -964,7 +1086,7 @@ var MiniDom;
         insertBefore(child, anchor) {
             child.removeAsChildFromAnyParents();
             child.parentNode = this;
-            const anchorIdx = this.children.findIndex(n => n.uuid === anchor?.uuid);
+            const anchorIdx = this.children.findIndex((n) => n.uuid === anchor?.uuid);
             if (anchorIdx !== -1) {
                 this.children.splice(anchorIdx, 0, child);
             }
@@ -973,7 +1095,7 @@ var MiniDom;
             }
         }
         removeChild(child) {
-            const idx = this.children.findIndex(n => n?.uuid === child?.uuid);
+            const idx = this.children.findIndex((n) => n?.uuid === child?.uuid);
             if (idx !== -1) {
                 this.children.splice(idx, 1);
             }
@@ -985,7 +1107,7 @@ var MiniDom;
             if (child) {
                 // remove child from any other parents
                 child.removeAsChildFromAnyParents();
-                // add to this node 
+                // add to this node
                 child.parentNode = this;
                 this.insertBefore(child, null);
             }
@@ -1013,11 +1135,15 @@ var MiniDom;
         // TODO: depth-first vs breadth-first
         walk(callback) {
             const queue = [this, ...this.children];
+            const traversed = [];
             let canContinue = true;
             while (queue.length && canContinue) {
                 const current = queue.shift();
                 if (current) {
-                    queue.push(...current.children);
+                    if (traversed.includes(current))
+                        continue;
+                    traversed.push(current);
+                    queue.push(...current.children.filter((child) => !traversed.includes(child)));
                     canContinue = callback(current);
                 }
                 else {
@@ -1029,7 +1155,7 @@ var MiniDom;
         // ====================
         minidomType;
         removeAsChildFromAnyParents() {
-            allNodes.forEach(node => node.removeChild(this));
+            allNodes.forEach((node) => node.removeChild(this));
         }
     }
     MiniDom.BaseNode = BaseNode;
@@ -1053,8 +1179,8 @@ var MiniDom;
         drop() {
             super.drop();
             // handle remove functions
-            Object.keys(this.eventListenerRemoveFunctions).forEach(key => {
-                this.eventListenerRemoveFunctions[key].forEach(func => func());
+            Object.keys(this.eventListenerRemoveFunctions).forEach((key) => {
+                this.eventListenerRemoveFunctions[key].forEach((func) => func());
             });
         }
     }
@@ -1065,7 +1191,8 @@ var MiniDom;
     class RendererRootNode extends MiniDom.RendererBaseNode {
         constructor(options = {}, parent) {
             super(options, parent);
-            this.domElement = options.domElement ?? document.createElement('div');
+            this.domElement =
+                options.domElement ?? document.createElement('div');
         }
         domElement;
         isLunchboxRootNode = true;
@@ -1082,7 +1209,8 @@ var MiniDom;
     class RendererDomNode extends MiniDom.RendererBaseNode {
         constructor(options = {}, parent) {
             super(options, parent);
-            this.domElement = options.domElement ?? document.createElement('div');
+            this.domElement =
+                options.domElement ?? document.createElement('div');
         }
         domElement;
     }
@@ -1115,7 +1243,14 @@ let frameID;
 const beforeRender = [];
 const afterRender = [];
 const update = (opts) => {
-    frameID = requestAnimationFrame(() => update(opts));
+    // request next frame
+    frameID = requestAnimationFrame(() => update({
+        app: opts.app,
+        renderer: ensureRenderer.value?.instance,
+        scene: ensuredScene.value.instance,
+        camera: ensuredCamera.value?.instance,
+    }));
+    // prep options
     const { app, renderer, scene, camera } = opts;
     // BEFORE RENDER
     beforeRender.forEach((cb) => {
@@ -1125,7 +1260,12 @@ const update = (opts) => {
     });
     // RENDER
     if (renderer && scene && camera) {
-        renderer.render(scene, camera);
+        if (app.customRender) {
+            app.customRender(opts);
+        }
+        else {
+            renderer.render(toRaw(scene), toRaw(camera));
+        }
     }
     // AFTER RENDER
     afterRender.forEach((cb) => {
@@ -1133,22 +1273,6 @@ const update = (opts) => {
             cb(opts);
         }
     });
-    /*
-    frameID = requestAnimationFrame(() => update(renderer, scene, camera))
-
-    // Make sure we have all necessary components
-    if (!renderer) {
-        renderer = ensureRenderer().instance
-    }
-    if (!scene) {
-        scene = ensureScene().instance
-    }
-    if (!camera) {
-        camera = ensureCamera().instance
-    }
-
-
-    */
 };
 const onBeforeRender = (cb, index = Infinity) => {
     if (index === Infinity) {
@@ -1158,6 +1282,15 @@ const onBeforeRender = (cb, index = Infinity) => {
         beforeRender.splice(index, 0, cb);
     }
 };
+const offBeforeRender = (cb) => {
+    if (isFinite(cb)) {
+        beforeRender.splice(cb, 1);
+    }
+    else {
+        const idx = beforeRender.findIndex((v) => v == cb);
+        beforeRender.splice(idx, 1);
+    }
+};
 const onAfterRender = (cb, index = Infinity) => {
     if (index === Infinity) {
         afterRender.push(cb);
@@ -1166,6 +1299,15 @@ const onAfterRender = (cb, index = Infinity) => {
         afterRender.splice(index, 0, cb);
     }
 };
+const offAfterRender = (cb) => {
+    if (isFinite(cb)) {
+        afterRender.splice(cb, 1);
+    }
+    else {
+        const idx = afterRender.findIndex((v) => v == cb);
+        afterRender.splice(idx, 1);
+    }
+};
 const cancelUpdate = () => {
     if (frameID)
         cancelAnimationFrame(frameID);
@@ -1271,10 +1413,7 @@ const internalLunchboxVueKeys = [
     'src',
 ];
 
-const autoAttach = [
-    'geometry',
-    'material',
-];
+const autoAttach = ['geometry', 'material'];
 const createElement = (type, isSVG, isCustomizedBuiltin, vnodeProps) => {
     const options = { type };
     if (vnodeProps) {
@@ -1289,7 +1428,7 @@ const createElement = (type, isSVG, isCustomizedBuiltin, vnodeProps) => {
     // handle standard node
     const node = createNode(options);
     // autoattach
-    autoAttach.forEach(key => {
+    autoAttach.forEach((key) => {
         if (type.toLowerCase().endsWith(key)) {
             node.props.attach = key;
         }
@@ -1329,17 +1468,19 @@ const insert = (child, parent, anchor) => {
         }
         // add to scene if parent is the wrapper node
         if (child.metaType === 'standardMeta' &&
-            child.type !== 'Scene' &&
+            child.type !== 'scene' &&
             isLunchboxRootNode(effectiveParent)) {
             // ensure scene exists
-            const sceneNode = ensureScene();
+            const sceneNode = ensuredScene.value;
             if (sceneNode.instance && child) {
                 sceneNode.addChild(child);
             }
             if (child.instance &&
                 child.instance.isObject3D &&
                 sceneNode.instance) {
-                sceneNode.instance.add(child.instance);
+                if (sceneNode !== child) {
+                    sceneNode.instance.add(child.instance);
+                }
             }
         }
         // add to hierarchy otherwise
@@ -1422,19 +1563,29 @@ function attachToParentInstance(child, parent, key, value) {
 const remove = (node) => {
     if (!node)
         return;
+    const overrideKeys = Object.keys(overrides);
     // prep subtree
     const subtree = [];
-    node.walk(descendant => {
+    node.walk((descendant) => {
         subtree.push(descendant);
         return true;
     });
     // clean up subtree
     subtree.forEach((n) => {
+        const overrideKey = overrideKeys.find((key) => overrides[key]?.uuid === n.uuid);
+        // if this node is an override, remove it from the overrides list
+        if (overrideKey) {
+            overrides[overrideKey] = null;
+        }
         if (isLunchboxStandardNode(n)) {
             // try to remove three object
             n.instance?.removeFromParent?.();
             // try to dispose three object
-            const dispose = n.instance?.dispose;
+            const dispose = 
+            // calling `dispose` on a scene triggers an error,
+            // so let's ignore if this node is a scene
+            n.type !== 'scene' &&
+                n.instance?.dispose;
             if (dispose)
                 dispose.bind(n.instance)();
             n.instance = null;
@@ -1442,7 +1593,7 @@ const remove = (node) => {
         // drop tree node
         n.drop();
         // remove Lunchbox node from main list
-        const idx = allNodes.findIndex(v => v.uuid === n.uuid);
+        const idx = allNodes.findIndex((v) => v.uuid === n.uuid);
         if (idx !== -1) {
             allNodes.splice(idx, 1);
         }
@@ -1509,15 +1660,34 @@ const globals = {
     dpr: ref(1),
     inputActive,
     mousePos,
-    camera: createdCamera,
-    renderer: createdRenderer,
-    scene: createdScene,
 };
-const camera = computed(() => globals.camera.value?.instance);
-const renderer = computed(() => globals.renderer.value?.instance);
-const scene = computed(() => globals.scene.value?.instance);
+const camera = computed(() => ensuredCamera.value?.instance ?? null);
+const renderer = computed(() => ensureRenderer.value?.instance ?? null);
+const scene = computed(() => ensuredScene.value.instance);
+// CUSTOM RENDER SUPPORT
+// ====================
+let app = null;
+let queuedCustomRenderFunction = null;
+/** Set a custom render function, overriding the Lunchbox app's default render function.
+ * Changing this requires the user to manually render their scene.
+ */
+const setCustomRender = (render) => {
+    if (app)
+        app.setCustomRender(render);
+    else
+        queuedCustomRenderFunction = render;
+};
+/** Clear the active app's custom render function. */
+const clearCustomRender = () => {
+    if (app)
+        app.clearCustomRender();
+    else
+        queuedCustomRenderFunction = null;
+};
+// CREATE APP
+// ====================
 const createApp = (root) => {
-    const app = createRenderer(nodeOps).createApp(root);
+    app = createRenderer(nodeOps).createApp(root);
     // register all components
     Object.keys(components).forEach((key) => {
         app.component(key, components[key]);
@@ -1540,16 +1710,24 @@ const createApp = (root) => {
     };
     // embed .extend function
     app.extend = (targets) => {
-        extend({ app, ...targets });
+        extend({ app: app, ...targets });
         return app;
     };
-    // kick update loop
-    // app.update = update
-    // app.update({
-    //     app,
-    // })
+    // prep for custom render support
+    app.setCustomRender = (newRender) => {
+        app.customRender = newRender;
+    };
+    // add queued custom render if we have one
+    if (queuedCustomRenderFunction) {
+        app.setCustomRender(queuedCustomRenderFunction);
+        queuedCustomRenderFunction = null;
+    }
+    // add custom render removal
+    app.clearCustomRender = () => {
+        app.customRender = null;
+    };
     // done
     return app;
 };
 
-export { camera, createApp, find, globals, lunchboxRootNode as lunchboxTree, onAfterRender, onBeforeRender, renderer, scene, update };
+export { camera, clearCustomRender, createApp, find, globals, lunchboxRootNode as lunchboxTree, offAfterRender, offBeforeRender, onAfterRender, onBeforeRender, renderer, scene, setCustomRender };