@playcanvas/web-components 0.9.0 → 0.10.1

package/dist/pwc.js

@@ -6,8 +6,13 @@
 
     /**
      * Base class for all PlayCanvas Web Components that initialize asynchronously.
+     *
+     * @fires {CustomEvent} ready - Fired once the element is fully initialized. Bubbles and is
+     * composed.
      */
     class AsyncElement extends HTMLElement {
+        _readyPromise;
+        _readyResolve;
         /** @ignore */
         constructor() {
             super();
@@ -15,13 +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() {
-            var _a;
-            return (_a = this.parentElement) === null || _a === void 0 ? void 0 : _a.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() {
-            var _a;
-            return (_a = this.parentElement) === null || _a === void 0 ? void 0 : _a.closest('pc-entity');
+            return this.parentElement?.closest('pc-entity') ?? null;
         }
         /**
          * Called when the element is fully initialized and ready. Subclasses should call this when
@@ -52,7 +65,7 @@
             try {
                 element = document.querySelector(target);
             }
-            catch (_a) {
+            catch {
                 throw new Error(`whenReady: '${target}' is not a valid CSS selector`);
             }
             if (!element) {
@@ -75,8 +88,19 @@
      * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-module/ | `<pc-module>`} elements.
      * The ModuleElement interface also inherits the properties and methods of the
      * {@link HTMLElement} interface.
+     *
+     * Note that these attributes are read once when the element is created, so changing them later
+     * has no effect.
+     *
+     * @attribute {string} name - The name of the WebAssembly module to configure, e.g. `Basis` or
+     * `Ammo`.
+     * @attribute {string} glue - The URL of the module's glue script.
+     * @attribute {string} wasm - The URL of the module's WebAssembly binary.
+     * @attribute {string} fallback - The URL of the module's asm.js fallback script, used when
+     * WebAssembly is unavailable.
      */
     class ModuleElement extends HTMLElement {
+        loadPromise;
         /** @ignore */
         constructor() {
             super();
@@ -104,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',
@@ -256,20 +390,22 @@
     };
 
     /**
-     * Parse a boolean attribute value. The same rules apply to every boolean attribute:
+     * Converts HTML attribute values into the values the engine expects. Every element's
+     * `attributeChangedCallback` funnels through this module.
      *
-     * - Attribute absent (or removed): the supplied default is used.
-     * - Attribute set to the string 'false': `false`.
-     * - Attribute present with any other value, including the empty string of a bare boolean
-     *   attribute (e.g. `<pc-light cast-shadows>`): `true`.
+     * The parsers share one contract:
      *
-     * @param value - The attribute value to parse (`null` when the attribute is absent).
-     * @param defaultValue - The value to use when the attribute is absent or removed.
-     * @returns The parsed boolean.
+     * - A `null` value means the attribute is absent or was removed, and yields the supplied default.
+     * - A malformed value yields the same default and logs exactly one `console.warn` naming the
+     *   attribute, so misuse is reported rather than thrown — nothing here throws or rejects.
+     * - A math-type default is cloned on the way out, which is what makes it safe to pass the engine's
+     *   shared frozen constants (`Vec3.ZERO`, `Color.WHITE`) as defaults.
+     * - `parseBool` and `parseTags` take no attribute name, because every value is valid for them and
+     *   so they never warn.
+     *
+     * `getEntity` is the exception: it resolves a reference to a live entity rather than parsing a
+     * literal, and returns `null` instead of falling back to a default.
      */
-    const parseBool = (value, defaultValue) => {
-        return value === null ? defaultValue : value !== 'false';
-    };
     /**
      * Splits an attribute value into exactly `count` numeric components. Returns `null` when the
      * value does not consist of exactly `count` whitespace-separated finite numbers.
@@ -297,6 +433,21 @@
     const cloneDefault = (value) => {
         return (value === null ? null : value.clone());
     };
+    /**
+     * Parse a boolean attribute value. The same rules apply to every boolean attribute:
+     *
+     * - Attribute absent (or removed): the supplied default is used.
+     * - Attribute set to the string 'false': `false`.
+     * - Attribute present with any other value, including the empty string of a bare boolean
+     *   attribute (e.g. `<pc-light cast-shadows>`): `true`.
+     *
+     * @param value - The attribute value to parse (`null` when the attribute is absent).
+     * @param defaultValue - The value to use when the attribute is absent or removed.
+     * @returns The parsed boolean.
+     */
+    const parseBool = (value, defaultValue) => {
+        return value === null ? defaultValue : value !== 'false';
+    };
     /**
      * Parse a color attribute value. The expected format is a CSS color name (e.g. 'rebeccapurple'),
      * a hex color (e.g. '#ff0000' or '#f00'), or 3 or 4 space-separated numbers in the range 0 to 1
@@ -310,7 +461,6 @@
      * @returns The parsed Color object.
      */
     const parseColor = (value, defaultValue, attribute) => {
-        var _a;
         if (value === null) {
             return cloneDefault(defaultValue);
         }
@@ -328,13 +478,56 @@
             return new playcanvas.Color().fromString(`#${hex}`);
         }
         // 3 or 4 space-separated components (e.g. '1 0.5 0.5')
-        const components = (_a = parseComponents(value, 4)) !== null && _a !== void 0 ? _a : parseComponents(value, 3);
+        const components = parseComponents(value, 4) ?? parseComponents(value, 3);
         if (components) {
             return new playcanvas.Color(components);
         }
         console.warn(`Invalid value '${value}' for attribute '${attribute}'. Expected a CSS color name, a hex color or 3 or 4 space-separated numbers. Using '${defaultValue}'.`);
         return cloneDefault(defaultValue);
     };
+    /**
+     * Resolves an enum attribute value against its set of valid names. Returns the value when it is
+     * one of the valid names. Returns `defaultValue` when the attribute is absent (`null`), or when
+     * 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 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.
+     */
+    const parseEnum = (value, valid, defaultValue, attribute) => {
+        if (value === null) {
+            return defaultValue;
+        }
+        const names = Array.isArray(valid) ? valid : [...valid.keys()];
+        if (names.includes(value)) {
+            return value;
+        }
+        console.warn(`Invalid value '${value}' for attribute '${attribute}'. Valid values: ${names.join(', ')}. Using '${defaultValue}'.`);
+        return defaultValue;
+    };
+    /**
+     * Parses a number attribute value. Returns the parsed number when the value is a finite number.
+     * Returns `defaultValue` when the attribute is absent (`null`), or when the value is not a
+     * finite number — the latter also logs a warning.
+     *
+     * @param value - The attribute value to parse (`null` when the attribute is absent).
+     * @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 parsed number.
+     */
+    const parseNumber = (value, defaultValue, attribute) => {
+        if (value === null) {
+            return defaultValue;
+        }
+        const number = value.trim() === '' ? NaN : Number(value);
+        if (!Number.isFinite(number)) {
+            console.warn(`Invalid value '${value}' for attribute '${attribute}'. Expected a finite number. Using '${defaultValue}'.`);
+            return defaultValue;
+        }
+        return number;
+    };
     /**
      * Parse an Euler-angles attribute value into a quaternion. The expected format is 3
      * space-separated angles in degrees (e.g. '0 90 0'). Returns `defaultValue` (cloned, when it is
@@ -357,6 +550,26 @@
         }
         return new playcanvas.Quat().setFromEulerAngles(components[0], components[1], components[2]);
     };
+    /**
+     * Parse a tags attribute value. The expected format is a comma-separated list of tag names
+     * (e.g. 'enemy, flying'). Surrounding whitespace is trimmed from each name and empty names are
+     * discarded, so a trailing comma or a doubled separator does not produce a blank tag. Returns a
+     * copy of `defaultValue` when the attribute is absent or removed (`null`).
+     *
+     * Every value is valid, so this never warns.
+     *
+     * @param value - The attribute value to parse (`null` when the attribute is absent).
+     * @param defaultValue - The value to use when the attribute is absent or removed.
+     * @returns The parsed tag names.
+     */
+    const parseTags = (value, defaultValue = []) => {
+        if (value === null) {
+            // Copied for the same reason cloneDefault exists: a parsed result must never alias the
+            // caller's default, or a later mutation would write back through it.
+            return [...defaultValue];
+        }
+        return value.split(',').map(tag => tag.trim()).filter(tag => tag !== '');
+    };
     /**
      * Parse a Vec2 attribute value. The expected format is 2 space-separated numbers (e.g. '1 2').
      * Returns `defaultValue` (cloned, when it is a vector) when the attribute is absent (`null`),
@@ -420,49 +633,6 @@
         }
         return new playcanvas.Vec4(components);
     };
-    /**
-     * Resolves an enum attribute value against its set of valid names. Returns the value when it is
-     * one of the valid names. Returns `defaultValue` when the attribute is absent (`null`), or when
-     * 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 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.
-     */
-    const parseEnum = (value, valid, defaultValue, attribute) => {
-        if (value === null) {
-            return defaultValue;
-        }
-        const names = Array.isArray(valid) ? valid : [...valid.keys()];
-        if (names.includes(value)) {
-            return value;
-        }
-        console.warn(`Invalid value '${value}' for attribute '${attribute}'. Valid values: ${names.join(', ')}. Using '${defaultValue}'.`);
-        return defaultValue;
-    };
-    /**
-     * Parses a number attribute value. Returns the parsed number when the value is a finite number.
-     * Returns `defaultValue` when the attribute is absent (`null`), or when the value is not a
-     * finite number — the latter also logs a warning.
-     *
-     * @param value - The attribute value to parse (`null` when the attribute is absent).
-     * @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 parsed number.
-     */
-    const parseNumber = (value, defaultValue, attribute) => {
-        if (value === null) {
-            return defaultValue;
-        }
-        const number = value.trim() === '' ? NaN : Number(value);
-        if (!Number.isFinite(number)) {
-            console.warn(`Invalid value '${value}' for attribute '${attribute}'. Expected a finite number. Using '${defaultValue}'.`);
-            return defaultValue;
-        }
-        return number;
-    };
     /**
      * Resolves a reference string to the {@link Entity} backing a `<pc-entity>` element. The reference
      * can be a CSS selector (e.g. `#my-id`, `pc-entity[name="Foo"]`), a bare element id, or a bare
@@ -472,7 +642,6 @@
      * @returns The resolved entity, or `null`.
      */
     const getEntity = (ref) => {
-        var _a, _b;
         if (!ref) {
             return null;
         }
@@ -482,13 +651,13 @@
         try {
             element = document.querySelector(ref);
         }
-        catch (_c) {
+        catch {
             element = null;
         }
         if (!element) {
-            element = (_a = document.getElementById(ref)) !== null && _a !== void 0 ? _a : document.querySelector(`pc-entity[name="${ref}"]`);
+            element = document.getElementById(ref) ?? document.querySelector(`pc-entity[name="${ref}"]`);
         }
-        return (_b = element === null || element === void 0 ? void 0 : element.entity) !== null && _b !== void 0 ? _b : null;
+        return element?.entity ?? null;
     };
 
     /**
@@ -496,16 +665,63 @@
      * {@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 {
         /**
-         * 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 canvas element.
+         */
+        _canvas = null;
+        _alpha = true;
+        _backend = 'webgpu';
+        _antialias = true;
+        _depth = true;
+        _stencil = true;
+        _highResolution = true;
+        _loadingBar = true;
+        _bar = null;
+        _hierarchyReady = false;
+        _picker = null;
+        _hasPointerListeners = {
+            pointerenter: false,
+            pointerleave: false,
+            pointerdown: false,
+            pointerup: false,
+            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. `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.
          *
@@ -513,36 +729,15 @@
          */
         constructor() {
             super();
-            /**
-             * The canvas element.
-             */
-            this._canvas = null;
-            this._alpha = true;
-            this._backend = 'webgl2';
-            this._antialias = true;
-            this._depth = true;
-            this._stencil = true;
-            this._highResolution = true;
-            this._hierarchyReady = false;
-            this._picker = null;
-            this._hasPointerListeners = {
-                pointerenter: false,
-                pointerleave: false,
-                pointerdown: false,
-                pointerup: false,
-                pointermove: false
-            };
-            this._hoveredEntity = null;
-            this._pointerHandlers = {
-                pointermove: null,
-                pointerdown: null,
-                pointerup: null
-            };
-            this._app = null;
             // Bind methods to maintain 'this' context
             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
@@ -630,10 +825,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');
@@ -641,7 +837,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
@@ -652,17 +848,39 @@
             // 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();
@@ -671,10 +889,13 @@
         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
@@ -691,10 +912,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));
@@ -742,29 +970,49 @@
             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 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;
             // 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;
+            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) {
@@ -782,46 +1030,30 @@
                 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;
+            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 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 entityElement = this.querySelector(`pc-entity[name="${node.name}"]`);
+            if (entityElement && entityElement.hasListeners('pointerup')) {
+                entityElement.dispatchEvent(new PointerEvent('pointerup', event));
             }
         }
         _onPointerListenerAdded(type) {
@@ -878,7 +1110,8 @@
             return this._antialias;
         }
         /**
-         * Sets the graphics backend.
+         * Sets the graphics backend. Defaults to 'webgpu', which falls back to 'webgl2' if WebGPU
+         * is not supported by the browser.
          * @param value - The graphics backend ('webgpu', 'webgl2', or 'null').
          */
         set backend(value) {
@@ -931,6 +1164,29 @@
         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.
@@ -946,7 +1202,7 @@
             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) {
@@ -957,7 +1213,7 @@
                     this.antialias = parseBool(newValue, true);
                     break;
                 case 'backend':
-                    this.backend = parseEnum(newValue, ['webgpu', 'webgl2', 'null'], 'webgl2', name);
+                    this.backend = parseEnum(newValue, ['webgpu', 'webgl2', 'null'], 'webgpu', name);
                     break;
                 case 'depth':
                     this.depth = parseBool(newValue, true);
@@ -965,6 +1221,9 @@
                 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;
@@ -978,52 +1237,68 @@
      * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-entity/ | `<pc-entity>`} elements.
      * The EntityElement interface also inherits the properties and methods of the
      * {@link HTMLElement} interface.
+     *
+     * The pointer events below are dispatched by the containing `<pc-app>` element when the pointer
+     * intersects this entity's geometry. They are only generated while the entity has a listener for
+     * them, registered either with {@link addEventListener} or with the matching inline `onpointer*`
+     * attribute.
+     *
+     * @attribute {string} onpointerenter - Script to run when the pointer moves onto the entity.
+     * @attribute {string} onpointerleave - Script to run when the pointer moves off the entity.
+     * @attribute {string} onpointermove - Script to run when the pointer moves over the entity.
+     * @attribute {string} onpointerdown - Script to run when a pointer button is pressed over the
+     * entity.
+     * @attribute {string} onpointerup - Script to run when a pointer button is released over the
+     * entity.
+     * @fires {PointerEvent} pointerenter - Fired when the pointer moves onto the entity.
+     * @fires {PointerEvent} pointerleave - Fired when the pointer moves off the entity.
+     * @fires {PointerEvent} pointermove - Fired when the pointer moves over the entity.
+     * @fires {PointerEvent} pointerdown - Fired when a pointer button is pressed over the entity.
+     * @fires {PointerEvent} pointerup - Fired when a pointer button is released over the entity.
      */
     class EntityElement extends AsyncElement {
-        constructor() {
-            super(...arguments);
-            /**
-             * Whether the entity is enabled.
-             */
-            this._enabled = true;
-            /**
-             * The name of the entity.
-             */
-            this._name = 'Untitled';
-            /**
-             * The position of the entity.
-             */
-            this._position = new playcanvas.Vec3();
-            /**
-             * The rotation of the entity.
-             */
-            this._rotation = new playcanvas.Vec3();
-            /**
-             * The scale of the entity.
-             */
-            this._scale = new playcanvas.Vec3(1, 1, 1);
-            /**
-             * The tags of the entity.
-             */
-            this._tags = [];
-            /**
-             * The pointer event listeners for the entity.
-             */
-            this._listeners = {};
-            /**
-             * The event types for which an inline `onpointer*` attribute is currently present.
-             */
-            this._inlineHandlerTypes = new Set();
-            /**
-             * Whether the hierarchy has been built for this entity.
-             */
-            this._built = false;
-            this._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.
+         * Whether the entity is enabled.
+         */
+        _enabled = true;
+        /**
+         * The name of the entity.
+         */
+        _name = 'Untitled';
+        /**
+         * The position of the entity.
+         */
+        _position = new playcanvas.Vec3();
+        /**
+         * The rotation of the entity.
+         */
+        _rotation = new playcanvas.Vec3();
+        /**
+         * The scale of the entity.
+         */
+        _scale = new playcanvas.Vec3(1, 1, 1);
+        /**
+         * The tags of the entity.
+         */
+        _tags = [];
+        /**
+         * The pointer event listeners for the entity.
+         */
+        _listeners = {};
+        /**
+         * The event types for which an inline `onpointer*` attribute is currently present.
+         */
+        _inlineHandlerTypes = new Set();
+        /**
+         * Whether the hierarchy has been built for this entity.
+         */
+        _built = false;
+        _entity = 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;
@@ -1035,16 +1310,18 @@
             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 = this.getAttribute('tags');
-            if (tags) {
-                entity.tags.add(tags.split(',').map(tag => tag.trim()));
+            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) {
@@ -1052,7 +1329,7 @@
                 return;
             this._built = true;
             const closestEntity = this.closestEntity;
-            if (closestEntity === null || closestEntity === void 0 ? void 0 : closestEntity.entity) {
+            if (closestEntity?.entity) {
                 closestEntity.entity.addChild(this.entity);
             }
             else {
@@ -1063,8 +1340,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;
@@ -1082,10 +1366,15 @@
         }
         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();
@@ -1241,7 +1530,7 @@
                     this.enabled = parseBool(newValue, true);
                     break;
                 case 'name':
-                    this.name = newValue;
+                    this.name = newValue ?? 'Untitled';
                     break;
                 case 'position':
                     this.position = parseVec3(newValue, playcanvas.Vec3.ZERO, name);
@@ -1253,7 +1542,7 @@
                     this.scale = parseVec3(newValue, playcanvas.Vec3.ONE, name);
                     break;
                 case 'tags':
-                    this.tags = newValue.split(',').map(tag => tag.trim());
+                    this.tags = parseTags(newValue);
                     break;
                 case 'onpointerenter':
                 case 'onpointerleave':
@@ -1284,8 +1573,7 @@
             }
         }
         hasListeners(type) {
-            var _a;
-            return Boolean((_a = this._listeners[type]) === null || _a === void 0 ? void 0 : _a.length) || this._inlineHandlerTypes.has(type);
+            return Boolean(this._listeners[type]?.length) || this._inlineHandlerTypes.has(type);
         }
     }
     customElements.define('pc-entity', EntityElement);
@@ -1477,11 +1765,13 @@
         ['frag', 'shader'],
         ['glb', 'container'],
         ['glsl', 'shader'],
+        ['gltf', 'container'],
         ['hdr', 'texture'],
         ['html', 'html'],
         ['jpg', 'texture'],
         ['js', 'script'],
         ['json', 'json'],
+        ['ktx2', 'texture'],
         ['mp3', 'audio'],
         ['mjs', 'script'],
         ['ply', 'gsplat'],
@@ -1524,25 +1814,43 @@
      * while the application is running are created and registered on insertion, and begin loading
      * immediately unless `lazy`. A `pc-asset` must be a direct child of `pc-app` — elements placed
      * elsewhere, or with an unsupported asset type, never become ready.
+     *
+     * Apart from `lazy`, these attributes are read once when the asset is created, so changing them
+     * later has no effect.
+     *
+     * @attribute {string} id - The identifier used to reference the asset from other elements.
+     * @attribute {string} src - The URL of the asset to load.
+     * @attribute {string} type - The asset type. Inferred from the `src` file extension when omitted.
+     * @attribute {string} data - Additional asset data, as a JSON object.
+     * @attribute {string} atlas - For a `sprite` asset, the `id` of the texture atlas asset it uses.
+     * The atlas must be declared before the sprite.
+     * @attribute {string} frame-keys - For a `sprite` asset, the atlas frame keys it uses, separated
+     * by spaces or commas.
+     * @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 {
-        constructor() {
-            super(...arguments);
-            this._lazy = false;
-            /**
-             * The asset that is loaded. Available once the element is ready — await
-             * {@link whenReady} or the element's `ready()` promise before accessing it.
-             */
-            this.asset = null;
-        }
+        _lazy = false;
+        /**
+         * The asset that is loaded. Available once the element is ready — await
+         * {@link whenReady} or the element's `ready()` promise before accessing it.
+         */
+        asset = null;
         async connectedCallback() {
-            var _a;
             const appElement = this.closestApp;
             if (!appElement)
                 return;
             // Assets must be direct children of pc-app (matches the boot query ':scope > pc-asset')
             if (this.parentElement !== appElement) {
-                console.warn(`pc-asset '${(_a = this.getAttribute('id')) !== null && _a !== void 0 ? _a : this.getAttribute('src')}' must be a direct child of pc-app - asset not created`);
+                console.warn(`pc-asset '${this.getAttribute('id') ?? this.getAttribute('src')}' must be a direct child of pc-app - asset not created`);
                 return;
             }
             await appElement.ready();
@@ -1571,15 +1879,22 @@
         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() {
-            var _a;
             const id = this.getAttribute('id') || '';
             const src = this.getAttribute('src') || '';
             let type = this.getAttribute('type');
             // If no type is specified, try to infer it from the file extension.
             if (!type) {
                 const ext = src.split('.').pop();
-                type = (_a = extToType.get(ext || '')) !== null && _a !== void 0 ? _a : null;
+                type = extToType.get(ext || '') ?? null;
             }
             if (!type) {
                 console.warn(`Unsupported asset type: ${src}`);
@@ -1606,6 +1921,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,
@@ -1615,7 +1934,6 @@
          * @returns The asset data, or `undefined`.
          */
         _buildData(type) {
-            var _a, _b, _c, _d;
             let data;
             const dataAttr = this.getAttribute('data');
             if (dataAttr) {
@@ -1627,10 +1945,10 @@
                 }
             }
             if (type === 'sprite') {
-                data = data !== null && data !== void 0 ? data : {};
+                data = data ?? {};
                 // Resolve the referenced texture atlas to its (numeric) asset id. The atlas must be
                 // declared before the sprite so its asset already exists in the registry.
-                const atlas = (_a = this.getAttribute('atlas')) !== null && _a !== void 0 ? _a : data.textureAtlasAsset;
+                const atlas = this.getAttribute('atlas') ?? data.textureAtlasAsset;
                 if (typeof atlas === 'string') {
                     const atlasAsset = AssetElement.get(atlas);
                     if (atlasAsset) {
@@ -1653,17 +1971,19 @@
                     data.renderMode = renderModes.get(parseEnum(renderMode, renderModes, 'simple', 'render-mode'));
                 }
                 // Apply engine defaults for any values not supplied.
-                data.renderMode = (_b = data.renderMode) !== null && _b !== void 0 ? _b : playcanvas.SPRITE_RENDERMODE_SIMPLE;
-                data.pixelsPerUnit = (_c = data.pixelsPerUnit) !== null && _c !== void 0 ? _c : 1;
-                data.frameKeys = (_d = data.frameKeys) !== null && _d !== void 0 ? _d : [];
+                data.renderMode = data.renderMode ?? playcanvas.SPRITE_RENDERMODE_SIMPLE;
+                data.pixelsPerUnit = data.pixelsPerUnit ?? 1;
+                data.frameKeys = data.frameKeys ?? [];
             }
             return data;
         }
         destroyAsset() {
-            var _a;
             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
-                (_a = this.asset.registry) === null || _a === void 0 ? void 0 : _a.remove(this.asset);
+                this.asset.registry?.remove(this.asset);
                 this.asset.unload();
                 this.asset = null;
             }
@@ -1687,7 +2007,7 @@
         }
         static get(id) {
             const assetElement = document.querySelector(`pc-asset[id="${id}"]`);
-            return assetElement === null || assetElement === void 0 ? void 0 : assetElement.asset;
+            return assetElement?.asset;
         }
         static get observedAttributes() {
             return ['lazy'];
@@ -1706,6 +2026,10 @@
      * @category Components
      */
     class ComponentElement extends AsyncElement {
+        _componentName;
+        _enabled = true;
+        _component = null;
+        _appElement = null;
         /**
          * Creates a new ComponentElement instance.
          *
@@ -1714,9 +2038,6 @@
          */
         constructor(componentName) {
             super();
-            this._enabled = true;
-            this._component = null;
-            this._appElement = null;
             this._componentName = componentName;
         }
         // Method to be overridden by subclasses to provide initial component data
@@ -1739,28 +2060,27 @@
         }
         initComponent() { }
         async connectedCallback() {
-            var _a, _b;
-            this._appElement = (_a = this.closestApp) !== null && _a !== void 0 ? _a : null;
-            await ((_b = this._appElement) === null || _b === void 0 ? void 0 : _b.ready());
+            this._appElement = this.closestApp ?? null;
+            await this._appElement?.ready();
             await this.addComponent();
             this.initComponent();
             this._onReady();
         }
         disconnectedCallback() {
-            var _a, _b;
             // Remove the component when the element is disconnected. Skip this when the owning
             // application has already been destroyed — removing a <pc-app> disconnects it before
             // its children, taking the component systems with it.
-            if (((_a = this._appElement) === null || _a === void 0 ? void 0 : _a.app) && ((_b = this._component) === null || _b === void 0 ? void 0 : _b.entity)) {
+            if (this._appElement?.app && this._component?.entity) {
                 this._component.entity.removeComponent(this._componentName);
             }
             this._component = null;
             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;
@@ -1830,26 +2150,25 @@
      * @category Components
      */
     class ButtonComponentElement extends ComponentElement {
+        _active = true;
+        _image = '';
+        _hitPadding = new playcanvas.Vec4(0, 0, 0, 0);
+        _transitionMode = 'tint';
+        _hoverTint = new playcanvas.Color(1, 1, 1, 1);
+        _pressedTint = new playcanvas.Color(1, 1, 1, 1);
+        _inactiveTint = new playcanvas.Color(1, 1, 1, 1);
+        _fadeDuration = 0;
+        _hoverSpriteAsset = '';
+        _hoverSpriteFrame = 0;
+        _pressedSpriteAsset = '';
+        _pressedSpriteFrame = 0;
+        _inactiveSpriteAsset = '';
+        _inactiveSpriteFrame = 0;
         /** @ignore */
         constructor() {
             super('button');
-            this._active = true;
-            this._image = '';
-            this._hitPadding = new playcanvas.Vec4(0, 0, 0, 0);
-            this._transitionMode = 'tint';
-            this._hoverTint = new playcanvas.Color(1, 1, 1, 1);
-            this._pressedTint = new playcanvas.Color(1, 1, 1, 1);
-            this._inactiveTint = new playcanvas.Color(1, 1, 1, 1);
-            this._fadeDuration = 0;
-            this._hoverSpriteAsset = '';
-            this._hoverSpriteFrame = 0;
-            this._pressedSpriteAsset = '';
-            this._pressedSpriteFrame = 0;
-            this._inactiveSpriteAsset = '';
-            this._inactiveSpriteFrame = 0;
         }
         getInitialComponentData() {
-            var _a;
             const data = {
                 active: this._active,
                 hitPadding: this._hitPadding,
@@ -1864,7 +2183,7 @@
             };
             // The image entity defaults to the button's own entity (which carries the image element)
             // when no explicit reference is provided.
-            const imageEntity = this._image ? getEntity(this._image) : (_a = this.closestEntity) === null || _a === void 0 ? void 0 : _a.entity;
+            const imageEntity = this._image ? getEntity(this._image) : this.closestEntity?.entity;
             if (imageEntity) {
                 data.imageEntity = imageEntity;
             }
@@ -1948,10 +2267,9 @@
          * @param value - The transition mode.
          */
         set transitionMode(value) {
-            var _a;
             this._transitionMode = value;
             if (this.component) {
-                this.component.transitionMode = (_a = transitionModes.get(value)) !== null && _a !== void 0 ? _a : playcanvas.BUTTON_TRANSITION_MODE_TINT;
+                this.component.transitionMode = transitionModes.get(value) ?? playcanvas.BUTTON_TRANSITION_MODE_TINT;
             }
         }
         /**
@@ -2166,7 +2484,7 @@
                     this.active = parseBool(newValue, true);
                     break;
                 case 'image':
-                    this.image = newValue;
+                    this.image = newValue ?? '';
                     break;
                 case 'hit-padding':
                     this.hitPadding = parseVec4(newValue, playcanvas.Vec4.ZERO, name);
@@ -2187,19 +2505,19 @@
                     this.fadeDuration = parseNumber(newValue, 0, name);
                     break;
                 case 'hover-sprite-asset':
-                    this.hoverSpriteAsset = newValue;
+                    this.hoverSpriteAsset = newValue ?? '';
                     break;
                 case 'hover-sprite-frame':
                     this.hoverSpriteFrame = parseNumber(newValue, 0, name);
                     break;
                 case 'pressed-sprite-asset':
-                    this.pressedSpriteAsset = newValue;
+                    this.pressedSpriteAsset = newValue ?? '';
                     break;
                 case 'pressed-sprite-frame':
                     this.pressedSpriteFrame = parseNumber(newValue, 0, name);
                     break;
                 case 'inactive-sprite-asset':
-                    this.inactiveSpriteAsset = newValue;
+                    this.inactiveSpriteAsset = newValue ?? '';
                     break;
                 case 'inactive-sprite-frame':
                     this.inactiveSpriteFrame = parseNumber(newValue, 0, name);
@@ -2227,27 +2545,27 @@
      * @category Components
      */
     class CameraComponentElement extends ComponentElement {
+        _clearColor = new playcanvas.Color(0.75, 0.75, 0.75, 1);
+        _clearColorBuffer = true;
+        _clearDepthBuffer = true;
+        _clearStencilBuffer = false;
+        _cullFaces = true;
+        _farClip = 1000;
+        _flipFaces = false;
+        _fov = 45;
+        _frustumCulling = true;
+        _gamma = 'srgb';
+        _horizontalFov = false;
+        _nearClip = 0.1;
+        _orthographic = false;
+        _orthoHeight = 10;
+        _priority = 0;
+        _rect = new playcanvas.Vec4(0, 0, 1, 1);
+        _scissorRect = new playcanvas.Vec4(0, 0, 1, 1);
+        _tonemap = 'none';
         /** @ignore */
         constructor() {
             super('camera');
-            this._clearColor = new playcanvas.Color(0.75, 0.75, 0.75, 1);
-            this._clearColorBuffer = true;
-            this._clearDepthBuffer = true;
-            this._clearStencilBuffer = false;
-            this._cullFaces = true;
-            this._farClip = 1000;
-            this._flipFaces = false;
-            this._fov = 45;
-            this._frustumCulling = true;
-            this._gamma = 'srgb';
-            this._horizontalFov = false;
-            this._nearClip = 0.1;
-            this._orthographic = false;
-            this._orthoHeight = 10;
-            this._priority = 0;
-            this._rect = new playcanvas.Vec4(0, 0, 1, 1);
-            this._scissorRect = new playcanvas.Vec4(0, 0, 1, 1);
-            this._tonemap = 'none';
         }
         getInitialComponentData() {
             return {
@@ -2272,8 +2590,7 @@
             };
         }
         get xrAvailable() {
-            var _a;
-            const xrManager = (_a = this.component) === null || _a === void 0 ? void 0 : _a.system.app.xr;
+            const xrManager = this.component?.system.app.xr;
             return xrManager && xrManager.supported && xrManager.isAvailable(playcanvas.XRTYPE_VR);
         }
         /**
@@ -2601,10 +2918,9 @@
          * @param value - The tone mapping.
          */
         set tonemap(value) {
-            var _a;
             this._tonemap = value;
             if (this.component) {
-                this.component.toneMapping = (_a = tonemaps.get(value)) !== null && _a !== void 0 ? _a : playcanvas.TONEMAP_NONE;
+                this.component.toneMapping = tonemaps.get(value) ?? playcanvas.TONEMAP_NONE;
             }
         }
         /**
@@ -2708,17 +3024,17 @@
      * @category Components
      */
     class CollisionComponentElement extends ComponentElement {
+        _angularOffset = new playcanvas.Quat();
+        _axis = 1;
+        _convexHull = false;
+        _halfExtents = new playcanvas.Vec3(0.5, 0.5, 0.5);
+        _height = 2;
+        _linearOffset = new playcanvas.Vec3();
+        _radius = 0.5;
+        _type = 'box';
         /** @ignore */
         constructor() {
             super('collision');
-            this._angularOffset = new playcanvas.Quat();
-            this._axis = 1;
-            this._convexHull = false;
-            this._halfExtents = new playcanvas.Vec3(0.5, 0.5, 0.5);
-            this._height = 2;
-            this._linearOffset = new playcanvas.Vec3();
-            this._radius = 0.5;
-            this._type = 'box';
         }
         getInitialComponentData() {
             return {
@@ -2855,52 +3171,51 @@
      * @category Components
      */
     class ElementComponentElement extends ComponentElement {
+        _anchor = new playcanvas.Vec4(0.5, 0.5, 0.5, 0.5);
+        _autoWidth = true;
+        _autoHeight = true;
+        _autoFitWidth = false;
+        _autoFitHeight = false;
+        _color = new playcanvas.Color(1, 1, 1, 1);
+        _enableMarkup = false;
+        _fontAsset = '';
+        _fontSize = 32;
+        _maxFontSize = 32;
+        _minFontSize = 8;
+        _height = 0;
+        _lineHeight = 32;
+        _margin = null;
+        _mask = false;
+        _opacity = 1;
+        _pivot = new playcanvas.Vec2(0.5, 0.5);
+        _pixelsPerUnit = null;
+        _spriteAsset = '';
+        _spriteFrame = 0;
+        _text = '';
+        _textureAsset = '';
+        _type = 'group';
+        _useInput = false;
+        _width = 0;
+        _wrapLines = false;
         /** @ignore */
         constructor() {
             super('element');
-            this._anchor = new playcanvas.Vec4(0.5, 0.5, 0.5, 0.5);
-            this._autoWidth = true;
-            this._autoHeight = true;
-            this._autoFitWidth = false;
-            this._autoFitHeight = false;
-            this._color = new playcanvas.Color(1, 1, 1, 1);
-            this._enableMarkup = false;
-            this._fontAsset = '';
-            this._fontSize = 32;
-            this._maxFontSize = 32;
-            this._minFontSize = 8;
-            this._height = 0;
-            this._lineHeight = 32;
-            this._margin = null;
-            this._mask = false;
-            this._opacity = 1;
-            this._pivot = new playcanvas.Vec2(0.5, 0.5);
-            this._pixelsPerUnit = null;
-            this._spriteAsset = '';
-            this._spriteFrame = 0;
-            this._text = '';
-            this._textureAsset = '';
-            this._type = 'group';
-            this._useInput = false;
-            this._width = 0;
-            this._wrapLines = false;
         }
         initComponent() {
-            var _a, _b;
             const component = this.component;
             if (!component) {
                 return;
             }
             // Text elements render through their own material; enable fog on it so 3D text respects
             // scene fog. Image/group elements have no text material, so guard the access.
-            if ((_a = component._text) === null || _a === void 0 ? void 0 : _a._material) {
+            if (component._text?._material) {
                 component._text._material.useFog = true;
             }
             // The engine establishes element masking in ElementComponent._onInsert, which fires when an
             // entity is inserted into the hierarchy. Web-components inserts the entity first and adds
             // the element component afterwards, so that pass is missed. Re-dirty the mask state here so
             // masks (e.g. a scroll view viewport) correctly clip this element and any added at runtime.
-            (_b = component._dirtifyMask) === null || _b === void 0 ? void 0 : _b.call(component);
+            component._dirtifyMask?.();
         }
         getInitialComponentData() {
             const data = {
@@ -3463,7 +3778,7 @@
                     this.enableMarkup = parseBool(newValue, false);
                     break;
                 case 'font-asset':
-                    this.fontAsset = newValue;
+                    this.fontAsset = newValue ?? '';
                     break;
                 case 'font-size':
                     this.fontSize = parseNumber(newValue, 32, name);
@@ -3496,16 +3811,16 @@
                     this.pixelsPerUnit = parseNumber(newValue, null, name);
                     break;
                 case 'sprite-asset':
-                    this.spriteAsset = newValue;
+                    this.spriteAsset = newValue ?? '';
                     break;
                 case 'sprite-frame':
                     this.spriteFrame = parseNumber(newValue, 0, name);
                     break;
                 case 'text':
-                    this.text = newValue;
+                    this.text = newValue ?? '';
                     break;
                 case 'texture-asset':
-                    this.textureAsset = newValue;
+                    this.textureAsset = newValue ?? '';
                     break;
                 case 'type':
                     this.type = parseEnum(newValue, ['group', 'image', 'text'], 'group', name);
@@ -3533,16 +3848,16 @@
      * @category Components
      */
     class LayoutChildComponentElement extends ComponentElement {
+        _minWidth = 0;
+        _minHeight = 0;
+        _maxWidth = null;
+        _maxHeight = null;
+        _fitWidthProportion = 0;
+        _fitHeightProportion = 0;
+        _excludeFromLayout = false;
         /** @ignore */
         constructor() {
             super('layoutchild');
-            this._minWidth = 0;
-            this._minHeight = 0;
-            this._maxWidth = null;
-            this._maxHeight = null;
-            this._fitWidthProportion = 0;
-            this._fitHeightProportion = 0;
-            this._excludeFromLayout = false;
         }
         getInitialComponentData() {
             return {
@@ -3743,18 +4058,18 @@
      * @category Components
      */
     class LayoutGroupComponentElement extends ComponentElement {
+        _orientation = 'horizontal';
+        _reverseX = false;
+        _reverseY = false;
+        _alignment = new playcanvas.Vec2(0, 1);
+        _padding = new playcanvas.Vec4(0, 0, 0, 0);
+        _spacing = new playcanvas.Vec2(0, 0);
+        _widthFitting = 'none';
+        _heightFitting = 'none';
+        _wrap = false;
         /** @ignore */
         constructor() {
             super('layoutgroup');
-            this._orientation = 'horizontal';
-            this._reverseX = false;
-            this._reverseY = false;
-            this._alignment = new playcanvas.Vec2(0, 1);
-            this._padding = new playcanvas.Vec4(0, 0, 0, 0);
-            this._spacing = new playcanvas.Vec2(0, 0);
-            this._widthFitting = 'none';
-            this._heightFitting = 'none';
-            this._wrap = false;
         }
         getInitialComponentData() {
             return {
@@ -3782,10 +4097,9 @@
          * @param value - The orientation.
          */
         set orientation(value) {
-            var _a;
             this._orientation = value;
             if (this.component) {
-                this.component.orientation = (_a = orientations$1.get(value)) !== null && _a !== void 0 ? _a : playcanvas.ORIENTATION_HORIZONTAL;
+                this.component.orientation = orientations$1.get(value) ?? playcanvas.ORIENTATION_HORIZONTAL;
             }
         }
         /**
@@ -3886,10 +4200,9 @@
          * @param value - The width fitting mode.
          */
         set widthFitting(value) {
-            var _a;
             this._widthFitting = value;
             if (this.component) {
-                this.component.widthFitting = (_a = fittings.get(value)) !== null && _a !== void 0 ? _a : playcanvas.FITTING_NONE;
+                this.component.widthFitting = fittings.get(value) ?? playcanvas.FITTING_NONE;
             }
         }
         /**
@@ -3905,10 +4218,9 @@
          * @param value - The height fitting mode.
          */
         set heightFitting(value) {
-            var _a;
             this._heightFitting = value;
             if (this.component) {
-                this.component.heightFitting = (_a = fittings.get(value)) !== null && _a !== void 0 ? _a : playcanvas.FITTING_NONE;
+                this.component.heightFitting = fittings.get(value) ?? playcanvas.FITTING_NONE;
             }
         }
         /**
@@ -4004,28 +4316,28 @@
      * @category Components
      */
     class LightComponentElement extends ComponentElement {
+        _castShadows = false;
+        _color = new playcanvas.Color(1, 1, 1);
+        _innerConeAngle = 40;
+        _intensity = 1;
+        _normalOffsetBias = 0.05;
+        _outerConeAngle = 45;
+        _range = 10;
+        _shadowBias = 0.2;
+        _shadowDistance = 16;
+        _shadowIntensity = 1;
+        _shadowResolution = 1024;
+        _shadowType = 'pcf3-32f';
+        _type = 'directional';
+        _vsmBias = 0.01;
+        _vsmBlurSize = 11;
+        _penumbraSize = 1;
+        _penumbraFalloff = 1;
+        _shadowSamples = 16;
+        _shadowBlockerSamples = 16;
         /** @ignore */
         constructor() {
             super('light');
-            this._castShadows = false;
-            this._color = new playcanvas.Color(1, 1, 1);
-            this._innerConeAngle = 40;
-            this._intensity = 1;
-            this._normalOffsetBias = 0.05;
-            this._outerConeAngle = 45;
-            this._range = 10;
-            this._shadowBias = 0.2;
-            this._shadowDistance = 16;
-            this._shadowIntensity = 1;
-            this._shadowResolution = 1024;
-            this._shadowType = 'pcf3-32f';
-            this._type = 'directional';
-            this._vsmBias = 0.01;
-            this._vsmBlurSize = 11;
-            this._penumbraSize = 1;
-            this._penumbraFalloff = 1;
-            this._shadowSamples = 16;
-            this._shadowBlockerSamples = 16;
         }
         getInitialComponentData() {
             return {
@@ -4259,10 +4571,9 @@
          * - `pcss-32f` - Percentage-closer soft shadow with 32-bit depth.
          */
         set shadowType(value) {
-            var _a;
             this._shadowType = value;
             if (this.component) {
-                this.component.shadowType = (_a = shadowTypes.get(value)) !== null && _a !== void 0 ? _a : playcanvas.SHADOW_PCF3_32F;
+                this.component.shadowType = shadowTypes.get(value) ?? playcanvas.SHADOW_PCF3_32F;
             }
         }
         /**
@@ -4490,20 +4801,19 @@
      * @category Components
      */
     class ParticleSystemComponentElement extends ComponentElement {
+        _asset = '';
         /** @ignore */
         constructor() {
             super('particlesystem');
-            this._asset = '';
         }
         getInitialComponentData() {
-            var _a;
             const asset = AssetElement.get(this._asset);
             if (!asset) {
                 return {};
             }
             if (asset.resource.colorMapAsset) {
                 const id = asset.resource.colorMapAsset;
-                const colorMapAsset = (_a = AssetElement.get(id)) === null || _a === void 0 ? void 0 : _a.id;
+                const colorMapAsset = AssetElement.get(id)?.id;
                 if (colorMapAsset) {
                     asset.resource.colorMapAsset = colorMapAsset;
                 }
@@ -4529,9 +4839,8 @@
             }
         }
         async _loadAsset() {
-            var _a;
-            const appElement = await ((_a = this.closestApp) === null || _a === void 0 ? void 0 : _a.ready());
-            const app = appElement === null || appElement === void 0 ? void 0 : appElement.app;
+            const appElement = await this.closestApp?.ready();
+            const app = appElement?.app;
             const asset = AssetElement.get(this._asset);
             if (!asset) {
                 return;
@@ -4606,148 +4915,2183 @@
             super.attributeChangedCallback(name, _oldValue, newValue);
             switch (name) {
                 case 'asset':
-                    this.asset = newValue;
+                    this.asset = newValue ?? '';
                     break;
             }
         }
     }
     customElements.define('pc-particles', ParticleSystemComponentElement);
 
-    /**
-     * The MaterialElement interface provides properties and methods for manipulating
-     * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-material/ | `<pc-material>`} elements.
+    const blendTypes = new Map([
+        ['none', playcanvas.BLEND_NONE],
+        ['normal', playcanvas.BLEND_NORMAL],
+        ['additive', playcanvas.BLEND_ADDITIVE],
+        ['additive-alpha', playcanvas.BLEND_ADDITIVEALPHA],
+        ['premultiplied', playcanvas.BLEND_PREMULTIPLIED],
+        ['multiplicative', playcanvas.BLEND_MULTIPLICATIVE],
+        ['multiplicative-2x', playcanvas.BLEND_MULTIPLICATIVE2X],
+        ['screen', playcanvas.BLEND_SCREEN],
+        ['min', playcanvas.BLEND_MIN],
+        ['max', playcanvas.BLEND_MAX],
+        ['subtractive', playcanvas.BLEND_SUBTRACTIVE]
+    ]);
+    const cullModes = new Map([
+        ['none', playcanvas.CULLFACE_NONE],
+        ['back', playcanvas.CULLFACE_BACK],
+        ['front', playcanvas.CULLFACE_FRONT],
+        ['front-and-back', playcanvas.CULLFACE_FRONTANDBACK]
+    ]);
+    const fresnelModels = new Map([
+        ['none', playcanvas.FRESNEL_NONE],
+        ['schlick', playcanvas.FRESNEL_SCHLICK]
+    ]);
+    const occludeSpeculars = new Map([
+        ['none', playcanvas.SPECOCC_NONE],
+        ['ao', playcanvas.SPECOCC_AO],
+        ['gloss-dependent', playcanvas.SPECOCC_GLOSSDEPENDENT]
+    ]);
+    const opacityDithers = ['none', 'bayer8', 'bluenoise', 'ignnoise'];
+    const colorChannels = ['r', 'g', 'b', 'a', 'rgb'];
+    const scalarChannels = ['r', 'g', 'b', 'a'];
+    /**
+     * The attributes that contradict a `roughness-*` attribute: each one carries the opposite
+     * interpretation of a value the aliases also write. The `gloss-map-*` modifiers are deliberately
+     * absent - they only configure the shared slot (tiling, offset, channel and so on) and carry no
+     * interpretation of their own, so they are the supported way to configure a `roughness-map`.
+     */
+    const glossConflicts = ['gloss', 'gloss-invert', 'gloss-map'];
+    /** The aliases those attributes contradict. */
+    const roughnessAliases = ['roughness', 'roughness-map'];
+    /**
+     * The MaterialElement interface provides properties and methods for manipulating
+     * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-material/ | `<pc-material>`} elements.
      * The MaterialElement interface also inherits the properties and methods of the
      * {@link HTMLElement} interface.
      *
      * A `pc-material` must be a direct child of `pc-app` — elements placed elsewhere log a warning
      * and never create a material. Elements inserted while the application is already running are
      * 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. 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
+     * `gloss` properties and would otherwise inherit gloss's description - which reads inverted.
+     *
+     * @attribute {number} roughness - The roughness of the material, from 0 (shiny) to 1 (rough). An
+     * alias for `gloss` that also inverts it, so do not combine it with the `gloss` attributes.
+     * @attribute {string} roughness-map - The id of the `pc-asset` to use as the roughness map. An
+     * alias for `gloss-map` that also inverts the gloss channel, so do not combine it with the `gloss`
+     * attributes.
      */
     class MaterialElement extends HTMLElement {
-        constructor() {
-            super(...arguments);
-            this._diffuse = new playcanvas.Color(1, 1, 1);
-            this._diffuseMap = '';
-            this._metalnessMap = '';
-            this._normalMap = '';
-            this._roughnessMap = '';
-            this.material = null;
-        }
+        _alphaTest = 0;
+        _alphaToCoverage = false;
+        _aoIntensity = 1;
+        _aoMap = '';
+        _aoMapChannel = 'g';
+        _aoMapOffset = new playcanvas.Vec2(0, 0);
+        _aoMapRotation = 0;
+        _aoMapTiling = new playcanvas.Vec2(1, 1);
+        _aoMapUv = 0;
+        _blendType = 'none';
+        _bumpiness = 1;
+        _cull = 'back';
+        _depthBias = 0;
+        _depthTest = true;
+        _depthWrite = true;
+        _diffuse = new playcanvas.Color(1, 1, 1);
+        _diffuseMap = '';
+        _diffuseMapChannel = 'rgb';
+        _diffuseMapOffset = new playcanvas.Vec2(0, 0);
+        _diffuseMapRotation = 0;
+        _diffuseMapTiling = new playcanvas.Vec2(1, 1);
+        _diffuseMapUv = 0;
+        _emissive = new playcanvas.Color(0, 0, 0);
+        _emissiveIntensity = 1;
+        _emissiveMap = '';
+        _emissiveMapChannel = 'rgb';
+        _emissiveMapOffset = new playcanvas.Vec2(0, 0);
+        _emissiveMapRotation = 0;
+        _emissiveMapTiling = new playcanvas.Vec2(1, 1);
+        _emissiveMapUv = 0;
+        _enableGGXSpecular = false;
+        _fresnelModel = 'schlick';
+        _gloss = 0.25;
+        _glossInvert = false;
+        _glossMap = '';
+        _glossMapChannel = 'g';
+        _glossMapOffset = new playcanvas.Vec2(0, 0);
+        _glossMapRotation = 0;
+        _glossMapTiling = new playcanvas.Vec2(1, 1);
+        _glossMapUv = 0;
+        _heightMap = '';
+        _heightMapChannel = 'g';
+        _heightMapFactor = 1;
+        _heightMapOffset = new playcanvas.Vec2(0, 0);
+        _heightMapRotation = 0;
+        _heightMapTiling = new playcanvas.Vec2(1, 1);
+        _heightMapUv = 0;
+        _metalness = 0;
+        _metalnessMap = '';
+        _metalnessMapChannel = 'g';
+        _metalnessMapOffset = new playcanvas.Vec2(0, 0);
+        _metalnessMapRotation = 0;
+        _metalnessMapTiling = new playcanvas.Vec2(1, 1);
+        _metalnessMapUv = 0;
+        _normalMap = '';
+        _normalMapOffset = new playcanvas.Vec2(0, 0);
+        _normalMapRotation = 0;
+        _normalMapTiling = new playcanvas.Vec2(1, 1);
+        _normalMapUv = 0;
+        _occludeDirect = false;
+        _occludeSpecular = 'ao';
+        _opacity = 1;
+        _opacityDither = 'none';
+        _opacityFadesSpecular = true;
+        _opacityMap = '';
+        _opacityMapChannel = 'a';
+        _opacityMapOffset = new playcanvas.Vec2(0, 0);
+        _opacityMapRotation = 0;
+        _opacityMapTiling = new playcanvas.Vec2(1, 1);
+        _opacityMapUv = 0;
+        _slopeDepthBias = 0;
+        _specular = new playcanvas.Color(0, 0, 0);
+        _specularityFactor = 1;
+        _twoSidedLighting = false;
+        _useFog = true;
+        _useLighting = true;
+        // Diverges from the engine default of false - see the class docblock and createMaterial()
+        _useMetalness = true;
+        _useMetalnessSpecularColor = false;
+        _useSkybox = true;
+        _useTonemap = true;
+        /**
+         * Pending `load` handlers, one per texture slot. A slot's handler is torn down when the slot is
+         * reassigned or the element disconnects, so a late-arriving asset can never write a texture the
+         * element no longer wants.
+         */
+        _mapHandles = new Map();
+        _updateScheduled = false;
+        _glossConflictWarned = false;
+        material = null;
         async connectedCallback() {
-            var _a, _b;
-            const appElement = (_b = (_a = this.parentElement) === null || _a === void 0 ? void 0 : _a.closest('pc-app')) !== null && _b !== void 0 ? _b : null;
+            const appElement = this.parentElement?.closest('pc-app') ?? null;
             // Materials must be direct children of pc-app (matches the boot query ':scope > pc-material')
             if (!appElement || this.parentElement !== appElement) {
                 console.warn(`pc-material '${this.id}' must be a direct child of pc-app - material not created`);
                 return;
             }
-            await appElement.ready();
-            // The element may have been removed or re-parented while waiting for the app
-            if (!this.isConnected || this.parentElement !== appElement)
-                return;
-            // Materials present at startup are created by AppElement's boot; this branch handles
-            // elements inserted (or re-inserted) after the app is already running
-            if (!this.material) {
-                if (!appElement.app)
-                    return; // pc-app is re-connecting; its own boot will create this
-                this.createMaterial();
+            await appElement.ready();
+            // The element may have been removed or re-parented while waiting for the app
+            if (!this.isConnected || this.parentElement !== appElement)
+                return;
+            // Materials present at startup are created by AppElement's boot; this branch handles
+            // elements inserted (or re-inserted) after the app is already running
+            if (!this.material) {
+                if (!appElement.app)
+                    return; // pc-app is re-connecting; its own boot will create this
+                this.createMaterial();
+            }
+        }
+        createMaterial() {
+            const material = new playcanvas.StandardMaterial();
+            this.material = material;
+            material.alphaTest = this._alphaTest;
+            material.alphaToCoverage = this._alphaToCoverage;
+            material.aoIntensity = this._aoIntensity;
+            material.aoMapChannel = this._aoMapChannel;
+            material.aoMapOffset = this._aoMapOffset;
+            material.aoMapRotation = this._aoMapRotation;
+            material.aoMapTiling = this._aoMapTiling;
+            material.aoMapUv = this._aoMapUv;
+            material.blendType = blendTypes.get(this._blendType) ?? playcanvas.BLEND_NONE;
+            material.bumpiness = this._bumpiness;
+            material.cull = cullModes.get(this._cull) ?? playcanvas.CULLFACE_BACK;
+            material.depthBias = this._depthBias;
+            material.depthTest = this._depthTest;
+            material.depthWrite = this._depthWrite;
+            material.diffuse = this._diffuse;
+            material.diffuseMapChannel = this._diffuseMapChannel;
+            material.diffuseMapOffset = this._diffuseMapOffset;
+            material.diffuseMapRotation = this._diffuseMapRotation;
+            material.diffuseMapTiling = this._diffuseMapTiling;
+            material.diffuseMapUv = this._diffuseMapUv;
+            material.emissive = this._emissive;
+            material.emissiveIntensity = this._emissiveIntensity;
+            material.emissiveMapChannel = this._emissiveMapChannel;
+            material.emissiveMapOffset = this._emissiveMapOffset;
+            material.emissiveMapRotation = this._emissiveMapRotation;
+            material.emissiveMapTiling = this._emissiveMapTiling;
+            material.emissiveMapUv = this._emissiveMapUv;
+            material.enableGGXSpecular = this._enableGGXSpecular;
+            material.fresnelModel = fresnelModels.get(this._fresnelModel) ?? playcanvas.FRESNEL_SCHLICK;
+            material.gloss = this._gloss;
+            material.glossInvert = this._glossInvert;
+            material.glossMapChannel = this._glossMapChannel;
+            material.glossMapOffset = this._glossMapOffset;
+            material.glossMapRotation = this._glossMapRotation;
+            material.glossMapTiling = this._glossMapTiling;
+            material.glossMapUv = this._glossMapUv;
+            material.heightMapChannel = this._heightMapChannel;
+            material.heightMapFactor = this._heightMapFactor;
+            material.heightMapOffset = this._heightMapOffset;
+            material.heightMapRotation = this._heightMapRotation;
+            material.heightMapTiling = this._heightMapTiling;
+            material.heightMapUv = this._heightMapUv;
+            material.metalness = this._metalness;
+            material.metalnessMapChannel = this._metalnessMapChannel;
+            material.metalnessMapOffset = this._metalnessMapOffset;
+            material.metalnessMapRotation = this._metalnessMapRotation;
+            material.metalnessMapTiling = this._metalnessMapTiling;
+            material.metalnessMapUv = this._metalnessMapUv;
+            material.normalMapOffset = this._normalMapOffset;
+            material.normalMapRotation = this._normalMapRotation;
+            material.normalMapTiling = this._normalMapTiling;
+            material.normalMapUv = this._normalMapUv;
+            // @ts-ignore the engine's generated .d.ts types occludeDirect as a number, but its own
+            // JSDoc documents it as a boolean and its runtime default is `false`
+            material.occludeDirect = this._occludeDirect;
+            material.occludeSpecular = occludeSpeculars.get(this._occludeSpecular) ?? playcanvas.SPECOCC_AO;
+            material.opacity = this._opacity;
+            material.opacityDither = this._opacityDither;
+            material.opacityFadesSpecular = this._opacityFadesSpecular;
+            material.opacityMapChannel = this._opacityMapChannel;
+            material.opacityMapOffset = this._opacityMapOffset;
+            material.opacityMapRotation = this._opacityMapRotation;
+            material.opacityMapTiling = this._opacityMapTiling;
+            material.opacityMapUv = this._opacityMapUv;
+            material.slopeDepthBias = this._slopeDepthBias;
+            material.specular = this._specular;
+            material.specularityFactor = this._specularityFactor;
+            material.twoSidedLighting = this._twoSidedLighting;
+            material.useFog = this._useFog;
+            material.useLighting = this._useLighting;
+            // The engine defaults to the older specular/gloss workflow, in which metalnessMap is never
+            // sampled at all - useMetalness drives the LIT_METALNESS define. This element defaults the
+            // other way, so that `metalness-map` does what its name says.
+            material.useMetalness = this._useMetalness;
+            material.useMetalnessSpecularColor = this._useMetalnessSpecularColor;
+            material.useSkybox = this._useSkybox;
+            material.useTonemap = this._useTonemap;
+            // Texture slots resolve a pc-asset id, which may not have loaded yet
+            this.aoMap = this._aoMap;
+            this.diffuseMap = this._diffuseMap;
+            this.emissiveMap = this._emissiveMap;
+            this.glossMap = this._glossMap;
+            this.heightMap = this._heightMap;
+            this.metalnessMap = this._metalnessMap;
+            this.normalMap = this._normalMap;
+            this.opacityMap = this._opacityMap;
+            material.update();
+        }
+        disconnectedCallback() {
+            for (const handle of this._mapHandles.values()) {
+                handle.off();
+            }
+            this._mapHandles.clear();
+            if (this.material) {
+                this.material.destroy();
+                this.material = null;
+            }
+        }
+        /**
+         * Coalesces `material.update()` across a burst of attribute or property writes, so that setting
+         * a dozen attributes in one parse costs one update rather than a dozen.
+         */
+        _scheduleUpdate() {
+            if (this._updateScheduled)
+                return;
+            this._updateScheduled = true;
+            queueMicrotask(() => {
+                this._updateScheduled = false;
+                this.material?.update();
+            });
+        }
+        /**
+         * Warns when a `roughness-*` attribute is combined with one that carries the opposite
+         * interpretation of the same value. They write the same engine properties but disagree about
+         * whether the channel is inverted, so the result would depend on attribute order rather than
+         * on intent.
+         *
+         * Called from both families rather than only from the roughness branches, because the two
+         * orderings are equally wrong and only one of them would otherwise be caught. The conflict is
+         * a property of the element rather than of any one write - and an upgrading element already
+         * has all of its attributes, so every branch would otherwise report the same clash - so the
+         * warning latches and reports once per episode, clearing when the clash is resolved.
+         */
+        _warnGlossConflict() {
+            const quote = (names) => `'${names.join('\', \'')}'`;
+            const roughness = roughnessAliases.filter(name => this.hasAttribute(name));
+            const gloss = glossConflicts.filter(name => this.hasAttribute(name));
+            if (roughness.length === 0 || gloss.length === 0) {
+                this._glossConflictWarned = false;
+                return;
+            }
+            if (this._glossConflictWarned)
+                return;
+            this._glossConflictWarned = true;
+            console.warn(`pc-material '${this.id}' sets both ${quote(roughness)} and ${quote(gloss)} - ` +
+                'the roughness-* attributes invert gloss, so the two families contradict each other. Use one or the other.');
+        }
+        /**
+         * Points a texture slot at the resource of a `pc-asset`, waiting for the asset to load when it
+         * has not already. An empty id clears the slot.
+         *
+         * @param id - The id of the `pc-asset`, or an empty string to clear the slot.
+         * @param slot - The material property to write.
+         */
+        setMap(id, slot) {
+            // Drop any load still pending for this slot - its texture is no longer the one we want
+            this._mapHandles.get(slot)?.off();
+            this._mapHandles.delete(slot);
+            if (!this.material)
+                return;
+            if (!id) {
+                this.material[slot] = null;
+                this._scheduleUpdate();
+                return;
+            }
+            const asset = AssetElement.get(id);
+            if (!asset)
+                return;
+            if (asset.loaded) {
+                this._applyMap(slot, asset.resource);
+                return;
+            }
+            this._mapHandles.set(slot, asset.once('load', () => {
+                this._mapHandles.delete(slot);
+                this._applyMap(slot, asset.resource);
+            }));
+        }
+        /**
+         * @param slot - The material property to write.
+         * @param texture - The loaded texture.
+         */
+        _applyMap(slot, texture) {
+            if (!this.material)
+                return;
+            this.material[slot] = texture;
+            texture.anisotropy = 4;
+            this._scheduleUpdate();
+        }
+        /**
+         * Sets the alpha test reference value. Fragments with an opacity below this value are discarded.
+         * @param value - The alpha test reference value.
+         */
+        set alphaTest(value) {
+            this._alphaTest = value;
+            if (this.material) {
+                this.material.alphaTest = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the alpha test reference value.
+         * @returns The alpha test reference value.
+         */
+        get alphaTest() {
+            return this._alphaTest;
+        }
+        /**
+         * Sets whether to use alpha to coverage, which resolves transparency using multisampling.
+         * @param value - The alpha to coverage flag.
+         */
+        set alphaToCoverage(value) {
+            this._alphaToCoverage = value;
+            if (this.material) {
+                this.material.alphaToCoverage = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets whether to use alpha to coverage.
+         * @returns The alpha to coverage flag.
+         */
+        get alphaToCoverage() {
+            return this._alphaToCoverage;
+        }
+        /**
+         * Sets the strength of the ambient occlusion map, from 0 to 1.
+         * @param value - The ambient occlusion intensity.
+         */
+        set aoIntensity(value) {
+            this._aoIntensity = value;
+            if (this.material) {
+                this.material.aoIntensity = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the strength of the ambient occlusion map.
+         * @returns The ambient occlusion intensity.
+         */
+        get aoIntensity() {
+            return this._aoIntensity;
+        }
+        /**
+         * Sets the id of the `pc-asset` to use as the ambient occlusion map.
+         * @param value - The asset id.
+         */
+        set aoMap(value) {
+            this._aoMap = value;
+            this.setMap(value, 'aoMap');
+        }
+        /**
+         * Gets the id of the `pc-asset` used as the ambient occlusion map.
+         * @returns The asset id.
+         */
+        get aoMap() {
+            return this._aoMap;
+        }
+        /**
+         * Sets the color channel of the ambient occlusion map to sample.
+         * @param value - The channel.
+         */
+        set aoMapChannel(value) {
+            this._aoMapChannel = value;
+            if (this.material) {
+                this.material.aoMapChannel = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the color channel of the ambient occlusion map to sample.
+         * @returns The channel.
+         */
+        get aoMapChannel() {
+            return this._aoMapChannel;
+        }
+        /**
+         * Sets the 2D offset of the ambient occlusion map.
+         * @param value - The offset.
+         */
+        set aoMapOffset(value) {
+            this._aoMapOffset = value;
+            if (this.material) {
+                this.material.aoMapOffset = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the 2D offset of the ambient occlusion map.
+         * @returns The offset.
+         */
+        get aoMapOffset() {
+            return this._aoMapOffset;
+        }
+        /**
+         * Sets the 2D rotation of the ambient occlusion map, in degrees.
+         * @param value - The rotation.
+         */
+        set aoMapRotation(value) {
+            this._aoMapRotation = value;
+            if (this.material) {
+                this.material.aoMapRotation = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the 2D rotation of the ambient occlusion map.
+         * @returns The rotation.
+         */
+        get aoMapRotation() {
+            return this._aoMapRotation;
+        }
+        /**
+         * Sets the 2D tiling of the ambient occlusion map.
+         * @param value - The tiling.
+         */
+        set aoMapTiling(value) {
+            this._aoMapTiling = value;
+            if (this.material) {
+                this.material.aoMapTiling = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the 2D tiling of the ambient occlusion map.
+         * @returns The tiling.
+         */
+        get aoMapTiling() {
+            return this._aoMapTiling;
+        }
+        /**
+         * Sets the UV channel the ambient occlusion map samples.
+         * @param value - The UV channel.
+         */
+        set aoMapUv(value) {
+            this._aoMapUv = value;
+            if (this.material) {
+                this.material.aoMapUv = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the UV channel the ambient occlusion map samples.
+         * @returns The UV channel.
+         */
+        get aoMapUv() {
+            return this._aoMapUv;
+        }
+        /**
+         * Sets how the material is blended with the scene behind it.
+         * @param value - The blend type.
+         */
+        set blendType(value) {
+            this._blendType = value;
+            if (this.material) {
+                this.material.blendType = blendTypes.get(value) ?? playcanvas.BLEND_NONE;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets how the material is blended with the scene behind it.
+         * @returns The blend type.
+         */
+        get blendType() {
+            return this._blendType;
+        }
+        /**
+         * Sets the strength of the normal map, where 0 is flat and 1 is the map's full effect.
+         * @param value - The bumpiness.
+         */
+        set bumpiness(value) {
+            this._bumpiness = value;
+            if (this.material) {
+                this.material.bumpiness = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the strength of the normal map.
+         * @returns The bumpiness.
+         */
+        get bumpiness() {
+            return this._bumpiness;
+        }
+        /**
+         * Sets which faces of a mesh are culled.
+         * @param value - The cull mode.
+         */
+        set cull(value) {
+            this._cull = value;
+            if (this.material) {
+                this.material.cull = cullModes.get(value) ?? playcanvas.CULLFACE_BACK;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets which faces of a mesh are culled.
+         * @returns The cull mode.
+         */
+        get cull() {
+            return this._cull;
+        }
+        /**
+         * Sets the offset applied to the depth of a fragment, used to resolve z-fighting.
+         * @param value - The depth bias.
+         */
+        set depthBias(value) {
+            this._depthBias = value;
+            if (this.material) {
+                this.material.depthBias = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the offset applied to the depth of a fragment.
+         * @returns The depth bias.
+         */
+        get depthBias() {
+            return this._depthBias;
+        }
+        /**
+         * Sets whether fragments are tested against the depth buffer.
+         * @param value - The depth test flag.
+         */
+        set depthTest(value) {
+            this._depthTest = value;
+            if (this.material) {
+                this.material.depthTest = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets whether fragments are tested against the depth buffer.
+         * @returns The depth test flag.
+         */
+        get depthTest() {
+            return this._depthTest;
+        }
+        /**
+         * Sets whether fragments write to the depth buffer.
+         * @param value - The depth write flag.
+         */
+        set depthWrite(value) {
+            this._depthWrite = value;
+            if (this.material) {
+                this.material.depthWrite = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets whether fragments write to the depth buffer.
+         * @returns The depth write flag.
+         */
+        get depthWrite() {
+            return this._depthWrite;
+        }
+        /**
+         * Sets the diffuse color of the material. With the metalness workflow this doubles as the
+         * specular color where the surface is metallic.
+         * @param value - The diffuse color.
+         */
+        set diffuse(value) {
+            this._diffuse = value;
+            if (this.material) {
+                this.material.diffuse = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the diffuse color of the material.
+         * @returns The diffuse color.
+         */
+        get diffuse() {
+            return this._diffuse;
+        }
+        /**
+         * Sets the id of the `pc-asset` to use as the diffuse map.
+         * @param value - The asset id.
+         */
+        set diffuseMap(value) {
+            this._diffuseMap = value;
+            this.setMap(value, 'diffuseMap');
+        }
+        /**
+         * Gets the id of the `pc-asset` used as the diffuse map.
+         * @returns The asset id.
+         */
+        get diffuseMap() {
+            return this._diffuseMap;
+        }
+        /**
+         * Sets the color channels of the diffuse map to sample.
+         * @param value - The channels.
+         */
+        set diffuseMapChannel(value) {
+            this._diffuseMapChannel = value;
+            if (this.material) {
+                this.material.diffuseMapChannel = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the color channels of the diffuse map to sample.
+         * @returns The channels.
+         */
+        get diffuseMapChannel() {
+            return this._diffuseMapChannel;
+        }
+        /**
+         * Sets the 2D offset of the diffuse map.
+         * @param value - The offset.
+         */
+        set diffuseMapOffset(value) {
+            this._diffuseMapOffset = value;
+            if (this.material) {
+                this.material.diffuseMapOffset = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the 2D offset of the diffuse map.
+         * @returns The offset.
+         */
+        get diffuseMapOffset() {
+            return this._diffuseMapOffset;
+        }
+        /**
+         * Sets the 2D rotation of the diffuse map, in degrees.
+         * @param value - The rotation.
+         */
+        set diffuseMapRotation(value) {
+            this._diffuseMapRotation = value;
+            if (this.material) {
+                this.material.diffuseMapRotation = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the 2D rotation of the diffuse map.
+         * @returns The rotation.
+         */
+        get diffuseMapRotation() {
+            return this._diffuseMapRotation;
+        }
+        /**
+         * Sets the 2D tiling of the diffuse map.
+         * @param value - The tiling.
+         */
+        set diffuseMapTiling(value) {
+            this._diffuseMapTiling = value;
+            if (this.material) {
+                this.material.diffuseMapTiling = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the 2D tiling of the diffuse map.
+         * @returns The tiling.
+         */
+        get diffuseMapTiling() {
+            return this._diffuseMapTiling;
+        }
+        /**
+         * Sets the UV channel the diffuse map samples.
+         * @param value - The UV channel.
+         */
+        set diffuseMapUv(value) {
+            this._diffuseMapUv = value;
+            if (this.material) {
+                this.material.diffuseMapUv = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the UV channel the diffuse map samples.
+         * @returns The UV channel.
+         */
+        get diffuseMapUv() {
+            return this._diffuseMapUv;
+        }
+        /**
+         * Sets the emissive color of the material, which is added to the lit result.
+         * @param value - The emissive color.
+         */
+        set emissive(value) {
+            this._emissive = value;
+            if (this.material) {
+                this.material.emissive = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the emissive color of the material.
+         * @returns The emissive color.
+         */
+        get emissive() {
+            return this._emissive;
+        }
+        /**
+         * Sets the multiplier applied to the emissive color and map.
+         * @param value - The emissive intensity.
+         */
+        set emissiveIntensity(value) {
+            this._emissiveIntensity = value;
+            if (this.material) {
+                this.material.emissiveIntensity = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the multiplier applied to the emissive color and map.
+         * @returns The emissive intensity.
+         */
+        get emissiveIntensity() {
+            return this._emissiveIntensity;
+        }
+        /**
+         * Sets the id of the `pc-asset` to use as the emissive map.
+         * @param value - The asset id.
+         */
+        set emissiveMap(value) {
+            this._emissiveMap = value;
+            this.setMap(value, 'emissiveMap');
+        }
+        /**
+         * Gets the id of the `pc-asset` used as the emissive map.
+         * @returns The asset id.
+         */
+        get emissiveMap() {
+            return this._emissiveMap;
+        }
+        /**
+         * Sets the color channels of the emissive map to sample.
+         * @param value - The channels.
+         */
+        set emissiveMapChannel(value) {
+            this._emissiveMapChannel = value;
+            if (this.material) {
+                this.material.emissiveMapChannel = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the color channels of the emissive map to sample.
+         * @returns The channels.
+         */
+        get emissiveMapChannel() {
+            return this._emissiveMapChannel;
+        }
+        /**
+         * Sets the 2D offset of the emissive map.
+         * @param value - The offset.
+         */
+        set emissiveMapOffset(value) {
+            this._emissiveMapOffset = value;
+            if (this.material) {
+                this.material.emissiveMapOffset = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the 2D offset of the emissive map.
+         * @returns The offset.
+         */
+        get emissiveMapOffset() {
+            return this._emissiveMapOffset;
+        }
+        /**
+         * Sets the 2D rotation of the emissive map, in degrees.
+         * @param value - The rotation.
+         */
+        set emissiveMapRotation(value) {
+            this._emissiveMapRotation = value;
+            if (this.material) {
+                this.material.emissiveMapRotation = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the 2D rotation of the emissive map.
+         * @returns The rotation.
+         */
+        get emissiveMapRotation() {
+            return this._emissiveMapRotation;
+        }
+        /**
+         * Sets the 2D tiling of the emissive map.
+         * @param value - The tiling.
+         */
+        set emissiveMapTiling(value) {
+            this._emissiveMapTiling = value;
+            if (this.material) {
+                this.material.emissiveMapTiling = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the 2D tiling of the emissive map.
+         * @returns The tiling.
+         */
+        get emissiveMapTiling() {
+            return this._emissiveMapTiling;
+        }
+        /**
+         * Sets the UV channel the emissive map samples.
+         * @param value - The UV channel.
+         */
+        set emissiveMapUv(value) {
+            this._emissiveMapUv = value;
+            if (this.material) {
+                this.material.emissiveMapUv = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the UV channel the emissive map samples.
+         * @returns The UV channel.
+         */
+        get emissiveMapUv() {
+            return this._emissiveMapUv;
+        }
+        /**
+         * Sets whether to use the GGX specular model, which supports anisotropy.
+         * @param value - The GGX specular flag.
+         */
+        set enableGGXSpecular(value) {
+            this._enableGGXSpecular = value;
+            if (this.material) {
+                this.material.enableGGXSpecular = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets whether to use the GGX specular model.
+         * @returns The GGX specular flag.
+         */
+        get enableGGXSpecular() {
+            return this._enableGGXSpecular;
+        }
+        /**
+         * Sets the Fresnel model used for specular reflections at grazing angles.
+         * @param value - The Fresnel model.
+         */
+        set fresnelModel(value) {
+            this._fresnelModel = value;
+            if (this.material) {
+                this.material.fresnelModel = fresnelModels.get(value) ?? playcanvas.FRESNEL_SCHLICK;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the Fresnel model used for specular reflections at grazing angles.
+         * @returns The Fresnel model.
+         */
+        get fresnelModel() {
+            return this._fresnelModel;
+        }
+        /**
+         * Sets the glossiness of the material, from 0 (rough) to 1 (shiny). See also `roughness`.
+         * @param value - The gloss.
+         */
+        set gloss(value) {
+            this._gloss = value;
+            if (this.material) {
+                this.material.gloss = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the glossiness of the material.
+         * @returns The gloss.
+         */
+        get gloss() {
+            return this._gloss;
+        }
+        /**
+         * Sets whether the gloss value and map are inverted, which makes the material treat them as
+         * roughness. Setting `roughness` or `roughness-map` enables this automatically.
+         * @param value - The gloss invert flag.
+         */
+        set glossInvert(value) {
+            this._glossInvert = value;
+            if (this.material) {
+                this.material.glossInvert = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets whether the gloss value and map are inverted.
+         * @returns The gloss invert flag.
+         */
+        get glossInvert() {
+            return this._glossInvert;
+        }
+        /**
+         * Sets the id of the `pc-asset` to use as the gloss map. See also `roughnessMap`.
+         * @param value - The asset id.
+         */
+        set glossMap(value) {
+            this._glossMap = value;
+            this.setMap(value, 'glossMap');
+        }
+        /**
+         * Gets the id of the `pc-asset` used as the gloss map.
+         * @returns The asset id.
+         */
+        get glossMap() {
+            return this._glossMap;
+        }
+        /**
+         * Sets the color channel of the gloss map to sample.
+         * @param value - The channel.
+         */
+        set glossMapChannel(value) {
+            this._glossMapChannel = value;
+            if (this.material) {
+                this.material.glossMapChannel = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the color channel of the gloss map to sample.
+         * @returns The channel.
+         */
+        get glossMapChannel() {
+            return this._glossMapChannel;
+        }
+        /**
+         * Sets the 2D offset of the gloss map.
+         * @param value - The offset.
+         */
+        set glossMapOffset(value) {
+            this._glossMapOffset = value;
+            if (this.material) {
+                this.material.glossMapOffset = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the 2D offset of the gloss map.
+         * @returns The offset.
+         */
+        get glossMapOffset() {
+            return this._glossMapOffset;
+        }
+        /**
+         * Sets the 2D rotation of the gloss map, in degrees.
+         * @param value - The rotation.
+         */
+        set glossMapRotation(value) {
+            this._glossMapRotation = value;
+            if (this.material) {
+                this.material.glossMapRotation = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the 2D rotation of the gloss map.
+         * @returns The rotation.
+         */
+        get glossMapRotation() {
+            return this._glossMapRotation;
+        }
+        /**
+         * Sets the 2D tiling of the gloss map.
+         * @param value - The tiling.
+         */
+        set glossMapTiling(value) {
+            this._glossMapTiling = value;
+            if (this.material) {
+                this.material.glossMapTiling = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the 2D tiling of the gloss map.
+         * @returns The tiling.
+         */
+        get glossMapTiling() {
+            return this._glossMapTiling;
+        }
+        /**
+         * Sets the UV channel the gloss map samples.
+         * @param value - The UV channel.
+         */
+        set glossMapUv(value) {
+            this._glossMapUv = value;
+            if (this.material) {
+                this.material.glossMapUv = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the UV channel the gloss map samples.
+         * @returns The UV channel.
+         */
+        get glossMapUv() {
+            return this._glossMapUv;
+        }
+        /**
+         * Sets the id of the `pc-asset` to use as the height map, which drives parallax mapping.
+         * @param value - The asset id.
+         */
+        set heightMap(value) {
+            this._heightMap = value;
+            this.setMap(value, 'heightMap');
+        }
+        /**
+         * Gets the id of the `pc-asset` used as the height map.
+         * @returns The asset id.
+         */
+        get heightMap() {
+            return this._heightMap;
+        }
+        /**
+         * Sets the color channel of the height map to sample.
+         * @param value - The channel.
+         */
+        set heightMapChannel(value) {
+            this._heightMapChannel = value;
+            if (this.material) {
+                this.material.heightMapChannel = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the color channel of the height map to sample.
+         * @returns The channel.
+         */
+        get heightMapChannel() {
+            return this._heightMapChannel;
+        }
+        /**
+         * Sets the strength of the parallax effect driven by the height map.
+         * @param value - The height map factor.
+         */
+        set heightMapFactor(value) {
+            this._heightMapFactor = value;
+            if (this.material) {
+                this.material.heightMapFactor = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the strength of the parallax effect driven by the height map.
+         * @returns The height map factor.
+         */
+        get heightMapFactor() {
+            return this._heightMapFactor;
+        }
+        /**
+         * Sets the 2D offset of the height map.
+         * @param value - The offset.
+         */
+        set heightMapOffset(value) {
+            this._heightMapOffset = value;
+            if (this.material) {
+                this.material.heightMapOffset = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the 2D offset of the height map.
+         * @returns The offset.
+         */
+        get heightMapOffset() {
+            return this._heightMapOffset;
+        }
+        /**
+         * Sets the 2D rotation of the height map, in degrees.
+         * @param value - The rotation.
+         */
+        set heightMapRotation(value) {
+            this._heightMapRotation = value;
+            if (this.material) {
+                this.material.heightMapRotation = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the 2D rotation of the height map.
+         * @returns The rotation.
+         */
+        get heightMapRotation() {
+            return this._heightMapRotation;
+        }
+        /**
+         * Sets the 2D tiling of the height map.
+         * @param value - The tiling.
+         */
+        set heightMapTiling(value) {
+            this._heightMapTiling = value;
+            if (this.material) {
+                this.material.heightMapTiling = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the 2D tiling of the height map.
+         * @returns The tiling.
+         */
+        get heightMapTiling() {
+            return this._heightMapTiling;
+        }
+        /**
+         * Sets the UV channel the height map samples.
+         * @param value - The UV channel.
+         */
+        set heightMapUv(value) {
+            this._heightMapUv = value;
+            if (this.material) {
+                this.material.heightMapUv = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the UV channel the height map samples.
+         * @returns The UV channel.
+         */
+        get heightMapUv() {
+            return this._heightMapUv;
+        }
+        /**
+         * Sets how metallic the surface is, from 0 (dielectric) to 1 (metal).
+         * @param value - The metalness.
+         */
+        set metalness(value) {
+            this._metalness = value;
+            if (this.material) {
+                this.material.metalness = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets how metallic the surface is.
+         * @returns The metalness.
+         */
+        get metalness() {
+            return this._metalness;
+        }
+        /**
+         * Sets the id of the `pc-asset` to use as the metalness map.
+         * @param value - The asset id.
+         */
+        set metalnessMap(value) {
+            this._metalnessMap = value;
+            this.setMap(value, 'metalnessMap');
+        }
+        /**
+         * Gets the id of the `pc-asset` used as the metalness map.
+         * @returns The asset id.
+         */
+        get metalnessMap() {
+            return this._metalnessMap;
+        }
+        /**
+         * Sets the color channel of the metalness map to sample.
+         * @param value - The channel.
+         */
+        set metalnessMapChannel(value) {
+            this._metalnessMapChannel = value;
+            if (this.material) {
+                this.material.metalnessMapChannel = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the color channel of the metalness map to sample.
+         * @returns The channel.
+         */
+        get metalnessMapChannel() {
+            return this._metalnessMapChannel;
+        }
+        /**
+         * Sets the 2D offset of the metalness map.
+         * @param value - The offset.
+         */
+        set metalnessMapOffset(value) {
+            this._metalnessMapOffset = value;
+            if (this.material) {
+                this.material.metalnessMapOffset = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the 2D offset of the metalness map.
+         * @returns The offset.
+         */
+        get metalnessMapOffset() {
+            return this._metalnessMapOffset;
+        }
+        /**
+         * Sets the 2D rotation of the metalness map, in degrees.
+         * @param value - The rotation.
+         */
+        set metalnessMapRotation(value) {
+            this._metalnessMapRotation = value;
+            if (this.material) {
+                this.material.metalnessMapRotation = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the 2D rotation of the metalness map.
+         * @returns The rotation.
+         */
+        get metalnessMapRotation() {
+            return this._metalnessMapRotation;
+        }
+        /**
+         * Sets the 2D tiling of the metalness map.
+         * @param value - The tiling.
+         */
+        set metalnessMapTiling(value) {
+            this._metalnessMapTiling = value;
+            if (this.material) {
+                this.material.metalnessMapTiling = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the 2D tiling of the metalness map.
+         * @returns The tiling.
+         */
+        get metalnessMapTiling() {
+            return this._metalnessMapTiling;
+        }
+        /**
+         * Sets the UV channel the metalness map samples.
+         * @param value - The UV channel.
+         */
+        set metalnessMapUv(value) {
+            this._metalnessMapUv = value;
+            if (this.material) {
+                this.material.metalnessMapUv = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the UV channel the metalness map samples.
+         * @returns The UV channel.
+         */
+        get metalnessMapUv() {
+            return this._metalnessMapUv;
+        }
+        /**
+         * Sets the id of the `pc-asset` to use as the normal map.
+         * @param value - The asset id.
+         */
+        set normalMap(value) {
+            this._normalMap = value;
+            this.setMap(value, 'normalMap');
+        }
+        /**
+         * Gets the id of the `pc-asset` used as the normal map.
+         * @returns The asset id.
+         */
+        get normalMap() {
+            return this._normalMap;
+        }
+        /**
+         * Sets the 2D offset of the normal map.
+         * @param value - The offset.
+         */
+        set normalMapOffset(value) {
+            this._normalMapOffset = value;
+            if (this.material) {
+                this.material.normalMapOffset = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the 2D offset of the normal map.
+         * @returns The offset.
+         */
+        get normalMapOffset() {
+            return this._normalMapOffset;
+        }
+        /**
+         * Sets the 2D rotation of the normal map, in degrees.
+         * @param value - The rotation.
+         */
+        set normalMapRotation(value) {
+            this._normalMapRotation = value;
+            if (this.material) {
+                this.material.normalMapRotation = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the 2D rotation of the normal map.
+         * @returns The rotation.
+         */
+        get normalMapRotation() {
+            return this._normalMapRotation;
+        }
+        /**
+         * Sets the 2D tiling of the normal map.
+         * @param value - The tiling.
+         */
+        set normalMapTiling(value) {
+            this._normalMapTiling = value;
+            if (this.material) {
+                this.material.normalMapTiling = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the 2D tiling of the normal map.
+         * @returns The tiling.
+         */
+        get normalMapTiling() {
+            return this._normalMapTiling;
+        }
+        /**
+         * Sets the UV channel the normal map samples.
+         * @param value - The UV channel.
+         */
+        set normalMapUv(value) {
+            this._normalMapUv = value;
+            if (this.material) {
+                this.material.normalMapUv = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the UV channel the normal map samples.
+         * @returns The UV channel.
+         */
+        get normalMapUv() {
+            return this._normalMapUv;
+        }
+        /**
+         * Sets whether ambient occlusion also attenuates direct lighting.
+         * @param value - The occlude direct flag.
+         */
+        set occludeDirect(value) {
+            this._occludeDirect = value;
+            if (this.material) {
+                // @ts-ignore see createMaterial() - the engine mistypes occludeDirect as a number
+                this.material.occludeDirect = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets whether ambient occlusion also attenuates direct lighting.
+         * @returns The occlude direct flag.
+         */
+        get occludeDirect() {
+            return this._occludeDirect;
+        }
+        /**
+         * Sets how specular reflections are occluded.
+         * @param value - The specular occlusion mode.
+         */
+        set occludeSpecular(value) {
+            this._occludeSpecular = value;
+            if (this.material) {
+                this.material.occludeSpecular = occludeSpeculars.get(value) ?? playcanvas.SPECOCC_AO;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets how specular reflections are occluded.
+         * @returns The specular occlusion mode.
+         */
+        get occludeSpecular() {
+            return this._occludeSpecular;
+        }
+        /**
+         * Sets the opacity of the material, from 0 (transparent) to 1 (opaque), which requires a
+         * `blend-type` other than `none` to have any visible effect.
+         * @param value - The opacity.
+         */
+        set opacity(value) {
+            this._opacity = value;
+            if (this.material) {
+                this.material.opacity = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the opacity of the material, which requires a `blend-type` other than `none` to have
+         * any visible effect.
+         * @returns The opacity.
+         */
+        get opacity() {
+            return this._opacity;
+        }
+        /**
+         * Sets the dithering used to render opacity, which approximates transparency without blending.
+         * @param value - The dither mode.
+         */
+        set opacityDither(value) {
+            this._opacityDither = value;
+            if (this.material) {
+                this.material.opacityDither = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the dithering used to render opacity.
+         * @returns The dither mode.
+         */
+        get opacityDither() {
+            return this._opacityDither;
+        }
+        /**
+         * Sets whether specular highlights fade out as the material becomes transparent.
+         * @param value - The opacity fades specular flag.
+         */
+        set opacityFadesSpecular(value) {
+            this._opacityFadesSpecular = value;
+            if (this.material) {
+                this.material.opacityFadesSpecular = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets whether specular highlights fade out as the material becomes transparent.
+         * @returns The opacity fades specular flag.
+         */
+        get opacityFadesSpecular() {
+            return this._opacityFadesSpecular;
+        }
+        /**
+         * Sets the id of the `pc-asset` to use as the opacity map.
+         * @param value - The asset id.
+         */
+        set opacityMap(value) {
+            this._opacityMap = value;
+            this.setMap(value, 'opacityMap');
+        }
+        /**
+         * Gets the id of the `pc-asset` used as the opacity map.
+         * @returns The asset id.
+         */
+        get opacityMap() {
+            return this._opacityMap;
+        }
+        /**
+         * Sets the color channel of the opacity map to sample.
+         * @param value - The channel.
+         */
+        set opacityMapChannel(value) {
+            this._opacityMapChannel = value;
+            if (this.material) {
+                this.material.opacityMapChannel = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the color channel of the opacity map to sample.
+         * @returns The channel.
+         */
+        get opacityMapChannel() {
+            return this._opacityMapChannel;
+        }
+        /**
+         * Sets the 2D offset of the opacity map.
+         * @param value - The offset.
+         */
+        set opacityMapOffset(value) {
+            this._opacityMapOffset = value;
+            if (this.material) {
+                this.material.opacityMapOffset = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the 2D offset of the opacity map.
+         * @returns The offset.
+         */
+        get opacityMapOffset() {
+            return this._opacityMapOffset;
+        }
+        /**
+         * Sets the 2D rotation of the opacity map, in degrees.
+         * @param value - The rotation.
+         */
+        set opacityMapRotation(value) {
+            this._opacityMapRotation = value;
+            if (this.material) {
+                this.material.opacityMapRotation = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the 2D rotation of the opacity map.
+         * @returns The rotation.
+         */
+        get opacityMapRotation() {
+            return this._opacityMapRotation;
+        }
+        /**
+         * Sets the 2D tiling of the opacity map.
+         * @param value - The tiling.
+         */
+        set opacityMapTiling(value) {
+            this._opacityMapTiling = value;
+            if (this.material) {
+                this.material.opacityMapTiling = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the 2D tiling of the opacity map.
+         * @returns The tiling.
+         */
+        get opacityMapTiling() {
+            return this._opacityMapTiling;
+        }
+        /**
+         * Sets the UV channel the opacity map samples.
+         * @param value - The UV channel.
+         */
+        set opacityMapUv(value) {
+            this._opacityMapUv = value;
+            if (this.material) {
+                this.material.opacityMapUv = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the UV channel the opacity map samples.
+         * @returns The UV channel.
+         */
+        get opacityMapUv() {
+            return this._opacityMapUv;
+        }
+        /**
+         * Sets the roughness of the material, from 0 (shiny) to 1 (rough). This is an alias for `gloss`
+         * that also inverts the gloss channel, so do not combine it with the `gloss` attributes.
+         * @param value - The roughness.
+         */
+        set roughness(value) {
+            this.gloss = value;
+            this.glossInvert = true;
+        }
+        /**
+         * Gets the roughness of the material.
+         * @returns The roughness.
+         */
+        get roughness() {
+            return this._gloss;
+        }
+        /**
+         * Sets the id of the `pc-asset` to use as the roughness map. This is an alias for `glossMap`
+         * that also inverts the gloss channel, so do not combine it with the `gloss` attributes.
+         * @param value - The asset id.
+         */
+        set roughnessMap(value) {
+            this.glossMap = value;
+            this.glossInvert = true;
+        }
+        /**
+         * Gets the id of the `pc-asset` used as the roughness map.
+         * @returns The asset id.
+         */
+        get roughnessMap() {
+            return this._glossMap;
+        }
+        /**
+         * Sets the depth offset applied in proportion to a surface's slope, used to resolve z-fighting.
+         * @param value - The slope depth bias.
+         */
+        set slopeDepthBias(value) {
+            this._slopeDepthBias = value;
+            if (this.material) {
+                this.material.slopeDepthBias = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the depth offset applied in proportion to a surface's slope.
+         * @returns The slope depth bias.
+         */
+        get slopeDepthBias() {
+            return this._slopeDepthBias;
+        }
+        /**
+         * Sets the specular color of the material, which applies only when the metalness workflow is
+         * disabled or `use-metalness-specular-color` is enabled.
+         * @param value - The specular color.
+         */
+        set specular(value) {
+            this._specular = value;
+            if (this.material) {
+                this.material.specular = value;
+                this._scheduleUpdate();
+            }
+        }
+        /**
+         * Gets the specular color of the material, which applies only when the metalness workflow is
+         * disabled or `use-metalness-specular-color` is enabled.
+         * @returns The specular color.
+         */
+        get specular() {
+            return this._specular;
+        }
+        /**
+         * Sets the strength of specular reflections at direct angles, from 0 to 1, which applies only
+         * when `use-metalness-specular-color` is enabled.
+         * @param value - The specularity factor.
+         */
+        set specularityFactor(value) {
+            this._specularityFactor = value;
+            if (this.material) {
+                this.material.specularityFactor = value;
+                this._scheduleUpdate();
             }
         }
-        createMaterial() {
-            this.material = new playcanvas.StandardMaterial();
-            this.material.glossInvert = false;
-            this.material.useMetalness = false;
-            this.material.diffuse = this._diffuse;
-            this.diffuseMap = this._diffuseMap;
-            this.metalnessMap = this._metalnessMap;
-            this.normalMap = this._normalMap;
-            this.roughnessMap = this._roughnessMap;
-            this.material.update();
+        /**
+         * Gets the strength of specular reflections at direct angles, which applies only when
+         * `use-metalness-specular-color` is enabled.
+         * @returns The specularity factor.
+         */
+        get specularityFactor() {
+            return this._specularityFactor;
         }
-        disconnectedCallback() {
+        /**
+         * Sets whether back faces are lit as though their normals were flipped.
+         * @param value - The two sided lighting flag.
+         */
+        set twoSidedLighting(value) {
+            this._twoSidedLighting = value;
             if (this.material) {
-                this.material.destroy();
-                this.material = null;
+                this.material.twoSidedLighting = value;
+                this._scheduleUpdate();
             }
         }
-        setMap(map, property) {
+        /**
+         * Gets whether back faces are lit as though their normals were flipped.
+         * @returns The two sided lighting flag.
+         */
+        get twoSidedLighting() {
+            return this._twoSidedLighting;
+        }
+        /**
+         * Sets whether the material is affected by scene fog.
+         * @param value - The use fog flag.
+         */
+        set useFog(value) {
+            this._useFog = value;
             if (this.material) {
-                const asset = AssetElement.get(map);
-                if (asset) {
-                    if (asset.loaded) {
-                        this.material[property] = asset.resource;
-                        this.material[property].anisotropy = 4;
-                    }
-                    else {
-                        asset.once('load', () => {
-                            this.material[property] = asset.resource;
-                            this.material[property].anisotropy = 4;
-                            this.material.update();
-                        });
-                    }
-                }
+                this.material.useFog = value;
+                this._scheduleUpdate();
             }
         }
-        set diffuse(value) {
-            this._diffuse = value;
+        /**
+         * Gets whether the material is affected by scene fog.
+         * @returns The use fog flag.
+         */
+        get useFog() {
+            return this._useFog;
+        }
+        /**
+         * Sets whether the material is affected by scene lights. When disabled the material renders
+         * unlit, using the diffuse color and map alone.
+         * @param value - The use lighting flag.
+         */
+        set useLighting(value) {
+            this._useLighting = value;
             if (this.material) {
-                this.material.diffuse = value;
+                this.material.useLighting = value;
+                this._scheduleUpdate();
             }
         }
-        get diffuse() {
-            return this._diffuse;
+        /**
+         * Gets whether the material is affected by scene lights.
+         * @returns The use lighting flag.
+         */
+        get useLighting() {
+            return this._useLighting;
         }
-        set diffuseMap(value) {
-            this._diffuseMap = value;
-            this.setMap(value, 'diffuseMap');
+        /**
+         * Sets whether to use the metalness workflow rather than the older specular workflow. Unlike a
+         * bare `StandardMaterial` this defaults to `true`, because the `metalness-*` attributes have no
+         * effect without it.
+         * @param value - The use metalness flag.
+         */
+        set useMetalness(value) {
+            this._useMetalness = value;
+            if (this.material) {
+                this.material.useMetalness = value;
+                this._scheduleUpdate();
+            }
         }
-        get diffuseMap() {
-            return this._diffuseMap;
+        /**
+         * Gets whether to use the metalness workflow.
+         * @returns The use metalness flag.
+         */
+        get useMetalness() {
+            return this._useMetalness;
         }
-        set metalnessMap(value) {
-            this._metalnessMap = value;
-            this.setMap(value, 'metalnessMap');
+        /**
+         * Sets whether the specular color tints reflections while the metalness workflow is in use.
+         * @param value - The use metalness specular color flag.
+         */
+        set useMetalnessSpecularColor(value) {
+            this._useMetalnessSpecularColor = value;
+            if (this.material) {
+                this.material.useMetalnessSpecularColor = value;
+                this._scheduleUpdate();
+            }
         }
-        get metalnessMap() {
-            return this._metalnessMap;
+        /**
+         * Gets whether the specular color tints reflections while the metalness workflow is in use.
+         * @returns The use metalness specular color flag.
+         */
+        get useMetalnessSpecularColor() {
+            return this._useMetalnessSpecularColor;
         }
-        set normalMap(value) {
-            this._normalMap = value;
-            this.setMap(value, 'normalMap');
+        /**
+         * Sets whether the material is lit by the scene's skybox.
+         * @param value - The use skybox flag.
+         */
+        set useSkybox(value) {
+            this._useSkybox = value;
+            if (this.material) {
+                this.material.useSkybox = value;
+                this._scheduleUpdate();
+            }
         }
-        get normalMap() {
-            return this._normalMap;
+        /**
+         * Gets whether the material is lit by the scene's skybox.
+         * @returns The use skybox flag.
+         */
+        get useSkybox() {
+            return this._useSkybox;
         }
-        set roughnessMap(value) {
-            this._roughnessMap = value;
-            this.setMap(value, 'glossMap');
+        /**
+         * Sets whether the camera's tone mapping is applied to the material.
+         * @param value - The use tonemap flag.
+         */
+        set useTonemap(value) {
+            this._useTonemap = value;
+            if (this.material) {
+                this.material.useTonemap = value;
+                this._scheduleUpdate();
+            }
         }
-        get roughnessMap() {
-            return this._roughnessMap;
+        /**
+         * Gets whether the camera's tone mapping is applied to the material.
+         * @returns The use tonemap flag.
+         */
+        get useTonemap() {
+            return this._useTonemap;
         }
         static get(id) {
             const materialElement = document.querySelector(`pc-material[id="${id}"]`);
-            return materialElement === null || materialElement === void 0 ? void 0 : materialElement.material;
+            return materialElement?.material;
         }
         static get observedAttributes() {
-            return ['diffuse', 'diffuse-map', 'metalness-map', 'normal-map', 'roughness-map'];
+            return [
+                'alpha-test',
+                'alpha-to-coverage',
+                'ao-intensity',
+                'ao-map',
+                'ao-map-channel',
+                'ao-map-offset',
+                'ao-map-rotation',
+                'ao-map-tiling',
+                'ao-map-uv',
+                'blend-type',
+                'bumpiness',
+                'cull',
+                'depth-bias',
+                'depth-test',
+                'depth-write',
+                'diffuse',
+                'diffuse-map',
+                'diffuse-map-channel',
+                'diffuse-map-offset',
+                'diffuse-map-rotation',
+                'diffuse-map-tiling',
+                'diffuse-map-uv',
+                'emissive',
+                'emissive-intensity',
+                'emissive-map',
+                'emissive-map-channel',
+                'emissive-map-offset',
+                'emissive-map-rotation',
+                'emissive-map-tiling',
+                'emissive-map-uv',
+                'enable-ggx-specular',
+                'fresnel-model',
+                'gloss',
+                'gloss-invert',
+                'gloss-map',
+                'gloss-map-channel',
+                'gloss-map-offset',
+                'gloss-map-rotation',
+                'gloss-map-tiling',
+                'gloss-map-uv',
+                'height-map',
+                'height-map-channel',
+                'height-map-factor',
+                'height-map-offset',
+                'height-map-rotation',
+                'height-map-tiling',
+                'height-map-uv',
+                'metalness',
+                'metalness-map',
+                'metalness-map-channel',
+                'metalness-map-offset',
+                'metalness-map-rotation',
+                'metalness-map-tiling',
+                'metalness-map-uv',
+                'normal-map',
+                'normal-map-offset',
+                'normal-map-rotation',
+                'normal-map-tiling',
+                'normal-map-uv',
+                'occlude-direct',
+                'occlude-specular',
+                'opacity',
+                'opacity-dither',
+                'opacity-fades-specular',
+                'opacity-map',
+                'opacity-map-channel',
+                'opacity-map-offset',
+                'opacity-map-rotation',
+                'opacity-map-tiling',
+                'opacity-map-uv',
+                'roughness',
+                'roughness-map',
+                'slope-depth-bias',
+                'specular',
+                'specularity-factor',
+                'two-sided-lighting',
+                'use-fog',
+                'use-lighting',
+                'use-metalness',
+                'use-metalness-specular-color',
+                'use-skybox',
+                'use-tonemap'
+            ];
         }
+        // newValue is null when an attribute is removed, which several branches below rely on. The
+        // other elements still declare it as `string`; widening those surfaces 21 real removal bugs of
+        // the #309 shape, which is its own change rather than a signature tweak.
         attributeChangedCallback(name, _oldValue, newValue) {
             switch (name) {
+                case 'alpha-test':
+                    this.alphaTest = parseNumber(newValue, 0, name);
+                    break;
+                case 'alpha-to-coverage':
+                    this.alphaToCoverage = parseBool(newValue, false);
+                    break;
+                case 'ao-intensity':
+                    this.aoIntensity = parseNumber(newValue, 1, name);
+                    break;
+                case 'ao-map':
+                    this.aoMap = newValue ?? '';
+                    break;
+                case 'ao-map-channel':
+                    this.aoMapChannel = parseEnum(newValue, scalarChannels, 'g', name);
+                    break;
+                case 'ao-map-offset':
+                    this.aoMapOffset = parseVec2(newValue, new playcanvas.Vec2(0, 0), name);
+                    break;
+                case 'ao-map-rotation':
+                    this.aoMapRotation = parseNumber(newValue, 0, name);
+                    break;
+                case 'ao-map-tiling':
+                    this.aoMapTiling = parseVec2(newValue, new playcanvas.Vec2(1, 1), name);
+                    break;
+                case 'ao-map-uv':
+                    this.aoMapUv = parseNumber(newValue, 0, name);
+                    break;
+                case 'blend-type':
+                    this.blendType = parseEnum(newValue, blendTypes, 'none', name);
+                    break;
+                case 'bumpiness':
+                    this.bumpiness = parseNumber(newValue, 1, name);
+                    break;
+                case 'cull':
+                    this.cull = parseEnum(newValue, cullModes, 'back', name);
+                    break;
+                case 'depth-bias':
+                    this.depthBias = parseNumber(newValue, 0, name);
+                    break;
+                case 'depth-test':
+                    this.depthTest = parseBool(newValue, true);
+                    break;
+                case 'depth-write':
+                    this.depthWrite = parseBool(newValue, true);
+                    break;
                 case 'diffuse':
-                    this.diffuse = parseColor(newValue, playcanvas.Color.WHITE, name);
+                    this.diffuse = parseColor(newValue, new playcanvas.Color(1, 1, 1), name);
                     break;
                 case 'diffuse-map':
-                    this.diffuseMap = newValue;
+                    this.diffuseMap = newValue ?? '';
+                    break;
+                case 'diffuse-map-channel':
+                    this.diffuseMapChannel = parseEnum(newValue, colorChannels, 'rgb', name);
+                    break;
+                case 'diffuse-map-offset':
+                    this.diffuseMapOffset = parseVec2(newValue, new playcanvas.Vec2(0, 0), name);
+                    break;
+                case 'diffuse-map-rotation':
+                    this.diffuseMapRotation = parseNumber(newValue, 0, name);
+                    break;
+                case 'diffuse-map-tiling':
+                    this.diffuseMapTiling = parseVec2(newValue, new playcanvas.Vec2(1, 1), name);
+                    break;
+                case 'diffuse-map-uv':
+                    this.diffuseMapUv = parseNumber(newValue, 0, name);
+                    break;
+                case 'emissive':
+                    this.emissive = parseColor(newValue, new playcanvas.Color(0, 0, 0), name);
+                    break;
+                case 'emissive-intensity':
+                    this.emissiveIntensity = parseNumber(newValue, 1, name);
+                    break;
+                case 'emissive-map':
+                    this.emissiveMap = newValue ?? '';
+                    break;
+                case 'emissive-map-channel':
+                    this.emissiveMapChannel = parseEnum(newValue, colorChannels, 'rgb', name);
+                    break;
+                case 'emissive-map-offset':
+                    this.emissiveMapOffset = parseVec2(newValue, new playcanvas.Vec2(0, 0), name);
+                    break;
+                case 'emissive-map-rotation':
+                    this.emissiveMapRotation = parseNumber(newValue, 0, name);
+                    break;
+                case 'emissive-map-tiling':
+                    this.emissiveMapTiling = parseVec2(newValue, new playcanvas.Vec2(1, 1), name);
+                    break;
+                case 'emissive-map-uv':
+                    this.emissiveMapUv = parseNumber(newValue, 0, name);
+                    break;
+                case 'enable-ggx-specular':
+                    this.enableGGXSpecular = parseBool(newValue, false);
+                    break;
+                case 'fresnel-model':
+                    this.fresnelModel = parseEnum(newValue, fresnelModels, 'schlick', name);
+                    break;
+                case 'gloss':
+                    this.gloss = parseNumber(newValue, 0.25, name);
+                    this._warnGlossConflict();
+                    break;
+                case 'gloss-invert':
+                    this.glossInvert = parseBool(newValue, false);
+                    this._warnGlossConflict();
+                    break;
+                case 'gloss-map':
+                    this.glossMap = newValue ?? '';
+                    this._warnGlossConflict();
+                    break;
+                case 'gloss-map-channel':
+                    this.glossMapChannel = parseEnum(newValue, scalarChannels, 'g', name);
+                    break;
+                case 'gloss-map-offset':
+                    this.glossMapOffset = parseVec2(newValue, new playcanvas.Vec2(0, 0), name);
+                    break;
+                case 'gloss-map-rotation':
+                    this.glossMapRotation = parseNumber(newValue, 0, name);
+                    break;
+                case 'gloss-map-tiling':
+                    this.glossMapTiling = parseVec2(newValue, new playcanvas.Vec2(1, 1), name);
+                    break;
+                case 'gloss-map-uv':
+                    this.glossMapUv = parseNumber(newValue, 0, name);
+                    break;
+                case 'height-map':
+                    this.heightMap = newValue ?? '';
+                    break;
+                case 'height-map-channel':
+                    this.heightMapChannel = parseEnum(newValue, scalarChannels, 'g', name);
+                    break;
+                case 'height-map-factor':
+                    this.heightMapFactor = parseNumber(newValue, 1, name);
+                    break;
+                case 'height-map-offset':
+                    this.heightMapOffset = parseVec2(newValue, new playcanvas.Vec2(0, 0), name);
+                    break;
+                case 'height-map-rotation':
+                    this.heightMapRotation = parseNumber(newValue, 0, name);
+                    break;
+                case 'height-map-tiling':
+                    this.heightMapTiling = parseVec2(newValue, new playcanvas.Vec2(1, 1), name);
+                    break;
+                case 'height-map-uv':
+                    this.heightMapUv = parseNumber(newValue, 0, name);
+                    break;
+                case 'metalness':
+                    this.metalness = parseNumber(newValue, 0, name);
                     break;
                 case 'metalness-map':
-                    this.metalnessMap = newValue;
+                    this.metalnessMap = newValue ?? '';
+                    break;
+                case 'metalness-map-channel':
+                    this.metalnessMapChannel = parseEnum(newValue, scalarChannels, 'g', name);
+                    break;
+                case 'metalness-map-offset':
+                    this.metalnessMapOffset = parseVec2(newValue, new playcanvas.Vec2(0, 0), name);
+                    break;
+                case 'metalness-map-rotation':
+                    this.metalnessMapRotation = parseNumber(newValue, 0, name);
+                    break;
+                case 'metalness-map-tiling':
+                    this.metalnessMapTiling = parseVec2(newValue, new playcanvas.Vec2(1, 1), name);
+                    break;
+                case 'metalness-map-uv':
+                    this.metalnessMapUv = parseNumber(newValue, 0, name);
                     break;
                 case 'normal-map':
-                    this.normalMap = newValue;
+                    this.normalMap = newValue ?? '';
+                    break;
+                case 'normal-map-offset':
+                    this.normalMapOffset = parseVec2(newValue, new playcanvas.Vec2(0, 0), name);
+                    break;
+                case 'normal-map-rotation':
+                    this.normalMapRotation = parseNumber(newValue, 0, name);
+                    break;
+                case 'normal-map-tiling':
+                    this.normalMapTiling = parseVec2(newValue, new playcanvas.Vec2(1, 1), name);
+                    break;
+                case 'normal-map-uv':
+                    this.normalMapUv = parseNumber(newValue, 0, name);
+                    break;
+                case 'occlude-direct':
+                    this.occludeDirect = parseBool(newValue, false);
+                    break;
+                case 'occlude-specular':
+                    this.occludeSpecular = parseEnum(newValue, occludeSpeculars, 'ao', name);
+                    break;
+                case 'opacity':
+                    this.opacity = parseNumber(newValue, 1, name);
+                    break;
+                case 'opacity-dither':
+                    this.opacityDither = parseEnum(newValue, opacityDithers, 'none', name);
+                    break;
+                case 'opacity-fades-specular':
+                    this.opacityFadesSpecular = parseBool(newValue, true);
+                    break;
+                case 'opacity-map':
+                    this.opacityMap = newValue ?? '';
+                    break;
+                case 'opacity-map-channel':
+                    this.opacityMapChannel = parseEnum(newValue, scalarChannels, 'a', name);
+                    break;
+                case 'opacity-map-offset':
+                    this.opacityMapOffset = parseVec2(newValue, new playcanvas.Vec2(0, 0), name);
+                    break;
+                case 'opacity-map-rotation':
+                    this.opacityMapRotation = parseNumber(newValue, 0, name);
+                    break;
+                case 'opacity-map-tiling':
+                    this.opacityMapTiling = parseVec2(newValue, new playcanvas.Vec2(1, 1), name);
+                    break;
+                case 'opacity-map-uv':
+                    this.opacityMapUv = parseNumber(newValue, 0, name);
+                    break;
+                case 'roughness':
+                    // Aliases gloss, and inverts it so the value reads as roughness. Removing the
+                    // attribute restores the engine's uninverted interpretation.
+                    this.gloss = parseNumber(newValue, 0.25, name);
+                    this.glossInvert = newValue !== null;
+                    this._warnGlossConflict();
                     break;
                 case 'roughness-map':
-                    this.roughnessMap = newValue;
+                    this.glossMap = newValue ?? '';
+                    this.glossInvert = newValue !== null;
+                    this._warnGlossConflict();
+                    break;
+                case 'slope-depth-bias':
+                    this.slopeDepthBias = parseNumber(newValue, 0, name);
+                    break;
+                case 'specular':
+                    this.specular = parseColor(newValue, new playcanvas.Color(0, 0, 0), name);
+                    break;
+                case 'specularity-factor':
+                    this.specularityFactor = parseNumber(newValue, 1, name);
+                    break;
+                case 'two-sided-lighting':
+                    this.twoSidedLighting = parseBool(newValue, false);
+                    break;
+                case 'use-fog':
+                    this.useFog = parseBool(newValue, true);
+                    break;
+                case 'use-lighting':
+                    this.useLighting = parseBool(newValue, true);
+                    break;
+                case 'use-metalness':
+                    this.useMetalness = parseBool(newValue, true);
+                    break;
+                case 'use-metalness-specular-color':
+                    this.useMetalnessSpecularColor = parseBool(newValue, false);
+                    break;
+                case 'use-skybox':
+                    this.useSkybox = parseBool(newValue, true);
+                    break;
+                case 'use-tonemap':
+                    this.useTonemap = parseBool(newValue, true);
                     break;
             }
         }
@@ -4767,13 +7111,13 @@
      * @category Components
      */
     class RenderComponentElement extends ComponentElement {
+        _castShadows = true;
+        _material = '';
+        _receiveShadows = true;
+        _type = 'box';
         /** @ignore */
         constructor() {
             super('render');
-            this._castShadows = true;
-            this._material = '';
-            this._receiveShadows = true;
-            this._type = 'box';
         }
         getInitialComponentData() {
             return {
@@ -4830,8 +7174,13 @@
          */
         set material(value) {
             this._material = value;
-            if (this.component) {
-                this.component.material = MaterialElement.get(value);
+            const material = MaterialElement.get(value);
+            // Guarded like every other reference attribute in the library. Assigning an unresolved
+            // lookup used to write `undefined` straight through to every mesh instance, and the
+            // engine's MeshInstance setter takes that literally - it clears the material and skips
+            // the ref/transparency/key bookkeeping, leaving the mesh with no material at all.
+            if (this.component && material) {
+                this.component.material = material;
             }
         }
         /**
@@ -4868,7 +7217,7 @@
                     this.castShadows = parseBool(newValue, true);
                     break;
                 case 'material':
-                    this.material = newValue;
+                    this.material = newValue ?? '';
                     break;
                 case 'receive-shadows':
                     this.receiveShadows = parseBool(newValue, true);
@@ -4890,45 +7239,45 @@
      * @category Components
      */
     class RigidBodyComponentElement extends ComponentElement {
+        /**
+         * The angular damping of the rigidbody.
+         */
+        _angularDamping = 0;
+        /**
+         * The angular factor of the rigidbody.
+         */
+        _angularFactor = new playcanvas.Vec3(1, 1, 1);
+        /**
+         * The friction of the rigidbody.
+         */
+        _friction = 0.5;
+        /**
+         * The linear damping of the rigidbody.
+         */
+        _linearDamping = 0;
+        /**
+         * The linear factor of the rigidbody.
+         */
+        _linearFactor = new playcanvas.Vec3(1, 1, 1);
+        /**
+         * The mass of the rigidbody.
+         */
+        _mass = 1;
+        /**
+         * The restitution of the rigidbody.
+         */
+        _restitution = 0;
+        /**
+         * The rolling friction of the rigidbody.
+         */
+        _rollingFriction = 0;
+        /**
+         * The type of the rigidbody.
+         */
+        _type = 'static';
         /** @ignore */
         constructor() {
             super('rigidbody');
-            /**
-             * The angular damping of the rigidbody.
-             */
-            this._angularDamping = 0;
-            /**
-             * The angular factor of the rigidbody.
-             */
-            this._angularFactor = new playcanvas.Vec3(1, 1, 1);
-            /**
-             * The friction of the rigidbody.
-             */
-            this._friction = 0.5;
-            /**
-             * The linear damping of the rigidbody.
-             */
-            this._linearDamping = 0;
-            /**
-             * The linear factor of the rigidbody.
-             */
-            this._linearFactor = new playcanvas.Vec3(1, 1, 1);
-            /**
-             * The mass of the rigidbody.
-             */
-            this._mass = 1;
-            /**
-             * The restitution of the rigidbody.
-             */
-            this._restitution = 0;
-            /**
-             * The rolling friction of the rigidbody.
-             */
-            this._rollingFriction = 0;
-            /**
-             * The type of the rigidbody.
-             */
-            this._type = 'static';
         }
         getInitialComponentData() {
             return {
@@ -5078,15 +7427,15 @@
      * @category Components
      */
     class ScreenComponentElement extends ComponentElement {
+        _screenSpace = false;
+        _resolution = new playcanvas.Vec2(640, 320);
+        _referenceResolution = new playcanvas.Vec2(640, 320);
+        _priority = 0;
+        _blend = false;
+        _scaleBlend = 0.5;
         /** @ignore */
         constructor() {
             super('screen');
-            this._screenSpace = false;
-            this._resolution = new playcanvas.Vec2(640, 320);
-            this._referenceResolution = new playcanvas.Vec2(640, 320);
-            this._priority = 0;
-            this._blend = false;
-            this._scaleBlend = 0.5;
         }
         getInitialComponentData() {
             return {
@@ -5209,13 +7558,13 @@
      * @category Components
      */
     class ScrollbarComponentElement extends ComponentElement {
+        _orientation = 'horizontal';
+        _value = 0;
+        _handleSize = 0.5;
+        _handle = '';
         /** @ignore */
         constructor() {
             super('scrollbar');
-            this._orientation = 'horizontal';
-            this._value = 0;
-            this._handleSize = 0.5;
-            this._handle = '';
         }
         getInitialComponentData() {
             const data = {
@@ -5242,10 +7591,9 @@
          * @param value - The orientation.
          */
         set orientation(value) {
-            var _a;
             this._orientation = value;
             if (this.component) {
-                this.component.orientation = (_a = orientations.get(value)) !== null && _a !== void 0 ? _a : playcanvas.ORIENTATION_HORIZONTAL;
+                this.component.orientation = orientations.get(value) ?? playcanvas.ORIENTATION_HORIZONTAL;
             }
         }
         /**
@@ -5330,7 +7678,7 @@
                     this.handleSize = parseNumber(newValue, 0.5, name);
                     break;
                 case 'handle':
-                    this.handle = newValue;
+                    this.handle = newValue ?? '';
                     break;
             }
         }
@@ -5355,22 +7703,22 @@
      * @category Components
      */
     class ScrollViewComponentElement extends ComponentElement {
+        _horizontal = true;
+        _vertical = true;
+        _scrollMode = 'bounce';
+        _bounceAmount = 0.1;
+        _friction = 0.05;
+        _useMouseWheel = true;
+        _mouseWheelSensitivity = new playcanvas.Vec2(1, 1);
+        _horizontalScrollbarVisibility = 'when-required';
+        _verticalScrollbarVisibility = 'when-required';
+        _viewport = '';
+        _content = '';
+        _horizontalScrollbar = '';
+        _verticalScrollbar = '';
         /** @ignore */
         constructor() {
             super('scrollview');
-            this._horizontal = true;
-            this._vertical = true;
-            this._scrollMode = 'bounce';
-            this._bounceAmount = 0.1;
-            this._friction = 0.05;
-            this._useMouseWheel = true;
-            this._mouseWheelSensitivity = new playcanvas.Vec2(1, 1);
-            this._horizontalScrollbarVisibility = 'when-required';
-            this._verticalScrollbarVisibility = 'when-required';
-            this._viewport = '';
-            this._content = '';
-            this._horizontalScrollbar = '';
-            this._verticalScrollbar = '';
         }
         getInitialComponentData() {
             const data = {
@@ -5449,10 +7797,9 @@
          * @param value - The scroll mode.
          */
         set scrollMode(value) {
-            var _a;
             this._scrollMode = value;
             if (this.component) {
-                this.component.scrollMode = (_a = scrollModes.get(value)) !== null && _a !== void 0 ? _a : playcanvas.SCROLL_MODE_BOUNCE;
+                this.component.scrollMode = scrollModes.get(value) ?? playcanvas.SCROLL_MODE_BOUNCE;
             }
         }
         /**
@@ -5538,10 +7885,9 @@
          * @param value - The horizontal scrollbar visibility.
          */
         set horizontalScrollbarVisibility(value) {
-            var _a;
             this._horizontalScrollbarVisibility = value;
             if (this.component) {
-                this.component.horizontalScrollbarVisibility = (_a = visibilities.get(value)) !== null && _a !== void 0 ? _a : playcanvas.SCROLLBAR_VISIBILITY_SHOW_WHEN_REQUIRED;
+                this.component.horizontalScrollbarVisibility = visibilities.get(value) ?? playcanvas.SCROLLBAR_VISIBILITY_SHOW_WHEN_REQUIRED;
             }
         }
         /**
@@ -5557,10 +7903,9 @@
          * @param value - The vertical scrollbar visibility.
          */
         set verticalScrollbarVisibility(value) {
-            var _a;
             this._verticalScrollbarVisibility = value;
             if (this.component) {
-                this.component.verticalScrollbarVisibility = (_a = visibilities.get(value)) !== null && _a !== void 0 ? _a : playcanvas.SCROLLBAR_VISIBILITY_SHOW_WHEN_REQUIRED;
+                this.component.verticalScrollbarVisibility = visibilities.get(value) ?? playcanvas.SCROLLBAR_VISIBILITY_SHOW_WHEN_REQUIRED;
             }
         }
         /**
@@ -5695,16 +8040,16 @@
                     this.verticalScrollbarVisibility = parseEnum(newValue, visibilities, 'when-required', name);
                     break;
                 case 'viewport':
-                    this.viewport = newValue;
+                    this.viewport = newValue ?? '';
                     break;
                 case 'content':
-                    this.content = newValue;
+                    this.content = newValue ?? '';
                     break;
                 case 'horizontal-scrollbar':
-                    this.horizontalScrollbar = newValue;
+                    this.horizontalScrollbar = newValue ?? '';
                     break;
                 case 'vertical-scrollbar':
-                    this.verticalScrollbar = newValue;
+                    this.verticalScrollbar = newValue ?? '';
                     break;
             }
         }
@@ -5736,24 +8081,28 @@
      *
      * The element becomes ready once its script instance has been created by the parent
      * `<pc-scripts>` element.
+     *
+     * @fires {CustomEvent} scriptattributeschange - Fired when the script's attributes change. The
+     * `detail` carries the new `attributes` object. Bubbles.
+     * @fires {CustomEvent} scriptenablechange - Fired when the script's enabled state changes. The
+     * `detail` carries the new `enabled` state. Bubbles.
+     * @fires {CustomEvent} scriptnamechange - Fired when the script is renamed on a live element. The
+     * `detail` carries `oldName` and `newName`. Bubbles.
      */
     class ScriptElement extends AsyncElement {
-        constructor() {
-            super(...arguments);
-            this._attributes = {};
-            this._enabled = true;
-            /**
-             * Whether readiness has been signalled. Creation can happen more than once over an
-             * element's life (a runtime `name` change recreates the instance), but `ready` is a
-             * one-shot signal, so only the first successful creation fires it.
-             */
-            this._readySignalled = false;
-            /**
-             * The Script instance created for this element by its parent `<pc-scripts>` element.
-             * @ignore
-             */
-            this._script = null;
-        }
+        _attributes = {};
+        _enabled = true;
+        /**
+         * Whether readiness has been signalled. Creation can happen more than once over an
+         * element's life (a runtime `name` change recreates the instance), but `ready` is a
+         * one-shot signal, so only the first successful creation fires it.
+         */
+        _readySignalled = false;
+        /**
+         * The Script instance created for this element by its parent `<pc-scripts>` element.
+         * @ignore
+         */
+        _script = null;
         /**
          * Sets the attributes of the script as an object. Values are converted with the same rules
          * as the `attributes` attribute: `asset:`/`entity:` references and `vec2:`/`vec3:`/`vec4:`/
@@ -5763,7 +8112,7 @@
          * @param value - The attributes of the script.
          */
         set scriptAttributes(value) {
-            this._attributes = value !== null && value !== void 0 ? value : {};
+            this._attributes = value ?? {};
             this.dispatchEvent(new CustomEvent('scriptattributeschange', {
                 detail: { attributes: this._attributes },
                 bubbles: true
@@ -5815,8 +8164,7 @@
          * @returns The name.
          */
         get name() {
-            var _a;
-            return (_a = this.getAttribute('name')) !== null && _a !== void 0 ? _a : '';
+            return this.getAttribute('name') ?? '';
         }
         /**
          * Gets the {@link Script} instance created for this element. Returns `null` until the
@@ -5828,10 +8176,9 @@
             return this._script;
         }
         connectedCallback() {
-            var _a;
             // Script instances are created by the parent pc-scripts element, so an element placed
             // anywhere else is inert and never becomes ready - warn rather than hang silently
-            if (((_a = this.parentElement) === null || _a === void 0 ? void 0 : _a.tagName) !== 'PC-SCRIPTS') {
+            if (this.parentElement?.tagName !== 'PC-SCRIPTS') {
                 console.warn(`pc-script '${this.getAttribute('name')}' must be a direct child of pc-scripts - script not created`);
             }
         }
@@ -5983,8 +8330,7 @@
      * @returns The color, or `raw`.
      */
     const colorConversion = (rest, raw) => {
-        var _a;
-        const components = (_a = parseComponents(rest, 4)) !== null && _a !== void 0 ? _a : parseComponents(rest, 3);
+        const components = parseComponents(rest, 4) ?? parseComponents(rest, 3);
         if (components) {
             return new playcanvas.Color(components);
         }
@@ -5992,7 +8338,7 @@
         return raw;
     };
     /**
-     * The conversion prefixes recognised in script attribute values, mapped to the conversion each
+     * The conversion prefixes recognized in script attribute values, mapped to the conversion each
      * performs. These keys are the single source of truth for the prefix vocabulary: they drive both
      * the conversion in `convertAttributes` and the has-a-prefix test in `setScriptProperty`, so a
      * prefix added here is automatically known to both.
@@ -6008,10 +8354,10 @@
     /**
      * Matches a value against the conversion prefixes. A prefix is the text before the first colon,
      * so a value whose remainder itself contains colons (`asset:a:b`) still resolves, and a value
-     * with an unrecognised prefix (`https://...`) or no colon does not match.
+     * with an unrecognized prefix (`https://...`) or no colon does not match.
      * @param value - The value to inspect.
      * @returns The matching converter and the text after the prefix, or `null` if the value carries
-     * no recognised prefix.
+     * no recognized prefix.
      */
     const matchConversion = (value) => {
         const index = value.indexOf(':');
@@ -6050,6 +8396,7 @@
      * @category Components
      */
     class ScriptComponentElement extends ComponentElement {
+        observer;
         /** @ignore */
         constructor() {
             super('script');
@@ -6304,8 +8651,7 @@
          * @param scriptElement - The `pc-script` element holding the attributes.
          */
         applyInlineAttributes(script, scriptElement) {
-            var _a;
-            const scriptName = (_a = scriptElement.getAttribute('name')) !== null && _a !== void 0 ? _a : '';
+            const scriptName = scriptElement.getAttribute('name') ?? '';
             for (const attr of Array.from(scriptElement.attributes)) {
                 if (!isReservedAttribute(attr.name)) {
                     this.setScriptProperty(script, scriptName, attr.name, attr.value);
@@ -6320,7 +8666,6 @@
          * @param attributeName - The name of the changed attribute.
          */
         applyScriptProperty(scriptElement, attributeName) {
-            var _a;
             const script = this.scriptFor(scriptElement);
             if (!script)
                 return;
@@ -6333,7 +8678,7 @@
                 }
                 return;
             }
-            this.setScriptProperty(script, (_a = scriptElement.getAttribute('name')) !== null && _a !== void 0 ? _a : '', attributeName, value);
+            this.setScriptProperty(script, scriptElement.getAttribute('name') ?? '', attributeName, value);
         }
         /**
          * Applies one attribute string to a script property. A string-typed attribute takes the
@@ -6448,9 +8793,8 @@
             }
         }
         disconnectedCallback() {
-            var _a;
             this.observer.disconnect();
-            (_a = super.disconnectedCallback) === null || _a === void 0 ? void 0 : _a.call(this);
+            super.disconnectedCallback?.();
         }
         /**
          * Gets the underlying PlayCanvas script component.
@@ -6471,16 +8815,16 @@
      * @category Components
      */
     class SoundComponentElement extends ComponentElement {
+        _distanceModel = 'linear';
+        _maxDistance = 10000;
+        _pitch = 1;
+        _positional = false;
+        _refDistance = 1;
+        _rollOffFactor = 1;
+        _volume = 1;
         /** @ignore */
         constructor() {
             super('sound');
-            this._distanceModel = 'linear';
-            this._maxDistance = 10000;
-            this._pitch = 1;
-            this._positional = false;
-            this._refDistance = 1;
-            this._rollOffFactor = 1;
-            this._volume = 1;
         }
         getInitialComponentData() {
             return {
@@ -6666,25 +9010,37 @@
      * methods of the {@link AsyncElement} interface.
      */
     class SoundSlotElement extends AsyncElement {
-        constructor() {
-            super(...arguments);
-            this._asset = '';
-            this._autoPlay = false;
-            this._duration = null;
-            this._loop = false;
-            this._name = '';
-            this._overlap = false;
-            this._pitch = 1;
-            this._startTime = 0;
-            this._volume = 1;
-            /**
-             * The sound slot.
-             */
-            this.soundSlot = null;
-        }
+        _asset = '';
+        _autoPlay = false;
+        _duration = null;
+        _loop = false;
+        _name = '';
+        _overlap = false;
+        _pitch = 1;
+        _startTime = 0;
+        _volume = 1;
+        /**
+         * The `<pc-sounds>` this slot was added to, captured at connect time.
+         *
+         * `disconnectedCallback` cannot rediscover it: by the time the element is disconnected its
+         * `parentElement` is already `null`, so a lookup would both fail to find the component and
+         * emit a misleading "must be a direct child" warning for what is an ordinary removal.
+         */
+        _soundElement = null;
+        /**
+         * The sound slot.
+         */
+        soundSlot = null;
         async connectedCallback() {
-            var _a;
-            await ((_a = this.soundElement) === null || _a === void 0 ? void 0 : _a.ready());
+            const soundElement = this.soundElement;
+            await soundElement?.ready();
+            // The element may have been removed, or its parent torn down, while we were waiting. A
+            // <pc-app> disconnects before its children, so by the time we resume the component can
+            // already be gone - see the matching guard in disconnectedCallback below.
+            const component = soundElement?.component;
+            if (!this.isConnected || !component) {
+                return;
+            }
             const options = {
                 autoPlay: this._autoPlay,
                 loop: this._loop,
@@ -6696,7 +9052,8 @@
             if (this._duration) {
                 options.duration = this._duration;
             }
-            this.soundSlot = this.soundElement.component.addSlot(this._name, options);
+            this._soundElement = soundElement;
+            this.soundSlot = component.addSlot(this._name, options);
             this.asset = this._asset;
             if (this._autoPlay) {
                 this.soundSlot.play();
@@ -6704,10 +9061,12 @@
             this._onReady();
         }
         disconnectedCallback() {
-            var _a, _b;
-            // The component is null if the parent <pc-sound> (or the whole <pc-app>) is being
-            // torn down — parents disconnect first and have already removed the component.
-            (_b = (_a = this.soundElement) === null || _a === void 0 ? void 0 : _a.component) === null || _b === void 0 ? void 0 : _b.removeSlot(this._name);
+            // Uses the cached parent rather than a fresh lookup, since parentElement is already null
+            // by now. The component itself is null if the parent <pc-sound> (or the whole <pc-app>) is
+            // being torn down — parents disconnect first and have already removed the component.
+            this._soundElement?.component?.removeSlot(this._name);
+            this._soundElement = null;
+            this.soundSlot = null;
         }
         get soundElement() {
             const soundElement = this.parentElement;
@@ -6722,10 +9081,9 @@
          * @param value - The asset.
          */
         set asset(value) {
-            var _a;
             this._asset = value;
             if (this.soundSlot) {
-                const id = (_a = AssetElement.get(value)) === null || _a === void 0 ? void 0 : _a.id;
+                const id = AssetElement.get(value)?.id;
                 if (id) {
                     this.soundSlot.asset = id;
                 }
@@ -6880,7 +9238,7 @@
         attributeChangedCallback(name, _oldValue, newValue) {
             switch (name) {
                 case 'asset':
-                    this.asset = newValue;
+                    this.asset = newValue ?? '';
                     break;
                 case 'auto-play':
                     this.autoPlay = parseBool(newValue, false);
@@ -6892,7 +9250,7 @@
                     this.loop = parseBool(newValue, false);
                     break;
                 case 'name':
-                    this.name = newValue;
+                    this.name = newValue ?? '';
                     break;
                 case 'overlap':
                     this.overlap = parseBool(newValue, false);
@@ -6920,15 +9278,15 @@
      * @category Components
      */
     class GSplatComponentElement extends ComponentElement {
+        _asset = '';
+        _castShadows = false;
+        _lodBaseDistance = 5;
+        _lodMultiplier = 3;
+        _lodRangeMin = 0;
+        _lodRangeMax = 99;
         /** @ignore */
         constructor() {
             super('gsplat');
-            this._asset = '';
-            this._castShadows = false;
-            this._lodBaseDistance = 5;
-            this._lodMultiplier = 3;
-            this._lodRangeMin = 0;
-            this._lodRangeMax = 99;
         }
         getInitialComponentData() {
             return {
@@ -7077,7 +9435,7 @@
             super.attributeChangedCallback(name, _oldValue, newValue);
             switch (name) {
                 case 'asset':
-                    this.asset = newValue;
+                    this.asset = newValue ?? '';
                     break;
                 case 'cast-shadows':
                     this.castShadows = parseBool(newValue, false);
@@ -7106,11 +9464,8 @@
      * {@link HTMLElement} interface.
      */
     class ModelElement extends AsyncElement {
-        constructor() {
-            super(...arguments);
-            this._asset = '';
-            this._entity = null;
-        }
+        _asset = '';
+        _entity = null;
         connectedCallback() {
             this._loadModel();
             this._onReady();
@@ -7142,10 +9497,9 @@
             }
         }
         async _loadModel() {
-            var _a;
             this._unloadModel();
-            const appElement = await ((_a = this.closestApp) === null || _a === void 0 ? void 0 : _a.ready());
-            const app = appElement === null || appElement === void 0 ? void 0 : appElement.app;
+            const appElement = await this.closestApp?.ready();
+            const app = appElement?.app;
             const asset = AssetElement.get(this._asset);
             if (!asset) {
                 return;
@@ -7161,8 +9515,7 @@
             }
         }
         _unloadModel() {
-            var _a;
-            (_a = this._entity) === null || _a === void 0 ? void 0 : _a.destroy();
+            this._entity?.destroy();
             this._entity = null;
         }
         /**
@@ -7188,7 +9541,7 @@
         attributeChangedCallback(name, _oldValue, newValue) {
             switch (name) {
                 case 'asset':
-                    this.asset = newValue;
+                    this.asset = newValue ?? '';
                     break;
             }
         }
@@ -7202,60 +9555,84 @@
      * {@link HTMLElement} interface.
      */
     class SceneElement extends AsyncElement {
-        constructor() {
-            super(...arguments);
-            /**
-             * The fog type of the scene.
-             */
-            this._fog = 'none';
-            /**
-             * The color of the fog.
-             */
-            this._fogColor = new playcanvas.Color(1, 1, 1);
-            /**
-             * The density of the fog.
-             */
-            this._fogDensity = 0;
-            /**
-             * The start distance of the fog.
-             */
-            this._fogStart = 0;
-            /**
-             * The end distance of the fog.
-             */
-            this._fogEnd = 1000;
-            /**
-             * The gravity of the scene.
-             */
-            this._gravity = new playcanvas.Vec3(0, -9.81, 0);
-            this._scene = null;
-        }
         /**
-         * The PlayCanvas scene instance. Available once the element is ready — await
+         * The fog type of the scene.
+         */
+        _fog = 'none';
+        /**
+         * The color of the fog.
+         */
+        _fogColor = new playcanvas.Color(1, 1, 1);
+        /**
+         * The density of the fog.
+         */
+        _fogDensity = 0;
+        /**
+         * The start distance of the fog.
+         */
+        _fogStart = 0;
+        /**
+         * The end distance of the fog.
+         */
+        _fogEnd = 1000;
+        /**
+         * The gravity of the scene.
+         */
+        _gravity = new playcanvas.Vec3(0, -9.81, 0);
+        _scene = null;
+        /**
+         * 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() {
-            var _a;
-            await ((_a = this.closestApp) === null || _a === void 0 ? void 0 : _a.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`.
@@ -7348,9 +9725,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);
             }
         }
         /**
@@ -7395,19 +9771,16 @@
      * methods of the {@link HTMLElement} interface.
      */
     class SkyElement extends AsyncElement {
-        constructor() {
-            super(...arguments);
-            this._asset = '';
-            this._center = new playcanvas.Vec3(0, 0.01, 0);
-            this._intensity = 1;
-            this._rotation = new playcanvas.Vec3();
-            this._level = 0;
-            this._lighting = false;
-            this._scale = new playcanvas.Vec3(100, 100, 100);
-            this._type = 'infinite';
-            this._scene = null;
-            this._appElement = null;
-        }
+        _asset = '';
+        _center = new playcanvas.Vec3(0, 0.01, 0);
+        _intensity = 1;
+        _rotation = new playcanvas.Vec3();
+        _level = 0;
+        _lighting = false;
+        _scale = new playcanvas.Vec3(100, 100, 100);
+        _type = 'infinite';
+        _scene = null;
+        _appElement = null;
         connectedCallback() {
             this._loadSkybox();
             this._onReady();
@@ -7439,9 +9812,8 @@
             this._scene.skyboxMip = this._level;
         }
         async _loadSkybox() {
-            var _a;
-            const appElement = await ((_a = this.closestApp) === null || _a === void 0 ? void 0 : _a.ready());
-            const app = appElement === null || appElement === void 0 ? void 0 : appElement.app;
+            const appElement = await this.closestApp?.ready();
+            const app = appElement?.app;
             if (!appElement || !app) {
                 return;
             }
@@ -7462,7 +9834,6 @@
             }
         }
         _unloadSkybox() {
-            var _a, _b, _c;
             const scene = this._scene;
             if (!scene)
                 return;
@@ -7470,12 +9841,12 @@
             // If the owning application has already been destroyed (removing a <pc-app>
             // disconnects it before its children), the scene, graphics device and skybox
             // textures have all been destroyed along with it — nothing left to clean up.
-            if (!((_a = this._appElement) === null || _a === void 0 ? void 0 : _a.app))
+            if (!this._appElement?.app)
                 return;
-            (_b = scene.skybox) === null || _b === void 0 ? void 0 : _b.destroy();
+            scene.skybox?.destroy();
             // @ts-ignore
             scene.skybox = null;
-            (_c = scene.envAtlas) === null || _c === void 0 ? void 0 : _c.destroy();
+            scene.envAtlas?.destroy();
             // @ts-ignore
             scene.envAtlas = null;
         }
@@ -7622,7 +9993,7 @@
         attributeChangedCallback(name, _oldValue, newValue) {
             switch (name) {
                 case 'asset':
-                    this.asset = newValue;
+                    this.asset = newValue ?? '';
                     break;
                 case 'center':
                     this.center = parseVec3(newValue, new playcanvas.Vec3(0, 0.01, 0), name);