@playcanvas/web-components 0.16.0 → 0.18.0

package/README.md

@@ -7,7 +7,7 @@
 [![Reddit](https://img.shields.io/badge/Reddit-FF4500?style=flat&logo=reddit&logoColor=white&color=black)](https://www.reddit.com/r/PlayCanvas)
 [![X](https://img.shields.io/badge/X-000000?style=flat&logo=x&logoColor=white&color=black)](https://x.com/intent/follow?screen_name=playcanvas)
 
-| [User Manual](https://developer.playcanvas.com//user-manual/web-components) | [API Reference](https://api.playcanvas.com/web-components) | [Examples](https://playcanvas.github.io/web-components/examples) | [Blog](https://blog.playcanvas.com) | [Forum](https://forum.playcanvas.com) |
+| [User Manual](https://developer.playcanvas.com/user-manual/web-components) | [API Reference](https://api.playcanvas.com/web-components) | [Examples](https://playcanvas.github.io/web-components/examples) | [Blog](https://blog.playcanvas.com) | [Forum](https://forum.playcanvas.com) |
 
 PlayCanvas Web Components are a set of custom HTML elements for building 3D interactive web apps. Using the declarative nature of HTML makes it both easy and fun to incorporate 3D into your website. Check out this simple example:
 
@@ -30,9 +30,11 @@ PlayCanvas Web Components are a set of custom HTML elements for building 3D inte
 
 ## Examples
 
-<img width="5120" height="2160" alt="examples" src="https://github.com/user-attachments/assets/92cf1156-c93f-46b5-8d05-e576967ceaf3" />
+<a href="https://playcanvas.github.io/web-components/examples">
+  <img width="5120" height="2160" alt="PlayCanvas Web Components examples gallery showing interactive 3D demos" src="https://github.com/user-attachments/assets/92cf1156-c93f-46b5-8d05-e576967ceaf3" />
+</a>
 
-See PlayCanvas Web Components in action here: https://playcanvas.github.io/web-components/examples
+Explore the [PlayCanvas Web Components examples gallery](https://playcanvas.github.io/web-components/examples).
 
 ## Usage
 

package/dist/app.d.cts

@@ -14,6 +14,10 @@ import type { EntityBaseElement } from './entity-base.cjs';
  * 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
@@ -53,9 +57,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 +107,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

@@ -14,6 +14,10 @@ import type { EntityBaseElement } from './entity-base.js';
  * 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
@@ -53,9 +57,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 +107,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/asset.d.cts

@@ -1,8 +1,14 @@
 import { Asset } from 'playcanvas';
 import { AsyncElement } from './async-element.cjs';
-type AddressMode = 'repeat' | 'clamp' | 'mirror';
-type MinFilterMode = 'nearest' | 'linear' | 'nearest-mip-nearest' | 'linear-mip-nearest' | 'nearest-mip-linear' | 'linear-mip-linear';
-type MagFilterMode = 'nearest' | 'linear';
+/** The addressing modes for a texture asset. */
+export type AddressMode = 'repeat' | 'clamp' | 'mirror';
+/** The minification filter modes for a texture asset. */
+export type MinFilterMode = 'nearest' | 'linear' | 'nearest-mip-nearest' | 'linear-mip-nearest' | 'nearest-mip-linear' | 'linear-mip-linear';
+/**
+ * The magnification filter modes for a texture asset. Magnification has no mip variants - the
+ * engine (and the GPU) only accepts these two.
+ */
+export type MagFilterMode = 'nearest' | 'linear';
 /**
  * The AssetElement interface provides properties and methods for manipulating
  * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-asset/ | `<pc-asset>`} elements.
@@ -31,6 +37,10 @@ type MagFilterMode = 'nearest' | 'linear';
  * 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.

package/dist/asset.d.ts

@@ -1,8 +1,14 @@
 import { Asset } from 'playcanvas';
 import { AsyncElement } from './async-element.js';
-type AddressMode = 'repeat' | 'clamp' | 'mirror';
-type MinFilterMode = 'nearest' | 'linear' | 'nearest-mip-nearest' | 'linear-mip-nearest' | 'nearest-mip-linear' | 'linear-mip-linear';
-type MagFilterMode = 'nearest' | 'linear';
+/** The addressing modes for a texture asset. */
+export type AddressMode = 'repeat' | 'clamp' | 'mirror';
+/** The minification filter modes for a texture asset. */
+export type MinFilterMode = 'nearest' | 'linear' | 'nearest-mip-nearest' | 'linear-mip-nearest' | 'nearest-mip-linear' | 'linear-mip-linear';
+/**
+ * The magnification filter modes for a texture asset. Magnification has no mip variants - the
+ * engine (and the GPU) only accepts these two.
+ */
+export type MagFilterMode = 'nearest' | 'linear';
 /**
  * The AssetElement interface provides properties and methods for manipulating
  * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-asset/ | `<pc-asset>`} elements.
@@ -31,6 +37,10 @@ type MagFilterMode = 'nearest' | 'linear';
  * 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.

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-clip.d.cts

@@ -13,6 +13,10 @@ import { AnimComponentElement } from './anim-component.cjs';
  * 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
  */
 declare class AnimClipElement extends AsyncElement {

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

@@ -13,6 +13,10 @@ import { AnimComponentElement } from './anim-component.js';
  * 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
  */
 declare class AnimClipElement extends AsyncElement {

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

@@ -25,6 +25,13 @@ type ContainerWithAnimations = ContainerResource & {
  * 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
  */
 declare class AnimComponentElement extends ComponentElement {
@@ -46,6 +53,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 +83,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,13 @@ type ContainerWithAnimations = ContainerResource & {
  * 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
  */
 declare class AnimComponentElement extends ComponentElement {
@@ -46,6 +53,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 +83,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/audio-listener-component.d.cts

@@ -0,0 +1,26 @@
+import type { AudioListenerComponent } from 'playcanvas';
+import { ComponentElement } from './component.cjs';
+/**
+ * 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
+ */
+declare class AudioListenerComponentElement extends ComponentElement {
+    /** @ignore */
+    constructor();
+    /**
+     * Gets the underlying PlayCanvas audio listener component.
+     * @returns The audio listener component.
+     */
+    get component(): AudioListenerComponent;
+}
+export { AudioListenerComponentElement };

package/dist/components/audio-listener-component.d.ts

@@ -0,0 +1,26 @@
+import type { AudioListenerComponent } from 'playcanvas';
+import { ComponentElement } from './component.js';
+/**
+ * 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
+ */
+declare class AudioListenerComponentElement extends ComponentElement {
+    /** @ignore */
+    constructor();
+    /**
+     * Gets the underlying PlayCanvas audio listener component.
+     * @returns The audio listener component.
+     */
+    get component(): AudioListenerComponent;
+}
+export { AudioListenerComponentElement };

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

@@ -7,6 +7,13 @@ import { ComponentElement } from './component.cjs';
  * 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
  */
 declare class ButtonComponentElement extends ComponentElement {
@@ -44,7 +51,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,13 @@ import { ComponentElement } from './component.js';
  * 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
  */
 declare class ButtonComponentElement extends ComponentElement {
@@ -44,7 +51,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);