@playcanvas/web-components 0.11.0 → 0.11.1

package/dist/pwc.js

@@ -7,12 +7,14 @@
     /**
      * Base class for all PlayCanvas Web Components that initialize asynchronously.
      *
-     * @fires {CustomEvent} ready - Fired once the element is fully initialized. Bubbles and is
-     * composed.
+     * @fires {CustomEvent} ready - Fired when the element is fully initialized — once per readiness
+     * cycle, so an element that is torn down and re-initialized (for example by removing and
+     * re-inserting it) fires it again. Bubbles and is composed.
      */
     class AsyncElement extends HTMLElement {
         _readyPromise;
         _readyResolve;
+        _readyResolved = false;
         /** @ignore */
         constructor() {
             super();
@@ -39,15 +41,39 @@
         /**
          * Called when the element is fully initialized and ready. Subclasses should call this when
          * they're ready. Resolves the ready promise and dispatches a bubbling, composed `ready`
-         * event.
+         * event. Signals at most once per readiness cycle: a repeat call before {@link _resetReady}
+         * has re-armed the promise does nothing.
          */
         _onReady() {
+            if (this._readyResolved)
+                return;
+            this._readyResolved = true;
             this._readyResolve();
             this.dispatchEvent(new CustomEvent('ready', { bubbles: true, composed: true }));
         }
+        /**
+         * Returns the ready promise to its pending state. Subclasses should call this when the
+         * resource their readiness announced is torn down (typically from `disconnectedCallback`),
+         * so that a later re-initialization can signal readiness again. Does nothing while the
+         * promise is still pending — an in-flight waiter carries over to the next readiness cycle
+         * rather than being stranded on a promise nothing will ever resolve.
+         */
+        _resetReady() {
+            if (!this._readyResolved)
+                return;
+            this._readyResolved = false;
+            this._readyPromise = new Promise((resolve) => {
+                this._readyResolve = resolve;
+            });
+        }
         /**
          * Returns a promise that resolves with this element when it's ready. This is the low-level
          * primitive underlying {@link whenReady}, which is the recommended way to wait for elements.
+         *
+         * Readiness tracks the element's current lifecycle: once a ready element is torn down (for
+         * example by removing it from the document), this returns a fresh promise that resolves when
+         * the element is next ready. A promise obtained earlier stays resolved — call this again
+         * after re-inserting an element rather than reusing a promise from before its removal.
          * @returns A promise that resolves with this element when it's ready.
          */
         ready() {
@@ -122,7 +148,14 @@
                 });
             }
         }
-        getLoadPromise() {
+        /**
+         * Returns the promise that settles when the module has loaded. Awaited by the containing
+         * `<pc-app>` element before it creates its graphics device.
+         *
+         * @returns The load promise.
+         * @internal
+         */
+        _getLoadPromise() {
             return this.loadPromise;
         }
     }
@@ -181,10 +214,7 @@
             // aria-valuenow is set, which is what marks a progressbar indeterminate. jsdom has no Web
             // Animations API, so the guard degrades to a static bar there rather than crashing boot.
             if (typeof this._fill.animate === 'function') {
-                this._sweep = this._fill.animate([
-                    { transform: 'scaleX(0.25) translateX(-100%)' },
-                    { transform: 'scaleX(0.25) translateX(500%)' }
-                ], {
+                this._sweep = this._fill.animate([{ transform: 'scaleX(0.25) translateX(-100%)' }, { transform: 'scaleX(0.25) translateX(500%)' }], {
                     duration: 1000,
                     iterations: Infinity,
                     easing: 'ease-in-out'
@@ -417,7 +447,7 @@
      */
     const parseComponents = (value, count) => {
         const components = value.trim().split(/\s+/).map(Number);
-        if (components.length !== count || components.some(component => !Number.isFinite(component))) {
+        if (components.length !== count || components.some((component) => !Number.isFinite(component))) {
             return null;
         }
         return components;
@@ -473,7 +503,10 @@
         if (/^#(?:[0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/i.test(value)) {
             let hex = value.slice(1);
             if (hex.length === 3 || hex.length === 4) {
-                hex = hex.split('').map(char => char + char).join('');
+                hex = hex
+                    .split('')
+                    .map((char) => char + char)
+                    .join('');
             }
             return new playcanvas.Color().fromString(`#${hex}`);
         }
@@ -570,7 +603,10 @@
             // caller's default, or a later mutation would write back through it.
             return [...defaultValue];
         }
-        return value.split(',').map(tag => tag.trim()).filter(tag => tag !== '');
+        return value
+            .split(',')
+            .map((tag) => tag.trim())
+            .filter((tag) => tag !== '');
     };
     /**
      * Parse a Vec2 attribute value. The expected format is 2 space-separated numbers (e.g. '1 2').
@@ -662,6 +698,8 @@
         return element?.entity ?? null;
     };
 
+    /** The pointer event types the application synthesizes on `<pc-entity>` elements via picking. */
+    const pointerEventTypes = ['pointermove', 'pointerdown', 'pointerup', 'pointerenter', 'pointerleave'];
     /**
      * The AppElement interface provides properties and methods for manipulating
      * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-app/ | `<pc-app>`} elements.
@@ -692,7 +730,20 @@
          */
         _optionsLocked = false;
         _bar = null;
+        /**
+         * Whether the application has created its initial entity hierarchy. Read by EntityElement to
+         * decide whether a newly connected element must create its entity itself or leave it to the
+         * boot sweep.
+         * @internal
+         */
         _hierarchyReady = false;
+        /**
+         * Incremented on every connect and disconnect. Boot captures the value on entry and abandons
+         * itself wherever it resumes from an await if the value has moved on — so a boot whose
+         * element was removed cannot complete against a torn-down element, and a boot whose element
+         * was removed and re-inserted (which starts a boot of its own) cannot race the newer one.
+         */
+        _bootGeneration = 0;
         /**
          * The elements backing this application's entities, keyed by the entity itself. Registered
          * by EntityElement at creation and removed when an entity is destroyed, this joins engine
@@ -745,8 +796,16 @@
             super();
             // Bind methods to maintain 'this' context
             this._onWindowResize = this._onWindowResize.bind(this);
+            // Track pointer listeners being added to and removed from descendant entities.
+            // Registered once here rather than on every boot - the handlers no-op while there is no
+            // canvas, and a re-booted element must not stack a second set.
+            pointerEventTypes.forEach((type) => {
+                this.addEventListener(`${type}:connect`, () => this._onPointerListenerAdded(type));
+                this.addEventListener(`${type}:disconnect`, () => this._onPointerListenerRemoved(type));
+            });
         }
         async connectedCallback() {
+            const generation = ++this._bootGeneration;
             // Created before the first await, so the bar is visible while modules and the graphics
             // device are created, and exists before any disconnect could need to clean it up
             if (this._loadingBar && !this._bar) {
@@ -755,7 +814,12 @@
             // Get all pc-module elements that are direct children of the pc-app element
             const moduleElements = this.querySelectorAll(':scope > pc-module');
             // Wait for all modules to load
-            await Promise.all(Array.from(moduleElements).map(module => module.getLoadPromise()));
+            await Promise.all(Array.from(moduleElements).map((module) => module._getLoadPromise()));
+            // The element may have been removed while the modules loaded. Nothing beyond the loading
+            // bar exists yet, and disconnectedCallback has already destroyed that.
+            if (generation !== this._bootGeneration) {
+                return;
+            }
             // Create and append the canvas to the element
             this._canvas = document.createElement('canvas');
             this.appendChild(this._canvas);
@@ -775,6 +839,13 @@
                 deviceTypes: deviceTypes,
                 stencil: this._stencilBuffer
             });
+            // The element may have been removed while the device was created. disconnectedCallback
+            // has already cleaned up the canvas; the device was created inside the await, so it is
+            // this boot's to release.
+            if (generation !== this._bootGeneration) {
+                device.destroy();
+                return;
+            }
             // Assigned rather than resolved to a number here: the engine caps against the live
             // window.devicePixelRatio on every resize, so an uncapped Infinity keeps following the
             // display when a window moves between monitors of differing density.
@@ -851,27 +922,41 @@
             this._pickerCreate();
             // Get all pc-asset elements that are direct children of the pc-app element
             const assetElements = this.querySelectorAll(':scope > pc-asset');
-            Array.from(assetElements).forEach((assetElement) => {
-                assetElement.createAsset();
+            for (const assetElement of Array.from(assetElements)) {
+                assetElement._createAsset();
                 const asset = assetElement.asset;
                 if (asset) {
                     app.assets.add(asset);
+                    // Adding a fileless asset (one built purely from data, such as a sprite)
+                    // completes it synchronously, dispatching the element's load event - whose
+                    // listeners may have removed this element. Stop before the next addition
+                    // reaches the destroyed registry, and before orphan entities are created.
+                    if (generation !== this._bootGeneration) {
+                        return;
+                    }
                 }
-            });
+            }
             // Get all pc-material elements that are direct children of the pc-app element
             const materialElements = this.querySelectorAll(':scope > pc-material');
             Array.from(materialElements).forEach((materialElement) => {
-                materialElement.createMaterial();
+                materialElement._createMaterial();
             });
             // Create all entities
             const entityElements = this.querySelectorAll('pc-entity');
             Array.from(entityElements).forEach((entityElement) => {
-                entityElement.createEntity(app);
+                entityElement._createEntity(app);
             });
             // Build hierarchy
             entityElements.forEach((entityElement) => {
-                entityElement.buildHierarchy(app);
+                entityElement._buildHierarchy(app);
             });
+            // Building the hierarchy dispatched each entity's ready event synchronously, and a
+            // listener may have removed the element. The sweep itself degrades safely - destroying
+            // the application nulls every element's entity, so the remaining builds no-op - but the
+            // teardown's reset must not be overwritten here.
+            if (generation !== this._bootGeneration) {
+                return;
+            }
             this._hierarchyReady = true;
             // Forward the engine's preload lifecycle as DOM ProgressEvents on this element. The
             // listener must be attached before preload() is called: an asset that is already loaded
@@ -888,8 +973,19 @@
             this._loadProgress = total === 0 ? 1 : 0;
             this._bar?.progress(0, total);
             this.dispatchEvent(new ProgressEvent('progress', { lengthComputable: true, loaded: 0, total }));
+            // The progress dispatch above ran listeners synchronously, and one may have removed the
+            // element. The application is already destroyed - it must not be asked to preload.
+            if (generation !== this._bootGeneration) {
+                return;
+            }
             // Load assets before starting the application
             app.preload(() => {
+                // The element may have been removed while assets loaded. The application is already
+                // destroyed, so it must not be started — and readiness must not be signaled for a
+                // boot that no longer owns the element.
+                if (generation !== this._bootGeneration) {
+                    return;
+                }
                 // Scope the counter to this preload pass, so a later app.preload() call by user code
                 // cannot push `loaded` past `total`
                 app.off('preload:progress', onPreloadProgress);
@@ -905,6 +1001,9 @@
             });
         }
         disconnectedCallback() {
+            // Invalidate any boot still in flight, so it abandons itself when it next resumes
+            // instead of completing against a torn-down element.
+            this._bootGeneration++;
             this._optionsLocked = false;
             this._pickerDestroy();
             // Clean up the application. Destroying it destroys every entity, whose destroy hooks
@@ -917,6 +1016,11 @@
             this._loadProgress = 0;
             this._bar?.destroy();
             this._bar = null;
+            // Return the element to its pre-boot state, so re-inserting it boots afresh: descendants
+            // must neither see a hierarchy that no longer exists nor resume against a readiness that
+            // no longer holds.
+            this._hierarchyReady = false;
+            this._resetReady();
             // Remove event listeners
             window.removeEventListener('resize', this._onWindowResize);
             // Remove the canvas
@@ -944,14 +1048,11 @@
             this._pointerHandlers.pointermove = listener(this._onPointerMove);
             this._pointerHandlers.pointerdown = listener(this._onPointerDown);
             this._pointerHandlers.pointerup = listener(this._onPointerUp);
-            // Listen for pointer listeners being added/removed
-            ['pointermove', 'pointerdown', 'pointerup', 'pointerenter', 'pointerleave'].forEach((type) => {
-                this.addEventListener(`${type}:connect`, () => this._onPointerListenerAdded(type));
-                this.addEventListener(`${type}:disconnect`, () => this._onPointerListenerRemoved(type));
-                // Attach canvas handlers for listeners registered before this point (e.g. handlers
-                // created from onpointer* attributes when their elements were first upgraded)
-                const anyListeners = Array.from(this.querySelectorAll('pc-entity'))
-                    .some(entity => entity.hasListeners(type));
+            // Attach canvas handlers for listeners registered before this boot (e.g. handlers
+            // created from onpointer* attributes when their elements were first upgraded, or
+            // listeners carried over from before a re-boot)
+            pointerEventTypes.forEach((type) => {
+                const anyListeners = Array.from(this.querySelectorAll('pc-entity')).some((entity) => entity._hasListeners(type));
                 if (anyListeners) {
                     this._onPointerListenerAdded(type);
                 }
@@ -966,6 +1067,7 @@
                 });
             }
             this._picker = null;
+            this._hoveredEntity = null;
             this._pointerHandlers = {
                 pointermove: null,
                 pointerdown: null,
@@ -985,7 +1087,7 @@
          *
          * @param entity - The entity.
          * @param element - The element that created it.
-         * @ignore
+         * @internal
          */
         _registerEntityElement(entity, element) {
             this._entityElements.set(entity, element);
@@ -994,7 +1096,7 @@
          * Removes the registration for a destroyed entity. Called by EntityElement.
          *
          * @param entity - The entity.
-         * @ignore
+         * @internal
          */
         _unregisterEntityElement(entity) {
             this._entityElements.delete(entity);
@@ -1040,7 +1142,7 @@
         _elementWithListener(node, type) {
             while (node !== null) {
                 const element = this._entityElements.get(node);
-                if (element?.hasListeners(type)) {
+                if (element?._hasListeners(type)) {
                     return element;
                 }
                 node = node.parent;
@@ -1097,17 +1199,17 @@
             const newHoverEntity = this._elementFromNode(node);
             // Handle enter/leave events
             if (this._hoveredEntity !== newHoverEntity) {
-                if (this._hoveredEntity && this._hoveredEntity.hasListeners('pointerleave')) {
+                if (this._hoveredEntity && this._hoveredEntity._hasListeners('pointerleave')) {
                     this._hoveredEntity.dispatchEvent(new PointerEvent('pointerleave', event));
                 }
-                if (newHoverEntity && newHoverEntity.hasListeners('pointerenter')) {
+                if (newHoverEntity && newHoverEntity._hasListeners('pointerenter')) {
                     newHoverEntity.dispatchEvent(new PointerEvent('pointerenter', event));
                 }
             }
             // Update hover state
             this._hoveredEntity = newHoverEntity;
             // Handle pointermove event
-            if (newHoverEntity && newHoverEntity.hasListeners('pointermove')) {
+            if (newHoverEntity && newHoverEntity._hasListeners('pointermove')) {
                 newHoverEntity.dispatchEvent(new PointerEvent('pointermove', event));
             }
         }
@@ -1137,22 +1239,21 @@
             if (!this._hasPointerListeners[type] && this._canvas) {
                 this._hasPointerListeners[type] = true;
                 // For enter/leave events, we need the move handler
-                const handler = (type === 'pointerenter' || type === 'pointerleave') ?
-                    this._pointerHandlers.pointermove :
-                    this._pointerHandlers[type];
+                const handler = type === 'pointerenter' || type === 'pointerleave'
+                    ? this._pointerHandlers.pointermove
+                    : this._pointerHandlers[type];
                 if (handler) {
                     this._canvas.addEventListener(type === 'pointerenter' || type === 'pointerleave' ? 'pointermove' : type, handler);
                 }
             }
         }
         _onPointerListenerRemoved(type) {
-            const hasListeners = Array.from(this.querySelectorAll('pc-entity'))
-                .some(entity => entity.hasListeners(type));
+            const hasListeners = Array.from(this.querySelectorAll('pc-entity')).some((entity) => entity._hasListeners(type));
             if (!hasListeners && this._canvas) {
                 this._hasPointerListeners[type] = false;
-                const handler = (type === 'pointerenter' || type === 'pointerleave') ?
-                    this._pointerHandlers.pointermove :
-                    this._pointerHandlers[type];
+                const handler = type === 'pointerenter' || type === 'pointerleave'
+                    ? this._pointerHandlers.pointermove
+                    : this._pointerHandlers[type];
                 if (handler) {
                     this._canvas.removeEventListener(type === 'pointerenter' || type === 'pointerleave' ? 'pointermove' : type, handler);
                 }
@@ -1233,14 +1334,6 @@
         get depthBuffer() {
             return this._depthBuffer;
         }
-        /**
-         * Gets the hierarchy ready flag.
-         * @returns The hierarchy ready flag.
-         * @ignore
-         */
-        get hierarchyReady() {
-            return this._hierarchyReady;
-        }
         /**
          * Sets whether the application shows its built-in loading bar while it boots and preloads its
          * assets. Enabled by default; setting `false` removes the bar immediately, while setting
@@ -1409,7 +1502,14 @@
         get entity() {
             return this._entity;
         }
-        createEntity(app) {
+        /**
+         * Creates the backing entity. Called by the containing `<pc-app>` element during its boot
+         * sweep, and on connection for elements inserted while the application is already running.
+         *
+         * @param app - The application to create the entity in.
+         * @internal
+         */
+        _createEntity(app) {
             // Guard against double creation. When a subtree is inserted at runtime (e.g. cloning a
             // `<template>`), an ancestor's connectedCallback eagerly creates descendant entities; the
             // descendants' own connectedCallbacks would otherwise create them a second time.
@@ -1440,8 +1540,10 @@
         }
         /**
          * Handles the destruction of the backing entity. Resets the element so a later re-insertion
-         * starts clean: `_built` must be cleared alongside `_entity`, or buildHierarchy would bail
-         * and a re-created entity would never be parented.
+         * starts clean: `_built` must be cleared alongside `_entity`, or _buildHierarchy would bail
+         * and a re-created entity would never be parented. Readiness is re-armed for the same
+         * reason — with the entity gone, a resolved ready promise would resume its awaiters against
+         * a null `entity`.
          *
          * @param entity - The entity that was destroyed.
          */
@@ -1450,8 +1552,18 @@
             this._appElement = null;
             this._entity = null;
             this._built = false;
+            this._resetReady();
         }
-        buildHierarchy(app) {
+        /**
+         * Parents the backing entity: under the entity of the nearest ancestor `<pc-entity>` when
+         * there is one, and under the application root otherwise. Called by the containing `<pc-app>`
+         * element once a sweep has created every entity, so a parent's existence never depends on
+         * document order.
+         *
+         * @param app - The application whose root adopts parentless entities.
+         * @internal
+         */
+        _buildHierarchy(app) {
             if (!this.entity || this._built)
                 return;
             this._built = true;
@@ -1477,17 +1589,17 @@
                 return;
             }
             // If app is already running, create entity immediately
-            if (closestApp.hierarchyReady) {
+            if (closestApp._hierarchyReady) {
                 const app = closestApp.app;
-                this.createEntity(app);
-                this.buildHierarchy(app);
+                this._createEntity(app);
+                this._buildHierarchy(app);
                 // Handle any child entities that might exist
                 const childEntities = this.querySelectorAll('pc-entity');
                 childEntities.forEach((child) => {
-                    child.createEntity(app);
+                    child._createEntity(app);
                 });
                 childEntities.forEach((child) => {
-                    child.buildHierarchy(app);
+                    child._buildHierarchy(app);
                 });
             }
         }
@@ -1681,14 +1793,23 @@
         }
         removeEventListener(type, listener, options) {
             if (this._listeners[type]) {
-                this._listeners[type] = this._listeners[type].filter(l => l !== listener);
+                this._listeners[type] = this._listeners[type].filter((l) => l !== listener);
             }
             super.removeEventListener(type, listener, options);
             if (type.startsWith('pointer')) {
                 this.dispatchEvent(new CustomEvent(`${type}:disconnect`, { bubbles: true }));
             }
         }
-        hasListeners(type) {
+        /**
+         * Whether the element has a listener for an event type, registered either with
+         * {@link addEventListener} or with the matching inline `onpointer*` attribute. Read by the
+         * containing `<pc-app>` element to gate pointer event synthesis.
+         *
+         * @param type - The event type.
+         * @returns Whether a listener is registered.
+         * @internal
+         */
+        _hasListeners(type) {
             return Boolean(this._listeners[type]?.length) || this._inlineHandlerTypes.has(type);
         }
     }
@@ -1979,7 +2100,7 @@
                 const app = appElement.app;
                 if (!app)
                     return; // pc-app is re-connecting; its own boot will create this asset
-                this.createAsset();
+                this._createAsset();
                 if (this.asset) {
                     app.assets.add(this.asset); // add() auto-loads when preload is true
                     if (!this.lazy) {
@@ -1987,13 +2108,15 @@
                     }
                 }
             }
-            // Never ready if createAsset failed (unsupported asset type)
+            // Never ready if _createAsset failed (unsupported asset type)
             if (this.asset) {
                 this._onReady();
             }
         }
         disconnectedCallback() {
-            this.destroyAsset();
+            this._destroyAsset();
+            // Re-arm readiness so a re-inserted element announces the asset it creates then
+            this._resetReady();
         }
         _onAssetLoad() {
             this.dispatchEvent(new Event('load'));
@@ -2003,7 +2126,14 @@
                 message: err instanceof Error ? err.message : String(err)
             }));
         }
-        createAsset() {
+        /**
+         * Creates the asset from the element's attributes. Called by the containing `<pc-app>`
+         * element during its boot sweep, and on connection for elements inserted while the
+         * application is already running.
+         *
+         * @internal
+         */
+        _createAsset() {
             const id = this.getAttribute('id') || '';
             const src = this.getAttribute('src') || '';
             let type = this.getAttribute('type');
@@ -2093,7 +2223,7 @@
             }
             return data;
         }
-        destroyAsset() {
+        _destroyAsset() {
             if (this.asset) {
                 // A caller that keeps the Asset alive must not dispatch on a removed element
                 this.asset.off('load', this._onAssetLoad, this);
@@ -2121,6 +2251,13 @@
         get lazy() {
             return this._lazy;
         }
+        /**
+         * Returns the {@link Asset} created by the `<pc-asset>` element with the given `id`, or
+         * `undefined` if there is no such element or its asset has not been created yet.
+         *
+         * @param id - The `id` of the `<pc-asset>` element.
+         * @returns The asset, or `undefined`.
+         */
         static get(id) {
             const assetElement = document.querySelector(`pc-asset[id="${id}"]`);
             return assetElement?.asset;
@@ -2146,6 +2283,14 @@
         _enabled = true;
         _component = null;
         _appElement = null;
+        /**
+         * Incremented on every connect and disconnect. connectedCallback captures the value on entry
+         * and abandons itself wherever it resumes from an await if the value has moved on — so a
+         * callback whose element was removed cannot act on a torn-down tree, and one whose element
+         * was removed and re-inserted (which runs a callback of its own) cannot add the component a
+         * second time.
+         */
+        _connectionGeneration = 0;
         /**
          * Creates a new ComponentElement instance.
          *
@@ -2156,11 +2301,17 @@
             super();
             this._componentName = componentName;
         }
-        // Method to be overridden by subclasses to provide initial component data
+        /**
+         * Returns the data the component is created with. Overridden by subclasses to supply the
+         * initial values of their cached properties.
+         *
+         * @returns The initial component data.
+         */
         getInitialComponentData() {
             return {};
         }
-        async addComponent() {
+        async _addComponent() {
+            const generation = this._connectionGeneration;
             const entityElement = this.closestEntity;
             if (!entityElement) {
                 // A component can only exist on an entity, so an element placed outside one is inert.
@@ -2170,19 +2321,42 @@
                 return;
             }
             await entityElement.ready();
+            // The element may have been removed, or removed and re-inserted, while the entity became
+            // ready — the component belongs to the connection that owns the current generation.
+            if (generation !== this._connectionGeneration) {
+                return;
+            }
             // Add the component to the entity
             const data = this.getInitialComponentData();
             this._component = entityElement.entity.addComponent(this._componentName, data);
         }
-        initComponent() { }
+        /**
+         * Configures the newly added component. Overridden by subclasses whose setup goes beyond
+         * the initial data — child-element handling, asset resolution and the like.
+         */
+        initComponent() {
+            // optional hook
+        }
         async connectedCallback() {
+            const generation = ++this._connectionGeneration;
             this._appElement = this.closestApp ?? null;
             await this._appElement?.ready();
-            await this.addComponent();
+            // The element may have been removed, or removed and re-inserted, while the application
+            // became ready. A re-insertion runs a connectedCallback of its own, so a stale resume
+            // must not add the component alongside it.
+            if (generation !== this._connectionGeneration) {
+                return;
+            }
+            await this._addComponent();
+            if (generation !== this._connectionGeneration) {
+                return;
+            }
             this.initComponent();
             this._onReady();
         }
         disconnectedCallback() {
+            // Invalidate any connectedCallback still suspended on an await
+            this._connectionGeneration++;
             // Remove the component when the element is disconnected. Skip this when the owning
             // application has already been destroyed — removing a <pc-app> disconnects it before
             // its children, taking the component systems with it.
@@ -2191,6 +2365,7 @@
             }
             this._component = null;
             this._appElement = null;
+            this._resetReady();
         }
         /**
          * The PlayCanvas component instance. `null` until the element is ready, and also for an
@@ -3248,7 +3423,17 @@
             return this._type;
         }
         static get observedAttributes() {
-            return [...super.observedAttributes, 'angular-offset', 'axis', 'convex-hull', 'half-extents', 'height', 'linear-offset', 'radius', 'type'];
+            return [
+                ...super.observedAttributes,
+                'angular-offset',
+                'axis',
+                'convex-hull',
+                'half-extents',
+                'height',
+                'linear-offset',
+                'radius',
+                'type'
+            ];
         }
         attributeChangedCallback(name, _oldValue, newValue) {
             super.attributeChangedCallback(name, _oldValue, newValue);
@@ -4953,7 +5138,7 @@
             }
             // Set all the config properties on the component
             for (const key in resource) {
-                if (resource.hasOwnProperty(key)) {
+                if (Object.hasOwn(resource, key)) {
                     this.component[key] = resource[key];
                 }
             }
@@ -5026,10 +5211,7 @@
             }
         }
         static get observedAttributes() {
-            return [
-                ...super.observedAttributes,
-                'asset'
-            ];
+            return [...super.observedAttributes, 'asset'];
         }
         attributeChangedCallback(name, _oldValue, newValue) {
             super.attributeChangedCallback(name, _oldValue, newValue);
@@ -5189,7 +5371,7 @@
         _twoSidedLighting = false;
         _useFog = true;
         _useLighting = true;
-        // Diverges from the engine default of false - see the class docblock and createMaterial()
+        // Diverges from the engine default of false - see the class docblock and _createMaterial()
         _useMetalness = true;
         _useMetalnessSpecularColor = false;
         _useSkybox = true;
@@ -5202,6 +5384,10 @@
         _mapHandles = new Map();
         _updateScheduled = false;
         _glossConflictWarned = false;
+        /**
+         * The material. `null` until the containing application has created it — an element present
+         * at startup has its material once the application is ready.
+         */
         material = null;
         async connectedCallback() {
             const appElement = this.parentElement?.closest('pc-app') ?? null;
@@ -5219,10 +5405,17 @@
             if (!this.material) {
                 if (!appElement.app)
                     return; // pc-app is re-connecting; its own boot will create this
-                this.createMaterial();
+                this._createMaterial();
             }
         }
-        createMaterial() {
+        /**
+         * Creates the material from the element's cached properties. Called by the containing
+         * `<pc-app>` element during its boot sweep, and on connection for elements inserted while
+         * the application is already running.
+         *
+         * @internal
+         */
+        _createMaterial() {
             const material = new playcanvas.StandardMaterial();
             this.material = material;
             material.alphaTest = this._alphaTest;
@@ -5349,9 +5542,9 @@
          * warning latches and reports once per episode, clearing when the clash is resolved.
          */
         _warnGlossConflict() {
-            const quote = (names) => `'${names.join('\', \'')}'`;
-            const roughness = roughnessAliases.filter(name => this.hasAttribute(name));
-            const gloss = glossConflicts.filter(name => this.hasAttribute(name));
+            const quote = (names) => `'${names.join("', '")}'`;
+            const roughness = roughnessAliases.filter((name) => this.hasAttribute(name));
+            const gloss = glossConflicts.filter((name) => this.hasAttribute(name));
             if (roughness.length === 0 || gloss.length === 0) {
                 this._glossConflictWarned = false;
                 return;
@@ -5369,7 +5562,7 @@
          * @param id - The id of the `pc-asset`, or an empty string to clear the slot.
          * @param slot - The material property to write.
          */
-        setMap(id, slot) {
+        _setMap(id, slot) {
             // Drop any load still pending for this slot - its texture is no longer the one we want
             this._mapHandles.get(slot)?.off();
             this._mapHandles.delete(slot);
@@ -5463,7 +5656,7 @@
          */
         set aoMap(value) {
             this._aoMap = value;
-            this.setMap(value, 'aoMap');
+            this._setMap(value, 'aoMap');
         }
         /**
          * Gets the id of the `pc-asset` used as the ambient occlusion map.
@@ -5695,7 +5888,7 @@
          */
         set diffuseMap(value) {
             this._diffuseMap = value;
-            this.setMap(value, 'diffuseMap');
+            this._setMap(value, 'diffuseMap');
         }
         /**
          * Gets the id of the `pc-asset` used as the diffuse map.
@@ -5836,7 +6029,7 @@
          */
         set emissiveMap(value) {
             this._emissiveMap = value;
-            this.setMap(value, 'emissiveMap');
+            this._setMap(value, 'emissiveMap');
         }
         /**
          * Gets the id of the `pc-asset` used as the emissive map.
@@ -6014,7 +6207,7 @@
          */
         set glossMap(value) {
             this._glossMap = value;
-            this.setMap(value, 'glossMap');
+            this._setMap(value, 'glossMap');
         }
         /**
          * Gets the id of the `pc-asset` used as the gloss map.
@@ -6119,7 +6312,7 @@
          */
         set heightMap(value) {
             this._heightMap = value;
-            this.setMap(value, 'heightMap');
+            this._setMap(value, 'heightMap');
         }
         /**
          * Gets the id of the `pc-asset` used as the height map.
@@ -6260,7 +6453,7 @@
          */
         set metalnessMap(value) {
             this._metalnessMap = value;
-            this.setMap(value, 'metalnessMap');
+            this._setMap(value, 'metalnessMap');
         }
         /**
          * Gets the id of the `pc-asset` used as the metalness map.
@@ -6365,7 +6558,7 @@
          */
         set normalMap(value) {
             this._normalMap = value;
-            this.setMap(value, 'normalMap');
+            this._setMap(value, 'normalMap');
         }
         /**
          * Gets the id of the `pc-asset` used as the normal map.
@@ -6453,7 +6646,7 @@
         set occludeDirect(value) {
             this._occludeDirect = value;
             if (this.material) {
-                // @ts-ignore see createMaterial() - the engine mistypes occludeDirect as a number
+                // @ts-ignore see _createMaterial() - the engine mistypes occludeDirect as a number
                 this.material.occludeDirect = value;
                 this._scheduleUpdate();
             }
@@ -6545,7 +6738,7 @@
          */
         set opacityMap(value) {
             this._opacityMap = value;
-            this.setMap(value, 'opacityMap');
+            this._setMap(value, 'opacityMap');
         }
         /**
          * Gets the id of the `pc-asset` used as the opacity map.
@@ -6863,6 +7056,13 @@
         get useTonemap() {
             return this._useTonemap;
         }
+        /**
+         * Returns the {@link StandardMaterial} created by the `<pc-material>` element with the given
+         * `id`, or `undefined` if there is no such element or its material has not been created yet.
+         *
+         * @param id - The `id` of the `<pc-material>` element.
+         * @returns The material, or `undefined`.
+         */
         static get(id) {
             const materialElement = document.querySelector(`pc-material[id="${id}"]`);
             return materialElement?.material;
@@ -7501,7 +7701,18 @@
             return this._type;
         }
         static get observedAttributes() {
-            return [...super.observedAttributes, 'angular-damping', 'angular-factor', 'friction', 'linear-damping', 'linear-factor', 'mass', 'restitution', 'rolling-friction', 'type'];
+            return [
+                ...super.observedAttributes,
+                'angular-damping',
+                'angular-factor',
+                'friction',
+                'linear-damping',
+                'linear-factor',
+                'mass',
+                'restitution',
+                'rolling-friction',
+                'type'
+            ];
         }
         attributeChangedCallback(name, _oldValue, newValue) {
             super.attributeChangedCallback(name, _oldValue, newValue);
@@ -7806,13 +8017,7 @@
             return this._handle;
         }
         static get observedAttributes() {
-            return [
-                ...super.observedAttributes,
-                'orientation',
-                'value',
-                'handle-size',
-                'handle'
-            ];
+            return [...super.observedAttributes, 'orientation', 'value', 'handle-size', 'handle'];
         }
         attributeChangedCallback(name, _oldValue, newValue) {
             super.attributeChangedCallback(name, _oldValue, newValue);
@@ -8038,7 +8243,8 @@
         set horizontalScrollbarVisibility(value) {
             this._horizontalScrollbarVisibility = value;
             if (this.component) {
-                this.component.horizontalScrollbarVisibility = visibilities.get(value) ?? playcanvas.SCROLLBAR_VISIBILITY_SHOW_WHEN_REQUIRED;
+                this.component.horizontalScrollbarVisibility =
+                    visibilities.get(value) ?? playcanvas.SCROLLBAR_VISIBILITY_SHOW_WHEN_REQUIRED;
             }
         }
         /**
@@ -8056,7 +8262,8 @@
         set verticalScrollbarVisibility(value) {
             this._verticalScrollbarVisibility = value;
             if (this.component) {
-                this.component.verticalScrollbarVisibility = visibilities.get(value) ?? playcanvas.SCROLLBAR_VISIBILITY_SHOW_WHEN_REQUIRED;
+                this.component.verticalScrollbarVisibility =
+                    visibilities.get(value) ?? playcanvas.SCROLLBAR_VISIBILITY_SHOW_WHEN_REQUIRED;
             }
         }
         /**
@@ -8243,15 +8450,9 @@
     class ScriptElement extends AsyncElement {
         _attributes = {};
         _enabled = true;
-        /**
-         * Whether readiness has been signalled. Creation can happen more than once over an
-         * element's life (a runtime `name` change recreates the instance), but `ready` is a
-         * one-shot signal, so only the first successful creation fires it.
-         */
-        _readySignalled = false;
         /**
          * The Script instance created for this element by its parent `<pc-scripts>` element.
-         * @ignore
+         * @internal
          */
         _script = null;
         /**
@@ -8333,14 +8534,20 @@
                 console.warn(`pc-script '${this.getAttribute('name')}' must be a direct child of pc-scripts - script not created`);
             }
         }
+        disconnectedCallback() {
+            // Re-arm readiness so a re-inserted element announces the instance created for it then.
+            // `_script` is deliberately NOT cleared here: the parent's mutation observer processes
+            // this removal afterwards and reads it to establish which engine script this element
+            // owned - the parent is what clears it.
+            this._resetReady();
+        }
         /**
          * Called by the parent `<pc-scripts>` element when the script instance has been created.
-         * @ignore
+         * Creation can happen more than once per connection (a runtime `name` change recreates the
+         * instance), but `_onReady` signals readiness at most once per cycle.
+         * @internal
          */
         _onScriptCreated() {
-            if (this._readySignalled)
-                return;
-            this._readySignalled = true;
             this._onReady();
         }
         static get observedAttributes() {
@@ -8385,10 +8592,34 @@
      */
     const RESERVED_ATTRIBUTES = new Set([
         ...ScriptElement.observedAttributes,
-        'accesskey', 'autocapitalize', 'autofocus', 'class', 'contenteditable', 'dir', 'draggable',
-        'exportparts', 'hidden', 'id', 'inert', 'is', 'itemid', 'itemprop', 'itemref', 'itemscope',
-        'itemtype', 'lang', 'nonce', 'part', 'popover', 'role', 'slot', 'spellcheck', 'style',
-        'tabindex', 'title', 'translate'
+        'accesskey',
+        'autocapitalize',
+        'autofocus',
+        'class',
+        'contenteditable',
+        'dir',
+        'draggable',
+        'exportparts',
+        'hidden',
+        'id',
+        'inert',
+        'is',
+        'itemid',
+        'itemprop',
+        'itemref',
+        'itemscope',
+        'itemtype',
+        'lang',
+        'nonce',
+        'part',
+        'popover',
+        'role',
+        'slot',
+        'spellcheck',
+        'style',
+        'tabindex',
+        'title',
+        'translate'
     ]);
     /**
      * Checks whether a `pc-script` attribute name is reserved (and so never maps to a script
@@ -8400,18 +8631,25 @@
      * @returns Whether the attribute name is reserved.
      */
     const isReservedAttribute = (name) => {
-        return RESERVED_ATTRIBUTES.has(name) ||
+        return (RESERVED_ATTRIBUTES.has(name) ||
             name.startsWith('data-') ||
             name.startsWith('aria-') ||
             name.startsWith('_') ||
-            (name.startsWith('on') && name in HTMLElement.prototype);
+            (name.startsWith('on') && name in HTMLElement.prototype));
     };
     /**
      * Script API members that per-property attributes must never overwrite: the engine bindings and
      * the (optional, so possibly undefined) lifecycle methods.
      */
     const SCRIPT_API_MEMBERS = new Set([
-        'app', 'entity', 'destroy', 'initialize', 'postInitialize', 'postUpdate', 'swap', 'update'
+        'app',
+        'entity',
+        'destroy',
+        'initialize',
+        'postInitialize',
+        'postUpdate',
+        'swap',
+        'update'
     ]);
     /**
      * Converts a kebab-case attribute name to the camelCase script attribute name.
@@ -8427,7 +8665,7 @@
      * @returns The kebab-case name.
      */
     const camelToKebab = (name) => {
-        return name.replace(/[A-Z]/g, char => `-${char.toLowerCase()}`);
+        return name.replace(/[A-Z]/g, (char) => `-${char.toLowerCase()}`);
     };
     /**
      * Resolves an `asset:` prefix to the Asset created by the `pc-asset` element with that id.
@@ -8626,7 +8864,10 @@
                 // Only recurse into plain objects. Class instances (Vec3, Color, Asset, Entity...)
                 // are leaf values assigned whole, so accessor-typed script attributes receive them
                 // through their setters instead of having a getter's returned copy mutated.
-                if (value && typeof value === 'object' && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype) {
+                if (value &&
+                    typeof value === 'object' &&
+                    !Array.isArray(value) &&
+                    Object.getPrototypeOf(value) === Object.prototype) {
                     if (!current || typeof current !== 'object') {
                         target[key] = {};
                     }
@@ -8644,7 +8885,11 @@
          * @returns Whether the value is a math type.
          */
         isMathType(value) {
-            return value instanceof playcanvas.Vec2 || value instanceof playcanvas.Vec3 || value instanceof playcanvas.Vec4 || value instanceof playcanvas.Color || value instanceof playcanvas.Quat;
+            return (value instanceof playcanvas.Vec2 ||
+                value instanceof playcanvas.Vec3 ||
+                value instanceof playcanvas.Vec4 ||
+                value instanceof playcanvas.Color ||
+                value instanceof playcanvas.Quat);
         }
         /**
          * Converts a plain numeric array to the math type of `current`. A 3-element array targeting
@@ -8657,7 +8902,7 @@
          * @returns The converted value, or `null`.
          */
         arrayToMathType(current, value, key) {
-            if (value.every(component => typeof component === 'number' && Number.isFinite(component))) {
+            if (value.every((component) => typeof component === 'number' && Number.isFinite(component))) {
                 if (current instanceof playcanvas.Vec2 && value.length === 2)
                     return new playcanvas.Vec2(value);
                 if (current instanceof playcanvas.Vec3 && value.length === 3)
@@ -8929,7 +9174,10 @@
                 mutation.removedNodes.forEach((node) => {
                     if (node instanceof ScriptElement) {
                         const scriptName = node.getAttribute('name');
-                        if (scriptName && node._script && this.component && this.component.get(scriptName) === node._script) {
+                        if (scriptName &&
+                            node._script &&
+                            this.component &&
+                            this.component.get(scriptName) === node._script) {
                             this.destroyScript(scriptName);
                         }
                         node._script = null;
@@ -9178,18 +9426,27 @@
          * emit a misleading "must be a direct child" warning for what is an ordinary removal.
          */
         _soundElement = null;
+        /**
+         * Incremented on every connect and disconnect, and captured by connectedCallback on entry —
+         * a resume from an await abandons itself if the value has moved on, so a stale callback can
+         * neither act on a torn-down tree nor add its slot alongside a re-inserted element's own
+         * callback.
+         */
+        _connectionGeneration = 0;
         /**
          * The sound slot.
          */
         soundSlot = null;
         async connectedCallback() {
+            const generation = ++this._connectionGeneration;
             const soundElement = this.soundElement;
             await soundElement?.ready();
-            // The element may have been removed, or its parent torn down, while we were waiting. A
-            // <pc-app> disconnects before its children, so by the time we resume the component can
-            // already be gone - see the matching guard in disconnectedCallback below.
+            // The element may have been removed (perhaps re-inserted, which runs a callback of its
+            // own), or its parent torn down, while we were waiting. A <pc-app> disconnects before
+            // its children, so by the time we resume the component can already be gone - see the
+            // matching guard in disconnectedCallback below.
             const component = soundElement?.component;
-            if (!this.isConnected || !component) {
+            if (generation !== this._connectionGeneration || !component) {
                 return;
             }
             const options = {
@@ -9212,12 +9469,15 @@
             this._onReady();
         }
         disconnectedCallback() {
+            // Invalidate any connectedCallback still suspended on an await
+            this._connectionGeneration++;
             // Uses the cached parent rather than a fresh lookup, since parentElement is already null
             // by now. The component itself is null if the parent <pc-sound> (or the whole <pc-app>) is
             // being torn down — parents disconnect first and have already removed the component.
             this._soundElement?.component?.removeSlot(this._name);
             this._soundElement = null;
             this.soundSlot = null;
+            this._resetReady();
         }
         get soundElement() {
             const soundElement = this.parentElement;
@@ -9617,39 +9877,85 @@
     class ModelElement extends AsyncElement {
         _asset = '';
         _entity = null;
+        /**
+         * Incremented on every new load and on disconnect, and captured by a load when it starts. A
+         * load that resumes from an await or a load callback abandons itself if the value has moved
+         * on, so a superseded load can neither instantiate a second entity nor parent one that has
+         * since been destroyed.
+         */
+        _loadGeneration = 0;
+        /**
+         * The pending asset-load subscription of the current load, if it is waiting for its asset.
+         * Held so that whatever supersedes the load can detach the handler from the asset, rather
+         * than leave it registered until the asset loads (or forever, if it never does).
+         */
+        _loadHandle = null;
+        /**
+         * The root entity of the instantiated model. `null` until the container asset has loaded
+         * and been instantiated, and again once the element has been removed from the document.
+         * @returns The model's root entity, or `null`.
+         */
+        get entity() {
+            return this._entity;
+        }
         connectedCallback() {
             this._loadModel();
             this._onReady();
         }
         disconnectedCallback() {
+            this._loadGeneration++;
+            this._detachLoadHandler();
             this._unloadModel();
+            this._resetReady();
+        }
+        _detachLoadHandler() {
+            this._loadHandle?.off();
+            this._loadHandle = null;
         }
         _instantiate(container) {
-            this._entity = container.instantiateRenderEntity();
+            const generation = this._loadGeneration;
+            const entity = container.instantiateRenderEntity();
+            this._entity = entity;
             // @ts-ignore
             if (container.animations.length > 0) {
-                this._entity.addComponent('anim');
+                entity.addComponent('anim');
                 // @ts-ignore
-                this._entity.anim.assignAnimation('animation', container.animations[0].resource);
+                entity.anim.assignAnimation('animation', container.animations[0].resource);
             }
+            // The parent's readiness re-arms when it is torn down, so these can resume in a later
+            // connection cycle. The entity is captured above and the generation re-checked, so a
+            // stale resume cannot parent an entity a newer cycle has already destroyed.
             const parentEntityElement = this.closestEntity;
             if (parentEntityElement) {
                 parentEntityElement.ready().then(() => {
-                    parentEntityElement.entity.addChild(this._entity);
+                    if (generation !== this._loadGeneration) {
+                        return;
+                    }
+                    parentEntityElement.entity.addChild(entity);
                 });
             }
             else {
                 const appElement = this.closestApp;
                 if (appElement) {
                     appElement.ready().then(() => {
-                        appElement.app.root.addChild(this._entity);
+                        if (generation !== this._loadGeneration) {
+                            return;
+                        }
+                        appElement.app.root.addChild(entity);
                     });
                 }
             }
         }
         async _loadModel() {
             this._unloadModel();
+            // Supersede any load already in flight - only the newest load may instantiate
+            const generation = ++this._loadGeneration;
+            this._detachLoadHandler();
             const appElement = await this.closestApp?.ready();
+            // The element may have been removed, or another load started, while we waited
+            if (generation !== this._loadGeneration) {
+                return;
+            }
             const app = appElement?.app;
             const asset = AssetElement.get(this._asset);
             if (!asset) {
@@ -9659,7 +9965,14 @@
                 this._instantiate(asset.resource);
             }
             else {
-                asset.once('load', () => {
+                // The generation is re-checked even though a superseded handler is detached: the
+                // detach relies on how the engine's event emitter treats removal, while the check
+                // holds on its own.
+                this._loadHandle = asset.once('load', () => {
+                    this._loadHandle = null;
+                    if (generation !== this._loadGeneration) {
+                        return;
+                    }
                     this._instantiate(asset.resource);
                 });
                 app.assets.load(asset);
@@ -9761,10 +10074,17 @@
                 return;
             }
             this._scene = app.scene;
-            this.updateSceneSettings();
+            this._updateSceneSettings();
             this._onReady();
         }
-        updateSceneSettings() {
+        disconnectedCallback() {
+            // The scene belongs to the application, and removing this element - or the <pc-app>
+            // above it, which disconnects first - parts the two. Re-arm readiness so a re-inserted
+            // element announces the scene it acquires then, not the one it lost here.
+            this._scene = null;
+            this._resetReady();
+        }
+        _updateSceneSettings() {
             if (this._scene) {
                 this._scene.fog.type = this._fog;
                 this._scene.fog.color = this._fogColor;
@@ -9932,13 +10252,32 @@
         _type = 'infinite';
         _scene = null;
         _appElement = null;
+        /**
+         * Incremented on every new load and on disconnect, and captured by a load when it starts. A
+         * load that resumes from an await or a load callback abandons itself if the value has moved
+         * on, so a superseded load cannot generate a skybox for a scene it no longer configures.
+         */
+        _loadGeneration = 0;
+        /**
+         * The pending asset-load subscription of the current load, if it is waiting for its asset.
+         * Held so that whatever supersedes the load can detach the handler from the asset, rather
+         * than leave it registered until the asset loads (or forever, if it never does).
+         */
+        _loadHandle = null;
         connectedCallback() {
             this._loadSkybox();
             this._onReady();
         }
         disconnectedCallback() {
+            this._loadGeneration++;
+            this._detachLoadHandler();
             this._unloadSkybox();
             this._appElement = null;
+            this._resetReady();
+        }
+        _detachLoadHandler() {
+            this._loadHandle?.off();
+            this._loadHandle = null;
         }
         _generateSkybox(asset) {
             if (!this._scene)
@@ -9946,10 +10285,17 @@
             const source = asset.resource;
             const skybox = playcanvas.EnvLighting.generateSkyboxCubemap(source);
             skybox.anisotropy = 4;
+            // This element owns what it generated (see _unloadSkybox) - replacing a skybox from an
+            // earlier load must release it, not orphan it on the GPU
+            this._scene.skybox?.destroy();
             this._scene.skybox = skybox;
             if (this._lighting) {
                 const lighting = playcanvas.EnvLighting.generateLightingSource(source);
                 const envAtlas = playcanvas.EnvLighting.generateAtlas(lighting);
+                // The lighting source is an intermediate: the atlas is rendered from it and it is
+                // not needed afterwards
+                lighting.destroy();
+                this._scene.envAtlas?.destroy();
                 this._scene.envAtlas = envAtlas;
             }
             const layer = this._scene.layers.getLayerById(playcanvas.LAYERID_SKYBOX);
@@ -9963,7 +10309,14 @@
             this._scene.skyboxMip = this._mipLevel;
         }
         async _loadSkybox() {
+            // Supersede any load already in flight - only the newest load may generate the skybox
+            const generation = ++this._loadGeneration;
+            this._detachLoadHandler();
             const appElement = await this.closestApp?.ready();
+            // The element may have been removed, or another load started, while we waited
+            if (generation !== this._loadGeneration) {
+                return;
+            }
             const app = appElement?.app;
             if (!appElement || !app) {
                 return;
@@ -9978,7 +10331,14 @@
                 this._generateSkybox(asset);
             }
             else {
-                asset.once('load', () => {
+                // The generation is re-checked even though a superseded handler is detached: the
+                // detach relies on how the engine's event emitter treats removal, while the check
+                // holds on its own.
+                this._loadHandle = asset.once('load', () => {
+                    this._loadHandle = null;
+                    if (generation !== this._loadGeneration) {
+                        return;
+                    }
                     this._generateSkybox(asset);
                 });
                 app.assets.load(asset);