@playcanvas/web-components 0.16.0 → 0.17.0

package/dist/app.d.cts

@@ -53,9 +53,9 @@ declare class AppElement extends AsyncElement {
     private _bootGeneration;
     /**
      * 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.
      */
     private _entityElements;
     private _picker;
@@ -103,25 +103,26 @@ declare class AppElement extends AsyncElement {
     private _pickerCreate;
     private _pickerDestroy;
     /**
-     * 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`.
      */
     elementFromEntity(entity: Entity): EntityBaseElement | 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`.
      */
-    private _elementFromNode;
+    private _hoverTarget;
     /**
      * Like {@link _elementFromNode}, but skips elements without a listener for `type`, so a hit
      * on an unlistened child still reaches a listening ancestor.

package/dist/app.d.ts

@@ -53,9 +53,9 @@ declare class AppElement extends AsyncElement {
     private _bootGeneration;
     /**
      * 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.
      */
     private _entityElements;
     private _picker;
@@ -103,25 +103,26 @@ declare class AppElement extends AsyncElement {
     private _pickerCreate;
     private _pickerDestroy;
     /**
-     * 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`.
      */
     elementFromEntity(entity: Entity): EntityBaseElement | 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`.
      */
-    private _elementFromNode;
+    private _hoverTarget;
     /**
      * Like {@link _elementFromNode}, but skips elements without a listener for `type`, so a hit
      * on an unlistened child still reaches a listening ancestor.

package/dist/async-element.d.cts

@@ -20,9 +20,9 @@ declare class AsyncElement extends HTMLElement {
      */
     get closestApp(): AppElement | 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(): EntityBaseElement | null;
@@ -62,11 +62,11 @@ type AsyncElementTagName = {
 }[keyof HTMLElementTagNameMap];
 /**
  * Waits for the first element matching the given tag name to be fully initialized. Note that the
- * promise never settles if the element cannot finish initializing (for example, a `<pc-script>`
- * that is not a direct child of `<pc-scripts>`, or a `<pc-app>` that could not create a graphics
- * device — listen for its `error` event instead). A component element outside a `<pc-entity>` is
- * the exception: it still becomes ready, but its `component` is `null`. Either way, a misplaced
- * element logs a warning naming the parent it requires.
+ * promise never settles if the element cannot finish initializing (for example, a `<pc-script-instance>`
+ * that is not a direct child of `<pc-script>`, or a `<pc-app>` that could not create a graphics
+ * device — listen for its `error` event instead). A component element outside an entity-fronting
+ * element is the exception: it still becomes ready, but its `component` is `null`. Either way, a
+ * misplaced element logs a warning naming the parent it requires.
  * @param target - The tag name of the element to wait for (e.g. `'pc-app'`).
  * @returns A promise that resolves with the element once it's ready.
  * @example
@@ -87,11 +87,11 @@ declare function whenReady<K extends AsyncElementTagName>(target: K): Promise<HT
 declare function whenReady<T extends AsyncElement>(target: T): Promise<T>;
 /**
  * Waits for the first element matching the given CSS selector to be fully initialized. Note that
- * the promise never settles if the element cannot finish initializing (for example, a `<pc-script>`
- * that is not a direct child of `<pc-scripts>`, or a `<pc-app>` that could not create a graphics
- * device — listen for its `error` event instead). A component element outside a `<pc-entity>` is
- * the exception: it still becomes ready, but its `component` is `null`. Either way, a misplaced
- * element logs a warning naming the parent it requires.
+ * the promise never settles if the element cannot finish initializing (for example, a `<pc-script-instance>`
+ * that is not a direct child of `<pc-script>`, or a `<pc-app>` that could not create a graphics
+ * device — listen for its `error` event instead). A component element outside an entity-fronting
+ * element is the exception: it still becomes ready, but its `component` is `null`. Either way, a
+ * misplaced element logs a warning naming the parent it requires.
  * @param target - A CSS selector matching the element to wait for (e.g. `'#my-app'`).
  * @returns A promise that resolves with the element once it's ready.
  * @example

package/dist/async-element.d.ts

@@ -20,9 +20,9 @@ declare class AsyncElement extends HTMLElement {
      */
     get closestApp(): AppElement | 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(): EntityBaseElement | null;
@@ -62,11 +62,11 @@ type AsyncElementTagName = {
 }[keyof HTMLElementTagNameMap];
 /**
  * Waits for the first element matching the given tag name to be fully initialized. Note that the
- * promise never settles if the element cannot finish initializing (for example, a `<pc-script>`
- * that is not a direct child of `<pc-scripts>`, or a `<pc-app>` that could not create a graphics
- * device — listen for its `error` event instead). A component element outside a `<pc-entity>` is
- * the exception: it still becomes ready, but its `component` is `null`. Either way, a misplaced
- * element logs a warning naming the parent it requires.
+ * promise never settles if the element cannot finish initializing (for example, a `<pc-script-instance>`
+ * that is not a direct child of `<pc-script>`, or a `<pc-app>` that could not create a graphics
+ * device — listen for its `error` event instead). A component element outside an entity-fronting
+ * element is the exception: it still becomes ready, but its `component` is `null`. Either way, a
+ * misplaced element logs a warning naming the parent it requires.
  * @param target - The tag name of the element to wait for (e.g. `'pc-app'`).
  * @returns A promise that resolves with the element once it's ready.
  * @example
@@ -87,11 +87,11 @@ declare function whenReady<K extends AsyncElementTagName>(target: K): Promise<HT
 declare function whenReady<T extends AsyncElement>(target: T): Promise<T>;
 /**
  * Waits for the first element matching the given CSS selector to be fully initialized. Note that
- * the promise never settles if the element cannot finish initializing (for example, a `<pc-script>`
- * that is not a direct child of `<pc-scripts>`, or a `<pc-app>` that could not create a graphics
- * device — listen for its `error` event instead). A component element outside a `<pc-entity>` is
- * the exception: it still becomes ready, but its `component` is `null`. Either way, a misplaced
- * element logs a warning naming the parent it requires.
+ * the promise never settles if the element cannot finish initializing (for example, a `<pc-script-instance>`
+ * that is not a direct child of `<pc-script>`, or a `<pc-app>` that could not create a graphics
+ * device — listen for its `error` event instead). A component element outside an entity-fronting
+ * element is the exception: it still becomes ready, but its `component` is `null`. Either way, a
+ * misplaced element logs a warning naming the parent it requires.
  * @param target - A CSS selector matching the element to wait for (e.g. `'#my-app'`).
  * @returns A promise that resolves with the element once it's ready.
  * @example

package/dist/components/anim-component.d.cts

@@ -25,6 +25,8 @@ type ContainerWithAnimations = ContainerResource & {
  * the underlying {@link AnimComponent} (via {@link component}) for playback state beyond what
  * this element exposes.
  *
+ * Engine component: {@link AnimComponent} (`anim`).
+ *
  * @category Components
  */
 declare class AnimComponentElement extends ComponentElement {
@@ -46,6 +48,11 @@ declare class AnimComponentElement extends ComponentElement {
      * The name of the active clip.
      */
     private _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.
+     */
+    private _managedRootBone;
     /**
      * The element the model-readiness listener is attached to, held so disconnection can detach
      * it after `closestEntity` no longer resolves.
@@ -71,14 +78,35 @@ declare class AnimComponentElement extends ComponentElement {
      */
     private _warnedClip;
     /**
-     * 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.
      */
     private _onModelReady;
+    /**
+     * 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.
+     */
+    private _skeletonSource;
+    /**
+     * 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.
+     */
+    private _applyRootBone;
     /** @ignore */
     constructor();
     protected getInitialComponentData(): {

package/dist/components/anim-component.d.ts

@@ -25,6 +25,8 @@ type ContainerWithAnimations = ContainerResource & {
  * the underlying {@link AnimComponent} (via {@link component}) for playback state beyond what
  * this element exposes.
  *
+ * Engine component: {@link AnimComponent} (`anim`).
+ *
  * @category Components
  */
 declare class AnimComponentElement extends ComponentElement {
@@ -46,6 +48,11 @@ declare class AnimComponentElement extends ComponentElement {
      * The name of the active clip.
      */
     private _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.
+     */
+    private _managedRootBone;
     /**
      * The element the model-readiness listener is attached to, held so disconnection can detach
      * it after `closestEntity` no longer resolves.
@@ -71,14 +78,35 @@ declare class AnimComponentElement extends ComponentElement {
      */
     private _warnedClip;
     /**
-     * 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.
      */
     private _onModelReady;
+    /**
+     * 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.
+     */
+    private _skeletonSource;
+    /**
+     * 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.
+     */
+    private _applyRootBone;
     /** @ignore */
     constructor();
     protected getInitialComponentData(): {

package/dist/components/{listener-component.d.cts → audio-listener-component.d.cts}

@@ -1,14 +1,16 @@
 import type { AudioListenerComponent } from 'playcanvas';
 import { ComponentElement } from './component.cjs';
 /**
- * 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`).
+ *
  * @category Components
  */
-declare class ListenerComponentElement extends ComponentElement {
+declare class AudioListenerComponentElement extends ComponentElement {
     /** @ignore */
     constructor();
     /**
@@ -17,4 +19,4 @@ declare class ListenerComponentElement extends ComponentElement {
      */
     get component(): AudioListenerComponent;
 }
-export { ListenerComponentElement };
+export { AudioListenerComponentElement };

package/dist/components/{listener-component.d.ts → audio-listener-component.d.ts}

@@ -1,14 +1,16 @@
 import type { AudioListenerComponent } from 'playcanvas';
 import { ComponentElement } from './component.js';
 /**
- * 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`).
+ *
  * @category Components
  */
-declare class ListenerComponentElement extends ComponentElement {
+declare class AudioListenerComponentElement extends ComponentElement {
     /** @ignore */
     constructor();
     /**
@@ -17,4 +19,4 @@ declare class ListenerComponentElement extends ComponentElement {
      */
     get component(): AudioListenerComponent;
 }
-export { ListenerComponentElement };
+export { AudioListenerComponentElement };

package/dist/components/button-component.d.cts

@@ -7,6 +7,8 @@ import { ComponentElement } from './component.cjs';
  * The ButtonComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link ButtonComponent} (`button`).
+ *
  * @category Components
  */
 declare class ButtonComponentElement extends ComponentElement {
@@ -44,7 +46,9 @@ declare class ButtonComponentElement extends ComponentElement {
     get active(): boolean;
     /**
      * 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: string);

package/dist/components/button-component.d.ts

@@ -7,6 +7,8 @@ import { ComponentElement } from './component.js';
  * The ButtonComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link ButtonComponent} (`button`).
+ *
  * @category Components
  */
 declare class ButtonComponentElement extends ComponentElement {
@@ -44,7 +46,9 @@ declare class ButtonComponentElement extends ComponentElement {
     get active(): boolean;
     /**
      * 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: string);

package/dist/components/camera-component.d.cts

@@ -7,6 +7,8 @@ import { ComponentElement } from './component.cjs';
  * The CameraComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link CameraComponent} (`camera`).
+ *
  * @category Components
  */
 declare class CameraComponentElement extends ComponentElement {

package/dist/components/camera-component.d.ts

@@ -7,6 +7,8 @@ import { ComponentElement } from './component.js';
  * The CameraComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link CameraComponent} (`camera`).
+ *
  * @category Components
  */
 declare class CameraComponentElement extends ComponentElement {

package/dist/components/collision-component.d.cts

@@ -13,6 +13,8 @@ import { ComponentElement } from './component.cjs';
  * 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`).
+ *
  * @category Components
  */
 declare class CollisionComponentElement extends ComponentElement {
@@ -43,7 +45,9 @@ declare 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`.
      */
     private _applyMeshGeometryDefault;
     /**

package/dist/components/collision-component.d.ts

@@ -13,6 +13,8 @@ import { ComponentElement } from './component.js';
  * 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`).
+ *
  * @category Components
  */
 declare class CollisionComponentElement extends ComponentElement {
@@ -43,7 +45,9 @@ declare 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`.
      */
     private _applyMeshGeometryDefault;
     /**

package/dist/components/component.d.cts

@@ -61,8 +61,9 @@ declare class ComponentElement extends AsyncElement {
     disconnectedCallback(): void;
     /**
      * 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(): Component | null;

package/dist/components/component.d.ts

@@ -61,8 +61,9 @@ declare class ComponentElement extends AsyncElement {
     disconnectedCallback(): void;
     /**
      * 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(): Component | null;

package/dist/components/element-component.d.cts

@@ -7,6 +7,13 @@ import { ComponentElement } from './component.cjs';
  * 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`).
+ *
  * @category Components
  */
 declare class ElementComponentElement extends ComponentElement {

package/dist/components/element-component.d.ts

@@ -7,6 +7,13 @@ import { ComponentElement } from './component.js';
  * 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`).
+ *
  * @category Components
  */
 declare class ElementComponentElement extends ComponentElement {

package/dist/components/gsplat-component.d.cts

@@ -6,6 +6,8 @@ import { ComponentElement } from './component.cjs';
  * The GSplatComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link GSplatComponent} (`gsplat`).
+ *
  * @category Components
  */
 declare class GSplatComponentElement extends ComponentElement {

package/dist/components/gsplat-component.d.ts

@@ -6,6 +6,8 @@ import { ComponentElement } from './component.js';
  * The GSplatComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link GSplatComponent} (`gsplat`).
+ *
  * @category Components
  */
 declare class GSplatComponentElement extends ComponentElement {

package/dist/components/joint-component.d.cts

@@ -20,6 +20,8 @@ type MotionMode = 'locked' | 'limited' | 'free';
  * 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
  */
 declare class JointComponentElement extends ComponentElement {

package/dist/components/joint-component.d.ts

@@ -20,6 +20,8 @@ type MotionMode = 'locked' | 'limited' | 'free';
  * 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
  */
 declare class JointComponentElement extends ComponentElement {

package/dist/components/{layoutchild-component.d.cts → layout-child-component.d.cts}

@@ -2,10 +2,12 @@ import type { LayoutChildComponent } from 'playcanvas';
 import { ComponentElement } from './component.cjs';
 /**
  * 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`).
+ *
  * @category Components
  */
 declare class LayoutChildComponentElement extends ComponentElement {

package/dist/components/{layoutchild-component.d.ts → layout-child-component.d.ts}

@@ -2,10 +2,12 @@ import type { LayoutChildComponent } from 'playcanvas';
 import { ComponentElement } from './component.js';
 /**
  * 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`).
+ *
  * @category Components
  */
 declare class LayoutChildComponentElement extends ComponentElement {

package/dist/components/{layoutgroup-component.d.cts → layout-group-component.d.cts}

@@ -3,10 +3,12 @@ import { Vec2, Vec4 } from 'playcanvas';
 import { ComponentElement } from './component.cjs';
 /**
  * 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`).
+ *
  * @category Components
  */
 declare class LayoutGroupComponentElement extends ComponentElement {