@playcanvas/web-components 0.16.0 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcanvas/web-components",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "author": "PlayCanvas <support@playcanvas.com>",
   "homepage": "https://playcanvas.com",
   "description": "Web Components for the PlayCanvas Engine",
@@ -91,25 +91,25 @@
     "@rollup/plugin-terser": "1.0.0",
     "@rollup/plugin-typescript": "12.3.0",
     "@tweenjs/tween.js": "25.0.0",
-    "@vitest/coverage-v8": "4.1.10",
-    "concurrently": "10.0.4",
+    "@vitest/coverage-v8": "4.1.11",
+    "concurrently": "10.0.5",
     "custom-element-jet-brains-integration": "1.7.0",
     "custom-element-vs-code-integration": "1.5.0",
     "earcut": "3.2.3",
     "eslint": "9.39.5",
     "globals": "17.11.0",
     "jsdom": "30.0.1",
-    "mediabunny": "1.53.1",
+    "mediabunny": "1.55.2",
     "opentype.js": "2.0.0",
     "playcanvas": "2.21.4",
     "prettier": "3.9.6",
-    "publint": "0.3.23",
-    "rollup": "4.62.4",
+    "publint": "0.3.24",
+    "rollup": "4.62.5",
     "serve": "14.2.6",
     "tslib": "2.8.1",
     "typedoc": "0.28.20",
     "typedoc-plugin-mdn-links": "5.1.1",
     "typescript": "6.0.3",
-    "vitest": "4.1.10"
+    "vitest": "4.1.11"
   }
 }

package/src/app.ts

@@ -66,16 +66,23 @@ import {
 
 import type { AssetElement } from './asset';
 import { AsyncElement } from './async-element';
-import type { EntityElement } from './entity';
 import type { EntityBaseElement } from './entity-base';
+import type { EntityOwnerElement } from './entity-owner';
 import { LoadingBar } from './loading-bar';
 import type { MaterialElement } from './material';
-import type { ModuleElement } from './module';
 import { parseBool, parseEnum, parseNumber } from './parse';
+import type { WasmElement } from './wasm';
 
 /** The pointer event types the application synthesizes on `<pc-entity>` elements via picking. */
 const pointerEventTypes = ['pointermove', 'pointerdown', 'pointerup', 'pointerenter', 'pointerleave'] as const;
 
+/**
+ * The event types whose listeners make an element a hover target. Hover resolution walks past
+ * elements listening for none of them, so a silent element never swallows an ancestor's
+ * enter/leave pair.
+ */
+const hoverEventTypes = ['pointerenter', 'pointerleave', 'pointermove'] as const;
+
 /**
  * Gives `pc-app` the sizing contract of a replaced element (`<video>`, `<img>`): a block-level
  * box that the page's CSS sizes, defaulting to the canvas's own 300x150 intrinsic size, with the
@@ -105,6 +112,10 @@ const ensureBaseStyles = () => {
  * tracked live via a ResizeObserver — so the element can be embedded at any size, resized by
  * its container, or made fullscreen with ordinary CSS such as `width: 100vw; height: 100dvh`.
  *
+ * @elementSummary The `<pc-app>` element creates a PlayCanvas application and the canvas it renders
+ * into, and is the root of every scene. It holds the `<pc-asset>`, `<pc-material>`, `<pc-wasm>` and
+ * `<pc-scene>` elements, and the page's CSS sizes it, as it would a `<video>`.
+ *
  * @fires {ProgressEvent} progress - Fired while the application preloads its assets. `loaded` and
  * `total` are asset counts, not bytes, and an asset that fails to load still counts as loaded.
  * Fired at least once per boot, and the final event always has `loaded` equal to `total`. Does
@@ -163,9 +174,9 @@ class AppElement extends AsyncElement {
 
     /**
      * 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 = new Map<GraphNode, EntityBaseElement>();
 
@@ -260,7 +271,7 @@ class AppElement extends AsyncElement {
         // there, leaving the element permanently unready: no canvas, no entities, no application.
         //
         // Upgrading is the fix here rather than skipping whatever has not upgraded, because a
-        // <pc-module> is the one child that nothing else ever builds on its own behalf - skipping
+        // <pc-wasm> is the one child that nothing else ever builds on its own behalf - skipping
         // it would drop the wasm module the app asked for, silently and only for cloned apps.
         // Upgrading runs each descendant's connectedCallback synchronously, a few lines earlier
         // than the parser's path runs them but into the same state they see there: no application
@@ -270,11 +281,11 @@ class AppElement extends AsyncElement {
         // is left completely untouched.
         customElements.upgrade(this);
 
-        // Get all pc-module elements that are direct children of the pc-app element
-        const moduleElements = this.querySelectorAll<ModuleElement>(':scope > pc-module');
+        // Get all pc-wasm elements that are direct children of the pc-app element
+        const wasmElements = this.querySelectorAll<WasmElement>(':scope > pc-wasm');
 
         // Wait for all modules to load
-        await Promise.all(Array.from(moduleElements).map((module) => module._getLoadPromise()));
+        await Promise.all(Array.from(wasmElements).map((element) => element._getLoadPromise()));
 
         // The element may have been removed while the modules loaded. Nothing beyond the loading
         // bar exists yet, and disconnectedCallback has already destroyed that.
@@ -462,15 +473,16 @@ class AppElement extends AsyncElement {
             materialElement._createMaterial();
         });
 
-        // Create all entities
-        const entityElements = this.querySelectorAll<EntityElement>('pc-entity');
-        Array.from(entityElements).forEach((entityElement) => {
-            entityElement._createEntity(app);
+        // Create all entities. pc-model joins the sweep because it owns a host entity of its
+        // own; its instantiated content arrives later, beneath that host.
+        const ownerElements = this.querySelectorAll<EntityOwnerElement>('pc-entity, pc-model');
+        Array.from(ownerElements).forEach((ownerElement) => {
+            ownerElement._createEntity(app);
         });
 
         // Build hierarchy
-        entityElements.forEach((entityElement) => {
-            entityElement._buildHierarchy(app);
+        ownerElements.forEach((ownerElement) => {
+            ownerElement._buildHierarchy(app);
         });
 
         // Building the hierarchy dispatched each entity's ready event synchronously, and a
@@ -602,9 +614,9 @@ class AppElement extends AsyncElement {
         // created from onpointer* attributes when their elements were first upgraded, or
         // listeners carried over from before a re-boot)
         pointerEventTypes.forEach((type) => {
-            const anyListeners = Array.from(this.querySelectorAll<EntityBaseElement>('pc-entity, pc-node')).some(
-                (entity) => entity._hasListeners(type)
-            );
+            const anyListeners = Array.from(
+                this.querySelectorAll<EntityBaseElement>('pc-entity, pc-model, pc-node')
+            ).some((entity) => entity._hasListeners(type));
             if (anyListeners) {
                 this._onPointerListenerAdded(type);
             }
@@ -659,10 +671,10 @@ class AppElement extends AsyncElement {
     }
 
     /**
-     * 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`.
@@ -672,18 +684,19 @@ class AppElement extends AsyncElement {
     }
 
     /**
-     * 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(node: GraphNode | null): EntityBaseElement | null {
+    private _hoverTarget(node: GraphNode | null): EntityBaseElement | null {
         while (node !== null) {
             const element = this._entityElements.get(node);
-            if (element) {
+            if (element && hoverEventTypes.some((type) => element._hasListeners(type))) {
                 return element;
             }
             node = node.parent;
@@ -831,9 +844,10 @@ class AppElement extends AsyncElement {
         const node = await this._pickNode(event);
         if (token !== this._pickToken || !this._picker) return;
 
-        // The hovered element is the nearest one up the node's parent chain, listening or not -
-        // dispatch is gated per event type below
-        const newHoverEntity = this._elementFromNode(node);
+        // The hovered element is the nearest one up the node's parent chain with a hover
+        // listener - the nearest-listener rule down/up use. Dispatch is still gated per event
+        // type below: having any hover listener selects the target, each event needs its own.
+        const newHoverEntity = this._hoverTarget(node);
 
         // Handle enter/leave events
         if (this._hoveredEntity !== newHoverEntity) {
@@ -898,9 +912,9 @@ class AppElement extends AsyncElement {
     }
 
     private _onPointerListenerRemoved(type: string) {
-        const hasListeners = Array.from(this.querySelectorAll<EntityBaseElement>('pc-entity, pc-node')).some((entity) =>
-            entity._hasListeners(type)
-        );
+        const hasListeners = Array.from(
+            this.querySelectorAll<EntityBaseElement>('pc-entity, pc-model, pc-node')
+        ).some((entity) => entity._hasListeners(type));
 
         if (!hasListeners && this._canvas) {
             this._hasPointerListeners[type] = false;

package/src/asset.ts

@@ -26,7 +26,8 @@ const renderModes = new Map<'simple' | 'sliced' | 'tiled', number>([
     ['tiled', SPRITE_RENDERMODE_TILED]
 ]);
 
-type AddressMode = 'repeat' | 'clamp' | 'mirror';
+/** The addressing modes for a texture asset. */
+export type AddressMode = 'repeat' | 'clamp' | 'mirror';
 
 const addressModes = new Map<AddressMode, number>([
     ['repeat', ADDRESS_REPEAT],
@@ -34,7 +35,8 @@ const addressModes = new Map<AddressMode, number>([
     ['mirror', ADDRESS_MIRRORED_REPEAT]
 ]);
 
-type MinFilterMode =
+/** 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';
 
 const minFilterModes = new Map<MinFilterMode, number>([
@@ -46,8 +48,11 @@ const minFilterModes = new Map<MinFilterMode, number>([
     ['linear-mip-linear', FILTER_LINEAR_MIPMAP_LINEAR]
 ]);
 
-// Magnification has no mip variants - the engine (and the GPU) only accepts these two.
-type MagFilterMode = 'nearest' | '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';
 
 const magFilterModes = new Map<MagFilterMode, number>([
     ['nearest', FILTER_NEAREST],
@@ -168,6 +173,10 @@ const processBufferView = (
  * 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/src/async-element.ts

@@ -33,13 +33,13 @@ class AsyncElement extends HTMLElement {
     }
 
     /**
-     * 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 {
-        return (this.parentElement?.closest('pc-entity, pc-node') as EntityBaseElement | null) ?? null;
+        return (this.parentElement?.closest('pc-entity, pc-model, pc-node') as EntityBaseElement | null) ?? null;
     }
 
     /**
@@ -95,11 +95,11 @@ type AsyncElementTagName = {
 
 /**
  * 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
@@ -120,11 +120,11 @@ function whenReady<K extends AsyncElementTagName>(target: K): Promise<HTMLElemen
 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/src/components/anim-clip.ts

@@ -22,6 +22,10 @@ import { AnimComponentElement } from './anim-component';
  * named; in a multi-track source the track named `name` is chosen, falling back to the first
  * with a warning. The element becomes ready once its resolved track is assigned.
  *
+ * @elementSummary The `<pc-anim-clip>` element declares one named animation clip on its parent
+ * `<pc-anim>`, taken from the `asset` it names or, without one, from the enclosing `<pc-model>`'s
+ * own animations. Must be a direct child of `<pc-anim>`.
+ *
  * @category Components
  */
 class AnimClipElement extends AsyncElement {

package/src/components/anim-component.ts

@@ -1,4 +1,4 @@
-import type { AnimComponent, Asset, ContainerResource } from 'playcanvas';
+import type { AnimComponent, Asset, ContainerResource, Entity } from 'playcanvas';
 import { ANIM_CONTROL_STATES, AnimTrack } from 'playcanvas';
 
 import { AssetElement } from '../asset';
@@ -46,6 +46,13 @@ type PlaybackState = {
  * the underlying {@link AnimComponent} (via {@link component}) for playback state beyond what
  * this element exposes.
  *
+ * Engine component: {@link AnimComponent} (`anim`).
+ *
+ * @elementSummary The `<pc-anim>` element plays animation clips over its entity's hierarchy, taken
+ * from `<pc-anim-clip>` children or from the enclosing `<pc-model>`'s own animations. The first
+ * clip plays automatically, and the `clip` attribute switches between them. Must be a child of a
+ * `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+ *
  * @category Components
  */
 class AnimComponentElement extends ComponentElement {
@@ -71,6 +78,12 @@ class AnimComponentElement extends ComponentElement {
      */
     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: Entity | null = null;
+
     /**
      * The element the model-readiness listener is attached to, held so disconnection can detach
      * it after `closestEntity` no longer resolves.
@@ -101,28 +114,76 @@ class AnimComponentElement extends ComponentElement {
     private _warnedClip: string | null = null;
 
     /**
-     * Rebinds when a model under the host announces readiness. The engine resolves each curve
-     * once, at the first tick after assignment, and never retries — and its mesh-instance
+     * Rebinds when a model that is not this component's host announces readiness — a sibling or
+     * deeper model whose content changed under the assigned clips. The engine resolves each
+     * curve once, at the first tick after assignment, and never retries — and its mesh-instance
      * broadcast fires before an instantiated hierarchy is parented, so a model that loads after
-     * the clips were assigned would otherwise stay silently unbound. A re-instantiation of the
-     * implicit clip source (the parent `<pc-model>`) means a new container, so the clip set
-     * refreshes instead — unless every clip declares its own asset, where a rebind suffices.
+     * the clips were assigned would otherwise stay silently unbound. The host model's own cycles
+     * are excluded: those re-enter through {@link initComponent}, which refreshes the whole clip
+     * set against the new container.
      */
     private _onModelReady = (event: Event) => {
         if (!(event.target instanceof ModelElement) || !this.component) {
             return;
         }
-        if (event.target === this.parentElement) {
-            const implicit = this._autoAssigned ||
-                [...this._assignedClips.values()].some(clip => !clip.asset);
-            if (implicit) {
-                this._refreshClips();
-                return;
-            }
+        // The host model's own readiness cycle already re-initialized this component through
+        // ComponentElement's host-ready listener, which is attached first and so has run by now.
+        // Acting here too would resolve every track twice and capture the playhead-restore
+        // snapshot mid-rebuild.
+        if (event.target === this._modelListenerTarget) {
+            return;
         }
+        // A model cycle can replace the skeleton source's host entity (a rebuild under a
+        // retargeting pc-node), so the binding root is re-asserted before the rebind.
+        this._applyRootBone();
         this.component.rebind();
     };
 
+    /**
+     * The model whose host entity scopes this component's curve binding: the parent `pc-model`,
+     * or the sole `pc-model` among the parent's direct children (the arrangement where clips
+     * live in a library asset beside the skeleton). `null` when there is no such model, or more
+     * than one — an ambiguous skeleton is left to the engine's name-based resolution.
+     */
+    private _skeletonSource(): ModelElement | null {
+        const parent = this.parentElement;
+        if (parent instanceof ModelElement) {
+            return parent;
+        }
+        const models = parent ? parent.querySelectorAll(':scope > pc-model') : null;
+        return models?.length === 1 && models[0] instanceof ModelElement ? models[0] : null;
+    }
+
+    /**
+     * Keeps the component's binding root pointing at the skeleton source's host entity. The host
+     * wraps the instantiated content, so left at its default — the component's own entity — the
+     * engine binder mis-resolves curves that target the asset's root node: its fallback treats
+     * the graph as the asset root once the root is no longer a direct child.
+     *
+     * Authoritative in both directions for values this element assigned: a source appearing pins
+     * its host, and a source dissolving (the model gone, or a second model making the skeleton
+     * ambiguous) clears the pin rather than leaving it on a stale host. A root assigned through
+     * the engine API is never overwritten — the user's choice outranks the managed default.
+     * Writes are skipped while unchanged, because the engine setter itself triggers a rebind.
+     */
+    private _applyRootBone() {
+        const component = this.component;
+
+        // A non-null root this element did not assign came through the engine API. A fresh
+        // component starts at null, which is always reclaimable.
+        if (component.rootBone !== null && component.rootBone !== this._managedRootBone) {
+            return;
+        }
+
+        const host = this._skeletonSource()?.entity ?? null;
+        if (component.rootBone !== host) {
+            // The engine setter accepts null - restoring the component's own entity as the
+            // binding graph - but its declared type does not
+            component.rootBone = host as Entity;
+        }
+        this._managedRootBone = host;
+    }
+
     /** @ignore */
     constructor() {
         super('anim');
@@ -151,7 +212,16 @@ class AnimComponentElement extends ComponentElement {
             this._modelListenerTarget = host;
         }
 
-        this._applyClips();
+        this._applyRootBone();
+
+        if (this.component.baseLayer) {
+            // The component survived the host's readiness cycle (a pc-model reloading content on
+            // its stable host entity). A loaded graph cannot be reassigned in place, so drop it
+            // and reassign from the current source, restoring the active clip and playhead.
+            this._refreshClips();
+        } else {
+            this._applyClips();
+        }
     }
 
     disconnectedCallback() {
@@ -163,6 +233,7 @@ class AnimComponentElement extends ComponentElement {
         this._sourceGeneration++;
         this._assignedClips.clear();
         this._autoAssigned = false;
+        this._managedRootBone = null;
 
         super.disconnectedCallback();
     }
@@ -353,6 +424,10 @@ class AnimComponentElement extends ComponentElement {
         if (!component) {
             return;
         }
+        // A clip-set change is also a chance for the skeleton source to have changed shape (a
+        // clip child appearing or leaving can accompany a model coming or going) - re-derive the
+        // binding root before the reassignment binds against it.
+        this._applyRootBone();
         const layer = component.baseLayer;
         const restore = layer ? {
             state: layer.activeState,

package/src/components/audio-listener-component.ts

@@ -0,0 +1,36 @@
+import type { AudioListenerComponent } from 'playcanvas';
+
+import { ComponentElement } from './component';
+
+/**
+ * The AudioListenerComponentElement interface provides properties and methods for manipulating
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-audio-listener/ | `<pc-audio-listener>`} elements.
+ * The AudioListenerComponentElement interface also inherits the properties and methods of the
+ * {@link HTMLElement} interface.
+ *
+ * Engine component: {@link AudioListenerComponent} (`audiolistener`).
+ *
+ * @elementSummary The `<pc-audio-listener>` element makes its entity the point from which
+ * positional sounds are heard, typically the entity holding the `<pc-camera>`. Must be a child of a
+ * `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+ *
+ * @category Components
+ */
+class AudioListenerComponentElement extends ComponentElement {
+    /** @ignore */
+    constructor() {
+        super('audiolistener');
+    }
+
+    /**
+     * Gets the underlying PlayCanvas audio listener component.
+     * @returns The audio listener component.
+     */
+    get component(): AudioListenerComponent {
+        return super.component as AudioListenerComponent;
+    }
+}
+
+customElements.define('pc-audio-listener', AudioListenerComponentElement);
+
+export { AudioListenerComponentElement };

package/src/components/button-component.ts

@@ -17,6 +17,13 @@ const transitionModes = new Map<'tint' | 'sprite', number>([
  * The ButtonComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link ButtonComponent} (`button`).
+ *
+ * @elementSummary The `<pc-button>` element makes its entity respond to pointer input, tinting or
+ * swapping its image as the pointer hovers, presses and releases it. The entity also needs a
+ * `<pc-element>` with `use-input` set. Must be a child of a `<pc-entity>`, `<pc-model>` or
+ * `<pc-node>`.
+ *
  * @category Components
  */
 class ButtonComponentElement extends ComponentElement {
@@ -121,7 +128,9 @@ class ButtonComponentElement extends ComponentElement {
 
     /**
      * Sets the reference (CSS selector, element id or entity name) to the `<pc-entity>` whose image
-     * element is used for visual transitions. Defaults to the button's own entity.
+     * element is used for visual transitions. Defaults to the button's own entity — inside a
+     * `<pc-model>`, that is the model's host entity, so supply an explicit reference to target a
+     * UI entity instead.
      * @param value - The image entity reference.
      */
     set image(value: string) {