@playcanvas/web-components 0.17.0 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcanvas/web-components",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "author": "PlayCanvas <support@playcanvas.com>",
   "homepage": "https://playcanvas.com",
   "description": "Web Components for the PlayCanvas Engine",
@@ -99,12 +99,12 @@
     "eslint": "9.39.5",
     "globals": "17.11.0",
     "jsdom": "30.0.1",
-    "mediabunny": "1.55.2",
+    "mediabunny": "1.55.3",
     "opentype.js": "2.0.0",
     "playcanvas": "2.21.4",
     "prettier": "3.9.6",
     "publint": "0.3.24",
-    "rollup": "4.62.5",
+    "rollup": "4.63.0",
     "serve": "14.2.6",
     "tslib": "2.8.1",
     "typedoc": "0.28.20",

package/src/app.ts

@@ -66,6 +66,7 @@ import {
 
 import type { AssetElement } from './asset';
 import { AsyncElement } from './async-element';
+import { SYNTHESIZED_EVENTS } from './entity-base';
 import type { EntityBaseElement } from './entity-base';
 import type { EntityOwnerElement } from './entity-owner';
 import { LoadingBar } from './loading-bar';
@@ -73,9 +74,6 @@ import type { MaterialElement } from './material';
 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
@@ -83,6 +81,48 @@ const pointerEventTypes = ['pointermove', 'pointerdown', 'pointerup', 'pointeren
  */
 const hoverEventTypes = ['pointerenter', 'pointerleave', 'pointermove'] as const;
 
+/**
+ * The canvas listeners each synthesized event type is driven by. Enter and leave are derived
+ * from move picks. A click is concluded from the down/up pair, with pointercancel discarding a
+ * press the browser takes back (for example a touch that becomes a scroll).
+ */
+const canvasEventsFor: Record<(typeof SYNTHESIZED_EVENTS)[number], readonly string[]> = {
+    pointermove: ['pointermove'],
+    pointerenter: ['pointermove'],
+    pointerleave: ['pointermove'],
+    pointerdown: ['pointerdown'],
+    pointerup: ['pointerup'],
+    click: ['pointerdown', 'pointerup', 'pointercancel']
+};
+
+/**
+ * How long after a click a further click on the same target still raises the click count that
+ * `detail` carries, approximating the platform's double-click time.
+ */
+const CLICK_CHAIN_MS = 500;
+
+/**
+ * Finds the nearest common inclusive ancestor of two picked nodes - the node a click belongs to
+ * when the press and the release picked different geometry, exactly as the DOM assigns a click
+ * whose down and up have different targets.
+ *
+ * @param a - The node the press picked, or `null`.
+ * @param b - The node the release picked, or `null`.
+ * @returns The nearest common inclusive ancestor, or `null` when there is none.
+ */
+const commonAncestor = (a: GraphNode | null, b: GraphNode | null): GraphNode | null => {
+    const ancestors = new Set<GraphNode>();
+    for (let node = a; node !== null; node = node.parent) {
+        ancestors.add(node);
+    }
+    for (let node = b; node !== null; node = node.parent) {
+        if (ancestors.has(node)) {
+            return node;
+        }
+    }
+    return null;
+};
+
 /**
  * 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
@@ -112,6 +152,10 @@ const ensureBaseStyles = () => {
  * tracked live via a ResizeObserver — so the element can be embedded at any size, resized by
  * its container, or made fullscreen with ordinary CSS such as `width: 100vw; height: 100dvh`.
  *
+ * @elementSummary The `<pc-app>` element creates a PlayCanvas application and the canvas it renders
+ * into, and is the root of every scene. It holds the `<pc-asset>`, `<pc-material>`, `<pc-wasm>` and
+ * `<pc-scene>` elements, and the page's CSS sizes it, as it would a `<video>`.
+ *
  * @fires {ProgressEvent} progress - Fired while the application preloads its assets. `loaded` and
  * `total` are asset counts, not bytes, and an asset that fails to load still counts as loaded.
  * Fired at least once per boot, and the final event always has `loaded` equal to `total`. Does
@@ -178,14 +222,6 @@ class AppElement extends AsyncElement {
 
     private _picker: Picker | null = null;
 
-    private _hasPointerListeners: Record<string, boolean> = {
-        pointerenter: false,
-        pointerleave: false,
-        pointerdown: false,
-        pointerup: false,
-        pointermove: false
-    };
-
     private _hoveredEntity: EntityBaseElement | null = null;
 
     // Identifies the newest in-flight hover pick, so out-of-order results can be discarded
@@ -194,9 +230,28 @@ class AppElement extends AsyncElement {
     private _pointerHandlers: Record<string, EventListener | null> = {
         pointermove: null,
         pointerdown: null,
-        pointerup: null
+        pointerup: null,
+        pointercancel: null
     };
 
+    /**
+     * 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 = new Map<number, Promise<GraphNode | null>>();
+
+    /** Whether any element in the tree listens for click. Maintained by _syncCanvasListeners. */
+    private _clickListened = false;
+
+    /**
+     * 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: { element: EntityBaseElement; time: number; count: number } | null = null;
+
     private _app: AppBase | null = null;
 
     private _loadProgress = 0;
@@ -237,12 +292,12 @@ class AppElement extends AsyncElement {
     constructor() {
         super();
 
-        // Track pointer listeners being added to and removed from descendant entities.
-        // Registered once here rather than on every boot - the handlers no-op while there is no
-        // canvas, and a re-booted element must not stack a second set.
-        pointerEventTypes.forEach((type) => {
-            this.addEventListener(`${type}:connect`, () => this._onPointerListenerAdded(type));
-            this.addEventListener(`${type}:disconnect`, () => this._onPointerListenerRemoved(type));
+        // Track listeners for the synthesized events being added to and removed from descendant
+        // entities. Registered once here rather than on every boot - the sync no-ops while there
+        // is no canvas, and a re-booted element must not stack a second set.
+        SYNTHESIZED_EVENTS.forEach((type) => {
+            this.addEventListener(`${type}:connect`, () => this._syncCanvasListeners());
+            this.addEventListener(`${type}:disconnect`, () => this._syncCanvasListeners());
         });
     }
 
@@ -605,18 +660,14 @@ class AppElement extends AsyncElement {
         this._pointerHandlers.pointermove = listener(this._onPointerMove);
         this._pointerHandlers.pointerdown = listener(this._onPointerDown);
         this._pointerHandlers.pointerup = listener(this._onPointerUp);
+        this._pointerHandlers.pointercancel = (event: Event) => {
+            this._downPicks.delete((event as PointerEvent).pointerId);
+        };
 
-        // Attach canvas handlers for listeners registered before this boot (e.g. handlers
-        // created from onpointer* attributes when their elements were first upgraded, or
+        // Attach canvas listeners for element listeners registered before this boot (e.g.
+        // handlers created from inline 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-model, pc-node')
-            ).some((entity) => entity._hasListeners(type));
-            if (anyListeners) {
-                this._onPointerListenerAdded(type);
-            }
-        });
+        this._syncCanvasListeners();
     }
 
     private _pickerDestroy() {
@@ -633,15 +684,12 @@ class AppElement extends AsyncElement {
         this._pointerHandlers = {
             pointermove: null,
             pointerdown: null,
-            pointerup: null
-        };
-        this._hasPointerListeners = {
-            pointerenter: false,
-            pointerleave: false,
-            pointerdown: false,
-            pointerup: false,
-            pointermove: false
+            pointerup: null,
+            pointercancel: null
         };
+        this._downPicks.clear();
+        this._clickListened = false;
+        this._lastClick = null;
     }
 
     /**
@@ -867,7 +915,17 @@ class AppElement extends AsyncElement {
     private async _onPointerDown(event: PointerEvent) {
         if (!this._picker || !this.app) return;
 
-        const node = await this._pickNode(event);
+        const pick = this._pickNode(event);
+
+        // A click concludes on the matching pointerup, which needs to know what the press
+        // picked. Primary button only - the only button a click can conclude from - and only
+        // while click is listened for, since it is the click mapping that keeps the pointerup
+        // and pointercancel listeners attached to clean the entry up again.
+        if (this._clickListened && event.button === 0) {
+            this._downPicks.set(event.pointerId, pick);
+        }
+
+        const node = await pick;
         if (!this._picker) return; // the element disconnected while the pick was in flight
 
         const entityElement = this._elementWithListener(node, 'pointerdown');
@@ -879,6 +937,11 @@ class AppElement extends AsyncElement {
     private async _onPointerUp(event: PointerEvent) {
         if (!this._picker || !this.app) return;
 
+        // The press pick this release may conclude as a click. Claimed synchronously, so the
+        // entry is gone before any other event for this pointer can be handled.
+        const downPick = this._downPicks.get(event.pointerId);
+        this._downPicks.delete(event.pointerId);
+
         const node = await this._pickNode(event);
         if (!this._picker) return; // the element disconnected while the pick was in flight
 
@@ -886,47 +949,63 @@ class AppElement extends AsyncElement {
         if (entityElement) {
             entityElement.dispatchEvent(new PointerEvent('pointerup', event));
         }
-    }
 
-    private _onPointerListenerAdded(type: string) {
-        if (!this._hasPointerListeners[type] && this._canvas) {
-            this._hasPointerListeners[type] = true;
-
-            // For enter/leave events, we need the move handler
-            const handler =
-                type === 'pointerenter' || type === 'pointerleave'
-                    ? this._pointerHandlers.pointermove
-                    : this._pointerHandlers[type];
-
-            if (handler) {
-                this._canvas.addEventListener(
-                    type === 'pointerenter' || type === 'pointerleave' ? 'pointermove' : type,
-                    handler
-                );
-            }
+        // A click fires where the DOM fires it: at the nearest common inclusive ancestor of
+        // what the press and the release picked, for the primary button only. The press pick
+        // may still be in flight - a quick tap resolves in pick order, not event order.
+        if (!downPick || event.button !== 0) return;
+        const downNode = await downPick;
+        if (!this._picker) return;
+
+        const clickElement = this._elementWithListener(commonAncestor(downNode, node), 'click');
+        if (clickElement) {
+            const click = new PointerEvent('click', event);
+
+            // The init above copied pointerup's `detail`, which the Pointer Events spec fixes
+            // at 0 - but click is exempt: its detail is the click count, chained here as the
+            // platform chains it (same target, within the double-click window). Overridden
+            // with defineProperty because an event instance used as an init dict cannot have
+            // single fields replaced.
+            const time = performance.now();
+            const last = this._lastClick;
+            const count =
+                last && last.element === clickElement && time - last.time <= CLICK_CHAIN_MS ? last.count + 1 : 1;
+            this._lastClick = { element: clickElement, time, count };
+            Object.defineProperty(click, 'detail', { value: count });
+
+            clickElement.dispatchEvent(click);
         }
     }
 
-    private _onPointerListenerRemoved(type: string) {
-        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;
-
-            const handler =
-                type === 'pointerenter' || type === 'pointerleave'
-                    ? this._pointerHandlers.pointermove
-                    : this._pointerHandlers[type];
+    /**
+     * 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() {
+        const canvas = this._canvas;
+        if (!canvas) return; // not booted yet: _pickerCreate syncs once the handlers exist
 
-            if (handler) {
-                this._canvas.removeEventListener(
-                    type === 'pointerenter' || type === 'pointerleave' ? 'pointermove' : type,
-                    handler
-                );
+        const elements = Array.from(this.querySelectorAll<EntityBaseElement>('pc-entity, pc-model, pc-node'));
+        const needed = new Set<string>();
+        for (const type of SYNTHESIZED_EVENTS) {
+            if (elements.some((element) => element._hasListeners(type))) {
+                canvasEventsFor[type].forEach((canvasType) => needed.add(canvasType));
             }
         }
+        this._clickListened = elements.some((element) => element._hasListeners('click'));
+
+        Object.entries(this._pointerHandlers).forEach(([canvasType, handler]) => {
+            if (!handler) return;
+            if (needed.has(canvasType)) {
+                canvas.addEventListener(canvasType, handler);
+            } else {
+                canvas.removeEventListener(canvasType, handler);
+            }
+        });
     }
 
     /**

package/src/asset.ts

@@ -26,7 +26,8 @@ const renderModes = new Map<'simple' | 'sliced' | 'tiled', number>([
     ['tiled', SPRITE_RENDERMODE_TILED]
 ]);
 
-type AddressMode = 'repeat' | 'clamp' | 'mirror';
+/** The addressing modes for a texture asset. */
+export type AddressMode = 'repeat' | 'clamp' | 'mirror';
 
 const addressModes = new Map<AddressMode, number>([
     ['repeat', ADDRESS_REPEAT],
@@ -34,7 +35,8 @@ const addressModes = new Map<AddressMode, number>([
     ['mirror', ADDRESS_MIRRORED_REPEAT]
 ]);
 
-type MinFilterMode =
+/** The minification filter modes for a texture asset. */
+export type MinFilterMode =
     'nearest' | 'linear' | 'nearest-mip-nearest' | 'linear-mip-nearest' | 'nearest-mip-linear' | 'linear-mip-linear';
 
 const minFilterModes = new Map<MinFilterMode, number>([
@@ -46,8 +48,11 @@ const minFilterModes = new Map<MinFilterMode, number>([
     ['linear-mip-linear', FILTER_LINEAR_MIPMAP_LINEAR]
 ]);
 
-// Magnification has no mip variants - the engine (and the GPU) only accepts these two.
-type MagFilterMode = 'nearest' | 'linear';
+/**
+ * The magnification filter modes for a texture asset. Magnification has no mip variants - the
+ * engine (and the GPU) only accepts these two.
+ */
+export type MagFilterMode = 'nearest' | 'linear';
 
 const magFilterModes = new Map<MagFilterMode, number>([
     ['nearest', FILTER_NEAREST],
@@ -168,6 +173,10 @@ const processBufferView = (
  * Apart from `lazy` and the texture options, these attributes are read once when the asset is
  * created, so changing them later has no effect.
  *
+ * @elementSummary The `<pc-asset>` element declares an asset for the application to load — a model,
+ * texture, font, sound, script or JSON file — under an `id` that other elements reference. Must be
+ * a direct child of `<pc-app>`.
+ *
  * @attribute {string} id - The identifier used to reference the asset from other elements.
  * @attribute {string} src - The URL of the asset to load.
  * @attribute {string} type - The asset type. Inferred from the `src` file extension when omitted.

package/src/components/anim-clip.ts

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

package/src/components/anim-component.ts

@@ -48,6 +48,11 @@ type PlaybackState = {
  *
  * 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 {

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

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

package/src/components/button-component.ts

@@ -19,6 +19,11 @@ const transitionModes = new Map<'tint' | 'sprite', number>([
  *
  * 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 {

package/src/components/camera-component.ts

@@ -13,6 +13,7 @@ import {
     TONEMAP_ACES,
     TONEMAP_HEJL,
     TONEMAP_NONE,
+    XRTYPE_AR,
     XRTYPE_VR
 } from 'playcanvas';
 
@@ -43,6 +44,10 @@ const tonemaps = new Map<'none' | 'linear' | 'filmic' | 'hejl' | 'aces' | 'aces2
  *
  * 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 {
@@ -50,9 +55,11 @@ class CameraComponentElement extends ComponentElement {
 
     private _clearColorBuffer = true;
 
+    private _clearDepth = 1;
+
     private _clearDepthBuffer = true;
 
-    private _clearStencilBuffer = false;
+    private _clearStencilBuffer = true;
 
     private _cullFaces = true;
 
@@ -91,6 +98,7 @@ class CameraComponentElement extends ComponentElement {
         return {
             clearColor: this._clearColor,
             clearColorBuffer: this._clearColorBuffer,
+            clearDepth: this._clearDepth,
             clearDepthBuffer: this._clearDepthBuffer,
             clearStencilBuffer: this._clearStencilBuffer,
             cullFaces: this._cullFaces,
@@ -110,9 +118,33 @@ class CameraComponentElement extends ComponentElement {
         };
     }
 
-    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(): boolean {
+        return this._available(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(): boolean {
+        return this._available(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.
+     */
+    private _available(type: string): boolean {
         const xrManager = this.component?.system.app.xr;
-        return xrManager && xrManager.supported && xrManager.isAvailable(XRTYPE_VR);
+        return Boolean(xrManager?.supported && xrManager.isAvailable(type));
     }
 
     /**
@@ -124,10 +156,12 @@ class CameraComponentElement extends ComponentElement {
         type: 'immersive-ar' | 'immersive-vr',
         space: 'bounded-floor' | 'local' | 'local-floor' | 'unbounded' | 'viewer'
     ) {
-        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: any) => {
-                    if (err) console.error(`WebXR Immersive VR failed to start: ${err.message}`);
+                    if (err) console.error(`WebXR ${type} failed to start: ${err.message}`);
                 }
             });
         }
@@ -188,6 +222,25 @@ class CameraComponentElement extends ComponentElement {
         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: number) {
+        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(): number {
+        return this._clearDepth;
+    }
+
     /**
      * Sets the clear depth buffer of the camera.
      * @param value - The clear depth buffer.
@@ -498,6 +551,7 @@ class CameraComponentElement extends ComponentElement {
             ...super.observedAttributes,
             'clear-color',
             'clear-color-buffer',
+            'clear-depth',
             'clear-depth-buffer',
             'clear-stencil-buffer',
             'cull-faces',
@@ -527,11 +581,14 @@ class CameraComponentElement extends ComponentElement {
             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);

package/src/components/collision-component.ts

@@ -19,6 +19,10 @@ import { ComponentElement } from './component';
  *
  * 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 {

package/src/components/element-component.ts

@@ -19,6 +19,10 @@ import { ComponentElement } from './component';
  *
  * 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 {

package/src/components/gsplat-component.ts

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

package/src/components/joint-component.ts

@@ -5,9 +5,14 @@ import { getEntity, parseBool, parseEnum, parseNumber, parseVec2, parseVec3 } fr
 
 import { ComponentElement } from './component';
 
-type JointType = 'fixed' | 'ball' | 'hinge' | 'slider' | '6dof';
+/** The constraint types supported by the `<pc-joint>` element. */
+export type JointType = 'fixed' | 'ball' | 'hinge' | 'slider' | '6dof';
 
-type MotionMode = 'locked' | 'limited' | 'free';
+/**
+ * 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
@@ -22,6 +27,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/src/components/layout-child-component.ts

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

package/src/components/layout-group-component.ts

@@ -34,6 +34,10 @@ const fittings = new Map<'none' | 'stretch' | 'shrink' | 'both', number>([
  *
  * 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 {