@playcanvas/web-components 0.16.0 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcanvas/web-components",
-  "version": "0.16.0",
+  "version": "0.17.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
@@ -163,9 +170,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 +267,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 +277,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 +469,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 +610,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 +667,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 +680,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 +840,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 +908,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/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-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,8 @@ type PlaybackState = {
  * the underlying {@link AnimComponent} (via {@link component}) for playback state beyond what
  * this element exposes.
  *
+ * Engine component: {@link AnimComponent} (`anim`).
+ *
  * @category Components
  */
 class AnimComponentElement extends ComponentElement {
@@ -71,6 +73,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 +109,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 +207,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 +228,7 @@ class AnimComponentElement extends ComponentElement {
         this._sourceGeneration++;
         this._assignedClips.clear();
         this._autoAssigned = false;
+        this._managedRootBone = null;
 
         super.disconnectedCallback();
     }
@@ -353,6 +419,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/{listener-component.ts → audio-listener-component.ts}

@@ -3,14 +3,16 @@ import type { AudioListenerComponent } from 'playcanvas';
 import { ComponentElement } from './component';
 
 /**
- * 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
  */
-class ListenerComponentElement extends ComponentElement {
+class AudioListenerComponentElement extends ComponentElement {
     /** @ignore */
     constructor() {
         super('audiolistener');
@@ -25,6 +27,6 @@ class ListenerComponentElement extends ComponentElement {
     }
 }
 
-customElements.define('pc-listener', ListenerComponentElement);
+customElements.define('pc-audio-listener', AudioListenerComponentElement);
 
-export { ListenerComponentElement };
+export { AudioListenerComponentElement };

package/src/components/button-component.ts

@@ -17,6 +17,8 @@ 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`).
+ *
  * @category Components
  */
 class ButtonComponentElement extends ComponentElement {
@@ -121,7 +123,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) {

package/src/components/camera-component.ts

@@ -41,6 +41,8 @@ const tonemaps = new Map<'none' | 'linear' | 'filmic' | 'hejl' | 'aces' | 'aces2
  * The CameraComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link CameraComponent} (`camera`).
+ *
  * @category Components
  */
 class CameraComponentElement extends ComponentElement {

package/src/components/collision-component.ts

@@ -17,6 +17,8 @@ import { ComponentElement } from './component';
  * 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
  */
 class CollisionComponentElement extends ComponentElement {
@@ -64,7 +66,9 @@ class CollisionComponentElement extends ComponentElement {
      * no attribute to supply it - so the host's visible geometry, the meaning a mesh collider
      * on a glTF node carries, fills the gap. Runs on every application (so a rebound `pc-node`
      * recomputes it) and on a runtime switch to `type="mesh"`; an explicitly assigned
-     * `renderAsset` is never overwritten.
+     * `renderAsset` is never overwritten. A `pc-model` host entity never carries a render
+     * component (the instantiated content beneath it does), so a mesh collider that should take
+     * an asset's geometry belongs on a bound `pc-node`.
      */
     private _applyMeshGeometryDefault() {
         const component = this.component;

package/src/components/component.ts

@@ -109,7 +109,7 @@ class ComponentElement extends AsyncElement {
             // It still becomes ready (with a null `component`), so warn rather than fail silently
             const label = this.id ? ` '${this.id}'` : '';
             console.warn(
-                `${this.tagName.toLowerCase()}${label} must be a descendant of pc-entity - component not added`
+                `${this.tagName.toLowerCase()}${label} must be a descendant of pc-entity, pc-model or pc-node - component not added`
             );
             return;
         }
@@ -214,8 +214,9 @@ class ComponentElement extends AsyncElement {
 
     /**
      * The PlayCanvas component instance. `null` until the element is ready, and also for an
-     * element that is not a descendant of a `<pc-entity>` — await {@link whenReady} or the
-     * element's `ready()` promise before accessing it.
+     * element that is not a descendant of an entity-fronting element (`<pc-entity>`,
+     * `<pc-model>` or `<pc-node>`) — await {@link whenReady} or the element's `ready()` promise
+     * before accessing it.
      * @returns The component instance, or `null`.
      */
     get component(): Component | null {

package/src/components/element-component.ts

@@ -12,6 +12,13 @@ import { ComponentElement } from './component';
  * 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
  */
 class ElementComponentElement extends ComponentElement {

package/src/components/gsplat-component.ts

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

package/src/components/joint-component.ts

@@ -26,6 +26,8 @@ type MotionMode = 'locked' | 'limited' | 'free';
  * constraint breaks. A broken joint no longer constrains its bodies; calling `refreshFrames()` on
  * the underlying component re-attaches it. Bubbles and is composed.
  *
+ * Engine component: {@link JointComponent} (`joint`).
+ *
  * @category Components
  */
 class JointComponentElement extends ComponentElement {

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

@@ -6,10 +6,12 @@ import { ComponentElement } from './component';
 
 /**
  * The LayoutChildComponentElement interface provides properties and methods for manipulating
- * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-layoutchild/ | `<pc-layoutchild>`} elements.
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-layout-child/ | `<pc-layout-child>`} elements.
  * The LayoutChildComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link LayoutChildComponent} (`layoutchild`).
+ *
  * @category Components
  */
 class LayoutChildComponentElement extends ComponentElement {
@@ -229,6 +231,6 @@ class LayoutChildComponentElement extends ComponentElement {
     }
 }
 
-customElements.define('pc-layoutchild', LayoutChildComponentElement);
+customElements.define('pc-layout-child', LayoutChildComponentElement);
 
 export { LayoutChildComponentElement };

package/src/components/{layoutgroup-component.ts → layout-group-component.ts}

@@ -28,10 +28,12 @@ const fittings = new Map<'none' | 'stretch' | 'shrink' | 'both', number>([
 
 /**
  * The LayoutGroupComponentElement interface provides properties and methods for manipulating
- * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-layoutgroup/ | `<pc-layoutgroup>`} elements.
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-layout-group/ | `<pc-layout-group>`} elements.
  * The LayoutGroupComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link LayoutGroupComponent} (`layoutgroup`).
+ *
  * @category Components
  */
 class LayoutGroupComponentElement extends ComponentElement {
@@ -304,6 +306,6 @@ class LayoutGroupComponentElement extends ComponentElement {
     }
 }
 
-customElements.define('pc-layoutgroup', LayoutGroupComponentElement);
+customElements.define('pc-layout-group', LayoutGroupComponentElement);
 
 export { LayoutGroupComponentElement };

package/src/components/light-component.ts

@@ -37,6 +37,8 @@ const shadowTypes = new Map<
  * The LightComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link LightComponent} (`light`).
+ *
  * @category Components
  */
 class LightComponentElement extends ComponentElement {

package/src/components/{particlesystem-component.ts → particle-system-component.ts}

@@ -6,10 +6,12 @@ import { ComponentElement } from './component';
 
 /**
  * The ParticleSystemComponentElement interface provides properties and methods for manipulating
- * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-particles/ | `<pc-particles>`} elements.
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-particle-system/ | `<pc-particle-system>`} elements.
  * The ParticleSystemComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link ParticleSystemComponent} (`particlesystem`).
+ *
  * @category Components
  */
 class ParticleSystemComponentElement extends ComponentElement {
@@ -147,6 +149,6 @@ class ParticleSystemComponentElement extends ComponentElement {
     }
 }
 
-customElements.define('pc-particles', ParticleSystemComponentElement);
+customElements.define('pc-particle-system', ParticleSystemComponentElement);
 
 export { ParticleSystemComponentElement };

package/src/components/render-component.ts

@@ -15,6 +15,8 @@ import { ComponentElement } from './component';
  * to `box`). It does not cover the engine's `asset` render type, since there is no way to supply
  * a render asset here — use `pc-model` for glTF content instead.
  *
+ * Engine component: {@link RenderComponent} (`render`).
+ *
  * @category Components
  */
 class RenderComponentElement extends ComponentElement {