@playcanvas/web-components 0.18.0 → 0.20.0

package/dist/pwc.js

@@ -181,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;
     /**
@@ -459,8 +589,13 @@
      * - `parseBool` and `parseTags` take no attribute name, because every value is valid for them and
      *   so they never warn.
      *
-     * `getEntity` is the exception: it resolves a reference to a live entity rather than parsing a
-     * literal, and returns `null` instead of falling back to a default.
+     * `findEntityElement` and `getEntity` are the exceptions: they resolve a reference rather than
+     * parsing a literal, and return `null` instead of falling back to a default. A reference
+     * beginning with `#` is a document-wide selector (an element id, or any selector rooted in one);
+     * anything else is an entity name, resolved lexically through the entity hierarchy first and
+     * against the document after — never as a selector or an id. They also do not warn - what an
+     * unresolved reference means depends on the element holding it - so elements report through
+     * `resolveEntity`, which takes that meaning as parameters.
      */
     /**
      * Splits an attribute value into exactly `count` numeric components. Returns `null` when the
@@ -707,41 +842,259 @@
         return new playcanvas.Vec4(components);
     };
     /**
-     * Resolves a reference string to the {@link Entity} backing a `<pc-entity>` element. The reference
-     * can be a CSS selector (e.g. `#my-id`, `pc-entity[name="Foo"]`), a bare element id, or a bare
-     * entity name. Returns `null` if no matching element (or backing entity) is found.
+     * Runs querySelector, absorbing the SyntaxError an unparseable selector throws - references are
+     * arbitrary author text, so a lookup must fail to `null`, never throw.
      *
-     * @param ref - The reference string to resolve.
-     * @returns The resolved entity, or `null`.
-     * @internal
+     * @param selector - The selector to query.
+     * @returns The matched element, or `null`.
      */
-    const getEntity = (ref) => {
-        if (!ref) {
+    const query = (selector) => {
+        try {
+            return document.querySelector(selector);
+        }
+        catch {
             return null;
         }
-        let element = null;
-        // Try the reference as a CSS selector. An invalid selector (e.g. a bare name containing
-        // spaces) throws, in which case we fall back to id/name lookups below.
+    };
+    /**
+     * Runs a lookup against one scope, checking the scope element itself before its subtree — a
+     * reference deep in a cloned prefab must be able to name the prefab's root. Absorbs the
+     * SyntaxError of an invalid selector like {@link query}: escaping quotes and backslashes does not
+     * make arbitrary text a valid CSS string (a reference containing a newline still throws), so a
+     * lookup must fail to `null`, never throw.
+     *
+     * @param scope - The element whose inclusive subtree to search.
+     * @param selector - The selector to query.
+     * @returns The matched element, or `null`.
+     */
+    const queryScope = (scope, selector) => {
         try {
-            element = document.querySelector(ref);
+            return scope.matches(selector) ? scope : scope.querySelector(selector);
         }
         catch {
-            element = null;
+            return null;
+        }
+    };
+    /**
+     * Reads the entity a resolved element is backing, through the `entity` accessor every
+     * entity-fronting element exposes. `null` for no element, and for an element backing nothing.
+     *
+     * @param element - The element to read, or `null`.
+     * @returns The backing entity, or `null`.
+     */
+    const entityOf = (element) => {
+        return element?.entity ?? null;
+    };
+    /**
+     * The elements that front an entity: what a bare name can resolve to, and the scopes of the
+     * lexical name lookup.
+     */
+    const ENTITY_KINDS = ['pc-entity', 'pc-model', 'pc-node'];
+    /**
+     * The entity-fronting elements as one selector, for the scope walk.
+     */
+    const ENTITY_SCOPES = ENTITY_KINDS.join(', ');
+    /**
+     * Resolves a reference string to the element it names. The grammar is closed — every reference
+     * has exactly one interpretation:
+     *
+     * - A reference beginning with `#` is a document-wide CSS selector — an element id (`#body`), or
+     *   any selector rooted in one (`#hud pc-entity`). It is authoritative: the name lookup never
+     *   runs for it, so an unusually named entity cannot shadow it.
+     * - Any other reference is the name of an entity-fronting element (`<pc-entity>`, `<pc-model>` or
+     *   `<pc-node>` — for a node, the glTF node name it binds), and nothing else. A bare reference is
+     *   never interpreted as a selector or an element id, so adding or renaming elements can never
+     *   change which form it takes.
+     *
+     * When `from` is supplied, a name resolves lexically first: the closest entity-fronting
+     * ancestor's inclusive subtree, then each outer entity-fronting ancestor, then the containing
+     * `<pc-app>`, then the document. This is what lets a `<template>` prefab reference its own
+     * entities by name — every clone resolves within itself before a document-wide lookup could reach
+     * an earlier clone — provided the prefab has a single entity-fronting root to be the enclosing
+     * scope.
+     *
+     * Separate from {@link getEntity} so a caller reporting a failure can tell the causes apart
+     * ({@link unresolvedCause} words them): nothing in the document matches the reference, or
+     * something matches but is not backing an entity (yet, or ever).
+     *
+     * @param ref - The reference string to resolve.
+     * @param from - The element resolving the reference, whose entity-fronting ancestors scope the
+     * name lookup. Omitted, the name lookup is document-wide only.
+     * @returns The matched element, or `null`.
+     * @internal
+     */
+    const findEntityElement = (ref, from) => {
+        if (!ref) {
+            return null;
+        }
+        // A '#' reference is document-wide and bypasses the name lookup entirely - an entity named
+        // '#body' must never shadow the element whose id is 'body'.
+        if (ref.startsWith('#')) {
+            return query(ref);
+        }
+        // The name lands inside a quoted CSS string, so its quotes and backslashes are escaped -
+        // a name like `say "hi"` must resolve, not turn the lookup into a SyntaxError.
+        const escaped = ref.replace(/["\\]/g, '\\$&');
+        const nameSelector = ENTITY_KINDS.map(kind => `${kind}[name="${escaped}"]`).join(', ');
+        if (from) {
+            let scope = from.parentElement?.closest(ENTITY_SCOPES);
+            while (scope) {
+                const element = queryScope(scope, nameSelector);
+                if (element) {
+                    return element;
+                }
+                scope = scope.parentElement?.closest(ENTITY_SCOPES);
+            }
+            const app = from.parentElement?.closest('pc-app');
+            if (app) {
+                const element = queryScope(app, nameSelector);
+                if (element) {
+                    return element;
+                }
+            }
         }
+        return query(nameSelector);
+    };
+    /**
+     * Resolves a reference string to the {@link Entity} backing an entity-fronting element
+     * (`<pc-entity>`, `<pc-model>` or `<pc-node>`). The reference is a name — resolved lexically
+     * through the entity hierarchy first when `from` is supplied — or a document-wide `#` selector
+     * ({@link findEntityElement} details the grammar and order). Returns `null` if no matching
+     * element (or backing entity) is found.
+     *
+     * @param ref - The reference string to resolve.
+     * @param from - The element resolving the reference, whose entity-fronting ancestors scope the
+     * name lookup. Omitted, the name lookup is document-wide only.
+     * @returns The resolved entity, or `null`.
+     * @internal
+     */
+    const getEntity = (ref, from) => {
+        return entityOf(findEntityElement(ref, from));
+    };
+    /**
+     * Describes why a non-empty reference did not resolve, for a warning. Three causes, because they
+     * have three different fixes: nothing matches (usually a typo), the matched element is not backing
+     * an entity yet (usually timing - a `pc-node` whose asset has not loaded - so resolving again
+     * later can work), or the matched element can never back one (the reference points at the wrong
+     * element, so only correcting it can). Capability is the `entity` accessor every entity-backing
+     * element inherits from EntityBaseElement.
+     *
+     * @param element - The element the reference matched, or `null` when nothing did.
+     * @returns The cause, phrased to follow `could not resolve ... -`.
+     * @internal
+     */
+    const unresolvedCause = (element) => {
         if (!element) {
-            element = document.getElementById(ref) ?? document.querySelector(`pc-entity[name="${ref}"]`);
+            return 'nothing in the document matches it';
         }
-        return element?.entity ?? null;
+        const tag = `<${element.tagName.toLowerCase()}>`;
+        return 'entity' in element
+            ? `${tag} matches it but is not backing an entity yet`
+            : `${tag} matches it but cannot back an entity`;
+    };
+    /**
+     * Builds the migration pointer for a bare reference that names nothing but matches the id of an
+     * entity-fronting element - it was almost certainly meant as an id, so point at the form that
+     * expresses it, escaped so the suggestion actually parses as a selector (an id like `a:b` must
+     * be written `#a\:b`). Empty when the reference is already a `#` form, matches no id, or the id
+     * belongs to an element that could never back an entity - suggesting it would only trade this
+     * warning for the wrong-target one.
+     *
+     * @param ref - The unresolved reference.
+     * @param prefix - Text the suggested form must carry in the caller's syntax (e.g. `entity:`).
+     * @returns The advice sentence, or an empty string.
+     * @internal
+     */
+    const idHint = (ref, prefix = '') => {
+        const match = !ref.startsWith('#') && document.getElementById(ref);
+        return match && 'entity' in match
+            ? `A bare reference is a name - write '${prefix}#${CSS.escape(ref)}' to reference the element with that id.`
+            : '';
+    };
+    /**
+     * Resolves a reference string to the {@link Entity} backing an entity-fronting element, scoped to
+     * the resolving element ({@link findEntityElement} details the order) and warning when a
+     * non-empty reference does not resolve - otherwise the reference fails silently, invisible
+     * except through the behavior it should have driven. The message names which of the three causes
+     * ({@link unresolvedCause}) it hit, and advises reassigning later only when that can work.
+     *
+     * An empty reference stays silent: it is the unset state of an optional attribute, and on some
+     * elements (`pc-joint` `entity-b`, `pc-button` `image`) a documented value of its own.
+     *
+     * @param ref - The reference string to resolve.
+     * @param from - The element resolving the reference; scopes the lookup and names the message.
+     * @param attribute - The attribute being resolved, for the message.
+     * @param consequence - What the unresolved reference means for the element, for the message.
+     * @returns The resolved entity, or `null`.
+     * @internal
+     */
+    const resolveEntity = (ref, from, attribute, consequence) => {
+        if (!ref) {
+            return null;
+        }
+        const element = findEntityElement(ref, from);
+        const entity = entityOf(element);
+        if (!entity) {
+            let advice = `Assign ${attribute} again once the entity exists.`;
+            if (element && !('entity' in element)) {
+                advice = `Point ${attribute} at a pc-entity, pc-model or pc-node instead.`;
+            }
+            else if (!element) {
+                const hint = idHint(ref);
+                if (hint) {
+                    advice = hint;
+                }
+            }
+            console.warn(`${from.tagName.toLowerCase()} could not resolve ${attribute} '${ref}' - ${unresolvedCause(element)} - ${consequence}. ${advice}`);
+        }
+        return entity;
     };
 
-    /** 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
@@ -826,21 +1179,36 @@
          */
         _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;
+        /**
+         * Serializes dispatch of the discrete synthesized events (pointerdown, pointerup, click),
+         * whose picks resolve in GPU order, not canvas-event order. Replaced on teardown, so a pick
+         * that never resolves cannot stall the dispatches of a later boot.
+         */
+        _dispatchChain = Promise.resolve();
         _app = null;
         _loadProgress = 0;
         /**
@@ -875,12 +1243,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() {
@@ -1187,9 +1555,8 @@
         _pickerCreate() {
             const { width, height } = this.app.graphicsDevice;
             this._picker = new playcanvas.Picker(this.app, width, height);
-            // Create bound handlers but don't attach them yet. The handlers pick asynchronously, so
-            // each is wrapped to discard the promise - a listener must not return one, and nothing
-            // awaits the result.
+            // Create bound handlers but don't attach them yet. The move handler is async, so it is
+            // wrapped to discard the promise - a listener must not return one.
             const listener = (handler) => {
                 return (event) => {
                     handler.call(this, event);
@@ -1198,15 +1565,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) {
@@ -1221,15 +1586,14 @@
             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;
+            // Replace the chain: a pick that never resolves must not stall a later boot's dispatches
+            this._dispatchChain = Promise.resolve();
         }
         /**
          * Registers the element that fronts an entity. Called by EntityElement when it creates its
@@ -1432,51 +1796,116 @@
                 newHoverEntity.dispatchEvent(new PointerEvent('pointermove', event));
             }
         }
-        async _onPointerDown(event) {
+        /**
+         * Appends a dispatch step to {@link _dispatchChain}. Must be called synchronously from the
+         * canvas event handler - the order of appends is what carries canvas-event order. A step
+         * that rejects is reported and released, so the steps queued behind it still dispatch.
+         *
+         * @param step - The dispatch work to run once every earlier step has finished.
+         */
+        _chainDispatch(step) {
+            this._dispatchChain = this._dispatchChain.then(step).catch((error) => {
+                console.error(error);
+            });
+        }
+        _onPointerDown(event) {
             if (!this._picker || !this.app)
                 return;
-            const node = await this._pickNode(event);
-            if (!this._picker)
-                return; // the element disconnected while the pick was in flight
-            const entityElement = this._elementWithListener(node, 'pointerdown');
-            if (entityElement) {
-                entityElement.dispatchEvent(new PointerEvent('pointerdown', event));
-            }
+            // Picks stay concurrent - only the dispatch of the results is serialized
+            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);
+            }
+            this._chainDispatch(async () => {
+                const node = await pick;
+                if (!this._picker)
+                    return; // the element disconnected while the pick was in flight
+                const entityElement = this._elementWithListener(node, 'pointerdown');
+                if (entityElement) {
+                    entityElement.dispatchEvent(new PointerEvent('pointerdown', event));
+                }
+            });
         }
-        async _onPointerUp(event) {
+        _onPointerUp(event) {
             if (!this._picker || !this.app)
                 return;
-            const node = await this._pickNode(event);
-            if (!this._picker)
-                return; // the element disconnected while the pick was in flight
-            const entityElement = this._elementWithListener(node, 'pointerup');
-            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);
+            // 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 pick = this._pickNode(event);
+            this._chainDispatch(async () => {
+                const node = await pick;
+                if (!this._picker)
+                    return; // the element disconnected while the pick was in flight
+                const entityElement = this._elementWithListener(node, 'pointerup');
+                if (entityElement) {
+                    entityElement.dispatchEvent(new PointerEvent('pointerup', event));
                 }
-            }
+            });
+            // 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. Appended after
+            // the release's own step, so it dispatches after the pointerup that concludes it.
+            if (!downPick || event.button !== 0)
+                return;
+            this._chainDispatch(async () => {
+                // A rejected pick was already reported by the press or release step that awaited it;
+                // here it just means no click can conclude.
+                const picked = await Promise.all([downPick, pick]).catch(() => null);
+                if (!picked || !this._picker)
+                    return;
+                const [downNode, upNode] = picked;
+                const clickElement = this._elementWithListener(commonAncestor(downNode, upNode), '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);
+                }
+            });
         }
-        _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);
+        /**
+         * 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));
                 }
             }
+            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
@@ -1645,126 +2074,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 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 (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 EventTarget.addEventListener} or with the matching inline `onpointer*` attribute. Read by the
-         * containing `<pc-app>` element to gate pointer event synthesis.
-         *
-         * @param type - The event type.
-         * @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
@@ -2032,8 +2341,8 @@
      *
      * 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 EventTarget.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
@@ -2053,11 +2362,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() {
@@ -2092,7 +2407,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) {
@@ -2119,6 +2434,7 @@
                 case 'onpointerdown':
                 case 'onpointerup':
                 case 'onpointermove':
+                case 'onclick':
                     this._updateInlineHandler(name, newValue);
                     break;
             }
@@ -3068,11 +3384,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.
@@ -3321,7 +3643,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) {
@@ -3351,6 +3673,7 @@
                 case 'onpointerdown':
                 case 'onpointerup':
                 case 'onpointermove':
+                case 'onclick':
                     this._updateInlineHandler(name, newValue);
                     break;
             }
@@ -4214,8 +4537,6 @@
      * @elementSummary The `<pc-anim-clip>` element declares one named animation clip on its parent
      * `<pc-anim>`, taken from the `asset` it names or, without one, from the enclosing `<pc-model>`'s
      * own animations. Must be a direct child of `<pc-anim>`.
-     *
-     * @category Components
      */
     class AnimClipElement extends AsyncElement {
         /**
@@ -4617,7 +4938,9 @@
             };
             // The image entity defaults to the button's own entity (which carries the image element)
             // when no explicit reference is provided.
-            const imageEntity = this._image ? getEntity(this._image) : this.closestEntity?.entity;
+            const imageEntity = this._image
+                ? resolveEntity(this._image, this, 'image', 'reference ignored')
+                : this.closestEntity?.entity;
             if (imageEntity) {
                 data.imageEntity = imageEntity;
             }
@@ -4660,21 +4983,27 @@
             return this._active;
         }
         /**
-         * Sets the reference (CSS selector, element id or entity name) to the `<pc-entity>` whose image
-         * element is used for visual transitions. Defaults to the button's own entity — inside a
-         * `<pc-model>`, that is the model's host entity, so supply an explicit reference to target a
-         * UI entity instead.
+         * Sets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+         * selector) to the entity whose image element is used for visual transitions. An exact name
+         * resolves against the nearest enclosing entity first, then outward, then the document.
+         * Defaults to the button's own entity — inside a `<pc-model>`, that is the model's host
+         * entity, so supply an explicit reference to target a UI entity instead. A non-empty
+         * reference that does not resolve warns and is ignored.
          * @param value - The image entity reference.
          */
         set image(value) {
             this._image = value;
-            const entity = getEntity(value);
-            if (this.component && entity) {
-                this.component.imageEntity = entity;
+            if (this.component) {
+                const entity = resolveEntity(value, this, 'image', 'reference ignored');
+                if (entity) {
+                    this.component.imageEntity = entity;
+                }
             }
         }
         /**
-         * Gets the reference to the `<pc-entity>` whose image element is used for visual transitions.
+         * Gets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+         * selector) to the entity whose image element is used for visual transitions, or empty for
+         * the button's own entity.
          * @returns The image entity reference.
          */
         get image() {
@@ -6402,7 +6731,12 @@
      * primary axis: a hinge rotates about it, a slider translates along it and a ball joint twists
      * about it. The constrained bodies are referenced by `entity-a` and `entity-b`, both of which need
      * 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.
+     * space. A reference can name any entity-fronting element — `<pc-entity>`, `<pc-model>` or
+     * `<pc-node>`, so a ragdoll can join a model's own skeleton nodes by name — and a name resolves
+     * against the nearest enclosing entity first, then outward through the entity hierarchy, then the
+     * document, while a `#` selector resolves document-wide. A `<template>` prefab with one
+     * entity-fronting root can therefore wire its joints by name and stay self-contained when cloned.
+     * 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
@@ -6556,8 +6890,8 @@
                 breakImpulse: this._breakImpulse,
                 enableCollision: this._enableCollision,
                 enableLimits: this._enableLimits,
-                entityA: getEntity(this._entityA),
-                entityB: getEntity(this._entityB),
+                entityA: resolveEntity(this._entityA, this, 'entity-a', 'constraint not created'),
+                entityB: resolveEntity(this._entityB, this, 'entity-b', 'constraint not created'),
                 limits: this._limits,
                 linearDamping: this._linearDamping,
                 linearEquilibrium: this._linearEquilibrium,
@@ -6812,39 +7146,48 @@
             return this._enableLimits;
         }
         /**
-         * Sets the reference (CSS selector, element id or entity name) to the `<pc-entity>` providing
-         * the first constrained body. The reference resolves when it is set, so an entity created
-         * later is picked up by setting the attribute again.
+         * Sets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+         * selector) to the element providing the first constrained body. An exact name resolves
+         * against the nearest enclosing entity first, then outward, then the document. The reference
+         * resolves when it is set, so an entity created later is picked up by setting the attribute
+         * again. A non-empty reference that does not resolve warns, naming which of the two causes it
+         * hit.
          * @param value - The first body's entity reference.
          */
         set entityA(value) {
             this._entityA = value;
             if (this.component) {
-                this.component.entityA = getEntity(value);
+                this.component.entityA = resolveEntity(value, this, 'entity-a', 'constraint not created');
             }
         }
         /**
-         * Gets the reference to the `<pc-entity>` providing the first constrained body.
+         * Gets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+         * selector) to the element providing the first constrained body.
          * @returns The first body's entity reference.
          */
         get entityA() {
             return this._entityA;
         }
         /**
-         * Sets the reference (CSS selector, element id or entity name) to the `<pc-entity>` providing
-         * the second constrained body, or empty to constrain the first body to a fixed point in world
-         * space. The reference resolves when it is set, so an entity created later is picked up by
-         * setting the attribute again.
+         * Sets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+         * selector) to the element providing the second constrained body, or empty to constrain the
+         * first body to a fixed point in world space. An exact name resolves against the nearest
+         * enclosing entity first, then outward, then the document. The reference resolves when it is
+         * set, so an entity created later is picked up by setting the attribute again. A non-empty
+         * reference that does not resolve warns; an empty one is the documented world-space case and
+         * stays silent.
          * @param value - The second body's entity reference.
          */
         set entityB(value) {
             this._entityB = value;
             if (this.component) {
-                this.component.entityB = getEntity(value);
+                this.component.entityB = resolveEntity(value, this, 'entity-b', 'constraint not created');
             }
         }
         /**
-         * Gets the reference to the `<pc-entity>` providing the second constrained body.
+         * Gets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+         * selector) to the element providing the second constrained body, or empty for the
+         * world-space case.
          * @returns The second body's entity reference.
          */
         get entityB() {
@@ -11218,7 +11561,7 @@
                 value: this._value,
                 handleSize: this._handleSize
             };
-            const handle = getEntity(this._handle);
+            const handle = resolveEntity(this._handle, this, 'handle', 'reference ignored');
             if (handle) {
                 data.handleEntity = handle;
             }
@@ -11284,19 +11627,24 @@
             return this._handleSize;
         }
         /**
-         * Sets the reference (CSS selector, element id or entity name) to the `<pc-entity>` used as the
-         * scrollbar handle.
+         * Sets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+         * selector) to the entity used as the scrollbar handle. An exact name resolves against the
+         * nearest enclosing entity first, then outward, then the document. A non-empty reference that
+         * does not resolve warns and is ignored.
          * @param value - The handle entity reference.
          */
         set handle(value) {
             this._handle = value;
-            const entity = getEntity(value);
-            if (this.component && entity) {
-                this.component.handleEntity = entity;
+            if (this.component) {
+                const entity = resolveEntity(value, this, 'handle', 'reference ignored');
+                if (entity) {
+                    this.component.handleEntity = entity;
+                }
             }
         }
         /**
-         * Gets the reference to the `<pc-entity>` used as the scrollbar handle.
+         * Gets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+         * selector) to the entity used as the scrollbar handle.
          * @returns The handle entity reference.
          */
         get handle() {
@@ -11378,19 +11726,19 @@
                 horizontalScrollbarVisibility: visibilities.get(this._horizontalScrollbarVisibility),
                 verticalScrollbarVisibility: visibilities.get(this._verticalScrollbarVisibility)
             };
-            const viewport = getEntity(this._viewport);
+            const viewport = resolveEntity(this._viewport, this, 'viewport', 'reference ignored');
             if (viewport) {
                 data.viewportEntity = viewport;
             }
-            const content = getEntity(this._content);
+            const content = resolveEntity(this._content, this, 'content', 'reference ignored');
             if (content) {
                 data.contentEntity = content;
             }
-            const horizontalScrollbar = getEntity(this._horizontalScrollbar);
+            const horizontalScrollbar = resolveEntity(this._horizontalScrollbar, this, 'horizontal-scrollbar', 'reference ignored');
             if (horizontalScrollbar) {
                 data.horizontalScrollbarEntity = horizontalScrollbar;
             }
-            const verticalScrollbar = getEntity(this._verticalScrollbar);
+            const verticalScrollbar = resolveEntity(this._verticalScrollbar, this, 'vertical-scrollbar', 'reference ignored');
             if (verticalScrollbar) {
                 data.verticalScrollbarEntity = verticalScrollbar;
             }
@@ -11566,76 +11914,96 @@
             return this._verticalScrollbarVisibility;
         }
         /**
-         * Sets the reference (CSS selector, element id or entity name) to the `<pc-entity>` used as the
-         * viewport, which clips the content to the scroll view's bounds.
+         * Sets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+         * selector) to the entity used as the viewport, which clips the content to the scroll view's
+         * bounds. An exact name resolves against the nearest enclosing entity first, then outward,
+         * then the document. A non-empty reference that does not resolve warns and is ignored.
          * @param value - The viewport entity reference.
          */
         set viewport(value) {
             this._viewport = value;
-            const entity = getEntity(value);
-            if (this.component && entity) {
-                this.component.viewportEntity = entity;
+            if (this.component) {
+                const entity = resolveEntity(value, this, 'viewport', 'reference ignored');
+                if (entity) {
+                    this.component.viewportEntity = entity;
+                }
             }
         }
         /**
-         * Gets the reference to the `<pc-entity>` used as the viewport.
+         * Gets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+         * selector) to the entity used as the viewport.
          * @returns The viewport entity reference.
          */
         get viewport() {
             return this._viewport;
         }
         /**
-         * Sets the reference (CSS selector, element id or entity name) to the `<pc-entity>` used as the
-         * content, which is moved as the scroll view is scrolled.
+         * Sets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+         * selector) to the entity used as the content, which is moved as the scroll view is
+         * scrolled. An exact name resolves against the nearest enclosing entity first, then outward,
+         * then the document. A non-empty reference that does not resolve warns and is ignored.
          * @param value - The content entity reference.
          */
         set content(value) {
             this._content = value;
-            const entity = getEntity(value);
-            if (this.component && entity) {
-                this.component.contentEntity = entity;
+            if (this.component) {
+                const entity = resolveEntity(value, this, 'content', 'reference ignored');
+                if (entity) {
+                    this.component.contentEntity = entity;
+                }
             }
         }
         /**
-         * Gets the reference to the `<pc-entity>` used as the content.
+         * Gets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+         * selector) to the entity used as the content.
          * @returns The content entity reference.
          */
         get content() {
             return this._content;
         }
         /**
-         * Sets the reference (CSS selector, element id or entity name) to the `<pc-entity>` containing
-         * the horizontal `<pc-scrollbar>`.
+         * Sets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+         * selector) to the entity containing the horizontal `<pc-scrollbar>`. An exact name resolves
+         * against the nearest enclosing entity first, then outward, then the document. A non-empty
+         * reference that does not resolve warns and is ignored.
          * @param value - The horizontal scrollbar entity reference.
          */
         set horizontalScrollbar(value) {
             this._horizontalScrollbar = value;
-            const entity = getEntity(value);
-            if (this.component && entity) {
-                this.component.horizontalScrollbarEntity = entity;
+            if (this.component) {
+                const entity = resolveEntity(value, this, 'horizontal-scrollbar', 'reference ignored');
+                if (entity) {
+                    this.component.horizontalScrollbarEntity = entity;
+                }
             }
         }
         /**
-         * Gets the reference to the `<pc-entity>` containing the horizontal scrollbar.
+         * Gets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+         * selector) to the entity containing the horizontal scrollbar.
          * @returns The horizontal scrollbar entity reference.
          */
         get horizontalScrollbar() {
             return this._horizontalScrollbar;
         }
         /**
-         * Sets the reference (CSS selector, element id or entity name) to the `<pc-entity>` containing
-         * the vertical `<pc-scrollbar>`.
+         * Sets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+         * selector) to the entity containing the vertical `<pc-scrollbar>`. An exact name resolves
+         * against the nearest enclosing entity first, then outward, then the document. A non-empty
+         * reference that does not resolve warns and is ignored.
          * @param value - The vertical scrollbar entity reference.
          */
         set verticalScrollbar(value) {
             this._verticalScrollbar = value;
-            const entity = getEntity(value);
-            if (this.component && entity) {
-                this.component.verticalScrollbarEntity = entity;
+            if (this.component) {
+                const entity = resolveEntity(value, this, 'vertical-scrollbar', 'reference ignored');
+                if (entity) {
+                    this.component.verticalScrollbarEntity = entity;
+                }
             }
         }
         /**
-         * Gets the reference to the `<pc-entity>` containing the vertical scrollbar.
+         * Gets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+         * selector) to the entity containing the vertical scrollbar.
          * @returns The vertical scrollbar entity reference.
          */
         get verticalScrollbar() {
@@ -11718,7 +12086,9 @@
      *   Values are parsed according to the type of the attribute's current value — initially the
      *   script's declared default (numbers, booleans, strings, Vec2/3/4, Color, Quat as Euler
      *   angles) — and the `asset:`/`entity:`/`vec2:`/`vec3:`/`vec4:`/`color:` prefixes may be used
-     *   to be explicit.
+     *   to be explicit. An `entity:` reference is an entity name — resolved against the nearest
+     *   enclosing entity first, then outward, then the document — or a document-wide `#` selector
+     *   (`entity:#id`); a bare value is always a name, never an element id.
      * - **The `attributes` JSON attribute**: an object supporting nested structures and attribute
      *   names that collide with reserved HTML attribute names (e.g. `title`).
      *
@@ -11734,7 +12104,8 @@
      *
      * @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>`.
+     * name, and `attributes` takes a JSON object instead. An `entity:` value is an entity name —
+     * write `entity:#id` for an element id. 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.
@@ -11754,9 +12125,11 @@
         /**
          * Sets the attributes of the script as an object. Values are converted with the same rules
          * as the `attributes` attribute: `asset:`/`entity:` references and `vec2:`/`vec3:`/`vec4:`/
-         * `color:` prefixed strings are resolved, and a plain numeric array is converted to the
-         * type of the attribute it targets when that attribute currently holds a Vec2, Vec3, Vec4
-         * or Color.
+         * `color:` prefixed strings are resolved (an entity name against the nearest enclosing
+         * entity first, then outward, then the document — or a document-wide `#` selector; a bare
+         * value is always a name, never an element id), and a plain numeric array is converted to
+         * the type of the attribute it targets when that attribute currently holds a Vec2, Vec3,
+         * Vec4 or Color.
          * @param value - The attributes of the script.
          */
         set scriptAttributes(value) {
@@ -11767,7 +12140,10 @@
             }));
         }
         /**
-         * Gets the attributes of the script.
+         * Gets the attributes of the script as an object whose `asset:`, `entity:`, `vec2:`, `vec3:`,
+         * `vec4:` and `color:` prefixed values are resolved when applied — an `entity:` value being
+         * an entity name (nearest enclosing entity first, then outward, then the document) or a
+         * document-wide `#` selector (`entity:#id`), never a bare element id.
          * @returns The attributes of the script.
          */
         get scriptAttributes() {
@@ -11978,18 +12354,23 @@
         return raw;
     };
     /**
-     * Resolves an `entity:` prefix to the Entity backing a `pc-entity` element. The reference can be a
-     * CSS selector, an element id or an entity name.
+     * Resolves an `entity:` prefix to the Entity backing a `pc-entity`, `pc-model` or `pc-node`
+     * element. The reference is a name — resolved against the nearest enclosing entity first, then
+     * outward, then the document — or a document-wide `#` selector. The failure warning names which
+     * of the three causes ({@link unresolvedCause}) it hit.
      * @param rest - The entity reference.
      * @param raw - The raw value, returned unchanged when the reference does not resolve.
+     * @param from - The element the value is declared under, which scopes the reference.
      * @returns The entity, or `raw`.
      */
-    const entityConversion = (rest, raw) => {
-        const entity = getEntity(rest);
+    const entityConversion = (rest, raw, from) => {
+        const entity = getEntity(rest, from);
         if (entity) {
             return entity;
         }
-        console.warn(`Unable to resolve '${raw}' in script attributes - no pc-entity found matching '${rest}'.`);
+        const element = findEntityElement(rest, from);
+        const hint = element ? '' : idHint(rest, 'entity:');
+        console.warn(`Unable to resolve '${raw}' in script attributes - ${unresolvedCause(element)}.${hint ? ` ${hint}` : ''}`);
         return raw;
     };
     /**
@@ -12122,8 +12503,10 @@
         /**
          * Recursively converts raw attribute data into proper PlayCanvas types. Supported conversions:
          * - "asset:id" → the Asset created by the `pc-asset` element with that id
-         * - "entity:ref" → the Entity backing a `pc-entity` element. The reference can be a CSS
-         *   selector, an element id or an entity name.
+         * - "entity:ref" → the Entity backing a `pc-entity`, `pc-model` or `pc-node` element. The
+         *   reference is a name, resolved against this element's nearest enclosing entity first,
+         *   then outward, then the document — or a document-wide `#` selector (`entity:#id`). A bare
+         *   value is always a name, never an id.
          * - "vec2:1 2" → new Vec2(1, 2)
          * - "vec3:1 2 3" → new Vec3(1, 2, 3)
          * - "vec4:1 2 3 4" → new Vec4(1, 2, 3, 4)
@@ -12137,7 +12520,7 @@
         convertAttributes(item) {
             if (typeof item === 'string') {
                 const match = matchConversion(item);
-                return match ? match.convert(match.rest, item) : item;
+                return match ? match.convert(match.rest, item, this) : item;
             }
             if (Array.isArray(item)) {
                 return item.map((element) => this.convertAttributes(element));
@@ -13344,11 +13727,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 = '';
@@ -13998,7 +14387,7 @@
                 'rotation',
                 'scale',
                 'tags',
-                ...POINTER_ATTRIBUTES
+                ...EVENT_ATTRIBUTES
             ];
         }
         attributeChangedCallback(name, _oldValue, newValue) {
@@ -14048,6 +14437,7 @@
                 case 'onpointerdown':
                 case 'onpointerup':
                 case 'onpointermove':
+                case 'onclick':
                     this._updateInlineHandler(name, newValue);
                     break;
             }
@@ -14062,9 +14452,14 @@
      * {@link HTMLElement} interface.
      *
      * @elementSummary The `<pc-scene>` element holds the entity hierarchy the application renders,
-     * along with the scene-wide fog and gravity settings. Must be a direct child of `<pc-app>`.
+     * 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.
          */
@@ -14132,6 +14527,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;
@@ -14150,6 +14546,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`.
@@ -14254,10 +14668,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;