@playcanvas/web-components 0.20.0 → 0.21.0

package/dist/pwc.js

@@ -588,14 +588,6 @@
      *   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.
-     *
-     * `findEntityElement` and `getEntity` are the exceptions: they resolve a reference rather than
-     * parsing a literal, and return `null` instead of falling back to a default. A reference
-     * beginning with `#` is a document-wide selector (an element id, or any selector rooted in one);
-     * anything else is an entity name, resolved lexically through the entity hierarchy first and
-     * against the document after — never as a selector or an id. They also do not warn - what an
-     * unresolved reference means depends on the element holding it - so elements report through
-     * `resolveEntity`, which takes that meaning as parameters.
      */
     /**
      * Splits an attribute value into exactly `count` numeric components. Returns `null` when the
@@ -841,215 +833,10 @@
         }
         return new playcanvas.Vec4(components);
     };
-    /**
-     * 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;
-    };
 
+    // 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
@@ -1096,88 +883,29 @@
         return null;
     };
     /**
-     * Gives `pc-app` the sizing contract of a replaced element (`<video>`, `<img>`): a block-level
-     * box that the page's CSS sizes, defaulting to the canvas's own 300x150 intrinsic size, with the
-     * canvas and loading bar anchored to it. `:where()` keeps every declaration at zero specificity,
-     * so any page rule - however plain - overrides these defaults.
-     */
-    const ensureBaseStyles = () => {
-        const id = 'pc-app-styles';
-        if (document.getElementById(id)) {
-            return;
-        }
-        const style = document.createElement('style');
-        style.id = id;
-        style.textContent = ':where(pc-app) { display: block; position: relative; width: 300px; height: 150px; }';
-        document.head.appendChild(style);
-    };
-    /**
-     * The AppElement interface provides properties and methods for manipulating
-     * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-app/ | `<pc-app>`} elements.
-     * The AppElement interface also inherits the properties and methods of the
-     * {@link HTMLElement} interface.
-     *
-     * The element is sized like a replaced element such as `<video>`: a block-level box that the
-     * page's CSS controls, 300x150 by default. The application's canvas always fills the element,
-     * and the drawing buffer resolution follows the element's size (capped by `max-pixel-ratio`),
-     * tracked live via a ResizeObserver — so the element can be embedded at any size, resized by
-     * its container, or made fullscreen with ordinary CSS such as `width: 100vw; height: 100dvh`.
-     *
-     * @elementSummary The `<pc-app>` element creates a PlayCanvas application and the canvas it renders
-     * into, and is the root of every scene. It holds the `<pc-asset>`, `<pc-material>`, `<pc-wasm>` and
-     * `<pc-scene>` elements, and the page's CSS sizes it, as it would a `<video>`.
+     * 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.
      *
-     * @fires {ProgressEvent} progress - Fired while the application preloads its assets. `loaded` and
-     * `total` are asset counts, not bytes, and an asset that fails to load still counts as loaded.
-     * Fired at least once per boot, and the final event always has `loaded` equal to `total`. Does
-     * not bubble.
+     * 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.
      *
-     * @fires {ErrorEvent} error - Fired when the application cannot boot because no graphics device
-     * could be created (for example, a browser with WebGL disabled). `message` names the requested
-     * backends and `error` holds the underlying failure. The element never becomes ready
-     * and `app` stays `null` — listen for this event to show a fallback UI. Removing the element and
-     * re-inserting it retries the boot with its current attributes. Does not bubble.
+     * @internal
      */
-    class AppElement extends AsyncElement {
+    class PointerController {
+        _host;
         /**
-         * The canvas element.
+         * 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;
-        _alpha = true;
-        _backend = 'webgpu';
-        _antialias = true;
-        _depthBuffer = true;
-        _stencilBuffer = true;
-        _maxPixelRatio = Infinity;
-        _loadingBar = true;
-        /**
-         * Set once the graphics options above have been handed to `createGraphicsDevice`, after which
-         * writing any of them changes nothing. Guards the warning in {@link _warnIfBooted}, and is
-         * cleared on disconnect so a re-connected element boots from its current attributes.
-         */
-        _optionsLocked = false;
-        _bar = null;
-        /**
-         * Whether the application has created its initial entity hierarchy. Read by EntityElement to
-         * decide whether a newly connected element must create its entity itself or leave it to the
-         * boot sweep.
-         * @internal
-         */
-        _hierarchyReady = false;
-        /**
-         * Incremented on every connect and disconnect. Boot captures the value on entry and abandons
-         * itself wherever it resumes from an await if the value has moved on — so a boot whose
-         * element was removed cannot complete against a torn-down element, and a boot whose element
-         * was removed and re-inserted (which starts a boot of its own) cannot race the newer one.
-         */
-        _bootGeneration = 0;
-        /**
-         * The elements backing this application's entities, keyed by the entity itself. Registered
-         * by entity-owning elements at creation (pc-entity, and pc-model for its host) and by
-         * NodeElement at binding, and removed when an entity is destroyed or unbound, this joins
-         * 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
@@ -1196,7 +924,7 @@
          * 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. */
+        /** 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
@@ -1205,504 +933,194 @@
         _lastClick = null;
         /**
          * Serializes dispatch of the discrete synthesized events (pointerdown, pointerup, click),
-         * whose picks resolve in GPU order, not canvas-event order. Replaced on teardown, so a pick
-         * that never resolves cannot stall the dispatches of a later boot.
+         * 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();
-        _app = null;
-        _loadProgress = 0;
         /**
-         * Tracks the element's box so the drawing buffer and picker follow it. Created per boot once
-         * the application exists, and disconnected on teardown. `null` where ResizeObserver is
-         * unavailable (jsdom), where the boot-time resolution set is the only sizing that happens.
+         * @param host - The services the controller reads from its host element.
          */
-        _resizeObserver = null;
+        constructor(host) {
+            this._host = host;
+        }
         /**
-         * The PlayCanvas application instance. `null` until the element is ready, and again once it
-         * has been removed from the document — await {@link whenReady} or the element's `ready()`
-         * promise before accessing it.
-         * @returns The application instance, or `null`.
+         * 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.
          */
-        get app() {
-            return this._app;
+        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();
         }
         /**
-         * The asset preload progress of the application, as a fraction from 0 to 1. It is 0 until
-         * preloading begins (and again once the element has been removed from the document), and 1
-         * once preloading has finished — including when there was nothing to preload. Read this to
-         * initialize a loading UI; subsequent updates arrive via the `progress` event.
-         * @returns The preload progress.
+         * 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.
          */
-        get loadProgress() {
-            return this._loadProgress;
+        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();
         }
         /**
-         * Creates a new AppElement instance.
+         * Resizes the picker to the drawing buffer. The picker must track the buffer, or picks would
+         * land at stale coordinates after a resize.
          *
-         * @ignore
+         * @param width - The drawing buffer width.
+         * @param height - The drawing buffer height.
          */
-        constructor() {
-            super();
-            // Track listeners for the synthesized events being added to and removed from descendant
-            // entities. Registered once here rather than on every boot - the sync no-ops while there
-            // is no canvas, and a re-booted element must not stack a second set.
-            SYNTHESIZED_EVENTS.forEach((type) => {
-                this.addEventListener(`${type}:connect`, () => this._syncCanvasListeners());
-                this.addEventListener(`${type}:disconnect`, () => this._syncCanvasListeners());
-            });
+        resize(width, height) {
+            this._picker?.resize(width, height);
         }
-        async connectedCallback() {
-            const generation = ++this._bootGeneration;
-            // Installed before the loading bar is created: the bar anchors to this element, which
-            // these styles make a positioned block box
-            ensureBaseStyles();
-            // Created before the first await, so the bar is visible while modules and the graphics
-            // device are created, and exists before any disconnect could need to clean it up
-            if (this._loadingBar && !this._bar) {
-                this._bar = new LoadingBar(this);
-            }
-            // Upgrade the subtree before reading anything out of it. A subtree cloned from a
-            // <template> arrives entirely unupgraded - template content lives in an inert document,
-            // where custom element definitions are never looked up - and appending the clone upgrades
-            // its elements in tree order, this one before its descendants. The module query below would
-            // otherwise find plain HTMLElements with no _getLoadPromise to call, and the boot would die
-            // there, leaving the element permanently unready: no canvas, no entities, no application.
-            //
-            // Upgrading is the fix here rather than skipping whatever has not upgraded, because a
-            // <pc-wasm> is the one child that nothing else ever builds on its own behalf - skipping
-            // it would drop the wasm module the app asked for, silently and only for cloned apps.
-            // Upgrading runs each descendant's connectedCallback synchronously, a few lines earlier
-            // than the parser's path runs them but into the same state they see there: no application
-            // yet and _hierarchyReady false, so they defer to the sweeps below. A descendant that
-            // disconnects this element from there is caught by the generation check after the await,
-            // as any other disconnect is. An already-upgraded subtree - every other insertion path -
-            // is left completely untouched.
-            customElements.upgrade(this);
-            // Get all pc-wasm elements that are direct children of the pc-app element
-            const wasmElements = this.querySelectorAll(':scope > pc-wasm');
-            // Wait for all modules to load
-            await Promise.all(Array.from(wasmElements).map((element) => element._getLoadPromise()));
-            // The element may have been removed while the modules loaded. Nothing beyond the loading
-            // bar exists yet, and disconnectedCallback has already destroyed that.
-            if (generation !== this._bootGeneration) {
+        /**
+         * 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));
+                }
             }
-            // Create and append the canvas, filling the element's content box - the page sizes the
-            // element, and everything else follows. touch-action: none keeps touch drags driving the
-            // engine's input handlers instead of scrolling the page.
-            this._canvas = document.createElement('canvas');
-            this._canvas.style.cssText = 'display: block; width: 100%; height: 100%; touch-action: none;';
-            this.appendChild(this._canvas);
-            // Configure device types based on backend selection
-            const backendToDeviceTypes = {
-                webgpu: ['webgpu', 'webgl2'], // fallback to webgl2 if webgpu not available
-                webgl2: ['webgl2'],
-                null: ['null']
-            };
-            const deviceTypes = backendToDeviceTypes[this._backend] || [];
-            this._optionsLocked = true;
-            // createGraphicsDevice appends its final null-device fallback to the array in place, so
-            // the requested list is captured now for the failure message.
-            const requested = deviceTypes.join(', ');
-            let device;
-            try {
-                device = await playcanvas.createGraphicsDevice(this._canvas, {
-                    // @ts-ignore - alpha needs to be documented
-                    alpha: this._alpha,
-                    antialias: this._antialias,
-                    depth: this._depthBuffer,
-                    deviceTypes: deviceTypes,
-                    stencil: this._stencilBuffer
-                });
-            }
-            catch (error) {
-                // The element may have been removed while device creation was failing. The teardown
-                // has already cleaned up, and the failure belongs to a boot that no longer owns the
-                // element.
-                if (generation !== this._bootGeneration) {
+            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);
                 }
-                // Return the element to its pre-boot state - no dead canvas, no loading bar stuck at
-                // zero - before announcing the failure. Readiness deliberately stays pending: nothing
-                // it would announce (the app, the entity hierarchy) exists, so a device-less element
-                // joins the documented never-ready cases and the failure surfaces through the error
-                // event instead.
-                if (this._canvas && this.contains(this._canvas)) {
-                    this.removeChild(this._canvas);
+                else {
+                    canvas.removeEventListener(canvasType, handler);
                 }
-                this._canvas = null;
-                this._bar?.destroy();
-                this._bar = null;
-                const reason = error instanceof Error ? error.message : String(error);
-                const message = `pc-app failed to create a graphics device (${requested}) - ${reason}`;
-                console.error(message, error);
-                this.dispatchEvent(new ErrorEvent('error', { message, error }));
-                return;
+            });
+        }
+        /**
+         * 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;
             }
-            // The element may have been removed while the device was created. disconnectedCallback
-            // has already cleaned up the canvas; the device was created inside the await, so it is
-            // this boot's to release.
-            if (generation !== this._bootGeneration) {
-                device.destroy();
-                return;
-            }
-            // Assigned rather than resolved to a number here: the engine caps against the live
-            // window.devicePixelRatio on every resize, so an uncapped Infinity keeps following the
-            // display when a window moves between monitors of differing density.
-            device.maxPixelRatio = this._maxPixelRatio;
-            const createOptions = new playcanvas.AppOptions();
-            createOptions.graphicsDevice = device;
-            createOptions.keyboard = new playcanvas.Keyboard(window);
-            createOptions.mouse = new playcanvas.Mouse(this._canvas);
-            createOptions.elementInput = new playcanvas.ElementInput(this._canvas, {
-                useMouse: true,
-                useTouch: true
-            });
-            createOptions.componentSystems = [
-                playcanvas.AnimComponentSystem,
-                playcanvas.AnimationComponentSystem,
-                playcanvas.AudioListenerComponentSystem,
-                playcanvas.ButtonComponentSystem,
-                playcanvas.CameraComponentSystem,
-                playcanvas.CollisionComponentSystem,
-                playcanvas.ElementComponentSystem,
-                playcanvas.GSplatComponentSystem,
-                playcanvas.JointComponentSystem,
-                playcanvas.LayoutChildComponentSystem,
-                playcanvas.LayoutGroupComponentSystem,
-                playcanvas.LightComponentSystem,
-                playcanvas.ModelComponentSystem,
-                playcanvas.ParticleSystemComponentSystem,
-                playcanvas.RenderComponentSystem,
-                playcanvas.RigidBodyComponentSystem,
-                playcanvas.ScreenComponentSystem,
-                playcanvas.ScriptComponentSystem,
-                playcanvas.ScrollbarComponentSystem,
-                playcanvas.ScrollViewComponentSystem,
-                playcanvas.SoundComponentSystem,
-                playcanvas.SpriteComponentSystem,
-                playcanvas.ZoneComponentSystem
-            ];
-            createOptions.resourceHandlers = [
-                playcanvas.AnimClipHandler,
-                playcanvas.AnimationHandler,
-                playcanvas.AnimStateGraphHandler,
-                playcanvas.AudioHandler,
-                playcanvas.BinaryHandler,
-                playcanvas.CssHandler,
-                playcanvas.ContainerHandler,
-                playcanvas.CubemapHandler,
-                playcanvas.FolderHandler,
-                playcanvas.FontHandler,
-                playcanvas.GSplatHandler,
-                playcanvas.HierarchyHandler,
-                playcanvas.HtmlHandler,
-                playcanvas.JsonHandler,
-                playcanvas.MaterialHandler,
-                playcanvas.ModelHandler,
-                playcanvas.RenderHandler,
-                playcanvas.ScriptHandler,
-                playcanvas.SceneHandler,
-                playcanvas.ShaderHandler,
-                playcanvas.SpriteHandler,
-                playcanvas.TemplateHandler,
-                playcanvas.TextHandler,
-                playcanvas.TextureAtlasHandler,
-                playcanvas.TextureHandler
-            ];
-            createOptions.soundManager = new playcanvas.SoundManager();
-            createOptions.lightmapper = playcanvas.Lightmapper;
-            createOptions.batchManager = playcanvas.BatchManager;
-            createOptions.xr = playcanvas.XrManager;
-            const app = new playcanvas.AppBase(this._canvas);
-            this._app = app;
-            app.init(createOptions);
-            // FILLMODE_NONE leaves the canvas's CSS sizing alone (the engine's other fill modes
-            // stamp window-derived pixel sizes onto it); RESOLUTION_AUTO sizes the drawing buffer
-            // from the canvas's client size
-            app.setCanvasFillMode(playcanvas.FILLMODE_NONE);
-            app.setCanvasResolution(playcanvas.RESOLUTION_AUTO);
-            this._pickerCreate();
-            // 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.
-            if (typeof ResizeObserver !== 'undefined') {
-                this._resizeObserver = new ResizeObserver(() => this._syncCanvasSize());
-                this._resizeObserver.observe(this);
-            }
-            // Get all pc-asset elements that are direct children of the pc-app element
-            const assetElements = this.querySelectorAll(':scope > pc-asset');
-            for (const assetElement of Array.from(assetElements)) {
-                assetElement._createAsset();
-                const asset = assetElement.asset;
-                if (asset) {
-                    app.assets.add(asset);
-                    // Adding a fileless asset (one built purely from data, such as a sprite)
-                    // completes it synchronously, dispatching the element's load event - whose
-                    // listeners may have removed this element. Stop before the next addition
-                    // reaches the destroyed registry, and before orphan entities are created.
-                    if (generation !== this._bootGeneration) {
-                        return;
-                    }
-                }
-            }
-            // Get all pc-material elements that are direct children of the pc-app element
-            const materialElements = this.querySelectorAll(':scope > pc-material');
-            Array.from(materialElements).forEach((materialElement) => {
-                materialElement._createMaterial();
-            });
-            // Create all entities. pc-model joins the sweep because it owns a host entity of its
-            // own; its instantiated content arrives later, beneath that host.
-            const ownerElements = this.querySelectorAll('pc-entity, pc-model');
-            Array.from(ownerElements).forEach((ownerElement) => {
-                ownerElement._createEntity(app);
-            });
-            // Build hierarchy
-            ownerElements.forEach((ownerElement) => {
-                ownerElement._buildHierarchy(app);
-            });
-            // Building the hierarchy dispatched each entity's ready event synchronously, and a
-            // listener may have removed the element. The sweep itself degrades safely - destroying
-            // the application nulls every element's entity, so the remaining builds no-op - but the
-            // teardown's reset must not be overwritten here.
-            if (generation !== this._bootGeneration) {
-                return;
-            }
-            this._hierarchyReady = true;
-            // Forward the engine's preload lifecycle as DOM ProgressEvents on this element. The
-            // listener must be attached before preload() is called: an asset that is already loaded
-            // ticks synchronously inside it.
-            const total = app.assets.list({ preload: true }).length;
-            let loaded = 0;
-            const onPreloadProgress = () => {
-                loaded += 1;
-                this._loadProgress = loaded / total;
-                this._bar?.progress(loaded, total);
-                this.dispatchEvent(new ProgressEvent('progress', { lengthComputable: true, loaded, total }));
-            };
-            app.on('preload:progress', onPreloadProgress);
-            this._loadProgress = total === 0 ? 1 : 0;
-            this._bar?.progress(0, total);
-            this.dispatchEvent(new ProgressEvent('progress', { lengthComputable: true, loaded: 0, total }));
-            // The progress dispatch above ran listeners synchronously, and one may have removed the
-            // element. The application is already destroyed - it must not be asked to preload.
-            if (generation !== this._bootGeneration) {
-                return;
-            }
-            // Load assets before starting the application
-            app.preload(() => {
-                // The element may have been removed while assets loaded. The application is already
-                // destroyed, so it must not be started — and readiness must not be signaled for a
-                // boot that no longer owns the element.
-                if (generation !== this._bootGeneration) {
-                    return;
-                }
-                // Scope the counter to this preload pass, so a later app.preload() call by user code
-                // cannot push `loaded` past `total`
-                app.off('preload:progress', onPreloadProgress);
-                this._loadProgress = 1;
-                // Start the application
-                app.start();
-                // Dismiss the bar only once a frame has actually rendered; ready fires before the
-                // first rAF tick
-                app.once('frameend', () => this._bar?.complete());
-                this._onReady();
-            });
-        }
-        disconnectedCallback() {
-            // Invalidate any boot still in flight, so it abandons itself when it next resumes
-            // instead of completing against a torn-down element.
-            this._bootGeneration++;
-            this._optionsLocked = false;
-            this._pickerDestroy();
-            // 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) {
-                this._app.destroy();
-                this._app = null;
-            }
-            this._entityElements.clear();
-            this._loadProgress = 0;
-            this._bar?.destroy();
-            this._bar = null;
-            // Return the element to its pre-boot state, so re-inserting it boots afresh: descendants
-            // must neither see a hierarchy that no longer exists nor resume against a readiness that
-            // no longer holds.
-            this._hierarchyReady = false;
-            this._resetReady();
-            // Stop tracking the element's size
-            this._resizeObserver?.disconnect();
-            this._resizeObserver = null;
-            // Remove the canvas
-            if (this._canvas && this.contains(this._canvas)) {
-                this.removeChild(this._canvas);
-                this._canvas = null;
+            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;
         }
         /**
-         * Syncs the drawing buffer and the picker to the canvas's current CSS size. The picker must
-         * track the buffer, or picks would land at stale coordinates after a resize. Skipped while
-         * an XR session presents - the session owns the buffer size.
+         * 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.
          */
-        _syncCanvasSize() {
-            if (!this.app || this.app.xr?.active) {
-                return;
-            }
-            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 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);
-            };
-            // 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);
-                    }
-                });
+        _getPickerCoordinates(event, canvas) {
+            const canvasRect = canvas.getBoundingClientRect();
+            if (canvasRect.width === 0 || canvasRect.height === 0) {
+                return { x: event.clientX, y: event.clientY, mapped: false };
             }
-            this._picker = null;
-            this._hoveredEntity = null;
-            this._pointerHandlers = {
-                pointermove: null,
-                pointerdown: null,
-                pointerup: null,
-                pointercancel: null
+            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
             };
-            this._downPicks.clear();
-            this._clickListened = false;
-            this._lastClick = null;
-            // Replace the chain: a pick that never resolves must not stall a later boot's dispatches
-            this._dispatchChain = Promise.resolve();
         }
         /**
-         * Registers the element that fronts an entity. Called by EntityElement when it creates its
-         * entity, and by NodeElement when it binds one.
+         * 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 entity - The entity.
-         * @param element - The element that fronts it.
-         * @internal
-         */
-        _registerEntityElement(entity, element) {
-            this._entityElements.set(entity, element);
-        }
-        /**
-         * Removes the registration for a destroyed entity. Called by EntityElement.
-         *
-         * @param entity - The entity.
-         * @internal
-         */
-        _unregisterEntityElement(entity) {
-            this._entityElements.delete(entity);
-        }
-        /**
-         * Returns the `<pc-entity>`, `<pc-model>` or `<pc-node>` element whose backing entity is
-         * `entity`, or `null` if the entity is not fronted by an element of this application - for
-         * 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.
+         * @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;
@@ -1731,7 +1149,8 @@
          * @returns The graph node under the pointer, or `null` if nothing was hit.
          */
         async _pickNode(event) {
-            const app = this.app;
+            const generation = this._generation;
+            const app = this._app;
             const picker = this._picker;
             const canvas = this._canvas;
             if (!app || !picker || !canvas)
@@ -1751,8 +1170,9 @@
                     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)
+                // 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];
@@ -1767,145 +1187,588 @@
             return null;
         }
         async _onPointerMove(event) {
-            if (!this._picker || !this.app)
+            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.
+            // 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 || !this._picker)
+            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
+     * canvas and loading bar anchored to it. `:where()` keeps every declaration at zero specificity,
+     * so any page rule - however plain - overrides these defaults.
+     */
+    const ensureBaseStyles = () => {
+        const id = 'pc-app-styles';
+        if (document.getElementById(id)) {
+            return;
+        }
+        const style = document.createElement('style');
+        style.id = id;
+        style.textContent = ':where(pc-app) { display: block; position: relative; width: 300px; height: 150px; }';
+        document.head.appendChild(style);
+    };
+    /**
+     * The AppElement interface provides properties and methods for manipulating
+     * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-app/ | `<pc-app>`} elements.
+     * The AppElement interface also inherits the properties and methods of the
+     * {@link HTMLElement} interface.
+     *
+     * The element is sized like a replaced element such as `<video>`: a block-level box that the
+     * page's CSS controls, 300x150 by default. The application's canvas always fills the element,
+     * and the drawing buffer resolution follows the element's size (capped by `max-pixel-ratio`),
+     * tracked live via a ResizeObserver — so the element can be embedded at any size, resized by
+     * its container, or made fullscreen with ordinary CSS such as `width: 100vw; height: 100dvh`.
+     *
+     * @elementSummary The `<pc-app>` element creates a PlayCanvas application and the canvas it renders
+     * into, and is the root of every scene. It holds the `<pc-asset>`, `<pc-material>`, `<pc-wasm>` and
+     * `<pc-scene>` elements, and the page's CSS sizes it, as it would a `<video>`.
+     *
+     * @fires {ProgressEvent} progress - Fired while the application preloads its assets. `loaded` and
+     * `total` are asset counts, not bytes, and an asset that fails to load still counts as loaded.
+     * Fired at least once per boot, and the final event always has `loaded` equal to `total`. Does
+     * not bubble.
+     *
+     * @fires {ErrorEvent} error - Fired when the application cannot boot because no graphics device
+     * could be created (for example, a browser with WebGL disabled). `message` names the requested
+     * backends and `error` holds the underlying failure. The element never becomes ready
+     * and `app` stays `null` — listen for this event to show a fallback UI. Removing the element and
+     * re-inserting it retries the boot with its current attributes. Does not bubble.
+     */
+    class AppElement extends AsyncElement {
+        /**
+         * The canvas element.
+         */
+        _canvas = null;
+        _alpha = true;
+        _backend = 'webgpu';
+        _antialias = true;
+        _depthBuffer = true;
+        _stencilBuffer = true;
+        _maxPixelRatio = Infinity;
+        _loadingBar = true;
+        /**
+         * Set once the graphics options above have been handed to `createGraphicsDevice`, after which
+         * writing any of them changes nothing. Guards the warning in {@link _warnIfBooted}, and is
+         * cleared on disconnect so a re-connected element boots from its current attributes.
+         */
+        _optionsLocked = false;
+        _bar = null;
+        /**
+         * Whether the application has created its initial entity hierarchy. Read by EntityElement to
+         * decide whether a newly connected element must create its entity itself or leave it to the
+         * boot sweep.
+         * @internal
+         */
+        _hierarchyReady = false;
+        /**
+         * Incremented on every connect and disconnect. Boot captures the value on entry and abandons
+         * itself wherever it resumes from an await if the value has moved on — so a boot whose
+         * element was removed cannot complete against a torn-down element, and a boot whose element
+         * was removed and re-inserted (which starts a boot of its own) cannot race the newer one.
+         */
+        _bootGeneration = 0;
+        /**
+         * The elements backing this application's entities, keyed by the entity itself. Registered
+         * by entity-owning elements at creation (pc-entity, and pc-model for its host) and by
+         * NodeElement at binding, and removed when an entity is destroyed or unbound, this joins
+         * engine scene nodes back to their owning elements by identity - never by name.
+         */
+        _entityElements = new Map();
+        /**
+         * 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.
+         */
+        _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;
+        /**
+         * Tracks the element's box so the drawing buffer and picker follow it. Created per boot once
+         * the application exists, and disconnected on teardown. `null` where ResizeObserver is
+         * unavailable (jsdom), where the boot-time resolution set is the only sizing that happens.
+         */
+        _resizeObserver = null;
+        /**
+         * The PlayCanvas application instance. `null` until the element is ready, and again once it
+         * has been removed from the document — await {@link whenReady} or the element's `ready()`
+         * promise before accessing it.
+         * @returns The application instance, or `null`.
+         */
+        get app() {
+            return this._app;
+        }
+        /**
+         * The asset preload progress of the application, as a fraction from 0 to 1. It is 0 until
+         * preloading begins (and again once the element has been removed from the document), and 1
+         * once preloading has finished — including when there was nothing to preload. Read this to
+         * initialize a loading UI; subsequent updates arrive via the `progress` event.
+         * @returns The preload progress.
+         */
+        get loadProgress() {
+            return this._loadProgress;
+        }
+        /**
+         * Creates a new AppElement instance.
+         *
+         * @ignore
+         */
+        constructor() {
+            super();
+            // Track listeners for the synthesized events being added to and removed from descendant
+            // entities. Registered once here rather than on every boot - the sync no-ops while there
+            // is no canvas, and a re-booted element must not stack a second set.
+            SYNTHESIZED_EVENTS.forEach((type) => {
+                this.addEventListener(`${type}:connect`, () => this._pointer.syncListeners());
+                this.addEventListener(`${type}:disconnect`, () => this._pointer.syncListeners());
+            });
+        }
+        async connectedCallback() {
+            const generation = ++this._bootGeneration;
+            // Installed before the loading bar is created: the bar anchors to this element, which
+            // these styles make a positioned block box
+            ensureBaseStyles();
+            // Created before the first await, so the bar is visible while modules and the graphics
+            // device are created, and exists before any disconnect could need to clean it up
+            if (this._loadingBar && !this._bar) {
+                this._bar = new LoadingBar(this);
+            }
+            // Upgrade the subtree before reading anything out of it. A subtree cloned from a
+            // <template> arrives entirely unupgraded - template content lives in an inert document,
+            // where custom element definitions are never looked up - and appending the clone upgrades
+            // its elements in tree order, this one before its descendants. The module query below would
+            // otherwise find plain HTMLElements with no _getLoadPromise to call, and the boot would die
+            // there, leaving the element permanently unready: no canvas, no entities, no application.
+            //
+            // Upgrading is the fix here rather than skipping whatever has not upgraded, because a
+            // <pc-wasm> is the one child that nothing else ever builds on its own behalf - skipping
+            // it would drop the wasm module the app asked for, silently and only for cloned apps.
+            // Upgrading runs each descendant's connectedCallback synchronously, a few lines earlier
+            // than the parser's path runs them but into the same state they see there: no application
+            // yet and _hierarchyReady false, so they defer to the sweeps below. A descendant that
+            // disconnects this element from there is caught by the generation check after the await,
+            // as any other disconnect is. An already-upgraded subtree - every other insertion path -
+            // is left completely untouched.
+            customElements.upgrade(this);
+            // Get all pc-wasm elements that are direct children of the pc-app element
+            const wasmElements = this.querySelectorAll(':scope > pc-wasm');
+            // Wait for all modules to load
+            await Promise.all(Array.from(wasmElements).map((element) => element._getLoadPromise()));
+            // The element may have been removed while the modules loaded. Nothing beyond the loading
+            // bar exists yet, and disconnectedCallback has already destroyed that.
+            if (generation !== this._bootGeneration) {
+                return;
+            }
+            // Create and append the canvas, filling the element's content box - the page sizes the
+            // element, and everything else follows. touch-action: none keeps touch drags driving the
+            // engine's input handlers instead of scrolling the page.
+            this._canvas = document.createElement('canvas');
+            this._canvas.style.cssText = 'display: block; width: 100%; height: 100%; touch-action: none;';
+            this.appendChild(this._canvas);
+            // Configure device types based on backend selection
+            const backendToDeviceTypes = {
+                webgpu: ['webgpu', 'webgl2'], // fallback to webgl2 if webgpu not available
+                webgl2: ['webgl2'],
+                null: ['null']
+            };
+            const deviceTypes = backendToDeviceTypes[this._backend] || [];
+            this._optionsLocked = true;
+            // createGraphicsDevice appends its final null-device fallback to the array in place, so
+            // the requested list is captured now for the failure message.
+            const requested = deviceTypes.join(', ');
+            let device;
+            try {
+                device = await playcanvas.createGraphicsDevice(this._canvas, {
+                    // @ts-ignore - alpha needs to be documented
+                    alpha: this._alpha,
+                    antialias: this._antialias,
+                    depth: this._depthBuffer,
+                    deviceTypes: deviceTypes,
+                    stencil: this._stencilBuffer
+                });
+            }
+            catch (error) {
+                // The element may have been removed while device creation was failing. The teardown
+                // has already cleaned up, and the failure belongs to a boot that no longer owns the
+                // element.
+                if (generation !== this._bootGeneration) {
+                    return;
+                }
+                // Return the element to its pre-boot state - no dead canvas, no loading bar stuck at
+                // zero - before announcing the failure. Readiness deliberately stays pending: nothing
+                // it would announce (the app, the entity hierarchy) exists, so a device-less element
+                // joins the documented never-ready cases and the failure surfaces through the error
+                // event instead.
+                if (this._canvas && this.contains(this._canvas)) {
+                    this.removeChild(this._canvas);
+                }
+                this._canvas = null;
+                this._bar?.destroy();
+                this._bar = null;
+                const reason = error instanceof Error ? error.message : String(error);
+                const message = `pc-app failed to create a graphics device (${requested}) - ${reason}`;
+                console.error(message, error);
+                this.dispatchEvent(new ErrorEvent('error', { message, error }));
+                return;
+            }
+            // The element may have been removed while the device was created. disconnectedCallback
+            // has already cleaned up the canvas; the device was created inside the await, so it is
+            // this boot's to release.
+            if (generation !== this._bootGeneration) {
+                device.destroy();
+                return;
+            }
+            // Assigned rather than resolved to a number here: the engine caps against the live
+            // window.devicePixelRatio on every resize, so an uncapped Infinity keeps following the
+            // display when a window moves between monitors of differing density.
+            device.maxPixelRatio = this._maxPixelRatio;
+            const createOptions = new playcanvas.AppOptions();
+            createOptions.graphicsDevice = device;
+            createOptions.keyboard = new playcanvas.Keyboard(window);
+            createOptions.mouse = new playcanvas.Mouse(this._canvas);
+            createOptions.elementInput = new playcanvas.ElementInput(this._canvas, {
+                useMouse: true,
+                useTouch: true
+            });
+            createOptions.componentSystems = [
+                playcanvas.AnimComponentSystem,
+                playcanvas.AnimationComponentSystem,
+                playcanvas.AudioListenerComponentSystem,
+                playcanvas.ButtonComponentSystem,
+                playcanvas.CameraComponentSystem,
+                playcanvas.CollisionComponentSystem,
+                playcanvas.ElementComponentSystem,
+                playcanvas.GSplatComponentSystem,
+                playcanvas.JointComponentSystem,
+                playcanvas.LayoutChildComponentSystem,
+                playcanvas.LayoutGroupComponentSystem,
+                playcanvas.LightComponentSystem,
+                playcanvas.ModelComponentSystem,
+                playcanvas.ParticleSystemComponentSystem,
+                playcanvas.RenderComponentSystem,
+                playcanvas.RigidBodyComponentSystem,
+                playcanvas.ScreenComponentSystem,
+                playcanvas.ScriptComponentSystem,
+                playcanvas.ScrollbarComponentSystem,
+                playcanvas.ScrollViewComponentSystem,
+                playcanvas.SoundComponentSystem,
+                playcanvas.SpriteComponentSystem,
+                playcanvas.ZoneComponentSystem
+            ];
+            createOptions.resourceHandlers = [
+                playcanvas.AnimClipHandler,
+                playcanvas.AnimationHandler,
+                playcanvas.AnimStateGraphHandler,
+                playcanvas.AudioHandler,
+                playcanvas.BinaryHandler,
+                playcanvas.CssHandler,
+                playcanvas.ContainerHandler,
+                playcanvas.CubemapHandler,
+                playcanvas.FolderHandler,
+                playcanvas.FontHandler,
+                playcanvas.GSplatHandler,
+                playcanvas.HierarchyHandler,
+                playcanvas.HtmlHandler,
+                playcanvas.JsonHandler,
+                playcanvas.MaterialHandler,
+                playcanvas.ModelHandler,
+                playcanvas.RenderHandler,
+                playcanvas.ScriptHandler,
+                playcanvas.SceneHandler,
+                playcanvas.ShaderHandler,
+                playcanvas.SpriteHandler,
+                playcanvas.TemplateHandler,
+                playcanvas.TextHandler,
+                playcanvas.TextureAtlasHandler,
+                playcanvas.TextureHandler
+            ];
+            createOptions.soundManager = new playcanvas.SoundManager();
+            createOptions.lightmapper = playcanvas.Lightmapper;
+            createOptions.batchManager = playcanvas.BatchManager;
+            createOptions.xr = playcanvas.XrManager;
+            const app = new playcanvas.AppBase(this._canvas);
+            this._app = app;
+            app.init(createOptions);
+            // FILLMODE_NONE leaves the canvas's CSS sizing alone (the engine's other fill modes
+            // stamp window-derived pixel sizes onto it); RESOLUTION_AUTO sizes the drawing buffer
+            // from the canvas's client size
+            app.setCanvasFillMode(playcanvas.FILLMODE_NONE);
+            app.setCanvasResolution(playcanvas.RESOLUTION_AUTO);
+            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.
+            if (typeof ResizeObserver !== 'undefined') {
+                this._resizeObserver = new ResizeObserver(() => this._syncCanvasSize());
+                this._resizeObserver.observe(this);
+            }
+            // Get all pc-asset elements that are direct children of the pc-app element
+            const assetElements = this.querySelectorAll(':scope > pc-asset');
+            for (const assetElement of Array.from(assetElements)) {
+                assetElement._createAsset();
+                const asset = assetElement.asset;
+                if (asset) {
+                    app.assets.add(asset);
+                    // Adding a fileless asset (one built purely from data, such as a sprite)
+                    // completes it synchronously, dispatching the element's load event - whose
+                    // listeners may have removed this element. Stop before the next addition
+                    // reaches the destroyed registry, and before orphan entities are created.
+                    if (generation !== this._bootGeneration) {
+                        return;
+                    }
+                }
+            }
+            // Get all pc-material elements that are direct children of the pc-app element
+            const materialElements = this.querySelectorAll(':scope > pc-material');
+            Array.from(materialElements).forEach((materialElement) => {
+                materialElement._createMaterial();
+            });
+            // Create all entities. pc-model joins the sweep because it owns a host entity of its
+            // own; its instantiated content arrives later, beneath that host.
+            const ownerElements = this.querySelectorAll('pc-entity, pc-model');
+            Array.from(ownerElements).forEach((ownerElement) => {
+                ownerElement._createEntity(app);
+            });
+            // Build hierarchy
+            ownerElements.forEach((ownerElement) => {
+                ownerElement._buildHierarchy(app);
+            });
+            // Building the hierarchy dispatched each entity's ready event synchronously, and a
+            // listener may have removed the element. The sweep itself degrades safely - destroying
+            // the application nulls every element's entity, so the remaining builds no-op - but the
+            // teardown's reset must not be overwritten here.
+            if (generation !== this._bootGeneration) {
                 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));
+            }
+            this._hierarchyReady = true;
+            // Forward the engine's preload lifecycle as DOM ProgressEvents on this element. The
+            // listener must be attached before preload() is called: an asset that is already loaded
+            // ticks synchronously inside it.
+            const total = app.assets.list({ preload: true }).length;
+            let loaded = 0;
+            const onPreloadProgress = () => {
+                loaded += 1;
+                this._loadProgress = loaded / total;
+                this._bar?.progress(loaded, total);
+                this.dispatchEvent(new ProgressEvent('progress', { lengthComputable: true, loaded, total }));
+            };
+            app.on('preload:progress', onPreloadProgress);
+            this._loadProgress = total === 0 ? 1 : 0;
+            this._bar?.progress(0, total);
+            this.dispatchEvent(new ProgressEvent('progress', { lengthComputable: true, loaded: 0, total }));
+            // The progress dispatch above ran listeners synchronously, and one may have removed the
+            // element. The application is already destroyed - it must not be asked to preload.
+            if (generation !== this._bootGeneration) {
+                return;
+            }
+            // Load assets before starting the application
+            app.preload(() => {
+                // The element may have been removed while assets loaded. The application is already
+                // destroyed, so it must not be started — and readiness must not be signaled for a
+                // boot that no longer owns the element.
+                if (generation !== this._bootGeneration) {
+                    return;
                 }
+                // Scope the counter to this preload pass, so a later app.preload() call by user code
+                // cannot push `loaded` past `total`
+                app.off('preload:progress', onPreloadProgress);
+                this._loadProgress = 1;
+                // Start the application
+                app.start();
+                // Dismiss the bar only once a frame has actually rendered; ready fires before the
+                // first rAF tick
+                app.once('frameend', () => this._bar?.complete());
+                this._onReady();
+            });
+        }
+        disconnectedCallback() {
+            // Invalidate any boot still in flight, so it abandons itself when it next resumes
+            // instead of completing against a torn-down element.
+            this._bootGeneration++;
+            this._optionsLocked = false;
+            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) {
+                this._app.destroy();
+                this._app = null;
             }
-            // Update hover state
-            this._hoveredEntity = newHoverEntity;
-            // Handle pointermove event
-            if (newHoverEntity && newHoverEntity._hasListeners('pointermove')) {
-                newHoverEntity.dispatchEvent(new PointerEvent('pointermove', event));
+            this._entityElements.clear();
+            this._loadProgress = 0;
+            this._bar?.destroy();
+            this._bar = null;
+            // Return the element to its pre-boot state, so re-inserting it boots afresh: descendants
+            // must neither see a hierarchy that no longer exists nor resume against a readiness that
+            // no longer holds.
+            this._hierarchyReady = false;
+            this._resetReady();
+            // Stop tracking the element's size
+            this._resizeObserver?.disconnect();
+            this._resizeObserver = null;
+            // Remove the canvas
+            if (this._canvas && this.contains(this._canvas)) {
+                this.removeChild(this._canvas);
+                this._canvas = null;
             }
         }
         /**
-         * 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.
+         * Syncs the drawing buffer and the picker to the canvas's current CSS size. The picker must
+         * track the buffer, or picks would land at stale coordinates after a resize. Skipped while
+         * an XR session presents - the session owns the buffer size.
          */
-        _chainDispatch(step) {
-            this._dispatchChain = this._dispatchChain.then(step).catch((error) => {
-                console.error(error);
-            });
-        }
-        _onPointerDown(event) {
-            if (!this._picker || !this.app)
+        _syncCanvasSize() {
+            if (!this.app || this.app.xr?.active) {
                 return;
-            // Picks stay concurrent - only the dispatch of the results is serialized
-            const pick = this._pickNode(event);
-            // A click concludes on the matching pointerup, which needs to know what the press
-            // picked. Primary button only - the only button a click can conclude from - and only
-            // while click is listened for, since it is the click mapping that keeps the pointerup
-            // and pointercancel listeners attached to clean the entry up again.
-            if (this._clickListened && event.button === 0) {
-                this._downPicks.set(event.pointerId, pick);
             }
-            this._chainDispatch(async () => {
-                const node = await pick;
-                if (!this._picker)
-                    return; // the element disconnected while the pick was in flight
-                const entityElement = this._elementWithListener(node, 'pointerdown');
-                if (entityElement) {
-                    entityElement.dispatchEvent(new PointerEvent('pointerdown', event));
-                }
-            });
+            this.app.updateCanvasSize();
+            const { width, height } = this.app.graphicsDevice;
+            this._pointer.resize(width, height);
         }
-        _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 pick = this._pickNode(event);
-            this._chainDispatch(async () => {
-                const node = await pick;
-                if (!this._picker)
-                    return; // the element disconnected while the pick was in flight
-                const entityElement = this._elementWithListener(node, 'pointerup');
-                if (entityElement) {
-                    entityElement.dispatchEvent(new PointerEvent('pointerup', event));
-                }
-            });
-            // A click fires where the DOM fires it: at the nearest common inclusive ancestor of
-            // what the press and the release picked, for the primary button only. Appended after
-            // the release's own step, so it dispatches after the pointerup that concludes it.
-            if (!downPick || event.button !== 0)
-                return;
-            this._chainDispatch(async () => {
-                // A rejected pick was already reported by the press or release step that awaited it;
-                // here it just means no click can conclude.
-                const picked = await Promise.all([downPick, pick]).catch(() => null);
-                if (!picked || !this._picker)
-                    return;
-                const [downNode, upNode] = picked;
-                const clickElement = this._elementWithListener(commonAncestor(downNode, upNode), 'click');
-                if (clickElement) {
-                    const click = new PointerEvent('click', event);
-                    // The init above copied pointerup's `detail`, which the Pointer Events spec fixes
-                    // at 0 - but click is exempt: its detail is the click count, chained here as the
-                    // platform chains it (same target, within the double-click window). Overridden
-                    // with defineProperty because an event instance used as an init dict cannot have
-                    // single fields replaced.
-                    const time = performance.now();
-                    const last = this._lastClick;
-                    const count = last && last.element === clickElement && time - last.time <= CLICK_CHAIN_MS ? last.count + 1 : 1;
-                    this._lastClick = { element: clickElement, time, count };
-                    Object.defineProperty(click, 'detail', { value: count });
-                    clickElement.dispatchEvent(click);
-                }
-            });
+        /**
+         * Registers the element that fronts an entity. Called by EntityElement when it creates its
+         * entity, and by NodeElement when it binds one.
+         *
+         * @param entity - The entity.
+         * @param element - The element that fronts it.
+         * @internal
+         */
+        _registerEntityElement(entity, element) {
+            this._entityElements.set(entity, element);
         }
         /**
-         * 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.
+         * Removes the registration for a destroyed entity. Called by EntityElement.
+         *
+         * @param entity - The entity.
+         * @internal
          */
-        _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);
-                }
-            });
+        _unregisterEntityElement(entity) {
+            this._entityElements.delete(entity);
+        }
+        /**
+         * Returns the `<pc-entity>`, `<pc-model>` or `<pc-node>` element whose backing entity is
+         * `entity`, or `null` if the entity is not fronted by an element of this application - for
+         * 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;
         }
         /**
          * Warns that a graphics option was written too late to have any effect. These options are read
@@ -3281,31 +3144,133 @@
                     else {
                         this.srgb = null;
                     }
-                    break;
+                    break;
+            }
+        }
+    }
+    customElements.define('pc-asset', AssetElement);
+    /**
+     * Resolves an asset reference for use: {@link AssetElement.get}, plus starting the load of a
+     * registered asset that has not begun one - a `lazy` asset. Every element that consumes assets
+     * resolves its references here, which is what makes `lazy` mean load on first use without any
+     * consumer having to remember the load. The load is asynchronous - callers observe the asset's
+     * `load` event for the resource.
+     *
+     * @param id - The `id` of the `<pc-asset>` element.
+     * @returns The asset, or `undefined`.
+     * @internal
+     */
+    const useAsset = (id) => {
+        const asset = AssetElement.get(id);
+        // load() ignores an asset that is already loaded or loading, so repeated resolution
+        // costs nothing.
+        if (asset) {
+            asset.registry?.load(asset);
+        }
+        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;
         }
     }
-    customElements.define('pc-asset', AssetElement);
-    /**
-     * Resolves an asset reference for use: {@link AssetElement.get}, plus starting the load of a
-     * registered asset that has not begun one - a `lazy` asset. Every element that consumes assets
-     * resolves its references here, which is what makes `lazy` mean load on first use without any
-     * consumer having to remember the load. The load is asynchronous - callers observe the asset's
-     * `load` event for the resource.
-     *
-     * @param id - The `id` of the `<pc-asset>` element.
-     * @returns The asset, or `undefined`.
-     * @internal
-     */
-    const useAsset = (id) => {
-        const asset = AssetElement.get(id);
-        // load() ignores an asset that is already loaded or loading, so repeated resolution
-        // costs nothing.
-        if (asset) {
-            asset.registry?.load(asset);
-        }
-        return asset;
-    };
 
     /**
      * Formats one line of the printable hierarchy: the node's name, an `[index]` marker when the
@@ -3407,18 +3372,18 @@
         _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,
@@ -3509,7 +3474,7 @@
             // 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();
         }
         /**
@@ -3528,16 +3493,10 @@
          */
         _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
@@ -3564,7 +3523,7 @@
             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();
@@ -3590,39 +3549,23 @@
                 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`);
             }
         }
         /**
@@ -3757,6 +3700,8 @@
                 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() {
@@ -4019,6 +3964,9 @@
          */
         _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) {
@@ -4091,7 +4039,7 @@
          * 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.
@@ -4399,8 +4347,9 @@
             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;
@@ -4549,6 +4498,11 @@
          */
         _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
@@ -4556,19 +4510,13 @@
          * 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;
@@ -4608,7 +4556,7 @@
             // 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.
@@ -4626,12 +4574,6 @@
             }
             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.
          *
@@ -4657,34 +4599,19 @@
         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;
@@ -4791,99 +4718,321 @@
             this._loop = value;
             this._animElement?._onClipParamsChanged(this);
         }
-        /**
-         * Gets whether the clip loops.
-         * @returns Whether the clip loops.
-         */
-        get loop() {
-            return this._loop;
+        /**
+         * Gets whether the clip loops.
+         * @returns Whether the clip loops.
+         */
+        get loop() {
+            return this._loop;
+        }
+        /**
+         * Sets the name of the clip: the name it is played by, and the track looked up in the
+         * clip's source. Names must be unique within a `<pc-anim>` and must not contain `.`.
+         * @param value - The clip name.
+         */
+        set name(value) {
+            this._name = value;
+            this._warnedInvalid = false;
+            if (this._animElement) {
+                this._resetReady();
+                this._animElement._refreshClips();
+            }
+        }
+        /**
+         * Gets the name of the clip.
+         * @returns The clip name.
+         */
+        get name() {
+            return this._name;
+        }
+        /**
+         * Sets the playback speed of the clip, where negative values play it backwards. Applies
+         * immediately, preserving the playhead. Defaults to 1.
+         * @param value - The playback speed.
+         */
+        set speed(value) {
+            this._speed = value;
+            this._animElement?._onClipParamsChanged(this);
+        }
+        /**
+         * Gets the playback speed of the clip.
+         * @returns The playback speed.
+         */
+        get speed() {
+            return this._speed;
+        }
+        static get observedAttributes() {
+            return ['asset', 'loop', 'name', 'speed'];
+        }
+        attributeChangedCallback(name, _oldValue, newValue) {
+            switch (name) {
+                case 'asset':
+                    this.asset = newValue ?? '';
+                    break;
+                case 'loop':
+                    this.loop = parseBool(newValue, true);
+                    break;
+                case 'name':
+                    this.name = newValue ?? '';
+                    break;
+                case 'speed':
+                    this.speed = parseNumber(newValue, 1, name);
+                    break;
+            }
+        }
+    }
+    customElements.define('pc-anim-clip', AnimClipElement);
+
+    /**
+     * The AudioListenerComponentElement interface provides properties and methods for manipulating
+     * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-audio-listener/ | `<pc-audio-listener>`} elements.
+     * The AudioListenerComponentElement interface also inherits the properties and methods of the
+     * {@link HTMLElement} interface.
+     *
+     * Engine component: {@link AudioListenerComponent} (`audiolistener`).
+     *
+     * @elementSummary The `<pc-audio-listener>` element makes its entity the point from which
+     * positional sounds are heard, typically the entity holding the `<pc-camera>`. Must be a child of a
+     * `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+     *
+     * @category Components
+     */
+    class AudioListenerComponentElement extends ComponentElement {
+        /** @ignore */
+        constructor() {
+            super('audiolistener');
+        }
+        /**
+         * 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;
+        }
+    }
+    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);
         }
-        /**
-         * Sets the name of the clip: the name it is played by, and the track looked up in the
-         * clip's source. Names must be unique within a `<pc-anim>` and must not contain `.`.
-         * @param value - The clip name.
-         */
-        set name(value) {
-            this._name = value;
-            this._warnedInvalid = false;
-            if (this._animElement) {
-                this._resetReady();
-                this._animElement._refreshClips();
+        // 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);
             }
-        }
-        /**
-         * Gets the name of the clip.
-         * @returns The clip name.
-         */
-        get name() {
-            return this._name;
-        }
-        /**
-         * Sets the playback speed of the clip, where negative values play it backwards. Applies
-         * immediately, preserving the playhead. Defaults to 1.
-         * @param value - The playback speed.
-         */
-        set speed(value) {
-            this._speed = value;
-            this._animElement?._onClipParamsChanged(this);
-        }
-        /**
-         * Gets the playback speed of the clip.
-         * @returns The playback speed.
-         */
-        get speed() {
-            return this._speed;
-        }
-        static get observedAttributes() {
-            return ['asset', 'loop', 'name', 'speed'];
-        }
-        attributeChangedCallback(name, _oldValue, newValue) {
-            switch (name) {
-                case 'asset':
-                    this.asset = newValue ?? '';
-                    break;
-                case 'loop':
-                    this.loop = parseBool(newValue, true);
-                    break;
-                case 'name':
-                    this.name = newValue ?? '';
-                    break;
-                case 'speed':
-                    this.speed = parseNumber(newValue, 1, name);
-                    break;
+            const app = from.parentElement?.closest('pc-app');
+            if (app) {
+                const element = queryScope(app, nameSelector);
+                if (element) {
+                    return element;
+                }
             }
         }
-    }
-    customElements.define('pc-anim-clip', AnimClipElement);
-
+        return query(nameSelector);
+    };
     /**
-     * The AudioListenerComponentElement interface provides properties and methods for manipulating
-     * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-audio-listener/ | `<pc-audio-listener>`} elements.
-     * The AudioListenerComponentElement interface also inherits the properties and methods of the
-     * {@link HTMLElement} interface.
+     * 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.
      *
-     * Engine component: {@link AudioListenerComponent} (`audiolistener`).
+     * @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.
      *
-     * @elementSummary The `<pc-audio-listener>` element makes its entity the point from which
-     * positional sounds are heard, typically the entity holding the `<pc-camera>`. Must be a child of a
-     * `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+     * @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.
      *
-     * @category Components
+     * @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
      */
-    class AudioListenerComponentElement extends ComponentElement {
-        /** @ignore */
-        constructor() {
-            super('audiolistener');
+    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;
         }
-        /**
-         * Gets the underlying PlayCanvas audio listener component.
-         * @returns The audio listener component.
-         */
-        get component() {
-            return super.component;
+        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}`);
         }
-    }
-    customElements.define('pc-audio-listener', AudioListenerComponentElement);
+        return entity;
+    };
 
     const transitionModes = new Map([
         ['tint', playcanvas.BUTTON_TRANSITION_MODE_TINT],
@@ -4959,8 +5108,9 @@
             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;
@@ -5418,8 +5568,9 @@
             }
         }
         /**
-         * 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;
@@ -5908,8 +6059,9 @@
             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;
@@ -6147,8 +6299,9 @@
             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;
@@ -6925,8 +7078,9 @@
             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;
@@ -7652,8 +7806,9 @@
             };
         }
         /**
-         * 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;
@@ -7872,8 +8027,9 @@
             };
         }
         /**
-         * 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;
@@ -8162,8 +8318,9 @@
             };
         }
         /**
-         * 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;
@@ -8679,36 +8836,68 @@
      */
     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)) {
@@ -8716,20 +8905,10 @@
                 }
             }
         }
-        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.
@@ -8738,7 +8917,7 @@
         set asset(value) {
             this._asset = value;
             if (this.isConnected) {
-                this._loadAsset();
+                this._bindConfig();
             }
         }
         /**
@@ -8955,11 +9134,12 @@
         _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;
         /**
@@ -9086,10 +9266,9 @@
             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;
@@ -9135,16 +9314,23 @@
                 '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) {
@@ -9152,17 +9338,9 @@
                 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.
@@ -11058,8 +11236,9 @@
             };
         }
         /**
-         * 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;
@@ -11230,8 +11409,9 @@
             };
         }
         /**
-         * 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;
@@ -11410,8 +11590,9 @@
             };
         }
         /**
-         * 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;
@@ -11568,8 +11749,9 @@
             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;
@@ -11745,8 +11927,9 @@
             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;
@@ -12898,8 +13081,9 @@
             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;
@@ -12945,8 +13129,9 @@
             };
         }
         /**
-         * 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;
@@ -13427,8 +13612,9 @@
             };
         }
         /**
-         * 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;
@@ -14721,31 +14907,27 @@
         _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;
@@ -14777,7 +14959,7 @@
         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) {
@@ -14788,26 +14970,18 @@
                 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;