@playcanvas/web-components 0.10.0 → 0.11.0

package/dist/pwc.js

@@ -20,11 +20,21 @@
                 this._readyResolve = resolve;
             });
         }
+        /**
+         * The nearest ancestor `<pc-app>` element, or `null` if this element has no `<pc-app>`
+         * ancestor. The search starts at the parent, so an element never resolves to itself.
+         * @returns The closest app element, or `null`.
+         */
         get closestApp() {
-            return this.parentElement?.closest('pc-app');
+            return this.parentElement?.closest('pc-app') ?? null;
         }
+        /**
+         * The nearest ancestor `<pc-entity>` element, or `null` if this element has no `<pc-entity>`
+         * ancestor. The search starts at the parent, so an element never resolves to itself.
+         * @returns The closest entity element, or `null`.
+         */
         get closestEntity() {
-            return this.parentElement?.closest('pc-entity');
+            return this.parentElement?.closest('pc-entity') ?? null;
         }
         /**
          * Called when the element is fully initialized and ready. Subclasses should call this when
@@ -118,6 +128,116 @@
     }
     customElements.define('pc-module', ModuleElement);
 
+    /** Covers the 0.2s opacity transition; jsdom never fires transitionend, so removal is timed. */
+    const REMOVAL_DELAY_MS = 250;
+    /**
+     * The slim progress bar `<pc-app>` shows while it boots and preloads. An implementation detail of
+     * AppElement rather than a custom element, so its shape can change without a breaking change.
+     *
+     * All styling is inline, so the library injects no stylesheet. The colors and height resolve CSS
+     * custom properties — `--pc-loading-bar-color`, `--pc-loading-bar-background` and
+     * `--pc-loading-bar-height` — so a page can theme the bar from `pc-app` or `:root`.
+     */
+    class LoadingBar {
+        _track;
+        _fill;
+        _sweep = null;
+        _removal = null;
+        /**
+         * Creates the bar and appends it to `parent`, starting in the indeterminate state.
+         * @param parent - The element to append the bar to.
+         */
+        constructor(parent) {
+            this._track = document.createElement('div');
+            this._track.setAttribute('role', 'progressbar');
+            this._track.setAttribute('aria-label', 'Loading');
+            this._track.setAttribute('aria-valuemin', '0');
+            this._track.setAttribute('aria-valuemax', '100');
+            // Fixed positioning matches the canvas, which always fills the window (FILLMODE_FILL_WINDOW)
+            this._track.style.cssText = [
+                'position: fixed',
+                'top: 0',
+                'left: 0',
+                'width: 100%',
+                'height: var(--pc-loading-bar-height, 3px)',
+                'background: var(--pc-loading-bar-background, rgba(0, 0, 0, 0.1))',
+                'z-index: 10000',
+                'pointer-events: none',
+                'opacity: 1',
+                'transition: opacity 0.2s ease'
+            ].join('; ');
+            this._fill = document.createElement('div');
+            this._fill.style.cssText = [
+                'width: 100%',
+                'height: 100%',
+                'transform-origin: left center',
+                'transform: scaleX(0)',
+                'background: var(--pc-loading-bar-color, #f60)',
+                'transition: transform 0.2s ease'
+            ].join('; ');
+            this._track.appendChild(this._fill);
+            parent.appendChild(this._track);
+            // Indeterminate sweep until the first progress() call reports a real total. No
+            // 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%)' }
+                ], {
+                    duration: 1000,
+                    iterations: Infinity,
+                    easing: 'ease-in-out'
+                });
+            }
+        }
+        /**
+         * Reflects preload progress, switching the bar from indeterminate to determinate on the first
+         * call.
+         * @param loaded - The number of assets that have finished loading.
+         * @param total - The number of assets being preloaded.
+         */
+        progress(loaded, total) {
+            if (this._sweep) {
+                this._sweep.cancel();
+                this._sweep = null;
+            }
+            const fraction = total === 0 ? 1 : loaded / total;
+            this._track.setAttribute('aria-valuenow', String(Math.round(fraction * 100)));
+            this._fill.style.transform = `scaleX(${fraction})`;
+        }
+        /**
+         * Fills the bar, fades it out and removes it. Idempotent.
+         */
+        complete() {
+            if (this._removal !== null) {
+                return;
+            }
+            if (this._sweep) {
+                this._sweep.cancel();
+                this._sweep = null;
+            }
+            this._track.setAttribute('aria-valuenow', '100');
+            this._fill.style.transform = 'scaleX(1)';
+            this._track.style.opacity = '0';
+            this._removal = setTimeout(() => this._track.remove(), REMOVAL_DELAY_MS);
+        }
+        /**
+         * Removes the bar immediately, cancelling any pending fade. Idempotent.
+         */
+        destroy() {
+            if (this._sweep) {
+                this._sweep.cancel();
+                this._sweep = null;
+            }
+            if (this._removal !== null) {
+                clearTimeout(this._removal);
+                this._removal = null;
+            }
+            this._track.remove();
+        }
+    }
+
     const CSS_COLORS = {
         aliceblue: '#f0f8ff',
         antiquewhite: '#faebd7',
@@ -371,7 +491,9 @@
      * 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.
@@ -545,6 +667,11 @@
      * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-app/ | `<pc-app>`} elements.
      * The AppElement interface also inherits the properties and methods of the
      * {@link HTMLElement} interface.
+     *
+     * @fires {ProgressEvent} progress - Fired while the application preloads its assets. `loaded` and
+     * `total` are asset counts, not bytes, and an asset that fails to load still counts as loaded.
+     * Fired at least once per boot, and the final event always has `loaded` equal to `total`. Does
+     * not bubble.
      */
     class AppElement extends AsyncElement {
         /**
@@ -554,10 +681,24 @@
         _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;
         _hierarchyReady = false;
+        /**
+         * 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,
@@ -567,20 +708,34 @@
             pointermove: false
         };
         _hoveredEntity = null;
+        // Identifies the newest in-flight hover pick, so out-of-order results can be discarded
+        _pickToken = 0;
         _pointerHandlers = {
             pointermove: null,
             pointerdown: null,
             pointerup: null
         };
         _app = null;
+        _loadProgress = 0;
         /**
-         * The PlayCanvas application instance. Available once the element is ready — await
-         * {@link whenReady} or the element's `ready()` promise before accessing it.
-         * @returns The application instance.
+         * The PlayCanvas application 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()`
+         * promise before accessing it.
+         * @returns The application instance, or `null`.
          */
         get app() {
             return this._app;
         }
+        /**
+         * The asset preload progress of the application, as a fraction from 0 to 1. It is 0 until
+         * preloading begins (and again once the element has been removed from the document), and 1
+         * once preloading has finished — including when there was nothing to preload. Read this to
+         * initialize a loading UI; subsequent updates arrive via the `progress` event.
+         * @returns The preload progress.
+         */
+        get loadProgress() {
+            return this._loadProgress;
+        }
         /**
          * Creates a new AppElement instance.
          *
@@ -592,6 +747,11 @@
             this._onWindowResize = this._onWindowResize.bind(this);
         }
         async connectedCallback() {
+            // 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) {
+                this._bar = new LoadingBar(this);
+            }
             // 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
@@ -606,15 +766,19 @@
                 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;
+            // 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);
@@ -679,10 +843,11 @@
             createOptions.lightmapper = playcanvas.Lightmapper;
             createOptions.batchManager = playcanvas.BatchManager;
             createOptions.xr = playcanvas.XrManager;
-            this._app = new playcanvas.AppBase(this._canvas);
-            this.app.init(createOptions);
-            this.app.setCanvasFillMode(playcanvas.FILLMODE_FILL_WINDOW);
-            this.app.setCanvasResolution(playcanvas.RESOLUTION_AUTO);
+            const app = new playcanvas.AppBase(this._canvas);
+            this._app = app;
+            app.init(createOptions);
+            app.setCanvasFillMode(playcanvas.FILLMODE_FILL_WINDOW);
+            app.setCanvasResolution(playcanvas.RESOLUTION_AUTO);
             this._pickerCreate();
             // Get all pc-asset elements that are direct children of the pc-app element
             const assetElements = this.querySelectorAll(':scope > pc-asset');
@@ -690,7 +855,7 @@
                 assetElement.createAsset();
                 const asset = assetElement.asset;
                 if (asset) {
-                    this.app.assets.add(asset);
+                    app.assets.add(asset);
                 }
             });
             // Get all pc-material elements that are direct children of the pc-app element
@@ -701,29 +866,57 @@
             // Create all entities
             const entityElements = this.querySelectorAll('pc-entity');
             Array.from(entityElements).forEach((entityElement) => {
-                entityElement.createEntity(this.app);
+                entityElement.createEntity(app);
             });
             // Build hierarchy
             entityElements.forEach((entityElement) => {
-                entityElement.buildHierarchy(this.app);
+                entityElement.buildHierarchy(app);
             });
             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
+            // ticks synchronously inside it.
+            const total = app.assets.list({ preload: true }).length;
+            let loaded = 0;
+            const onPreloadProgress = () => {
+                loaded += 1;
+                this._loadProgress = loaded / total;
+                this._bar?.progress(loaded, total);
+                this.dispatchEvent(new ProgressEvent('progress', { lengthComputable: true, loaded, total }));
+            };
+            app.on('preload:progress', onPreloadProgress);
+            this._loadProgress = total === 0 ? 1 : 0;
+            this._bar?.progress(0, total);
+            this.dispatchEvent(new ProgressEvent('progress', { lengthComputable: true, loaded: 0, total }));
             // Load assets before starting the application
-            this.app.preload(() => {
+            app.preload(() => {
+                // 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);
+                this._loadProgress = 1;
                 // Start the application
-                this.app.start();
+                app.start();
+                // Dismiss the bar only once a frame has actually rendered; ready fires before the
+                // first rAF tick
+                app.once('frameend', () => this._bar?.complete());
                 // Handle window resize to keep the canvas responsive
                 window.addEventListener('resize', this._onWindowResize);
                 this._onReady();
             });
         }
         disconnectedCallback() {
+            this._optionsLocked = false;
             this._pickerDestroy();
-            // Clean up the application
-            if (this.app) {
-                this.app.destroy();
+            // 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;
             // Remove event listeners
             window.removeEventListener('resize', this._onWindowResize);
             // Remove the canvas
@@ -740,10 +933,17 @@
         _pickerCreate() {
             const { width, height } = this.app.graphicsDevice;
             this._picker = new playcanvas.Picker(this.app, width, height);
-            // Create bound handlers but don't attach them yet
-            this._pointerHandlers.pointermove = this._onPointerMove.bind(this);
-            this._pointerHandlers.pointerdown = this._onPointerDown.bind(this);
-            this._pointerHandlers.pointerup = this._onPointerUp.bind(this);
+            // Create bound handlers but don't attach them yet. The handlers pick asynchronously, so
+            // each is wrapped to discard the promise - a listener must not return one, and nothing
+            // awaits the result.
+            const listener = (handler) => {
+                return (event) => {
+                    handler.call(this, event);
+                };
+            };
+            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));
@@ -779,6 +979,74 @@
                 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.
+         * @ignore
+         */
+        _registerEntityElement(entity, element) {
+            this._entityElements.set(entity, element);
+        }
+        /**
+         * Removes the registration for a destroyed entity. Called by EntityElement.
+         *
+         * @param entity - The entity.
+         * @ignore
+         */
+        _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.
@@ -791,30 +1059,42 @@
             const y = (event.clientY - canvasRect.top) * scaleY;
             return { x, y };
         }
-        _onPointerMove(event) {
-            if (!this._picker || !this.app)
-                return;
+        /**
+         * Picks the scene under the pointer and returns the graph node that was hit, or `null`.
+         *
+         * The read back is asynchronous because the synchronous {@link Picker.getSelection} is not
+         * supported on WebGPU, where it returns an empty selection rather than failing - which
+         * silently disabled every `onpointer*` handler once WebGPU became the resolved backend. The
+         * async variant works on both backends and does not block the main thread on a GPU read.
+         *
+         * @param event - The pointer event to pick under.
+         * @returns The graph node under the pointer, or `null` if nothing was hit.
+         */
+        async _pickNode(event) {
             const camera = this.app.root.findComponent('camera');
             if (!camera)
-                return;
-            // Use the helper to convert event coordinates into canvas/picker coordinates.
+                return null;
             const { x, y } = this._getPickerCoordinates(event);
             this._picker.prepare(camera, this.app.scene);
-            const selection = this._picker.getSelection(x, y);
-            // Get the currently hovered entity by walking up the hierarchy
-            let newHoverEntity = null;
-            if (selection.length > 0) {
-                const item = selection[0];
-                let currentNode = item instanceof playcanvas.MeshInstance ? item.node : item.entity;
-                while (currentNode !== null) {
-                    const entityElement = this.querySelector(`pc-entity[name="${currentNode.name}"]`);
-                    if (entityElement) {
-                        newHoverEntity = entityElement;
-                        break;
-                    }
-                    currentNode = currentNode.parent;
-                }
-            }
+            const selection = await this._picker.getSelectionAsync(x, y);
+            if (selection.length === 0)
+                return null;
+            const item = selection[0];
+            return item instanceof playcanvas.MeshInstance ? item.node : item.entity;
+        }
+        async _onPointerMove(event) {
+            if (!this._picker || !this.app)
+                return;
+            // Moves arrive faster than a pick resolves, so results can land out of order. Only the
+            // newest pick may update the hover state - an older one describes a pointer position the
+            // user has already left.
+            const token = ++this._pickToken;
+            const node = await this._pickNode(event);
+            if (token !== this._pickToken || !this._picker)
+                return;
+            // 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')) {
@@ -831,46 +1111,26 @@
                 newHoverEntity.dispatchEvent(new PointerEvent('pointermove', event));
             }
         }
-        _onPointerDown(event) {
+        async _onPointerDown(event) {
             if (!this._picker || !this.app)
                 return;
-            const camera = this.app.root.findComponent('camera');
-            if (!camera)
-                return;
-            // Convert the event's pointer coordinates
-            const { x, y } = this._getPickerCoordinates(event);
-            this._picker.prepare(camera, this.app.scene);
-            const selection = this._picker.getSelection(x, y);
-            if (selection.length > 0) {
-                const item = selection[0];
-                let currentNode = item instanceof playcanvas.MeshInstance ? item.node : item.entity;
-                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 node = await this._pickNode(event);
+            if (!this._picker)
+                return; // the element disconnected while the pick was in flight
+            const entityElement = this._elementWithListener(node, 'pointerdown');
+            if (entityElement) {
+                entityElement.dispatchEvent(new PointerEvent('pointerdown', event));
             }
         }
-        _onPointerUp(event) {
+        async _onPointerUp(event) {
             if (!this._picker || !this.app)
                 return;
-            const camera = this.app.root.findComponent('camera');
-            if (!camera)
-                return;
-            // Convert CSS coordinates to picker coordinates
-            const { x, y } = this._getPickerCoordinates(event);
-            this._picker.prepare(camera, this.app.scene);
-            const selection = this._picker.getSelection(x, y);
-            if (selection.length > 0) {
-                const item = selection[0];
-                const node = item instanceof playcanvas.MeshInstance ? item.node : item.entity;
-                const entityElement = this.querySelector(`pc-entity[name="${node.name}"]`);
-                if (entityElement && entityElement.hasListeners('pointerup')) {
-                    entityElement.dispatchEvent(new PointerEvent('pointerup', event));
-                }
+            const node = await this._pickNode(event);
+            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));
             }
         }
         _onPointerListenerAdded(type) {
@@ -899,28 +1159,43 @@
             }
         }
         /**
-         * 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() {
@@ -928,10 +1203,11 @@
         }
         /**
          * 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;
         }
         /**
@@ -942,18 +1218,20 @@
             return this._backend;
         }
         /**
-         * Sets the depth flag.
-         * @param value - The depth 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 depth(value) {
-            this._depth = value;
+        set depthBuffer(value) {
+            this._warnIfBooted('depth-buffer');
+            this._depthBuffer = value;
         }
         /**
-         * Gets the depth flag.
-         * @returns The depth flag.
+         * Gets whether the frame buffer has a depth buffer.
+         * @returns The depth buffer flag.
          */
-        get depth() {
-            return this._depth;
+        get depthBuffer() {
+            return this._depthBuffer;
         }
         /**
          * Gets the hierarchy ready flag.
@@ -964,39 +1242,68 @@
             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 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
+         * `true` has no effect until the element is next connected. The bar can be themed with the
+         * CSS custom properties `--pc-loading-bar-color`, `--pc-loading-bar-background` and
+         * `--pc-loading-bar-height`.
+         * @param value - The loading bar flag.
          */
-        set highResolution(value) {
-            this._highResolution = value;
+        set loadingBar(value) {
+            this._loadingBar = value;
+            if (!value && this._bar) {
+                this._bar.destroy();
+                this._bar = null;
+            }
+        }
+        /**
+         * Gets whether the application shows its built-in loading bar while it boots and preloads
+         * its assets.
+         * @returns The loading bar flag.
+         */
+        get loadingBar() {
+            return this._loadingBar;
+        }
+        /**
+         * 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 ? window.devicePixelRatio : 1;
+                this.app.graphicsDevice.maxPixelRatio = value;
+                this.app.resizeCanvas();
             }
         }
         /**
-         * Gets the high resolution flag.
-         * @returns The high resolution flag.
+         * Gets the cap on the pixel ratio the application renders at.
+         * @returns The maximum pixel ratio.
          */
-        get highResolution() {
-            return this._highResolution;
+        get maxPixelRatio() {
+            return this._maxPixelRatio;
         }
         /**
-         * Sets the stencil flag.
-         * @param value - The stencil flag.
+         * 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'];
+            return ['alpha', 'antialias', 'backend', 'depth-buffer', 'loading-bar', 'max-pixel-ratio', 'stencil-buffer'];
         }
         attributeChangedCallback(name, _oldValue, newValue) {
             switch (name) {
@@ -1009,14 +1316,17 @@
                 case 'backend':
                     this.backend = parseEnum(newValue, ['webgpu', 'webgl2', 'null'], 'webgpu', name);
                     break;
-                case 'depth':
-                    this.depth = parseBool(newValue, true);
+                case 'depth-buffer':
+                    this.depthBuffer = parseBool(newValue, true);
                     break;
-                case 'high-resolution':
-                    this.highResolution = parseBool(newValue, true);
+                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;
             }
         }
@@ -1086,9 +1396,15 @@
         _built = false;
         _entity = null;
         /**
-         * The PlayCanvas entity instance. Available once the element is ready — await
-         * {@link whenReady} or the element's `ready()` promise before accessing it.
-         * @returns The entity instance.
+         * 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()`
+         * promise before accessing it.
+         * @returns The entity instance, or `null`.
          */
         get entity() {
             return this._entity;
@@ -1100,17 +1416,40 @@
             if (this._entity) {
                 return;
             }
-            // Create a new entity
-            const entity = new playcanvas.Entity(this.getAttribute('name') || this._name, app);
+            // Seed from the cached fields rather than re-reading the attributes. Every observed
+            // attribute is routed through its property setter by attributeChangedCallback, so the field
+            // already holds the parsed attribute value - and it also holds anything assigned through the
+            // property API before the app booted, which reading the attribute back would discard.
+            const entity = new playcanvas.Entity(this._name, app);
             this._entity = entity;
-            entity.enabled = parseBool(this.getAttribute('enabled'), true);
-            entity.setLocalPosition(parseVec3(this.getAttribute('position'), playcanvas.Vec3.ZERO, 'position'));
-            entity.setLocalEulerAngles(parseVec3(this.getAttribute('rotation'), playcanvas.Vec3.ZERO, 'rotation'));
-            entity.setLocalScale(parseVec3(this.getAttribute('scale'), playcanvas.Vec3.ONE, 'scale'));
-            const tags = parseTags(this.getAttribute('tags'));
-            if (tags.length > 0) {
-                entity.tags.add(tags);
-            }
+            entity.enabled = this._enabled;
+            entity.setLocalPosition(this._position);
+            entity.setLocalEulerAngles(this._rotation);
+            entity.setLocalScale(this._scale);
+            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.
+         *
+         * @param entity - The entity that was destroyed.
+         */
+        _onEntityDestroy(entity) {
+            this._appElement?._unregisterEntityElement(entity);
+            this._appElement = null;
+            this._entity = null;
+            this._built = false;
         }
         buildHierarchy(app) {
             if (!this.entity || this._built)
@@ -1128,8 +1467,15 @@
         connectedCallback() {
             // Wait for app to be ready
             const closestApp = this.closestApp;
-            if (!closestApp)
+            if (!closestApp) {
+                // An entity outside an application is inert and never becomes ready, so awaiting it
+                // hangs. Warn rather than fail silently, naming the parent it requires, as every other
+                // misplaced element does.
+                const name = this.getAttribute('name');
+                const label = name ? ` '${name}'` : '';
+                console.warn(`pc-entity${label} must be a descendant of pc-app - entity not created`);
                 return;
+            }
             // If app is already running, create entity immediately
             if (closestApp.hierarchyReady) {
                 const app = closestApp.app;
@@ -1146,17 +1492,11 @@
             }
         }
         disconnectedCallback() {
-            if (this.entity) {
-                // Notify all children that their entities are about to become invalid
-                const children = this.querySelectorAll('pc-entity');
-                children.forEach((child) => {
-                    child._entity = null;
-                });
-                // 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.
@@ -1605,6 +1945,13 @@
      * @attribute {number} pixels-per-unit - For a `sprite` asset, the number of pixels per world unit.
      * @attribute {'simple' | 'sliced' | 'tiled'} render-mode - For a `sprite` asset, how the sprite is
      * rendered when resized.
+     *
+     * @fires {Event} load - Fired each time the asset finishes loading, including a `lazy` asset
+     * loaded later and any subsequent reloads. Does not bubble — listen on this element, or use a
+     * capture-phase listener on an ancestor to observe every asset.
+     * @fires {ErrorEvent} error - Fired when the asset fails to load, with the engine's error in
+     * `message`. Does not bubble. The element still becomes ready — readiness means the load settled,
+     * not that it succeeded.
      */
     class AssetElement extends AsyncElement {
         _lazy = false;
@@ -1648,6 +1995,14 @@
         disconnectedCallback() {
             this.destroyAsset();
         }
+        _onAssetLoad() {
+            this.dispatchEvent(new Event('load'));
+        }
+        _onAssetError(err) {
+            this.dispatchEvent(new ErrorEvent('error', {
+                message: err instanceof Error ? err.message : String(err)
+            }));
+        }
         createAsset() {
             const id = this.getAttribute('id') || '';
             const src = this.getAttribute('src') || '';
@@ -1682,6 +2037,10 @@
                 this.asset = new playcanvas.Asset(id, type, src ? { url: src } : null, data);
             }
             this.asset.preload = !this._lazy;
+            // Forward the engine asset's load outcome as DOM events on this element, like <img>.
+            // Attached before the asset joins the registry, which is what starts a preloaded load.
+            this.asset.on('load', this._onAssetLoad, this);
+            this.asset.on('error', this._onAssetError, this);
         }
         /**
          * Builds the `data` object for the asset from an optional inline `data` attribute (JSON) and,
@@ -1736,6 +2095,9 @@
         }
         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);
+                this.asset.off('error', this._onAssetError, this);
                 // Deregister first so unload() can still notify the registry
                 this.asset.registry?.remove(this.asset);
                 this.asset.unload();
@@ -1831,9 +2193,10 @@
             this._appElement = null;
         }
         /**
-         * The PlayCanvas component instance. Available once the element is ready — await
-         * {@link whenReady} or the element's `ready()` promise before accessing it.
-         * @returns The component instance.
+         * The PlayCanvas component instance. `null` until the element is ready, and also for an
+         * element that is not a descendant of a `<pc-entity>` — await {@link whenReady} or the
+         * element's `ready()` promise before accessing it.
+         * @returns The component instance, or `null`.
          */
         get component() {
             return this._component;
@@ -2280,6 +2643,10 @@
     }
     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],
@@ -2310,7 +2677,7 @@
         _gamma = 'srgb';
         _horizontalFov = false;
         _nearClip = 0.1;
-        _orthographic = false;
+        _projection = 'perspective';
         _orthoHeight = 10;
         _priority = 0;
         _rect = new playcanvas.Vec4(0, 0, 1, 1);
@@ -2334,12 +2701,12 @@
                 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() {
@@ -2581,23 +2948,6 @@
         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.
@@ -2632,6 +2982,23 @@
         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.
@@ -2698,9 +3065,9 @@
                 'gamma',
                 'horizontal-fov',
                 'near-clip',
-                'orthographic',
                 'ortho-height',
                 'priority',
+                'projection',
                 'rect',
                 'scissor-rect',
                 'tonemap'
@@ -2745,15 +3112,15 @@
                 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;
@@ -4726,8 +5093,14 @@
      * created on insertion.
      *
      * The element is metal/rough by default: unlike a bare `StandardMaterial` it enables the metalness
-     * workflow, which is what the `metalness-*` attributes assume and what glTF means by PBR. The
-     * `roughness` and `roughness-map` attributes are aliases for `gloss` and `gloss-map` that
+     * workflow, which is what the `metalness-*` attributes assume and what glTF means by PBR. It also
+     * defaults `metalness` to 0 rather than the engine's 1, because those two defaults have to be
+     * chosen together - the engine's 1 is unreachable under its own `useMetalness` of false, and with
+     * the workflow on it would make every material fully metallic, so `<pc-material diffuse="crimson">`
+     * would render as dark tinted reflections of an environment that may not exist rather than as a
+     * crimson surface. `metalness="1"` remains one attribute away.
+     *
+     * The `roughness` and `roughness-map` attributes are aliases for `gloss` and `gloss-map` that
      * additionally invert the gloss channel; do not mix the two families on one element.
      *
      * The two aliases are documented here rather than on an accessor, because they resolve to the
@@ -4787,7 +5160,7 @@
         _heightMapRotation = 0;
         _heightMapTiling = new playcanvas.Vec2(1, 1);
         _heightMapUv = 0;
-        _metalness = 1;
+        _metalness = 0;
         _metalnessMap = '';
         _metalnessMapChannel = 'g';
         _metalnessMapOffset = new playcanvas.Vec2(0, 0);
@@ -6730,7 +7103,7 @@
                     this.heightMapUv = parseNumber(newValue, 0, name);
                     break;
                 case 'metalness':
-                    this.metalness = parseNumber(newValue, 1, name);
+                    this.metalness = parseNumber(newValue, 0, name);
                     break;
                 case 'metalness-map':
                     this.metalnessMap = newValue ?? '';
@@ -7165,6 +7538,14 @@
     }
     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.
@@ -7178,7 +7559,7 @@
         _resolution = new playcanvas.Vec2(640, 320);
         _referenceResolution = new playcanvas.Vec2(640, 320);
         _priority = 0;
-        _blend = false;
+        _scaleMode = 'none';
         _scaleBlend = 0.5;
         /** @ignore */
         constructor() {
@@ -7190,7 +7571,7 @@
                 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
             };
         }
@@ -7228,23 +7609,44 @@
         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;
@@ -7258,12 +7660,12 @@
         static get observedAttributes() {
             return [
                 ...super.observedAttributes,
-                'blend',
                 'screen-space',
                 'resolution',
                 'reference-resolution',
                 'priority',
-                'scale-blend'
+                'scale-blend',
+                'scale-mode'
             ];
         }
         attributeChangedCallback(name, _oldValue, newValue) {
@@ -7281,8 +7683,8 @@
                 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);
@@ -7505,7 +7907,8 @@
             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) {
@@ -7515,14 +7918,15 @@
             }
         }
         /**
-         * 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) {
@@ -7532,7 +7936,7 @@
             }
         }
         /**
-         * Gets whether vertical scrolling is enabled.
+         * Gets whether scrolling along the vertical axis is enabled.
          * @returns Whether vertical scrolling is enabled.
          */
         get vertical() {
@@ -9328,30 +9732,58 @@
         _gravity = new playcanvas.Vec3(0, -9.81, 0);
         _scene = null;
         /**
-         * The PlayCanvas scene instance. Available once the element is ready — await
+         * The PlayCanvas scene instance. `null` until the element is ready — await
          * {@link whenReady} or the element's `ready()` promise before accessing it.
-         * @returns The scene instance.
+         * @returns The scene instance, or `null`.
          */
         get scene() {
             return this._scene;
         }
         async connectedCallback() {
-            await this.closestApp?.ready();
-            this._scene = this.closestApp.app.scene;
+            const appElement = this.closestApp;
+            if (!appElement) {
+                console.warn('pc-scene must be a descendant of pc-app - scene settings not applied');
+                return;
+            }
+            await appElement.ready();
+            // The element may have been removed or re-parented while waiting for the app. Matches the
+            // guard in AssetElement and MaterialElement, but compares closestApp rather than
+            // parentElement because pc-scene resolves its app by ancestor rather than direct child.
+            // Without this, a scene re-parented mid-await would take its Scene from the app it started
+            // under while _applyGravity resolved the app it ended up under, splitting the two.
+            if (!this.isConnected || this.closestApp !== appElement) {
+                return;
+            }
+            // The application is gone if the tree was torn down while we awaited readiness. There is
+            // nothing to configure and nothing the author can act on, so this stays silent.
+            const app = appElement.app;
+            if (!app) {
+                return;
+            }
+            this._scene = app.scene;
             this.updateSceneSettings();
             this._onReady();
         }
         updateSceneSettings() {
-            if (this.scene) {
-                this.scene.fog.type = this._fog;
-                this.scene.fog.color = this._fogColor;
-                this.scene.fog.density = this._fogDensity;
-                this.scene.fog.start = this._fogStart;
-                this.scene.fog.end = this._fogEnd;
-                const appElement = this.parentElement;
-                appElement.app.systems.rigidbody.gravity.copy(this._gravity);
+            if (this._scene) {
+                this._scene.fog.type = this._fog;
+                this._scene.fog.color = this._fogColor;
+                this._scene.fog.density = this._fogDensity;
+                this._scene.fog.start = this._fogStart;
+                this._scene.fog.end = this._fogEnd;
+                this._applyGravity(this._gravity);
             }
         }
+        /**
+         * Applies gravity to the rigid body system. Resolved through `closestApp` rather than
+         * `parentElement` so that a `<pc-scene>` nested inside a wrapper element behaves the same as
+         * a direct child, matching how `connectedCallback` resolves the application.
+         *
+         * @param value - The gravity to apply.
+         */
+        _applyGravity(value) {
+            this.closestApp?.app?.systems.rigidbody?.gravity.copy(value);
+        }
         /**
          * Sets the fog type of the scene. Can be `none`, `linear`, `exp` or `exp2`. Defaults to
          * `none`.
@@ -9444,9 +9876,8 @@
          */
         set gravity(value) {
             this._gravity = value;
-            if (this.scene) {
-                const appElement = this.parentElement;
-                appElement.app.systems.rigidbody.gravity.copy(value);
+            if (this._scene) {
+                this._applyGravity(value);
             }
         }
         /**
@@ -9495,7 +9926,7 @@
         _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';
@@ -9529,7 +9960,7 @@
             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() {
             const appElement = await this.closestApp?.ready();
@@ -9621,23 +10052,6 @@
         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.
@@ -9652,6 +10066,24 @@
         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.
@@ -9708,7 +10140,7 @@
             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) {
@@ -9721,12 +10153,12 @@
                 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;