@playcanvas/web-components 0.17.0 → 0.19.0

package/README.md

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

package/dist/app.d.cts

@@ -14,6 +14,10 @@ import type { EntityBaseElement } from './entity-base.cjs';
  * tracked live via a ResizeObserver — so the element can be embedded at any size, resized by
  * its container, or made fullscreen with ordinary CSS such as `width: 100vw; height: 100dvh`.
  *
+ * @elementSummary The `<pc-app>` element creates a PlayCanvas application and the canvas it renders
+ * into, and is the root of every scene. It holds the `<pc-asset>`, `<pc-material>`, `<pc-wasm>` and
+ * `<pc-scene>` elements, and the page's CSS sizes it, as it would a `<video>`.
+ *
  * @fires {ProgressEvent} progress - Fired while the application preloads its assets. `loaded` and
  * `total` are asset counts, not bytes, and an asset that fails to load still counts as loaded.
  * Fired at least once per boot, and the final event always has `loaded` equal to `total`. Does
@@ -59,10 +63,24 @@ declare class AppElement extends AsyncElement {
      */
     private _entityElements;
     private _picker;
-    private _hasPointerListeners;
     private _hoveredEntity;
     private _pickToken;
     private _pointerHandlers;
+    /**
+     * The pick of each pointer's primary-button press, keyed by pointerId and kept while a click
+     * may still conclude it. The promise is stored rather than its result, so a release can
+     * await a press pick that has not resolved yet. Entries are removed by the matching
+     * pointerup or pointercancel, and only ever stored while some element listens for click -
+     * which is also what keeps those two canvas listeners attached.
+     */
+    private _downPicks;
+    /** Whether any element in the tree listens for click. Maintained by _syncCanvasListeners. */
+    private _clickListened;
+    /**
+     * The previous click's target, time and count, for chaining successive clicks into the
+     * click count that `detail` carries. `null` until a click has fired.
+     */
+    private _lastClick;
     private _app;
     private _loadProgress;
     /**
@@ -183,8 +201,15 @@ declare class AppElement extends AsyncElement {
     private _onPointerMove;
     private _onPointerDown;
     private _onPointerUp;
-    private _onPointerListenerAdded;
-    private _onPointerListenerRemoved;
+    /**
+     * Attaches exactly the canvas listeners the tree's current element listeners need, and
+     * detaches the rest. Recomputed whenever a listener connects or disconnects anywhere under
+     * this element: several synthesized types can need the same canvas listener (enter, leave
+     * and move all ride the move pick; click rides the down/up pair), so one type's removal
+     * must not detach a listener another type still uses. Re-attaching an attached listener is
+     * a no-op by EventTarget semantics, so no attach state is kept.
+     */
+    private _syncCanvasListeners;
     /**
      * Warns that a graphics option was written too late to have any effect. These options are read
      * once, when the element connects and creates its graphics device, so a later write updates

package/dist/app.d.ts

@@ -14,6 +14,10 @@ import type { EntityBaseElement } from './entity-base.js';
  * tracked live via a ResizeObserver — so the element can be embedded at any size, resized by
  * its container, or made fullscreen with ordinary CSS such as `width: 100vw; height: 100dvh`.
  *
+ * @elementSummary The `<pc-app>` element creates a PlayCanvas application and the canvas it renders
+ * into, and is the root of every scene. It holds the `<pc-asset>`, `<pc-material>`, `<pc-wasm>` and
+ * `<pc-scene>` elements, and the page's CSS sizes it, as it would a `<video>`.
+ *
  * @fires {ProgressEvent} progress - Fired while the application preloads its assets. `loaded` and
  * `total` are asset counts, not bytes, and an asset that fails to load still counts as loaded.
  * Fired at least once per boot, and the final event always has `loaded` equal to `total`. Does
@@ -59,10 +63,24 @@ declare class AppElement extends AsyncElement {
      */
     private _entityElements;
     private _picker;
-    private _hasPointerListeners;
     private _hoveredEntity;
     private _pickToken;
     private _pointerHandlers;
+    /**
+     * The pick of each pointer's primary-button press, keyed by pointerId and kept while a click
+     * may still conclude it. The promise is stored rather than its result, so a release can
+     * await a press pick that has not resolved yet. Entries are removed by the matching
+     * pointerup or pointercancel, and only ever stored while some element listens for click -
+     * which is also what keeps those two canvas listeners attached.
+     */
+    private _downPicks;
+    /** Whether any element in the tree listens for click. Maintained by _syncCanvasListeners. */
+    private _clickListened;
+    /**
+     * The previous click's target, time and count, for chaining successive clicks into the
+     * click count that `detail` carries. `null` until a click has fired.
+     */
+    private _lastClick;
     private _app;
     private _loadProgress;
     /**
@@ -183,8 +201,15 @@ declare class AppElement extends AsyncElement {
     private _onPointerMove;
     private _onPointerDown;
     private _onPointerUp;
-    private _onPointerListenerAdded;
-    private _onPointerListenerRemoved;
+    /**
+     * Attaches exactly the canvas listeners the tree's current element listeners need, and
+     * detaches the rest. Recomputed whenever a listener connects or disconnects anywhere under
+     * this element: several synthesized types can need the same canvas listener (enter, leave
+     * and move all ride the move pick; click rides the down/up pair), so one type's removal
+     * must not detach a listener another type still uses. Re-attaching an attached listener is
+     * a no-op by EventTarget semantics, so no attach state is kept.
+     */
+    private _syncCanvasListeners;
     /**
      * Warns that a graphics option was written too late to have any effect. These options are read
      * once, when the element connects and creates its graphics device, so a later write updates

package/dist/asset.d.cts

@@ -1,8 +1,14 @@
 import { Asset } from 'playcanvas';
 import { AsyncElement } from './async-element.cjs';
-type AddressMode = 'repeat' | 'clamp' | 'mirror';
-type MinFilterMode = 'nearest' | 'linear' | 'nearest-mip-nearest' | 'linear-mip-nearest' | 'nearest-mip-linear' | 'linear-mip-linear';
-type MagFilterMode = 'nearest' | 'linear';
+/** The addressing modes for a texture asset. */
+export type AddressMode = 'repeat' | 'clamp' | 'mirror';
+/** The minification filter modes for a texture asset. */
+export type MinFilterMode = 'nearest' | 'linear' | 'nearest-mip-nearest' | 'linear-mip-nearest' | 'nearest-mip-linear' | 'linear-mip-linear';
+/**
+ * The magnification filter modes for a texture asset. Magnification has no mip variants - the
+ * engine (and the GPU) only accepts these two.
+ */
+export type MagFilterMode = 'nearest' | 'linear';
 /**
  * The AssetElement interface provides properties and methods for manipulating
  * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-asset/ | `<pc-asset>`} elements.
@@ -31,6 +37,10 @@ type MagFilterMode = 'nearest' | 'linear';
  * Apart from `lazy` and the texture options, these attributes are read once when the asset is
  * created, so changing them later has no effect.
  *
+ * @elementSummary The `<pc-asset>` element declares an asset for the application to load — a model,
+ * texture, font, sound, script or JSON file — under an `id` that other elements reference. Must be
+ * a direct child of `<pc-app>`.
+ *
  * @attribute {string} id - The identifier used to reference the asset from other elements.
  * @attribute {string} src - The URL of the asset to load.
  * @attribute {string} type - The asset type. Inferred from the `src` file extension when omitted.

package/dist/asset.d.ts

@@ -1,8 +1,14 @@
 import { Asset } from 'playcanvas';
 import { AsyncElement } from './async-element.js';
-type AddressMode = 'repeat' | 'clamp' | 'mirror';
-type MinFilterMode = 'nearest' | 'linear' | 'nearest-mip-nearest' | 'linear-mip-nearest' | 'nearest-mip-linear' | 'linear-mip-linear';
-type MagFilterMode = 'nearest' | 'linear';
+/** The addressing modes for a texture asset. */
+export type AddressMode = 'repeat' | 'clamp' | 'mirror';
+/** The minification filter modes for a texture asset. */
+export type MinFilterMode = 'nearest' | 'linear' | 'nearest-mip-nearest' | 'linear-mip-nearest' | 'nearest-mip-linear' | 'linear-mip-linear';
+/**
+ * The magnification filter modes for a texture asset. Magnification has no mip variants - the
+ * engine (and the GPU) only accepts these two.
+ */
+export type MagFilterMode = 'nearest' | 'linear';
 /**
  * The AssetElement interface provides properties and methods for manipulating
  * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-asset/ | `<pc-asset>`} elements.
@@ -31,6 +37,10 @@ type MagFilterMode = 'nearest' | 'linear';
  * Apart from `lazy` and the texture options, these attributes are read once when the asset is
  * created, so changing them later has no effect.
  *
+ * @elementSummary The `<pc-asset>` element declares an asset for the application to load — a model,
+ * texture, font, sound, script or JSON file — under an `id` that other elements reference. Must be
+ * a direct child of `<pc-app>`.
+ *
  * @attribute {string} id - The identifier used to reference the asset from other elements.
  * @attribute {string} src - The URL of the asset to load.
  * @attribute {string} type - The asset type. Inferred from the `src` file extension when omitted.

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

@@ -13,7 +13,9 @@ import { AnimComponentElement } from './anim-component.cjs';
  * named; in a multi-track source the track named `name` is chosen, falling back to the first
  * with a warning. The element becomes ready once its resolved track is assigned.
  *
- * @category Components
+ * @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>`.
  */
 declare class AnimClipElement extends AsyncElement {
     /**

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

@@ -13,7 +13,9 @@ import { AnimComponentElement } from './anim-component.js';
  * named; in a multi-track source the track named `name` is chosen, falling back to the first
  * with a warning. The element becomes ready once its resolved track is assigned.
  *
- * @category Components
+ * @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>`.
  */
 declare class AnimClipElement extends AsyncElement {
     /**

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

@@ -27,6 +27,11 @@ type ContainerWithAnimations = ContainerResource & {
  *
  * Engine component: {@link AnimComponent} (`anim`).
  *
+ * @elementSummary The `<pc-anim>` element plays animation clips over its entity's hierarchy, taken
+ * from `<pc-anim-clip>` children or from the enclosing `<pc-model>`'s own animations. The first
+ * clip plays automatically, and the `clip` attribute switches between them. Must be a child of a
+ * `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+ *
  * @category Components
  */
 declare class AnimComponentElement extends ComponentElement {

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

@@ -27,6 +27,11 @@ type ContainerWithAnimations = ContainerResource & {
  *
  * Engine component: {@link AnimComponent} (`anim`).
  *
+ * @elementSummary The `<pc-anim>` element plays animation clips over its entity's hierarchy, taken
+ * from `<pc-anim-clip>` children or from the enclosing `<pc-model>`'s own animations. The first
+ * clip plays automatically, and the `clip` attribute switches between them. Must be a child of a
+ * `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+ *
  * @category Components
  */
 declare class AnimComponentElement extends ComponentElement {

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

@@ -8,6 +8,10 @@ import { ComponentElement } from './component.cjs';
  *
  * Engine component: {@link AudioListenerComponent} (`audiolistener`).
  *
+ * @elementSummary The `<pc-audio-listener>` element makes its entity the point from which
+ * positional sounds are heard, typically the entity holding the `<pc-camera>`. Must be a child of a
+ * `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+ *
  * @category Components
  */
 declare class AudioListenerComponentElement extends ComponentElement {

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

@@ -8,6 +8,10 @@ import { ComponentElement } from './component.js';
  *
  * Engine component: {@link AudioListenerComponent} (`audiolistener`).
  *
+ * @elementSummary The `<pc-audio-listener>` element makes its entity the point from which
+ * positional sounds are heard, typically the entity holding the `<pc-camera>`. Must be a child of a
+ * `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+ *
  * @category Components
  */
 declare class AudioListenerComponentElement extends ComponentElement {

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

@@ -9,6 +9,11 @@ import { ComponentElement } from './component.cjs';
  *
  * Engine component: {@link ButtonComponent} (`button`).
  *
+ * @elementSummary The `<pc-button>` element makes its entity respond to pointer input, tinting or
+ * swapping its image as the pointer hovers, presses and releases it. The entity also needs a
+ * `<pc-element>` with `use-input` set. Must be a child of a `<pc-entity>`, `<pc-model>` or
+ * `<pc-node>`.
+ *
  * @category Components
  */
 declare class ButtonComponentElement extends ComponentElement {

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

@@ -9,6 +9,11 @@ import { ComponentElement } from './component.js';
  *
  * Engine component: {@link ButtonComponent} (`button`).
  *
+ * @elementSummary The `<pc-button>` element makes its entity respond to pointer input, tinting or
+ * swapping its image as the pointer hovers, presses and releases it. The entity also needs a
+ * `<pc-element>` with `use-input` set. Must be a child of a `<pc-entity>`, `<pc-model>` or
+ * `<pc-node>`.
+ *
  * @category Components
  */
 declare class ButtonComponentElement extends ComponentElement {

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

@@ -9,11 +9,16 @@ import { ComponentElement } from './component.cjs';
  *
  * 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
  */
 declare class CameraComponentElement extends ComponentElement {
     private _clearColor;
     private _clearColorBuffer;
+    private _clearDepth;
     private _clearDepthBuffer;
     private _clearStencilBuffer;
     private _cullFaces;
@@ -35,6 +40,7 @@ declare class CameraComponentElement extends ComponentElement {
     protected getInitialComponentData(): {
         clearColor: Color;
         clearColorBuffer: boolean;
+        clearDepth: number;
         clearDepthBuffer: boolean;
         clearStencilBuffer: boolean;
         cullFaces: boolean;
@@ -52,7 +58,25 @@ declare class CameraComponentElement extends ComponentElement {
         scissorRect: Vec4;
         toneMapping: number;
     };
-    get xrAvailable(): boolean | null;
+    /**
+     * 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(): boolean;
+    /**
+     * 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(): boolean;
+    /**
+     * Whether one XR session type is available on this device.
+     *
+     * @param type - The XR session type to test.
+     * @returns Whether that type is available.
+     */
+    private _available;
     /**
      * Starts the camera in XR mode.
      * @param type - The type of XR mode to start.
@@ -88,6 +112,16 @@ declare class CameraComponentElement extends ComponentElement {
      * @returns The clear color buffer.
      */
     get clearColorBuffer(): boolean;
+    /**
+     * Sets the depth value the depth buffer is cleared to. Defaults to 1.
+     * @param value - The clear depth value.
+     */
+    set clearDepth(value: number);
+    /**
+     * Gets the depth value the depth buffer is cleared to.
+     * @returns The clear depth value.
+     */
+    get clearDepth(): number;
     /**
      * Sets the clear depth buffer of the camera.
      * @param value - The clear depth buffer.

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

@@ -9,11 +9,16 @@ import { ComponentElement } from './component.js';
  *
  * 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
  */
 declare class CameraComponentElement extends ComponentElement {
     private _clearColor;
     private _clearColorBuffer;
+    private _clearDepth;
     private _clearDepthBuffer;
     private _clearStencilBuffer;
     private _cullFaces;
@@ -35,6 +40,7 @@ declare class CameraComponentElement extends ComponentElement {
     protected getInitialComponentData(): {
         clearColor: Color;
         clearColorBuffer: boolean;
+        clearDepth: number;
         clearDepthBuffer: boolean;
         clearStencilBuffer: boolean;
         cullFaces: boolean;
@@ -52,7 +58,25 @@ declare class CameraComponentElement extends ComponentElement {
         scissorRect: Vec4;
         toneMapping: number;
     };
-    get xrAvailable(): boolean | null;
+    /**
+     * 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(): boolean;
+    /**
+     * 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(): boolean;
+    /**
+     * Whether one XR session type is available on this device.
+     *
+     * @param type - The XR session type to test.
+     * @returns Whether that type is available.
+     */
+    private _available;
     /**
      * Starts the camera in XR mode.
      * @param type - The type of XR mode to start.
@@ -88,6 +112,16 @@ declare class CameraComponentElement extends ComponentElement {
      * @returns The clear color buffer.
      */
     get clearColorBuffer(): boolean;
+    /**
+     * Sets the depth value the depth buffer is cleared to. Defaults to 1.
+     * @param value - The clear depth value.
+     */
+    set clearDepth(value: number);
+    /**
+     * Gets the depth value the depth buffer is cleared to.
+     * @returns The clear depth value.
+     */
+    get clearDepth(): number;
     /**
      * Sets the clear depth buffer of the camera.
      * @param value - The clear depth buffer.

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

@@ -15,6 +15,10 @@ import { ComponentElement } from './component.cjs';
  *
  * 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
  */
 declare class CollisionComponentElement extends ComponentElement {

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

@@ -15,6 +15,10 @@ import { ComponentElement } from './component.js';
  *
  * 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
  */
 declare class CollisionComponentElement extends ComponentElement {

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

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

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

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

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

@@ -8,6 +8,10 @@ import { ComponentElement } from './component.cjs';
  *
  * 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
  */
 declare class GSplatComponentElement extends ComponentElement {

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

@@ -8,6 +8,10 @@ import { ComponentElement } from './component.js';
  *
  * 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
  */
 declare class GSplatComponentElement extends ComponentElement {

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

@@ -1,8 +1,13 @@
 import type { JointComponent } from 'playcanvas';
 import { Vec2, Vec3 } from 'playcanvas';
 import { ComponentElement } from './component.cjs';
-type JointType = 'fixed' | 'ball' | 'hinge' | 'slider' | '6dof';
-type MotionMode = 'locked' | 'limited' | 'free';
+/** The constraint types supported by the `<pc-joint>` element. */
+export type JointType = 'fixed' | 'ball' | 'hinge' | 'slider' | '6dof';
+/**
+ * The motion modes for a single joint axis: fully constrained (`locked`), constrained within
+ * limits (`limited`) or unconstrained (`free`).
+ */
+export type MotionMode = 'locked' | 'limited' | 'free';
 /**
  * The JointComponentElement interface provides properties and methods for manipulating
  * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-joint/ | `<pc-joint>`} elements.
@@ -16,6 +21,11 @@ type MotionMode = 'locked' | 'limited' | 'free';
  * 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.

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

@@ -1,8 +1,13 @@
 import type { JointComponent } from 'playcanvas';
 import { Vec2, Vec3 } from 'playcanvas';
 import { ComponentElement } from './component.js';
-type JointType = 'fixed' | 'ball' | 'hinge' | 'slider' | '6dof';
-type MotionMode = 'locked' | 'limited' | 'free';
+/** The constraint types supported by the `<pc-joint>` element. */
+export type JointType = 'fixed' | 'ball' | 'hinge' | 'slider' | '6dof';
+/**
+ * The motion modes for a single joint axis: fully constrained (`locked`), constrained within
+ * limits (`limited`) or unconstrained (`free`).
+ */
+export type MotionMode = 'locked' | 'limited' | 'free';
 /**
  * The JointComponentElement interface provides properties and methods for manipulating
  * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-joint/ | `<pc-joint>`} elements.
@@ -16,6 +21,11 @@ type MotionMode = 'locked' | 'limited' | 'free';
  * 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.

package/dist/components/layout-child-component.d.cts

@@ -8,6 +8,10 @@ import { ComponentElement } from './component.cjs';
  *
  * 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
  */
 declare class LayoutChildComponentElement extends ComponentElement {

package/dist/components/layout-child-component.d.ts

@@ -8,6 +8,10 @@ import { ComponentElement } from './component.js';
  *
  * 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
  */
 declare class LayoutChildComponentElement extends ComponentElement {

package/dist/components/layout-group-component.d.cts

@@ -9,6 +9,10 @@ import { ComponentElement } from './component.cjs';
  *
  * 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
  */
 declare class LayoutGroupComponentElement extends ComponentElement {

package/dist/components/layout-group-component.d.ts

@@ -9,6 +9,10 @@ import { ComponentElement } from './component.js';
  *
  * 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
  */
 declare class LayoutGroupComponentElement extends ComponentElement {