@playcanvas/web-components 0.12.0 → 0.13.1

package/dist/pwc.js

@@ -1,7 +1,7 @@
 (function (global, factory) {
     typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports, require('playcanvas')) :
     typeof define === 'function' && define.amd ? define(['exports', 'playcanvas'], factory) :
-    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.pd = {}, global.pc));
+    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.pwc = {}, global.pc));
 })(this, (function (exports, playcanvas) { 'use strict';
 
     /**
@@ -112,12 +112,18 @@
 
     /**
      * The ModuleElement interface provides properties and methods for manipulating
-     * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-module/ | `<pc-module>`} elements.
-     * The ModuleElement interface also inherits the properties and methods of the
-     * {@link HTMLElement} interface.
+     * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-module/ | `<pc-module>`}
+     * elements. The ModuleElement interface also inherits the properties and methods of the
+     * {@link AsyncElement} interface.
+     *
+     * The attributes are read once, when the module starts loading - on the element's first
+     * connection, or earlier if a containing `<pc-app>` boots first and collects it - so changing
+     * them later has no effect. The element becomes ready once the module has loaded. WebAssembly
+     * modules configure engine-global state that never unloads, so readiness is not re-armed by
+     * removing the element, and a re-inserted element does not load again.
      *
-     * Note that these attributes are read once when the element is created, so changing them later
-     * has no effect.
+     * A `<pc-module>` without a `name` warns and never becomes ready; a containing `<pc-app>` still
+     * boots.
      *
      * @attribute {string} name - The name of the WebAssembly module to configure, e.g. `Basis` or
      * `Ammo`.
@@ -126,19 +132,22 @@
      * @attribute {string} fallback - The URL of the module's asm.js fallback script, used when
      * WebAssembly is unavailable.
      */
-    class ModuleElement extends HTMLElement {
-        loadPromise;
-        /** @ignore */
-        constructor() {
-            super();
-            this.loadPromise = this.loadModule();
+    class ModuleElement extends AsyncElement {
+        _loadPromise = null;
+        connectedCallback() {
+            this._getLoadPromise();
         }
-        async loadModule() {
+        async _loadModule() {
             const name = this.getAttribute('name');
-            const glueUrl = this.getAttribute('glue');
-            const wasmUrl = this.getAttribute('wasm');
-            const fallbackUrl = this.getAttribute('fallback');
-            const config = { glueUrl, wasmUrl, fallbackUrl };
+            if (!name) {
+                console.warn("pc-module requires a 'name' attribute - no module was configured");
+                return;
+            }
+            const config = {
+                glueUrl: this.getAttribute('glue') ?? undefined,
+                wasmUrl: this.getAttribute('wasm') ?? undefined,
+                fallbackUrl: this.getAttribute('fallback') ?? undefined
+            };
             if (name === 'Basis') {
                 playcanvas.basisInitialize(config);
             }
@@ -148,16 +157,22 @@
                     playcanvas.WasmModule.getInstance(name, () => resolve());
                 });
             }
+            this._onReady();
         }
         /**
-         * Returns the promise that settles when the module has loaded. Awaited by the containing
-         * `<pc-app>` element before it creates its graphics device.
+         * Returns the promise that settles when the module has loaded, starting the load if it has
+         * not already started - a containing `<pc-app>` boots in document order, so it may collect
+         * this element before the element's own connectedCallback has run. A missing `name` resolves
+         * the promise without configuring anything, so a misconfigured module never blocks the app.
          *
          * @returns The load promise.
          * @internal
          */
         _getLoadPromise() {
-            return this.loadPromise;
+            if (!this._loadPromise) {
+                this._loadPromise = this._loadModule();
+            }
+            return this._loadPromise;
         }
     }
     customElements.define('pc-module', ModuleElement);
@@ -187,9 +202,9 @@
             this._track.setAttribute('aria-label', 'Loading');
             this._track.setAttribute('aria-valuemin', '0');
             this._track.setAttribute('aria-valuemax', '100');
-            // Fixed positioning matches the canvas, which always fills the window (FILLMODE_FILL_WINDOW)
+            // Anchored to the pc-app element, which the library's base styles make a positioned box
             this._track.style.cssText = [
-                'position: fixed',
+                'position: absolute',
                 'top: 0',
                 'left: 0',
                 'width: 100%',
@@ -701,16 +716,44 @@
 
     /** The pointer event types the application synthesizes on `<pc-entity>` elements via picking. */
     const pointerEventTypes = ['pointermove', 'pointerdown', 'pointerup', 'pointerenter', 'pointerleave'];
+    /**
+     * 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`.
+     *
      * @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 {
         /**
@@ -770,6 +813,12 @@
         };
         _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()`
@@ -796,8 +845,6 @@
          */
         constructor() {
             super();
-            // Bind methods to maintain 'this' context
-            this._onWindowResize = this._onWindowResize.bind(this);
             // Track pointer listeners being added to and removed from descendant entities.
             // Registered once here rather than on every boot - the handlers no-op while there is no
             // canvas, and a re-booted element must not stack a second set.
@@ -808,6 +855,9 @@
         }
         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) {
@@ -822,8 +872,11 @@
             if (generation !== this._bootGeneration) {
                 return;
             }
-            // Create and append the canvas to the element
+            // 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 = {
@@ -833,14 +886,44 @@
             };
             const deviceTypes = backendToDeviceTypes[this._backend] || [];
             this._optionsLocked = true;
-            const 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
-            });
+            // 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.
@@ -919,9 +1002,19 @@
             const app = new playcanvas.AppBase(this._canvas);
             this._app = app;
             app.init(createOptions);
-            app.setCanvasFillMode(playcanvas.FILLMODE_FILL_WINDOW);
+            // 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)) {
@@ -997,8 +1090,6 @@
                 // Dismiss the bar only once a frame has actually rendered; ready fires before the
                 // first rAF tick
                 app.once('frameend', () => this._bar?.complete());
-                // Handle window resize to keep the canvas responsive
-                window.addEventListener('resize', this._onWindowResize);
                 this._onReady();
             });
         }
@@ -1023,18 +1114,27 @@
             // no longer holds.
             this._hierarchyReady = false;
             this._resetReady();
-            // Remove event listeners
-            window.removeEventListener('resize', this._onWindowResize);
+            // 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;
             }
         }
-        _onWindowResize() {
-            if (this.app) {
-                this.app.resizeCanvas();
+        /**
+         * 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.
+         */
+        _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;
@@ -1152,21 +1252,63 @@
             }
             return null;
         }
-        // New helper to convert CSS coordinates to canvas (picker) coordinates
-        _getPickerCoordinates(event) {
-            // Get the canvas' bounding rectangle in CSS pixels.
-            const canvasRect = this._canvas.getBoundingClientRect();
-            // Compute scale factors based on canvas actual resolution vs. its CSS display size.
-            const scaleX = this._canvas.width / canvasRect.width;
-            const scaleY = this._canvas.height / canvasRect.height;
-            // Convert the client coordinates accordingly.
-            const x = (event.clientX - canvasRect.left) * scaleX;
-            const y = (event.clientY - canvasRect.top) * scaleY;
-            return { x, y };
+        /**
+         * Converts a pointer event's client coordinates into drawing-buffer coordinates - the space
+         * the pick buffer and the camera viewports are laid out in. When the canvas has no CSS box
+         * to map through (jsdom; a hidden canvas receives no pointer events in a browser), the
+         * client coordinates are passed through unmapped and `mapped` is false, so callers know the
+         * coordinates correspond to no real geometry.
+         *
+         * @param event - The pointer event to convert.
+         * @param canvas - The canvas the event was dispatched on.
+         * @returns The buffer-space coordinates, and whether they were actually mapped.
+         */
+        _getPickerCoordinates(event, canvas) {
+            const canvasRect = canvas.getBoundingClientRect();
+            if (canvasRect.width === 0 || canvasRect.height === 0) {
+                return { x: event.clientX, y: event.clientY, mapped: false };
+            }
+            const scaleX = canvas.width / canvasRect.width;
+            const scaleY = canvas.height / canvasRect.height;
+            return {
+                x: (event.clientX - canvasRect.left) * scaleX,
+                y: (event.clientY - canvasRect.top) * scaleY,
+                mapped: true
+            };
+        }
+        /**
+         * Whether a camera's viewport contains the point. A camera renders into its normalized
+         * `rect`, whose origin is the bottom-left of the canvas while buffer coordinates run from
+         * the top-left - so the vertical test flips, as the engine's ElementInput flips it for UI
+         * input. The right and bottom edges are exclusive: a viewport rasterizes the half-open
+         * pixel range [left, right) x [top, bottom), so a coordinate on a shared edge belongs to
+         * the viewport whose first pixel it is - never to the one it just left, whose pick buffer
+         * holds nothing there.
+         *
+         * @param camera - The camera to test.
+         * @param x - The x coordinate, in buffer space.
+         * @param y - The y coordinate, in buffer space.
+         * @param canvas - The canvas the coordinates are relative to.
+         * @returns Whether the camera's viewport contains the point.
+         */
+        _cameraContains(camera, x, y, canvas) {
+            const rect = camera.rect;
+            const left = rect.x * canvas.width;
+            const bottom = (1 - rect.y) * canvas.height;
+            const top = bottom - rect.w * canvas.height;
+            return x >= left && x < left + rect.z * canvas.width && y >= top && y < bottom;
         }
         /**
          * Picks the scene under the pointer and returns the graph node that was hit, or `null`.
          *
+         * The camera is resolved the way the engine's ElementInput resolves it for UI input:
+         * enabled cameras are tried topmost-first (they render in ascending `priority` order),
+         * skipping cameras that render to a texture and cameras whose viewport `rect` does not
+         * contain the pointer. A camera that picks nothing ends the search if it clears the color
+         * buffer - its background visually owns the pixel - and otherwise cedes to the cameras
+         * beneath it, so an overlay camera only intercepts picks where it actually drew something.
+         * The pick buffer is prepared per camera, so each camera picks from its own layers.
+         *
          * The read back is asynchronous because the synchronous {@link Picker.getSelection} is not
          * supported on WebGPU, where it returns an empty selection rather than failing - which
          * silently disabled every `onpointer*` handler once WebGPU became the resolved backend. The
@@ -1176,16 +1318,40 @@
          * @returns The graph node under the pointer, or `null` if nothing was hit.
          */
         async _pickNode(event) {
-            const camera = this.app.root.findComponent('camera');
-            if (!camera)
-                return null;
-            const { x, y } = this._getPickerCoordinates(event);
-            this._picker.prepare(camera, this.app.scene);
-            const selection = await this._picker.getSelectionAsync(x, y);
-            if (selection.length === 0)
+            const app = this.app;
+            const picker = this._picker;
+            const canvas = this._canvas;
+            if (!app || !picker || !canvas)
                 return null;
-            const item = selection[0];
-            return item instanceof playcanvas.MeshInstance ? item.node : item.entity;
+            const { x, y, mapped } = this._getPickerCoordinates(event, canvas);
+            // Walked from the end: the array is sorted by ascending priority, so the last camera
+            // renders last and sits on top. Read through .at() because a pick handler may remove
+            // cameras while an earlier iteration's read back is in flight.
+            const cameras = app.systems.camera?.cameras ?? [];
+            for (let i = cameras.length - 1; i >= 0; i--) {
+                const camera = cameras.at(i);
+                // A camera rendering to a texture is not on the canvas.
+                if (!camera || camera.renderTarget)
+                    continue;
+                // Coordinates that could not be mapped cannot be tested for containment.
+                if (mapped && !this._cameraContains(camera, x, y, canvas))
+                    continue;
+                picker.prepare(camera, app.scene);
+                const selection = await picker.getSelectionAsync(x, y);
+                // The element may have disconnected while the read back was in flight.
+                if (!this._picker || !this.app)
+                    return null;
+                if (selection.length > 0) {
+                    const item = selection[0];
+                    return item instanceof playcanvas.MeshInstance ? item.node : item.entity;
+                }
+                // Nothing hit. A camera that clears the color buffer paints its background over
+                // everything beneath it, so the miss is final; one that does not is an overlay
+                // that the cameras beneath show through, so they get their turn.
+                if (camera.clearColorBuffer)
+                    return null;
+            }
+            return null;
         }
         async _onPointerMove(event) {
             if (!this._picker || !this.app)
@@ -1372,7 +1538,7 @@
             this._maxPixelRatio = value;
             if (this.app) {
                 this.app.graphicsDevice.maxPixelRatio = value;
-                this.app.resizeCanvas();
+                this._syncCanvasSize();
             }
         }
         /**
@@ -2129,6 +2295,10 @@
      * immediately unless `lazy`. A `pc-asset` must be a direct child of `pc-app` — elements placed
      * elsewhere, or with an unsupported asset type, never become ready.
      *
+     * A `lazy` asset loads on first use: the first time any element resolves it by `id` — a model,
+     * a material map, a sky, a script `asset:` reference — or when the `lazy` attribute is removed,
+     * whichever comes first. Until then it stays registered and unloaded.
+     *
      * For `texture` and `textureatlas` assets, the texture options (`address-u`, `address-v`,
      * `min-filter`, `mag-filter`, `anisotropy`, `mipmaps`, `srgb`, `flip-y`) apply when the texture is
      * created and — like `lazy` — are observed: changing one updates a texture that has already
@@ -2328,7 +2498,9 @@
             if (type === 'sprite') {
                 data = data ?? {};
                 // Resolve the referenced texture atlas to its (numeric) asset id. The atlas must be
-                // declared before the sprite so its asset already exists in the registry.
+                // declared before the sprite so its asset already exists in the registry. Resolved
+                // with get, not useAsset: creation-time wiring is not a use, and the engine's
+                // sprite handler loads the atlas when the sprite itself loads.
                 const atlas = this.getAttribute('atlas') ?? data.textureAtlasAsset;
                 if (typeof atlas === 'string') {
                     const atlasAsset = AssetElement.get(atlas);
@@ -2489,13 +2661,18 @@
             return this._flipY;
         }
         /**
-         * Sets whether the asset should be loaded lazily.
+         * Sets whether the asset should be loaded lazily. A lazy asset is registered without being
+         * loaded; it loads on first use - the first time any element resolves it by `id` - or when
+         * this flag is cleared on a registered asset, whichever comes first.
          * @param value - The lazy loading flag.
          */
         set lazy(value) {
             this._lazy = value;
             if (this.asset) {
                 this.asset.preload = !value;
+                if (!value) {
+                    this.asset.registry?.load(this.asset);
+                }
             }
         }
         /**
@@ -2679,6 +2856,26 @@
         }
     }
     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;
+    };
 
     /**
      * Represents a component in the PlayCanvas engine.
@@ -2962,15 +3159,15 @@
             if (imageEntity) {
                 data.imageEntity = imageEntity;
             }
-            const hoverSpriteAsset = AssetElement.get(this._hoverSpriteAsset);
+            const hoverSpriteAsset = useAsset(this._hoverSpriteAsset);
             if (hoverSpriteAsset) {
                 data.hoverSpriteAsset = hoverSpriteAsset.id;
             }
-            const pressedSpriteAsset = AssetElement.get(this._pressedSpriteAsset);
+            const pressedSpriteAsset = useAsset(this._pressedSpriteAsset);
             if (pressedSpriteAsset) {
                 data.pressedSpriteAsset = pressedSpriteAsset.id;
             }
-            const inactiveSpriteAsset = AssetElement.get(this._inactiveSpriteAsset);
+            const inactiveSpriteAsset = useAsset(this._inactiveSpriteAsset);
             if (inactiveSpriteAsset) {
                 data.inactiveSpriteAsset = inactiveSpriteAsset.id;
             }
@@ -3132,7 +3329,7 @@
          */
         set hoverSpriteAsset(value) {
             this._hoverSpriteAsset = value;
-            const asset = AssetElement.get(value);
+            const asset = useAsset(value);
             if (this.component && asset) {
                 this.component.hoverSpriteAsset = asset.id;
             }
@@ -3168,7 +3365,7 @@
          */
         set pressedSpriteAsset(value) {
             this._pressedSpriteAsset = value;
-            const asset = AssetElement.get(value);
+            const asset = useAsset(value);
             if (this.component && asset) {
                 this.component.pressedSpriteAsset = asset.id;
             }
@@ -3204,7 +3401,7 @@
          */
         set inactiveSpriteAsset(value) {
             this._inactiveSpriteAsset = value;
-            const asset = AssetElement.get(value);
+            const asset = useAsset(value);
             if (this.component && asset) {
                 this.component.inactiveSpriteAsset = asset.id;
             }
@@ -4062,15 +4259,15 @@
             };
             // Asset references are resolved from `<pc-asset>` element ids to engine asset ids. They are
             // only included when they resolve, so image/group elements (with no font) don't error.
-            const fontAsset = AssetElement.get(this._fontAsset);
+            const fontAsset = useAsset(this._fontAsset);
             if (fontAsset) {
                 data.fontAsset = fontAsset.id;
             }
-            const spriteAsset = AssetElement.get(this._spriteAsset);
+            const spriteAsset = useAsset(this._spriteAsset);
             if (spriteAsset) {
                 data.spriteAsset = spriteAsset.id;
             }
-            const textureAsset = AssetElement.get(this._textureAsset);
+            const textureAsset = useAsset(this._textureAsset);
             if (textureAsset) {
                 data.textureAsset = textureAsset.id;
             }
@@ -4184,7 +4381,7 @@
          */
         set fontAsset(value) {
             this._fontAsset = value;
-            const asset = AssetElement.get(value);
+            const asset = useAsset(value);
             if (this.component && asset) {
                 this.component.fontAsset = asset.id;
             }
@@ -4339,7 +4536,7 @@
          */
         set spriteAsset(value) {
             this._spriteAsset = value;
-            const asset = AssetElement.get(value);
+            const asset = useAsset(value);
             if (this.component && asset) {
                 this.component.spriteAsset = asset.id;
             }
@@ -4391,7 +4588,7 @@
          */
         set textureAsset(value) {
             this._textureAsset = value;
-            const asset = AssetElement.get(value);
+            const asset = useAsset(value);
             if (this.component && asset) {
                 this.component.textureAsset = asset.id;
             }
@@ -5626,13 +5823,14 @@
             super('particlesystem');
         }
         getInitialComponentData() {
-            const asset = AssetElement.get(this._asset);
-            if (!asset) {
+            const asset = useAsset(this._asset);
+            // A lazy config has no resource yet - _loadAsset applies it once the load completes
+            if (!asset || !asset.resource) {
                 return {};
             }
             if (asset.resource.colorMapAsset) {
                 const id = asset.resource.colorMapAsset;
-                const colorMapAsset = AssetElement.get(id)?.id;
+                const colorMapAsset = useAsset(id)?.id;
                 if (colorMapAsset) {
                     asset.resource.colorMapAsset = colorMapAsset;
                 }
@@ -5658,9 +5856,8 @@
             }
         }
         async _loadAsset() {
-            const appElement = await this.closestApp?.ready();
-            const app = appElement?.app;
-            const asset = AssetElement.get(this._asset);
+            await this.closestApp?.ready();
+            const asset = useAsset(this._asset);
             if (!asset) {
                 return;
             }
@@ -5671,7 +5868,6 @@
                 asset.once('load', () => {
                     this.applyConfig(asset.resource);
                 });
-                app.assets.load(asset);
             }
         }
         /**
@@ -6087,7 +6283,7 @@
                 this._scheduleUpdate();
                 return;
             }
-            const asset = AssetElement.get(id);
+            const asset = useAsset(id);
             if (!asset)
                 return;
             if (asset.loaded) {
@@ -9188,7 +9384,7 @@
      * @returns The asset, or `raw`.
      */
     const assetConversion = (rest, raw) => {
-        const asset = AssetElement.get(rest);
+        const asset = useAsset(rest);
         if (asset) {
             return asset;
         }
@@ -10008,7 +10204,7 @@
         set asset(value) {
             this._asset = value;
             if (this.soundSlot) {
-                const id = AssetElement.get(value)?.id;
+                const id = useAsset(value)?.id;
                 if (id) {
                     this.soundSlot.asset = id;
                 }
@@ -10215,7 +10411,7 @@
         }
         getInitialComponentData() {
             return {
-                asset: AssetElement.get(this._asset),
+                asset: useAsset(this._asset),
                 castShadows: this._castShadows,
                 lodBaseDistance: this._lodBaseDistance,
                 lodMultiplier: this._lodMultiplier,
@@ -10236,7 +10432,7 @@
          */
         set asset(value) {
             this._asset = value;
-            const asset = AssetElement.get(value);
+            const asset = useAsset(value);
             if (this.component && asset) {
                 this.component.asset = asset;
             }
@@ -10514,8 +10710,7 @@
             if (generation !== this._loadGeneration) {
                 return;
             }
-            const app = appElement.app;
-            const asset = AssetElement.get(this._asset);
+            const asset = useAsset(this._asset);
             if (!asset) {
                 // An empty id is a legitimate transient (the asset may be assigned later); a
                 // non-empty one that resolves to nothing is a dead end - say so rather than staying
@@ -10551,7 +10746,6 @@
                     }));
                     this._onReady();
                 });
-                app.assets.load(asset);
             }
         }
         _unloadModel() {
@@ -11516,7 +11710,7 @@
                 return;
             }
             this._appElement = appElement;
-            const asset = AssetElement.get(this._asset);
+            const asset = useAsset(this._asset);
             if (!asset) {
                 return;
             }
@@ -11535,7 +11729,6 @@
                     }
                     this._generateSkybox(asset);
                 });
-                app.assets.load(asset);
             }
         }
         _unloadSkybox() {