@playcanvas/web-components 0.17.0 → 0.19.0

package/dist/pwc.mjs

@@ -1,4 +1,4 @@
-import { basisInitialize, WasmModule, Vec3, Color, Vec4, Quat, Vec2, createGraphicsDevice, AppOptions, Keyboard, Mouse, ElementInput, AnimComponentSystem, AnimationComponentSystem, AudioListenerComponentSystem, ButtonComponentSystem, CameraComponentSystem, CollisionComponentSystem, ElementComponentSystem, GSplatComponentSystem, JointComponentSystem, LayoutChildComponentSystem, LayoutGroupComponentSystem, LightComponentSystem, ModelComponentSystem, ParticleSystemComponentSystem, RenderComponentSystem, RigidBodyComponentSystem, ScreenComponentSystem, ScriptComponentSystem, ScrollbarComponentSystem, ScrollViewComponentSystem, SoundComponentSystem, SpriteComponentSystem, ZoneComponentSystem, AnimClipHandler, AnimationHandler, AnimStateGraphHandler, AudioHandler, BinaryHandler, CssHandler, ContainerHandler, CubemapHandler, FolderHandler, FontHandler, GSplatHandler, HierarchyHandler, HtmlHandler, JsonHandler, MaterialHandler, ModelHandler, RenderHandler, ScriptHandler, SceneHandler, ShaderHandler, SpriteHandler, TemplateHandler, TextHandler, TextureAtlasHandler, TextureHandler, SoundManager, Lightmapper, BatchManager, XrManager, AppBase, FILLMODE_NONE, RESOLUTION_AUTO, Picker, MeshInstance, Entity, Asset, SPRITE_RENDERMODE_SIMPLE, FILTER_LINEAR_MIPMAP_LINEAR, FILTER_LINEAR, ADDRESS_REPEAT, SPRITE_RENDERMODE_SLICED, SPRITE_RENDERMODE_TILED, ADDRESS_CLAMP_TO_EDGE, ADDRESS_MIRRORED_REPEAT, FILTER_NEAREST, FILTER_NEAREST_MIPMAP_NEAREST, FILTER_LINEAR_MIPMAP_NEAREST, FILTER_NEAREST_MIPMAP_LINEAR, AnimTrack, ANIM_CONTROL_STATES, BUTTON_TRANSITION_MODE_TINT, BUTTON_TRANSITION_MODE_SPRITE_CHANGE, TONEMAP_NONE, PROJECTION_PERSPECTIVE, GAMMA_SRGB, GAMMA_NONE, XRTYPE_VR, TONEMAP_LINEAR, TONEMAP_FILMIC, TONEMAP_HEJL, TONEMAP_ACES, TONEMAP_ACES2, TONEMAP_NEUTRAL, PROJECTION_ORTHOGRAPHIC, ORIENTATION_HORIZONTAL, FITTING_NONE, FITTING_STRETCH, FITTING_SHRINK, FITTING_BOTH, ORIENTATION_VERTICAL, SHADOW_PCF3_32F, SHADOW_PCF1_16F, SHADOW_PCF1_32F, SHADOW_PCF3_16F, SHADOW_PCF5_16F, SHADOW_PCF5_32F, SHADOW_VSM_16F, SHADOW_VSM_32F, SHADOW_PCSS_32F, StandardMaterial, BLEND_NONE, CULLFACE_BACK, FRESNEL_SCHLICK, SPECOCC_AO, BLEND_NORMAL, BLEND_ADDITIVE, BLEND_ADDITIVEALPHA, BLEND_PREMULTIPLIED, BLEND_MULTIPLICATIVE, BLEND_MULTIPLICATIVE2X, BLEND_SCREEN, BLEND_MIN, BLEND_MAX, BLEND_SUBTRACTIVE, CULLFACE_NONE, CULLFACE_FRONT, CULLFACE_FRONTANDBACK, FRESNEL_NONE, SPECOCC_NONE, SPECOCC_GLOSSDEPENDENT, SCALEMODE_NONE, SCALEMODE_BLEND, SCROLL_MODE_BOUNCE, SCROLLBAR_VISIBILITY_SHOW_WHEN_REQUIRED, SCROLLBAR_VISIBILITY_SHOW_ALWAYS, SCROLL_MODE_CLAMP, SCROLL_MODE_INFINITE, EnvLighting, LAYERID_SKYBOX } from 'playcanvas';
+import { basisInitialize, WasmModule, Vec3, Color, Vec4, Quat, Vec2, createGraphicsDevice, AppOptions, Keyboard, Mouse, ElementInput, AnimComponentSystem, AnimationComponentSystem, AudioListenerComponentSystem, ButtonComponentSystem, CameraComponentSystem, CollisionComponentSystem, ElementComponentSystem, GSplatComponentSystem, JointComponentSystem, LayoutChildComponentSystem, LayoutGroupComponentSystem, LightComponentSystem, ModelComponentSystem, ParticleSystemComponentSystem, RenderComponentSystem, RigidBodyComponentSystem, ScreenComponentSystem, ScriptComponentSystem, ScrollbarComponentSystem, ScrollViewComponentSystem, SoundComponentSystem, SpriteComponentSystem, ZoneComponentSystem, AnimClipHandler, AnimationHandler, AnimStateGraphHandler, AudioHandler, BinaryHandler, CssHandler, ContainerHandler, CubemapHandler, FolderHandler, FontHandler, GSplatHandler, HierarchyHandler, HtmlHandler, JsonHandler, MaterialHandler, ModelHandler, RenderHandler, ScriptHandler, SceneHandler, ShaderHandler, SpriteHandler, TemplateHandler, TextHandler, TextureAtlasHandler, TextureHandler, SoundManager, Lightmapper, BatchManager, XrManager, AppBase, FILLMODE_NONE, RESOLUTION_AUTO, Picker, MeshInstance, Entity, Asset, SPRITE_RENDERMODE_SIMPLE, FILTER_LINEAR_MIPMAP_LINEAR, FILTER_LINEAR, ADDRESS_REPEAT, SPRITE_RENDERMODE_SLICED, SPRITE_RENDERMODE_TILED, ADDRESS_CLAMP_TO_EDGE, ADDRESS_MIRRORED_REPEAT, FILTER_NEAREST, FILTER_NEAREST_MIPMAP_NEAREST, FILTER_LINEAR_MIPMAP_NEAREST, FILTER_NEAREST_MIPMAP_LINEAR, AnimTrack, ANIM_CONTROL_STATES, BUTTON_TRANSITION_MODE_TINT, BUTTON_TRANSITION_MODE_SPRITE_CHANGE, TONEMAP_NONE, PROJECTION_PERSPECTIVE, GAMMA_SRGB, GAMMA_NONE, XRTYPE_AR, XRTYPE_VR, TONEMAP_LINEAR, TONEMAP_FILMIC, TONEMAP_HEJL, TONEMAP_ACES, TONEMAP_ACES2, TONEMAP_NEUTRAL, PROJECTION_ORTHOGRAPHIC, ORIENTATION_HORIZONTAL, FITTING_NONE, FITTING_STRETCH, FITTING_SHRINK, FITTING_BOTH, ORIENTATION_VERTICAL, SHADOW_PCF3_32F, SHADOW_PCF1_16F, SHADOW_PCF1_32F, SHADOW_PCF3_16F, SHADOW_PCF5_16F, SHADOW_PCF5_32F, SHADOW_VSM_16F, SHADOW_VSM_32F, SHADOW_PCSS_32F, StandardMaterial, BLEND_NONE, CULLFACE_BACK, FRESNEL_SCHLICK, SPECOCC_AO, BLEND_NORMAL, BLEND_ADDITIVE, BLEND_ADDITIVEALPHA, BLEND_PREMULTIPLIED, BLEND_MULTIPLICATIVE, BLEND_MULTIPLICATIVE2X, BLEND_SCREEN, BLEND_MIN, BLEND_MAX, BLEND_SUBTRACTIVE, CULLFACE_NONE, CULLFACE_FRONT, CULLFACE_FRONTANDBACK, FRESNEL_NONE, SPECOCC_NONE, SPECOCC_GLOSSDEPENDENT, SCALEMODE_NONE, SCALEMODE_BLEND, SCROLL_MODE_BOUNCE, SCROLLBAR_VISIBILITY_SHOW_WHEN_REQUIRED, SCROLLBAR_VISIBILITY_SHOW_ALWAYS, SCROLL_MODE_CLAMP, SCROLL_MODE_INFINITE, EnvLighting, LAYERID_SKYBOX } from 'playcanvas';
 
 /**
  * Base class for all PlayCanvas Web Components that initialize asynchronously.
@@ -121,6 +121,10 @@ async function whenReady(target) {
  * 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.
@@ -173,6 +177,136 @@ class WasmElement extends AsyncElement {
 }
 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;
 /**
@@ -726,14 +860,51 @@ const getEntity = (ref) => {
     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
@@ -762,6 +933,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
@@ -814,21 +989,30 @@ class AppElement extends AsyncElement {
      */
     _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;
     /**
@@ -863,12 +1047,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());
         });
     }
     async connectedCallback() {
@@ -1186,15 +1370,13 @@ class AppElement extends AsyncElement {
         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) {
@@ -1209,15 +1391,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;
     }
     /**
      * Registers the element that fronts an entity. Called by EntityElement when it creates its
@@ -1423,7 +1602,15 @@ class AppElement extends AsyncElement {
     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');
@@ -1434,6 +1621,10 @@ class AppElement extends AsyncElement {
     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
@@ -1441,30 +1632,60 @@ class AppElement extends AsyncElement {
         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
@@ -1633,126 +1854,6 @@ class AppElement extends AsyncElement {
 }
 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
@@ -1810,7 +1911,7 @@ class EntityOwnerElement extends EntityBaseElement {
      */
     _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;
@@ -1899,7 +2000,7 @@ class EntityOwnerElement extends EntityBaseElement {
         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.
@@ -2020,8 +2121,13 @@ class EntityOwnerElement extends EntityBaseElement {
  *
  * 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.
@@ -2036,11 +2142,17 @@ class EntityOwnerElement extends EntityBaseElement {
  * 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() {
@@ -2075,7 +2187,7 @@ class EntityElement extends EntityOwnerElement {
         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) {
@@ -2102,6 +2214,7 @@ class EntityElement extends EntityOwnerElement {
             case 'onpointerdown':
             case 'onpointerup':
             case 'onpointermove':
+            case 'onclick':
                 this._updateInlineHandler(name, newValue);
                 break;
         }
@@ -2403,6 +2516,10 @@ const processBufferView = (gltfBuffer, buffers, continuation) => {
  * 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.
@@ -3029,6 +3146,11 @@ const formatHierarchy = (root, counts) => {
  * 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.
@@ -3042,11 +3164,17 @@ const formatHierarchy = (root, counts) => {
  * 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.
@@ -3295,7 +3423,7 @@ class ModelElement extends EntityOwnerElement {
         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) {
@@ -3325,6 +3453,7 @@ class ModelElement extends EntityOwnerElement {
             case 'onpointerdown':
             case 'onpointerup':
             case 'onpointermove':
+            case 'onclick':
                 this._updateInlineHandler(name, newValue);
                 break;
         }
@@ -3562,6 +3691,11 @@ class ComponentElement extends AsyncElement {
  *
  * 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 {
@@ -4180,7 +4314,9 @@ customElements.define('pc-anim', AnimComponentElement);
  * 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 {
     /**
@@ -4508,6 +4644,10 @@ customElements.define('pc-anim-clip', AnimClipElement);
  *
  * 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 {
@@ -4537,6 +4677,11 @@ const transitionModes = new Map([
  *
  * 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 {
@@ -4940,13 +5085,18 @@ const tonemaps = new Map([
  *
  * 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 Color(0.75, 0.75, 0.75, 1);
     _clearColorBuffer = true;
+    _clearDepth = 1;
     _clearDepthBuffer = true;
-    _clearStencilBuffer = false;
+    _clearStencilBuffer = true;
     _cullFaces = true;
     _farClip = 1000;
     _flipFaces = false;
@@ -4969,6 +5119,7 @@ class CameraComponentElement extends ComponentElement {
         return {
             clearColor: this._clearColor,
             clearColorBuffer: this._clearColorBuffer,
+            clearDepth: this._clearDepth,
             clearDepthBuffer: this._clearDepthBuffer,
             clearStencilBuffer: this._clearStencilBuffer,
             cullFaces: this._cullFaces,
@@ -4987,9 +5138,31 @@ class CameraComponentElement extends ComponentElement {
             toneMapping: tonemaps.get(this._tonemap) ?? 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(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(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(XRTYPE_VR);
+        return Boolean(xrManager?.supported && xrManager.isAvailable(type));
     }
     /**
      * Starts the camera in XR mode.
@@ -4997,11 +5170,13 @@ class CameraComponentElement extends ComponentElement {
      * @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}`);
                 }
             });
         }
@@ -5055,6 +5230,23 @@ class CameraComponentElement extends ComponentElement {
     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.
@@ -5333,6 +5525,7 @@ class CameraComponentElement extends ComponentElement {
             ...super.observedAttributes,
             'clear-color',
             'clear-color-buffer',
+            'clear-depth',
             'clear-depth-buffer',
             'clear-stencil-buffer',
             'cull-faces',
@@ -5360,11 +5553,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);
@@ -5427,6 +5623,10 @@ customElements.define('pc-camera', CameraComponentElement);
  *
  * 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 {
@@ -5617,6 +5817,10 @@ customElements.define('pc-collision', CollisionComponentElement);
  *
  * 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 {
@@ -6301,6 +6505,11 @@ customElements.define('pc-element', ElementComponentElement);
  * 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.
@@ -7171,6 +7380,10 @@ customElements.define('pc-joint', JointComponentElement);
  *
  * 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 {
@@ -7383,6 +7596,10 @@ const fittings = new Map([
  *
  * 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 {
@@ -7643,23 +7860,30 @@ const shadowTypes = new Map([
  *
  * 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 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;
@@ -7671,11 +7895,14 @@ class LightComponentElement extends ComponentElement {
     }
     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,
@@ -7686,7 +7913,7 @@ class LightComponentElement extends ComponentElement {
             shadowIntensity: this._shadowIntensity,
             shadowResolution: this._shadowResolution,
             shadowSamples: this._shadowSamples,
-            shadowType: shadowTypes.get(this._shadowType),
+            shadowType: shadowTypes.get(this._shadowType) ?? SHADOW_PCF3_32F,
             type: this._type,
             vsmBias: this._vsmBias,
             vsmBlurSize: this._vsmBlurSize
@@ -7699,6 +7926,47 @@ class LightComponentElement extends ComponentElement {
     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.
@@ -7784,6 +8052,25 @@ class LightComponentElement extends ComponentElement {
     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.
@@ -8036,11 +8323,14 @@ class LightComponentElement extends ComponentElement {
     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',
@@ -8060,12 +8350,18 @@ class LightComponentElement extends ComponentElement {
     attributeChangedCallback(name, _oldValue, newValue) {
         super.attributeChangedCallback(name, _oldValue, newValue);
         switch (name) {
-            case 'color':
-                this.color = parseColor(newValue, 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, Color.WHITE, name);
+                break;
             case 'inner-cone-angle':
                 this.innerConeAngle = parseNumber(newValue, 40, name);
                 break;
@@ -8073,7 +8369,10 @@ class LightComponentElement extends ComponentElement {
                 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);
@@ -8088,20 +8387,20 @@ class LightComponentElement extends ComponentElement {
                 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;
@@ -8112,7 +8411,7 @@ class LightComponentElement extends ComponentElement {
                 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);
@@ -8130,6 +8429,10 @@ customElements.define('pc-light', LightComponentElement);
  *
  * 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 {
@@ -8278,6 +8581,8 @@ const occludeSpeculars = new Map([
     ['ao', SPECOCC_AO],
     ['gloss-dependent', 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'];
@@ -8314,6 +8619,10 @@ const roughnessAliases = ['roughness', 'roughness-map'];
  * 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
@@ -10482,6 +10791,11 @@ customElements.define('pc-material', MaterialElement);
  *
  * 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 {
@@ -10612,6 +10926,11 @@ customElements.define('pc-render', RenderComponentElement);
  *
  * 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 {
@@ -10821,6 +11140,10 @@ const scaleModes = new Map([
  *
  * 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 {
@@ -10975,6 +11298,10 @@ const orientations = new Map([
  *
  * 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 {
@@ -11116,6 +11443,10 @@ const visibilities = new Map([
  *
  * 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 {
@@ -11502,6 +11833,10 @@ customElements.define('pc-scroll-view', ScrollViewComponentElement);
  * 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
@@ -11846,6 +12181,9 @@ const findCaseMatch = (script, key) => {
  *
  * 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 {
@@ -12295,6 +12633,10 @@ customElements.define('pc-script', ScriptComponentElement);
  *
  * 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 {
@@ -12491,6 +12833,9 @@ customElements.define('pc-sound', SoundComponentElement);
  * 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 = '';
@@ -12772,6 +13117,10 @@ customElements.define('pc-sound-slot', SoundSlotElement);
  *
  * 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 {
@@ -13067,6 +13416,11 @@ const levenshtein = (a, b) => {
  * 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,
@@ -13091,11 +13445,17 @@ const levenshtein = (a, b) => {
  * 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 = '';
@@ -13745,7 +14105,7 @@ class NodeElement extends EntityBaseElement {
             'rotation',
             'scale',
             'tags',
-            ...POINTER_ATTRIBUTES
+            ...EVENT_ATTRIBUTES
         ];
     }
     attributeChangedCallback(name, _oldValue, newValue) {
@@ -13795,6 +14155,7 @@ class NodeElement extends EntityBaseElement {
             case 'onpointerdown':
             case 'onpointerup':
             case 'onpointermove':
+            case 'onclick':
                 this._updateInlineHandler(name, newValue);
                 break;
         }
@@ -13807,8 +14168,16 @@ customElements.define('pc-node', NodeElement);
  * {@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.
      */
@@ -13876,6 +14245,7 @@ class SceneElement extends AsyncElement {
     }
     _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;
@@ -13894,6 +14264,24 @@ class SceneElement extends AsyncElement {
     _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`.
@@ -13998,10 +14386,13 @@ class SceneElement extends AsyncElement {
         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;
@@ -14030,6 +14421,10 @@ customElements.define('pc-scene', SceneElement);
  * 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 = '';