@playcanvas/web-components 0.10.1 → 0.11.1

package/dist/pwc.cjs

@@ -5,12 +5,14 @@ var playcanvas = require('playcanvas');
 /**
  * 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();
@@ -37,15 +39,39 @@ class AsyncElement extends HTMLElement {
     /**
      * 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() {
@@ -120,7 +146,14 @@ class ModuleElement extends HTMLElement {
             });
         }
     }
-    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;
     }
 }
@@ -179,10 +212,7 @@ class LoadingBar {
         // 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'
@@ -415,7 +445,7 @@ const CSS_COLORS = {
  */
 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;
@@ -471,7 +501,10 @@ const parseColor = (value, defaultValue, attribute) => {
     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}`);
     }
@@ -489,7 +522,9 @@ const parseColor = (value, defaultValue, attribute) => {
  * the value is invalid — the latter also logs a warning listing the valid names.
  *
  * @param value - The attribute value to parse (`null` when the attribute is absent).
- * @param valid - The valid names: an array, or a map whose keys are the valid names.
+ * @param valid - The valid names: an array, or a map whose keys are the valid names. Only the keys
+ * are read, so the map's value type is unconstrained - engine enums are mostly numeric constants,
+ * but some (e.g. `SCALEMODE_BLEND`) are strings.
  * @param defaultValue - The value to use when the attribute is absent or invalid.
  * @param attribute - The attribute name, used in the warning message.
  * @returns The resolved enum name.
@@ -566,7 +601,10 @@ const parseTags = (value, defaultValue = []) => {
         // 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').
@@ -658,6 +696,8 @@ const getEntity = (ref) => {
     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.
@@ -677,12 +717,37 @@ class AppElement extends AsyncElement {
     _alpha = true;
     _backend = 'webgpu';
     _antialias = true;
-    _depth = true;
-    _stencil = true;
-    _highResolution = true;
+    _depthBuffer = true;
+    _stencilBuffer = true;
+    _maxPixelRatio = Infinity;
     _loadingBar = true;
+    /**
+     * Set once the graphics options above have been handed to `createGraphicsDevice`, after which
+     * writing any of them changes nothing. Guards the warning in {@link _warnIfBooted}, and is
+     * cleared on disconnect so a re-connected element boots from its current attributes.
+     */
+    _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
+     * scene nodes back to their owning elements by identity - never by name.
+     */
+    _entityElements = new Map();
     _picker = null;
     _hasPointerListeners = {
         pointerenter: false,
@@ -729,8 +794,16 @@ class AppElement extends AsyncElement {
         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) {
@@ -739,7 +812,12 @@ class AppElement extends AsyncElement {
         // 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);
@@ -750,15 +828,26 @@ class AppElement extends AsyncElement {
             null: ['null']
         };
         const deviceTypes = backendToDeviceTypes[this._backend] || [];
+        this._optionsLocked = true;
         const device = await playcanvas.createGraphicsDevice(this._canvas, {
             // @ts-ignore - alpha needs to be documented
             alpha: this._alpha,
             antialias: this._antialias,
-            depth: this._depth,
+            depth: this._depthBuffer,
             deviceTypes: deviceTypes,
-            stencil: this._stencil
+            stencil: this._stencilBuffer
         });
-        device.maxPixelRatio = this._highResolution ? window.devicePixelRatio : 1;
+        // 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.
+        device.maxPixelRatio = this._maxPixelRatio;
         const createOptions = new playcanvas.AppOptions();
         createOptions.graphicsDevice = device;
         createOptions.keyboard = new playcanvas.Keyboard(window);
@@ -831,27 +920,41 @@ class AppElement extends AsyncElement {
         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
@@ -868,8 +971,19 @@ class AppElement extends AsyncElement {
         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);
@@ -885,15 +999,26 @@ class AppElement extends AsyncElement {
         });
     }
     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
+        // Clean up the application. Destroying it destroys every entity, whose destroy hooks
+        // unregister them - clear() covers any entity the engine no longer reached.
         if (this._app) {
             this._app.destroy();
             this._app = null;
         }
+        this._entityElements.clear();
         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
@@ -921,14 +1046,11 @@ class AppElement extends AsyncElement {
         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);
             }
@@ -943,6 +1065,7 @@ class AppElement extends AsyncElement {
             });
         }
         this._picker = null;
+        this._hoveredEntity = null;
         this._pointerHandlers = {
             pointermove: null,
             pointerdown: null,
@@ -956,6 +1079,74 @@ class AppElement extends AsyncElement {
             pointermove: false
         };
     }
+    /**
+     * Registers the element that created an entity. Called by EntityElement when it creates its
+     * entity.
+     *
+     * @param entity - The entity.
+     * @param element - The element that created it.
+     * @internal
+     */
+    _registerEntityElement(entity, element) {
+        this._entityElements.set(entity, element);
+    }
+    /**
+     * Removes the registration for a destroyed entity. Called by EntityElement.
+     *
+     * @param entity - The entity.
+     * @internal
+     */
+    _unregisterEntityElement(entity) {
+        this._entityElements.delete(entity);
+    }
+    /**
+     * Returns the `<pc-entity>` element whose backing entity is `entity`, or `null` if the
+     * entity was not created by an element of this application - for example, a node inside a
+     * model's instantiated hierarchy, or an entity created through the engine API.
+     *
+     * @param entity - The entity to look up.
+     * @returns The element backing the entity, or `null`.
+     */
+    elementFromEntity(entity) {
+        return this._entityElements.get(entity) ?? null;
+    }
+    /**
+     * Resolves the element that owns a picked node: the nearest node up the parent chain -
+     * starting with the node itself - that was created by a `<pc-entity>` of this application.
+     * A hit inside a model's instantiated hierarchy therefore resolves to the element hosting
+     * the model.
+     *
+     * @param node - The picked node, or `null`.
+     * @returns The owning element, or `null`.
+     */
+    _elementFromNode(node) {
+        while (node !== null) {
+            const element = this._entityElements.get(node);
+            if (element) {
+                return element;
+            }
+            node = node.parent;
+        }
+        return null;
+    }
+    /**
+     * Like {@link _elementFromNode}, but skips elements without a listener for `type`, so a hit
+     * on an unlistened child still reaches a listening ancestor.
+     *
+     * @param node - The picked node, or `null`.
+     * @param type - The pointer event type a listener is required for.
+     * @returns The nearest listening element, or `null`.
+     */
+    _elementWithListener(node, type) {
+        while (node !== null) {
+            const element = this._entityElements.get(node);
+            if (element?._hasListeners(type)) {
+                return element;
+            }
+            node = node.parent;
+        }
+        return null;
+    }
     // New helper to convert CSS coordinates to canvas (picker) coordinates
     _getPickerCoordinates(event) {
         // Get the canvas' bounding rectangle in CSS pixels.
@@ -1001,56 +1192,44 @@ class AppElement extends AsyncElement {
         const node = await this._pickNode(event);
         if (token !== this._pickToken || !this._picker)
             return;
-        // Get the currently hovered entity by walking up the hierarchy
-        let newHoverEntity = null;
-        let currentNode = node;
-        while (currentNode !== null) {
-            const entityElement = this.querySelector(`pc-entity[name="${currentNode.name}"]`);
-            if (entityElement) {
-                newHoverEntity = entityElement;
-                break;
-            }
-            currentNode = currentNode.parent;
-        }
+        // The hovered element is the nearest one up the node's parent chain, listening or not -
+        // dispatch is gated per event type below
+        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));
         }
     }
     async _onPointerDown(event) {
         if (!this._picker || !this.app)
             return;
-        let currentNode = await this._pickNode(event);
+        const node = await this._pickNode(event);
         if (!this._picker)
             return; // the element disconnected while the pick was in flight
-        while (currentNode !== null) {
-            const entityElement = this.querySelector(`pc-entity[name="${currentNode.name}"]`);
-            if (entityElement && entityElement.hasListeners('pointerdown')) {
-                entityElement.dispatchEvent(new PointerEvent('pointerdown', event));
-                break;
-            }
-            currentNode = currentNode.parent;
+        const entityElement = this._elementWithListener(node, 'pointerdown');
+        if (entityElement) {
+            entityElement.dispatchEvent(new PointerEvent('pointerdown', event));
         }
     }
     async _onPointerUp(event) {
         if (!this._picker || !this.app)
             return;
         const node = await this._pickNode(event);
-        if (!node || !this._picker)
-            return;
-        const entityElement = this.querySelector(`pc-entity[name="${node.name}"]`);
-        if (entityElement && entityElement.hasListeners('pointerup')) {
+        if (!this._picker)
+            return; // the element disconnected while the pick was in flight
+        const entityElement = this._elementWithListener(node, 'pointerup');
+        if (entityElement) {
             entityElement.dispatchEvent(new PointerEvent('pointerup', event));
         }
     }
@@ -1058,50 +1237,64 @@ class AppElement extends AsyncElement {
         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);
             }
         }
     }
     /**
-     * Sets the alpha flag.
+     * Warns that a graphics option was written too late to have any effect. These options are read
+     * once, when the element connects and creates its graphics device, so a later write updates
+     * only the element's own property - silently, without this.
+     *
+     * @param name - The name of the option, as its attribute.
+     */
+    _warnIfBooted(name) {
+        if (this._optionsLocked) {
+            console.warn(`Attribute '${name}' on <pc-app> is only read when the application boots, so this change has no effect. Set it before the element is connected, or remove and re-insert the element to reboot with the new value.`);
+        }
+    }
+    /**
+     * Sets whether the frame buffer has an alpha channel, which is what lets the page show through
+     * wherever the scene has not drawn. Read only when the application boots.
      * @param value - The alpha flag.
      */
     set alpha(value) {
+        this._warnIfBooted('alpha');
         this._alpha = value;
     }
     /**
-     * Gets the alpha flag.
+     * Gets whether the frame buffer has an alpha channel.
      * @returns The alpha flag.
      */
     get alpha() {
         return this._alpha;
     }
     /**
-     * Sets the antialias flag.
+     * Sets whether the frame buffer is anti-aliased. Read only when the application boots.
      * @param value - The antialias flag.
      */
     set antialias(value) {
+        this._warnIfBooted('antialias');
         this._antialias = value;
     }
     /**
-     * Gets the antialias flag.
+     * Gets whether the frame buffer is anti-aliased.
      * @returns The antialias flag.
      */
     get antialias() {
@@ -1109,10 +1302,11 @@ class AppElement extends AsyncElement {
     }
     /**
      * Sets the graphics backend. Defaults to 'webgpu', which falls back to 'webgl2' if WebGPU
-     * is not supported by the browser.
+     * is not supported by the browser. Read only when the application boots.
      * @param value - The graphics backend ('webgpu', 'webgl2', or 'null').
      */
     set backend(value) {
+        this._warnIfBooted('backend');
         this._backend = value;
     }
     /**
@@ -1123,44 +1317,20 @@ class AppElement extends AsyncElement {
         return this._backend;
     }
     /**
-     * Sets the depth flag.
-     * @param value - The depth flag.
-     */
-    set depth(value) {
-        this._depth = value;
-    }
-    /**
-     * Gets the depth flag.
-     * @returns The depth flag.
-     */
-    get depth() {
-        return this._depth;
-    }
-    /**
-     * Gets the hierarchy ready flag.
-     * @returns The hierarchy ready flag.
-     * @ignore
-     */
-    get hierarchyReady() {
-        return this._hierarchyReady;
-    }
-    /**
-     * Sets the high resolution flag. When true, the application will render at the device's
-     * physical resolution. When false, the application will render at CSS resolution.
-     * @param value - The high resolution flag.
+     * Sets whether the frame buffer has a depth buffer, which the renderer needs to resolve which
+     * surface is nearest the camera. Read only when the application boots.
+     * @param value - The depth buffer flag.
      */
-    set highResolution(value) {
-        this._highResolution = value;
-        if (this.app) {
-            this.app.graphicsDevice.maxPixelRatio = value ? window.devicePixelRatio : 1;
-        }
+    set depthBuffer(value) {
+        this._warnIfBooted('depth-buffer');
+        this._depthBuffer = value;
     }
     /**
-     * Gets the high resolution flag.
-     * @returns The high resolution flag.
+     * Gets whether the frame buffer has a depth buffer.
+     * @returns The depth buffer flag.
      */
-    get highResolution() {
-        return this._highResolution;
+    get depthBuffer() {
+        return this._depthBuffer;
     }
     /**
      * Sets whether the application shows its built-in loading bar while it boots and preloads its
@@ -1186,21 +1356,45 @@ class AppElement extends AsyncElement {
         return this._loadingBar;
     }
     /**
-     * Sets the stencil flag.
-     * @param value - The stencil flag.
+     * Sets the cap on the pixel ratio the application renders at. The canvas is sized by the
+     * smaller of this value and the display's own device pixel ratio, so the default of `Infinity`
+     * renders at full physical resolution, `1` renders at CSS resolution, and an intermediate
+     * value such as `2` keeps a dense display sharp without paying for every one of its pixels.
+     * Must be greater than 0. Unlike the other graphics options, this applies immediately.
+     * @param value - The maximum pixel ratio.
+     */
+    set maxPixelRatio(value) {
+        this._maxPixelRatio = value;
+        if (this.app) {
+            this.app.graphicsDevice.maxPixelRatio = value;
+            this.app.resizeCanvas();
+        }
+    }
+    /**
+     * Gets the cap on the pixel ratio the application renders at.
+     * @returns The maximum pixel ratio.
+     */
+    get maxPixelRatio() {
+        return this._maxPixelRatio;
+    }
+    /**
+     * Sets whether the frame buffer has a stencil buffer, which stencil-based effects and UI
+     * masking need. Read only when the application boots.
+     * @param value - The stencil buffer flag.
      */
-    set stencil(value) {
-        this._stencil = value;
+    set stencilBuffer(value) {
+        this._warnIfBooted('stencil-buffer');
+        this._stencilBuffer = value;
     }
     /**
-     * Gets the stencil flag.
-     * @returns The stencil flag.
+     * Gets whether the frame buffer has a stencil buffer.
+     * @returns The stencil buffer flag.
      */
-    get stencil() {
-        return this._stencil;
+    get stencilBuffer() {
+        return this._stencilBuffer;
     }
     static get observedAttributes() {
-        return ['alpha', 'antialias', 'backend', 'depth', 'stencil', 'high-resolution', 'loading-bar'];
+        return ['alpha', 'antialias', 'backend', 'depth-buffer', 'loading-bar', 'max-pixel-ratio', 'stencil-buffer'];
     }
     attributeChangedCallback(name, _oldValue, newValue) {
         switch (name) {
@@ -1213,17 +1407,17 @@ class AppElement extends AsyncElement {
             case 'backend':
                 this.backend = parseEnum(newValue, ['webgpu', 'webgl2', 'null'], 'webgpu', name);
                 break;
-            case 'depth':
-                this.depth = parseBool(newValue, true);
-                break;
-            case 'high-resolution':
-                this.highResolution = parseBool(newValue, true);
+            case 'depth-buffer':
+                this.depthBuffer = parseBool(newValue, true);
                 break;
             case 'loading-bar':
                 this.loadingBar = parseBool(newValue, true);
                 break;
-            case 'stencil':
-                this.stencil = parseBool(newValue, true);
+            case 'max-pixel-ratio':
+                this.maxPixelRatio = parseNumber(newValue, Infinity, name);
+                break;
+            case 'stencil-buffer':
+                this.stencilBuffer = parseBool(newValue, true);
                 break;
         }
     }
@@ -1292,6 +1486,11 @@ class EntityElement extends AsyncElement {
      */
     _built = false;
     _entity = null;
+    /**
+     * The application element this entity is registered with, cached at creation time so the
+     * entity can be unregistered even once this element has left the DOM.
+     */
+    _appElement = null;
     /**
      * The PlayCanvas entity instance. `null` until the element is ready, and again once it has
      * been removed from the document — await {@link whenReady} or the element's `ready()`
@@ -1301,7 +1500,14 @@ class EntityElement extends AsyncElement {
     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.
@@ -1321,8 +1527,41 @@ class EntityElement extends AsyncElement {
         if (this._tags.length > 0) {
             entity.tags.add(this._tags);
         }
+        // Register with the owning application, which joins engine nodes back to elements by
+        // identity (never by name), and hook the entity's destruction. The engine fires 'destroy'
+        // for every entity in a destroyed subtree, so the element learns of its entity's death no
+        // matter who causes it: this element, an ancestor, the whole application, or a user
+        // script calling entity.destroy().
+        this._appElement = this.closestApp;
+        this._appElement?._registerEntityElement(entity, this);
+        entity.once('destroy', this._onEntityDestroy, this);
+    }
+    /**
+     * 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. 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.
+     */
+    _onEntityDestroy(entity) {
+        this._appElement?._unregisterEntityElement(entity);
+        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;
@@ -1348,37 +1587,26 @@ class EntityElement extends AsyncElement {
             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);
             });
         }
     }
     disconnectedCallback() {
-        if (this.entity) {
-            // Notify all children that their entities are about to become invalid. Both fields have
-            // to be reset here, not just _entity: a descendant's own disconnectedCallback runs after
-            // this one and skips its reset behind the `if (this.entity)` guard, because we have
-            // already nulled the entity it tests. Leaving _built set would make buildHierarchy bail
-            // on re-insertion, so the descendant would get a fresh entity that is never parented.
-            const children = this.querySelectorAll('pc-entity');
-            children.forEach((child) => {
-                child._entity = null;
-                child._built = false;
-            });
-            // Destroy the entity
-            this.entity.destroy();
-            this._entity = null;
-            this._built = false;
-        }
+        // Destroying the entity destroys its whole subtree, and the engine fires 'destroy' for
+        // every entity in it - so _onEntityDestroy resets this element AND every descendant
+        // element before the descendants' own disconnectedCallbacks run. Their entities are null
+        // by then, making this call a no-op for them.
+        this._entity?.destroy();
     }
     /**
      * Sets the enabled state of the entity.
@@ -1563,14 +1791,23 @@ class EntityElement extends AsyncElement {
     }
     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);
     }
 }
@@ -1861,7 +2098,7 @@ class AssetElement extends AsyncElement {
             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) {
@@ -1869,13 +2106,15 @@ class AssetElement extends AsyncElement {
                 }
             }
         }
-        // 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'));
@@ -1885,7 +2124,14 @@ class AssetElement extends AsyncElement {
             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');
@@ -1975,7 +2221,7 @@ class AssetElement extends AsyncElement {
         }
         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);
@@ -2003,6 +2249,13 @@ class AssetElement extends AsyncElement {
     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;
@@ -2028,6 +2281,14 @@ class ComponentElement extends AsyncElement {
     _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.
      *
@@ -2038,11 +2299,17 @@ class ComponentElement extends AsyncElement {
         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.
@@ -2052,19 +2319,42 @@ class ComponentElement extends AsyncElement {
             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.
@@ -2073,6 +2363,7 @@ class ComponentElement extends AsyncElement {
         }
         this._component = null;
         this._appElement = null;
+        this._resetReady();
     }
     /**
      * The PlayCanvas component instance. `null` until the element is ready, and also for an
@@ -2525,6 +2816,10 @@ class ButtonComponentElement extends ComponentElement {
 }
 customElements.define('pc-button', ButtonComponentElement);
 
+const projections = new Map([
+    ['perspective', playcanvas.PROJECTION_PERSPECTIVE],
+    ['orthographic', playcanvas.PROJECTION_ORTHOGRAPHIC]
+]);
 const tonemaps = new Map([
     ['none', playcanvas.TONEMAP_NONE],
     ['linear', playcanvas.TONEMAP_LINEAR],
@@ -2555,7 +2850,7 @@ class CameraComponentElement extends ComponentElement {
     _gamma = 'srgb';
     _horizontalFov = false;
     _nearClip = 0.1;
-    _orthographic = false;
+    _projection = 'perspective';
     _orthoHeight = 10;
     _priority = 0;
     _rect = new playcanvas.Vec4(0, 0, 1, 1);
@@ -2579,12 +2874,12 @@ class CameraComponentElement extends ComponentElement {
             gammaCorrection: this._gamma === 'srgb' ? playcanvas.GAMMA_SRGB : playcanvas.GAMMA_NONE,
             horizontalFov: this._horizontalFov,
             nearClip: this._nearClip,
-            projection: this._orthographic ? playcanvas.PROJECTION_ORTHOGRAPHIC : playcanvas.PROJECTION_PERSPECTIVE,
+            projection: projections.get(this._projection) ?? playcanvas.PROJECTION_PERSPECTIVE,
             orthoHeight: this._orthoHeight,
             priority: this._priority,
             rect: this._rect,
             scissorRect: this._scissorRect,
-            toneMapping: tonemaps.get(this._tonemap)
+            toneMapping: tonemaps.get(this._tonemap) ?? playcanvas.TONEMAP_NONE
         };
     }
     get xrAvailable() {
@@ -2826,23 +3121,6 @@ class CameraComponentElement extends ComponentElement {
     get nearClip() {
         return this._nearClip;
     }
-    /**
-     * Sets the orthographic projection of the camera.
-     * @param value - The orthographic projection.
-     */
-    set orthographic(value) {
-        this._orthographic = value;
-        if (this.component) {
-            this.component.projection = value ? playcanvas.PROJECTION_ORTHOGRAPHIC : playcanvas.PROJECTION_PERSPECTIVE;
-        }
-    }
-    /**
-     * Gets the orthographic projection of the camera.
-     * @returns The orthographic projection.
-     */
-    get orthographic() {
-        return this._orthographic;
-    }
     /**
      * Sets the orthographic height of the camera.
      * @param value - The orthographic height.
@@ -2877,6 +3155,23 @@ class CameraComponentElement extends ComponentElement {
     get priority() {
         return this._priority;
     }
+    /**
+     * Sets the projection of the camera. Use `orthoHeight` to size an orthographic projection.
+     * @param value - The projection ('perspective' or 'orthographic').
+     */
+    set projection(value) {
+        this._projection = value;
+        if (this.component) {
+            this.component.projection = projections.get(value) ?? playcanvas.PROJECTION_PERSPECTIVE;
+        }
+    }
+    /**
+     * Gets the projection of the camera.
+     * @returns The projection.
+     */
+    get projection() {
+        return this._projection;
+    }
     /**
      * Sets the rect of the camera.
      * @param value - The rect.
@@ -2943,9 +3238,9 @@ class CameraComponentElement extends ComponentElement {
             'gamma',
             'horizontal-fov',
             'near-clip',
-            'orthographic',
             'ortho-height',
             'priority',
+            'projection',
             'rect',
             'scissor-rect',
             'tonemap'
@@ -2990,15 +3285,15 @@ class CameraComponentElement extends ComponentElement {
             case 'near-clip':
                 this.nearClip = parseNumber(newValue, 0.1, name);
                 break;
-            case 'orthographic':
-                this.orthographic = parseBool(newValue, false);
-                break;
             case 'ortho-height':
                 this.orthoHeight = parseNumber(newValue, 10, name);
                 break;
             case 'priority':
                 this.priority = parseNumber(newValue, 0, name);
                 break;
+            case 'projection':
+                this.projection = parseEnum(newValue, projections, 'perspective', name);
+                break;
             case 'rect':
                 this.rect = parseVec4(newValue, new playcanvas.Vec4(0, 0, 1, 1), name);
                 break;
@@ -3126,7 +3421,17 @@ class CollisionComponentElement extends ComponentElement {
         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);
@@ -4831,7 +5136,7 @@ class ParticleSystemComponentElement extends ComponentElement {
         }
         // 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];
             }
         }
@@ -4904,10 +5209,7 @@ class ParticleSystemComponentElement extends ComponentElement {
         }
     }
     static get observedAttributes() {
-        return [
-            ...super.observedAttributes,
-            'asset'
-        ];
+        return [...super.observedAttributes, 'asset'];
     }
     attributeChangedCallback(name, _oldValue, newValue) {
         super.attributeChangedCallback(name, _oldValue, newValue);
@@ -5067,7 +5369,7 @@ class MaterialElement extends HTMLElement {
     _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;
@@ -5080,6 +5382,10 @@ class MaterialElement extends HTMLElement {
     _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;
@@ -5097,10 +5403,17 @@ class MaterialElement extends HTMLElement {
         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;
@@ -5227,9 +5540,9 @@ class MaterialElement extends HTMLElement {
      * 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;
@@ -5247,7 +5560,7 @@ class MaterialElement extends HTMLElement {
      * @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);
@@ -5341,7 +5654,7 @@ class MaterialElement extends HTMLElement {
      */
     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.
@@ -5573,7 +5886,7 @@ class MaterialElement extends HTMLElement {
      */
     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.
@@ -5714,7 +6027,7 @@ class MaterialElement extends HTMLElement {
      */
     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.
@@ -5892,7 +6205,7 @@ class MaterialElement extends HTMLElement {
      */
     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.
@@ -5997,7 +6310,7 @@ class MaterialElement extends HTMLElement {
      */
     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.
@@ -6138,7 +6451,7 @@ class MaterialElement extends HTMLElement {
      */
     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.
@@ -6243,7 +6556,7 @@ class MaterialElement extends HTMLElement {
      */
     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.
@@ -6331,7 +6644,7 @@ class MaterialElement extends HTMLElement {
     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();
         }
@@ -6423,7 +6736,7 @@ class MaterialElement extends HTMLElement {
      */
     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.
@@ -6741,6 +7054,13 @@ class MaterialElement extends HTMLElement {
     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;
@@ -7379,7 +7699,18 @@ class RigidBodyComponentElement extends ComponentElement {
         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);
@@ -7416,6 +7747,14 @@ class RigidBodyComponentElement extends ComponentElement {
 }
 customElements.define('pc-rigidbody', RigidBodyComponentElement);
 
+// The engine's SCALEMODE_* constants are the strings 'none' and 'blend', so this map happens to be
+// an identity. It is still the right shape: it supplies parseEnum's valid-name list, it is what the
+// manifest generator reads the enum values from, and it keeps the attribute vocabulary independent
+// of constants the engine is free to change.
+const scaleModes = new Map([
+    ['none', playcanvas.SCALEMODE_NONE],
+    ['blend', playcanvas.SCALEMODE_BLEND]
+]);
 /**
  * The ScreenComponentElement interface provides properties and methods for manipulating
  * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-screen/ | `<pc-screen>`} elements.
@@ -7429,7 +7768,7 @@ class ScreenComponentElement extends ComponentElement {
     _resolution = new playcanvas.Vec2(640, 320);
     _referenceResolution = new playcanvas.Vec2(640, 320);
     _priority = 0;
-    _blend = false;
+    _scaleMode = 'none';
     _scaleBlend = 0.5;
     /** @ignore */
     constructor() {
@@ -7441,7 +7780,7 @@ class ScreenComponentElement extends ComponentElement {
             referenceResolution: this._referenceResolution,
             resolution: this._resolution,
             scaleBlend: this._scaleBlend,
-            scaleMode: this._blend ? playcanvas.SCALEMODE_BLEND : playcanvas.SCALEMODE_NONE,
+            scaleMode: scaleModes.get(this._scaleMode) ?? playcanvas.SCALEMODE_NONE,
             screenSpace: this._screenSpace
         };
     }
@@ -7479,23 +7818,44 @@ class ScreenComponentElement extends ComponentElement {
     get resolution() {
         return this._resolution;
     }
+    /**
+     * Sets how the screen's `resolution` and `referenceResolution` are weighted against each other
+     * when `scaleMode` is `blend`, from 0 (follow the resolution) to 1 (follow the reference
+     * resolution). Ignored while `scaleMode` is `none`.
+     * @param value - The scale blend factor.
+     */
     set scaleBlend(value) {
         this._scaleBlend = value;
         if (this.component) {
             this.component.scaleBlend = this._scaleBlend;
         }
     }
+    /**
+     * Gets how the screen's resolutions are weighted against each other.
+     * @returns The scale blend factor.
+     */
     get scaleBlend() {
         return this._scaleBlend;
     }
-    set blend(value) {
-        this._blend = value;
+    /**
+     * Sets how the screen scales its contents. `none` renders at `resolution` and ignores
+     * `referenceResolution`; `blend` scales between the two, weighted by `scaleBlend`, which is what
+     * keeps a UI laid out at one resolution usable at another. Requires `screenSpace` - the engine
+     * forces `none` on a world-space screen, which does not support scaling.
+     * @param value - The scale mode ('none' or 'blend').
+     */
+    set scaleMode(value) {
+        this._scaleMode = value;
         if (this.component) {
-            this.component.scaleMode = this._blend ? playcanvas.SCALEMODE_BLEND : playcanvas.SCALEMODE_NONE;
+            this.component.scaleMode = scaleModes.get(value) ?? playcanvas.SCALEMODE_NONE;
         }
     }
-    get blend() {
-        return this._blend;
+    /**
+     * Gets how the screen scales its contents.
+     * @returns The scale mode.
+     */
+    get scaleMode() {
+        return this._scaleMode;
     }
     set screenSpace(value) {
         this._screenSpace = value;
@@ -7509,12 +7869,12 @@ class ScreenComponentElement extends ComponentElement {
     static get observedAttributes() {
         return [
             ...super.observedAttributes,
-            'blend',
             'screen-space',
             'resolution',
             'reference-resolution',
             'priority',
-            'scale-blend'
+            'scale-blend',
+            'scale-mode'
         ];
     }
     attributeChangedCallback(name, _oldValue, newValue) {
@@ -7532,8 +7892,8 @@ class ScreenComponentElement extends ComponentElement {
             case 'scale-blend':
                 this.scaleBlend = parseNumber(newValue, 0.5, name);
                 break;
-            case 'blend':
-                this.blend = parseBool(newValue, false);
+            case 'scale-mode':
+                this.scaleMode = parseEnum(newValue, scaleModes, 'none', name);
                 break;
             case 'screen-space':
                 this.screenSpace = parseBool(newValue, false);
@@ -7655,13 +8015,7 @@ class ScrollbarComponentElement extends ComponentElement {
         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);
@@ -7756,7 +8110,8 @@ class ScrollViewComponentElement extends ComponentElement {
         return super.component;
     }
     /**
-     * Sets whether horizontal scrolling is enabled.
+     * Sets whether scrolling along the horizontal axis is enabled. This is a toggle, unlike the
+     * `orientation` of a `<pc-scrollbar>`, for which `horizontal` is one of the accepted values.
      * @param value - Whether horizontal scrolling is enabled.
      */
     set horizontal(value) {
@@ -7766,14 +8121,15 @@ class ScrollViewComponentElement extends ComponentElement {
         }
     }
     /**
-     * Gets whether horizontal scrolling is enabled.
+     * Gets whether scrolling along the horizontal axis is enabled.
      * @returns Whether horizontal scrolling is enabled.
      */
     get horizontal() {
         return this._horizontal;
     }
     /**
-     * Sets whether vertical scrolling is enabled.
+     * Sets whether scrolling along the vertical axis is enabled. This is a toggle, unlike the
+     * `orientation` of a `<pc-scrollbar>`, for which `vertical` is one of the accepted values.
      * @param value - Whether vertical scrolling is enabled.
      */
     set vertical(value) {
@@ -7783,7 +8139,7 @@ class ScrollViewComponentElement extends ComponentElement {
         }
     }
     /**
-     * Gets whether vertical scrolling is enabled.
+     * Gets whether scrolling along the vertical axis is enabled.
      * @returns Whether vertical scrolling is enabled.
      */
     get vertical() {
@@ -7885,7 +8241,8 @@ class ScrollViewComponentElement extends ComponentElement {
     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;
         }
     }
     /**
@@ -7903,7 +8260,8 @@ class ScrollViewComponentElement extends ComponentElement {
     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;
         }
     }
     /**
@@ -8090,15 +8448,9 @@ customElements.define('pc-scrollview', ScrollViewComponentElement);
 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;
     /**
@@ -8180,14 +8532,20 @@ class ScriptElement extends AsyncElement {
             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() {
@@ -8232,10 +8590,34 @@ customElements.define('pc-script', ScriptElement);
  */
 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
@@ -8247,18 +8629,25 @@ const RESERVED_ATTRIBUTES = new Set([
  * @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.
@@ -8274,7 +8663,7 @@ const kebabToCamel = (name) => {
  * @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.
@@ -8473,7 +8862,10 @@ class ScriptComponentElement extends ComponentElement {
             // 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] = {};
                 }
@@ -8491,7 +8883,11 @@ class ScriptComponentElement extends ComponentElement {
      * @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
@@ -8504,7 +8900,7 @@ class ScriptComponentElement extends ComponentElement {
      * @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)
@@ -8776,7 +9172,10 @@ class ScriptComponentElement extends ComponentElement {
             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;
@@ -9025,18 +9424,27 @@ class SoundSlotElement extends AsyncElement {
      * 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 = {
@@ -9059,12 +9467,15 @@ class SoundSlotElement extends AsyncElement {
         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;
@@ -9464,39 +9875,85 @@ customElements.define('pc-gsplat', GSplatComponentElement);
 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) {
@@ -9506,7 +9963,14 @@ class ModelElement extends AsyncElement {
             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);
@@ -9608,10 +10072,17 @@ class SceneElement extends AsyncElement {
             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;
@@ -9773,19 +10244,38 @@ class SkyElement extends AsyncElement {
     _center = new playcanvas.Vec3(0, 0.01, 0);
     _intensity = 1;
     _rotation = new playcanvas.Vec3();
-    _level = 0;
+    _mipLevel = 0;
     _lighting = false;
     _scale = new playcanvas.Vec3(100, 100, 100);
     _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)
@@ -9793,10 +10283,17 @@ class SkyElement extends AsyncElement {
         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);
@@ -9807,10 +10304,17 @@ class SkyElement extends AsyncElement {
         this._scene.sky.node.setLocalScale(this._scale);
         this._scene.sky.center = this._center;
         this._scene.skyboxIntensity = this._intensity;
-        this._scene.skyboxMip = this._level;
+        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;
@@ -9825,7 +10329,14 @@ class SkyElement extends AsyncElement {
             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);
@@ -9899,23 +10410,6 @@ class SkyElement extends AsyncElement {
     get intensity() {
         return this._intensity;
     }
-    /**
-     * Sets the mip level of the skybox.
-     * @param value - The mip level.
-     */
-    set level(value) {
-        this._level = value;
-        if (this._scene) {
-            this._scene.skyboxMip = this._level;
-        }
-    }
-    /**
-     * Gets the mip level of the skybox.
-     * @returns The mip level.
-     */
-    get level() {
-        return this._level;
-    }
     /**
      * Sets whether the skybox is used as a light source.
      * @param value - Whether to use lighting.
@@ -9930,6 +10424,24 @@ class SkyElement extends AsyncElement {
     get lighting() {
         return this._lighting;
     }
+    /**
+     * Sets the mip level of the skybox, where 0 is the sharpest. Raising it selects a blurrier mip,
+     * which is how a skybox is softened without blurring the texture itself.
+     * @param value - The mip level.
+     */
+    set mipLevel(value) {
+        this._mipLevel = value;
+        if (this._scene) {
+            this._scene.skyboxMip = this._mipLevel;
+        }
+    }
+    /**
+     * Gets the mip level of the skybox.
+     * @returns The mip level.
+     */
+    get mipLevel() {
+        return this._mipLevel;
+    }
     /**
      * Sets the Euler rotation of the skybox.
      * @param value - The rotation.
@@ -9986,7 +10498,7 @@ class SkyElement extends AsyncElement {
         return this._type;
     }
     static get observedAttributes() {
-        return ['asset', 'center', 'intensity', 'level', 'lighting', 'rotation', 'scale', 'type'];
+        return ['asset', 'center', 'intensity', 'lighting', 'mip-level', 'rotation', 'scale', 'type'];
     }
     attributeChangedCallback(name, _oldValue, newValue) {
         switch (name) {
@@ -9999,12 +10511,12 @@ class SkyElement extends AsyncElement {
             case 'intensity':
                 this.intensity = parseNumber(newValue, 1, name);
                 break;
-            case 'level':
-                this.level = parseNumber(newValue, 0, name);
-                break;
             case 'lighting':
                 this.lighting = parseBool(newValue, false);
                 break;
+            case 'mip-level':
+                this.mipLevel = parseNumber(newValue, 0, name);
+                break;
             case 'rotation':
                 this.rotation = parseVec3(newValue, playcanvas.Vec3.ZERO, name);
                 break;