@playcanvas/web-components 0.18.0 → 0.20.0

package/src/app.ts

@@ -66,6 +66,7 @@ import {
 
 import type { AssetElement } from './asset';
 import { AsyncElement } from './async-element';
+import { SYNTHESIZED_EVENTS } from './entity-base';
 import type { EntityBaseElement } from './entity-base';
 import type { EntityOwnerElement } from './entity-owner';
 import { LoadingBar } from './loading-bar';
@@ -73,9 +74,6 @@ import type { MaterialElement } from './material';
 import { parseBool, parseEnum, parseNumber } from './parse';
 import type { WasmElement } from './wasm';
 
-/** The pointer event types the application synthesizes on `<pc-entity>` elements via picking. */
-const pointerEventTypes = ['pointermove', 'pointerdown', 'pointerup', 'pointerenter', 'pointerleave'] as const;
-
 /**
  * The event types whose listeners make an element a hover target. Hover resolution walks past
  * elements listening for none of them, so a silent element never swallows an ancestor's
@@ -83,6 +81,48 @@ const pointerEventTypes = ['pointermove', 'pointerdown', 'pointerup', 'pointeren
  */
 const hoverEventTypes = ['pointerenter', 'pointerleave', 'pointermove'] as const;
 
+/**
+ * The canvas listeners each synthesized event type is driven by. Enter and leave are derived
+ * from move picks. A click is concluded from the down/up pair, with pointercancel discarding a
+ * press the browser takes back (for example a touch that becomes a scroll).
+ */
+const canvasEventsFor: Record<(typeof SYNTHESIZED_EVENTS)[number], readonly string[]> = {
+    pointermove: ['pointermove'],
+    pointerenter: ['pointermove'],
+    pointerleave: ['pointermove'],
+    pointerdown: ['pointerdown'],
+    pointerup: ['pointerup'],
+    click: ['pointerdown', 'pointerup', 'pointercancel']
+};
+
+/**
+ * How long after a click a further click on the same target still raises the click count that
+ * `detail` carries, approximating the platform's double-click time.
+ */
+const CLICK_CHAIN_MS = 500;
+
+/**
+ * Finds the nearest common inclusive ancestor of two picked nodes - the node a click belongs to
+ * when the press and the release picked different geometry, exactly as the DOM assigns a click
+ * whose down and up have different targets.
+ *
+ * @param a - The node the press picked, or `null`.
+ * @param b - The node the release picked, or `null`.
+ * @returns The nearest common inclusive ancestor, or `null` when there is none.
+ */
+const commonAncestor = (a: GraphNode | null, b: GraphNode | null): GraphNode | null => {
+    const ancestors = new Set<GraphNode>();
+    for (let node = a; node !== null; node = node.parent) {
+        ancestors.add(node);
+    }
+    for (let node = b; node !== null; node = node.parent) {
+        if (ancestors.has(node)) {
+            return node;
+        }
+    }
+    return null;
+};
+
 /**
  * Gives `pc-app` the sizing contract of a replaced element (`<video>`, `<img>`): a block-level
  * box that the page's CSS sizes, defaulting to the canvas's own 300x150 intrinsic size, with the
@@ -182,14 +222,6 @@ class AppElement extends AsyncElement {
 
     private _picker: Picker | null = null;
 
-    private _hasPointerListeners: Record<string, boolean> = {
-        pointerenter: false,
-        pointerleave: false,
-        pointerdown: false,
-        pointerup: false,
-        pointermove: false
-    };
-
     private _hoveredEntity: EntityBaseElement | null = null;
 
     // Identifies the newest in-flight hover pick, so out-of-order results can be discarded
@@ -198,9 +230,35 @@ class AppElement extends AsyncElement {
     private _pointerHandlers: Record<string, EventListener | null> = {
         pointermove: null,
         pointerdown: null,
-        pointerup: null
+        pointerup: null,
+        pointercancel: null
     };
 
+    /**
+     * The pick of each pointer's primary-button press, keyed by pointerId and kept while a click
+     * may still conclude it. The promise is stored rather than its result, so a release can
+     * await a press pick that has not resolved yet. Entries are removed by the matching
+     * pointerup or pointercancel, and only ever stored while some element listens for click -
+     * which is also what keeps those two canvas listeners attached.
+     */
+    private _downPicks = new Map<number, Promise<GraphNode | null>>();
+
+    /** Whether any element in the tree listens for click. Maintained by _syncCanvasListeners. */
+    private _clickListened = false;
+
+    /**
+     * The previous click's target, time and count, for chaining successive clicks into the
+     * click count that `detail` carries. `null` until a click has fired.
+     */
+    private _lastClick: { element: EntityBaseElement; time: number; count: number } | null = null;
+
+    /**
+     * 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.
+     */
+    private _dispatchChain: Promise<void> = Promise.resolve();
+
     private _app: AppBase | null = null;
 
     private _loadProgress = 0;
@@ -241,12 +299,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());
         });
     }
 
@@ -597,10 +655,9 @@ class AppElement extends AsyncElement {
         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.
-        const listener = (handler: (event: PointerEvent) => Promise<void>): EventListener => {
+        // 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: (event: PointerEvent) => void | Promise<void>): EventListener => {
             return (event: Event) => {
                 handler.call(this, event as PointerEvent);
             };
@@ -609,18 +666,14 @@ class AppElement extends AsyncElement {
         this._pointerHandlers.pointermove = listener(this._onPointerMove);
         this._pointerHandlers.pointerdown = listener(this._onPointerDown);
         this._pointerHandlers.pointerup = listener(this._onPointerUp);
+        this._pointerHandlers.pointercancel = (event: Event) => {
+            this._downPicks.delete((event as PointerEvent).pointerId);
+        };
 
-        // Attach canvas handlers for listeners registered before this boot (e.g. handlers
-        // created from onpointer* attributes when their elements were first upgraded, or
+        // Attach canvas listeners for element listeners registered before this boot (e.g.
+        // handlers created from inline attributes when their elements were first upgraded, or
         // listeners carried over from before a re-boot)
-        pointerEventTypes.forEach((type) => {
-            const anyListeners = Array.from(
-                this.querySelectorAll<EntityBaseElement>('pc-entity, pc-model, pc-node')
-            ).some((entity) => entity._hasListeners(type));
-            if (anyListeners) {
-                this._onPointerListenerAdded(type);
-            }
-        });
+        this._syncCanvasListeners();
     }
 
     private _pickerDestroy() {
@@ -637,15 +690,15 @@ 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();
     }
 
     /**
@@ -868,69 +921,126 @@ class AppElement extends AsyncElement {
         }
     }
 
-    private async _onPointerDown(event: PointerEvent) {
+    /**
+     * 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.
+     */
+    private _chainDispatch(step: () => Promise<void>) {
+        this._dispatchChain = this._dispatchChain.then(step).catch((error) => {
+            console.error(error);
+        });
+    }
+
+    private _onPointerDown(event: PointerEvent) {
         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
+        // Picks stay concurrent - only the dispatch of the results is serialized
+        const pick = this._pickNode(event);
 
-        const entityElement = this._elementWithListener(node, 'pointerdown');
-        if (entityElement) {
-            entityElement.dispatchEvent(new PointerEvent('pointerdown', 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));
+            }
+        });
     }
 
-    private async _onPointerUp(event: PointerEvent) {
+    private _onPointerUp(event: PointerEvent) {
         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
+        // 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 entityElement = this._elementWithListener(node, 'pointerup');
-        if (entityElement) {
-            entityElement.dispatchEvent(new PointerEvent('pointerup', event));
-        }
-    }
+        const pick = this._pickNode(event);
 
-    private _onPointerListenerAdded(type: string) {
-        if (!this._hasPointerListeners[type] && this._canvas) {
-            this._hasPointerListeners[type] = true;
-
-            // For enter/leave events, we need the move handler
-            const handler =
-                type === 'pointerenter' || type === 'pointerleave'
-                    ? this._pointerHandlers.pointermove
-                    : this._pointerHandlers[type];
-
-            if (handler) {
-                this._canvas.addEventListener(
-                    type === 'pointerenter' || type === 'pointerleave' ? 'pointermove' : type,
-                    handler
-                );
-            }
-        }
-    }
+        this._chainDispatch(async () => {
+            const node = await pick;
+            if (!this._picker) return; // the element disconnected while the pick was in flight
 
-    private _onPointerListenerRemoved(type: string) {
-        const hasListeners = Array.from(
-            this.querySelectorAll<EntityBaseElement>('pc-entity, pc-model, pc-node')
-        ).some((entity) => entity._hasListeners(type));
+            const entityElement = this._elementWithListener(node, 'pointerup');
+            if (entityElement) {
+                entityElement.dispatchEvent(new PointerEvent('pointerup', event));
+            }
+        });
 
-        if (!hasListeners && this._canvas) {
-            this._hasPointerListeners[type] = false;
+        // 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);
+            }
+        });
+    }
 
-            const handler =
-                type === 'pointerenter' || type === 'pointerleave'
-                    ? this._pointerHandlers.pointermove
-                    : this._pointerHandlers[type];
+    /**
+     * Attaches exactly the canvas listeners the tree's current element listeners need, and
+     * detaches the rest. Recomputed whenever a listener connects or disconnects anywhere under
+     * this element: several synthesized types can need the same canvas listener (enter, leave
+     * and move all ride the move pick; click rides the down/up pair), so one type's removal
+     * must not detach a listener another type still uses. Re-attaching an attached listener is
+     * a no-op by EventTarget semantics, so no attach state is kept.
+     */
+    private _syncCanvasListeners() {
+        const canvas = this._canvas;
+        if (!canvas) return; // not booted yet: _pickerCreate syncs once the handlers exist
 
-            if (handler) {
-                this._canvas.removeEventListener(
-                    type === 'pointerenter' || type === 'pointerleave' ? 'pointermove' : type,
-                    handler
-                );
+        const elements = Array.from(this.querySelectorAll<EntityBaseElement>('pc-entity, pc-model, pc-node'));
+        const needed = new Set<string>();
+        for (const type of SYNTHESIZED_EVENTS) {
+            if (elements.some((element) => element._hasListeners(type))) {
+                canvasEventsFor[type].forEach((canvasType) => needed.add(canvasType));
             }
         }
+        this._clickListened = elements.some((element) => element._hasListeners('click'));
+
+        Object.entries(this._pointerHandlers).forEach(([canvasType, handler]) => {
+            if (!handler) return;
+            if (needed.has(canvasType)) {
+                canvas.addEventListener(canvasType, handler);
+            } else {
+                canvas.removeEventListener(canvasType, handler);
+            }
+        });
     }
 
     /**

package/src/components/anim-clip.ts

@@ -25,8 +25,6 @@ import { AnimComponentElement } from './anim-component';
  * @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 {
     /**

package/src/components/button-component.ts

@@ -2,7 +2,7 @@ import type { ButtonComponent } from 'playcanvas';
 import { BUTTON_TRANSITION_MODE_SPRITE_CHANGE, BUTTON_TRANSITION_MODE_TINT, Color, Vec4 } from 'playcanvas';
 
 import { useAsset } from '../asset';
-import { getEntity, parseBool, parseColor, parseEnum, parseNumber, parseVec4 } from '../parse';
+import { parseBool, parseColor, parseEnum, parseNumber, parseVec4, resolveEntity } from '../parse';
 
 import { ComponentElement } from './component';
 
@@ -76,7 +76,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;
         }
@@ -127,22 +129,28 @@ class ButtonComponentElement extends ComponentElement {
     }
 
     /**
-     * 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: string) {
         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() {

package/src/components/joint-component.ts

@@ -1,7 +1,7 @@
 import type { JointComponent } from 'playcanvas';
 import { Vec2, Vec3 } from 'playcanvas';
 
-import { getEntity, parseBool, parseEnum, parseNumber, parseVec2, parseVec3 } from '../parse';
+import { parseBool, parseEnum, parseNumber, parseVec2, parseVec3, resolveEntity } from '../parse';
 
 import { ComponentElement } from './component';
 
@@ -25,7 +25,12 @@ export type MotionMode = 'locked' | 'limited' | 'free';
  * 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
@@ -210,8 +215,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,
@@ -495,20 +500,24 @@ class JointComponentElement extends ComponentElement {
     }
 
     /**
-     * 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: string) {
         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() {
@@ -516,21 +525,26 @@ class JointComponentElement extends ComponentElement {
     }
 
     /**
-     * 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: string) {
         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() {

package/src/components/script-component.ts

@@ -3,7 +3,9 @@ import { Color, Quat, Vec2, Vec3, Vec4 } from 'playcanvas';
 
 import { useAsset } from '../asset';
 import {
+    findEntityElement,
     getEntity,
+    idHint,
     parseBool,
     parseColor,
     parseComponents,
@@ -11,7 +13,8 @@ import {
     parseQuat,
     parseVec2,
     parseVec3,
-    parseVec4
+    parseVec4,
+    unresolvedCause
 } from '../parse';
 
 import { ComponentElement } from './component';
@@ -107,10 +110,11 @@ const camelToKebab = (name: string): string => {
 
 /**
  * A conversion applied to a script attribute value carrying an explicit type prefix. Receives the
- * text after the prefix plus the raw value, and returns the raw value (having warned) when it
- * cannot resolve or parse it — callers rely on that identity to tell failure from success.
+ * text after the prefix, the raw value, and the element the value is declared under — which
+ * scopes entity references — and returns the raw value (having warned) when it cannot resolve or
+ * parse it — callers rely on that identity to tell failure from success.
  */
-type Conversion = (rest: string, raw: string) => any;
+type Conversion = (rest: string, raw: string, from: Element) => any;
 
 /**
  * Resolves an `asset:` prefix to the Asset created by the `pc-asset` element with that id.
@@ -128,18 +132,25 @@ const assetConversion: Conversion = (rest, 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: Conversion = (rest, raw) => {
-    const entity = getEntity(rest);
+const entityConversion: Conversion = (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;
 };
 
@@ -298,8 +309,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)
@@ -313,7 +326,7 @@ class ScriptComponentElement extends ComponentElement {
     private convertAttributes(item: any): any {
         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)) {