@playcanvas/web-components 0.17.0 → 0.18.0

package/dist/pwc.js

@@ -125,6 +125,10 @@
      * A `<pc-wasm>` without a `name` warns and never becomes ready; a containing `<pc-app>` still
      * boots.
      *
+     * @elementSummary The `<pc-wasm>` element loads a WebAssembly module the engine needs before the
+     * application starts — `Ammo` for physics, `Basis` or `DracoDecoderModule` for compressed assets.
+     * Must be a direct child of `<pc-app>`.
+     *
      * @attribute {string} name - The name of the WebAssembly module to configure, e.g. `Basis` or
      * `Ammo`.
      * @attribute {string} glue - The URL of the module's glue script.
@@ -766,6 +770,10 @@
      * 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
@@ -1704,7 +1712,7 @@
          * Tracks whether an inline `onpointer*` attribute is present. The browser itself compiles and
          * runs these attributes — they are standard `GlobalEventHandlers`, so setting one replaces
          * the previous handler and removing it removes the handler, exactly like `onclick` on any
-         * HTML element. But because they bypass {@link addEventListener}, the connect/disconnect
+         * HTML element. But because they bypass {@link EventTarget.addEventListener}, the connect/disconnect
          * bookkeeping that lets the application lazily attach its canvas pointer handlers must be
          * kept in sync here.
          *
@@ -1745,7 +1753,7 @@
         }
         /**
          * Whether the element has a listener for an event type, registered either with
-         * {@link addEventListener} or with the matching inline `onpointer*` attribute. Read by the
+         * {@link EventTarget.addEventListener} or with the matching inline `onpointer*` attribute. Read by the
          * containing `<pc-app>` element to gate pointer event synthesis.
          *
          * @param type - The event type.
@@ -1814,7 +1822,7 @@
          */
         _tags = [];
         /**
-         * Whether the hierarchy has been built for this entity — set once {@link _buildHierarchy} has
+         * Whether the hierarchy has been built for this entity — set once `_buildHierarchy` has
          * parented it. Read by subclasses that gate work on the entity being in the scene graph.
          */
         _built = false;
@@ -1903,7 +1911,7 @@
             this._onBuilt();
         }
         /**
-         * Called by {@link _buildHierarchy} once the backing entity has been parented — exactly once
+         * Called by `_buildHierarchy` once the backing entity has been parented — exactly once
          * per build cycle. The default announces readiness, which is what a parented `<pc-entity>`
          * means; `<pc-model>` overrides it to start loading content instead, because its readiness
          * tracks the content settling rather than the host entering the scene graph.
@@ -2024,9 +2032,14 @@
      *
      * The pointer events below are dispatched by the containing `<pc-app>` element when the pointer
      * intersects this entity's geometry. They are only generated while the entity has a listener for
-     * them, registered either with {@link addEventListener} or with the matching inline `onpointer*`
+     * them, registered either with {@link EventTarget.addEventListener} or with the matching inline `onpointer*`
      * attribute.
      *
+     * @elementSummary The `<pc-entity>` element creates an entity: a named, transformable node of the
+     * scene hierarchy, and the host for component elements such as `<pc-camera>`, `<pc-light>` and
+     * `<pc-render>`. Place it in the `<pc-scene>`, or nest it under another `<pc-entity>`, a
+     * `<pc-model>` or a `<pc-node>` to parent it there.
+     *
      * @attribute {boolean} enabled - The enabled state of the entity.
      * @attribute {string} name - The name of the entity.
      * @attribute {string} position - The position of the entity.
@@ -2407,6 +2420,10 @@
      * 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.
@@ -3033,6 +3050,11 @@
      * intersects the model's geometry, exactly as for `<pc-entity>` — a hit on a content node that no
      * `pc-node` fronts resolves to this element.
      *
+     * @elementSummary The `<pc-model>` element instantiates a 3D model from a container asset
+     * (typically a GLB) beneath an entity of its own, so the element's transform and tags place the
+     * instance in the scene. Its `<pc-node>` children override what the asset authored. Place it in the
+     * `<pc-scene>`, or nest it under a `<pc-entity>`, another `<pc-model>` or a `<pc-node>`.
+     *
      * @attribute {boolean} enabled - The enabled state of the model.
      * @attribute {string} name - The name of the model.
      * @attribute {string} position - The position of the model.
@@ -3566,6 +3588,11 @@
      *
      * 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 {
@@ -4184,6 +4211,10 @@
      * 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 {
@@ -4512,6 +4543,10 @@
      *
      * 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 {
@@ -4541,6 +4576,11 @@
      *
      * 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 {
@@ -4944,13 +4984,18 @@
      *
      * Engine component: {@link CameraComponent} (`camera`).
      *
+     * @elementSummary The `<pc-camera>` element renders the scene from its entity's transform, with
+     * attributes for the projection, field of view, clip planes, clear color and tonemapping. Must be a
+     * child of a `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+     *
      * @category Components
      */
     class CameraComponentElement extends ComponentElement {
         _clearColor = new playcanvas.Color(0.75, 0.75, 0.75, 1);
         _clearColorBuffer = true;
+        _clearDepth = 1;
         _clearDepthBuffer = true;
-        _clearStencilBuffer = false;
+        _clearStencilBuffer = true;
         _cullFaces = true;
         _farClip = 1000;
         _flipFaces = false;
@@ -4973,6 +5018,7 @@
             return {
                 clearColor: this._clearColor,
                 clearColorBuffer: this._clearColorBuffer,
+                clearDepth: this._clearDepth,
                 clearDepthBuffer: this._clearDepthBuffer,
                 clearStencilBuffer: this._clearStencilBuffer,
                 cullFaces: this._cullFaces,
@@ -4991,9 +5037,31 @@
                 toneMapping: tonemaps.get(this._tonemap) ?? playcanvas.TONEMAP_NONE
             };
         }
-        get xrAvailable() {
+        /**
+         * Whether immersive AR is available. Independent of {@link vrAvailable}: a device can offer
+         * either mode without the other.
+         * @returns Whether immersive AR is available.
+         */
+        get arAvailable() {
+            return this._available(playcanvas.XRTYPE_AR);
+        }
+        /**
+         * Whether immersive VR is available. Independent of {@link arAvailable}: a device can offer
+         * either mode without the other.
+         * @returns Whether immersive VR is available.
+         */
+        get vrAvailable() {
+            return this._available(playcanvas.XRTYPE_VR);
+        }
+        /**
+         * Whether one XR session type is available on this device.
+         *
+         * @param type - The XR session type to test.
+         * @returns Whether that type is available.
+         */
+        _available(type) {
             const xrManager = this.component?.system.app.xr;
-            return xrManager && xrManager.supported && xrManager.isAvailable(playcanvas.XRTYPE_VR);
+            return Boolean(xrManager?.supported && xrManager.isAvailable(type));
         }
         /**
          * Starts the camera in XR mode.
@@ -5001,11 +5069,13 @@
          * @param space - The space to start the camera in.
          */
         startXr(type, space) {
-            if (this.component && this.xrAvailable) {
+            // Gated on the mode being started, not on XR in general: a device that offers only
+            // one of the two would otherwise accept a session it cannot serve
+            if (this.component && this._available(type)) {
                 this.component.startXr(type, space, {
                     callback: (err) => {
                         if (err)
-                            console.error(`WebXR Immersive VR failed to start: ${err.message}`);
+                            console.error(`WebXR ${type} failed to start: ${err.message}`);
                     }
                 });
             }
@@ -5059,6 +5129,23 @@
         get clearColorBuffer() {
             return this._clearColorBuffer;
         }
+        /**
+         * Sets the depth value the depth buffer is cleared to. Defaults to 1.
+         * @param value - The clear depth value.
+         */
+        set clearDepth(value) {
+            this._clearDepth = value;
+            if (this.component) {
+                this.component.clearDepth = value;
+            }
+        }
+        /**
+         * Gets the depth value the depth buffer is cleared to.
+         * @returns The clear depth value.
+         */
+        get clearDepth() {
+            return this._clearDepth;
+        }
         /**
          * Sets the clear depth buffer of the camera.
          * @param value - The clear depth buffer.
@@ -5337,6 +5424,7 @@
                 ...super.observedAttributes,
                 'clear-color',
                 'clear-color-buffer',
+                'clear-depth',
                 'clear-depth-buffer',
                 'clear-stencil-buffer',
                 'cull-faces',
@@ -5364,11 +5452,14 @@
                 case 'clear-color-buffer':
                     this.clearColorBuffer = parseBool(newValue, true);
                     break;
+                case 'clear-depth':
+                    this.clearDepth = parseNumber(newValue, 1, name);
+                    break;
                 case 'clear-depth-buffer':
                     this.clearDepthBuffer = parseBool(newValue, true);
                     break;
                 case 'clear-stencil-buffer':
-                    this.clearStencilBuffer = parseBool(newValue, false);
+                    this.clearStencilBuffer = parseBool(newValue, true);
                     break;
                 case 'cull-faces':
                     this.cullFaces = parseBool(newValue, true);
@@ -5431,6 +5522,10 @@
      *
      * Engine component: {@link CollisionComponent} (`collision`).
      *
+     * @elementSummary The `<pc-collision>` element gives its entity a collision shape — a box, sphere,
+     * capsule, cone, cylinder or mesh — for the physics simulation to collide against. Pair it with a
+     * `<pc-rigid-body>`. Must be a child of a `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+     *
      * @category Components
      */
     class CollisionComponentElement extends ComponentElement {
@@ -5621,6 +5716,10 @@
      *
      * Engine component: {@link ElementComponent} (`element`).
      *
+     * @elementSummary The `<pc-element>` element gives its entity a 2D UI rectangle inside a
+     * `<pc-screen>` hierarchy, drawing an image, a line of text or nothing (`type="image"`, `"text"` or
+     * `"group"`). Must be a child of a `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+     *
      * @category Components
      */
     class ElementComponentElement extends ComponentElement {
@@ -6305,6 +6404,11 @@
      * a rigid body component; leaving `entity-b` empty constrains `entity-a` to a fixed point in world
      * space. The underlying engine component is in alpha, so its API may change.
      *
+     * @elementSummary The `<pc-joint>` element constrains two rigid bodies to each other — a hinged
+     * door, a swinging chain, a sliding drawer. Its entity's transform is the joint frame, and
+     * `entity-a` and `entity-b` name the bodies. Must be a child of a `<pc-entity>`, `<pc-model>` or
+     * `<pc-node>`.
+     *
      * @fires {CustomEvent} break - Fired when the impulse on the joint exceeds `break-impulse` and the
      * constraint breaks. A broken joint no longer constrains its bodies; calling `refreshFrames()` on
      * the underlying component re-attaches it. Bubbles and is composed.
@@ -7175,6 +7279,10 @@
      *
      * Engine component: {@link LayoutChildComponent} (`layoutchild`).
      *
+     * @elementSummary The `<pc-layout-child>` element controls how its entity is sized by the
+     * `<pc-layout-group>` above it, through minimum and maximum sizes and fit proportions. Must be a
+     * child of a `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+     *
      * @category Components
      */
     class LayoutChildComponentElement extends ComponentElement {
@@ -7387,6 +7495,10 @@
      *
      * Engine component: {@link LayoutGroupComponent} (`layoutgroup`).
      *
+     * @elementSummary The `<pc-layout-group>` element arranges its entity's children in a row or
+     * column, with spacing, padding, alignment and fitting. Must be a child of a `<pc-entity>`,
+     * `<pc-model>` or `<pc-node>`.
+     *
      * @category Components
      */
     class LayoutGroupComponentElement extends ComponentElement {
@@ -7647,23 +7759,30 @@
      *
      * Engine component: {@link LightComponent} (`light`).
      *
+     * @elementSummary The `<pc-light>` element lights the scene from its entity — as a directional,
+     * omni or spot light — with attributes for color, intensity, range and shadows. Must be a child of
+     * a `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+     *
      * @category Components
      */
     class LightComponentElement extends ComponentElement {
+        _cascadeBlend = 0;
+        _cascadeDistribution = 0.5;
         _castShadows = false;
         _color = new playcanvas.Color(1, 1, 1);
         _innerConeAngle = 40;
         _intensity = 1;
-        _normalOffsetBias = 0.05;
+        _normalOffsetBias = 0;
+        _numCascades = 1;
         _outerConeAngle = 45;
         _range = 10;
-        _shadowBias = 0.2;
-        _shadowDistance = 16;
+        _shadowBias = 0.05;
+        _shadowDistance = 40;
         _shadowIntensity = 1;
         _shadowResolution = 1024;
         _shadowType = 'pcf3-32f';
         _type = 'directional';
-        _vsmBias = 0.01;
+        _vsmBias = 0.0025;
         _vsmBlurSize = 11;
         _penumbraSize = 1;
         _penumbraFalloff = 1;
@@ -7675,11 +7794,14 @@
         }
         getInitialComponentData() {
             return {
+                cascadeBlend: this._cascadeBlend,
+                cascadeDistribution: this._cascadeDistribution,
                 castShadows: this._castShadows,
                 color: this._color,
                 innerConeAngle: this._innerConeAngle,
                 intensity: this._intensity,
                 normalOffsetBias: this._normalOffsetBias,
+                numCascades: this._numCascades,
                 outerConeAngle: this._outerConeAngle,
                 penumbraFalloff: this._penumbraFalloff,
                 penumbraSize: this._penumbraSize,
@@ -7690,7 +7812,7 @@
                 shadowIntensity: this._shadowIntensity,
                 shadowResolution: this._shadowResolution,
                 shadowSamples: this._shadowSamples,
-                shadowType: shadowTypes.get(this._shadowType),
+                shadowType: shadowTypes.get(this._shadowType) ?? playcanvas.SHADOW_PCF3_32F,
                 type: this._type,
                 vsmBias: this._vsmBias,
                 vsmBlurSize: this._vsmBlurSize
@@ -7703,6 +7825,47 @@
         get component() {
             return super.component;
         }
+        /**
+         * Sets the fraction of each shadow cascade that is blended into the next one, from 0 (no
+         * blending) to 1, which applies only to `directional` lights with `num-cascades` greater than
+         * 1. Defaults to 0.
+         * @param value - The cascade blend factor.
+         */
+        set cascadeBlend(value) {
+            this._cascadeBlend = value;
+            if (this.component) {
+                this.component.cascadeBlend = value;
+            }
+        }
+        /**
+         * Gets the cascade blend factor of the light, from 0 (no blending) to 1, which applies only to
+         * `directional` lights with `num-cascades` greater than 1.
+         * @returns The cascade blend factor.
+         */
+        get cascadeBlend() {
+            return this._cascadeBlend;
+        }
+        /**
+         * Sets the distribution of the camera frustum split between shadow cascades, from 0 (linear
+         * split) to 1 (logarithmic split, concentrating shadow resolution near the camera), which
+         * applies only to `directional` lights with `num-cascades` greater than 1. Defaults to 0.5.
+         * @param value - The cascade distribution.
+         */
+        set cascadeDistribution(value) {
+            this._cascadeDistribution = value;
+            if (this.component) {
+                this.component.cascadeDistribution = value;
+            }
+        }
+        /**
+         * Gets the cascade distribution of the light, from 0 (linear split) to 1 (logarithmic split,
+         * concentrating shadow resolution near the camera), which applies only to `directional` lights
+         * with `num-cascades` greater than 1.
+         * @returns The cascade distribution.
+         */
+        get cascadeDistribution() {
+            return this._cascadeDistribution;
+        }
         /**
          * Sets the cast shadows flag of the light.
          * @param value - The cast shadows flag.
@@ -7788,6 +7951,25 @@
         get normalOffsetBias() {
             return this._normalOffsetBias;
         }
+        /**
+         * Sets the number of shadow cascades of the light, an integer from 1 (no cascades) to 4, which
+         * applies only to `directional` lights. Defaults to 1.
+         * @param value - The number of shadow cascades.
+         */
+        set numCascades(value) {
+            this._numCascades = value;
+            if (this.component) {
+                this.component.numCascades = value;
+            }
+        }
+        /**
+         * Gets the number of shadow cascades of the light, an integer from 1 (no cascades) to 4, which
+         * applies only to `directional` lights.
+         * @returns The number of shadow cascades.
+         */
+        get numCascades() {
+            return this._numCascades;
+        }
         /**
          * Sets the outer cone angle of the light.
          * @param value - The outer cone angle.
@@ -8040,11 +8222,14 @@
         static get observedAttributes() {
             return [
                 ...super.observedAttributes,
-                'color',
+                'cascade-blend',
+                'cascade-distribution',
                 'cast-shadows',
-                'intensity',
+                'color',
                 'inner-cone-angle',
+                'intensity',
                 'normal-offset-bias',
+                'num-cascades',
                 'outer-cone-angle',
                 'penumbra-falloff',
                 'penumbra-size',
@@ -8064,12 +8249,18 @@
         attributeChangedCallback(name, _oldValue, newValue) {
             super.attributeChangedCallback(name, _oldValue, newValue);
             switch (name) {
-                case 'color':
-                    this.color = parseColor(newValue, playcanvas.Color.WHITE, name);
+                case 'cascade-blend':
+                    this.cascadeBlend = parseNumber(newValue, 0, name);
+                    break;
+                case 'cascade-distribution':
+                    this.cascadeDistribution = parseNumber(newValue, 0.5, name);
                     break;
                 case 'cast-shadows':
                     this.castShadows = parseBool(newValue, false);
                     break;
+                case 'color':
+                    this.color = parseColor(newValue, playcanvas.Color.WHITE, name);
+                    break;
                 case 'inner-cone-angle':
                     this.innerConeAngle = parseNumber(newValue, 40, name);
                     break;
@@ -8077,7 +8268,10 @@
                     this.intensity = parseNumber(newValue, 1, name);
                     break;
                 case 'normal-offset-bias':
-                    this.normalOffsetBias = parseNumber(newValue, 0.05, name);
+                    this.normalOffsetBias = parseNumber(newValue, 0, name);
+                    break;
+                case 'num-cascades':
+                    this.numCascades = parseNumber(newValue, 1, name);
                     break;
                 case 'outer-cone-angle':
                     this.outerConeAngle = parseNumber(newValue, 45, name);
@@ -8092,20 +8286,20 @@
                     this.range = parseNumber(newValue, 10, name);
                     break;
                 case 'shadow-bias':
-                    this.shadowBias = parseNumber(newValue, 0.2, name);
-                    break;
-                case 'shadow-distance':
-                    this.shadowDistance = parseNumber(newValue, 16, name);
+                    this.shadowBias = parseNumber(newValue, 0.05, name);
                     break;
                 case 'shadow-blocker-samples':
                     this.shadowBlockerSamples = parseNumber(newValue, 16, name);
                     break;
-                case 'shadow-resolution':
-                    this.shadowResolution = parseNumber(newValue, 1024, name);
+                case 'shadow-distance':
+                    this.shadowDistance = parseNumber(newValue, 40, name);
                     break;
                 case 'shadow-intensity':
                     this.shadowIntensity = parseNumber(newValue, 1, name);
                     break;
+                case 'shadow-resolution':
+                    this.shadowResolution = parseNumber(newValue, 1024, name);
+                    break;
                 case 'shadow-samples':
                     this.shadowSamples = parseNumber(newValue, 16, name);
                     break;
@@ -8116,7 +8310,7 @@
                     this.type = parseEnum(newValue, ['directional', 'omni', 'spot'], 'directional', name);
                     break;
                 case 'vsm-bias':
-                    this.vsmBias = parseNumber(newValue, 0.01, name);
+                    this.vsmBias = parseNumber(newValue, 0.0025, name);
                     break;
                 case 'vsm-blur-size':
                     this.vsmBlurSize = parseNumber(newValue, 11, name);
@@ -8134,6 +8328,10 @@
      *
      * Engine component: {@link ParticleSystemComponent} (`particlesystem`).
      *
+     * @elementSummary The `<pc-particle-system>` element emits particles from its entity, with
+     * attributes for the emitter's shape, rate, lifetime, textures and blending. Must be a child of a
+     * `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+     *
      * @category Components
      */
     class ParticleSystemComponentElement extends ComponentElement {
@@ -8282,6 +8480,8 @@
         ['ao', playcanvas.SPECOCC_AO],
         ['gloss-dependent', playcanvas.SPECOCC_GLOSSDEPENDENT]
     ]);
+    // The DITHER_* constants are strings whose values are exactly these names, so a parsed value is
+    // assigned to the material unchanged rather than mapped through a table.
     const opacityDithers = ['none', 'bayer8', 'bluenoise', 'ignnoise'];
     const colorChannels = ['r', 'g', 'b', 'a', 'rgb'];
     const scalarChannels = ['r', 'g', 'b', 'a'];
@@ -8318,6 +8518,10 @@
      * The two aliases are documented here rather than on an accessor, because they resolve to the
      * `gloss` properties and would otherwise inherit gloss's description - which reads inverted.
      *
+     * @elementSummary The `<pc-material>` element defines a physically based material, which
+     * `<pc-render>` elements apply by naming its `id`. It is metal/rough by default, with `metalness`
+     * starting at 0. Must be a direct child of `<pc-app>`.
+     *
      * @attribute {number} roughness - The roughness of the material, from 0 (shiny) to 1 (rough). An
      * alias for `gloss` that also inverts it, so do not combine it with the `gloss` attributes.
      * @attribute {string} roughness-map - The id of the `pc-asset` to use as the roughness map. An
@@ -10486,6 +10690,11 @@
      *
      * Engine component: {@link RenderComponent} (`render`).
      *
+     * @elementSummary The `<pc-render>` element renders one of the engine's built-in primitives at its
+     * entity — box, sphere, capsule, cone, cylinder or plane — shaded by the `<pc-material>` its
+     * `material` attribute names. For glTF content, use `<pc-model>` instead. Must be a child of a
+     * `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+     *
      * @category Components
      */
     class RenderComponentElement extends ComponentElement {
@@ -10616,6 +10825,11 @@
      *
      * Engine component: {@link RigidBodyComponent} (`rigidbody`).
      *
+     * @elementSummary The `<pc-rigid-body>` element hands its entity to the physics simulation, with
+     * attributes for its type, mass, friction and restitution. It needs a sibling `<pc-collision>` for
+     * its shape, and `Ammo` loaded through `<pc-wasm>`. Must be a child of a `<pc-entity>`,
+     * `<pc-model>` or `<pc-node>`.
+     *
      * @category Components
      */
     class RigidBodyComponentElement extends ComponentElement {
@@ -10825,6 +11039,10 @@
      *
      * Engine component: {@link ScreenComponent} (`screen`).
      *
+     * @elementSummary The `<pc-screen>` element gives its entity a 2D space — in screen space or in the
+     * world — that a hierarchy of `<pc-element>` descendants lays out inside. Must be a child of a
+     * `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+     *
      * @category Components
      */
     class ScreenComponentElement extends ComponentElement {
@@ -10979,6 +11197,10 @@
      *
      * Engine component: {@link ScrollbarComponent} (`scrollbar`).
      *
+     * @elementSummary The `<pc-scrollbar>` element gives its entity a draggable handle reporting a
+     * position from 0 to 1, which a `<pc-scroll-view>` references to scroll its content. Must be a
+     * child of a `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+     *
      * @category Components
      */
     class ScrollbarComponentElement extends ComponentElement {
@@ -11120,6 +11342,10 @@
      *
      * Engine component: {@link ScrollViewComponent} (`scrollview`).
      *
+     * @elementSummary The `<pc-scroll-view>` element scrolls a larger content entity within a clipped
+     * viewport at its entity, optionally driven by the `<pc-scrollbar>` elements it references. Must be
+     * a child of a `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+     *
      * @category Components
      */
     class ScrollViewComponentElement extends ComponentElement {
@@ -11506,6 +11732,10 @@
      * The element becomes ready once its script instance has been created by the parent
      * `<pc-script>` element.
      *
+     * @elementSummary The `<pc-script-instance>` element attaches one script class, named by `name`, to
+     * the entity of its parent `<pc-script>`. Its other attributes set script attributes of the same
+     * name, and `attributes` takes a JSON object instead. Must be a direct child of `<pc-script>`.
+     *
      * @fires {CustomEvent} scriptattributeschange - Fired when the script's attributes change. The
      * `detail` carries the new `attributes` object. Bubbles.
      * @fires {CustomEvent} scriptenablechange - Fired when the script's enabled state changes. The
@@ -11850,6 +12080,9 @@
      *
      * Engine component: {@link ScriptComponent} (`script`).
      *
+     * @elementSummary The `<pc-script>` element holds the `<pc-script-instance>` children that attach
+     * scripts to its entity. Must be a child of a `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+     *
      * @category Components
      */
     class ScriptComponentElement extends ComponentElement {
@@ -12299,6 +12532,10 @@
      *
      * Engine component: {@link SoundComponent} (`sound`).
      *
+     * @elementSummary The `<pc-sound>` element holds the `<pc-sound-slot>` children that play sounds at
+     * its entity, along with the positional audio settings they share. Must be a child of a
+     * `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+     *
      * @category Components
      */
     class SoundComponentElement extends ComponentElement {
@@ -12495,6 +12732,9 @@
      * The SoundSlotElement interface provides properties and methods for manipulating
      * `<pc-sound-slot>` elements. The SoundSlotElement interface also inherits the properties and
      * methods of the {@link AsyncElement} interface.
+     *
+     * @elementSummary The `<pc-sound-slot>` element declares one named sound on its parent `<pc-sound>`
+     * — its asset, volume, pitch, looping and autoplay. Must be a direct child of `<pc-sound>`.
      */
     class SoundSlotElement extends AsyncElement {
         _asset = '';
@@ -12776,6 +13016,10 @@
      *
      * Engine component: {@link GSplatComponent} (`gsplat`).
      *
+     * @elementSummary The `<pc-gsplat>` element renders the 3D Gaussian splats of a `gsplat` asset at
+     * its entity, with attributes for shadow casting and level of detail. Must be a child of a
+     * `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+     *
      * @category Components
      */
     class GSplatComponentElement extends ComponentElement {
@@ -13071,6 +13315,11 @@
      * The pointer events below are dispatched by the containing `<pc-app>` element when the pointer
      * intersects the bound node's geometry, exactly as for `<pc-entity>`.
      *
+     * @elementSummary The `<pc-node>` element binds to a node inside the hierarchy a `<pc-model>`
+     * instantiated and declares overrides against it: a transform, an enabled state, tags, components
+     * to add, or content to attach. Its `name` is a lookup, never a rename. Must be a descendant of
+     * `<pc-model>`.
+     *
      * @attribute {string} name - The name of the node to bind, resolved within the nearest ancestor
      * `pc-model` (or `pc-node`) once it has instantiated.
      * @attribute {number} index - Which match to bind when `name` matches more than one node,
@@ -13811,6 +14060,9 @@
      * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-scene/ | `<pc-scene>`} elements.
      * The SceneElement interface also inherits the properties and methods of the
      * {@link HTMLElement} interface.
+     *
+     * @elementSummary The `<pc-scene>` element holds the entity hierarchy the application renders,
+     * along with the scene-wide fog and gravity settings. Must be a direct child of `<pc-app>`.
      */
     class SceneElement extends AsyncElement {
         /**
@@ -14034,6 +14286,10 @@
      * The SkyElement interface provides properties and methods for manipulating
      * `<pc-sky>` elements. The SkyElement interface also inherits the properties and
      * methods of the {@link HTMLElement} interface.
+     *
+     * @elementSummary The `<pc-sky>` element renders a skybox from a texture asset, projected as an
+     * infinite background, a box or a dome, and optionally lights the scene from it. Must be a direct
+     * child of `<pc-scene>`.
      */
     class SkyElement extends AsyncElement {
         _asset = '';