@playcanvas/web-components 0.10.0 → 0.10.1

package/dist/pwc.mjs

@@ -16,11 +16,21 @@ class AsyncElement extends HTMLElement {
             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
@@ -114,6 +124,116 @@ class ModuleElement extends HTMLElement {
 }
 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',
@@ -541,6 +661,11 @@ const getEntity = (ref) => {
  * {@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 {
     /**
@@ -553,6 +678,8 @@ class AppElement extends AsyncElement {
     _depth = true;
     _stencil = true;
     _highResolution = true;
+    _loadingBar = true;
+    _bar = null;
     _hierarchyReady = false;
     _picker = null;
     _hasPointerListeners = {
@@ -563,20 +690,34 @@ class AppElement extends AsyncElement {
         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.
      *
@@ -588,6 +729,11 @@ class AppElement extends AsyncElement {
         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
@@ -675,10 +821,11 @@ class AppElement extends AsyncElement {
         createOptions.lightmapper = Lightmapper;
         createOptions.batchManager = BatchManager;
         createOptions.xr = XrManager;
-        this._app = new AppBase(this._canvas);
-        this.app.init(createOptions);
-        this.app.setCanvasFillMode(FILLMODE_FILL_WINDOW);
-        this.app.setCanvasResolution(RESOLUTION_AUTO);
+        const app = new AppBase(this._canvas);
+        this._app = app;
+        app.init(createOptions);
+        app.setCanvasFillMode(FILLMODE_FILL_WINDOW);
+        app.setCanvasResolution(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');
@@ -686,7 +833,7 @@ class AppElement extends AsyncElement {
             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
@@ -697,17 +844,39 @@ class AppElement extends AsyncElement {
         // 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();
@@ -716,10 +885,13 @@ class AppElement extends AsyncElement {
     disconnectedCallback() {
         this._pickerDestroy();
         // Clean up the application
-        if (this.app) {
-            this.app.destroy();
+        if (this._app) {
+            this._app.destroy();
             this._app = null;
         }
+        this._loadProgress = 0;
+        this._bar?.destroy();
+        this._bar = null;
         // Remove event listeners
         window.removeEventListener('resize', this._onWindowResize);
         // Remove the canvas
@@ -736,10 +908,17 @@ class AppElement extends AsyncElement {
     _pickerCreate() {
         const { width, height } = this.app.graphicsDevice;
         this._picker = new 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));
@@ -787,29 +966,49 @@ class AppElement extends AsyncElement {
         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);
+        const selection = await this._picker.getSelectionAsync(x, y);
+        if (selection.length === 0)
+            return null;
+        const item = selection[0];
+        return item instanceof 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;
         // 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 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;
+        let currentNode = node;
+        while (currentNode !== null) {
+            const entityElement = this.querySelector(`pc-entity[name="${currentNode.name}"]`);
+            if (entityElement) {
+                newHoverEntity = entityElement;
+                break;
             }
+            currentNode = currentNode.parent;
         }
         // Handle enter/leave events
         if (this._hoveredEntity !== newHoverEntity) {
@@ -827,46 +1026,30 @@ class AppElement extends AsyncElement {
             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 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;
+        let currentNode = 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;
         }
     }
-    _onPointerUp(event) {
+    async _onPointerUp(event) {
         if (!this._picker || !this.app)
             return;
-        const camera = this.app.root.findComponent('camera');
-        if (!camera)
+        const node = await this._pickNode(event);
+        if (!node || !this._picker)
             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 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 entityElement = this.querySelector(`pc-entity[name="${node.name}"]`);
+        if (entityElement && entityElement.hasListeners('pointerup')) {
+            entityElement.dispatchEvent(new PointerEvent('pointerup', event));
         }
     }
     _onPointerListenerAdded(type) {
@@ -977,6 +1160,29 @@ class AppElement extends AsyncElement {
     get highResolution() {
         return this._highResolution;
     }
+    /**
+     * 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 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 stencil flag.
      * @param value - The stencil flag.
@@ -992,7 +1198,7 @@ class AppElement extends AsyncElement {
         return this._stencil;
     }
     static get observedAttributes() {
-        return ['alpha', 'antialias', 'backend', 'depth', 'stencil', 'high-resolution'];
+        return ['alpha', 'antialias', 'backend', 'depth', 'stencil', 'high-resolution', 'loading-bar'];
     }
     attributeChangedCallback(name, _oldValue, newValue) {
         switch (name) {
@@ -1011,6 +1217,9 @@ class AppElement extends AsyncElement {
             case 'high-resolution':
                 this.highResolution = parseBool(newValue, true);
                 break;
+            case 'loading-bar':
+                this.loadingBar = parseBool(newValue, true);
+                break;
             case 'stencil':
                 this.stencil = parseBool(newValue, true);
                 break;
@@ -1082,9 +1291,10 @@ class EntityElement extends AsyncElement {
     _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 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;
@@ -1096,16 +1306,18 @@ class EntityElement extends AsyncElement {
         if (this._entity) {
             return;
         }
-        // Create a new entity
-        const entity = new 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 Entity(this._name, app);
         this._entity = entity;
-        entity.enabled = parseBool(this.getAttribute('enabled'), true);
-        entity.setLocalPosition(parseVec3(this.getAttribute('position'), Vec3.ZERO, 'position'));
-        entity.setLocalEulerAngles(parseVec3(this.getAttribute('rotation'), Vec3.ZERO, 'rotation'));
-        entity.setLocalScale(parseVec3(this.getAttribute('scale'), 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);
         }
     }
     buildHierarchy(app) {
@@ -1124,8 +1336,15 @@ class EntityElement extends AsyncElement {
     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;
@@ -1143,10 +1362,15 @@ class EntityElement extends AsyncElement {
     }
     disconnectedCallback() {
         if (this.entity) {
-            // Notify all children that their entities are about to become invalid
+            // 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();
@@ -1601,6 +1825,13 @@ const processBufferView = (gltfBuffer, buffers, continuation) => {
  * @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;
@@ -1644,6 +1875,14 @@ class AssetElement extends AsyncElement {
     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') || '';
@@ -1678,6 +1917,10 @@ class AssetElement extends AsyncElement {
             this.asset = new 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,
@@ -1732,6 +1975,9 @@ class AssetElement extends AsyncElement {
     }
     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();
@@ -1827,9 +2073,10 @@ class ComponentElement extends AsyncElement {
         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;
@@ -4722,8 +4969,14 @@ const roughnessAliases = ['roughness', 'roughness-map'];
  * 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
@@ -4783,7 +5036,7 @@ class MaterialElement extends HTMLElement {
     _heightMapRotation = 0;
     _heightMapTiling = new Vec2(1, 1);
     _heightMapUv = 0;
-    _metalness = 1;
+    _metalness = 0;
     _metalnessMap = '';
     _metalnessMapChannel = 'g';
     _metalnessMapOffset = new Vec2(0, 0);
@@ -6726,7 +6979,7 @@ class MaterialElement extends HTMLElement {
                 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 ?? '';
@@ -9324,30 +9577,58 @@ class SceneElement extends AsyncElement {
     _gravity = new 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`.
@@ -9440,9 +9721,8 @@ class SceneElement extends AsyncElement {
      */
     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);
         }
     }
     /**