@playcanvas/web-components 0.19.0 → 0.21.0

package/dist/pwc.cjs

@@ -586,9 +586,6 @@ const CSS_COLORS = {
  *   shared frozen constants (`Vec3.ZERO`, `Color.WHITE`) as defaults.
  * - `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.
  */
 /**
  * Splits an attribute value into exactly `count` numeric components. Returns `null` when the
@@ -834,34 +831,10 @@ const parseVec4 = (value, defaultValue, attribute) => {
     }
     return new playcanvas.Vec4(components);
 };
-/**
- * Resolves a reference string to the {@link Entity} backing a `<pc-entity>` element. The reference
- * can be a CSS selector (e.g. `#my-id`, `pc-entity[name="Foo"]`), a bare element id, or a bare
- * entity name. Returns `null` if no matching element (or backing entity) is found.
- *
- * @param ref - The reference string to resolve.
- * @returns The resolved entity, or `null`.
- * @internal
- */
-const getEntity = (ref) => {
-    if (!ref) {
-        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.
-    try {
-        element = document.querySelector(ref);
-    }
-    catch {
-        element = null;
-    }
-    if (!element) {
-        element = document.getElementById(ref) ?? document.querySelector(`pc-entity[name="${ref}"]`);
-    }
-    return element?.entity ?? null;
-};
 
+// Keep `export` on these declarations. TypeScript removes the declaration and its inline export
+// when `stripInternal` is enabled. A separate `export { ... }` statement would remain in the
+// generated .d.ts file and refer to a declaration that had been removed.
 /**
  * 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
@@ -905,8 +878,428 @@ const commonAncestor = (a, b) => {
             return node;
         }
     }
-    return null;
-};
+    return null;
+};
+/**
+ * The pointer-input subsystem of a `<pc-app>` element: it owns the engine {@link Picker}, the
+ * canvas pointer handlers, and everything between them - mapping browser coordinates into the
+ * drawing buffer, selecting the camera, resolving picked nodes to listening elements, tracking
+ * hover, and dispatching the synthesized pointer and click events in canvas-event order.
+ *
+ * The host drives a small lifecycle: {@link connect} once the application and canvas exist,
+ * {@link resize} when the drawing buffer changes size, {@link syncListeners} when a descendant's
+ * pointer listeners change, and {@link disconnect} on teardown. Everything else is internal.
+ *
+ * @internal
+ */
+class PointerController {
+    _host;
+    /**
+     * Incremented by every connect and disconnect. Async work captures the value when it starts
+     * and stops if it has moved on - so a pick or dispatch belonging to an earlier connection
+     * can neither keep reading through its destroyed picker nor deliver into a later
+     * connection. The field null checks alone cannot tell the two apart once a reconnect has
+     * repopulated them.
+     */
+    _generation = 0;
+    _app = null;
+    _canvas = null;
+    _picker = null;
+    _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,
+        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 syncListeners. */
+    _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 disconnect, so a
+     * pick that never resolves cannot stall the dispatches of a later boot.
+     */
+    _dispatchChain = Promise.resolve();
+    /**
+     * @param host - The services the controller reads from its host element.
+     */
+    constructor(host) {
+        this._host = host;
+    }
+    /**
+     * Creates the picker and the canvas handlers for a booted application, and attaches whatever
+     * canvas listeners the tree's current element listeners already need (handlers created from
+     * inline attributes when their elements were first upgraded, or listeners carried over from
+     * before a re-boot).
+     *
+     * @param app - The application to pick against.
+     * @param canvas - The canvas the application renders into.
+     */
+    connect(app, canvas) {
+        this._generation++;
+        this._app = app;
+        this._canvas = canvas;
+        const { width, height } = app.graphicsDevice;
+        this._picker = new playcanvas.Picker(app, width, height);
+        // 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);
+            };
+        };
+        this._pointerHandlers.pointermove = listener(this._onPointerMove);
+        this._pointerHandlers.pointerdown = listener(this._onPointerDown);
+        this._pointerHandlers.pointerup = listener(this._onPointerUp);
+        this._pointerHandlers.pointercancel = (event) => {
+            this._downPicks.delete(event.pointerId);
+        };
+        this.syncListeners();
+    }
+    /**
+     * Detaches the canvas listeners and drops every piece of pointer state, so nothing picked or
+     * queued before the teardown can affect a later boot. Safe to call on a controller that was
+     * never connected.
+     */
+    disconnect() {
+        this._generation++;
+        if (this._canvas) {
+            Object.entries(this._pointerHandlers).forEach(([type, handler]) => {
+                if (handler) {
+                    this._canvas.removeEventListener(type, handler);
+                }
+            });
+        }
+        this._app = null;
+        this._canvas = null;
+        this._picker = null;
+        this._hoveredEntity = null;
+        this._pointerHandlers = {
+            pointermove: null,
+            pointerdown: null,
+            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();
+    }
+    /**
+     * Resizes the picker to the drawing buffer. The picker must track the buffer, or picks would
+     * land at stale coordinates after a resize.
+     *
+     * @param width - The drawing buffer width.
+     * @param height - The drawing buffer height.
+     */
+    resize(width, height) {
+        this._picker?.resize(width, height);
+    }
+    /**
+     * Attaches exactly the canvas listeners the tree's current element listeners need, and
+     * detaches the rest. Called whenever a listener connects or disconnects anywhere under the
+     * host 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. Does nothing before
+     * {@link connect} - connecting syncs once the handlers exist.
+     */
+    syncListeners() {
+        const canvas = this._canvas;
+        if (!canvas)
+            return;
+        const elements = this._host.pointerTargets();
+        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);
+            }
+        });
+    }
+    /**
+     * Resolves the element that owns hover for a picked node: the nearest node up the parent
+     * chain - starting with the node itself - whose element listens for any of the hover event
+     * types. Skipping silent elements matches {@link _elementWithListener}, so a registered
+     * element with no hover listeners (a `<pc-model>` host, a plain child entity) is transparent
+     * to hover rather than swallowing a listening ancestor's enter/leave pair.
+     *
+     * @param node - The picked node, or `null`.
+     * @returns The hover-owning element, or `null`.
+     */
+    _hoverTarget(node) {
+        while (node !== null) {
+            const element = this._host.elementFromNode(node);
+            if (element && hoverEventTypes.some((type) => element._hasListeners(type))) {
+                return element;
+            }
+            node = node.parent;
+        }
+        return null;
+    }
+    /**
+     * Like {@link _hoverTarget}, but for one event type: skips elements without a listener for
+     * `type`, so a hit on an unlistened child still reaches a listening ancestor.
+     *
+     * @param node - The picked node, or `null`.
+     * @param type - The pointer event type a listener is required for.
+     * @returns The nearest listening element, or `null`.
+     */
+    _elementWithListener(node, type) {
+        while (node !== null) {
+            const element = this._host.elementFromNode(node);
+            if (element?._hasListeners(type)) {
+                return element;
+            }
+            node = node.parent;
+        }
+        return null;
+    }
+    /**
+     * Converts a pointer event's client coordinates into drawing-buffer coordinates - the space
+     * the pick buffer and the camera viewports are laid out in. When the canvas has no CSS box
+     * to map through (jsdom; a hidden canvas receives no pointer events in a browser), the
+     * client coordinates are passed through unmapped and `mapped` is false, so callers know the
+     * coordinates correspond to no real geometry.
+     *
+     * @param event - The pointer event to convert.
+     * @param canvas - The canvas the event was dispatched on.
+     * @returns The buffer-space coordinates, and whether they were actually mapped.
+     */
+    _getPickerCoordinates(event, canvas) {
+        const canvasRect = canvas.getBoundingClientRect();
+        if (canvasRect.width === 0 || canvasRect.height === 0) {
+            return { x: event.clientX, y: event.clientY, mapped: false };
+        }
+        const scaleX = canvas.width / canvasRect.width;
+        const scaleY = canvas.height / canvasRect.height;
+        return {
+            x: (event.clientX - canvasRect.left) * scaleX,
+            y: (event.clientY - canvasRect.top) * scaleY,
+            mapped: true
+        };
+    }
+    /**
+     * Whether a camera's viewport contains the point. A camera renders into its normalized
+     * `rect`, whose origin is the bottom-left of the canvas while buffer coordinates run from
+     * the top-left - so the vertical test flips, as the engine's ElementInput flips it for UI
+     * input. The right and bottom edges are exclusive: a viewport rasterizes the half-open
+     * pixel range [left, right) x [top, bottom), so a coordinate on a shared edge belongs to
+     * the viewport whose first pixel it is - never to the one it just left, whose pick buffer
+     * holds nothing there.
+     *
+     * @param camera - The camera to test.
+     * @param x - The x coordinate, in buffer space.
+     * @param y - The y coordinate, in buffer space.
+     * @param canvas - The canvas the coordinates are relative to.
+     * @returns Whether the camera's viewport contains the point.
+     */
+    _cameraContains(camera, x, y, canvas) {
+        const rect = camera.rect;
+        const left = rect.x * canvas.width;
+        const bottom = (1 - rect.y) * canvas.height;
+        const top = bottom - rect.w * canvas.height;
+        return x >= left && x < left + rect.z * canvas.width && y >= top && y < bottom;
+    }
+    /**
+     * Picks the scene under the pointer and returns the graph node that was hit, or `null`.
+     *
+     * The camera is resolved the way the engine's ElementInput resolves it for UI input:
+     * enabled cameras are tried topmost-first (they render in ascending `priority` order),
+     * skipping cameras that render to a texture and cameras whose viewport `rect` does not
+     * contain the pointer. A camera that picks nothing ends the search if it clears the color
+     * buffer - its background visually owns the pixel - and otherwise cedes to the cameras
+     * beneath it, so an overlay camera only intercepts picks where it actually drew something.
+     * The pick buffer is prepared per camera, so each camera picks from its own layers.
+     *
+     * The read back is asynchronous because the synchronous {@link Picker.getSelection} is not
+     * supported on WebGPU, where it returns an empty selection rather than failing - which
+     * silently disabled every `onpointer*` handler once WebGPU became the resolved backend. The
+     * async variant works on both backends and does not block the main thread on a GPU read.
+     *
+     * @param event - The pointer event to pick under.
+     * @returns The graph node under the pointer, or `null` if nothing was hit.
+     */
+    async _pickNode(event) {
+        const generation = this._generation;
+        const app = this._app;
+        const picker = this._picker;
+        const canvas = this._canvas;
+        if (!app || !picker || !canvas)
+            return null;
+        const { x, y, mapped } = this._getPickerCoordinates(event, canvas);
+        // Walked from the end: the array is sorted by ascending priority, so the last camera
+        // renders last and sits on top. Read through .at() because a pick handler may remove
+        // cameras while an earlier iteration's read back is in flight.
+        const cameras = app.systems.camera?.cameras ?? [];
+        for (let i = cameras.length - 1; i >= 0; i--) {
+            const camera = cameras.at(i);
+            // A camera rendering to a texture is not on the canvas.
+            if (!camera || camera.renderTarget)
+                continue;
+            // Coordinates that could not be mapped cannot be tested for containment.
+            if (mapped && !this._cameraContains(camera, x, y, canvas))
+                continue;
+            picker.prepare(camera, app.scene);
+            const selection = await picker.getSelectionAsync(x, y);
+            // The host may have disconnected - or disconnected and reconnected - while the read
+            // back was in flight. Either way this pick's connection is gone.
+            if (generation !== this._generation)
+                return null;
+            if (selection.length > 0) {
+                const item = selection[0];
+                return item instanceof playcanvas.MeshInstance ? item.node : item.entity;
+            }
+            // Nothing hit. A camera that clears the color buffer paints its background over
+            // everything beneath it, so the miss is final; one that does not is an overlay
+            // that the cameras beneath show through, so they get their turn.
+            if (camera.clearColorBuffer)
+                return null;
+        }
+        return null;
+    }
+    async _onPointerMove(event) {
+        if (!this._picker || !this._app)
+            return;
+        // Moves arrive faster than a pick resolves, so results can land out of order. Only the
+        // newest pick may update the hover state - an older one describes a pointer position the
+        // user has already left, and one from an earlier connection describes a scene that no
+        // longer exists.
+        const generation = this._generation;
+        const token = ++this._pickToken;
+        const node = await this._pickNode(event);
+        if (token !== this._pickToken || generation !== this._generation)
+            return;
+        // The hovered element is the nearest one up the node's parent chain with a hover
+        // listener - the nearest-listener rule down/up use. Dispatch is still gated per event
+        // type below: having any hover listener selects the target, each event needs its own.
+        const newHoverEntity = this._hoverTarget(node);
+        // Handle enter/leave events
+        if (this._hoveredEntity !== newHoverEntity) {
+            if (this._hoveredEntity && this._hoveredEntity._hasListeners('pointerleave')) {
+                this._hoveredEntity.dispatchEvent(new PointerEvent('pointerleave', event));
+            }
+            if (newHoverEntity && newHoverEntity._hasListeners('pointerenter')) {
+                newHoverEntity.dispatchEvent(new PointerEvent('pointerenter', event));
+            }
+        }
+        // Update hover state
+        this._hoveredEntity = newHoverEntity;
+        // Handle pointermove event
+        if (newHoverEntity && newHoverEntity._hasListeners('pointermove')) {
+            newHoverEntity.dispatchEvent(new PointerEvent('pointermove', 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 generation = this._generation;
+        // 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 (generation !== this._generation)
+                return; // this press's connection is gone
+            const entityElement = this._elementWithListener(node, 'pointerdown');
+            if (entityElement) {
+                entityElement.dispatchEvent(new PointerEvent('pointerdown', event));
+            }
+        });
+    }
+    _onPointerUp(event) {
+        if (!this._picker || !this._app)
+            return;
+        const generation = this._generation;
+        // 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 (generation !== this._generation)
+                return; // this release's connection is gone
+            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 || generation !== this._generation)
+                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);
+            }
+        });
+    }
+}
+
 /**
  * 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
@@ -990,31 +1383,16 @@ class AppElement extends AsyncElement {
      * engine scene nodes back to their owning elements by identity - never by name.
      */
     _entityElements = new Map();
-    _picker = null;
-    _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,
-        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.
+     * The pointer-input subsystem: the picker, the canvas handlers, and the synthesized-event
+     * dispatch. The element drives its lifecycle (connect on boot, resize with the drawing
+     * buffer, listener syncs, disconnect on teardown) and hands it the two lookups it needs -
+     * everything else about pointer input lives in the controller.
      */
-    _lastClick = null;
+    _pointer = new PointerController({
+        elementFromNode: (node) => this._entityElements.get(node) ?? null,
+        pointerTargets: () => Array.from(this.querySelectorAll('pc-entity, pc-model, pc-node'))
+    });
     _app = null;
     _loadProgress = 0;
     /**
@@ -1053,8 +1431,8 @@ class AppElement extends AsyncElement {
         // 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());
+            this.addEventListener(`${type}:connect`, () => this._pointer.syncListeners());
+            this.addEventListener(`${type}:disconnect`, () => this._pointer.syncListeners());
         });
     }
     async connectedCallback() {
@@ -1228,7 +1606,7 @@ class AppElement extends AsyncElement {
         // from the canvas's client size
         app.setCanvasFillMode(playcanvas.FILLMODE_NONE);
         app.setCanvasResolution(playcanvas.RESOLUTION_AUTO);
-        this._pickerCreate();
+        this._pointer.connect(app, this._canvas);
         // Track the element's box rather than the window: containers resize without any window
         // event (splitter drags, flex reflow, animations). Guarded because jsdom has no
         // ResizeObserver - there, the resolution set above is the only sizing that happens.
@@ -1320,7 +1698,7 @@ class AppElement extends AsyncElement {
         // instead of completing against a torn-down element.
         this._bootGeneration++;
         this._optionsLocked = false;
-        this._pickerDestroy();
+        this._pointer.disconnect();
         // Clean up the application. Destroying it destroys every entity, whose destroy hooks
         // unregister them - clear() covers any entity the engine no longer reached.
         if (this._app) {
@@ -1356,49 +1734,7 @@ class AppElement extends AsyncElement {
         }
         this.app.updateCanvasSize();
         const { width, height } = this.app.graphicsDevice;
-        this._picker?.resize(width, height);
-    }
-    _pickerCreate() {
-        const { width, height } = this.app.graphicsDevice;
-        this._picker = new playcanvas.Picker(this.app, width, height);
-        // Create bound handlers but don't attach them yet. The handlers pick asynchronously, so
-        // each is wrapped to discard the promise - a listener must not return one, and nothing
-        // awaits the result.
-        const listener = (handler) => {
-            return (event) => {
-                handler.call(this, event);
-            };
-        };
-        this._pointerHandlers.pointermove = listener(this._onPointerMove);
-        this._pointerHandlers.pointerdown = listener(this._onPointerDown);
-        this._pointerHandlers.pointerup = listener(this._onPointerUp);
-        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)
-        this._syncCanvasListeners();
-    }
-    _pickerDestroy() {
-        if (this._canvas) {
-            Object.entries(this._pointerHandlers).forEach(([type, handler]) => {
-                if (handler) {
-                    this._canvas.removeEventListener(type, handler);
-                }
-            });
-        }
-        this._picker = null;
-        this._hoveredEntity = null;
-        this._pointerHandlers = {
-            pointermove: null,
-            pointerdown: null,
-            pointerup: null,
-            pointercancel: null
-        };
-        this._downPicks.clear();
-        this._clickListened = false;
-        this._lastClick = null;
+        this._pointer.resize(width, height);
     }
     /**
      * Registers the element that fronts an entity. Called by EntityElement when it creates its
@@ -1426,268 +1762,11 @@ class AppElement extends AsyncElement {
      * example, an unbound node inside a model's instantiated hierarchy, or an entity created
      * through the engine API.
      *
-     * @param entity - The entity to look up.
-     * @returns The element fronting the entity, or `null`.
-     */
-    elementFromEntity(entity) {
-        return this._entityElements.get(entity) ?? null;
-    }
-    /**
-     * Resolves the element that owns hover for a picked node: the nearest node up the parent
-     * chain - starting with the node itself - whose element listens for any of the hover event
-     * types. Skipping silent elements matches {@link _elementWithListener}, so a registered
-     * element with no hover listeners (a `<pc-model>` host, a plain child entity) is transparent
-     * to hover rather than swallowing a listening ancestor's enter/leave pair.
-     *
-     * @param node - The picked node, or `null`.
-     * @returns The hover-owning element, or `null`.
-     */
-    _hoverTarget(node) {
-        while (node !== null) {
-            const element = this._entityElements.get(node);
-            if (element && hoverEventTypes.some((type) => element._hasListeners(type))) {
-                return element;
-            }
-            node = node.parent;
-        }
-        return null;
-    }
-    /**
-     * Like {@link _elementFromNode}, but skips elements without a listener for `type`, so a hit
-     * on an unlistened child still reaches a listening ancestor.
-     *
-     * @param node - The picked node, or `null`.
-     * @param type - The pointer event type a listener is required for.
-     * @returns The nearest listening element, or `null`.
-     */
-    _elementWithListener(node, type) {
-        while (node !== null) {
-            const element = this._entityElements.get(node);
-            if (element?._hasListeners(type)) {
-                return element;
-            }
-            node = node.parent;
-        }
-        return null;
-    }
-    /**
-     * Converts a pointer event's client coordinates into drawing-buffer coordinates - the space
-     * the pick buffer and the camera viewports are laid out in. When the canvas has no CSS box
-     * to map through (jsdom; a hidden canvas receives no pointer events in a browser), the
-     * client coordinates are passed through unmapped and `mapped` is false, so callers know the
-     * coordinates correspond to no real geometry.
-     *
-     * @param event - The pointer event to convert.
-     * @param canvas - The canvas the event was dispatched on.
-     * @returns The buffer-space coordinates, and whether they were actually mapped.
-     */
-    _getPickerCoordinates(event, canvas) {
-        const canvasRect = canvas.getBoundingClientRect();
-        if (canvasRect.width === 0 || canvasRect.height === 0) {
-            return { x: event.clientX, y: event.clientY, mapped: false };
-        }
-        const scaleX = canvas.width / canvasRect.width;
-        const scaleY = canvas.height / canvasRect.height;
-        return {
-            x: (event.clientX - canvasRect.left) * scaleX,
-            y: (event.clientY - canvasRect.top) * scaleY,
-            mapped: true
-        };
-    }
-    /**
-     * Whether a camera's viewport contains the point. A camera renders into its normalized
-     * `rect`, whose origin is the bottom-left of the canvas while buffer coordinates run from
-     * the top-left - so the vertical test flips, as the engine's ElementInput flips it for UI
-     * input. The right and bottom edges are exclusive: a viewport rasterizes the half-open
-     * pixel range [left, right) x [top, bottom), so a coordinate on a shared edge belongs to
-     * the viewport whose first pixel it is - never to the one it just left, whose pick buffer
-     * holds nothing there.
-     *
-     * @param camera - The camera to test.
-     * @param x - The x coordinate, in buffer space.
-     * @param y - The y coordinate, in buffer space.
-     * @param canvas - The canvas the coordinates are relative to.
-     * @returns Whether the camera's viewport contains the point.
-     */
-    _cameraContains(camera, x, y, canvas) {
-        const rect = camera.rect;
-        const left = rect.x * canvas.width;
-        const bottom = (1 - rect.y) * canvas.height;
-        const top = bottom - rect.w * canvas.height;
-        return x >= left && x < left + rect.z * canvas.width && y >= top && y < bottom;
-    }
-    /**
-     * Picks the scene under the pointer and returns the graph node that was hit, or `null`.
-     *
-     * The camera is resolved the way the engine's ElementInput resolves it for UI input:
-     * enabled cameras are tried topmost-first (they render in ascending `priority` order),
-     * skipping cameras that render to a texture and cameras whose viewport `rect` does not
-     * contain the pointer. A camera that picks nothing ends the search if it clears the color
-     * buffer - its background visually owns the pixel - and otherwise cedes to the cameras
-     * beneath it, so an overlay camera only intercepts picks where it actually drew something.
-     * The pick buffer is prepared per camera, so each camera picks from its own layers.
-     *
-     * The read back is asynchronous because the synchronous {@link Picker.getSelection} is not
-     * supported on WebGPU, where it returns an empty selection rather than failing - which
-     * silently disabled every `onpointer*` handler once WebGPU became the resolved backend. The
-     * async variant works on both backends and does not block the main thread on a GPU read.
-     *
-     * @param event - The pointer event to pick under.
-     * @returns The graph node under the pointer, or `null` if nothing was hit.
-     */
-    async _pickNode(event) {
-        const app = this.app;
-        const picker = this._picker;
-        const canvas = this._canvas;
-        if (!app || !picker || !canvas)
-            return null;
-        const { x, y, mapped } = this._getPickerCoordinates(event, canvas);
-        // Walked from the end: the array is sorted by ascending priority, so the last camera
-        // renders last and sits on top. Read through .at() because a pick handler may remove
-        // cameras while an earlier iteration's read back is in flight.
-        const cameras = app.systems.camera?.cameras ?? [];
-        for (let i = cameras.length - 1; i >= 0; i--) {
-            const camera = cameras.at(i);
-            // A camera rendering to a texture is not on the canvas.
-            if (!camera || camera.renderTarget)
-                continue;
-            // Coordinates that could not be mapped cannot be tested for containment.
-            if (mapped && !this._cameraContains(camera, x, y, canvas))
-                continue;
-            picker.prepare(camera, app.scene);
-            const selection = await picker.getSelectionAsync(x, y);
-            // The element may have disconnected while the read back was in flight.
-            if (!this._picker || !this.app)
-                return null;
-            if (selection.length > 0) {
-                const item = selection[0];
-                return item instanceof playcanvas.MeshInstance ? item.node : item.entity;
-            }
-            // Nothing hit. A camera that clears the color buffer paints its background over
-            // everything beneath it, so the miss is final; one that does not is an overlay
-            // that the cameras beneath show through, so they get their turn.
-            if (camera.clearColorBuffer)
-                return null;
-        }
-        return null;
-    }
-    async _onPointerMove(event) {
-        if (!this._picker || !this.app)
-            return;
-        // Moves arrive faster than a pick resolves, so results can land out of order. Only the
-        // newest pick may update the hover state - an older one describes a pointer position the
-        // user has already left.
-        const token = ++this._pickToken;
-        const node = await this._pickNode(event);
-        if (token !== this._pickToken || !this._picker)
-            return;
-        // The hovered element is the nearest one up the node's parent chain with a hover
-        // listener - the nearest-listener rule down/up use. Dispatch is still gated per event
-        // type below: having any hover listener selects the target, each event needs its own.
-        const newHoverEntity = this._hoverTarget(node);
-        // Handle enter/leave events
-        if (this._hoveredEntity !== newHoverEntity) {
-            if (this._hoveredEntity && this._hoveredEntity._hasListeners('pointerleave')) {
-                this._hoveredEntity.dispatchEvent(new PointerEvent('pointerleave', event));
-            }
-            if (newHoverEntity && newHoverEntity._hasListeners('pointerenter')) {
-                newHoverEntity.dispatchEvent(new PointerEvent('pointerenter', event));
-            }
-        }
-        // Update hover state
-        this._hoveredEntity = newHoverEntity;
-        // Handle pointermove event
-        if (newHoverEntity && newHoverEntity._hasListeners('pointermove')) {
-            newHoverEntity.dispatchEvent(new PointerEvent('pointermove', event));
-        }
-    }
-    async _onPointerDown(event) {
-        if (!this._picker || !this.app)
-            return;
-        const pick = this._pickNode(event);
-        // A click concludes on the matching pointerup, which needs to know what the press
-        // picked. Primary button only - the only button a click can conclude from - and only
-        // while click is listened for, since it is the click mapping that keeps the pointerup
-        // and pointercancel listeners attached to clean the entry up again.
-        if (this._clickListened && event.button === 0) {
-            this._downPicks.set(event.pointerId, pick);
-        }
-        const node = await pick;
-        if (!this._picker)
-            return; // the element disconnected while the pick was in flight
-        const entityElement = this._elementWithListener(node, 'pointerdown');
-        if (entityElement) {
-            entityElement.dispatchEvent(new PointerEvent('pointerdown', event));
-        }
-    }
-    async _onPointerUp(event) {
-        if (!this._picker || !this.app)
-            return;
-        // The press pick this release may conclude as a click. Claimed synchronously, so the
-        // entry is gone before any other event for this pointer can be handled.
-        const downPick = this._downPicks.get(event.pointerId);
-        this._downPicks.delete(event.pointerId);
-        const node = await this._pickNode(event);
-        if (!this._picker)
-            return; // the element disconnected while the pick was in flight
-        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. The press pick
-        // may still be in flight - a quick tap resolves in pick order, not event order.
-        if (!downPick || event.button !== 0)
-            return;
-        const downNode = await downPick;
-        if (!this._picker)
-            return;
-        const clickElement = this._elementWithListener(commonAncestor(downNode, node), 'click');
-        if (clickElement) {
-            const click = new PointerEvent('click', event);
-            // The init above copied pointerup's `detail`, which the Pointer Events spec fixes
-            // at 0 - but click is exempt: its detail is the click count, chained here as the
-            // platform chains it (same target, within the double-click window). Overridden
-            // with defineProperty because an event instance used as an init dict cannot have
-            // single fields replaced.
-            const time = performance.now();
-            const last = this._lastClick;
-            const count = last && last.element === clickElement && time - last.time <= CLICK_CHAIN_MS ? last.count + 1 : 1;
-            this._lastClick = { element: clickElement, time, count };
-            Object.defineProperty(click, 'detail', { value: count });
-            clickElement.dispatchEvent(click);
-        }
-    }
-    /**
-     * Attaches exactly the canvas listeners the tree's current element listeners need, and
-     * detaches the rest. Recomputed whenever a listener connects or disconnects anywhere under
-     * this element: several synthesized types can need the same canvas listener (enter, leave
-     * and move all ride the move pick; click rides the down/up pair), so one type's removal
-     * must not detach a listener another type still uses. Re-attaching an attached listener is
-     * a no-op by EventTarget semantics, so no attach state is kept.
+     * @param entity - The entity to look up.
+     * @returns The element fronting the entity, or `null`.
      */
-    _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);
-            }
-        });
+    elementFromEntity(entity) {
+        return this._entityElements.get(entity) ?? null;
     }
     /**
      * Warns that a graphics option was written too late to have any effect. These options are read
@@ -3089,6 +3168,108 @@ const useAsset = (id) => {
     return asset;
 };
 
+/**
+ * Watches the asset currently selected by an element.
+ *
+ * An element can change its asset while the old one is still loading, or disconnect before the
+ * load finishes. This class makes sure callbacks from those older loads do nothing. Calling
+ * {@link bind} stops watching the previous asset and starts watching the new one. Calling
+ * {@link cancel} stops watching altogether.
+ *
+ * Asset lookup goes through {@link useAsset}, so selecting a lazy asset starts its load. The
+ * caller still decides what to do with the result, such as creating scene content, reporting an
+ * error, or marking an element ready.
+ *
+ * Reuse one `AssetBinding` for each asset-valued property throughout the element's lifetime. It
+ * is safe for a callback to call `bind` again: the new asset remains active after the callback
+ * returns.
+ *
+ * @internal
+ */
+class AssetBinding {
+    /**
+     * Each bind or cancel gets a new number. Event handlers remember the number they were created
+     * with and return if it is no longer current. Old listeners are normally removed as well, but
+     * this check also protects against an event that was already in progress when removal
+     * happened.
+     */
+    _generation = 0;
+    _loadHandle = null;
+    _errorHandle = null;
+    _detach() {
+        this._loadHandle?.off();
+        this._loadHandle = null;
+        this._errorHandle?.off();
+        this._errorHandle = null;
+    }
+    /**
+     * Stops watching the current asset and prevents its callbacks from running. The binding can
+     * be used again by calling {@link bind}.
+     */
+    cancel() {
+        this._generation++;
+        this._detach();
+    }
+    /**
+     * Starts watching the asset registered under `id` and stops watching the previous one. A
+     * missing `id` still clears the previous binding. Looking up a lazy asset starts its load.
+     *
+     * If the asset has already loaded successfully, `load` runs before this method returns. An
+     * earlier failure calls `error` immediately when that callback is provided; without one, the
+     * binding waits for a later successful reload. Assets still loading are watched for the same
+     * two outcomes. Once an event is handled, both listeners are removed.
+     *
+     * @param id - The `id` of the `<pc-asset>` element to bind to.
+     * @param callbacks - Functions to call when loading succeeds or fails.
+     * @returns The selected asset, or `undefined` if no asset has this `id`. The caller decides
+     * how to handle a missing asset.
+     */
+    bind(id, callbacks) {
+        const generation = ++this._generation;
+        this._detach();
+        const asset = useAsset(id);
+        if (!asset) {
+            return undefined;
+        }
+        const { error } = callbacks;
+        if (asset.loaded) {
+            // PlayCanvas sets `loaded` after both success and failure, so a resource must also be
+            // present before this counts as success. Use `!= null` deliberately: `undefined` and
+            // `null` both mean there is no resource, while a valid resource can still be falsy
+            // (for example, an empty text file produces '').
+            if (asset.resource != null) {
+                callbacks.load(asset);
+                return asset;
+            }
+            if (error) {
+                error(`asset '${id}' failed to load`);
+                return asset;
+            }
+        }
+        // Old listeners are normally removed by bind or cancel. The number check is a second
+        // safeguard for a late event. Check it before _detach so an old callback cannot remove
+        // the listeners for the current asset. Whichever current event runs first removes both
+        // listeners.
+        this._loadHandle = asset.once('load', () => {
+            if (generation !== this._generation) {
+                return;
+            }
+            this._detach();
+            callbacks.load(asset);
+        });
+        if (error) {
+            this._errorHandle = asset.once('error', (err) => {
+                if (generation !== this._generation) {
+                    return;
+                }
+                this._detach();
+                error(err);
+            });
+        }
+        return asset;
+    }
+}
+
 /**
  * Formats one line of the printable hierarchy: the node's name, an `[index]` marker when the
  * name is shared by several nodes in the model, the attached component types, and the material
@@ -3189,18 +3370,18 @@ class ModelElement extends EntityOwnerElement {
     _contentEntity = null;
     /**
      * Incremented on every new load, on disconnect, and when the host entity dies, and captured
-     * by a load when it starts. A load that resumes from an await or a load callback abandons
-     * itself if the value has moved on, so a superseded load can neither instantiate a second
-     * content root nor parent one under a host a newer cycle has already replaced.
+     * by a load when it starts. A load that resumes from an await abandons itself if the value
+     * has moved on, so a superseded load can neither instantiate a second content root nor
+     * parent one under a host a newer cycle has already replaced. The asset subscription itself
+     * is guarded by the binding below.
      */
     _loadGeneration = 0;
     /**
-     * The pending asset subscriptions of the current load, if it is waiting for its asset. Held
-     * so that whatever supersedes the load can detach the handlers from the asset, rather than
-     * leave them registered until the asset settles (or forever, if it never does).
+     * The subscription to the current container asset while it is loading. Whatever supersedes
+     * the load — a newer load, a disconnect, the host dying — cancels it, so the asset settling
+     * later cannot deliver to a load that no longer owns the element.
      */
-    _loadHandle = null;
-    _errorHandle = null;
+    _binding = new AssetBinding();
     /**
      * The root entity of the instantiated model content, parented beneath the host entity.
      * `null` until the container asset has loaded and been instantiated, after a failed load,
@@ -3291,7 +3472,7 @@ class ModelElement extends EntityOwnerElement {
         // resets the element. The generation guard comes first so a load suspended on an await
         // cannot resume against the torn-down element.
         this._loadGeneration++;
-        this._detachLoadHandlers();
+        this._binding.cancel();
         this._entity?.destroy();
     }
     /**
@@ -3310,16 +3491,10 @@ class ModelElement extends EntityOwnerElement {
      */
     _onEntityDestroy(entity) {
         this._loadGeneration++;
-        this._detachLoadHandlers();
+        this._binding.cancel();
         this._contentEntity = null;
         super._onEntityDestroy(entity);
     }
-    _detachLoadHandlers() {
-        this._loadHandle?.off();
-        this._loadHandle = null;
-        this._errorHandle?.off();
-        this._errorHandle = null;
-    }
     /**
      * Resolves readiness and dispatches the `load` event. Called once the instantiated content
      * has been parented beneath the host — the host itself is already in the scene graph by
@@ -3346,7 +3521,7 @@ class ModelElement extends EntityOwnerElement {
         this._destroyContent();
         // Supersede any load already in flight - only the newest load may instantiate
         const generation = ++this._loadGeneration;
-        this._detachLoadHandlers();
+        this._binding.cancel();
         // Re-arm readiness so a waiter obtained after an asset change resolves against the new
         // content. A no-op on first connection, where readiness is still pending.
         this._resetReady();
@@ -3372,39 +3547,23 @@ class ModelElement extends EntityOwnerElement {
             this._onReady();
             return;
         }
-        const asset = useAsset(this._asset);
-        if (!asset) {
-            // A non-empty id that resolves to nothing is a dead end - say so rather than staying
-            // silently pending.
-            console.warn(`pc-model could not find asset '${this._asset}' - model not created`);
-            return;
-        }
-        if (asset.loaded) {
-            this._instantiate(asset.resource);
-        }
-        else {
-            // The generation is re-checked even though a superseded handler is detached: the
-            // detach relies on how the engine's event emitter treats removal, while the check
-            // holds on its own. Whichever of load/error fires first detaches the other.
-            this._loadHandle = asset.once('load', () => {
-                this._detachLoadHandlers();
-                if (generation !== this._loadGeneration) {
-                    return;
-                }
-                this._instantiate(asset.resource);
-            });
-            this._errorHandle = asset.once('error', (err) => {
-                this._detachLoadHandlers();
-                if (generation !== this._loadGeneration) {
-                    return;
-                }
+        // Every path that moves _loadGeneration also rebinds or cancels the binding, so a
+        // delivery below is always current - no generation re-check needed in the callbacks.
+        const asset = this._binding.bind(this._asset, {
+            load: ({ resource }) => this._instantiate(resource),
+            error: (err) => {
                 // A failed load settles readiness with a null contentEntity, mirroring pc-asset:
                 // readiness means the load settled, not that it succeeded.
                 this.dispatchEvent(new ErrorEvent('error', {
                     message: err instanceof Error ? err.message : String(err)
                 }));
                 this._onReady();
-            });
+            }
+        });
+        if (!asset) {
+            // A non-empty id that resolves to nothing is a dead end - say so rather than staying
+            // silently pending.
+            console.warn(`pc-model could not find asset '${this._asset}' - model not created`);
         }
     }
     /**
@@ -3539,6 +3698,8 @@ class ComponentElement extends AsyncElement {
             console.warn(`${this.tagName.toLowerCase()}${label} - '${entity.name}' already has a '${this._componentName}' component - component not added`);
             return;
         }
+        // The name passed by the subclass selects the engine system that creates its T - a
+        // pairing the type system cannot express, so it is asserted this once
         this._component = entity.addComponent(this._componentName, this.getInitialComponentData());
     }
     async _addComponent() {
@@ -3801,6 +3962,9 @@ class AnimComponentElement extends ComponentElement {
      */
     _applyRootBone() {
         const component = this.component;
+        if (!component) {
+            return;
+        }
         // A non-null root this element did not assign came through the engine API. A fresh
         // component starts at null, which is always reclaimable.
         if (component.rootBone !== null && component.rootBone !== this._managedRootBone) {
@@ -3873,7 +4037,7 @@ class AnimComponentElement extends ComponentElement {
      * declared `clip` selection can apply before any asset has loaded.
      */
     _assignClip(clip) {
-        this.component.assignAnimation(clip.name, clip._track ?? playcanvas.AnimTrack.EMPTY, undefined, clip.speed, clip.loop);
+        this.component?.assignAnimation(clip.name, clip._track ?? playcanvas.AnimTrack.EMPTY, undefined, clip.speed, clip.loop);
     }
     /**
      * Validates a clip child and, when valid, assigns its state and starts its track resolution.
@@ -4181,8 +4345,9 @@ class AnimComponentElement extends ComponentElement {
         component.playing = true;
     }
     /**
-     * Gets the underlying PlayCanvas anim component.
-     * @returns The anim component.
+     * Gets the underlying PlayCanvas anim component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The anim component, or `null`.
      */
     get component() {
         return super.component;
@@ -4331,6 +4496,11 @@ class AnimClipElement extends AsyncElement {
      */
     _animElement = null;
     _asset = '';
+    /**
+     * Watches the current source asset while it loads. Starting a new resolution or
+     * disconnecting cancels it, so a superseded source can never hand its track to the parent.
+     */
+    _binding = new AssetBinding();
     /**
      * Incremented on every connect and disconnect, and captured by connectedCallback on entry —
      * a resume from an await abandons itself if the value has moved on, so a stale callback can
@@ -4338,19 +4508,13 @@ class AnimClipElement extends AsyncElement {
      * own callback.
      */
     _connectionGeneration = 0;
-    _errorHandle = null;
     /**
      * Incremented on every track resolution and on disconnect, and captured by a resolution when
-     * it starts. A resolution that resumes from an await or an asset callback abandons itself if
-     * the value has moved on, so a superseded resolution cannot hand a stale track to the parent.
+     * it starts. A resolution that resumes from an await abandons itself if the value has moved
+     * on, so a superseded resolution cannot hand a stale track to the parent. The asset
+     * subscription itself is guarded by the binding above.
      */
     _loadGeneration = 0;
-    /**
-     * The pending asset subscriptions of the current resolution, if it is waiting for its asset.
-     * Held so that whatever supersedes the resolution can detach the handlers from the asset,
-     * rather than leave them registered until the asset settles (or forever, if it never does).
-     */
-    _loadHandle = null;
     _loop = true;
     _name = '';
     _speed = 1;
@@ -4390,7 +4554,7 @@ class AnimClipElement extends AsyncElement {
         // Invalidate any connectedCallback or track resolution still suspended on an await
         this._connectionGeneration++;
         this._loadGeneration++;
-        this._detachLoadHandlers();
+        this._binding.cancel();
         // Uses the cached parent rather than a fresh lookup, since parentElement is already null
         // by now. The component itself is null if the whole <pc-app> is being torn down —
         // parents disconnect first and have already removed the component.
@@ -4408,12 +4572,6 @@ class AnimClipElement extends AsyncElement {
         }
         return animElement;
     }
-    _detachLoadHandlers() {
-        this._loadHandle?.off();
-        this._loadHandle = null;
-        this._errorHandle?.off();
-        this._errorHandle = null;
-    }
     /**
      * Reports a name-validation failure from the owning `<pc-anim>`, once per name value.
      *
@@ -4439,34 +4597,19 @@ class AnimClipElement extends AsyncElement {
     async _resolveTrack(animElement) {
         this._animElement = animElement;
         const generation = ++this._loadGeneration;
-        this._detachLoadHandlers();
+        this._binding.cancel();
         if (this._asset) {
-            const asset = useAsset(this._asset);
+            // Every path that moves _loadGeneration also rebinds or cancels the binding, so a
+            // delivery below is always current.
+            const asset = this._binding.bind(this._asset, {
+                load: (loaded) => this._extractTrack(loaded, `asset '${this._asset}'`),
+                error: () => {
+                    this._warnSource(`pc-anim-clip '${this._name}' - asset '${this._asset}' failed to load - clip not assigned`);
+                }
+            });
             if (!asset) {
                 this._warnSource(`pc-anim-clip '${this._name}' could not find asset '${this._asset}' - clip not assigned`);
-                return;
-            }
-            if (asset.loaded) {
-                this._extractTrack(asset, `asset '${this._asset}'`);
-                return;
             }
-            // Whichever of load/error fires first detaches the other. The generation is
-            // re-checked even though a superseded handler is detached: the detach relies on how
-            // the engine's event emitter treats removal, while the check holds on its own.
-            this._loadHandle = asset.once('load', () => {
-                this._detachLoadHandlers();
-                if (generation !== this._loadGeneration) {
-                    return;
-                }
-                this._extractTrack(asset, `asset '${this._asset}'`);
-            });
-            this._errorHandle = asset.once('error', () => {
-                this._detachLoadHandlers();
-                if (generation !== this._loadGeneration) {
-                    return;
-                }
-                this._warnSource(`pc-anim-clip '${this._name}' - asset '${this._asset}' failed to load - clip not assigned`);
-            });
             return;
         }
         const model = animElement.parentElement;
@@ -4658,8 +4801,9 @@ class AudioListenerComponentElement extends ComponentElement {
         super('audiolistener');
     }
     /**
-     * Gets the underlying PlayCanvas audio listener component.
-     * @returns The audio listener component.
+     * Gets the underlying PlayCanvas audio listener component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The audio listener component, or `null`.
      */
     get component() {
         return super.component;
@@ -4667,6 +4811,227 @@ class AudioListenerComponentElement extends ComponentElement {
 }
 customElements.define('pc-audio-listener', AudioListenerComponentElement);
 
+/**
+ * Resolves entity reference strings against the document. 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.
+ *
+ * Unlike the attribute parsers in `parse.ts`, these helpers touch the DOM, and `findEntityElement`
+ * and `getEntity` return `null` instead of falling back to a default. 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, and `pc-script` builds its own
+ * message from the lower-level pieces.
+ */
+/**
+ * Runs querySelector, absorbing the SyntaxError an unparseable selector throws - references are
+ * arbitrary author text, so a lookup must fail to `null`, never throw.
+ *
+ * @param selector - The selector to query.
+ * @returns The matched element, or `null`.
+ */
+const query = (selector) => {
+    try {
+        return document.querySelector(selector);
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * 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 {
+        return scope.matches(selector) ? scope : scope.querySelector(selector);
+    }
+    catch {
+        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) {
+        return 'nothing in the document matches it';
+    }
+    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;
+};
+
 const transitionModes = new Map([
     ['tint', playcanvas.BUTTON_TRANSITION_MODE_TINT],
     ['sprite', playcanvas.BUTTON_TRANSITION_MODE_SPRITE_CHANGE]
@@ -4720,7 +5085,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;
         }
@@ -4739,8 +5106,9 @@ class ButtonComponentElement extends ComponentElement {
         return data;
     }
     /**
-     * Gets the underlying PlayCanvas button component.
-     * @returns The button component.
+     * Gets the underlying PlayCanvas button component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The button component, or `null`.
      */
     get component() {
         return super.component;
@@ -4763,21 +5131,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() {
@@ -5192,8 +5566,9 @@ class CameraComponentElement extends ComponentElement {
         }
     }
     /**
-     * Gets the underlying PlayCanvas camera component.
-     * @returns The camera component.
+     * Gets the underlying PlayCanvas camera component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The camera component, or `null`.
      */
     get component() {
         return super.component;
@@ -5682,8 +6057,9 @@ class CollisionComponentElement extends ComponentElement {
         component.renderAsset = asset;
     }
     /**
-     * Gets the underlying PlayCanvas collision component.
-     * @returns The collision component.
+     * Gets the underlying PlayCanvas collision component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The collision component, or `null`.
      */
     get component() {
         return super.component;
@@ -5921,8 +6297,9 @@ class ElementComponentElement extends ComponentElement {
         return data;
     }
     /**
-     * Gets the underlying PlayCanvas element component.
-     * @returns The element component.
+     * Gets the underlying PlayCanvas element component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The element component, or `null`.
      */
     get component() {
         return super.component;
@@ -6505,7 +6882,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
@@ -6659,8 +7041,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,
@@ -6694,8 +7076,9 @@ class JointComponentElement extends ComponentElement {
         component.on('break', this._onBreak, this);
     }
     /**
-     * Gets the underlying PlayCanvas joint component.
-     * @returns The joint component.
+     * Gets the underlying PlayCanvas joint component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The joint component, or `null`.
      */
     get component() {
         return super.component;
@@ -6915,39 +7298,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() {
@@ -7412,8 +7804,9 @@ class LayoutChildComponentElement extends ComponentElement {
         };
     }
     /**
-     * Gets the underlying PlayCanvas layout child component.
-     * @returns The layout child component.
+     * Gets the underlying PlayCanvas layout child component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The layout child component, or `null`.
      */
     get component() {
         return super.component;
@@ -7632,8 +8025,9 @@ class LayoutGroupComponentElement extends ComponentElement {
         };
     }
     /**
-     * Gets the underlying PlayCanvas layout group component.
-     * @returns The layout group component.
+     * Gets the underlying PlayCanvas layout group component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The layout group component, or `null`.
      */
     get component() {
         return super.component;
@@ -7922,8 +8316,9 @@ class LightComponentElement extends ComponentElement {
         };
     }
     /**
-     * Gets the underlying PlayCanvas light component.
-     * @returns The light component.
+     * Gets the underlying PlayCanvas light component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The light component, or `null`.
      */
     get component() {
         return super.component;
@@ -8439,36 +8834,68 @@ customElements.define('pc-light', LightComponentElement);
  */
 class ParticleSystemComponentElement extends ComponentElement {
     _asset = '';
+    /**
+     * The subscription to the current config asset while its load is in flight. Rebinding
+     * supersedes it and disconnect cancels it, so a superseded config — an earlier asset that
+     * finishes loading after its replacement, or a callback left behind by a previous
+     * connection — can never configure the component.
+     */
+    _binding = new AssetBinding();
     /** @ignore */
     constructor() {
         super('particlesystem');
     }
     getInitialComponentData() {
         const asset = useAsset(this._asset);
-        // A lazy config has no resource yet - _loadAsset applies it once the load completes
+        // A lazy config has no resource yet - the config binding applies it once the load
+        // completes
         if (!asset || !asset.resource) {
             return {};
         }
-        if (asset.resource.colorMapAsset) {
-            const id = asset.resource.colorMapAsset;
-            const colorMapAsset = useAsset(id)?.id;
-            if (colorMapAsset) {
-                asset.resource.colorMapAsset = colorMapAsset;
-            }
-        }
+        this._resolveColorMap(asset.resource);
         return asset.resource;
     }
+    initComponent() {
+        // A loaded config already arrived through getInitialComponentData - the binding is only
+        // needed for a load still in flight. Resolution here also starts a lazy config's load.
+        const asset = useAsset(this._asset);
+        if (asset && !asset.loaded) {
+            this._bindConfig();
+        }
+    }
+    disconnectedCallback() {
+        // The binding dies with the connection, so a config that finishes loading later cannot
+        // configure the component a reconnection creates - that connection binds afresh.
+        this._binding.cancel();
+        super.disconnectedCallback();
+    }
     /**
-     * Gets the underlying PlayCanvas particle system component.
-     * @returns The particle system component.
+     * Gets the underlying PlayCanvas particle system component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The particle system component, or `null`.
      */
     get component() {
         return super.component;
     }
+    /**
+     * Rewrites the config's `colorMapAsset` from the `pc-asset` id it is authored with to the
+     * engine asset id the component resolves, starting the texture's load if it is lazy. The
+     * rewrite is in place, so a config applied again — a host cycle, a reconnection — is already
+     * resolved and passes through unchanged.
+     */
+    _resolveColorMap(resource) {
+        if (resource.colorMapAsset) {
+            const colorMapAsset = useAsset(resource.colorMapAsset)?.id;
+            if (colorMapAsset) {
+                resource.colorMapAsset = colorMapAsset;
+            }
+        }
+    }
     applyConfig(resource) {
         if (!this.component) {
             return;
         }
+        this._resolveColorMap(resource);
         // Set all the config properties on the component
         for (const key in resource) {
             if (Object.hasOwn(resource, key)) {
@@ -8476,20 +8903,10 @@ class ParticleSystemComponentElement extends ComponentElement {
             }
         }
     }
-    async _loadAsset() {
-        await this.closestApp?.ready();
-        const asset = useAsset(this._asset);
-        if (!asset) {
-            return;
-        }
-        if (asset.loaded) {
-            this.applyConfig(asset.resource);
-        }
-        else {
-            asset.once('load', () => {
-                this.applyConfig(asset.resource);
-            });
-        }
+    _bindConfig() {
+        this._binding.bind(this._asset, {
+            load: (asset) => this.applyConfig(asset.resource)
+        });
     }
     /**
      * Sets the id of the `pc-asset` to use for the model.
@@ -8498,7 +8915,7 @@ class ParticleSystemComponentElement extends ComponentElement {
     set asset(value) {
         this._asset = value;
         if (this.isConnected) {
-            this._loadAsset();
+            this._bindConfig();
         }
     }
     /**
@@ -8715,11 +9132,12 @@ class MaterialElement extends HTMLElement {
     _useSkybox = true;
     _useTonemap = true;
     /**
-     * Pending `load` handlers, one per texture slot. A slot's handler is torn down when the slot is
-     * reassigned or the element disconnects, so a late-arriving asset can never write a texture the
-     * element no longer wants.
+     * One asset binding per texture slot, created on first use and kept for the element's
+     * lifetime. A slot's binding is superseded when the slot is reassigned and cancelled when the
+     * element disconnects, so a late-arriving asset can never write a texture the element no
+     * longer wants.
      */
-    _mapHandles = new Map();
+    _mapBindings = new Map();
     _updateScheduled = false;
     _glossConflictWarned = false;
     /**
@@ -8846,10 +9264,9 @@ class MaterialElement extends HTMLElement {
         material.update();
     }
     disconnectedCallback() {
-        for (const handle of this._mapHandles.values()) {
-            handle.off();
+        for (const binding of this._mapBindings.values()) {
+            binding.cancel();
         }
-        this._mapHandles.clear();
         if (this.material) {
             this.material.destroy();
             this.material = null;
@@ -8895,16 +9312,23 @@ class MaterialElement extends HTMLElement {
             'the roughness-* attributes invert gloss, so the two families contradict each other. Use one or the other.');
     }
     /**
-     * Points a texture slot at the resource of a `pc-asset`, waiting for the asset to load when it
-     * has not already. An empty id clears the slot.
+     * Points a texture slot at the resource of a `pc-asset`, waiting for the asset to load when
+     * it has not already. An empty id clears the slot; a slot keeps its current texture while
+     * the new asset loads, and also across a failed load - a later reload can still deliver.
      *
      * @param id - The id of the `pc-asset`, or an empty string to clear the slot.
      * @param slot - The material property to write.
      */
     _setMap(id, slot) {
-        // Drop any load still pending for this slot - its texture is no longer the one we want
-        this._mapHandles.get(slot)?.off();
-        this._mapHandles.delete(slot);
+        let binding = this._mapBindings.get(slot);
+        if (!binding) {
+            binding = new AssetBinding();
+            this._mapBindings.set(slot, binding);
+        }
+        // Drop any load still pending for this slot - its texture is no longer the one we want.
+        // Cancelled here rather than left to the bind below, which the material-less and
+        // clear-slot returns never reach.
+        binding.cancel();
         if (!this.material)
             return;
         if (!id) {
@@ -8912,17 +9336,9 @@ class MaterialElement extends HTMLElement {
             this._scheduleUpdate();
             return;
         }
-        const asset = useAsset(id);
-        if (!asset)
-            return;
-        if (asset.loaded) {
-            this._applyMap(slot, asset.resource);
-            return;
-        }
-        this._mapHandles.set(slot, asset.once('load', () => {
-            this._mapHandles.delete(slot);
-            this._applyMap(slot, asset.resource);
-        }));
+        binding.bind(id, {
+            load: (asset) => this._applyMap(slot, asset.resource)
+        });
     }
     /**
      * @param slot - The material property to write.
@@ -10818,8 +11234,9 @@ class RenderComponentElement extends ComponentElement {
         };
     }
     /**
-     * Gets the underlying PlayCanvas render component.
-     * @returns The render component.
+     * Gets the underlying PlayCanvas render component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The render component, or `null`.
      */
     get component() {
         return super.component;
@@ -10990,8 +11407,9 @@ class RigidBodyComponentElement extends ComponentElement {
         };
     }
     /**
-     * Gets the underlying PlayCanvas rigidbody component.
-     * @returns The rigidbody component.
+     * Gets the underlying PlayCanvas rigidbody component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The rigidbody component, or `null`.
      */
     get component() {
         return super.component;
@@ -11170,8 +11588,9 @@ class ScreenComponentElement extends ComponentElement {
         };
     }
     /**
-     * Gets the underlying PlayCanvas screen component.
-     * @returns The screen component.
+     * Gets the underlying PlayCanvas screen component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The screen component, or `null`.
      */
     get component() {
         return super.component;
@@ -11321,15 +11740,16 @@ 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;
         }
         return data;
     }
     /**
-     * Gets the underlying PlayCanvas scrollbar component.
-     * @returns The scrollbar component.
+     * Gets the underlying PlayCanvas scrollbar component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The scrollbar component, or `null`.
      */
     get component() {
         return super.component;
@@ -11387,19 +11807,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() {
@@ -11481,27 +11906,28 @@ 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;
         }
         return data;
     }
     /**
-     * Gets the underlying PlayCanvas scroll view component.
-     * @returns The scroll view component.
+     * Gets the underlying PlayCanvas scroll view component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The scroll view component, or `null`.
      */
     get component() {
         return super.component;
@@ -11669,76 +12095,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() {
@@ -11821,7 +12267,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`).
  *
@@ -11837,7 +12285,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.
@@ -11857,9 +12306,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) {
@@ -11870,7 +12321,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() {
@@ -12081,18 +12535,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;
 };
 /**
@@ -12225,8 +12684,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)
@@ -12240,7 +12701,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));
@@ -12618,8 +13079,9 @@ class ScriptComponentElement extends ComponentElement {
         super.disconnectedCallback?.();
     }
     /**
-     * Gets the underlying PlayCanvas script component.
-     * @returns The script component.
+     * Gets the underlying PlayCanvas script component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The script component, or `null`.
      */
     get component() {
         return super.component;
@@ -12665,8 +13127,9 @@ class SoundComponentElement extends ComponentElement {
         };
     }
     /**
-     * Gets the underlying PlayCanvas sound component.
-     * @returns The sound component.
+     * Gets the underlying PlayCanvas sound component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The sound component, or `null`.
      */
     get component() {
         return super.component;
@@ -13147,8 +13610,9 @@ class GSplatComponentElement extends ComponentElement {
         };
     }
     /**
-     * Gets the underlying PlayCanvas gsplat component.
-     * @returns The gsplat component.
+     * Gets the underlying PlayCanvas gsplat component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The gsplat component, or `null`.
      */
     get component() {
         return super.component;
@@ -14441,31 +14905,27 @@ class SkyElement extends AsyncElement {
     _appElement = null;
     /**
      * Incremented on every new load and on disconnect, and captured by a load when it starts. A
-     * load that resumes from an await or a load callback abandons itself if the value has moved
-     * on, so a superseded load cannot generate a skybox for a scene it no longer configures.
+     * load that resumes from an await abandons itself if the value has moved on, so a superseded
+     * load cannot generate a skybox for a scene it no longer configures. The asset subscription
+     * itself is guarded by the binding below.
      */
     _loadGeneration = 0;
     /**
-     * The pending asset-load subscription of the current load, if it is waiting for its asset.
-     * Held so that whatever supersedes the load can detach the handler from the asset, rather
-     * than leave it registered until the asset loads (or forever, if it never does).
+     * Watches the current texture asset while it loads. Starting a new load or disconnecting
+     * cancels it, so a superseded texture can never generate the skybox.
      */
-    _loadHandle = null;
+    _binding = new AssetBinding();
     connectedCallback() {
         this._loadSkybox();
         this._onReady();
     }
     disconnectedCallback() {
         this._loadGeneration++;
-        this._detachLoadHandler();
+        this._binding.cancel();
         this._unloadSkybox();
         this._appElement = null;
         this._resetReady();
     }
-    _detachLoadHandler() {
-        this._loadHandle?.off();
-        this._loadHandle = null;
-    }
     _generateSkybox(asset) {
         if (!this._scene)
             return;
@@ -14497,7 +14957,7 @@ class SkyElement extends AsyncElement {
     async _loadSkybox() {
         // Supersede any load already in flight - only the newest load may generate the skybox
         const generation = ++this._loadGeneration;
-        this._detachLoadHandler();
+        this._binding.cancel();
         const appElement = await this.closestApp?.ready();
         // The element may have been removed, or another load started, while we waited
         if (generation !== this._loadGeneration) {
@@ -14508,26 +14968,18 @@ class SkyElement extends AsyncElement {
             return;
         }
         this._appElement = appElement;
-        const asset = useAsset(this._asset);
-        if (!asset) {
+        // The scene is only adopted once the reference resolves: an unresolved id must leave the
+        // scene untouched, or this element's teardown would destroy a skybox it never created.
+        // The bind below repeats the resolution, which useAsset documents as free - it cannot
+        // happen after the bind, because a loaded asset delivers before bind returns and
+        // _generateSkybox needs the scene by then.
+        if (!useAsset(this._asset)) {
             return;
         }
         this._scene = app.scene;
-        if (asset.loaded) {
-            this._generateSkybox(asset);
-        }
-        else {
-            // The generation is re-checked even though a superseded handler is detached: the
-            // detach relies on how the engine's event emitter treats removal, while the check
-            // holds on its own.
-            this._loadHandle = asset.once('load', () => {
-                this._loadHandle = null;
-                if (generation !== this._loadGeneration) {
-                    return;
-                }
-                this._generateSkybox(asset);
-            });
-        }
+        this._binding.bind(this._asset, {
+            load: (asset) => this._generateSkybox(asset)
+        });
     }
     _unloadSkybox() {
         const scene = this._scene;