@playcanvas/web-components 0.16.0 → 0.18.0

package/dist/pwc.mjs

@@ -1,4 +1,4 @@
-import { basisInitialize, WasmModule, Vec3, Color, Vec4, Quat, Vec2, createGraphicsDevice, AppOptions, Keyboard, Mouse, ElementInput, AnimComponentSystem, AnimationComponentSystem, AudioListenerComponentSystem, ButtonComponentSystem, CameraComponentSystem, CollisionComponentSystem, ElementComponentSystem, GSplatComponentSystem, JointComponentSystem, LayoutChildComponentSystem, LayoutGroupComponentSystem, LightComponentSystem, ModelComponentSystem, ParticleSystemComponentSystem, RenderComponentSystem, RigidBodyComponentSystem, ScreenComponentSystem, ScriptComponentSystem, ScrollbarComponentSystem, ScrollViewComponentSystem, SoundComponentSystem, SpriteComponentSystem, ZoneComponentSystem, AnimClipHandler, AnimationHandler, AnimStateGraphHandler, AudioHandler, BinaryHandler, CssHandler, ContainerHandler, CubemapHandler, FolderHandler, FontHandler, GSplatHandler, HierarchyHandler, HtmlHandler, JsonHandler, MaterialHandler, ModelHandler, RenderHandler, ScriptHandler, SceneHandler, ShaderHandler, SpriteHandler, TemplateHandler, TextHandler, TextureAtlasHandler, TextureHandler, SoundManager, Lightmapper, BatchManager, XrManager, AppBase, FILLMODE_NONE, RESOLUTION_AUTO, Picker, MeshInstance, Entity, Asset, SPRITE_RENDERMODE_SIMPLE, FILTER_LINEAR_MIPMAP_LINEAR, FILTER_LINEAR, ADDRESS_REPEAT, SPRITE_RENDERMODE_SLICED, SPRITE_RENDERMODE_TILED, ADDRESS_CLAMP_TO_EDGE, ADDRESS_MIRRORED_REPEAT, FILTER_NEAREST, FILTER_NEAREST_MIPMAP_NEAREST, FILTER_LINEAR_MIPMAP_NEAREST, FILTER_NEAREST_MIPMAP_LINEAR, AnimTrack, ANIM_CONTROL_STATES, BUTTON_TRANSITION_MODE_TINT, BUTTON_TRANSITION_MODE_SPRITE_CHANGE, TONEMAP_NONE, PROJECTION_PERSPECTIVE, GAMMA_SRGB, GAMMA_NONE, XRTYPE_VR, TONEMAP_LINEAR, TONEMAP_FILMIC, TONEMAP_HEJL, TONEMAP_ACES, TONEMAP_ACES2, TONEMAP_NEUTRAL, PROJECTION_ORTHOGRAPHIC, ORIENTATION_HORIZONTAL, FITTING_NONE, FITTING_STRETCH, FITTING_SHRINK, FITTING_BOTH, ORIENTATION_VERTICAL, SHADOW_PCF3_32F, SHADOW_PCF1_16F, SHADOW_PCF1_32F, SHADOW_PCF3_16F, SHADOW_PCF5_16F, SHADOW_PCF5_32F, SHADOW_VSM_16F, SHADOW_VSM_32F, SHADOW_PCSS_32F, StandardMaterial, BLEND_NONE, CULLFACE_BACK, FRESNEL_SCHLICK, SPECOCC_AO, BLEND_NORMAL, BLEND_ADDITIVE, BLEND_ADDITIVEALPHA, BLEND_PREMULTIPLIED, BLEND_MULTIPLICATIVE, BLEND_MULTIPLICATIVE2X, BLEND_SCREEN, BLEND_MIN, BLEND_MAX, BLEND_SUBTRACTIVE, CULLFACE_NONE, CULLFACE_FRONT, CULLFACE_FRONTANDBACK, FRESNEL_NONE, SPECOCC_NONE, SPECOCC_GLOSSDEPENDENT, SCALEMODE_NONE, SCALEMODE_BLEND, SCROLL_MODE_BOUNCE, SCROLLBAR_VISIBILITY_SHOW_WHEN_REQUIRED, SCROLLBAR_VISIBILITY_SHOW_ALWAYS, SCROLL_MODE_CLAMP, SCROLL_MODE_INFINITE, EnvLighting, LAYERID_SKYBOX } from 'playcanvas';
+import { basisInitialize, WasmModule, Vec3, Color, Vec4, Quat, Vec2, createGraphicsDevice, AppOptions, Keyboard, Mouse, ElementInput, AnimComponentSystem, AnimationComponentSystem, AudioListenerComponentSystem, ButtonComponentSystem, CameraComponentSystem, CollisionComponentSystem, ElementComponentSystem, GSplatComponentSystem, JointComponentSystem, LayoutChildComponentSystem, LayoutGroupComponentSystem, LightComponentSystem, ModelComponentSystem, ParticleSystemComponentSystem, RenderComponentSystem, RigidBodyComponentSystem, ScreenComponentSystem, ScriptComponentSystem, ScrollbarComponentSystem, ScrollViewComponentSystem, SoundComponentSystem, SpriteComponentSystem, ZoneComponentSystem, AnimClipHandler, AnimationHandler, AnimStateGraphHandler, AudioHandler, BinaryHandler, CssHandler, ContainerHandler, CubemapHandler, FolderHandler, FontHandler, GSplatHandler, HierarchyHandler, HtmlHandler, JsonHandler, MaterialHandler, ModelHandler, RenderHandler, ScriptHandler, SceneHandler, ShaderHandler, SpriteHandler, TemplateHandler, TextHandler, TextureAtlasHandler, TextureHandler, SoundManager, Lightmapper, BatchManager, XrManager, AppBase, FILLMODE_NONE, RESOLUTION_AUTO, Picker, MeshInstance, Entity, Asset, SPRITE_RENDERMODE_SIMPLE, FILTER_LINEAR_MIPMAP_LINEAR, FILTER_LINEAR, ADDRESS_REPEAT, SPRITE_RENDERMODE_SLICED, SPRITE_RENDERMODE_TILED, ADDRESS_CLAMP_TO_EDGE, ADDRESS_MIRRORED_REPEAT, FILTER_NEAREST, FILTER_NEAREST_MIPMAP_NEAREST, FILTER_LINEAR_MIPMAP_NEAREST, FILTER_NEAREST_MIPMAP_LINEAR, AnimTrack, ANIM_CONTROL_STATES, BUTTON_TRANSITION_MODE_TINT, BUTTON_TRANSITION_MODE_SPRITE_CHANGE, TONEMAP_NONE, PROJECTION_PERSPECTIVE, GAMMA_SRGB, GAMMA_NONE, XRTYPE_AR, XRTYPE_VR, TONEMAP_LINEAR, TONEMAP_FILMIC, TONEMAP_HEJL, TONEMAP_ACES, TONEMAP_ACES2, TONEMAP_NEUTRAL, PROJECTION_ORTHOGRAPHIC, ORIENTATION_HORIZONTAL, FITTING_NONE, FITTING_STRETCH, FITTING_SHRINK, FITTING_BOTH, ORIENTATION_VERTICAL, SHADOW_PCF3_32F, SHADOW_PCF1_16F, SHADOW_PCF1_32F, SHADOW_PCF3_16F, SHADOW_PCF5_16F, SHADOW_PCF5_32F, SHADOW_VSM_16F, SHADOW_VSM_32F, SHADOW_PCSS_32F, StandardMaterial, BLEND_NONE, CULLFACE_BACK, FRESNEL_SCHLICK, SPECOCC_AO, BLEND_NORMAL, BLEND_ADDITIVE, BLEND_ADDITIVEALPHA, BLEND_PREMULTIPLIED, BLEND_MULTIPLICATIVE, BLEND_MULTIPLICATIVE2X, BLEND_SCREEN, BLEND_MIN, BLEND_MAX, BLEND_SUBTRACTIVE, CULLFACE_NONE, CULLFACE_FRONT, CULLFACE_FRONTANDBACK, FRESNEL_NONE, SPECOCC_NONE, SPECOCC_GLOSSDEPENDENT, SCALEMODE_NONE, SCALEMODE_BLEND, SCROLL_MODE_BOUNCE, SCROLLBAR_VISIBILITY_SHOW_WHEN_REQUIRED, SCROLLBAR_VISIBILITY_SHOW_ALWAYS, SCROLL_MODE_CLAMP, SCROLL_MODE_INFINITE, EnvLighting, LAYERID_SKYBOX } from 'playcanvas';
 
 /**
  * Base class for all PlayCanvas Web Components that initialize asynchronously.
@@ -27,13 +27,13 @@ class AsyncElement extends HTMLElement {
         return this.parentElement?.closest('pc-app') ?? 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.
+     * The nearest ancestor element that fronts an entity — `<pc-entity>`, `<pc-model>` 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, pc-node') ?? null;
+        return this.parentElement?.closest('pc-entity, pc-model, pc-node') ?? null;
     }
     /**
      * Called when the element is fully initialized and ready. Subclasses should call this when
@@ -107,9 +107,9 @@ async function whenReady(target) {
 }
 
 /**
- * The ModuleElement interface provides properties and methods for manipulating
- * {@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
+ * The WasmElement interface provides properties and methods for manipulating
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-wasm/ | `<pc-wasm>`}
+ * elements. The WasmElement interface also inherits the properties and methods of the
  * {@link AsyncElement} interface.
  *
  * The attributes are read once, when the module starts loading - on the element's first
@@ -118,9 +118,13 @@ async function whenReady(target) {
  * modules configure engine-global state that never unloads, so readiness is not re-armed by
  * removing the element, and a re-inserted element does not load again.
  *
- * A `<pc-module>` without a `name` warns and never becomes ready; a containing `<pc-app>` still
+ * A `<pc-wasm>` without a `name` warns and never becomes ready; a containing `<pc-app>` still
  * boots.
  *
+ * @elementSummary The `<pc-wasm>` element loads a WebAssembly module the engine needs before the
+ * application starts — `Ammo` for physics, `Basis` or `DracoDecoderModule` for compressed assets.
+ * Must be a direct child of `<pc-app>`.
+ *
  * @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.
@@ -128,7 +132,7 @@ async function whenReady(target) {
  * @attribute {string} fallback - The URL of the module's asm.js fallback script, used when
  * WebAssembly is unavailable.
  */
-class ModuleElement extends AsyncElement {
+class WasmElement extends AsyncElement {
     _loadPromise = null;
     connectedCallback() {
         this._getLoadPromise();
@@ -136,7 +140,7 @@ class ModuleElement extends AsyncElement {
     async _loadModule() {
         const name = this.getAttribute('name');
         if (!name) {
-            console.warn("pc-module requires a 'name' attribute - no module was configured");
+            console.warn("pc-wasm requires a 'name' attribute - no module was configured");
             return;
         }
         const config = {
@@ -171,7 +175,7 @@ class ModuleElement extends AsyncElement {
         return this._loadPromise;
     }
 }
-customElements.define('pc-module', ModuleElement);
+customElements.define('pc-wasm', WasmElement);
 
 /** Covers the 0.2s opacity transition; jsdom never fires transitionend, so removal is timed. */
 const REMOVAL_DELAY_MS = 250;
@@ -728,6 +732,12 @@ const getEntity = (ref) => {
 
 /** The pointer event types the application synthesizes on `<pc-entity>` elements via picking. */
 const pointerEventTypes = ['pointermove', 'pointerdown', 'pointerup', 'pointerenter', 'pointerleave'];
+/**
+ * The event types whose listeners make an element a hover target. Hover resolution walks past
+ * elements listening for none of them, so a silent element never swallows an ancestor's
+ * enter/leave pair.
+ */
+const hoverEventTypes = ['pointerenter', 'pointerleave', 'pointermove'];
 /**
  * Gives `pc-app` the sizing contract of a replaced element (`<video>`, `<img>`): a block-level
  * box that the page's CSS sizes, defaulting to the canvas's own 300x150 intrinsic size, with the
@@ -756,6 +766,10 @@ const ensureBaseStyles = () => {
  * tracked live via a ResizeObserver — so the element can be embedded at any size, resized by
  * its container, or made fullscreen with ordinary CSS such as `width: 100vw; height: 100dvh`.
  *
+ * @elementSummary The `<pc-app>` element creates a PlayCanvas application and the canvas it renders
+ * into, and is the root of every scene. It holds the `<pc-asset>`, `<pc-material>`, `<pc-wasm>` and
+ * `<pc-scene>` elements, and the page's CSS sizes it, as it would a `<video>`.
+ *
  * @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
@@ -802,9 +816,9 @@ class AppElement extends AsyncElement {
     _bootGeneration = 0;
     /**
      * The elements backing this application's entities, keyed by the entity itself. Registered
-     * 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.
+     * by entity-owning elements at creation (pc-entity, and pc-model for its host) and by
+     * 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;
@@ -883,7 +897,7 @@ class AppElement extends AsyncElement {
         // there, leaving the element permanently unready: no canvas, no entities, no application.
         //
         // Upgrading is the fix here rather than skipping whatever has not upgraded, because a
-        // <pc-module> is the one child that nothing else ever builds on its own behalf - skipping
+        // <pc-wasm> is the one child that nothing else ever builds on its own behalf - skipping
         // it would drop the wasm module the app asked for, silently and only for cloned apps.
         // Upgrading runs each descendant's connectedCallback synchronously, a few lines earlier
         // than the parser's path runs them but into the same state they see there: no application
@@ -892,10 +906,10 @@ class AppElement extends AsyncElement {
         // as any other disconnect is. An already-upgraded subtree - every other insertion path -
         // is left completely untouched.
         customElements.upgrade(this);
-        // Get all pc-module elements that are direct children of the pc-app element
-        const moduleElements = this.querySelectorAll(':scope > pc-module');
+        // Get all pc-wasm elements that are direct children of the pc-app element
+        const wasmElements = this.querySelectorAll(':scope > pc-wasm');
         // Wait for all modules to load
-        await Promise.all(Array.from(moduleElements).map((module) => module._getLoadPromise()));
+        await Promise.all(Array.from(wasmElements).map((element) => element._getLoadPromise()));
         // The element may have been removed while the modules loaded. Nothing beyond the loading
         // bar exists yet, and disconnectedCallback has already destroyed that.
         if (generation !== this._bootGeneration) {
@@ -1065,14 +1079,15 @@ class AppElement extends AsyncElement {
         Array.from(materialElements).forEach((materialElement) => {
             materialElement._createMaterial();
         });
-        // Create all entities
-        const entityElements = this.querySelectorAll('pc-entity');
-        Array.from(entityElements).forEach((entityElement) => {
-            entityElement._createEntity(app);
+        // Create all entities. pc-model joins the sweep because it owns a host entity of its
+        // own; its instantiated content arrives later, beneath that host.
+        const ownerElements = this.querySelectorAll('pc-entity, pc-model');
+        Array.from(ownerElements).forEach((ownerElement) => {
+            ownerElement._createEntity(app);
         });
         // Build hierarchy
-        entityElements.forEach((entityElement) => {
-            entityElement._buildHierarchy(app);
+        ownerElements.forEach((ownerElement) => {
+            ownerElement._buildHierarchy(app);
         });
         // Building the hierarchy dispatched each entity's ready event synchronously, and a
         // listener may have removed the element. The sweep itself degrades safely - destroying
@@ -1183,7 +1198,7 @@ class AppElement extends AsyncElement {
         // 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, pc-node')).some((entity) => entity._hasListeners(type));
+            const anyListeners = Array.from(this.querySelectorAll('pc-entity, pc-model, pc-node')).some((entity) => entity._hasListeners(type));
             if (anyListeners) {
                 this._onPointerListenerAdded(type);
             }
@@ -1233,10 +1248,10 @@ class AppElement extends AsyncElement {
         this._entityElements.delete(entity);
     }
     /**
-     * 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.
+     * Returns the `<pc-entity>`, `<pc-model>` 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 fronting the entity, or `null`.
@@ -1245,18 +1260,19 @@ class AppElement extends AsyncElement {
         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 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.
+     * Resolves the element that owns hover for a picked node: the nearest node up the parent
+     * chain - starting with the node itself - whose element listens for any of the hover event
+     * types. Skipping silent elements matches {@link _elementWithListener}, so a registered
+     * element with no hover listeners (a `<pc-model>` host, a plain child entity) is transparent
+     * to hover rather than swallowing a listening ancestor's enter/leave pair.
      *
      * @param node - The picked node, or `null`.
-     * @returns The owning element, or `null`.
+     * @returns The hover-owning element, or `null`.
      */
-    _elementFromNode(node) {
+    _hoverTarget(node) {
         while (node !== null) {
             const element = this._entityElements.get(node);
-            if (element) {
+            if (element && hoverEventTypes.some((type) => element._hasListeners(type))) {
                 return element;
             }
             node = node.parent;
@@ -1392,9 +1408,10 @@ class AppElement extends AsyncElement {
         const node = await this._pickNode(event);
         if (token !== this._pickToken || !this._picker)
             return;
-        // The hovered element is the nearest one up the node's parent chain, listening or not -
-        // dispatch is gated per event type below
-        const newHoverEntity = this._elementFromNode(node);
+        // The hovered element is the nearest one up the node's parent chain with a hover
+        // listener - the nearest-listener rule down/up use. Dispatch is still gated per event
+        // type below: having any hover listener selects the target, each event needs its own.
+        const newHoverEntity = this._hoverTarget(node);
         // Handle enter/leave events
         if (this._hoveredEntity !== newHoverEntity) {
             if (this._hoveredEntity && this._hoveredEntity._hasListeners('pointerleave')) {
@@ -1446,7 +1463,7 @@ class AppElement extends AsyncElement {
         }
     }
     _onPointerListenerRemoved(type) {
-        const hasListeners = Array.from(this.querySelectorAll('pc-entity, pc-node')).some((entity) => entity._hasListeners(type));
+        const hasListeners = Array.from(this.querySelectorAll('pc-entity, pc-model, pc-node')).some((entity) => entity._hasListeners(type));
         if (!hasListeners && this._canvas) {
             this._hasPointerListeners[type] = false;
             const handler = type === 'pointerenter' || type === 'pointerleave'
@@ -1637,11 +1654,12 @@ const POINTER_ATTRIBUTES = [
     '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.
+ * The base class for elements that front an engine {@link Entity}: `<pc-entity>` and
+ * `<pc-model>`, which create one, and `<pc-node>`, which binds to one inside a model's
+ * instantiated hierarchy. It carries what all of them 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;
@@ -1690,7 +1708,7 @@ class EntityBaseElement extends AsyncElement {
      * 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
+     * HTML element. But because they bypass {@link EventTarget.addEventListener}, the connect/disconnect
      * bookkeeping that lets the application lazily attach its canvas pointer handlers must be
      * kept in sync here.
      *
@@ -1731,7 +1749,7 @@ class EntityBaseElement extends AsyncElement {
     }
     /**
      * 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
+     * {@link EventTarget.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.
@@ -1744,17 +1762,17 @@ class EntityBaseElement extends AsyncElement {
 }
 
 /**
- * Creates and parents the entities of every descendant `<pc-entity>` of `root`, in two passes so
- * that no parent's existence depends on document order. Called wherever a subtree could not build
- * itself: an element inserted into an application that is already running, and a `<pc-node>` whose
- * children waited for it to bind.
+ * Creates and parents the entities of every descendant entity-owning element of `root`, in two
+ * passes so that no parent's existence depends on document order. Called wherever a subtree could
+ * not build itself: an element inserted into an application that is already running, and a
+ * `<pc-node>` whose children waited for it to bind.
  *
  * Descendants that are not yet custom elements are skipped, because there is nothing useful to do
  * for them and reaching for `_createEntity` would throw. A subtree cloned from a `<template>`
  * arrives entirely unupgraded — template content lives in an inert document, where custom element
  * definitions are never looked up — and appending the clone upgrades its elements in tree order,
  * an element before its descendants. So a sweep from an element's own `connectedCallback` sees
- * plain `HTMLElement`s below it. Each becomes an `EntityElement` moments later and its own
+ * plain `HTMLElement`s below it. Each becomes an entity-owning element moments later and its own
  * `connectedCallback` creates and parents it, by which time the ancestor it parents under has its
  * entity — the same guarantee tree order gives this sweep.
  *
@@ -1763,35 +1781,18 @@ class EntityBaseElement extends AsyncElement {
  * @internal
  */
 const buildDescendantEntities = (root, app) => {
-    const children = Array.from(root.querySelectorAll('pc-entity')).filter((child) => child instanceof EntityElement);
+    const children = Array.from(root.querySelectorAll('pc-entity, pc-model')).filter((child) => child instanceof EntityOwnerElement);
     children.forEach((child) => child._createEntity(app));
     children.forEach((child) => child._buildHierarchy(app));
 };
 /**
- * The EntityElement interface provides properties and methods for manipulating
- * {@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.
+ * The base class for elements that create and own their backing entity: `<pc-entity>` and
+ * `<pc-model>`, whose host entity carries the same authored properties. It carries the cached
+ * property state, entity creation and parenting, and the reset that follows the entity's
+ * destruction. `<pc-node>` sits outside this class: it borrows an entity a model instantiated,
+ * and its properties are nullable overrides rather than owned values.
  */
-class EntityElement extends EntityBaseElement {
+class EntityOwnerElement extends EntityBaseElement {
     /**
      * Whether the entity is enabled.
      */
@@ -1817,7 +1818,8 @@ class EntityElement extends EntityBaseElement {
      */
     _tags = [];
     /**
-     * Whether the hierarchy has been built for this entity.
+     * Whether the hierarchy has been built for this entity — set once `_buildHierarchy` has
+     * parented it. Read by subclasses that gate work on the entity being in the scene graph.
      */
     _built = false;
     /**
@@ -1870,10 +1872,10 @@ class EntityElement extends EntityBaseElement {
         this._resetReady();
     }
     /**
-     * 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.
+     * Parents the backing entity: under the entity of the nearest ancestor `<pc-entity>`,
+     * `<pc-model>` 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
@@ -1888,6 +1890,13 @@ class EntityElement extends EntityBaseElement {
         if (closestEntity && !closestEntity.entity) {
             return;
         }
+        // An owner that exists but is not yet parented is itself deferred behind an unresolved
+        // node further up. Building beneath it would announce readiness for an entity that is
+        // not in the scene graph; stay unbuilt with it - the node's bind sweeps the whole
+        // subtree, ancestors before descendants.
+        if (closestEntity instanceof EntityOwnerElement && !closestEntity._built) {
+            return;
+        }
         this._built = true;
         if (closestEntity?.entity) {
             closestEntity.entity.addChild(this.entity);
@@ -1895,35 +1904,16 @@ class EntityElement extends EntityBaseElement {
         else {
             app.root.addChild(this.entity);
         }
-        this._onReady();
+        this._onBuilt();
     }
-    connectedCallback() {
-        // Wait for app to be ready
-        const closestApp = this.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;
-            this._createEntity(app);
-            this._buildHierarchy(app);
-            // Handle any child entities that might exist
-            buildDescendantEntities(this, app);
-        }
-    }
-    disconnectedCallback() {
-        // Destroying the entity destroys its whole subtree, and the engine fires 'destroy' for
-        // every entity in it - so _onEntityDestroy resets this element AND every descendant
-        // element before the descendants' own disconnectedCallbacks run. Their entities are null
-        // by then, making this call a no-op for them.
-        this._entity?.destroy();
+    /**
+     * Called by `_buildHierarchy` once the backing entity has been parented — exactly once
+     * per build cycle. The default announces readiness, which is what a parented `<pc-entity>`
+     * means; `<pc-model>` overrides it to start loading content instead, because its readiness
+     * tracks the content settling rather than the host entering the scene graph.
+     */
+    _onBuilt() {
+        this._onReady();
     }
     /**
      * Sets the enabled state of the entity.
@@ -2028,6 +2018,75 @@ class EntityElement extends EntityBaseElement {
     get tags() {
         return this._tags;
     }
+}
+
+/**
+ * The EntityElement interface provides properties and methods for manipulating
+ * {@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 EventTarget.addEventListener} or with the matching inline `onpointer*`
+ * attribute.
+ *
+ * @elementSummary The `<pc-entity>` element creates an entity: a named, transformable node of the
+ * scene hierarchy, and the host for component elements such as `<pc-camera>`, `<pc-light>` and
+ * `<pc-render>`. Place it in the `<pc-scene>`, or nest it under another `<pc-entity>`, a
+ * `<pc-model>` or a `<pc-node>` to parent it there.
+ *
+ * @attribute {boolean} enabled - The enabled state of the entity.
+ * @attribute {string} name - The name of the entity.
+ * @attribute {string} position - The position of the entity.
+ * @attribute {string} rotation - The rotation of the entity.
+ * @attribute {string} scale - The scale of the entity.
+ * @attribute {string} tags - The tags of the entity.
+ * @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 EntityOwnerElement {
+    connectedCallback() {
+        // Wait for app to be ready
+        const closestApp = this.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;
+            this._createEntity(app);
+            this._buildHierarchy(app);
+            // Handle any child entities that might exist. A build that deferred (an unresolved
+            // pc-node above) defers the whole subtree with it - the node's bind sweeps it.
+            if (this._built) {
+                buildDescendantEntities(this, app);
+            }
+        }
+    }
+    disconnectedCallback() {
+        // Destroying the entity destroys its whole subtree, and the engine fires 'destroy' for
+        // every entity in it - so _onEntityDestroy resets this element AND every descendant
+        // element before the descendants' own disconnectedCallbacks run. Their entities are null
+        // by then, making this call a no-op for them.
+        this._entity?.destroy();
+    }
     static get observedAttributes() {
         return ['enabled', 'name', 'position', 'rotation', 'scale', 'tags', ...POINTER_ATTRIBUTES];
     }
@@ -2357,6 +2416,10 @@ const processBufferView = (gltfBuffer, buffers, continuation) => {
  * Apart from `lazy` and the texture options, these attributes are read once when the asset is
  * created, so changing them later has no effect.
  *
+ * @elementSummary The `<pc-asset>` element declares an asset for the application to load — a model,
+ * texture, font, sound, script or JSON file — under an `id` that other elements reference. Must be
+ * a direct child of `<pc-app>`.
+ *
  * @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.
@@ -2965,14 +3028,47 @@ const formatHierarchy = (root, counts) => {
  * 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.
+ * The element creates and fronts a stable host entity: `entity` is that host, created when the
+ * application builds its hierarchy and kept across `asset` changes, so the element's transform
+ * and tags are instance placement that composes with whatever transform the asset authored on
+ * its root. The instantiated content is parented beneath the host and exposed as
+ * {@link contentEntity}.
+ *
+ * The element becomes ready once its current asset selection has settled: the container asset
+ * has loaded and its content root has been parented beneath the host, the load has failed
+ * (`contentEntity` stays `null` — listen for `error`, or check `contentEntity`, to tell the
+ * outcomes apart), or no asset is assigned at all. Changing `asset` re-arms readiness and
+ * instantiates anew, so a `ready()` obtained after the change resolves against the new content.
+ * A `pc-model` outside a `pc-app`, or referencing an unknown asset id, warns and never becomes
+ * ready.
+ *
+ * The pointer events below are dispatched by the containing `<pc-app>` element when the pointer
+ * intersects the model's geometry, exactly as for `<pc-entity>` — a hit on a content node that no
+ * `pc-node` fronts resolves to this element.
+ *
+ * @elementSummary The `<pc-model>` element instantiates a 3D model from a container asset
+ * (typically a GLB) beneath an entity of its own, so the element's transform and tags place the
+ * instance in the scene. Its `<pc-node>` children override what the asset authored. Place it in the
+ * `<pc-scene>`, or nest it under a `<pc-entity>`, another `<pc-model>` or a `<pc-node>`.
  *
+ * @attribute {boolean} enabled - The enabled state of the model.
+ * @attribute {string} name - The name of the model.
+ * @attribute {string} position - The position of the model.
+ * @attribute {string} rotation - The rotation of the model.
+ * @attribute {string} scale - The scale of the model.
+ * @attribute {string} tags - The tags of the model.
+ * @attribute {string} onpointerenter - Script to run when the pointer moves onto the model.
+ * @attribute {string} onpointerleave - Script to run when the pointer moves off the model.
+ * @attribute {string} onpointermove - Script to run when the pointer moves over the model.
+ * @attribute {string} onpointerdown - Script to run when a pointer button is pressed over the
+ * model.
+ * @attribute {string} onpointerup - Script to run when a pointer button is released over the
+ * model.
+ * @fires {PointerEvent} pointerenter - Fired when the pointer moves onto the model.
+ * @fires {PointerEvent} pointerleave - Fired when the pointer moves off the model.
+ * @fires {PointerEvent} pointermove - Fired when the pointer moves over the model.
+ * @fires {PointerEvent} pointerdown - Fired when a pointer button is pressed over the model.
+ * @fires {PointerEvent} pointerup - Fired when a pointer button is released over the model.
  * @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.
@@ -2980,14 +3076,14 @@ const formatHierarchy = (root, counts) => {
  * error in `message`. Does not bubble. The element still becomes ready — readiness means the load
  * settled, not that it succeeded.
  */
-class ModelElement extends AsyncElement {
+class ModelElement extends EntityOwnerElement {
     _asset = '';
-    _entity = null;
+    _contentEntity = null;
     /**
-     * Incremented on every new load and on disconnect, and captured by a load when it starts. A
-     * load that resumes from an await or a load callback abandons itself if the value has moved
-     * on, so a superseded load can neither instantiate a second entity nor parent one that has
-     * since been destroyed.
+     * Incremented on every new load, on disconnect, and when the host entity dies, and captured
+     * by a load when it starts. A load that resumes from an await or a load callback abandons
+     * itself if the value has moved on, so a superseded load can neither instantiate a second
+     * content root nor parent one under a host a newer cycle has already replaced.
      */
     _loadGeneration = 0;
     /**
@@ -2998,12 +3094,13 @@ class ModelElement extends AsyncElement {
     _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.
-     * @returns The model's root entity, or `null`.
+     * The root entity of the instantiated model content, parented beneath the host entity.
+     * `null` until the container asset has loaded and been instantiated, after a failed load,
+     * and again once the element has been removed from the document.
+     * @returns The content root entity, or `null`.
      */
-    get entity() {
-        return this._entity;
+    get contentEntity() {
+        return this._contentEntity;
     }
     /**
      * Returns a snapshot of the instantiated node tree, or `null` while there is none (the
@@ -3015,12 +3112,13 @@ class ModelElement extends AsyncElement {
      * is the printable form.
      *
      * The snapshot is plain data, computed afresh each call: it does not follow later changes
-     * to the hierarchy, and mutating it changes nothing.
+     * to the hierarchy, and mutating it changes nothing. It covers the instantiated content
+     * only — the host entity the element fronts is not part of the asset's node tree.
      *
      * @returns The root of the instantiated node tree, or `null`.
      */
     hierarchy() {
-        const root = this._entity;
+        const root = this._contentEntity;
         if (!root) {
             return null;
         }
@@ -3060,18 +3158,53 @@ class ModelElement extends AsyncElement {
         // 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 closestApp = this.closestApp;
+        if (!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();
+        // If the app is already running, create the host immediately; during a boot, the app's
+        // own sweep does it. Either way, _onBuilt starts the content load once the host is
+        // parented.
+        if (closestApp._hierarchyReady) {
+            const app = closestApp.app;
+            this._createEntity(app);
+            this._buildHierarchy(app);
+            // A build that deferred (an unresolved pc-node above) defers the whole subtree with
+            // it - the node's bind sweeps it.
+            if (this._built) {
+                buildDescendantEntities(this, app);
+            }
+        }
     }
     disconnectedCallback() {
+        // Destroying the host destroys the instantiated content with it, and the destroy hook
+        // resets the element. The generation guard comes first so a load suspended on an await
+        // cannot resume against the torn-down element.
         this._loadGeneration++;
         this._detachLoadHandlers();
-        this._unloadModel();
-        this._resetReady();
+        this._entity?.destroy();
+    }
+    /**
+     * Starts (or restarts) the content load once the host has been parented. Readiness is not
+     * announced here — it tracks the content settling, not the host entering the scene graph.
+     */
+    _onBuilt() {
+        this._loadContent();
+    }
+    /**
+     * Extends the owner reset for the content: the engine's destroy cascade has already taken
+     * the content root down with the host subtree, so only the reference and the in-flight load
+     * are dropped here. The next build re-creates the host and re-instantiates the content.
+     *
+     * @param entity - The host entity that was destroyed.
+     */
+    _onEntityDestroy(entity) {
+        this._loadGeneration++;
+        this._detachLoadHandlers();
+        this._contentEntity = null;
+        super._onEntityDestroy(entity);
     }
     _detachLoadHandlers() {
         this._loadHandle?.off();
@@ -3080,51 +3213,34 @@ class ModelElement extends AsyncElement {
         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.
+     * Resolves readiness and dispatches the `load` event. Called once the instantiated content
+     * has been parented beneath the host — the host itself is already in the scene graph by
+     * then, so a ready model's content always has world transforms.
      */
     _announceLoad() {
         this._onReady();
         this.dispatchEvent(new Event('load'));
     }
     _instantiate(container) {
-        const generation = this._loadGeneration;
-        const entity = container.instantiateRenderEntity();
-        this._entity = entity;
-        // The parent's readiness re-arms when it is torn down, so these can resume in a later
-        // connection cycle. The entity is captured above and the generation re-checked, so a
-        // stale resume cannot parent an entity a newer cycle has already destroyed.
-        const parentEntityElement = this.closestEntity;
-        if (parentEntityElement) {
-            parentEntityElement.ready().then(() => {
-                if (generation !== this._loadGeneration) {
-                    return;
-                }
-                parentEntityElement.entity.addChild(entity);
-                this._announceLoad();
-            });
-        }
-        else {
-            const appElement = this.closestApp;
-            if (appElement) {
-                appElement.ready().then(() => {
-                    if (generation !== this._loadGeneration) {
-                        return;
-                    }
-                    appElement.app.root.addChild(entity);
-                    this._announceLoad();
-                });
-            }
-        }
-    }
-    async _loadModel() {
-        this._unloadModel();
+        const content = container.instantiateRenderEntity();
+        this._contentEntity = content;
+        this._entity.addChild(content);
+        this._announceLoad();
+    }
+    _destroyContent() {
+        this._contentEntity?.destroy();
+        this._contentEntity = null;
+    }
+    async _loadContent() {
+        // The old content goes down synchronously, so a reader that checks after an asset change
+        // never sees the outgoing hierarchy. The host survives - components and child entities
+        // attached to it carry over to the new content.
+        this._destroyContent();
         // Supersede any load already in flight - only the newest load may instantiate
         const generation = ++this._loadGeneration;
         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.
+        // content. A no-op on first connection, where readiness is still pending.
         this._resetReady();
         const appElement = this.closestApp;
         if (!appElement) {
@@ -3136,14 +3252,23 @@ class ModelElement extends AsyncElement {
         if (generation !== this._loadGeneration) {
             return;
         }
+        // The host may not be parented yet - a model under a pc-node that has not bound, reached
+        // through the asset setter. Nothing settles here: _onBuilt re-runs this load once the
+        // host builds.
+        if (!this._entity || !this._built) {
+            return;
+        }
+        if (this._asset === '') {
+            // No asset assigned is a settled selection: the element is a usable host (components
+            // attach, waiters resolve) with no content. Assigning an asset later re-arms.
+            this._onReady();
+            return;
+        }
         const asset = useAsset(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
+            // A non-empty id 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`);
-            }
+            console.warn(`pc-model could not find asset '${this._asset}' - model not created`);
             return;
         }
         if (asset.loaded) {
@@ -3165,7 +3290,7 @@ class ModelElement extends AsyncElement {
                 if (generation !== this._loadGeneration) {
                     return;
                 }
-                // A failed load settles readiness with a null entity, mirroring pc-asset:
+                // A failed load settles readiness with a null contentEntity, 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)
@@ -3174,10 +3299,6 @@ class ModelElement extends AsyncElement {
             });
         }
     }
-    _unloadModel() {
-        this._entity?.destroy();
-        this._entity = null;
-    }
     /**
      * Sets the id of the `pc-asset` to use for the model.
      * @param value - The asset ID.
@@ -3185,7 +3306,7 @@ class ModelElement extends AsyncElement {
     set asset(value) {
         this._asset = value;
         if (this.isConnected) {
-            this._loadModel();
+            this._loadContent();
         }
     }
     /**
@@ -3196,13 +3317,38 @@ class ModelElement extends AsyncElement {
         return this._asset;
     }
     static get observedAttributes() {
-        return ['asset'];
+        return ['asset', 'enabled', 'name', 'position', 'rotation', 'scale', 'tags', ...POINTER_ATTRIBUTES];
     }
     attributeChangedCallback(name, _oldValue, newValue) {
         switch (name) {
             case 'asset':
                 this.asset = newValue ?? '';
                 break;
+            case 'enabled':
+                this.enabled = parseBool(newValue, true);
+                break;
+            case 'name':
+                this.name = newValue ?? 'Untitled';
+                break;
+            case 'position':
+                this.position = parseVec3(newValue, Vec3.ZERO, name);
+                break;
+            case 'rotation':
+                this.rotation = parseVec3(newValue, Vec3.ZERO, name);
+                break;
+            case 'scale':
+                this.scale = parseVec3(newValue, Vec3.ONE, name);
+                break;
+            case 'tags':
+                this.tags = parseTags(newValue);
+                break;
+            case 'onpointerenter':
+            case 'onpointerleave':
+            case 'onpointerdown':
+            case 'onpointerup':
+            case 'onpointermove':
+                this._updateInlineHandler(name, newValue);
+                break;
         }
     }
 }
@@ -3293,7 +3439,7 @@ class ComponentElement extends AsyncElement {
             // A component can only exist on an entity, so an element placed outside one is inert.
             // It still becomes ready (with a null `component`), so warn rather than fail silently
             const label = this.id ? ` '${this.id}'` : '';
-            console.warn(`${this.tagName.toLowerCase()}${label} must be a descendant of pc-entity - component not added`);
+            console.warn(`${this.tagName.toLowerCase()}${label} must be a descendant of pc-entity, pc-model or pc-node - component not added`);
             return;
         }
         await entityElement.ready();
@@ -3381,8 +3527,9 @@ class ComponentElement extends AsyncElement {
     }
     /**
      * 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.
+     * element that is not a descendant of an entity-fronting element (`<pc-entity>`,
+     * `<pc-model>` or `<pc-node>`) — await {@link whenReady} or the element's `ready()` promise
+     * before accessing it.
      * @returns The component instance, or `null`.
      */
     get component() {
@@ -3435,6 +3582,13 @@ class ComponentElement extends AsyncElement {
  * the underlying {@link AnimComponent} (via {@link component}) for playback state beyond what
  * this element exposes.
  *
+ * Engine component: {@link AnimComponent} (`anim`).
+ *
+ * @elementSummary The `<pc-anim>` element plays animation clips over its entity's hierarchy, taken
+ * from `<pc-anim-clip>` children or from the enclosing `<pc-model>`'s own animations. The first
+ * clip plays automatically, and the `clip` attribute switches between them. Must be a child of a
+ * `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+ *
  * @category Components
  */
 class AnimComponentElement extends ComponentElement {
@@ -3456,6 +3610,11 @@ class AnimComponentElement extends ComponentElement {
      * The name of the active clip.
      */
     _clip = '';
+    /**
+     * The binding root this element last assigned through {@link _applyRootBone}, distinguishing
+     * its own writes from a `rootBone` assigned through the engine API — which is left alone.
+     */
+    _managedRootBone = null;
     /**
      * The element the model-readiness listener is attached to, held so disconnection can detach
      * it after `closestEntity` no longer resolves.
@@ -3481,27 +3640,71 @@ class AnimComponentElement extends ComponentElement {
      */
     _warnedClip = null;
     /**
-     * Rebinds when a model under the host announces readiness. The engine resolves each curve
-     * once, at the first tick after assignment, and never retries — and its mesh-instance
+     * Rebinds when a model that is not this component's host announces readiness — a sibling or
+     * deeper model whose content changed under the assigned clips. The engine resolves each
+     * curve once, at the first tick after assignment, and never retries — and its mesh-instance
      * broadcast fires before an instantiated hierarchy is parented, so a model that loads after
-     * the clips were assigned would otherwise stay silently unbound. A re-instantiation of the
-     * implicit clip source (the parent `<pc-model>`) means a new container, so the clip set
-     * refreshes instead — unless every clip declares its own asset, where a rebind suffices.
+     * the clips were assigned would otherwise stay silently unbound. The host model's own cycles
+     * are excluded: those re-enter through {@link initComponent}, which refreshes the whole clip
+     * set against the new container.
      */
     _onModelReady = (event) => {
         if (!(event.target instanceof ModelElement) || !this.component) {
             return;
         }
-        if (event.target === this.parentElement) {
-            const implicit = this._autoAssigned ||
-                [...this._assignedClips.values()].some(clip => !clip.asset);
-            if (implicit) {
-                this._refreshClips();
-                return;
-            }
+        // The host model's own readiness cycle already re-initialized this component through
+        // ComponentElement's host-ready listener, which is attached first and so has run by now.
+        // Acting here too would resolve every track twice and capture the playhead-restore
+        // snapshot mid-rebuild.
+        if (event.target === this._modelListenerTarget) {
+            return;
         }
+        // A model cycle can replace the skeleton source's host entity (a rebuild under a
+        // retargeting pc-node), so the binding root is re-asserted before the rebind.
+        this._applyRootBone();
         this.component.rebind();
     };
+    /**
+     * The model whose host entity scopes this component's curve binding: the parent `pc-model`,
+     * or the sole `pc-model` among the parent's direct children (the arrangement where clips
+     * live in a library asset beside the skeleton). `null` when there is no such model, or more
+     * than one — an ambiguous skeleton is left to the engine's name-based resolution.
+     */
+    _skeletonSource() {
+        const parent = this.parentElement;
+        if (parent instanceof ModelElement) {
+            return parent;
+        }
+        const models = parent ? parent.querySelectorAll(':scope > pc-model') : null;
+        return models?.length === 1 && models[0] instanceof ModelElement ? models[0] : null;
+    }
+    /**
+     * Keeps the component's binding root pointing at the skeleton source's host entity. The host
+     * wraps the instantiated content, so left at its default — the component's own entity — the
+     * engine binder mis-resolves curves that target the asset's root node: its fallback treats
+     * the graph as the asset root once the root is no longer a direct child.
+     *
+     * Authoritative in both directions for values this element assigned: a source appearing pins
+     * its host, and a source dissolving (the model gone, or a second model making the skeleton
+     * ambiguous) clears the pin rather than leaving it on a stale host. A root assigned through
+     * the engine API is never overwritten — the user's choice outranks the managed default.
+     * Writes are skipped while unchanged, because the engine setter itself triggers a rebind.
+     */
+    _applyRootBone() {
+        const component = this.component;
+        // A non-null root this element did not assign came through the engine API. A fresh
+        // component starts at null, which is always reclaimable.
+        if (component.rootBone !== null && component.rootBone !== this._managedRootBone) {
+            return;
+        }
+        const host = this._skeletonSource()?.entity ?? null;
+        if (component.rootBone !== host) {
+            // The engine setter accepts null - restoring the component's own entity as the
+            // binding graph - but its declared type does not
+            component.rootBone = host;
+        }
+        this._managedRootBone = host;
+    }
     /** @ignore */
     constructor() {
         super('anim');
@@ -3526,7 +3729,16 @@ class AnimComponentElement extends ComponentElement {
             host.addEventListener('ready', this._onModelReady);
             this._modelListenerTarget = host;
         }
-        this._applyClips();
+        this._applyRootBone();
+        if (this.component.baseLayer) {
+            // The component survived the host's readiness cycle (a pc-model reloading content on
+            // its stable host entity). A loaded graph cannot be reassigned in place, so drop it
+            // and reassign from the current source, restoring the active clip and playhead.
+            this._refreshClips();
+        }
+        else {
+            this._applyClips();
+        }
     }
     disconnectedCallback() {
         this._modelListenerTarget?.removeEventListener('ready', this._onModelReady);
@@ -3536,6 +3748,7 @@ class AnimComponentElement extends ComponentElement {
         this._sourceGeneration++;
         this._assignedClips.clear();
         this._autoAssigned = false;
+        this._managedRootBone = null;
         super.disconnectedCallback();
     }
     /**
@@ -3704,6 +3917,10 @@ class AnimComponentElement extends ComponentElement {
         if (!component) {
             return;
         }
+        // A clip-set change is also a chance for the skeleton source to have changed shape (a
+        // clip child appearing or leaving can accompany a model coming or going) - re-derive the
+        // binding root before the reassignment binds against it.
+        this._applyRootBone();
         const layer = component.baseLayer;
         const restore = layer ? {
             state: layer.activeState,
@@ -3990,6 +4207,10 @@ customElements.define('pc-anim', AnimComponentElement);
  * named; in a multi-track source the track named `name` is chosen, falling back to the first
  * with a warning. The element becomes ready once its resolved track is assigned.
  *
+ * @elementSummary The `<pc-anim-clip>` element declares one named animation clip on its parent
+ * `<pc-anim>`, taken from the `asset` it names or, without one, from the enclosing `<pc-model>`'s
+ * own animations. Must be a direct child of `<pc-anim>`.
+ *
  * @category Components
  */
 class AnimClipElement extends AsyncElement {
@@ -4311,14 +4532,20 @@ class AnimClipElement extends AsyncElement {
 customElements.define('pc-anim-clip', AnimClipElement);
 
 /**
- * The ListenerComponentElement interface provides properties and methods for manipulating
- * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-listener/ | `<pc-listener>`} elements.
- * The ListenerComponentElement interface also inherits the properties and methods of the
+ * The AudioListenerComponentElement interface provides properties and methods for manipulating
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-audio-listener/ | `<pc-audio-listener>`} elements.
+ * The AudioListenerComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link AudioListenerComponent} (`audiolistener`).
+ *
+ * @elementSummary The `<pc-audio-listener>` element makes its entity the point from which
+ * positional sounds are heard, typically the entity holding the `<pc-camera>`. Must be a child of a
+ * `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+ *
  * @category Components
  */
-class ListenerComponentElement extends ComponentElement {
+class AudioListenerComponentElement extends ComponentElement {
     /** @ignore */
     constructor() {
         super('audiolistener');
@@ -4331,7 +4558,7 @@ class ListenerComponentElement extends ComponentElement {
         return super.component;
     }
 }
-customElements.define('pc-listener', ListenerComponentElement);
+customElements.define('pc-audio-listener', AudioListenerComponentElement);
 
 const transitionModes = new Map([
     ['tint', BUTTON_TRANSITION_MODE_TINT],
@@ -4343,6 +4570,13 @@ const transitionModes = new Map([
  * The ButtonComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link ButtonComponent} (`button`).
+ *
+ * @elementSummary The `<pc-button>` element makes its entity respond to pointer input, tinting or
+ * swapping its image as the pointer hovers, presses and releases it. The entity also needs a
+ * `<pc-element>` with `use-input` set. Must be a child of a `<pc-entity>`, `<pc-model>` or
+ * `<pc-node>`.
+ *
  * @category Components
  */
 class ButtonComponentElement extends ComponentElement {
@@ -4423,7 +4657,9 @@ class ButtonComponentElement extends ComponentElement {
     }
     /**
      * Sets the reference (CSS selector, element id or entity name) to the `<pc-entity>` whose image
-     * element is used for visual transitions. Defaults to the button's own entity.
+     * element is used for visual transitions. Defaults to the button's own entity — inside a
+     * `<pc-model>`, that is the model's host entity, so supply an explicit reference to target a
+     * UI entity instead.
      * @param value - The image entity reference.
      */
     set image(value) {
@@ -4742,13 +4978,20 @@ const tonemaps = new Map([
  * The CameraComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link CameraComponent} (`camera`).
+ *
+ * @elementSummary The `<pc-camera>` element renders the scene from its entity's transform, with
+ * attributes for the projection, field of view, clip planes, clear color and tonemapping. Must be a
+ * child of a `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+ *
  * @category Components
  */
 class CameraComponentElement extends ComponentElement {
     _clearColor = new Color(0.75, 0.75, 0.75, 1);
     _clearColorBuffer = true;
+    _clearDepth = 1;
     _clearDepthBuffer = true;
-    _clearStencilBuffer = false;
+    _clearStencilBuffer = true;
     _cullFaces = true;
     _farClip = 1000;
     _flipFaces = false;
@@ -4771,6 +5014,7 @@ class CameraComponentElement extends ComponentElement {
         return {
             clearColor: this._clearColor,
             clearColorBuffer: this._clearColorBuffer,
+            clearDepth: this._clearDepth,
             clearDepthBuffer: this._clearDepthBuffer,
             clearStencilBuffer: this._clearStencilBuffer,
             cullFaces: this._cullFaces,
@@ -4789,9 +5033,31 @@ class CameraComponentElement extends ComponentElement {
             toneMapping: tonemaps.get(this._tonemap) ?? TONEMAP_NONE
         };
     }
-    get xrAvailable() {
+    /**
+     * Whether immersive AR is available. Independent of {@link vrAvailable}: a device can offer
+     * either mode without the other.
+     * @returns Whether immersive AR is available.
+     */
+    get arAvailable() {
+        return this._available(XRTYPE_AR);
+    }
+    /**
+     * Whether immersive VR is available. Independent of {@link arAvailable}: a device can offer
+     * either mode without the other.
+     * @returns Whether immersive VR is available.
+     */
+    get vrAvailable() {
+        return this._available(XRTYPE_VR);
+    }
+    /**
+     * Whether one XR session type is available on this device.
+     *
+     * @param type - The XR session type to test.
+     * @returns Whether that type is available.
+     */
+    _available(type) {
         const xrManager = this.component?.system.app.xr;
-        return xrManager && xrManager.supported && xrManager.isAvailable(XRTYPE_VR);
+        return Boolean(xrManager?.supported && xrManager.isAvailable(type));
     }
     /**
      * Starts the camera in XR mode.
@@ -4799,11 +5065,13 @@ class CameraComponentElement extends ComponentElement {
      * @param space - The space to start the camera in.
      */
     startXr(type, space) {
-        if (this.component && this.xrAvailable) {
+        // Gated on the mode being started, not on XR in general: a device that offers only
+        // one of the two would otherwise accept a session it cannot serve
+        if (this.component && this._available(type)) {
             this.component.startXr(type, space, {
                 callback: (err) => {
                     if (err)
-                        console.error(`WebXR Immersive VR failed to start: ${err.message}`);
+                        console.error(`WebXR ${type} failed to start: ${err.message}`);
                 }
             });
         }
@@ -4857,6 +5125,23 @@ class CameraComponentElement extends ComponentElement {
     get clearColorBuffer() {
         return this._clearColorBuffer;
     }
+    /**
+     * Sets the depth value the depth buffer is cleared to. Defaults to 1.
+     * @param value - The clear depth value.
+     */
+    set clearDepth(value) {
+        this._clearDepth = value;
+        if (this.component) {
+            this.component.clearDepth = value;
+        }
+    }
+    /**
+     * Gets the depth value the depth buffer is cleared to.
+     * @returns The clear depth value.
+     */
+    get clearDepth() {
+        return this._clearDepth;
+    }
     /**
      * Sets the clear depth buffer of the camera.
      * @param value - The clear depth buffer.
@@ -5135,6 +5420,7 @@ class CameraComponentElement extends ComponentElement {
             ...super.observedAttributes,
             'clear-color',
             'clear-color-buffer',
+            'clear-depth',
             'clear-depth-buffer',
             'clear-stencil-buffer',
             'cull-faces',
@@ -5162,11 +5448,14 @@ class CameraComponentElement extends ComponentElement {
             case 'clear-color-buffer':
                 this.clearColorBuffer = parseBool(newValue, true);
                 break;
+            case 'clear-depth':
+                this.clearDepth = parseNumber(newValue, 1, name);
+                break;
             case 'clear-depth-buffer':
                 this.clearDepthBuffer = parseBool(newValue, true);
                 break;
             case 'clear-stencil-buffer':
-                this.clearStencilBuffer = parseBool(newValue, false);
+                this.clearStencilBuffer = parseBool(newValue, true);
                 break;
             case 'cull-faces':
                 this.cullFaces = parseBool(newValue, true);
@@ -5227,6 +5516,12 @@ customElements.define('pc-camera', CameraComponentElement);
  * 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.
  *
+ * Engine component: {@link CollisionComponent} (`collision`).
+ *
+ * @elementSummary The `<pc-collision>` element gives its entity a collision shape — a box, sphere,
+ * capsule, cone, cylinder or mesh — for the physics simulation to collide against. Pair it with a
+ * `<pc-rigid-body>`. Must be a child of a `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+ *
  * @category Components
  */
 class CollisionComponentElement extends ComponentElement {
@@ -5263,7 +5558,9 @@ class CollisionComponentElement extends ComponentElement {
      * 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.
+     * `renderAsset` is never overwritten. A `pc-model` host entity never carries a render
+     * component (the instantiated content beneath it does), so a mesh collider that should take
+     * an asset's geometry belongs on a bound `pc-node`.
      */
     _applyMeshGeometryDefault() {
         const component = this.component;
@@ -5408,6 +5705,17 @@ customElements.define('pc-collision', CollisionComponentElement);
  * The ElementComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Despite the name, this is not a base class or a generic wrapper: it is the engine's 2D UI
+ * component, which gives its host entity a rectangle in a `<pc-screen>` hierarchy that draws
+ * either an image, a line of text or nothing (`type="image"`, `"text"` or `"group"`). The tag
+ * spells the engine component it adds, as every component element does.
+ *
+ * Engine component: {@link ElementComponent} (`element`).
+ *
+ * @elementSummary The `<pc-element>` element gives its entity a 2D UI rectangle inside a
+ * `<pc-screen>` hierarchy, drawing an image, a line of text or nothing (`type="image"`, `"text"` or
+ * `"group"`). Must be a child of a `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+ *
  * @category Components
  */
 class ElementComponentElement extends ComponentElement {
@@ -6092,10 +6400,17 @@ customElements.define('pc-element', ElementComponentElement);
  * a rigid body component; leaving `entity-b` empty constrains `entity-a` to a fixed point in world
  * space. The underlying engine component is in alpha, so its API may change.
  *
+ * @elementSummary The `<pc-joint>` element constrains two rigid bodies to each other — a hinged
+ * door, a swinging chain, a sliding drawer. Its entity's transform is the joint frame, and
+ * `entity-a` and `entity-b` name the bodies. Must be a child of a `<pc-entity>`, `<pc-model>` or
+ * `<pc-node>`.
+ *
  * @fires {CustomEvent} break - Fired when the impulse on the joint exceeds `break-impulse` and the
  * constraint breaks. A broken joint no longer constrains its bodies; calling `refreshFrames()` on
  * the underlying component re-attaches it. Bubbles and is composed.
  *
+ * Engine component: {@link JointComponent} (`joint`).
+ *
  * @category Components
  */
 class JointComponentElement extends ComponentElement {
@@ -6954,10 +7269,16 @@ customElements.define('pc-joint', JointComponentElement);
 
 /**
  * The LayoutChildComponentElement interface provides properties and methods for manipulating
- * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-layoutchild/ | `<pc-layoutchild>`} elements.
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-layout-child/ | `<pc-layout-child>`} elements.
  * The LayoutChildComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link LayoutChildComponent} (`layoutchild`).
+ *
+ * @elementSummary The `<pc-layout-child>` element controls how its entity is sized by the
+ * `<pc-layout-group>` above it, through minimum and maximum sizes and fit proportions. Must be a
+ * child of a `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+ *
  * @category Components
  */
 class LayoutChildComponentElement extends ComponentElement {
@@ -7150,7 +7471,7 @@ class LayoutChildComponentElement extends ComponentElement {
         }
     }
 }
-customElements.define('pc-layoutchild', LayoutChildComponentElement);
+customElements.define('pc-layout-child', LayoutChildComponentElement);
 
 const orientations$1 = new Map([
     ['horizontal', ORIENTATION_HORIZONTAL],
@@ -7164,10 +7485,16 @@ const fittings = new Map([
 ]);
 /**
  * The LayoutGroupComponentElement interface provides properties and methods for manipulating
- * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-layoutgroup/ | `<pc-layoutgroup>`} elements.
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-layout-group/ | `<pc-layout-group>`} elements.
  * The LayoutGroupComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link LayoutGroupComponent} (`layoutgroup`).
+ *
+ * @elementSummary The `<pc-layout-group>` element arranges its entity's children in a row or
+ * column, with spacing, padding, alignment and fitting. Must be a child of a `<pc-entity>`,
+ * `<pc-model>` or `<pc-node>`.
+ *
  * @category Components
  */
 class LayoutGroupComponentElement extends ComponentElement {
@@ -7407,7 +7734,7 @@ class LayoutGroupComponentElement extends ComponentElement {
         }
     }
 }
-customElements.define('pc-layoutgroup', LayoutGroupComponentElement);
+customElements.define('pc-layout-group', LayoutGroupComponentElement);
 
 const shadowTypes = new Map([
     ['pcf1-16f', SHADOW_PCF1_16F],
@@ -7426,23 +7753,32 @@ const shadowTypes = new Map([
  * The LightComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link LightComponent} (`light`).
+ *
+ * @elementSummary The `<pc-light>` element lights the scene from its entity — as a directional,
+ * omni or spot light — with attributes for color, intensity, range and shadows. Must be a child of
+ * a `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+ *
  * @category Components
  */
 class LightComponentElement extends ComponentElement {
+    _cascadeBlend = 0;
+    _cascadeDistribution = 0.5;
     _castShadows = false;
     _color = new Color(1, 1, 1);
     _innerConeAngle = 40;
     _intensity = 1;
-    _normalOffsetBias = 0.05;
+    _normalOffsetBias = 0;
+    _numCascades = 1;
     _outerConeAngle = 45;
     _range = 10;
-    _shadowBias = 0.2;
-    _shadowDistance = 16;
+    _shadowBias = 0.05;
+    _shadowDistance = 40;
     _shadowIntensity = 1;
     _shadowResolution = 1024;
     _shadowType = 'pcf3-32f';
     _type = 'directional';
-    _vsmBias = 0.01;
+    _vsmBias = 0.0025;
     _vsmBlurSize = 11;
     _penumbraSize = 1;
     _penumbraFalloff = 1;
@@ -7454,11 +7790,14 @@ class LightComponentElement extends ComponentElement {
     }
     getInitialComponentData() {
         return {
+            cascadeBlend: this._cascadeBlend,
+            cascadeDistribution: this._cascadeDistribution,
             castShadows: this._castShadows,
             color: this._color,
             innerConeAngle: this._innerConeAngle,
             intensity: this._intensity,
             normalOffsetBias: this._normalOffsetBias,
+            numCascades: this._numCascades,
             outerConeAngle: this._outerConeAngle,
             penumbraFalloff: this._penumbraFalloff,
             penumbraSize: this._penumbraSize,
@@ -7469,7 +7808,7 @@ class LightComponentElement extends ComponentElement {
             shadowIntensity: this._shadowIntensity,
             shadowResolution: this._shadowResolution,
             shadowSamples: this._shadowSamples,
-            shadowType: shadowTypes.get(this._shadowType),
+            shadowType: shadowTypes.get(this._shadowType) ?? SHADOW_PCF3_32F,
             type: this._type,
             vsmBias: this._vsmBias,
             vsmBlurSize: this._vsmBlurSize
@@ -7482,6 +7821,47 @@ class LightComponentElement extends ComponentElement {
     get component() {
         return super.component;
     }
+    /**
+     * Sets the fraction of each shadow cascade that is blended into the next one, from 0 (no
+     * blending) to 1, which applies only to `directional` lights with `num-cascades` greater than
+     * 1. Defaults to 0.
+     * @param value - The cascade blend factor.
+     */
+    set cascadeBlend(value) {
+        this._cascadeBlend = value;
+        if (this.component) {
+            this.component.cascadeBlend = value;
+        }
+    }
+    /**
+     * Gets the cascade blend factor of the light, from 0 (no blending) to 1, which applies only to
+     * `directional` lights with `num-cascades` greater than 1.
+     * @returns The cascade blend factor.
+     */
+    get cascadeBlend() {
+        return this._cascadeBlend;
+    }
+    /**
+     * Sets the distribution of the camera frustum split between shadow cascades, from 0 (linear
+     * split) to 1 (logarithmic split, concentrating shadow resolution near the camera), which
+     * applies only to `directional` lights with `num-cascades` greater than 1. Defaults to 0.5.
+     * @param value - The cascade distribution.
+     */
+    set cascadeDistribution(value) {
+        this._cascadeDistribution = value;
+        if (this.component) {
+            this.component.cascadeDistribution = value;
+        }
+    }
+    /**
+     * Gets the cascade distribution of the light, from 0 (linear split) to 1 (logarithmic split,
+     * concentrating shadow resolution near the camera), which applies only to `directional` lights
+     * with `num-cascades` greater than 1.
+     * @returns The cascade distribution.
+     */
+    get cascadeDistribution() {
+        return this._cascadeDistribution;
+    }
     /**
      * Sets the cast shadows flag of the light.
      * @param value - The cast shadows flag.
@@ -7567,6 +7947,25 @@ class LightComponentElement extends ComponentElement {
     get normalOffsetBias() {
         return this._normalOffsetBias;
     }
+    /**
+     * Sets the number of shadow cascades of the light, an integer from 1 (no cascades) to 4, which
+     * applies only to `directional` lights. Defaults to 1.
+     * @param value - The number of shadow cascades.
+     */
+    set numCascades(value) {
+        this._numCascades = value;
+        if (this.component) {
+            this.component.numCascades = value;
+        }
+    }
+    /**
+     * Gets the number of shadow cascades of the light, an integer from 1 (no cascades) to 4, which
+     * applies only to `directional` lights.
+     * @returns The number of shadow cascades.
+     */
+    get numCascades() {
+        return this._numCascades;
+    }
     /**
      * Sets the outer cone angle of the light.
      * @param value - The outer cone angle.
@@ -7819,11 +8218,14 @@ class LightComponentElement extends ComponentElement {
     static get observedAttributes() {
         return [
             ...super.observedAttributes,
-            'color',
+            'cascade-blend',
+            'cascade-distribution',
             'cast-shadows',
-            'intensity',
+            'color',
             'inner-cone-angle',
+            'intensity',
             'normal-offset-bias',
+            'num-cascades',
             'outer-cone-angle',
             'penumbra-falloff',
             'penumbra-size',
@@ -7843,12 +8245,18 @@ class LightComponentElement extends ComponentElement {
     attributeChangedCallback(name, _oldValue, newValue) {
         super.attributeChangedCallback(name, _oldValue, newValue);
         switch (name) {
-            case 'color':
-                this.color = parseColor(newValue, Color.WHITE, name);
+            case 'cascade-blend':
+                this.cascadeBlend = parseNumber(newValue, 0, name);
+                break;
+            case 'cascade-distribution':
+                this.cascadeDistribution = parseNumber(newValue, 0.5, name);
                 break;
             case 'cast-shadows':
                 this.castShadows = parseBool(newValue, false);
                 break;
+            case 'color':
+                this.color = parseColor(newValue, Color.WHITE, name);
+                break;
             case 'inner-cone-angle':
                 this.innerConeAngle = parseNumber(newValue, 40, name);
                 break;
@@ -7856,7 +8264,10 @@ class LightComponentElement extends ComponentElement {
                 this.intensity = parseNumber(newValue, 1, name);
                 break;
             case 'normal-offset-bias':
-                this.normalOffsetBias = parseNumber(newValue, 0.05, name);
+                this.normalOffsetBias = parseNumber(newValue, 0, name);
+                break;
+            case 'num-cascades':
+                this.numCascades = parseNumber(newValue, 1, name);
                 break;
             case 'outer-cone-angle':
                 this.outerConeAngle = parseNumber(newValue, 45, name);
@@ -7871,20 +8282,20 @@ class LightComponentElement extends ComponentElement {
                 this.range = parseNumber(newValue, 10, name);
                 break;
             case 'shadow-bias':
-                this.shadowBias = parseNumber(newValue, 0.2, name);
-                break;
-            case 'shadow-distance':
-                this.shadowDistance = parseNumber(newValue, 16, name);
+                this.shadowBias = parseNumber(newValue, 0.05, name);
                 break;
             case 'shadow-blocker-samples':
                 this.shadowBlockerSamples = parseNumber(newValue, 16, name);
                 break;
-            case 'shadow-resolution':
-                this.shadowResolution = parseNumber(newValue, 1024, name);
+            case 'shadow-distance':
+                this.shadowDistance = parseNumber(newValue, 40, name);
                 break;
             case 'shadow-intensity':
                 this.shadowIntensity = parseNumber(newValue, 1, name);
                 break;
+            case 'shadow-resolution':
+                this.shadowResolution = parseNumber(newValue, 1024, name);
+                break;
             case 'shadow-samples':
                 this.shadowSamples = parseNumber(newValue, 16, name);
                 break;
@@ -7895,7 +8306,7 @@ class LightComponentElement extends ComponentElement {
                 this.type = parseEnum(newValue, ['directional', 'omni', 'spot'], 'directional', name);
                 break;
             case 'vsm-bias':
-                this.vsmBias = parseNumber(newValue, 0.01, name);
+                this.vsmBias = parseNumber(newValue, 0.0025, name);
                 break;
             case 'vsm-blur-size':
                 this.vsmBlurSize = parseNumber(newValue, 11, name);
@@ -7907,10 +8318,16 @@ customElements.define('pc-light', LightComponentElement);
 
 /**
  * The ParticleSystemComponentElement interface provides properties and methods for manipulating
- * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-particles/ | `<pc-particles>`} elements.
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-particle-system/ | `<pc-particle-system>`} elements.
  * The ParticleSystemComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link ParticleSystemComponent} (`particlesystem`).
+ *
+ * @elementSummary The `<pc-particle-system>` element emits particles from its entity, with
+ * attributes for the emitter's shape, rate, lifetime, textures and blending. Must be a child of a
+ * `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+ *
  * @category Components
  */
 class ParticleSystemComponentElement extends ComponentElement {
@@ -8029,7 +8446,7 @@ class ParticleSystemComponentElement extends ComponentElement {
         }
     }
 }
-customElements.define('pc-particles', ParticleSystemComponentElement);
+customElements.define('pc-particle-system', ParticleSystemComponentElement);
 
 const blendTypes = new Map([
     ['none', BLEND_NONE],
@@ -8059,6 +8476,8 @@ const occludeSpeculars = new Map([
     ['ao', SPECOCC_AO],
     ['gloss-dependent', SPECOCC_GLOSSDEPENDENT]
 ]);
+// The DITHER_* constants are strings whose values are exactly these names, so a parsed value is
+// assigned to the material unchanged rather than mapped through a table.
 const opacityDithers = ['none', 'bayer8', 'bluenoise', 'ignnoise'];
 const colorChannels = ['r', 'g', 'b', 'a', 'rgb'];
 const scalarChannels = ['r', 'g', 'b', 'a'];
@@ -8095,6 +8514,10 @@ const roughnessAliases = ['roughness', 'roughness-map'];
  * 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.
  *
+ * @elementSummary The `<pc-material>` element defines a physically based material, which
+ * `<pc-render>` elements apply by naming its `id`. It is metal/rough by default, with `metalness`
+ * starting at 0. Must be a direct child of `<pc-app>`.
+ *
  * @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
@@ -10261,6 +10684,13 @@ customElements.define('pc-material', MaterialElement);
  * to `box`). It does not cover the engine's `asset` render type, since there is no way to supply
  * a render asset here — use `pc-model` for glTF content instead.
  *
+ * Engine component: {@link RenderComponent} (`render`).
+ *
+ * @elementSummary The `<pc-render>` element renders one of the engine's built-in primitives at its
+ * entity — box, sphere, capsule, cone, cylinder or plane — shaded by the `<pc-material>` its
+ * `material` attribute names. For glTF content, use `<pc-model>` instead. Must be a child of a
+ * `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+ *
  * @category Components
  */
 class RenderComponentElement extends ComponentElement {
@@ -10385,10 +10815,17 @@ customElements.define('pc-render', RenderComponentElement);
 
 /**
  * The RigidBodyComponentElement interface provides properties and methods for manipulating
- * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-rigidbody/ | `<pc-rigidbody>`} elements.
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-rigid-body/ | `<pc-rigid-body>`} elements.
  * The RigidBodyComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link RigidBodyComponent} (`rigidbody`).
+ *
+ * @elementSummary The `<pc-rigid-body>` element hands its entity to the physics simulation, with
+ * attributes for its type, mass, friction and restitution. It needs a sibling `<pc-collision>` for
+ * its shape, and `Ammo` loaded through `<pc-wasm>`. Must be a child of a `<pc-entity>`,
+ * `<pc-model>` or `<pc-node>`.
+ *
  * @category Components
  */
 class RigidBodyComponentElement extends ComponentElement {
@@ -10580,7 +11017,7 @@ class RigidBodyComponentElement extends ComponentElement {
         }
     }
 }
-customElements.define('pc-rigidbody', RigidBodyComponentElement);
+customElements.define('pc-rigid-body', RigidBodyComponentElement);
 
 // The engine's SCALEMODE_* constants are the strings 'none' and 'blend', so this map happens to be
 // an identity. It is still the right shape: it supplies parseEnum's valid-name list, it is what the
@@ -10596,6 +11033,12 @@ const scaleModes = new Map([
  * The ScreenComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link ScreenComponent} (`screen`).
+ *
+ * @elementSummary The `<pc-screen>` element gives its entity a 2D space — in screen space or in the
+ * world — that a hierarchy of `<pc-element>` descendants lays out inside. Must be a child of a
+ * `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+ *
  * @category Components
  */
 class ScreenComponentElement extends ComponentElement {
@@ -10748,6 +11191,12 @@ const orientations = new Map([
  * The ScrollbarComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link ScrollbarComponent} (`scrollbar`).
+ *
+ * @elementSummary The `<pc-scrollbar>` element gives its entity a draggable handle reporting a
+ * position from 0 to 1, which a `<pc-scroll-view>` references to scroll its content. Must be a
+ * child of a `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+ *
  * @category Components
  */
 class ScrollbarComponentElement extends ComponentElement {
@@ -10883,10 +11332,16 @@ const visibilities = new Map([
 ]);
 /**
  * The ScrollViewComponentElement interface provides properties and methods for manipulating
- * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-scrollview/ | `<pc-scrollview>`} elements.
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-scroll-view/ | `<pc-scroll-view>`} elements.
  * The ScrollViewComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link ScrollViewComponent} (`scrollview`).
+ *
+ * @elementSummary The `<pc-scroll-view>` element scrolls a larger content entity within a clipped
+ * viewport at its entity, optionally driven by the `<pc-scrollbar>` elements it references. Must be
+ * a child of a `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+ *
  * @category Components
  */
 class ScrollViewComponentElement extends ComponentElement {
@@ -11245,11 +11700,11 @@ class ScrollViewComponentElement extends ComponentElement {
         }
     }
 }
-customElements.define('pc-scrollview', ScrollViewComponentElement);
+customElements.define('pc-scroll-view', ScrollViewComponentElement);
 
 /**
- * The ScriptElement interface provides properties and methods for manipulating
- * `<pc-script>` elements. The ScriptElement interface also inherits the properties and
+ * The ScriptInstanceElement interface provides properties and methods for manipulating
+ * `<pc-script-instance>` elements. The ScriptInstanceElement interface also inherits the properties and
  * methods of the {@link AsyncElement} interface.
  *
  * Script attributes can be supplied through two channels:
@@ -11271,7 +11726,11 @@ customElements.define('pc-scrollview', ScrollViewComponentElement);
  * new-name one, re-applying both attribute channels to it.
  *
  * The element becomes ready once its script instance has been created by the parent
- * `<pc-scripts>` element.
+ * `<pc-script>` element.
+ *
+ * @elementSummary The `<pc-script-instance>` element attaches one script class, named by `name`, to
+ * the entity of its parent `<pc-script>`. Its other attributes set script attributes of the same
+ * name, and `attributes` takes a JSON object instead. Must be a direct child of `<pc-script>`.
  *
  * @fires {CustomEvent} scriptattributeschange - Fired when the script's attributes change. The
  * `detail` carries the new `attributes` object. Bubbles.
@@ -11280,11 +11739,11 @@ customElements.define('pc-scrollview', ScrollViewComponentElement);
  * @fires {CustomEvent} scriptnamechange - Fired when the script is renamed on a live element. The
  * `detail` carries `oldName` and `newName`. Bubbles.
  */
-class ScriptElement extends AsyncElement {
+class ScriptInstanceElement extends AsyncElement {
     _attributes = {};
     _enabled = true;
     /**
-     * The Script instance created for this element by its parent `<pc-scripts>` element.
+     * The Script instance created for this element by its parent `<pc-script>` element.
      * @internal
      */
     _script = null;
@@ -11330,11 +11789,11 @@ class ScriptElement extends AsyncElement {
     }
     /**
      * Sets the name of the script to create. The `name` attribute is the single source of truth
-     * (it is what the parent `<pc-scripts>` element reads when creating the instance), so the
+     * (it is what the parent `<pc-script>` element reads when creating the instance), so the
      * property writes through to it — assigning before insertion works as expected:
      *
      * ```js
-     * const script = document.createElement('pc-script');
+     * const script = document.createElement('pc-script-instance');
      * script.name = 'rotate';
      * scriptsElement.appendChild(script);
      * await script.ready();
@@ -11361,10 +11820,10 @@ class ScriptElement extends AsyncElement {
         return this._script;
     }
     connectedCallback() {
-        // Script instances are created by the parent pc-scripts element, so an element placed
+        // Script instances are created by the parent pc-script element, so an element placed
         // anywhere else is inert and never becomes ready - warn rather than hang silently
-        if (this.parentElement?.tagName !== 'PC-SCRIPTS') {
-            console.warn(`pc-script '${this.getAttribute('name')}' must be a direct child of pc-scripts - script not created`);
+        if (this.parentElement?.tagName !== 'PC-SCRIPT') {
+            console.warn(`pc-script-instance '${this.getAttribute('name')}' must be a direct child of pc-script - script not created`);
         }
     }
     disconnectedCallback() {
@@ -11375,7 +11834,7 @@ class ScriptElement extends AsyncElement {
         this._resetReady();
     }
     /**
-     * Called by the parent `<pc-scripts>` element when the script instance has been created.
+     * Called by the parent `<pc-script>` element when the script instance has been created.
      * Creation can happen more than once per connection (a runtime `name` change recreates the
      * instance), but `_onReady` signals readiness at most once per cycle.
      * @internal
@@ -11397,7 +11856,7 @@ class ScriptElement extends AsyncElement {
                     this.scriptAttributes = JSON.parse(newValue);
                 }
                 catch (error) {
-                    console.warn(`Invalid 'attributes' JSON on pc-script '${this.getAttribute('name')}': ${error.message}`);
+                    console.warn(`Invalid 'attributes' JSON on pc-script-instance '${this.getAttribute('name')}': ${error.message}`);
                 }
                 break;
             case 'enabled':
@@ -11417,14 +11876,14 @@ class ScriptElement extends AsyncElement {
         }
     }
 }
-customElements.define('pc-script', ScriptElement);
+customElements.define('pc-script-instance', ScriptInstanceElement);
 
 /**
- * Attributes on `pc-script` that never map to script attributes: the element's own API (derived
+ * Attributes on `pc-script-instance` that never map to script attributes: the element's own API (derived
  * from its observed attributes) plus reserved and global HTML attribute names.
  */
 const RESERVED_ATTRIBUTES = new Set([
-    ...ScriptElement.observedAttributes,
+    ...ScriptInstanceElement.observedAttributes,
     'accesskey',
     'autocapitalize',
     'autofocus',
@@ -11455,7 +11914,7 @@ const RESERVED_ATTRIBUTES = new Set([
     'translate'
 ]);
 /**
- * Checks whether a `pc-script` attribute name is reserved (and so never maps to a script
+ * Checks whether a `pc-script-instance` attribute name is reserved (and so never maps to a script
  * attribute). Reserved names are the element's own API, global HTML attribute names, `data-*`
  * and `aria-*` attributes, names starting with `_` (framework-stamped attributes), and real
  * inline event handler names (`onclick` etc. — detected via the platform, so script attributes
@@ -11611,10 +12070,15 @@ const findCaseMatch = (script, key) => {
 };
 /**
  * The ScriptComponentElement interface provides properties and methods for manipulating
- * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-scripts/ | `<pc-scripts>`} elements.
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-script/ | `<pc-script>`} elements.
  * The ScriptComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link ScriptComponent} (`script`).
+ *
+ * @elementSummary The `<pc-script>` element holds the `<pc-script-instance>` children that attach
+ * scripts to its entity. Must be a child of a `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+ *
  * @category Components
  */
 class ScriptComponentElement extends ComponentElement {
@@ -11631,14 +12095,23 @@ class ScriptComponentElement extends ComponentElement {
     }
     connectedCallback() {
         // (Re-)observe on every connection - disconnectedCallback disconnects the observer.
-        // Attribute changes on child pc-script elements are watched here too: per-property
+        // Attribute changes on child pc-script-instance elements are watched here too: per-property
         // script attributes are not statically known, so they cannot use observedAttributes.
         this.observer.observe(this, { childList: true, subtree: true, attributes: true });
         return super.connectedCallback();
     }
     initComponent() {
-        // Handle initial script elements
-        this.querySelectorAll(':scope > pc-script').forEach((scriptElement) => {
+        this.querySelectorAll(':scope > pc-script-instance').forEach((scriptElement) => {
+            // A host readiness cycle re-runs this against a component that can have survived it
+            // (a pc-model reloading content on its stable host entity). The engine rejects a
+            // duplicate create - returning null, silently in production builds - which would
+            // skip attribute application entirely. A surviving instance is re-asserted instead,
+            // so both cycle outcomes leave the component reflecting the element's declared state.
+            const script = this.scriptFor(scriptElement);
+            if (script) {
+                this.applyDeclaredState(script, scriptElement);
+                return;
+            }
             this.createScript(scriptElement);
         });
     }
@@ -11772,9 +12245,9 @@ class ScriptComponentElement extends ComponentElement {
         this.mergeDeep(script, converted);
     }
     /**
-     * Returns the camelCase keys of the per-property attributes present on a `pc-script`
+     * Returns the camelCase keys of the per-property attributes present on a `pc-script-instance`
      * element.
-     * @param scriptElement - The `pc-script` element.
+     * @param scriptElement - The `pc-script-instance` element.
      * @returns The camelCase keys.
      */
     inlineKeys(scriptElement) {
@@ -11787,10 +12260,10 @@ class ScriptComponentElement extends ComponentElement {
         return keys;
     }
     /**
-     * Resolves the script instance owned by a `pc-script` element. Returns `null` when the
+     * Resolves the script instance owned by a `pc-script-instance` element. Returns `null` when the
      * element has no created script, or when its name resolves to a script created by a
      * different element (e.g. a duplicate-named sibling).
-     * @param scriptElement - The `pc-script` element.
+     * @param scriptElement - The `pc-script-instance` element.
      * @returns The owned script, or `null`.
      */
     scriptFor(scriptElement) {
@@ -11819,7 +12292,7 @@ class ScriptComponentElement extends ComponentElement {
         }
     }
     /**
-     * Handles a runtime `name` change on a child `pc-script`, swapping the engine script instance
+     * Handles a runtime `name` change on a child `pc-script-instance`, swapping the engine script instance
      * to match. Without this the element would keep pointing at the old-name instance: the old
      * script would go on running while every subsequent update (attribute changes, enable
      * changes, destruction on removal) resolved the new name and silently no-opped.
@@ -11830,8 +12303,8 @@ class ScriptComponentElement extends ComponentElement {
      */
     handleScriptNameChange(event) {
         const scriptElement = event.target;
-        // Only direct children are managed, matching initComponent's ':scope > pc-script'
-        // contract - the event bubbles, so a deeper pc-script must not be created here
+        // Only direct children are managed, matching initComponent's ':scope > pc-script-instance'
+        // contract - the event bubbles, so a deeper pc-script-instance must not be created here
         if (scriptElement.parentElement !== this)
             return;
         // Before the component exists there is nothing to swap: initComponent creates from
@@ -11848,11 +12321,11 @@ class ScriptComponentElement extends ComponentElement {
         this.createScript(scriptElement);
     }
     /**
-     * Creates the script instance for a `pc-script` element. The instance is created disabled,
+     * Creates the script instance for a `pc-script-instance` element. The instance is created disabled,
      * the element's converted attributes are merged over the instance's defaults (which is what
      * allows plain numeric arrays to be typed against those defaults), and only then is the
      * declared enabled state applied — so `initialize()` runs with every attribute in place.
-     * @param scriptElement - The `pc-script` element to create the script instance for.
+     * @param scriptElement - The `pc-script-instance` element to create the script instance for.
      * @returns The created script, or `null`.
      */
     createScript(scriptElement) {
@@ -11863,21 +12336,30 @@ class ScriptComponentElement extends ComponentElement {
         if (!script)
             return null;
         scriptElement._script = script;
-        // The JSON blob first with per-property-shadowed keys stripped, then the per-property
-        // attributes: each property is written exactly once and individual attributes win
+        this.applyDeclaredState(script, scriptElement);
+        scriptElement._onScriptCreated();
+        return script;
+    }
+    /**
+     * Applies a `pc-script-instance` element's declared state to a script instance: the `attributes` JSON
+     * first with per-property-shadowed keys stripped, then the per-property attributes — each
+     * property is written exactly once and individual attributes win — and finally the declared
+     * enabled state, so `initialize()` runs with every attribute in place.
+     * @param script - The script instance.
+     * @param scriptElement - The `pc-script-instance` element holding the declared state.
+     */
+    applyDeclaredState(script, scriptElement) {
         this.applyAttributes(script, scriptElement.scriptAttributes, this.inlineKeys(scriptElement));
         this.applyInlineAttributes(script, scriptElement);
         script.enabled = scriptElement.enabled;
-        scriptElement._onScriptCreated();
-        return script;
     }
     /**
-     * Applies the per-property attributes present on a `pc-script` element — any attribute that
+     * Applies the per-property attributes present on a `pc-script-instance` element — any attribute that
      * is not part of the element's own API or a reserved HTML attribute name. These are applied
      * after the `attributes` JSON, so an individual attribute always takes precedence over the
      * blob.
      * @param script - The script to apply the attributes to.
-     * @param scriptElement - The `pc-script` element holding the attributes.
+     * @param scriptElement - The `pc-script-instance` element holding the attributes.
      */
     applyInlineAttributes(script, scriptElement) {
         const scriptName = scriptElement.getAttribute('name') ?? '';
@@ -11888,10 +12370,10 @@ class ScriptComponentElement extends ComponentElement {
         }
     }
     /**
-     * Applies a single per-property attribute change to the script of a `pc-script` element.
+     * Applies a single per-property attribute change to the script of a `pc-script-instance` element.
      * When the attribute has been removed, the value from the `attributes` JSON (if any) takes
      * effect again.
-     * @param scriptElement - The `pc-script` element whose attribute changed.
+     * @param scriptElement - The `pc-script-instance` element whose attribute changed.
      * @param attributeName - The name of the changed attribute.
      */
     applyScriptProperty(scriptElement, attributeName) {
@@ -11927,7 +12409,7 @@ class ScriptComponentElement extends ComponentElement {
         try {
             const current = script[key];
             if (typeof current === 'function' || SCRIPT_API_MEMBERS.has(key)) {
-                console.warn(`Ignoring attribute '${attributeName}' on pc-script '${scriptName}' - '${key}' is part of the Script API.`);
+                console.warn(`Ignoring attribute '${attributeName}' on pc-script-instance '${scriptName}' - '${key}' is part of the Script API.`);
                 return;
             }
             if (typeof current === 'string') {
@@ -11983,10 +12465,10 @@ class ScriptComponentElement extends ComponentElement {
     }
     handleMutations(mutations) {
         for (const mutation of mutations) {
-            // Handle per-property attribute changes on child pc-script elements
+            // Handle per-property attribute changes on child pc-script-instance elements
             if (mutation.type === 'attributes') {
                 const target = mutation.target;
-                if (target instanceof ScriptElement &&
+                if (target instanceof ScriptInstanceElement &&
                     target.parentElement === this &&
                     mutation.attributeName &&
                     !isReservedAttribute(mutation.attributeName)) {
@@ -11996,16 +12478,16 @@ class ScriptComponentElement extends ComponentElement {
             }
             // Only direct children are managed - the observer watches the subtree for attribute
             // changes, but deeper childList records must not create or destroy scripts
-            // (matching initComponent's ':scope > pc-script' contract)
+            // (matching initComponent's ':scope > pc-script-instance' contract)
             if (mutation.target !== this) {
                 continue;
             }
-            // Handle removed nodes first, so that replacing a pc-script with a same-named one
+            // Handle removed nodes first, so that replacing a pc-script-instance with a same-named one
             // destroys the old script before the replacement is created. Only destroy a script
             // this element actually owns - a duplicate-named element whose own create() failed
             // must not take down the live script on removal.
             mutation.removedNodes.forEach((node) => {
-                if (node instanceof ScriptElement) {
+                if (node instanceof ScriptInstanceElement) {
                     const scriptName = node.getAttribute('name');
                     if (scriptName &&
                         node._script &&
@@ -12018,7 +12500,7 @@ class ScriptComponentElement extends ComponentElement {
             });
             // Handle added nodes
             mutation.addedNodes.forEach((node) => {
-                if (node instanceof ScriptElement) {
+                if (node instanceof ScriptInstanceElement) {
                     this.createScript(node);
                 }
             });
@@ -12036,14 +12518,20 @@ class ScriptComponentElement extends ComponentElement {
         return super.component;
     }
 }
-customElements.define('pc-scripts', ScriptComponentElement);
+customElements.define('pc-script', ScriptComponentElement);
 
 /**
  * The SoundComponentElement interface provides properties and methods for manipulating
- * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-sounds/ | `<pc-sounds>`} elements.
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-sound/ | `<pc-sound>`} elements.
  * The SoundComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link SoundComponent} (`sound`).
+ *
+ * @elementSummary The `<pc-sound>` element holds the `<pc-sound-slot>` children that play sounds at
+ * its entity, along with the positional audio settings they share. Must be a child of a
+ * `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+ *
  * @category Components
  */
 class SoundComponentElement extends ComponentElement {
@@ -12234,12 +12722,15 @@ class SoundComponentElement extends ComponentElement {
         }
     }
 }
-customElements.define('pc-sounds', SoundComponentElement);
+customElements.define('pc-sound', SoundComponentElement);
 
 /**
  * The SoundSlotElement interface provides properties and methods for manipulating
- * `<pc-sound>` elements. The SoundSlotElement interface also inherits the properties and
+ * `<pc-sound-slot>` elements. The SoundSlotElement interface also inherits the properties and
  * methods of the {@link AsyncElement} interface.
+ *
+ * @elementSummary The `<pc-sound-slot>` element declares one named sound on its parent `<pc-sound>`
+ * — its asset, volume, pitch, looping and autoplay. Must be a direct child of `<pc-sound>`.
  */
 class SoundSlotElement extends AsyncElement {
     _asset = '';
@@ -12252,7 +12743,7 @@ class SoundSlotElement extends AsyncElement {
     _startTime = 0;
     _volume = 1;
     /**
-     * The `<pc-sounds>` this slot was added to, captured at connect time.
+     * The `<pc-sound>` 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
@@ -12315,7 +12806,7 @@ class SoundSlotElement extends AsyncElement {
     get soundElement() {
         const soundElement = this.parentElement;
         if (!(soundElement instanceof SoundComponentElement)) {
-            console.warn('pc-sound must be a direct child of a pc-sounds element');
+            console.warn('pc-sound-slot must be a direct child of a pc-sound element');
             return null;
         }
         return soundElement;
@@ -12511,7 +13002,7 @@ class SoundSlotElement extends AsyncElement {
         }
     }
 }
-customElements.define('pc-sound', SoundSlotElement);
+customElements.define('pc-sound-slot', SoundSlotElement);
 
 /**
  * The GSplatComponentElement interface provides properties and methods for manipulating
@@ -12519,6 +13010,12 @@ customElements.define('pc-sound', SoundSlotElement);
  * The GSplatComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link GSplatComponent} (`gsplat`).
+ *
+ * @elementSummary The `<pc-gsplat>` element renders the 3D Gaussian splats of a `gsplat` asset at
+ * its entity, with attributes for shadow casting and level of detail. Must be a child of a
+ * `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+ *
  * @category Components
  */
 class GSplatComponentElement extends ComponentElement {
@@ -12814,6 +13311,11 @@ const levenshtein = (a, b) => {
  * 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>`.
  *
+ * @elementSummary The `<pc-node>` element binds to a node inside the hierarchy a `<pc-model>`
+ * instantiated and declares overrides against it: a transform, an enabled state, tags, components
+ * to add, or content to attach. Its `name` is a lookup, never a rename. Must be a descendant of
+ * `<pc-model>`.
+ *
  * @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,
@@ -12940,7 +13442,10 @@ class NodeElement extends EntityBaseElement {
      * is retained untouched — a redundant edit must not flicker overrides through a revert.
      */
     _rebind() {
-        const hostEntity = this._host?.entity ?? null;
+        // A model fronts a host entity of its own; the names this element resolves are the
+        // asset's, so the search starts at the instantiated content root, not the wrapper.
+        const host = this._host;
+        const hostEntity = (host instanceof ModelElement ? host.contentEntity : 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.
@@ -13037,8 +13542,9 @@ class NodeElement extends EntityBaseElement {
         }
         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) => {
+        // destroyed entity resets its element, which the next _buildChildren re-creates - a
+        // model host among them re-instantiates its content when it rebuilds.
+        this.querySelectorAll('pc-entity, pc-model').forEach((child) => {
             if (child.closestEntity === this) {
                 child.entity?.destroy();
             }
@@ -13550,6 +14056,9 @@ customElements.define('pc-node', NodeElement);
  * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-scene/ | `<pc-scene>`} elements.
  * The SceneElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
+ *
+ * @elementSummary The `<pc-scene>` element holds the entity hierarchy the application renders,
+ * along with the scene-wide fog and gravity settings. Must be a direct child of `<pc-app>`.
  */
 class SceneElement extends AsyncElement {
     /**
@@ -13773,6 +14282,10 @@ customElements.define('pc-scene', SceneElement);
  * The SkyElement interface provides properties and methods for manipulating
  * `<pc-sky>` elements. The SkyElement interface also inherits the properties and
  * methods of the {@link HTMLElement} interface.
+ *
+ * @elementSummary The `<pc-sky>` element renders a skybox from a texture asset, projected as an
+ * infinite background, a box or a dome, and optionally lights the scene from it. Must be a direct
+ * child of `<pc-scene>`.
  */
 class SkyElement extends AsyncElement {
     _asset = '';
@@ -14064,5 +14577,5 @@ class SkyElement extends AsyncElement {
 }
 customElements.define('pc-sky', SkyElement);
 
-export { AnimClipElement, AnimComponentElement, AppElement, AssetElement, AsyncElement, ButtonComponentElement, CameraComponentElement, CollisionComponentElement, ComponentElement, ElementComponentElement, EntityBaseElement, EntityElement, GSplatComponentElement, JointComponentElement, LayoutChildComponentElement, LayoutGroupComponentElement, LightComponentElement, ListenerComponentElement, MaterialElement, ModelElement, ModuleElement, NodeElement, ParticleSystemComponentElement, RenderComponentElement, RigidBodyComponentElement, SceneElement, ScreenComponentElement, ScriptComponentElement, ScriptElement, ScrollViewComponentElement, ScrollbarComponentElement, SkyElement, SoundComponentElement, SoundSlotElement, whenReady };
+export { AnimClipElement, AnimComponentElement, AppElement, AssetElement, AsyncElement, AudioListenerComponentElement, ButtonComponentElement, CameraComponentElement, CollisionComponentElement, ComponentElement, ElementComponentElement, EntityBaseElement, EntityElement, EntityOwnerElement, GSplatComponentElement, JointComponentElement, LayoutChildComponentElement, LayoutGroupComponentElement, LightComponentElement, MaterialElement, ModelElement, NodeElement, ParticleSystemComponentElement, RenderComponentElement, RigidBodyComponentElement, SceneElement, ScreenComponentElement, ScriptComponentElement, ScriptInstanceElement, ScrollViewComponentElement, ScrollbarComponentElement, SkyElement, SoundComponentElement, SoundSlotElement, WasmElement, whenReady };
 //# sourceMappingURL=pwc.mjs.map