@playcanvas/web-components 0.18.0 → 0.20.0

package/dist/pwc.mjs

@@ -177,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;
 /**
@@ -455,8 +585,13 @@ const CSS_COLORS = {
  * - `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
@@ -703,41 +838,259 @@ const parseVec4 = (value, defaultValue, attribute) => {
     return new 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
@@ -822,21 +1175,36 @@ 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;
+    /**
+     * 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;
     /**
@@ -871,12 +1239,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() {
@@ -1183,9 +1551,8 @@ class AppElement extends AsyncElement {
     _pickerCreate() {
         const { width, height } = this.app.graphicsDevice;
         this._picker = new 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);
@@ -1194,15 +1561,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) {
@@ -1217,15 +1582,14 @@ 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;
+        // 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
@@ -1428,51 +1792,116 @@ class AppElement extends AsyncElement {
             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
@@ -1641,126 +2070,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 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
@@ -2028,8 +2337,8 @@ 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 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
@@ -2049,11 +2358,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() {
@@ -2088,7 +2403,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) {
@@ -2115,6 +2430,7 @@ class EntityElement extends EntityOwnerElement {
             case 'onpointerdown':
             case 'onpointerup':
             case 'onpointermove':
+            case 'onclick':
                 this._updateInlineHandler(name, newValue);
                 break;
         }
@@ -3064,11 +3380,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.
@@ -3317,7 +3639,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) {
@@ -3347,6 +3669,7 @@ class ModelElement extends EntityOwnerElement {
             case 'onpointerdown':
             case 'onpointerup':
             case 'onpointermove':
+            case 'onclick':
                 this._updateInlineHandler(name, newValue);
                 break;
         }
@@ -4210,8 +4533,6 @@ customElements.define('pc-anim', AnimComponentElement);
  * @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 {
     /**
@@ -4613,7 +4934,9 @@ class ButtonComponentElement extends ComponentElement {
         };
         // 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;
         }
@@ -4656,21 +4979,27 @@ class ButtonComponentElement extends ComponentElement {
         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() {
@@ -6398,7 +6727,12 @@ customElements.define('pc-element', ElementComponentElement);
  * 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
@@ -6552,8 +6886,8 @@ class JointComponentElement extends ComponentElement {
             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,
@@ -6808,39 +7142,48 @@ class JointComponentElement extends ComponentElement {
         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() {
@@ -11214,7 +11557,7 @@ class ScrollbarComponentElement extends ComponentElement {
             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;
         }
@@ -11280,19 +11623,24 @@ class ScrollbarComponentElement extends ComponentElement {
         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() {
@@ -11374,19 +11722,19 @@ class ScrollViewComponentElement extends ComponentElement {
             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;
         }
@@ -11562,76 +11910,96 @@ class ScrollViewComponentElement extends ComponentElement {
         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() {
@@ -11714,7 +12082,9 @@ customElements.define('pc-scroll-view', ScrollViewComponentElement);
  *   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`).
  *
@@ -11730,7 +12100,8 @@ customElements.define('pc-scroll-view', ScrollViewComponentElement);
  *
  * @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.
@@ -11750,9 +12121,11 @@ class ScriptInstanceElement extends AsyncElement {
     /**
      * 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) {
@@ -11763,7 +12136,10 @@ class ScriptInstanceElement extends AsyncElement {
         }));
     }
     /**
-     * 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() {
@@ -11974,18 +12350,23 @@ const assetConversion = (rest, raw) => {
     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;
 };
 /**
@@ -12118,8 +12499,10 @@ class ScriptComponentElement extends ComponentElement {
     /**
      * 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)
@@ -12133,7 +12516,7 @@ class ScriptComponentElement extends ComponentElement {
     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));
@@ -13340,11 +13723,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 = '';
@@ -13994,7 +14383,7 @@ class NodeElement extends EntityBaseElement {
             'rotation',
             'scale',
             'tags',
-            ...POINTER_ATTRIBUTES
+            ...EVENT_ATTRIBUTES
         ];
     }
     attributeChangedCallback(name, _oldValue, newValue) {
@@ -14044,6 +14433,7 @@ class NodeElement extends EntityBaseElement {
             case 'onpointerdown':
             case 'onpointerup':
             case 'onpointermove':
+            case 'onclick':
                 this._updateInlineHandler(name, newValue);
                 break;
         }
@@ -14058,9 +14448,14 @@ customElements.define('pc-node', NodeElement);
  * {@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.
      */
@@ -14128,6 +14523,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;
@@ -14146,6 +14542,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`.
@@ -14250,10 +14664,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;