@playcanvas/web-components 0.17.0 → 0.19.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.
@@ -177,6 +181,136 @@
     }
     customElements.define('pc-wasm', WasmElement);
 
+    /**
+     * The event types the containing `<pc-app>` synthesizes on entity-fronting elements via picking:
+     * the `pointer*` events, plus `click` — which concludes a primary-button press and release, and
+     * is delivered as a `PointerEvent` exactly as modern browsers deliver native clicks.
+     * @internal
+     */
+    const SYNTHESIZED_EVENTS = [
+        'pointerenter',
+        'pointerleave',
+        'pointerdown',
+        'pointerup',
+        'pointermove',
+        'click'
+    ];
+    const SYNTHESIZED_EVENT_SET = new Set(SYNTHESIZED_EVENTS);
+    /**
+     * The attribute names of the inline event handlers (`onpointerdown`, `onclick`, ...), shared by
+     * every element that fronts an engine entity. Spread into `observedAttributes` by subclasses.
+     * @internal
+     */
+    const EVENT_ATTRIBUTES = SYNTHESIZED_EVENTS.map((type) => `on${type}`);
+    /**
+     * The base class for elements that front an engine {@link Entity}: `<pc-entity>` and
+     * `<pc-model>`, which create one, and `<pc-node>`, which binds to one inside a model's
+     * instantiated hierarchy. It carries what all of them need — the `entity` contract, registration
+     * with the owning application (which joins picked scene nodes back to elements by identity,
+     * never by name), and the pointer listener bookkeeping that lets the application lazily attach
+     * its canvas handlers.
+     */
+    class EntityBaseElement extends AsyncElement {
+        _entity = null;
+        /**
+         * The application element this entity is registered with, cached at registration time so the
+         * entity can be unregistered even once this element has left the DOM.
+         */
+        _appElement = null;
+        /**
+         * The event listeners registered on the element, by type.
+         */
+        _listeners = {};
+        /**
+         * The event types for which an inline handler attribute (`onpointerdown`, `onclick`, ...)
+         * is currently present.
+         */
+        _inlineHandlerTypes = new Set();
+        /**
+         * The PlayCanvas entity instance. `null` until the element is ready, and again once the
+         * entity is gone — await {@link whenReady} or the element's `ready()` promise before
+         * accessing it.
+         * @returns The entity instance, or `null`.
+         */
+        get entity() {
+            return this._entity;
+        }
+        /**
+         * Registers `entity` as this element's backing entity with the owning application, which
+         * joins engine nodes back to elements by identity (never by name).
+         *
+         * @param entity - The entity to register.
+         */
+        _registerEntity(entity) {
+            this._appElement = this.closestApp;
+            this._appElement?._registerEntityElement(entity, this);
+        }
+        /**
+         * Removes the registration for `entity`.
+         *
+         * @param entity - The entity to unregister.
+         */
+        _unregisterEntity(entity) {
+            this._appElement?._unregisterEntityElement(entity);
+            this._appElement = null;
+        }
+        /**
+         * Tracks whether an inline handler 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 EventTarget.addEventListener}, the connect/disconnect
+         * bookkeeping that lets the application lazily attach its canvas pointer handlers must be
+         * kept in sync here.
+         *
+         * @param name - The attribute name (e.g. 'onpointerdown').
+         * @param value - The attribute value, or `null` when the attribute has been removed.
+         */
+        _updateInlineHandler(name, value) {
+            const type = name.substring(2);
+            const had = this._inlineHandlerTypes.has(type);
+            const has = value !== null;
+            if (has && !had) {
+                this._inlineHandlerTypes.add(type);
+                this.dispatchEvent(new CustomEvent(`${type}:connect`, { bubbles: true }));
+            }
+            else if (!has && had) {
+                this._inlineHandlerTypes.delete(type);
+                this.dispatchEvent(new CustomEvent(`${type}:disconnect`, { bubbles: true }));
+            }
+        }
+        addEventListener(type, listener, options) {
+            if (!this._listeners[type]) {
+                this._listeners[type] = [];
+            }
+            this._listeners[type].push(listener);
+            super.addEventListener(type, listener, options);
+            if (SYNTHESIZED_EVENT_SET.has(type)) {
+                this.dispatchEvent(new CustomEvent(`${type}:connect`, { bubbles: true }));
+            }
+        }
+        removeEventListener(type, listener, options) {
+            if (this._listeners[type]) {
+                this._listeners[type] = this._listeners[type].filter((l) => l !== listener);
+            }
+            super.removeEventListener(type, listener, options);
+            if (SYNTHESIZED_EVENT_SET.has(type)) {
+                this.dispatchEvent(new CustomEvent(`${type}:disconnect`, { bubbles: true }));
+            }
+        }
+        /**
+         * Whether the element has a listener for an event type, registered either with
+         * {@link EventTarget.addEventListener} or with the matching inline handler attribute. Read by the
+         * containing `<pc-app>` element to gate event synthesis.
+         *
+         * @param type - The event type.
+         * @returns Whether a listener is registered.
+         * @internal
+         */
+        _hasListeners(type) {
+            return Boolean(this._listeners[type]?.length) || this._inlineHandlerTypes.has(type);
+        }
+    }
+
     /** Covers the 0.2s opacity transition; jsdom never fires transitionend, so removal is timed. */
     const REMOVAL_DELAY_MS = 250;
     /**
@@ -730,14 +864,51 @@
         return element?.entity ?? null;
     };
 
-    /** The pointer event types the application synthesizes on `<pc-entity>` elements via picking. */
-    const pointerEventTypes = ['pointermove', 'pointerdown', 'pointerup', 'pointerenter', 'pointerleave'];
     /**
      * The event types whose listeners make an element a hover target. Hover resolution walks past
      * elements listening for none of them, so a silent element never swallows an ancestor's
      * enter/leave pair.
      */
     const hoverEventTypes = ['pointerenter', 'pointerleave', 'pointermove'];
+    /**
+     * 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 = {
+        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, b) => {
+        const ancestors = new Set();
+        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
@@ -766,6 +937,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
@@ -818,21 +993,30 @@
          */
         _entityElements = new Map();
         _picker = null;
-        _hasPointerListeners = {
-            pointerenter: false,
-            pointerleave: false,
-            pointerdown: false,
-            pointerup: false,
-            pointermove: false
-        };
         _hoveredEntity = null;
         // Identifies the newest in-flight hover pick, so out-of-order results can be discarded
         _pickToken = 0;
         _pointerHandlers = {
             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.
+         */
+        _downPicks = new Map();
+        /** Whether any element in the tree listens for click. Maintained by _syncCanvasListeners. */
+        _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.
+         */
+        _lastClick = null;
         _app = null;
         _loadProgress = 0;
         /**
@@ -867,12 +1051,12 @@
          */
         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());
             });
         }
         async connectedCallback() {
@@ -1190,15 +1374,13 @@
             this._pointerHandlers.pointermove = listener(this._onPointerMove);
             this._pointerHandlers.pointerdown = listener(this._onPointerDown);
             this._pointerHandlers.pointerup = listener(this._onPointerUp);
-            // Attach canvas handlers for listeners registered before this boot (e.g. handlers
-            // created from onpointer* attributes when their elements were first upgraded, or
+            this._pointerHandlers.pointercancel = (event) => {
+                this._downPicks.delete(event.pointerId);
+            };
+            // 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('pc-entity, pc-model, pc-node')).some((entity) => entity._hasListeners(type));
-                if (anyListeners) {
-                    this._onPointerListenerAdded(type);
-                }
-            });
+            this._syncCanvasListeners();
         }
         _pickerDestroy() {
             if (this._canvas) {
@@ -1213,15 +1395,12 @@
             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;
         }
         /**
          * Registers the element that fronts an entity. Called by EntityElement when it creates its
@@ -1427,7 +1606,15 @@
         async _onPointerDown(event) {
             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');
@@ -1438,6 +1625,10 @@
         async _onPointerUp(event) {
             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
@@ -1445,30 +1636,60 @@
             if (entityElement) {
                 entityElement.dispatchEvent(new PointerEvent('pointerup', event));
             }
-        }
-        _onPointerListenerAdded(type) {
-            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);
+            }
+        }
+        /**
+         * 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.
+         */
+        _syncCanvasListeners() {
+            const canvas = this._canvas;
+            if (!canvas)
+                return; // not booted yet: _pickerCreate syncs once the handlers exist
+            const elements = Array.from(this.querySelectorAll('pc-entity, pc-model, pc-node'));
+            const needed = new Set();
+            for (const type of SYNTHESIZED_EVENTS) {
+                if (elements.some((element) => element._hasListeners(type))) {
+                    canvasEventsFor[type].forEach((canvasType) => needed.add(canvasType));
                 }
             }
-        }
-        _onPointerListenerRemoved(type) {
-            const hasListeners = Array.from(this.querySelectorAll('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];
-                if (handler) {
-                    this._canvas.removeEventListener(type === 'pointerenter' || type === 'pointerleave' ? 'pointermove' : type, handler);
+            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);
+                }
+            });
         }
         /**
          * Warns that a graphics option was written too late to have any effect. These options are read
@@ -1637,126 +1858,6 @@
     }
     customElements.define('pc-app', AppElement);
 
-    /**
-     * The attribute names of the inline `onpointer*` event handlers, shared by every element that
-     * fronts an engine entity. Spread into `observedAttributes` by subclasses.
-     * @internal
-     */
-    const POINTER_ATTRIBUTES = [
-        'onpointerenter',
-        'onpointerleave',
-        'onpointerdown',
-        'onpointerup',
-        'onpointermove'
-    ];
-    /**
-     * The base class for elements that front an engine {@link Entity}: `<pc-entity>` and
-     * `<pc-model>`, which create one, and `<pc-node>`, which binds to one inside a model's
-     * instantiated hierarchy. It carries what all of them need — the `entity` contract, registration
-     * with the owning application (which joins picked scene nodes back to elements by identity,
-     * never by name), and the pointer listener bookkeeping that lets the application lazily attach
-     * its canvas handlers.
-     */
-    class EntityBaseElement extends AsyncElement {
-        _entity = null;
-        /**
-         * The application element this entity is registered with, cached at registration time so the
-         * entity can be unregistered even once this element has left the DOM.
-         */
-        _appElement = null;
-        /**
-         * The pointer event listeners for the entity.
-         */
-        _listeners = {};
-        /**
-         * The event types for which an inline `onpointer*` attribute is currently present.
-         */
-        _inlineHandlerTypes = new Set();
-        /**
-         * The PlayCanvas entity instance. `null` until the element is ready, and again once the
-         * entity is gone — await {@link whenReady} or the element's `ready()` promise before
-         * accessing it.
-         * @returns The entity instance, or `null`.
-         */
-        get entity() {
-            return this._entity;
-        }
-        /**
-         * Registers `entity` as this element's backing entity with the owning application, which
-         * joins engine nodes back to elements by identity (never by name).
-         *
-         * @param entity - The entity to register.
-         */
-        _registerEntity(entity) {
-            this._appElement = this.closestApp;
-            this._appElement?._registerEntityElement(entity, this);
-        }
-        /**
-         * Removes the registration for `entity`.
-         *
-         * @param entity - The entity to unregister.
-         */
-        _unregisterEntity(entity) {
-            this._appElement?._unregisterEntityElement(entity);
-            this._appElement = null;
-        }
-        /**
-         * 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
-         * bookkeeping that lets the application lazily attach its canvas pointer handlers must be
-         * kept in sync here.
-         *
-         * @param name - The attribute name (e.g. 'onpointerdown').
-         * @param value - The attribute value, or `null` when the attribute has been removed.
-         */
-        _updateInlineHandler(name, value) {
-            const type = name.substring(2);
-            const had = this._inlineHandlerTypes.has(type);
-            const has = value !== null;
-            if (has && !had) {
-                this._inlineHandlerTypes.add(type);
-                this.dispatchEvent(new CustomEvent(`${type}:connect`, { bubbles: true }));
-            }
-            else if (!has && had) {
-                this._inlineHandlerTypes.delete(type);
-                this.dispatchEvent(new CustomEvent(`${type}:disconnect`, { bubbles: true }));
-            }
-        }
-        addEventListener(type, listener, options) {
-            if (!this._listeners[type]) {
-                this._listeners[type] = [];
-            }
-            this._listeners[type].push(listener);
-            super.addEventListener(type, listener, options);
-            if (type.startsWith('pointer')) {
-                this.dispatchEvent(new CustomEvent(`${type}:connect`, { bubbles: true }));
-            }
-        }
-        removeEventListener(type, listener, options) {
-            if (this._listeners[type]) {
-                this._listeners[type] = this._listeners[type].filter((l) => l !== listener);
-            }
-            super.removeEventListener(type, listener, options);
-            if (type.startsWith('pointer')) {
-                this.dispatchEvent(new CustomEvent(`${type}:disconnect`, { bubbles: true }));
-            }
-        }
-        /**
-         * 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
-         * containing `<pc-app>` element to gate pointer event synthesis.
-         *
-         * @param type - The event type.
-         * @returns Whether a listener is registered.
-         * @internal
-         */
-        _hasListeners(type) {
-            return Boolean(this._listeners[type]?.length) || this._inlineHandlerTypes.has(type);
-        }
-    }
-
     /**
      * Creates and parents the entities of every descendant entity-owning element of `root`, in two
      * passes so that no parent's existence depends on document order. Called wherever a subtree could
@@ -1814,7 +1915,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 +2004,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,8 +2125,13 @@
      *
      * 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*`
-     * attribute.
+     * them, registered either with {@link EventTarget.addEventListener} or with the matching inline
+     * attribute (`onpointerdown`, `onclick`, ...).
+     *
+     * @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.
@@ -2040,11 +2146,17 @@
      * entity.
      * @attribute {string} onpointerup - Script to run when a pointer button is released over the
      * entity.
+     * @attribute {string} onclick - Script to run when the entity is clicked: a primary pointer
+     * button pressed and then released over it.
      * @fires {PointerEvent} pointerenter - Fired when the pointer moves onto the entity.
      * @fires {PointerEvent} pointerleave - Fired when the pointer moves off the entity.
      * @fires {PointerEvent} pointermove - Fired when the pointer moves over the entity.
      * @fires {PointerEvent} pointerdown - Fired when a pointer button is pressed over the entity.
      * @fires {PointerEvent} pointerup - Fired when a pointer button is released over the entity.
+     * @fires {PointerEvent} click - Fired when a primary pointer button is pressed and then released
+     * over the entity. A press and release that picked different entities fires on their nearest
+     * common ancestor instead, as in the DOM. `detail` carries the click count, so a double click
+     * arrives as a click whose `detail` is 2.
      */
     class EntityElement extends EntityOwnerElement {
         connectedCallback() {
@@ -2079,7 +2191,7 @@
             this._entity?.destroy();
         }
         static get observedAttributes() {
-            return ['enabled', 'name', 'position', 'rotation', 'scale', 'tags', ...POINTER_ATTRIBUTES];
+            return ['enabled', 'name', 'position', 'rotation', 'scale', 'tags', ...EVENT_ATTRIBUTES];
         }
         attributeChangedCallback(name, _oldValue, newValue) {
             switch (name) {
@@ -2106,6 +2218,7 @@
                 case 'onpointerdown':
                 case 'onpointerup':
                 case 'onpointermove':
+                case 'onclick':
                     this._updateInlineHandler(name, newValue);
                     break;
             }
@@ -2407,6 +2520,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 +3150,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.
@@ -3046,11 +3168,17 @@
      * model.
      * @attribute {string} onpointerup - Script to run when a pointer button is released over the
      * model.
+     * @attribute {string} onclick - Script to run when the model is clicked: a primary pointer
+     * button pressed and then released over it.
      * @fires {PointerEvent} pointerenter - Fired when the pointer moves onto the model.
      * @fires {PointerEvent} pointerleave - Fired when the pointer moves off the model.
      * @fires {PointerEvent} pointermove - Fired when the pointer moves over the model.
      * @fires {PointerEvent} pointerdown - Fired when a pointer button is pressed over the model.
      * @fires {PointerEvent} pointerup - Fired when a pointer button is released over the model.
+     * @fires {PointerEvent} click - Fired when a primary pointer button is pressed and then released
+     * over the model. A press and release that picked different entities fires on their nearest
+     * common ancestor instead, as in the DOM. `detail` carries the click count, so a double click
+     * arrives as a click whose `detail` is 2.
      * @fires {Event} load - Fired each time a container asset finishes instantiating, including
      * re-instantiation after `asset` changes. Does not bubble — listen on this element, or use a
      * capture-phase listener on an ancestor.
@@ -3299,7 +3427,7 @@
             return this._asset;
         }
         static get observedAttributes() {
-            return ['asset', 'enabled', 'name', 'position', 'rotation', 'scale', 'tags', ...POINTER_ATTRIBUTES];
+            return ['asset', 'enabled', 'name', 'position', 'rotation', 'scale', 'tags', ...EVENT_ATTRIBUTES];
         }
         attributeChangedCallback(name, _oldValue, newValue) {
             switch (name) {
@@ -3329,6 +3457,7 @@
                 case 'onpointerdown':
                 case 'onpointerup':
                 case 'onpointermove':
+                case 'onclick':
                     this._updateInlineHandler(name, newValue);
                     break;
             }
@@ -3566,6 +3695,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,7 +4318,9 @@
      * 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 {
         /**
@@ -4512,6 +4648,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 +4681,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 +5089,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 +5123,7 @@
             return {
                 clearColor: this._clearColor,
                 clearColorBuffer: this._clearColorBuffer,
+                clearDepth: this._clearDepth,
                 clearDepthBuffer: this._clearDepthBuffer,
                 clearStencilBuffer: this._clearStencilBuffer,
                 cullFaces: this._cullFaces,
@@ -4991,9 +5142,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 +5174,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 +5234,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 +5529,7 @@
                 ...super.observedAttributes,
                 'clear-color',
                 'clear-color-buffer',
+                'clear-depth',
                 'clear-depth-buffer',
                 'clear-stencil-buffer',
                 'cull-faces',
@@ -5364,11 +5557,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 +5627,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 +5821,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 +6509,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 +7384,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 +7600,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 +7864,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 +7899,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 +7917,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 +7930,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 +8056,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 +8327,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 +8354,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 +8373,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 +8391,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 +8415,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 +8433,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 +8585,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 +8623,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 +10795,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 +10930,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 +11144,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 +11302,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 +11447,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 +11837,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 +12185,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 +12637,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 +12837,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 +13121,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 +13420,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,
@@ -13095,11 +13449,17 @@
      * node.
      * @attribute {string} onpointerup - Script to run when a pointer button is released over the
      * node.
+     * @attribute {string} onclick - Script to run when the node is clicked: a primary pointer
+     * button pressed and then released over it.
      * @fires {PointerEvent} pointerenter - Fired when the pointer moves onto the node.
      * @fires {PointerEvent} pointerleave - Fired when the pointer moves off the node.
      * @fires {PointerEvent} pointermove - Fired when the pointer moves over the node.
      * @fires {PointerEvent} pointerdown - Fired when a pointer button is pressed over the node.
      * @fires {PointerEvent} pointerup - Fired when a pointer button is released over the node.
+     * @fires {PointerEvent} click - Fired when a primary pointer button is pressed and then released
+     * over the node. A press and release that picked different entities fires on their nearest
+     * common ancestor instead, as in the DOM. `detail` carries the click count, so a double click
+     * arrives as a click whose `detail` is 2.
      */
     class NodeElement extends EntityBaseElement {
         _name = '';
@@ -13749,7 +14109,7 @@
                 'rotation',
                 'scale',
                 'tags',
-                ...POINTER_ATTRIBUTES
+                ...EVENT_ATTRIBUTES
             ];
         }
         attributeChangedCallback(name, _oldValue, newValue) {
@@ -13799,6 +14159,7 @@
                 case 'onpointerdown':
                 case 'onpointerup':
                 case 'onpointermove':
+                case 'onclick':
                     this._updateInlineHandler(name, newValue);
                     break;
             }
@@ -13811,8 +14172,16 @@
      * {@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, exposure and gravity settings. Must be a direct child of
+     * `<pc-app>`.
      */
     class SceneElement extends AsyncElement {
+        /**
+         * The exposure of the scene.
+         */
+        _exposure = 1;
         /**
          * The fog type of the scene.
          */
@@ -13880,6 +14249,7 @@
         }
         _updateSceneSettings() {
             if (this._scene) {
+                this._scene.exposure = this._exposure;
                 this._scene.fog.type = this._fog;
                 this._scene.fog.color = this._fogColor;
                 this._scene.fog.density = this._fogDensity;
@@ -13898,6 +14268,24 @@
         _applyGravity(value) {
             this.closestApp?.app?.systems.rigidbody?.gravity.copy(value);
         }
+        /**
+         * Sets the exposure of the scene, which tweaks the overall brightness of the rendered image.
+         * Ignored if the scene is using physical units. Defaults to 1.
+         * @param value - The exposure.
+         */
+        set exposure(value) {
+            this._exposure = value;
+            if (this.scene) {
+                this.scene.exposure = value;
+            }
+        }
+        /**
+         * Gets the exposure of the scene.
+         * @returns The exposure.
+         */
+        get exposure() {
+            return this._exposure;
+        }
         /**
          * Sets the fog type of the scene. Can be `none`, `linear`, `exp` or `exp2`. Defaults to
          * `none`.
@@ -14002,10 +14390,13 @@
             return this._gravity;
         }
         static get observedAttributes() {
-            return ['fog', 'fog-color', 'fog-density', 'fog-start', 'fog-end', 'gravity'];
+            return ['exposure', 'fog', 'fog-color', 'fog-density', 'fog-start', 'fog-end', 'gravity'];
         }
         attributeChangedCallback(name, _oldValue, newValue) {
             switch (name) {
+                case 'exposure':
+                    this.exposure = parseNumber(newValue, 1, name);
+                    break;
                 case 'fog':
                     this.fog = parseEnum(newValue, ['none', 'linear', 'exp', 'exp2'], 'none', name);
                     break;
@@ -14034,6 +14425,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 = '';