@playcanvas/web-components 0.11.1 → 0.12.0

package/dist/pwc.js

@@ -31,12 +31,13 @@
             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`.
+         * The nearest ancestor element that fronts an entity — `<pc-entity>` or `<pc-node>` — or
+         * `null` if this element has no such ancestor. The search starts at the parent, so an element
+         * never resolves to itself.
+         * @returns The closest entity-fronting element, or `null`.
          */
         get closestEntity() {
-            return this.parentElement?.closest('pc-entity') ?? null;
+            return this.parentElement?.closest('pc-entity, pc-node') ?? null;
         }
         /**
          * Called when the element is fully initialized and ready. Subclasses should call this when
@@ -746,8 +747,9 @@
         _bootGeneration = 0;
         /**
          * The elements backing this application's entities, keyed by the entity itself. Registered
-         * by EntityElement at creation and removed when an entity is destroyed, this joins engine
-         * scene nodes back to their owning elements by identity - never by name.
+         * by EntityElement at creation (and NodeElement at binding) and removed when an entity is
+         * destroyed or unbound, this joins engine scene nodes back to their owning elements by
+         * identity - never by name.
          */
         _entityElements = new Map();
         _picker = null;
@@ -1052,7 +1054,7 @@
             // created from onpointer* attributes when their elements were first upgraded, or
             // listeners carried over from before a re-boot)
             pointerEventTypes.forEach((type) => {
-                const anyListeners = Array.from(this.querySelectorAll('pc-entity')).some((entity) => entity._hasListeners(type));
+                const anyListeners = Array.from(this.querySelectorAll('pc-entity, pc-node')).some((entity) => entity._hasListeners(type));
                 if (anyListeners) {
                     this._onPointerListenerAdded(type);
                 }
@@ -1082,11 +1084,11 @@
             };
         }
         /**
-         * Registers the element that created an entity. Called by EntityElement when it creates its
-         * entity.
+         * Registers the element that fronts an entity. Called by EntityElement when it creates its
+         * entity, and by NodeElement when it binds one.
          *
          * @param entity - The entity.
-         * @param element - The element that created it.
+         * @param element - The element that fronts it.
          * @internal
          */
         _registerEntityElement(entity, element) {
@@ -1102,21 +1104,22 @@
             this._entityElements.delete(entity);
         }
         /**
-         * Returns the `<pc-entity>` element whose backing entity is `entity`, or `null` if the
-         * entity was not created by an element of this application - for example, a node inside a
-         * model's instantiated hierarchy, or an entity created through the engine API.
+         * Returns the `<pc-entity>` or `<pc-node>` element whose backing entity is `entity`, or
+         * `null` if the entity is not fronted by an element of this application - for example, an
+         * unbound node inside a model's instantiated hierarchy, or an entity created through the
+         * engine API.
          *
          * @param entity - The entity to look up.
-         * @returns The element backing the entity, or `null`.
+         * @returns The element fronting the entity, or `null`.
          */
         elementFromEntity(entity) {
             return this._entityElements.get(entity) ?? null;
         }
         /**
          * Resolves the element that owns a picked node: the nearest node up the parent chain -
-         * starting with the node itself - that was created by a `<pc-entity>` of this application.
-         * A hit inside a model's instantiated hierarchy therefore resolves to the element hosting
-         * the model.
+         * starting with the node itself - that is fronted by a `<pc-entity>` or `<pc-node>` of this
+         * application. A hit inside a model's instantiated hierarchy therefore resolves to the
+         * nearest bound `<pc-node>`, or failing that the element hosting the model.
          *
          * @param node - The picked node, or `null`.
          * @returns The owning element, or `null`.
@@ -1248,7 +1251,7 @@
             }
         }
         _onPointerListenerRemoved(type) {
-            const hasListeners = Array.from(this.querySelectorAll('pc-entity')).some((entity) => entity._hasListeners(type));
+            const hasListeners = Array.from(this.querySelectorAll('pc-entity, pc-node')).some((entity) => entity._hasListeners(type));
             if (!hasListeners && this._canvas) {
                 this._hasPointerListeners[type] = false;
                 const handler = type === 'pointerenter' || type === 'pointerleave'
@@ -1426,6 +1429,125 @@
     }
     customElements.define('pc-app', AppElement);
 
+    /**
+     * The attribute names of the inline `onpointer*` event handlers, shared by every element that
+     * fronts an engine entity. Spread into `observedAttributes` by subclasses.
+     * @ignore
+     */
+    const POINTER_ATTRIBUTES = [
+        'onpointerenter',
+        'onpointerleave',
+        'onpointerdown',
+        'onpointerup',
+        'onpointermove'
+    ];
+    /**
+     * The base class for elements that front an engine {@link Entity}: `<pc-entity>`, which creates
+     * one, and `<pc-node>`, which binds to one inside a model's instantiated hierarchy. It carries
+     * what both need — the `entity` contract, registration with the owning application (which joins
+     * picked scene nodes back to elements by identity, never by name), and the pointer listener
+     * bookkeeping that lets the application lazily attach its canvas handlers.
+     */
+    class EntityBaseElement extends AsyncElement {
+        _entity = null;
+        /**
+         * The application element this entity is registered with, cached at registration time so the
+         * entity can be unregistered even once this element has left the DOM.
+         */
+        _appElement = null;
+        /**
+         * The pointer event listeners for the entity.
+         */
+        _listeners = {};
+        /**
+         * The event types for which an inline `onpointer*` attribute is currently present.
+         */
+        _inlineHandlerTypes = new Set();
+        /**
+         * The PlayCanvas entity instance. `null` until the element is ready, and again once the
+         * entity is gone — await {@link whenReady} or the element's `ready()` promise before
+         * accessing it.
+         * @returns The entity instance, or `null`.
+         */
+        get entity() {
+            return this._entity;
+        }
+        /**
+         * Registers `entity` as this element's backing entity with the owning application, which
+         * joins engine nodes back to elements by identity (never by name).
+         *
+         * @param entity - The entity to register.
+         */
+        _registerEntity(entity) {
+            this._appElement = this.closestApp;
+            this._appElement?._registerEntityElement(entity, this);
+        }
+        /**
+         * Removes the registration for `entity`.
+         *
+         * @param entity - The entity to unregister.
+         */
+        _unregisterEntity(entity) {
+            this._appElement?._unregisterEntityElement(entity);
+            this._appElement = null;
+        }
+        /**
+         * Tracks whether an inline `onpointer*` attribute is present. The browser itself compiles and
+         * runs these attributes — they are standard `GlobalEventHandlers`, so setting one replaces
+         * the previous handler and removing it removes the handler, exactly like `onclick` on any
+         * HTML element. But because they bypass {@link addEventListener}, the connect/disconnect
+         * bookkeeping that lets the application lazily attach its canvas pointer handlers must be
+         * kept in sync here.
+         *
+         * @param name - The attribute name (e.g. 'onpointerdown').
+         * @param value - The attribute value, or `null` when the attribute has been removed.
+         */
+        _updateInlineHandler(name, value) {
+            const type = name.substring(2);
+            const had = this._inlineHandlerTypes.has(type);
+            const has = value !== null;
+            if (has && !had) {
+                this._inlineHandlerTypes.add(type);
+                this.dispatchEvent(new CustomEvent(`${type}:connect`, { bubbles: true }));
+            }
+            else if (!has && had) {
+                this._inlineHandlerTypes.delete(type);
+                this.dispatchEvent(new CustomEvent(`${type}:disconnect`, { bubbles: true }));
+            }
+        }
+        addEventListener(type, listener, options) {
+            if (!this._listeners[type]) {
+                this._listeners[type] = [];
+            }
+            this._listeners[type].push(listener);
+            super.addEventListener(type, listener, options);
+            if (type.startsWith('pointer')) {
+                this.dispatchEvent(new CustomEvent(`${type}:connect`, { bubbles: true }));
+            }
+        }
+        removeEventListener(type, listener, options) {
+            if (this._listeners[type]) {
+                this._listeners[type] = this._listeners[type].filter((l) => l !== listener);
+            }
+            super.removeEventListener(type, listener, options);
+            if (type.startsWith('pointer')) {
+                this.dispatchEvent(new CustomEvent(`${type}:disconnect`, { bubbles: true }));
+            }
+        }
+        /**
+         * Whether the element has a listener for an event type, registered either with
+         * {@link addEventListener} or with the matching inline `onpointer*` attribute. Read by the
+         * containing `<pc-app>` element to gate pointer event synthesis.
+         *
+         * @param type - The event type.
+         * @returns Whether a listener is registered.
+         * @internal
+         */
+        _hasListeners(type) {
+            return Boolean(this._listeners[type]?.length) || this._inlineHandlerTypes.has(type);
+        }
+    }
+
     /**
      * The EntityElement interface provides properties and methods for manipulating
      * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-entity/ | `<pc-entity>`} elements.
@@ -1450,7 +1572,7 @@
      * @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 {
+    class EntityElement extends EntityBaseElement {
         /**
          * Whether the entity is enabled.
          */
@@ -1475,33 +1597,10 @@
          * 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 application element this entity is registered with, cached at creation time so the
-         * entity can be unregistered even once this element has left the DOM.
-         */
-        _appElement = null;
-        /**
-         * The PlayCanvas entity instance. `null` until the element is ready, and again once it has
-         * been removed from the document — await {@link whenReady} or the element's `ready()`
-         * promise before accessing it.
-         * @returns The entity instance, or `null`.
-         */
-        get entity() {
-            return this._entity;
-        }
         /**
          * Creates the backing entity. Called by the containing `<pc-app>` element during its boot
          * sweep, and on connection for elements inserted while the application is already running.
@@ -1529,13 +1628,11 @@
             if (this._tags.length > 0) {
                 entity.tags.add(this._tags);
             }
-            // Register with the owning application, which joins engine nodes back to elements by
-            // identity (never by name), and hook the entity's destruction. The engine fires 'destroy'
-            // for every entity in a destroyed subtree, so the element learns of its entity's death no
-            // matter who causes it: this element, an ancestor, the whole application, or a user
-            // script calling entity.destroy().
-            this._appElement = this.closestApp;
-            this._appElement?._registerEntityElement(entity, this);
+            // Register with the owning application and hook the entity's destruction. The engine
+            // fires 'destroy' for every entity in a destroyed subtree, so the element learns of its
+            // entity's death no matter who causes it: this element, an ancestor, the whole
+            // application, or a user script calling entity.destroy().
+            this._registerEntity(entity);
             entity.once('destroy', this._onEntityDestroy, this);
         }
         /**
@@ -1548,17 +1645,16 @@
          * @param entity - The entity that was destroyed.
          */
         _onEntityDestroy(entity) {
-            this._appElement?._unregisterEntityElement(entity);
-            this._appElement = null;
+            this._unregisterEntity(entity);
             this._entity = null;
             this._built = false;
             this._resetReady();
         }
         /**
-         * Parents the backing entity: under the entity of the nearest ancestor `<pc-entity>` when
-         * there is one, and under the application root otherwise. Called by the containing `<pc-app>`
-         * element once a sweep has created every entity, so a parent's existence never depends on
-         * document order.
+         * Parents the backing entity: under the entity of the nearest ancestor `<pc-entity>` or
+         * `<pc-node>` when there is one, and under the application root otherwise. Called by the
+         * containing `<pc-app>` element once a sweep has created every entity, so a parent's
+         * existence never depends on document order.
          *
          * @param app - The application whose root adopts parentless entities.
          * @internal
@@ -1566,8 +1662,14 @@
         _buildHierarchy(app) {
             if (!this.entity || this._built)
                 return;
-            this._built = true;
             const closestEntity = this.closestEntity;
+            // A host element without an entity is an unresolved `<pc-node>`: building now would
+            // mis-anchor this entity to the application root while the host is still resolving.
+            // Stay unbuilt - the host drives this subtree itself once it binds.
+            if (closestEntity && !closestEntity.entity) {
+                return;
+            }
+            this._built = true;
             if (closestEntity?.entity) {
                 closestEntity.entity.addChild(this.entity);
             }
@@ -1713,44 +1815,8 @@
         get tags() {
             return this._tags;
         }
-        /**
-         * Tracks whether an inline `onpointer*` attribute is present. The browser itself compiles and
-         * runs these attributes — they are standard `GlobalEventHandlers`, so setting one replaces
-         * the previous handler and removing it removes the handler, exactly like `onclick` on any
-         * HTML element. But because they bypass {@link addEventListener}, the connect/disconnect
-         * bookkeeping that lets the application lazily attach its canvas pointer handlers must be
-         * kept in sync here.
-         *
-         * @param name - The attribute name (e.g. 'onpointerdown').
-         * @param value - The attribute value, or `null` when the attribute has been removed.
-         */
-        _updateInlineHandler(name, value) {
-            const type = name.substring(2);
-            const had = this._inlineHandlerTypes.has(type);
-            const has = value !== null;
-            if (has && !had) {
-                this._inlineHandlerTypes.add(type);
-                this.dispatchEvent(new CustomEvent(`${type}:connect`, { bubbles: true }));
-            }
-            else if (!has && had) {
-                this._inlineHandlerTypes.delete(type);
-                this.dispatchEvent(new CustomEvent(`${type}:disconnect`, { bubbles: true }));
-            }
-        }
         static get observedAttributes() {
-            return [
-                'enabled',
-                'name',
-                'position',
-                'rotation',
-                'scale',
-                'tags',
-                'onpointerenter',
-                'onpointerleave',
-                'onpointerdown',
-                'onpointerup',
-                'onpointermove'
-            ];
+            return ['enabled', 'name', 'position', 'rotation', 'scale', 'tags', ...POINTER_ATTRIBUTES];
         }
         attributeChangedCallback(name, _oldValue, newValue) {
             switch (name) {
@@ -1781,37 +1847,6 @@
                     break;
             }
         }
-        addEventListener(type, listener, options) {
-            if (!this._listeners[type]) {
-                this._listeners[type] = [];
-            }
-            this._listeners[type].push(listener);
-            super.addEventListener(type, listener, options);
-            if (type.startsWith('pointer')) {
-                this.dispatchEvent(new CustomEvent(`${type}:connect`, { bubbles: true }));
-            }
-        }
-        removeEventListener(type, listener, options) {
-            if (this._listeners[type]) {
-                this._listeners[type] = this._listeners[type].filter((l) => l !== listener);
-            }
-            super.removeEventListener(type, listener, options);
-            if (type.startsWith('pointer')) {
-                this.dispatchEvent(new CustomEvent(`${type}:disconnect`, { bubbles: true }));
-            }
-        }
-        /**
-         * Whether the element has a listener for an event type, registered either with
-         * {@link addEventListener} or with the matching inline `onpointer*` attribute. Read by the
-         * containing `<pc-app>` element to gate pointer event synthesis.
-         *
-         * @param type - The event type.
-         * @returns Whether a listener is registered.
-         * @internal
-         */
-        _hasListeners(type) {
-            return Boolean(this._listeners[type]?.length) || this._inlineHandlerTypes.has(type);
-        }
     }
     customElements.define('pc-entity', EntityElement);
 
@@ -1996,6 +2031,48 @@
         ['sliced', playcanvas.SPRITE_RENDERMODE_SLICED],
         ['tiled', playcanvas.SPRITE_RENDERMODE_TILED]
     ]);
+    const addressModes = new Map([
+        ['repeat', playcanvas.ADDRESS_REPEAT],
+        ['clamp', playcanvas.ADDRESS_CLAMP_TO_EDGE],
+        ['mirror', playcanvas.ADDRESS_MIRRORED_REPEAT]
+    ]);
+    const minFilterModes = new Map([
+        ['nearest', playcanvas.FILTER_NEAREST],
+        ['linear', playcanvas.FILTER_LINEAR],
+        ['nearest-mip-nearest', playcanvas.FILTER_NEAREST_MIPMAP_NEAREST],
+        ['linear-mip-nearest', playcanvas.FILTER_LINEAR_MIPMAP_NEAREST],
+        ['nearest-mip-linear', playcanvas.FILTER_NEAREST_MIPMAP_LINEAR],
+        ['linear-mip-linear', playcanvas.FILTER_LINEAR_MIPMAP_LINEAR]
+    ]);
+    const magFilterModes = new Map([
+        ['nearest', playcanvas.FILTER_NEAREST],
+        ['linear', playcanvas.FILTER_LINEAR]
+    ]);
+    // The engine's texture JSON spells the filter names with underscores ('linear_mip_linear'); the
+    // attribute values are kebab-case like every other enum attribute in this library. The address
+    // mode names contain no dashes, so for them the rename is the identity.
+    const toTextureJson = (name) => name.replace(/-/g, '_');
+    // Engine Texture constructor defaults, restored on a loaded texture when a texture option
+    // attribute is removed.
+    const textureOptionDefaults = {
+        addressU: playcanvas.ADDRESS_REPEAT,
+        addressV: playcanvas.ADDRESS_REPEAT,
+        anisotropy: 1,
+        flipY: false,
+        magFilter: playcanvas.FILTER_LINEAR,
+        minFilter: playcanvas.FILTER_LINEAR_MIPMAP_LINEAR,
+        mipmaps: true,
+        srgb: false
+    };
+    // Attributes that only apply to certain asset types, used to warn when one is set on an asset of
+    // any other type (where it would otherwise be silently ignored).
+    const typeScopedAttributes = [
+        [
+            ['address-u', 'address-v', 'anisotropy', 'flip-y', 'mag-filter', 'min-filter', 'mipmaps', 'srgb'],
+            ['texture', 'textureatlas']
+        ],
+        [['atlas', 'frame-keys', 'pixels-per-unit', 'render-mode'], ['sprite']]
+    ];
     const extToType = new Map([
         ['bin', 'binary'],
         ['css', 'css'],
@@ -2052,8 +2129,16 @@
      * 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.
+     * For `texture` and `textureatlas` assets, the texture options (`address-u`, `address-v`,
+     * `min-filter`, `mag-filter`, `anisotropy`, `mipmaps`, `srgb`, `flip-y`) apply when the texture is
+     * created and — like `lazy` — are observed: changing one updates a texture that has already
+     * loaded, and removing one restores the engine default. Changing `srgb` or `mipmaps` on a loaded
+     * texture recreates the underlying GPU resource, so prefer declaring those up front. Each option
+     * overrides the matching key in the `data` JSON; options left unset write nothing, leaving the
+     * engine's per-format defaults in force.
+     *
+     * Apart from `lazy` and the texture options, 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.
@@ -2075,7 +2160,15 @@
      * not that it succeeded.
      */
     class AssetElement extends AsyncElement {
+        _addressU = null;
+        _addressV = null;
+        _anisotropy = null;
+        _flipY = null;
         _lazy = false;
+        _magFilter = null;
+        _minFilter = null;
+        _mipmaps = null;
+        _srgb = null;
         /**
          * The asset that is loaded. Available once the element is ready — await
          * {@link whenReady} or the element's `ready()` promise before accessing it.
@@ -2146,6 +2239,15 @@
                 console.warn(`Unsupported asset type: ${src}`);
                 return;
             }
+            // Attributes scoped to other asset types have no effect here - say so rather than
+            // failing silently.
+            const inapplicable = typeScopedAttributes
+                .filter(([, types]) => !types.includes(type))
+                .flatMap(([attributes]) => attributes)
+                .filter((attribute) => this.hasAttribute(attribute));
+            if (inapplicable.length > 0) {
+                console.warn(`pc-asset '${id || src}' has attributes that do not apply to asset type '${type}' and are ignored: ${inapplicable.join(', ')}`);
+            }
             // Optional inline asset data, used by data-driven assets such as texture atlases (frame
             // definitions) and sprites (atlas reference, frame keys, etc.).
             const data = this._buildData(type);
@@ -2173,9 +2275,11 @@
             this.asset.on('error', this._onAssetError, this);
         }
         /**
-         * Builds the `data` object for the asset from an optional inline `data` attribute (JSON) and,
-         * for sprites, from the convenience attributes (`atlas`, `frame-keys`, `pixels-per-unit`,
-         * `render-mode`). Returns `undefined` when there is no data to apply.
+         * Builds the `data` object for the asset from an optional inline `data` attribute (JSON), the
+         * texture option attributes (for `texture` and `textureatlas` assets), and the sprite
+         * convenience attributes (`atlas`, `frame-keys`, `pixels-per-unit`, `render-mode`). An
+         * attribute overrides the matching `data` JSON key. Returns `undefined` when there is no data
+         * to apply.
          * @param type - The resolved asset type.
          * @returns The asset data, or `undefined`.
          */
@@ -2190,6 +2294,37 @@
                     console.warn(`Invalid 'data' JSON on pc-asset: ${dataAttr}`);
                 }
             }
+            if (type === 'texture' || type === 'textureatlas') {
+                data = data ?? {};
+                // Only options the user actually set are written: the engine reads these keys with
+                // hasOwnProperty semantics, and an absent key leaves its per-format default (an HDR's
+                // 'rgbe' type, a KTX2's transcoded format) in force.
+                if (this._addressU !== null) {
+                    data.addressu = this._addressU;
+                }
+                if (this._addressV !== null) {
+                    data.addressv = this._addressV;
+                }
+                if (this._anisotropy !== null) {
+                    data.anisotropy = this._anisotropy;
+                }
+                if (this._flipY !== null) {
+                    // 'flipY' is the one camelCase key in the engine's texture JSON
+                    data.flipY = this._flipY;
+                }
+                if (this._magFilter !== null) {
+                    data.magfilter = toTextureJson(this._magFilter);
+                }
+                if (this._minFilter !== null) {
+                    data.minfilter = toTextureJson(this._minFilter);
+                }
+                if (this._mipmaps !== null) {
+                    data.mipmaps = this._mipmaps;
+                }
+                if (this._srgb !== null) {
+                    data.srgb = this._srgb;
+                }
+            }
             if (type === 'sprite') {
                 data = data ?? {};
                 // Resolve the referenced texture atlas to its (numeric) asset id. The atlas must be
@@ -2223,6 +2358,56 @@
             }
             return data;
         }
+        /**
+         * Returns the engine texture behind this asset, when there is one: the resource itself for a
+         * `texture` asset, the atlas's texture for a `textureatlas` asset, `null` otherwise
+         * (including before the asset has loaded).
+         * @returns The texture, or `null`.
+         */
+        _texture() {
+            const asset = this.asset;
+            if (!asset?.resource)
+                return null;
+            if (asset.type === 'texture')
+                return asset.resource;
+            if (asset.type === 'textureatlas')
+                return asset.resource.texture ?? null;
+            return null;
+        }
+        /**
+         * Writes one texture option through to the created asset, if any. The engine-JSON key is
+         * written into `asset.data`, mutated in place - replacing the whole object would make the
+         * registry re-patch every key, and a re-patched `srgb` or `mipmaps` recreates the texture
+         * even when unchanged. The in-place key is what a not-yet-started load reads at texture
+         * construction, and what any later reload reads. When the texture already exists, the
+         * corresponding property is assigned directly; `null` (attribute removed) deletes the key
+         * and restores the engine default. Assets of any other type are left untouched.
+         *
+         * @param key - The engine texture JSON key in `asset.data`.
+         * @param property - The Texture property to assign.
+         * @param dataValue - The engine-JSON value for `asset.data`, or `null` to delete the key.
+         * @param textureValue - The value for the Texture property, or `null` for the engine default.
+         */
+        _applyTextureOption(key, property, dataValue, textureValue) {
+            const asset = this.asset;
+            if (!asset || (asset.type !== 'texture' && asset.type !== 'textureatlas'))
+                return;
+            const data = asset.data;
+            if (dataValue === null) {
+                delete data[key];
+            }
+            else {
+                data[key] = dataValue;
+            }
+            const texture = this._texture();
+            if (texture) {
+                // Every option here is a number- or boolean-valued Texture property; the
+                // value/property pairing is fixed by the callers, which TypeScript cannot see
+                // through the union.
+                texture[property] =
+                    textureValue ?? textureOptionDefaults[property];
+            }
+        }
         _destroyAsset() {
             if (this.asset) {
                 // A caller that keeps the Asset alive must not dispatch on a removed element
@@ -2234,6 +2419,75 @@
                 this.asset = null;
             }
         }
+        /**
+         * Sets the texture's horizontal (U) address mode: how texture coordinates outside the 0 to 1
+         * range sample the texture. Applies to `texture` and `textureatlas` assets, both when the
+         * texture is created and after it has loaded.
+         * @param value - The address mode, or `null` to use the engine default of 'repeat'.
+         */
+        set addressU(value) {
+            this._addressU = value;
+            const constant = value === null ? null : (addressModes.get(value) ?? playcanvas.ADDRESS_REPEAT);
+            this._applyTextureOption('addressu', 'addressU', value, constant);
+        }
+        /**
+         * Gets the texture's horizontal (U) address mode.
+         * @returns The address mode, or `null` when unset.
+         */
+        get addressU() {
+            return this._addressU;
+        }
+        /**
+         * Sets the texture's vertical (V) address mode: how texture coordinates outside the 0 to 1
+         * range sample the texture. Applies to `texture` and `textureatlas` assets, both when the
+         * texture is created and after it has loaded.
+         * @param value - The address mode, or `null` to use the engine default of 'repeat'.
+         */
+        set addressV(value) {
+            this._addressV = value;
+            const constant = value === null ? null : (addressModes.get(value) ?? playcanvas.ADDRESS_REPEAT);
+            this._applyTextureOption('addressv', 'addressV', value, constant);
+        }
+        /**
+         * Gets the texture's vertical (V) address mode.
+         * @returns The address mode, or `null` when unset.
+         */
+        get addressV() {
+            return this._addressV;
+        }
+        /**
+         * Sets the texture's maximum anisotropic filtering level, which improves quality at oblique
+         * viewing angles. Applies to `texture` and `textureatlas` assets, both when the texture is
+         * created and after it has loaded.
+         * @param value - The anisotropy level, or `null` to use the engine default of 1.
+         */
+        set anisotropy(value) {
+            this._anisotropy = value;
+            this._applyTextureOption('anisotropy', 'anisotropy', value, value);
+        }
+        /**
+         * Gets the texture's maximum anisotropic filtering level.
+         * @returns The anisotropy level, or `null` when unset.
+         */
+        get anisotropy() {
+            return this._anisotropy;
+        }
+        /**
+         * Sets whether the texture's image data is flipped vertically at upload. Applies to `texture`
+         * and `textureatlas` assets, both when the texture is created and after it has loaded.
+         * @param value - The flip flag, or `null` to use the engine default of `false`.
+         */
+        set flipY(value) {
+            this._flipY = value;
+            this._applyTextureOption('flipY', 'flipY', value, value);
+        }
+        /**
+         * Gets whether the texture's image data is flipped vertically at upload.
+         * @returns The flip flag, or `null` when unset.
+         */
+        get flipY() {
+            return this._flipY;
+        }
         /**
          * Sets whether the asset should be loaded lazily.
          * @param value - The lazy loading flag.
@@ -2252,37 +2506,200 @@
             return this._lazy;
         }
         /**
-         * Returns the {@link Asset} created by the `<pc-asset>` element with the given `id`, or
-         * `undefined` if there is no such element or its asset has not been created yet.
-         *
-         * @param id - The `id` of the `<pc-asset>` element.
-         * @returns The asset, or `undefined`.
+         * Sets the texture's magnification filter, used when the texture is displayed larger than its
+         * source size. Applies to `texture` and `textureatlas` assets, both when the texture is
+         * created and after it has loaded.
+         * @param value - The filter, or `null` to use the engine default of 'linear'.
          */
-        static get(id) {
-            const assetElement = document.querySelector(`pc-asset[id="${id}"]`);
-            return assetElement?.asset;
+        set magFilter(value) {
+            this._magFilter = value;
+            const json = value === null ? null : toTextureJson(value);
+            const constant = value === null ? null : (magFilterModes.get(value) ?? playcanvas.FILTER_LINEAR);
+            this._applyTextureOption('magfilter', 'magFilter', json, constant);
         }
-        static get observedAttributes() {
-            return ['lazy'];
+        /**
+         * Gets the texture's magnification filter.
+         * @returns The filter, or `null` when unset.
+         */
+        get magFilter() {
+            return this._magFilter;
         }
-        attributeChangedCallback(name, _oldValue, newValue) {
-            if (name === 'lazy') {
-                this.lazy = parseBool(newValue, false);
-            }
+        /**
+         * Sets the texture's minification filter, used when the texture is displayed smaller than its
+         * source size. The mip variants blend within (and, for the second `linear`, between) mipmap
+         * levels. Applies to `texture` and `textureatlas` assets, both when the texture is created
+         * and after it has loaded.
+         * @param value - The filter, or `null` to use the engine default of 'linear-mip-linear'.
+         */
+        set minFilter(value) {
+            this._minFilter = value;
+            const json = value === null ? null : toTextureJson(value);
+            const constant = value === null ? null : (minFilterModes.get(value) ?? playcanvas.FILTER_LINEAR_MIPMAP_LINEAR);
+            this._applyTextureOption('minfilter', 'minFilter', json, constant);
         }
-    }
-    customElements.define('pc-asset', AssetElement);
-
-    /**
-     * Represents a component in the PlayCanvas engine.
-     *
-     * @category Components
-     */
+        /**
+         * Gets the texture's minification filter.
+         * @returns The filter, or `null` when unset.
+         */
+        get minFilter() {
+            return this._minFilter;
+        }
+        /**
+         * Sets whether the texture generates and uses mipmaps. Changing this on a loaded texture
+         * recreates the underlying GPU resource, so prefer declaring it up front. Applies to
+         * `texture` and `textureatlas` assets.
+         * @param value - The mipmaps flag, or `null` to use the engine default of `true`.
+         */
+        set mipmaps(value) {
+            this._mipmaps = value;
+            this._applyTextureOption('mipmaps', 'mipmaps', value, value);
+        }
+        /**
+         * Gets whether the texture generates and uses mipmaps.
+         * @returns The mipmaps flag, or `null` when unset.
+         */
+        get mipmaps() {
+            return this._mipmaps;
+        }
+        /**
+         * Sets whether the texture holds sRGB (gamma-encoded) color data, enabling hardware gamma
+         * decode. Free when set before the texture loads; changing it on a loaded texture recreates
+         * the underlying GPU resource. Applies to `texture` and `textureatlas` assets.
+         * @param value - The sRGB flag, or `null` to use the engine default of `false`.
+         */
+        set srgb(value) {
+            this._srgb = value;
+            this._applyTextureOption('srgb', 'srgb', value, value);
+        }
+        /**
+         * Gets whether the texture holds sRGB (gamma-encoded) color data.
+         * @returns The sRGB flag, or `null` when unset.
+         */
+        get srgb() {
+            return this._srgb;
+        }
+        /**
+         * Returns the {@link Asset} created by the `<pc-asset>` element with the given `id`, or
+         * `undefined` if there is no such element or its asset has not been created yet.
+         *
+         * @param id - The `id` of the `<pc-asset>` element.
+         * @returns The asset, or `undefined`.
+         */
+        static get(id) {
+            const assetElement = document.querySelector(`pc-asset[id="${id}"]`);
+            return assetElement?.asset;
+        }
+        static get observedAttributes() {
+            return [
+                'address-u',
+                'address-v',
+                'anisotropy',
+                'flip-y',
+                'lazy',
+                'mag-filter',
+                'min-filter',
+                'mipmaps',
+                'srgb'
+            ];
+        }
+        attributeChangedCallback(name, _oldValue, newValue) {
+            // Each texture option keeps its parse* call as the branch's first assignment (the CEM
+            // manifest derives the attribute's type and default from it - a ternary would degrade
+            // both to plain string) and treats a removed attribute (null) as a reset to unset,
+            // which restores the engine default on a loaded texture.
+            switch (name) {
+                case 'address-u':
+                    if (newValue !== null) {
+                        this.addressU = parseEnum(newValue, addressModes, 'repeat', name);
+                    }
+                    else {
+                        this.addressU = null;
+                    }
+                    break;
+                case 'address-v':
+                    if (newValue !== null) {
+                        this.addressV = parseEnum(newValue, addressModes, 'repeat', name);
+                    }
+                    else {
+                        this.addressV = null;
+                    }
+                    break;
+                case 'anisotropy':
+                    if (newValue !== null) {
+                        this.anisotropy = parseNumber(newValue, 1, name);
+                    }
+                    else {
+                        this.anisotropy = null;
+                    }
+                    break;
+                case 'flip-y':
+                    if (newValue !== null) {
+                        this.flipY = parseBool(newValue, false);
+                    }
+                    else {
+                        this.flipY = null;
+                    }
+                    break;
+                case 'lazy':
+                    this.lazy = parseBool(newValue, false);
+                    break;
+                case 'mag-filter':
+                    if (newValue !== null) {
+                        this.magFilter = parseEnum(newValue, magFilterModes, 'linear', name);
+                    }
+                    else {
+                        this.magFilter = null;
+                    }
+                    break;
+                case 'min-filter':
+                    if (newValue !== null) {
+                        this.minFilter = parseEnum(newValue, minFilterModes, 'linear-mip-linear', name);
+                    }
+                    else {
+                        this.minFilter = null;
+                    }
+                    break;
+                case 'mipmaps':
+                    if (newValue !== null) {
+                        this.mipmaps = parseBool(newValue, true);
+                    }
+                    else {
+                        this.mipmaps = null;
+                    }
+                    break;
+                case 'srgb':
+                    if (newValue !== null) {
+                        this.srgb = parseBool(newValue, false);
+                    }
+                    else {
+                        this.srgb = null;
+                    }
+                    break;
+            }
+        }
+    }
+    customElements.define('pc-asset', AssetElement);
+
+    /**
+     * Represents a component in the PlayCanvas engine.
+     *
+     * @category Components
+     */
     class ComponentElement extends AsyncElement {
         _componentName;
         _enabled = true;
         _component = null;
         _appElement = null;
+        /**
+         * The element hosting this component, held so the host's readiness cycles can be observed
+         * even after `closestEntity` would no longer resolve (during teardown).
+         */
+        _hostElement = null;
+        /**
+         * The listener re-applying this component when the host's readiness cycles. Held for
+         * removal on disconnect.
+         */
+        _hostReadyListener = null;
         /**
          * Incremented on every connect and disconnect. connectedCallback captures the value on entry
          * and abandons itself wherever it resumes from an await if the value has moved on — so a
@@ -2310,6 +2727,37 @@
         getInitialComponentData() {
             return {};
         }
+        /**
+         * Creates the component on the host's current entity, removing it first from a previous
+         * entity that is still alive (a retargeted `<pc-node>` moves its decorations with it). When
+         * the entity already has a component of this type — a glTF node arriving with its authored
+         * `render` component, say — warns and leaves `component` null. The element-level warning is
+         * load-bearing: the engine's own duplicate-addComponent warning is Debug-stripped from
+         * production builds, which would otherwise leave a silent null.
+         */
+        _applyComponent() {
+            const entity = this._hostElement?.entity ?? null;
+            if (this._component && this._component.entity === entity) {
+                return;
+            }
+            // A retarget leaves the previous component on a still-live entity - remove it so the
+            // decoration follows the element, or vanishes with a dissolved binding. A destroyed
+            // entity took its components with it.
+            const previous = this._component;
+            if (previous?.entity && previous.entity.c[this._componentName] === previous) {
+                previous.entity.removeComponent(this._componentName);
+            }
+            this._component = null;
+            if (!entity) {
+                return;
+            }
+            if (entity.c[this._componentName]) {
+                const label = this.id ? ` '${this.id}'` : '';
+                console.warn(`${this.tagName.toLowerCase()}${label} - '${entity.name}' already has a '${this._componentName}' component - component not added`);
+                return;
+            }
+            this._component = entity.addComponent(this._componentName, this.getInitialComponentData());
+        }
         async _addComponent() {
             const generation = this._connectionGeneration;
             const entityElement = this.closestEntity;
@@ -2326,9 +2774,40 @@
             if (generation !== this._connectionGeneration) {
                 return;
             }
-            // Add the component to the entity
-            const data = this.getInitialComponentData();
-            this._component = entityElement.entity.addComponent(this._componentName, data);
+            this._hostElement = entityElement;
+            this._applyComponent();
+            // Re-apply when the host's readiness cycles without this element disconnecting: a
+            // `<pc-node>` rebinding after its model reloads or retargets, or a re-created entity.
+            // The 'ready' event bubbles, so events from descendants pass through this host - only
+            // the host's own cycles count. Readiness is cycled here too, so decorations one level
+            // down re-apply the same way.
+            this._hostReadyListener = (event) => {
+                if (event.target !== this._hostElement) {
+                    return;
+                }
+                if (generation !== this._connectionGeneration) {
+                    return;
+                }
+                this._hostCycled();
+            };
+            entityElement.addEventListener('ready', this._hostReadyListener);
+        }
+        /**
+         * Re-evaluates this component against the host's current entity: applied to a new entity,
+         * moved from a still-live old one, or removed when the host no longer fronts an entity at
+         * all. Readiness follows - it cycles with a re-application and stays unresolved while the
+         * host is unbound. Called by the host-ready listener, and directly by a `<pc-node>`
+         * dissolving its binding: the one transition that fires no ready event to ride.
+         *
+         * @internal
+         */
+        _hostCycled() {
+            this._resetReady();
+            this._applyComponent();
+            if (this._hostElement?.entity) {
+                this.initComponent();
+                this._onReady();
+            }
         }
         /**
          * Configures the newly added component. Overridden by subclasses whose setup goes beyond
@@ -2357,6 +2836,11 @@
         disconnectedCallback() {
             // Invalidate any connectedCallback still suspended on an await
             this._connectionGeneration++;
+            if (this._hostElement && this._hostReadyListener) {
+                this._hostElement.removeEventListener('ready', this._hostReadyListener);
+            }
+            this._hostElement = null;
+            this._hostReadyListener = null;
             // 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.
@@ -3316,6 +3800,12 @@
      * The CollisionComponentElement interface also inherits the properties and methods of the
      * {@link HTMLElement} interface.
      *
+     * For `type="mesh"`, the collision geometry defaults to the host entity's own render component
+     * (its render asset) — a collider matching the visible mesh, which is what a mesh collider on a
+     * glTF node means. The default resolves each time the component applies, so a `pc-node` that
+     * retargets or rebinds picks up the new node's geometry. An entity with no asset-backed render
+     * component warns, and the collider has no shape.
+     *
      * @category Components
      */
     class CollisionComponentElement extends ComponentElement {
@@ -3343,6 +3833,29 @@
                 type: this._type
             };
         }
+        initComponent() {
+            this._applyMeshGeometryDefault();
+        }
+        /**
+         * Defaults a mesh collider's geometry to the host entity's own render component. The
+         * engine's mesh collider only works with explicitly supplied geometry, and the element has
+         * no attribute to supply it - so the host's visible geometry, the meaning a mesh collider
+         * on a glTF node carries, fills the gap. Runs on every application (so a rebound `pc-node`
+         * recomputes it) and on a runtime switch to `type="mesh"`; an explicitly assigned
+         * `renderAsset` is never overwritten.
+         */
+        _applyMeshGeometryDefault() {
+            const component = this.component;
+            if (!component || this._type !== 'mesh' || component.renderAsset !== null) {
+                return;
+            }
+            const asset = component.entity.render?.asset ?? null;
+            if (asset === null) {
+                console.warn(`pc-collision type="mesh" on '${component.entity.name}' found no asset-backed render component to take geometry from - collider has no shape`);
+                return;
+            }
+            component.renderAsset = asset;
+        }
         /**
          * Gets the underlying PlayCanvas collision component.
          * @returns The collision component.
@@ -3417,6 +3930,7 @@
             this._type = value;
             if (this.component) {
                 this.component.type = value;
+                this._applyMeshGeometryDefault();
             }
         }
         get type() {
@@ -5587,13 +6101,13 @@
         }
         /**
          * @param slot - The material property to write.
-         * @param texture - The loaded texture.
+         * @param texture - The loaded texture, applied with its sampler state untouched - anisotropy
+         * and friends belong to the `pc-asset`'s texture options.
          */
         _applyMap(slot, texture) {
             if (!this.material)
                 return;
             this.material[slot] = texture;
-            texture.anisotropy = 4;
             this._scheduleUpdate();
         }
         /**
@@ -9873,6 +10387,21 @@
      * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-model/ | `<pc-model>`} elements.
      * The ModelElement interface also inherits the properties and methods of the
      * {@link HTMLElement} interface.
+     *
+     * The element becomes ready once its container asset has loaded and the instantiated hierarchy has
+     * been added to the scene — `entity` is non-null by then. A failed load also settles readiness,
+     * with `entity` remaining `null`: readiness means the load settled, not that it succeeded — listen
+     * for `error`, or check `entity`, to tell the outcomes apart. Changing `asset` re-arms readiness
+     * and instantiates anew, so a `ready()` obtained after the change resolves against the new
+     * hierarchy. A `pc-model` outside a `pc-app`, or referencing an unknown asset id, warns and never
+     * becomes ready.
+     *
+     * @fires {Event} load - Fired each time a container asset finishes instantiating, including
+     * re-instantiation after `asset` changes. Does not bubble — listen on this element, or use a
+     * capture-phase listener on an ancestor.
+     * @fires {ErrorEvent} error - Fired when the container 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 ModelElement extends AsyncElement {
         _asset = '';
@@ -9885,11 +10414,12 @@
          */
         _loadGeneration = 0;
         /**
-         * The pending asset-load subscription of the current load, if it is waiting for its asset.
-         * Held so that whatever supersedes the load can detach the handler from the asset, rather
-         * than leave it registered until the asset loads (or forever, if it never does).
+         * The pending asset subscriptions of the current load, if it is waiting for its asset. Held
+         * so that whatever supersedes the load can detach the handlers from the asset, rather than
+         * leave them registered until the asset settles (or forever, if it never does).
          */
         _loadHandle = null;
+        _errorHandle = null;
         /**
          * The root entity of the instantiated model. `null` until the container asset has loaded
          * and been instantiated, and again once the element has been removed from the document.
@@ -9899,18 +10429,36 @@
             return this._entity;
         }
         connectedCallback() {
+            // A model 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.
+            if (!this.closestApp) {
+                const label = this._asset ? ` '${this._asset}'` : '';
+                console.warn(`pc-model${label} must be a descendant of pc-app - model not created`);
+                return;
+            }
             this._loadModel();
-            this._onReady();
         }
         disconnectedCallback() {
             this._loadGeneration++;
-            this._detachLoadHandler();
+            this._detachLoadHandlers();
             this._unloadModel();
             this._resetReady();
         }
-        _detachLoadHandler() {
+        _detachLoadHandlers() {
             this._loadHandle?.off();
             this._loadHandle = null;
+            this._errorHandle?.off();
+            this._errorHandle = null;
+        }
+        /**
+         * Resolves readiness and dispatches the `load` event. Called once the instantiated hierarchy
+         * has been parented — readiness means "in the scene graph", matching `pc-entity`, so a ready
+         * model's entity always has world transforms.
+         */
+        _announceLoad() {
+            this._onReady();
+            this.dispatchEvent(new Event('load'));
         }
         _instantiate(container) {
             const generation = this._loadGeneration;
@@ -9932,6 +10480,7 @@
                         return;
                     }
                     parentEntityElement.entity.addChild(entity);
+                    this._announceLoad();
                 });
             }
             else {
@@ -9942,6 +10491,7 @@
                             return;
                         }
                         appElement.app.root.addChild(entity);
+                        this._announceLoad();
                     });
                 }
             }
@@ -9950,15 +10500,29 @@
             this._unloadModel();
             // Supersede any load already in flight - only the newest load may instantiate
             const generation = ++this._loadGeneration;
-            this._detachLoadHandler();
-            const appElement = await this.closestApp?.ready();
+            this._detachLoadHandlers();
+            // Re-arm readiness so a waiter obtained after an asset change resolves against the new
+            // hierarchy. A no-op on first connection, where readiness is still pending.
+            this._resetReady();
+            const appElement = this.closestApp;
+            if (!appElement) {
+                // Outside pc-app; connectedCallback already warned. Reached through the asset setter.
+                return;
+            }
+            await appElement.ready();
             // The element may have been removed, or another load started, while we waited
             if (generation !== this._loadGeneration) {
                 return;
             }
-            const app = appElement?.app;
+            const app = appElement.app;
             const asset = AssetElement.get(this._asset);
             if (!asset) {
+                // An empty id is a legitimate transient (the asset may be assigned later); a
+                // non-empty one that resolves to nothing is a dead end - say so rather than staying
+                // silently pending.
+                if (this._asset) {
+                    console.warn(`pc-model could not find asset '${this._asset}' - model not created`);
+                }
                 return;
             }
             if (asset.loaded) {
@@ -9967,14 +10531,26 @@
             else {
                 // The generation is re-checked even though a superseded handler is detached: the
                 // detach relies on how the engine's event emitter treats removal, while the check
-                // holds on its own.
+                // holds on its own. Whichever of load/error fires first detaches the other.
                 this._loadHandle = asset.once('load', () => {
-                    this._loadHandle = null;
+                    this._detachLoadHandlers();
                     if (generation !== this._loadGeneration) {
                         return;
                     }
                     this._instantiate(asset.resource);
                 });
+                this._errorHandle = asset.once('error', (err) => {
+                    this._detachLoadHandlers();
+                    if (generation !== this._loadGeneration) {
+                        return;
+                    }
+                    // A failed load settles readiness with a null entity, mirroring pc-asset:
+                    // readiness means the load settled, not that it succeeded.
+                    this.dispatchEvent(new ErrorEvent('error', {
+                        message: err instanceof Error ? err.message : String(err)
+                    }));
+                    this._onReady();
+                });
                 app.assets.load(asset);
             }
         }
@@ -10012,6 +10588,625 @@
     }
     customElements.define('pc-model', ModelElement);
 
+    /**
+     * Computes the Levenshtein distance between two strings, for near-miss suggestions in the
+     * resolution warnings.
+     *
+     * @param a - The first string.
+     * @param b - The second string.
+     * @returns The edit distance.
+     */
+    const levenshtein = (a, b) => {
+        const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+        for (let i = 1; i <= a.length; i++) {
+            let previous = row[0];
+            row[0] = i;
+            for (let j = 1; j <= b.length; j++) {
+                const current = row[j];
+                row[j] = Math.min(row[j] + 1, row[j - 1] + 1, previous + (a[i - 1] === b[j - 1] ? 0 : 1));
+                previous = current;
+            }
+        }
+        return row[b.length];
+    };
+    /**
+     * The NodeElement interface provides properties and methods for manipulating
+     * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-node/ | `<pc-node>`}
+     * elements. The NodeElement interface also inherits the properties and methods of the
+     * {@link HTMLElement} interface.
+     *
+     * A `pc-node` is an override element: where `pc-entity` creates an entity, `pc-node` binds to a
+     * node a `pc-model` loaded and declares overrides against the authored asset — components to
+     * add, properties to change, content to attach. Attributes present apply as overrides; attributes
+     * absent leave authored values untouched, and removing an attribute (or assigning `null` to the
+     * matching property) restores the authored value.
+     *
+     * `name` selects among the host model's nodes (first match in depth-first order), nesting a
+     * `pc-node` inside another scopes the search to that subtree, and `index` picks among identically
+     * named matches. When `name` matches more than one node and no `index` is given, the element
+     * warns and binds nothing.
+     *
+     * The element becomes ready once bound, and never while unresolved — a missing or ambiguous
+     * name warns and records the failure in `state`, readiness stays unresolved, and descendants
+     * wait with it.
+     *
+     * The pointer events below are dispatched by the containing `<pc-app>` element when the pointer
+     * intersects the bound node's geometry, exactly as for `<pc-entity>`.
+     *
+     * @attribute {string} name - The name of the node to bind, resolved within the nearest ancestor
+     * `pc-model` (or `pc-node`) once it has instantiated.
+     * @attribute {number} index - Which match to bind when `name` matches more than one node,
+     * 0-based in depth-first order. Optional for a unique match; required for an ambiguous one.
+     * @attribute {boolean} enabled - Overrides the node's enabled state.
+     * @attribute {string} position - Overrides the node's local position, as an "x y z" triple.
+     * @attribute {string} rotation - Overrides the node's local rotation (Euler angles), as an
+     * "x y z" triple.
+     * @attribute {string} scale - Overrides the node's local scale, as an "x y z" triple.
+     * @attribute {string} tags - Overrides the node's tags, separated by spaces or commas.
+     * @attribute {string} onpointerenter - Script to run when the pointer moves onto the node.
+     * @attribute {string} onpointerleave - Script to run when the pointer moves off the node.
+     * @attribute {string} onpointermove - Script to run when the pointer moves over the node.
+     * @attribute {string} onpointerdown - Script to run when a pointer button is pressed over the
+     * node.
+     * @attribute {string} onpointerup - Script to run when a pointer button is released over the
+     * node.
+     * @fires {PointerEvent} pointerenter - Fired when the pointer moves onto the node.
+     * @fires {PointerEvent} pointerleave - Fired when the pointer moves off the node.
+     * @fires {PointerEvent} pointermove - Fired when the pointer moves over the node.
+     * @fires {PointerEvent} pointerdown - Fired when a pointer button is pressed over the node.
+     * @fires {PointerEvent} pointerup - Fired when a pointer button is released over the node.
+     */
+    class NodeElement extends EntityBaseElement {
+        _name = '';
+        _index = null;
+        _state = 'pending';
+        _path = null;
+        /**
+         * The element whose entity roots this element's search: the nearest ancestor `pc-node`, or
+         * failing that the nearest ancestor `pc-model`. Resolved on connection.
+         */
+        _host = null;
+        /**
+         * The listener following the host's binding cycles. Both host kinds announce each cycle
+         * with a `ready` event — `pc-model` on every instantiation, `pc-node` on every bind.
+         */
+        _hostListener = null;
+        /**
+         * The subscription to the bound entity's destruction, detached on unbind so a retargeted
+         * element cannot be reset by the eventual death of a node it no longer fronts.
+         */
+        _destroyHandle = null;
+        /** The authored values displaced by this element's overrides, captured per property. */
+        _authored = {};
+        // Override values. `null` means "no override": the authored value stays in force.
+        _enabled = null;
+        _position = null;
+        _rotation = null;
+        _scale = null;
+        _tags = null;
+        /**
+         * The binding state: `pending` until the host instantiates and `name` resolves, `bound`
+         * once decorated, `missing`/`ambiguous`/`duplicate` when resolution failed (each also
+         * warns). Useful for asserting a document's bindings programmatically.
+         * @returns The binding state.
+         */
+        get state() {
+            return this._state;
+        }
+        /**
+         * The path of the bound node below the search root, `/`-separated, or `null` while not
+         * bound.
+         * @returns The bound node's path, or `null`.
+         */
+        get path() {
+            return this._path;
+        }
+        connectedCallback() {
+            const host = (this.parentElement?.closest('pc-model, pc-node') ?? null);
+            if (!host) {
+                const label = this._name ? ` '${this._name}'` : '';
+                console.warn(`pc-node${label} must be a descendant of pc-model - node not bound`);
+                return;
+            }
+            this._host = host;
+            // Follow the host's binding cycles. `ready` bubbles, so cycles of elements nested under
+            // the host pass through it - only the host's own count.
+            this._hostListener = (event) => {
+                if (event.target !== this._host) {
+                    return;
+                }
+                this._rebind();
+            };
+            host.addEventListener('ready', this._hostListener);
+            // The host may already be instantiated (an element inserted after load binds immediately)
+            this._rebind();
+        }
+        disconnectedCallback() {
+            if (this._host && this._hostListener) {
+                this._host.removeEventListener('ready', this._hostListener);
+            }
+            this._host = null;
+            this._hostListener = null;
+            // Removal reverts: the model owns the node, so the entity is left as authored. Children
+            // clean up through their own disconnect behavior.
+            this._unbind();
+            this._state = 'pending';
+        }
+        /**
+         * Re-resolves the binding against the host's current hierarchy: on connection, on a `name`
+         * or `index` change, and on every host cycle (a model [re]instantiating, an enclosing
+         * `pc-node` [re]binding). When re-resolution yields the entity already bound, the binding
+         * is retained untouched — a redundant edit must not flicker overrides through a revert.
+         */
+        _rebind() {
+            const hostEntity = this._host?.entity ?? null;
+            if (!hostEntity || !this._name) {
+                // Host not instantiated (or nothing to look up yet): return to pending. An assigned
+                // name arriving later, or the host's next cycle, resolves it.
+                this._unbind();
+                this._state = 'pending';
+                return;
+            }
+            const target = this._resolve(hostEntity);
+            if (target && target === this._entity) {
+                this._path = this._pathOf(target, hostEntity);
+                return;
+            }
+            this._unbind();
+            if (!target) {
+                // _resolve warned and set the failure state
+                return;
+            }
+            this._bind(target, hostEntity);
+        }
+        /**
+         * Resolves `name` (and `index`) to an entity under `hostEntity`, warning and recording the
+         * failure state when it cannot.
+         *
+         * @param hostEntity - The root of the search.
+         * @returns The resolved entity, or `null`.
+         */
+        _resolve(hostEntity) {
+            const matches = hostEntity.find((node) => node.name === this._name);
+            if (matches.length === 0) {
+                const closest = this._closestName(hostEntity);
+                const hint = closest ? ` - closest match: '${closest}'` : '';
+                console.warn(`pc-node '${this._name}' not found in ${this._describeHost()}${hint}`);
+                this._state = 'missing';
+                return null;
+            }
+            let target;
+            if (this._index !== null) {
+                if (this._index >= matches.length) {
+                    console.warn(`pc-node '${this._name}' index ${this._index} is out of range - ${matches.length} match(es) in ${this._describeHost()}`);
+                    this._state = 'missing';
+                    return null;
+                }
+                target = matches[this._index];
+            }
+            else if (matches.length > 1) {
+                // Ambiguity binds nothing: a fallback guess performs side effects on the wrong
+                // scene node, and would go wrong silently when a re-export introduces a duplicate
+                // name. The candidates tell the author exactly what to write.
+                const candidates = matches.map((m, i) => `[${i}] ${this._pathOf(m, hostEntity)}`).join(', ');
+                console.warn(`pc-node '${this._name}' is ambiguous in ${this._describeHost()} - specify index: ${candidates}`);
+                this._state = 'ambiguous';
+                return null;
+            }
+            else {
+                target = matches[0];
+            }
+            const owner = this.closestApp?.elementFromEntity(target);
+            if (owner && owner !== this) {
+                console.warn(`pc-node '${this._name}' resolves to a node already bound by another element - element ignored`);
+                this._state = 'duplicate';
+                return null;
+            }
+            return target;
+        }
+        /**
+         * Binds `target`: registers it (making it a pick target), hooks its destruction, applies
+         * this element's overrides, announces readiness and builds the deferred child subtree.
+         *
+         * @param target - The entity to bind.
+         * @param hostEntity - The search root, for the path.
+         */
+        _bind(target, hostEntity) {
+            this._entity = target;
+            this._registerEntity(target);
+            this._destroyHandle = target.once('destroy', this._onEntityDestroy, this);
+            this._state = 'bound';
+            this._path = this._pathOf(target, hostEntity);
+            this._applyOverrides();
+            this._onReady();
+            this._buildChildren();
+        }
+        /**
+         * Dissolves the current binding, restoring every authored value this element's overrides
+         * displaced and removing the decorations this binding hosts: attachment entities are
+         * destroyed (re-created against the next binding) and component decorations are removed
+         * from the abandoned node. Both sweeps are scoped by `closestEntity`, so a still-bound
+         * nested `pc-node` keeps its own decorations. Safe to call in any state.
+         */
+        _unbind() {
+            const entity = this._entity;
+            if (!entity) {
+                return;
+            }
+            this._revertOverrides();
+            // Attachment points anchor to the bound node, so they cannot outlive the binding. Each
+            // destroyed entity resets its element, which the next _buildChildren re-creates.
+            this.querySelectorAll('pc-entity').forEach((child) => {
+                if (child.closestEntity === this) {
+                    child.entity?.destroy();
+                }
+            });
+            this._destroyHandle?.off();
+            this._destroyHandle = null;
+            this._unregisterEntity(entity);
+            this._entity = null;
+            this._path = null;
+            this._authored = {};
+            // Component decorations come off through the same hook the host-ready cycle uses. A
+            // dissolve that never rebinds fires no ready event, so the sweep is explicit - after
+            // `_entity` is cleared, so the hook sees a host without an entity.
+            this.querySelectorAll('*').forEach((child) => {
+                if (child instanceof ComponentElement && child.closestEntity === this) {
+                    child._hostCycled();
+                }
+            });
+            this._resetReady();
+        }
+        /**
+         * Handles the destruction of the bound entity - its model unloading, reloading, or a script
+         * destroying it. There is nothing to revert on a destroyed entity; the element returns to
+         * pending and the host's next cycle re-resolves it.
+         */
+        _onEntityDestroy(entity) {
+            this._destroyHandle = null;
+            this._unregisterEntity(entity);
+            this._entity = null;
+            this._path = null;
+            this._authored = {};
+            this._state = 'pending';
+            this._resetReady();
+        }
+        /**
+         * Creates and parents the entities of child `pc-entity` elements - the attachment points.
+         * Mirrors the runtime-insertion path in EntityElement.connectedCallback: children were
+         * deferred while this host was unresolved (or reset when a previous binding dissolved), and
+         * build here once it binds.
+         */
+        _buildChildren() {
+            const app = this.closestApp?.app;
+            if (!app) {
+                return;
+            }
+            const childEntities = this.querySelectorAll('pc-entity');
+            childEntities.forEach((child) => {
+                child._createEntity(app);
+            });
+            childEntities.forEach((child) => {
+                child._buildHierarchy(app);
+            });
+        }
+        /**
+         * Applies every override that is explicitly set, capturing the authored value it displaces.
+         */
+        _applyOverrides() {
+            if (this._enabled !== null) {
+                this.enabled = this._enabled;
+            }
+            if (this._position !== null) {
+                this.position = this._position;
+            }
+            if (this._rotation !== null) {
+                this.rotation = this._rotation;
+            }
+            if (this._scale !== null) {
+                this.scale = this._scale;
+            }
+            if (this._tags !== null) {
+                this.tags = this._tags;
+            }
+        }
+        /**
+         * Restores every authored value this element's overrides displaced. The override values
+         * themselves are kept - they re-apply on the next binding.
+         */
+        _revertOverrides() {
+            const entity = this._entity;
+            const authored = this._authored;
+            if (authored.enabled !== undefined) {
+                entity.enabled = authored.enabled;
+            }
+            if (authored.position) {
+                entity.setLocalPosition(authored.position);
+            }
+            if (authored.rotation) {
+                entity.setLocalRotation(authored.rotation);
+            }
+            if (authored.scale) {
+                entity.setLocalScale(authored.scale);
+            }
+            if (authored.tags) {
+                entity.tags.clear();
+                entity.tags.add(authored.tags);
+            }
+            this._authored = {};
+        }
+        /**
+         * Renders the path of `node` below `root`, for the `path` property and the resolution
+         * warnings.
+         *
+         * @param node - The node to describe.
+         * @param root - The search root.
+         * @returns The `/`-separated path.
+         */
+        _pathOf(node, root) {
+            const parts = [];
+            for (let current = node; current && current !== root; current = current.parent) {
+                parts.unshift(current.name);
+            }
+            return parts.join('/') || node.name;
+        }
+        /**
+         * Describes the search root for warnings: the model's asset id, or the enclosing node's
+         * name.
+         * @returns The description.
+         */
+        _describeHost() {
+            if (this._host instanceof ModelElement) {
+                return `model '${this._host.asset}'`;
+            }
+            return `pc-node '${this._host?.name ?? ''}' subtree`;
+        }
+        /**
+         * Finds the node name nearest to the missing `name`, for the miss warning. The names are
+         * already in hand from resolution, so the suggestion is nearly free.
+         *
+         * @param hostEntity - The root of the search.
+         * @returns The closest name within an edit distance of 2, or `null`.
+         */
+        _closestName(hostEntity) {
+            let best = null;
+            let bestDistance = 3;
+            hostEntity.find((node) => {
+                const distance = levenshtein(this._name, node.name);
+                if (distance < bestDistance) {
+                    bestDistance = distance;
+                    best = node.name;
+                }
+                return false;
+            });
+            return best;
+        }
+        /**
+         * Sets the name of the node to bind. A change retargets: the current binding's overrides
+         * revert and the new name resolves afresh. `name` on a `pc-node` is never a rename of the
+         * authored node - it is only ever a reference.
+         * @param value - The node name.
+         */
+        set name(value) {
+            this._name = value;
+            if (this.isConnected && this._host) {
+                this._rebind();
+            }
+        }
+        /**
+         * Gets the name of the node to bind.
+         * @returns The node name.
+         */
+        get name() {
+            return this._name;
+        }
+        /**
+         * Sets which match to bind when `name` matches more than one node, 0-based in depth-first
+         * order. A change retargets, like `name`. `null` means unset - required when the name is
+         * ambiguous, optional otherwise.
+         * @param value - The match index, or `null`.
+         */
+        set index(value) {
+            this._index = value;
+            if (this.isConnected && this._host) {
+                this._rebind();
+            }
+        }
+        /**
+         * Gets which match to bind.
+         * @returns The match index, or `null` when unset.
+         */
+        get index() {
+            return this._index;
+        }
+        /**
+         * Sets the enabled override. `null` clears it, restoring the authored state.
+         * @param value - The enabled state, or `null`.
+         */
+        set enabled(value) {
+            this._enabled = value;
+            const entity = this._state === 'bound' ? this._entity : null;
+            if (!entity) {
+                return;
+            }
+            if (value !== null) {
+                this._authored.enabled ??= entity.enabled;
+                entity.enabled = value;
+            }
+            else if (this._authored.enabled !== undefined) {
+                entity.enabled = this._authored.enabled;
+                delete this._authored.enabled;
+            }
+        }
+        /**
+         * Gets the enabled override.
+         * @returns The enabled state, or `null` while no override is set.
+         */
+        get enabled() {
+            return this._enabled;
+        }
+        /**
+         * Sets the local position override. `null` clears it, restoring the authored position.
+         * @param value - The position, or `null`.
+         */
+        set position(value) {
+            this._position = value;
+            const entity = this._state === 'bound' ? this._entity : null;
+            if (!entity) {
+                return;
+            }
+            if (value !== null) {
+                this._authored.position ??= entity.getLocalPosition().clone();
+                entity.setLocalPosition(value);
+            }
+            else if (this._authored.position) {
+                entity.setLocalPosition(this._authored.position);
+                delete this._authored.position;
+            }
+        }
+        /**
+         * Gets the local position override.
+         * @returns The position, or `null` while no override is set.
+         */
+        get position() {
+            return this._position;
+        }
+        /**
+         * Sets the local rotation override, as Euler angles in degrees. `null` clears it, restoring
+         * the authored rotation.
+         * @param value - The rotation, or `null`.
+         */
+        set rotation(value) {
+            this._rotation = value;
+            const entity = this._state === 'bound' ? this._entity : null;
+            if (!entity) {
+                return;
+            }
+            if (value !== null) {
+                // The authored rotation is cached as a quaternion: it restores exactly, where a
+                // round trip through Euler angles need not.
+                this._authored.rotation ??= entity.getLocalRotation().clone();
+                entity.setLocalEulerAngles(value);
+            }
+            else if (this._authored.rotation) {
+                entity.setLocalRotation(this._authored.rotation);
+                delete this._authored.rotation;
+            }
+        }
+        /**
+         * Gets the local rotation override.
+         * @returns The rotation, or `null` while no override is set.
+         */
+        get rotation() {
+            return this._rotation;
+        }
+        /**
+         * Sets the local scale override. `null` clears it, restoring the authored scale.
+         * @param value - The scale, or `null`.
+         */
+        set scale(value) {
+            this._scale = value;
+            const entity = this._state === 'bound' ? this._entity : null;
+            if (!entity) {
+                return;
+            }
+            if (value !== null) {
+                this._authored.scale ??= entity.getLocalScale().clone();
+                entity.setLocalScale(value);
+            }
+            else if (this._authored.scale) {
+                entity.setLocalScale(this._authored.scale);
+                delete this._authored.scale;
+            }
+        }
+        /**
+         * Gets the local scale override.
+         * @returns The scale, or `null` while no override is set.
+         */
+        get scale() {
+            return this._scale;
+        }
+        /**
+         * Sets the tags override. `null` clears it, restoring the authored tags.
+         * @param value - The tags, or `null`.
+         */
+        set tags(value) {
+            this._tags = value;
+            const entity = this._state === 'bound' ? this._entity : null;
+            if (!entity) {
+                return;
+            }
+            if (value !== null) {
+                this._authored.tags ??= entity.tags.list().slice();
+                entity.tags.clear();
+                entity.tags.add(value);
+            }
+            else if (this._authored.tags) {
+                entity.tags.clear();
+                entity.tags.add(this._authored.tags);
+                delete this._authored.tags;
+            }
+        }
+        /**
+         * Gets the tags override.
+         * @returns The tags, or `null` while no override is set.
+         */
+        get tags() {
+            return this._tags;
+        }
+        static get observedAttributes() {
+            return ['enabled', 'index', 'name', 'position', 'rotation', 'scale', 'tags', ...POINTER_ATTRIBUTES];
+        }
+        attributeChangedCallback(name, _oldValue, newValue) {
+            switch (name) {
+                case 'enabled':
+                    this.enabled = newValue === null ? null : parseBool(newValue, true);
+                    break;
+                case 'index':
+                    if (newValue === null) {
+                        this.index = null;
+                    }
+                    else {
+                        // Number('') is 0, which would make index="" silently mean the first match
+                        const index = newValue.trim() === '' ? NaN : Number(newValue);
+                        if (!Number.isInteger(index) || index < 0) {
+                            // Invalid values are treated as absent: under ambiguity that means
+                            // unbound, the fail-safe direction.
+                            console.warn(`pc-node index '${newValue}' is not a non-negative integer - treated as absent`);
+                            this.index = null;
+                        }
+                        else {
+                            this.index = index;
+                        }
+                    }
+                    break;
+                case 'name':
+                    this.name = newValue ?? '';
+                    break;
+                case 'position':
+                    this.position = newValue === null ? null : parseVec3(newValue, playcanvas.Vec3.ZERO, name);
+                    break;
+                case 'rotation':
+                    this.rotation = newValue === null ? null : parseVec3(newValue, playcanvas.Vec3.ZERO, name);
+                    break;
+                case 'scale':
+                    this.scale = newValue === null ? null : parseVec3(newValue, playcanvas.Vec3.ONE, name);
+                    break;
+                case 'tags':
+                    this.tags = newValue === null ? null : parseTags(newValue);
+                    break;
+                case 'onpointerenter':
+                case 'onpointerleave':
+                case 'onpointerdown':
+                case 'onpointerup':
+                case 'onpointermove':
+                    this._updateInlineHandler(name, newValue);
+                    break;
+            }
+        }
+    }
+    customElements.define('pc-node', NodeElement);
+
     /**
      * The SceneElement interface provides properties and methods for manipulating
      * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-scene/ | `<pc-scene>`} elements.
@@ -10284,7 +11479,6 @@
                 return;
             const source = asset.resource;
             const skybox = playcanvas.EnvLighting.generateSkyboxCubemap(source);
-            skybox.anisotropy = 4;
             // This element owns what it generated (see _unloadSkybox) - replacing a skybox from an
             // earlier load must release it, not orphan it on the GPU
             this._scene.skybox?.destroy();
@@ -10541,6 +11735,7 @@
     exports.CollisionComponentElement = CollisionComponentElement;
     exports.ComponentElement = ComponentElement;
     exports.ElementComponentElement = ElementComponentElement;
+    exports.EntityBaseElement = EntityBaseElement;
     exports.EntityElement = EntityElement;
     exports.GSplatComponentElement = GSplatComponentElement;
     exports.LayoutChildComponentElement = LayoutChildComponentElement;
@@ -10550,6 +11745,7 @@
     exports.MaterialElement = MaterialElement;
     exports.ModelElement = ModelElement;
     exports.ModuleElement = ModuleElement;
+    exports.NodeElement = NodeElement;
     exports.ParticleSystemComponentElement = ParticleSystemComponentElement;
     exports.RenderComponentElement = RenderComponentElement;
     exports.RigidBodyComponentElement = RigidBodyComponentElement;