lunchboxjs 0.1.4001 → 0.1.4005

package/dist/lunchboxjs.js

@@ -28,29 +28,39 @@
     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(vue.toRaw(scene), vue.toRaw(camera.instance));
         }
     };
 
@@ -94,8 +104,13 @@
         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,
@@ -106,6 +121,7 @@
             const dpr = vue.ref(props.dpr ?? -1);
             const container = vue.ref();
             let renderer;
+            let camera;
             let scene;
             // MOUNT
             // ====================
@@ -113,40 +129,106 @@
                 // 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) => {
-                        lodash.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) => {
+                            lodash.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 THREE.Color(props.background);
@@ -156,7 +238,7 @@
                 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)
@@ -167,9 +249,10 @@
                 }
                 // KICK UPDATE
                 // ====================
+                // console.log(scene)
                 update({
                     app: vue.getCurrentInstance().appContext.app,
-                    camera,
+                    camera: camera.instance,
                     renderer: renderer.instance,
                     scene: scene.instance,
                 });
@@ -199,21 +282,6 @@
         },
     };
 
-    const catalogue = {};
-
-    const lunchboxDomComponentNames = [
-        'canvas',
-        'div',
-        'LunchboxWrapper',
-    ];
-    // component creation utility
-    const createComponent$1 = (tag) => vue.defineComponent({
-        inheritAttrs: false,
-        name: tag,
-        setup(props, context) {
-            return () => vue.h(tag, context.attrs, context.slots?.default?.() || []);
-        },
-    });
     // list of all components to register out of the box
     const autoGeneratedComponents = [
         // ThreeJS basics
@@ -326,21 +394,11 @@
         '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
 
@@ -388,6 +446,27 @@
         fogExp2: FogExp2Props
         shape: ShapeProps
     */
+    ];
+
+    const catalogue = {};
+
+    const lunchboxDomComponentNames = ['canvas', 'div', 'LunchboxWrapper'];
+    // component creation utility
+    const createComponent$1 = (tag) => vue.defineComponent({
+        inheritAttrs: false,
+        name: tag,
+        setup(props, context) {
+            return () => vue.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 = vue.isRef(target) ? target.value : target;
@@ -444,7 +523,7 @@
     /** Create a new Lunchbox comment node. */
     function createCommentNode(options = {}) {
         const defaults = {
-            text: options.text ?? ''
+            text: options.text ?? '',
         };
         return new MiniDom.RendererCommentNode({
             ...defaults,
@@ -468,7 +547,7 @@
     /** Create a new Lunchbox text node. */
     function createTextNode(options = {}) {
         const defaults = {
-            text: options.text ?? ''
+            text: options.text ?? '',
         };
         return new MiniDom.RendererTextNode({
             ...options,
@@ -481,7 +560,7 @@
         const defaults = {
             attached: options.attached ?? [],
             attachedArray: options.attachedArray ?? {},
-            instance: options.instance ?? null
+            instance: options.instance ?? null,
         };
         const node = new MiniDom.RendererStandardNode({
             ...options,
@@ -489,14 +568,25 @@
             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;
     }
 
@@ -527,7 +617,9 @@
         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));
@@ -585,7 +677,7 @@
             return;
         // add mouse events once renderer is ready
         let stopWatcher = null;
-        stopWatcher = vue.watch(() => createdRenderer.value, (renderer) => {
+        stopWatcher = vue.watch(() => ensureRenderer.value, (renderer) => {
             // make sure renderer exists
             if (!renderer?.instance)
                 return;
@@ -626,8 +718,8 @@
     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);
@@ -711,119 +803,147 @@
         }
         return exports.lunchboxTree;
     }
-    // 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 = vue.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 = vue.reactive({});
+    const overrides = vue.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 vue.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 = vue.ref(false);
+    const ensuredCamera = vue.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 = vue.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 = vue.ref(false);
+    const ensureRenderer = vue.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 = vue.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 = vue.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) => vue.defineComponent({
         inheritAttrs: false,
@@ -871,9 +991,11 @@
         // 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);
@@ -975,7 +1097,7 @@
             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];
@@ -985,7 +1107,7 @@
             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);
                 }
@@ -994,7 +1116,7 @@
                 }
             }
             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);
                 }
@@ -1006,7 +1128,7 @@
                 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);
                 }
@@ -1034,11 +1156,15 @@
             // 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 {
@@ -1050,7 +1176,7 @@
             // ====================
             minidomType;
             removeAsChildFromAnyParents() {
-                allNodes.forEach(node => node.removeChild(this));
+                allNodes.forEach((node) => node.removeChild(this));
             }
         }
         MiniDom.BaseNode = BaseNode;
@@ -1074,8 +1200,8 @@
             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());
                 });
             }
         }
@@ -1086,7 +1212,8 @@
         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;
@@ -1103,7 +1230,8 @@
         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;
         }
@@ -1136,7 +1264,14 @@
     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) => {
@@ -1146,7 +1281,12 @@
         });
         // RENDER
         if (renderer && scene && camera) {
-            renderer.render(scene, camera);
+            if (app.customRender) {
+                app.customRender(opts);
+            }
+            else {
+                renderer.render(vue.toRaw(scene), vue.toRaw(camera));
+            }
         }
         // AFTER RENDER
         afterRender.forEach((cb) => {
@@ -1154,22 +1294,6 @@
                 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) {
@@ -1179,6 +1303,15 @@
             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);
@@ -1187,6 +1320,15 @@
             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);
@@ -1292,10 +1434,7 @@
         'src',
     ];
 
-    const autoAttach = [
-        'geometry',
-        'material',
-    ];
+    const autoAttach = ['geometry', 'material'];
     const createElement = (type, isSVG, isCustomizedBuiltin, vnodeProps) => {
         const options = { type };
         if (vnodeProps) {
@@ -1310,7 +1449,7 @@
         // handle standard node
         const node = createNode(options);
         // autoattach
-        autoAttach.forEach(key => {
+        autoAttach.forEach((key) => {
             if (type.toLowerCase().endsWith(key)) {
                 node.props.attach = key;
             }
@@ -1350,17 +1489,19 @@
             }
             // 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
@@ -1443,19 +1584,29 @@
     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;
@@ -1463,7 +1614,7 @@
             // 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);
             }
@@ -1530,15 +1681,34 @@
         dpr: vue.ref(1),
         inputActive,
         mousePos,
-        camera: createdCamera,
-        renderer: createdRenderer,
-        scene: createdScene,
     };
-    const camera = vue.computed(() => globals.camera.value?.instance);
-    const renderer = vue.computed(() => globals.renderer.value?.instance);
-    const scene = vue.computed(() => globals.scene.value?.instance);
+    const camera = vue.computed(() => ensuredCamera.value?.instance ?? null);
+    const renderer = vue.computed(() => ensureRenderer.value?.instance ?? null);
+    const scene = vue.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 = vue.createRenderer(nodeOps).createApp(root);
+        app = vue.createRenderer(nodeOps).createApp(root);
         // register all components
         Object.keys(components).forEach((key) => {
             app.component(key, components[key]);
@@ -1561,27 +1731,38 @@
         };
         // 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;
     };
 
     exports.camera = camera;
+    exports.clearCustomRender = clearCustomRender;
     exports.createApp = createApp;
     exports.find = find;
     exports.globals = globals;
+    exports.offAfterRender = offAfterRender;
+    exports.offBeforeRender = offBeforeRender;
     exports.onAfterRender = onAfterRender;
     exports.onBeforeRender = onBeforeRender;
     exports.renderer = renderer;
     exports.scene = scene;
-    exports.update = update;
+    exports.setCustomRender = setCustomRender;
 
     Object.defineProperty(exports, '__esModule', { value: true });