@playcanvas/web-components 0.15.0 → 0.17.0

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

@@ -0,0 +1,235 @@
+import type { AnimComponent, Asset, ContainerResource } from 'playcanvas';
+import { ComponentElement } from './component.cjs';
+/**
+ * A container resource with the `animations` sub-assets the engine documents but does not type:
+ * one `Asset` of type `animation` per glTF animation, each holding an `AnimTrack` resource.
+ */
+type ContainerWithAnimations = ContainerResource & {
+    animations: Asset[];
+};
+/**
+ * The AnimComponentElement interface provides properties and methods for manipulating
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-anim/ | `<pc-anim>`} elements.
+ * The AnimComponentElement interface also inherits the properties and methods of the
+ * {@link HTMLElement} interface.
+ *
+ * The element drives animation clips over the host entity's hierarchy. Clips come from
+ * `<pc-anim-clip>` children — or, when the element is a direct child of a `<pc-model>` and
+ * declares no clips, every animation of that model's container asset is assigned, named by track
+ * name, in container order. The first clip plays automatically (opt out with `activate="false"`);
+ * switch clips declaratively through the `clip` attribute, or imperatively through {@link play}
+ * and {@link transition}. Tracks bind to scene nodes by name, so any hierarchy whose node names
+ * match a clip's curves can be animated — a model's skeleton is simply the common case.
+ *
+ * The engine reports no clip completion: a non-looping clip holds its last pose silently. Poll
+ * 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 {
+    /**
+     * Whether playback starts automatically once a clip is assigned.
+     */
+    private _activate;
+    /**
+     * The clip elements whose states are currently assigned, by clip name. The single writer of
+     * a state: a later clip child re-using an adopted name is rejected as a duplicate.
+     */
+    private _assignedClips;
+    /**
+     * Whether the current clip set was auto-assigned from the enclosing model rather than
+     * declared by clip children.
+     */
+    private _autoAssigned;
+    /**
+     * 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.
+     */
+    private _modelListenerTarget;
+    /**
+     * Incremented whenever the clip source changes, and captured by an auto-assign pass on
+     * entry — a pass resuming from an await abandons itself if the value has moved on, so a
+     * superseded pass cannot assign clips alongside declared children or a newer pass.
+     */
+    private _sourceGeneration;
+    /**
+     * The playback speed multiplier applied across all clips.
+     */
+    private _speed;
+    /**
+     * The cross-fade duration of declarative clip switches, in seconds.
+     */
+    private _transitionTime;
+    /**
+     * The unknown clip name already warned about, so a repeated selection of the same missing
+     * name complains once.
+     */
+    private _warnedClip;
+    /**
+     * 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. 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(): {
+        activate: boolean;
+        speed: number;
+    };
+    protected initComponent(): void;
+    disconnectedCallback(): void;
+    /**
+     * The clip children in DOM order. Read afresh each pass — the DOM is the single source of
+     * truth for the declared clip set.
+     */
+    private _clipElements;
+    /**
+     * Assigns a clip's state. Until the clip's real track resolves, the engine's own placeholder
+     * track stands in — it keeps the layer playable, so `activate` can start playback and the
+     * declared `clip` selection can apply before any asset has loaded.
+     */
+    private _assignClip;
+    /**
+     * Validates a clip child and, when valid, assigns its state and starts its track resolution.
+     *
+     * @param clip - The clip element.
+     * @returns Whether the clip was adopted.
+     */
+    private _adoptClip;
+    /**
+     * Assigns the current clip set: the declared clip children when there are any, otherwise the
+     * enclosing model's clips. Runs against a fresh component after a host cycle, so the
+     * adoption bookkeeping rebuilds from scratch.
+     */
+    private _applyClips;
+    /**
+     * Assigns every clip of the enclosing model's container, named by track name, in container
+     * order. Names the engine cannot host — dotted (reserved for blend tree paths) or already
+     * taken — are skipped with a warning naming each.
+     */
+    private _kickAutoAssign;
+    /**
+     * Applies the active-clip selection: the declared `clip` when it names an assigned state,
+     * else a captured pre-rebuild state when it survived, else the engine's default (the first
+     * assigned clip). A restore also reinstates the playhead and both playing flags exactly as
+     * captured — the reassignment that preceded it set both to the `activate` outcome, which is
+     * not necessarily the state the rebuild interrupted.
+     */
+    private _applySelection;
+    private _warnUnknownClip;
+    /**
+     * Resumes playback, optionally switching to a named clip first (a hard cut). A name that
+     * matches no clip leaves the selection unchanged.
+     *
+     * @param name - The name of the clip to play. Resumes the current clip when omitted.
+     */
+    play(name?: string): void;
+    /**
+     * Pauses playback, preserving the playhead — {@link play} resumes from where it stopped.
+     */
+    pause(): void;
+    /**
+     * Cross-fades to a named clip and ensures playback is running. A name that matches no clip
+     * leaves the selection unchanged.
+     *
+     * @param name - The name of the clip to fade to.
+     * @param time - The fade duration in seconds. Defaults to the `transition-time` attribute.
+     */
+    transition(name: string, time?: number): void;
+    /**
+     * Gets the underlying PlayCanvas anim component.
+     * @returns The anim component.
+     */
+    get component(): AnimComponent;
+    /**
+     * Gets the names of the assigned clips.
+     * @returns The clip names, in assignment order.
+     */
+    get clips(): string[];
+    /**
+     * Sets whether playback starts automatically once a clip is assigned. Defaults to `true`.
+     * Applies when clips are assigned — it does not stop a clip that is already playing.
+     * @param value - Whether playback starts automatically.
+     */
+    set activate(value: boolean);
+    /**
+     * Gets whether playback starts automatically once a clip is assigned.
+     * @returns Whether playback starts automatically.
+     */
+    get activate(): boolean;
+    /**
+     * Sets the name of the active clip. Changing it switches playback, cross-fading over
+     * `transition-time` seconds (a hard cut at 0). An empty value leaves the current clip
+     * playing; a name that matches no clip warns and leaves the selection unchanged.
+     * @param value - The name of the active clip.
+     */
+    set clip(value: string);
+    /**
+     * Gets the name of the active clip.
+     * @returns The name of the active clip.
+     */
+    get clip(): string;
+    /**
+     * Sets the playback speed multiplier applied across all clips, where 0 freezes playback.
+     * Defaults to 1.
+     * @param value - The playback speed multiplier.
+     */
+    set speed(value: number);
+    /**
+     * Gets the playback speed multiplier applied across all clips.
+     * @returns The playback speed multiplier.
+     */
+    get speed(): number;
+    /**
+     * Sets the cross-fade duration of clip switches made through the `clip` attribute, in
+     * seconds. Defaults to 0 (a hard cut).
+     * @param value - The cross-fade duration in seconds.
+     */
+    set transitionTime(value: number);
+    /**
+     * Gets the cross-fade duration of clip switches made through the `clip` attribute.
+     * @returns The cross-fade duration in seconds.
+     */
+    get transitionTime(): number;
+    static get observedAttributes(): string[];
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
+}
+export { AnimComponentElement };
+export type { ContainerWithAnimations };

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

@@ -0,0 +1,235 @@
+import type { AnimComponent, Asset, ContainerResource } from 'playcanvas';
+import { ComponentElement } from './component.js';
+/**
+ * A container resource with the `animations` sub-assets the engine documents but does not type:
+ * one `Asset` of type `animation` per glTF animation, each holding an `AnimTrack` resource.
+ */
+type ContainerWithAnimations = ContainerResource & {
+    animations: Asset[];
+};
+/**
+ * The AnimComponentElement interface provides properties and methods for manipulating
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-anim/ | `<pc-anim>`} elements.
+ * The AnimComponentElement interface also inherits the properties and methods of the
+ * {@link HTMLElement} interface.
+ *
+ * The element drives animation clips over the host entity's hierarchy. Clips come from
+ * `<pc-anim-clip>` children — or, when the element is a direct child of a `<pc-model>` and
+ * declares no clips, every animation of that model's container asset is assigned, named by track
+ * name, in container order. The first clip plays automatically (opt out with `activate="false"`);
+ * switch clips declaratively through the `clip` attribute, or imperatively through {@link play}
+ * and {@link transition}. Tracks bind to scene nodes by name, so any hierarchy whose node names
+ * match a clip's curves can be animated — a model's skeleton is simply the common case.
+ *
+ * The engine reports no clip completion: a non-looping clip holds its last pose silently. Poll
+ * 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 {
+    /**
+     * Whether playback starts automatically once a clip is assigned.
+     */
+    private _activate;
+    /**
+     * The clip elements whose states are currently assigned, by clip name. The single writer of
+     * a state: a later clip child re-using an adopted name is rejected as a duplicate.
+     */
+    private _assignedClips;
+    /**
+     * Whether the current clip set was auto-assigned from the enclosing model rather than
+     * declared by clip children.
+     */
+    private _autoAssigned;
+    /**
+     * 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.
+     */
+    private _modelListenerTarget;
+    /**
+     * Incremented whenever the clip source changes, and captured by an auto-assign pass on
+     * entry — a pass resuming from an await abandons itself if the value has moved on, so a
+     * superseded pass cannot assign clips alongside declared children or a newer pass.
+     */
+    private _sourceGeneration;
+    /**
+     * The playback speed multiplier applied across all clips.
+     */
+    private _speed;
+    /**
+     * The cross-fade duration of declarative clip switches, in seconds.
+     */
+    private _transitionTime;
+    /**
+     * The unknown clip name already warned about, so a repeated selection of the same missing
+     * name complains once.
+     */
+    private _warnedClip;
+    /**
+     * 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. 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(): {
+        activate: boolean;
+        speed: number;
+    };
+    protected initComponent(): void;
+    disconnectedCallback(): void;
+    /**
+     * The clip children in DOM order. Read afresh each pass — the DOM is the single source of
+     * truth for the declared clip set.
+     */
+    private _clipElements;
+    /**
+     * Assigns a clip's state. Until the clip's real track resolves, the engine's own placeholder
+     * track stands in — it keeps the layer playable, so `activate` can start playback and the
+     * declared `clip` selection can apply before any asset has loaded.
+     */
+    private _assignClip;
+    /**
+     * Validates a clip child and, when valid, assigns its state and starts its track resolution.
+     *
+     * @param clip - The clip element.
+     * @returns Whether the clip was adopted.
+     */
+    private _adoptClip;
+    /**
+     * Assigns the current clip set: the declared clip children when there are any, otherwise the
+     * enclosing model's clips. Runs against a fresh component after a host cycle, so the
+     * adoption bookkeeping rebuilds from scratch.
+     */
+    private _applyClips;
+    /**
+     * Assigns every clip of the enclosing model's container, named by track name, in container
+     * order. Names the engine cannot host — dotted (reserved for blend tree paths) or already
+     * taken — are skipped with a warning naming each.
+     */
+    private _kickAutoAssign;
+    /**
+     * Applies the active-clip selection: the declared `clip` when it names an assigned state,
+     * else a captured pre-rebuild state when it survived, else the engine's default (the first
+     * assigned clip). A restore also reinstates the playhead and both playing flags exactly as
+     * captured — the reassignment that preceded it set both to the `activate` outcome, which is
+     * not necessarily the state the rebuild interrupted.
+     */
+    private _applySelection;
+    private _warnUnknownClip;
+    /**
+     * Resumes playback, optionally switching to a named clip first (a hard cut). A name that
+     * matches no clip leaves the selection unchanged.
+     *
+     * @param name - The name of the clip to play. Resumes the current clip when omitted.
+     */
+    play(name?: string): void;
+    /**
+     * Pauses playback, preserving the playhead — {@link play} resumes from where it stopped.
+     */
+    pause(): void;
+    /**
+     * Cross-fades to a named clip and ensures playback is running. A name that matches no clip
+     * leaves the selection unchanged.
+     *
+     * @param name - The name of the clip to fade to.
+     * @param time - The fade duration in seconds. Defaults to the `transition-time` attribute.
+     */
+    transition(name: string, time?: number): void;
+    /**
+     * Gets the underlying PlayCanvas anim component.
+     * @returns The anim component.
+     */
+    get component(): AnimComponent;
+    /**
+     * Gets the names of the assigned clips.
+     * @returns The clip names, in assignment order.
+     */
+    get clips(): string[];
+    /**
+     * Sets whether playback starts automatically once a clip is assigned. Defaults to `true`.
+     * Applies when clips are assigned — it does not stop a clip that is already playing.
+     * @param value - Whether playback starts automatically.
+     */
+    set activate(value: boolean);
+    /**
+     * Gets whether playback starts automatically once a clip is assigned.
+     * @returns Whether playback starts automatically.
+     */
+    get activate(): boolean;
+    /**
+     * Sets the name of the active clip. Changing it switches playback, cross-fading over
+     * `transition-time` seconds (a hard cut at 0). An empty value leaves the current clip
+     * playing; a name that matches no clip warns and leaves the selection unchanged.
+     * @param value - The name of the active clip.
+     */
+    set clip(value: string);
+    /**
+     * Gets the name of the active clip.
+     * @returns The name of the active clip.
+     */
+    get clip(): string;
+    /**
+     * Sets the playback speed multiplier applied across all clips, where 0 freezes playback.
+     * Defaults to 1.
+     * @param value - The playback speed multiplier.
+     */
+    set speed(value: number);
+    /**
+     * Gets the playback speed multiplier applied across all clips.
+     * @returns The playback speed multiplier.
+     */
+    get speed(): number;
+    /**
+     * Sets the cross-fade duration of clip switches made through the `clip` attribute, in
+     * seconds. Defaults to 0 (a hard cut).
+     * @param value - The cross-fade duration in seconds.
+     */
+    set transitionTime(value: number);
+    /**
+     * Gets the cross-fade duration of clip switches made through the `clip` attribute.
+     * @returns The cross-fade duration in seconds.
+     */
+    get transitionTime(): number;
+    static get observedAttributes(): string[];
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
+}
+export { AnimComponentElement };
+export type { ContainerWithAnimations };

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 {