@playcanvas/web-components 0.9.0 → 0.10.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcanvas/web-components",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "author": "PlayCanvas <support@playcanvas.com>",
   "homepage": "https://playcanvas.com",
   "description": "Web Components for the PlayCanvas Engine",
@@ -25,8 +25,11 @@
   },
   "main": "dist/pwc.cjs",
   "module": "dist/pwc.mjs",
-  "browser": "dist/pwc.js",
+  "unpkg": "dist/pwc.min.js",
+  "jsdelivr": "dist/pwc.min.js",
   "types": "dist/index.d.ts",
+  "customElements": "dist/custom-elements.json",
+  "web-types": "dist/web-types.json",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -44,21 +47,31 @@
   "scripts": {
     "prebuild": "node -e \"fs.rmSync('dist', { recursive: true, force: true })\"",
     "build": "rollup -c",
+    "postbuild": "npm run cem",
+    "cem": "cem analyze && node utils/cem/validate.mjs",
     "dev": "concurrently \"npm run watch\" \"npm run serve\"",
     "docs": "typedoc",
-    "lint": "eslint examples/js examples/assets/scripts src",
+    "lint": "eslint examples/js examples/assets/scripts src test vitest.config.ts",
     "serve": "serve",
-    "test": "echo \"Error: no test specified\" && exit 1",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:unit": "vitest run --project unit",
+    "test:elements": "vitest run --project elements",
+    "test:integration": "vitest run --project integration",
     "publint": "publint",
-    "type-check": "tsc --noEmit",
-    "type-check:watch": "npm run type-check -- --watch",
+    "type-check": "npm run type-check:src && npm run type-check:test",
+    "type-check:src": "tsc --noEmit -p tsconfig.json",
+    "type-check:test": "tsc --noEmit -p tsconfig.test.json",
+    "type-check:watch": "npm run type-check:src -- --watch",
     "watch": "rollup -c -w"
   },
   "peerDependencies": {
     "playcanvas": "^2.20.1"
   },
   "devDependencies": {
-    "@mediapipe/tasks-vision": "1.0.0",
+    "@custom-elements-manifest/analyzer": "0.11.0",
+    "@mediapipe/tasks-vision": "1.0.1",
     "@playcanvas/eslint-config": "2.1.0",
     "@rollup/plugin-commonjs": "29.0.3",
     "@rollup/plugin-node-resolve": "16.0.3",
@@ -67,20 +80,25 @@
     "@tweenjs/tween.js": "25.0.0",
     "@typescript-eslint/eslint-plugin": "8.65.0",
     "@typescript-eslint/parser": "8.65.0",
+    "@vitest/coverage-v8": "4.1.10",
     "concurrently": "10.0.4",
+    "custom-element-jet-brains-integration": "1.7.0",
+    "custom-element-vs-code-integration": "1.5.0",
     "earcut": "3.2.3",
     "eslint": "9.39.5",
     "eslint-import-resolver-typescript": "4.4.5",
-    "globals": "17.8.0",
-    "mediabunny": "1.51.0",
+    "globals": "17.9.0",
+    "jsdom": "30.0.1",
+    "mediabunny": "1.52.2",
     "opentype.js": "2.0.0",
     "playcanvas": "2.21.3",
     "publint": "0.3.22",
-    "rollup": "4.62.3",
+    "rollup": "4.62.4",
     "serve": "14.2.6",
     "tslib": "2.8.1",
     "typedoc": "0.28.20",
     "typedoc-plugin-mdn-links": "5.1.1",
-    "typescript": "6.0.3"
+    "typescript": "6.0.3",
+    "vitest": "4.1.10"
   }
 }

package/src/app.ts

@@ -69,15 +69,21 @@ import {
 import { AssetElement } from './asset';
 import { AsyncElement } from './async-element';
 import { EntityElement } from './entity';
+import { LoadingBar } from './loading-bar';
 import { MaterialElement } from './material';
 import { ModuleElement } from './module';
-import { parseBool, parseEnum } from './utils';
+import { parseBool, parseEnum } from './parse';
 
 /**
  * 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.
+ *
+ * @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.
  */
 class AppElement extends AsyncElement {
     /**
@@ -87,7 +93,7 @@ class AppElement extends AsyncElement {
 
     private _alpha = true;
 
-    private _backend: 'webgpu' | 'webgl2' | 'null' = 'webgl2';
+    private _backend: 'webgpu' | 'webgl2' | 'null' = 'webgpu';
 
     private _antialias = true;
 
@@ -97,6 +103,10 @@ class AppElement extends AsyncElement {
 
     private _highResolution = true;
 
+    private _loadingBar = true;
+
+    private _bar: LoadingBar | null = null;
+
     private _hierarchyReady = false;
 
     private _picker: Picker | null = null;
@@ -111,6 +121,9 @@ class AppElement extends AsyncElement {
 
     private _hoveredEntity: EntityElement | null = null;
 
+    // Identifies the newest in-flight hover pick, so out-of-order results can be discarded
+    private _pickToken = 0;
+
     private _pointerHandlers: { [key: string]: EventListener | null } = {
         pointermove: null,
         pointerdown: null,
@@ -119,13 +132,27 @@ class AppElement extends AsyncElement {
 
     private _app: AppBase | null = null;
 
+    private _loadProgress = 0;
+
     /**
-     * The PlayCanvas application instance. Available once the element is ready — await
-     * {@link whenReady} or the element's `ready()` promise before accessing it.
-     * @returns The application instance.
+     * 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(): AppBase {
-        return this._app!;
+    get app(): AppBase | null {
+        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(): number {
+        return this._loadProgress;
     }
 
     /**
@@ -141,6 +168,12 @@ class AppElement extends AsyncElement {
     }
 
     async connectedCallback() {
+        // 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);
+        }
+
         // Get all pc-module elements that are direct children of the pc-app element
         const moduleElements = this.querySelectorAll<ModuleElement>(':scope > pc-module');
 
@@ -234,11 +267,12 @@ class AppElement extends AsyncElement {
         createOptions.batchManager = BatchManager;
         createOptions.xr = XrManager;
 
-        this._app = new AppBase(this._canvas);
-        this.app.init(createOptions);
+        const app = new AppBase(this._canvas);
+        this._app = app;
+        app.init(createOptions);
 
-        this.app.setCanvasFillMode(FILLMODE_FILL_WINDOW);
-        this.app.setCanvasResolution(RESOLUTION_AUTO);
+        app.setCanvasFillMode(FILLMODE_FILL_WINDOW);
+        app.setCanvasResolution(RESOLUTION_AUTO);
 
         this._pickerCreate();
 
@@ -248,7 +282,7 @@ class AppElement extends AsyncElement {
             assetElement.createAsset();
             const asset = assetElement.asset;
             if (asset) {
-                this.app!.assets.add(asset);
+                app.assets.add(asset);
             }
         });
 
@@ -261,20 +295,46 @@ class AppElement extends AsyncElement {
         // Create all entities
         const entityElements = this.querySelectorAll<EntityElement>('pc-entity');
         Array.from(entityElements).forEach((entityElement) => {
-            entityElement.createEntity(this.app!);
+            entityElement.createEntity(app);
         });
 
         // Build hierarchy
         entityElements.forEach((entityElement) => {
-            entityElement.buildHierarchy(this.app!);
+            entityElement.buildHierarchy(app);
         });
 
         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 }));
+
         // Load assets before starting the application
-        this.app.preload(() => {
+        app.preload(() => {
+            // 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
-            this.app!.start();
+            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());
 
             // Handle window resize to keep the canvas responsive
             window.addEventListener('resize', this._onWindowResize);
@@ -287,10 +347,13 @@ class AppElement extends AsyncElement {
         this._pickerDestroy();
 
         // Clean up the application
-        if (this.app) {
-            this.app.destroy();
+        if (this._app) {
+            this._app.destroy();
             this._app = null;
         }
+        this._loadProgress = 0;
+        this._bar?.destroy();
+        this._bar = null;
 
         // Remove event listeners
         window.removeEventListener('resize', this._onWindowResize);
@@ -312,10 +375,18 @@ class AppElement extends AsyncElement {
         const { width, height } = this.app!.graphicsDevice;
         this._picker = new Picker(this.app!, width, height);
 
-        // Create bound handlers but don't attach them yet
-        this._pointerHandlers.pointermove = this._onPointerMove.bind(this) as EventListener;
-        this._pointerHandlers.pointerdown = this._onPointerDown.bind(this) as EventListener;
-        this._pointerHandlers.pointerup = this._onPointerUp.bind(this) as EventListener;
+        // Create bound handlers but don't attach them yet. The handlers pick asynchronously, so
+        // each is wrapped to discard the promise - a listener must not return one, and nothing
+        // awaits the result.
+        const listener = (handler: (event: PointerEvent) => Promise<void>): EventListener => {
+            return (event: Event) => {
+                handler.call(this, event as PointerEvent);
+            };
+        };
+
+        this._pointerHandlers.pointermove = listener(this._onPointerMove);
+        this._pointerHandlers.pointerdown = listener(this._onPointerDown);
+        this._pointerHandlers.pointerup = listener(this._onPointerUp);
 
         // Listen for pointer listeners being added/removed
         ['pointermove', 'pointerdown', 'pointerup', 'pointerenter', 'pointerleave'].forEach((type) => {
@@ -369,31 +440,51 @@ class AppElement extends AsyncElement {
         return { x, y };
     }
 
-    _onPointerMove(event: PointerEvent) {
-        if (!this._picker || !this.app) return;
-
+    /**
+     * Picks the scene under the pointer and returns the graph node that was hit, or `null`.
+     *
+     * The read back is asynchronous because the synchronous {@link Picker.getSelection} is not
+     * supported on WebGPU, where it returns an empty selection rather than failing - which
+     * silently disabled every `onpointer*` handler once WebGPU became the resolved backend. The
+     * async variant works on both backends and does not block the main thread on a GPU read.
+     *
+     * @param event - The pointer event to pick under.
+     * @returns The graph node under the pointer, or `null` if nothing was hit.
+     */
+    private async _pickNode(event: PointerEvent): Promise<GraphNode | null> {
         const camera = this.app!.root.findComponent('camera') as CameraComponent;
-        if (!camera) return;
+        if (!camera) return null;
 
-        // Use the helper to convert event coordinates into canvas/picker coordinates.
         const { x, y } = this._getPickerCoordinates(event);
 
-        this._picker.prepare(camera, this.app!.scene);
-        const selection = this._picker.getSelection(x, y);
+        this._picker!.prepare(camera, this.app!.scene);
+        const selection = await this._picker!.getSelectionAsync(x, y);
+        if (selection.length === 0) return null;
+
+        const item = selection[0];
+        return item instanceof MeshInstance ? item.node : (item as GSplatComponent).entity;
+    }
+
+    async _onPointerMove(event: PointerEvent) {
+        if (!this._picker || !this.app) return;
+
+        // Moves arrive faster than a pick resolves, so results can land out of order. Only the
+        // newest pick may update the hover state - an older one describes a pointer position the
+        // user has already left.
+        const token = ++this._pickToken;
+        const node = await this._pickNode(event);
+        if (token !== this._pickToken || !this._picker) return;
 
         // Get the currently hovered entity by walking up the hierarchy
         let newHoverEntity: EntityElement | null = null;
-        if (selection.length > 0) {
-            const item = selection[0];
-            let currentNode: GraphNode | null = item instanceof MeshInstance ? item.node : (item as GSplatComponent).entity;
-            while (currentNode !== null) {
-                const entityElement = this.querySelector(`pc-entity[name="${currentNode.name}"]`) as EntityElement;
-                if (entityElement) {
-                    newHoverEntity = entityElement;
-                    break;
-                }
-                currentNode = currentNode.parent;
+        let currentNode = node;
+        while (currentNode !== null) {
+            const entityElement = this.querySelector(`pc-entity[name="${currentNode.name}"]`) as EntityElement;
+            if (entityElement) {
+                newHoverEntity = entityElement;
+                break;
             }
+            currentNode = currentNode.parent;
         }
 
         // Handle enter/leave events
@@ -415,51 +506,31 @@ class AppElement extends AsyncElement {
         }
     }
 
-    _onPointerDown(event: PointerEvent) {
+    async _onPointerDown(event: PointerEvent) {
         if (!this._picker || !this.app) return;
 
-        const camera = this.app!.root.findComponent('camera') as CameraComponent;
-        if (!camera) return;
+        let currentNode = await this._pickNode(event);
+        if (!this._picker) return; // the element disconnected while the pick was in flight
 
-        // Convert the event's pointer coordinates
-        const { x, y } = this._getPickerCoordinates(event);
-
-        this._picker.prepare(camera, this.app!.scene);
-        const selection = this._picker.getSelection(x, y);
-
-        if (selection.length > 0) {
-            const item = selection[0];
-            let currentNode: GraphNode | null = item instanceof MeshInstance ? item.node : (item as GSplatComponent).entity;
-            while (currentNode !== null) {
-                const entityElement = this.querySelector(`pc-entity[name="${currentNode.name}"]`) as EntityElement;
-                if (entityElement && entityElement.hasListeners('pointerdown')) {
-                    entityElement.dispatchEvent(new PointerEvent('pointerdown', event));
-                    break;
-                }
-                currentNode = currentNode.parent;
+        while (currentNode !== null) {
+            const entityElement = this.querySelector(`pc-entity[name="${currentNode.name}"]`) as EntityElement;
+            if (entityElement && entityElement.hasListeners('pointerdown')) {
+                entityElement.dispatchEvent(new PointerEvent('pointerdown', event));
+                break;
             }
+            currentNode = currentNode.parent;
         }
     }
 
-    _onPointerUp(event: PointerEvent) {
+    async _onPointerUp(event: PointerEvent) {
         if (!this._picker || !this.app) return;
 
-        const camera = this.app!.root.findComponent('camera') as CameraComponent;
-        if (!camera) return;
-
-        // Convert CSS coordinates to picker coordinates
-        const { x, y } = this._getPickerCoordinates(event);
+        const node = await this._pickNode(event);
+        if (!node || !this._picker) return;
 
-        this._picker.prepare(camera, this.app!.scene);
-        const selection = this._picker.getSelection(x, y);
-
-        if (selection.length > 0) {
-            const item = selection[0];
-            const node = item instanceof MeshInstance ? item.node : (item as GSplatComponent).entity;
-            const entityElement = this.querySelector(`pc-entity[name="${node.name}"]`) as EntityElement;
-            if (entityElement && entityElement.hasListeners('pointerup')) {
-                entityElement.dispatchEvent(new PointerEvent('pointerup', event));
-            }
+        const entityElement = this.querySelector(`pc-entity[name="${node.name}"]`) as EntityElement;
+        if (entityElement && entityElement.hasListeners('pointerup')) {
+            entityElement.dispatchEvent(new PointerEvent('pointerup', event));
         }
     }
 
@@ -528,7 +599,8 @@ class AppElement extends AsyncElement {
     }
 
     /**
-     * Sets the graphics backend.
+     * Sets the graphics backend. Defaults to 'webgpu', which falls back to 'webgl2' if WebGPU
+     * is not supported by the browser.
      * @param value - The graphics backend ('webgpu', 'webgl2', or 'null').
      */
     set backend(value: 'webgpu' | 'webgl2' | 'null') {
@@ -588,6 +660,31 @@ class AppElement extends AsyncElement {
         return this._highResolution;
     }
 
+    /**
+     * Sets whether the application shows its built-in loading bar while it boots and preloads its
+     * assets. Enabled by default; setting `false` removes the bar immediately, while setting
+     * `true` has no effect until the element is next connected. The bar can be themed with the
+     * CSS custom properties `--pc-loading-bar-color`, `--pc-loading-bar-background` and
+     * `--pc-loading-bar-height`.
+     * @param value - The loading bar flag.
+     */
+    set loadingBar(value: boolean) {
+        this._loadingBar = value;
+        if (!value && this._bar) {
+            this._bar.destroy();
+            this._bar = null;
+        }
+    }
+
+    /**
+     * Gets whether the application shows its built-in loading bar while it boots and preloads
+     * its assets.
+     * @returns The loading bar flag.
+     */
+    get loadingBar() {
+        return this._loadingBar;
+    }
+
     /**
      * Sets the stencil flag.
      * @param value - The stencil flag.
@@ -605,10 +702,10 @@ class AppElement extends AsyncElement {
     }
 
     static get observedAttributes() {
-        return ['alpha', 'antialias', 'backend', 'depth', 'stencil', 'high-resolution'];
+        return ['alpha', 'antialias', 'backend', 'depth', 'stencil', 'high-resolution', 'loading-bar'];
     }
 
-    attributeChangedCallback(name: string, _oldValue: string, newValue: string) {
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null) {
         switch (name) {
             case 'alpha':
                 this.alpha = parseBool(newValue, true);
@@ -617,7 +714,7 @@ class AppElement extends AsyncElement {
                 this.antialias = parseBool(newValue, true);
                 break;
             case 'backend':
-                this.backend = parseEnum(newValue, ['webgpu', 'webgl2', 'null'], 'webgl2', name);
+                this.backend = parseEnum(newValue, ['webgpu', 'webgl2', 'null'], 'webgpu', name);
                 break;
             case 'depth':
                 this.depth = parseBool(newValue, true);
@@ -625,6 +722,9 @@ class AppElement extends AsyncElement {
             case 'high-resolution':
                 this.highResolution = parseBool(newValue, true);
                 break;
+            case 'loading-bar':
+                this.loadingBar = parseBool(newValue, true);
+                break;
             case 'stencil':
                 this.stencil = parseBool(newValue, true);
                 break;

package/src/asset.ts

@@ -1,7 +1,7 @@
 import { Asset, SPRITE_RENDERMODE_SIMPLE, SPRITE_RENDERMODE_SLICED, SPRITE_RENDERMODE_TILED } from 'playcanvas';
 
 import { AsyncElement } from './async-element';
-import { parseBool, parseEnum, parseNumber } from './utils';
+import { parseBool, parseEnum, parseNumber } from './parse';
 import { MeshoptDecoder } from '../lib/meshopt_decoder.module.js';
 
 const renderModes = new Map<'simple' | 'sliced' | 'tiled', number>([
@@ -16,11 +16,13 @@ const extToType = new Map([
     ['frag', 'shader'],
     ['glb', 'container'],
     ['glsl', 'shader'],
+    ['gltf', 'container'],
     ['hdr', 'texture'],
     ['html', 'html'],
     ['jpg', 'texture'],
     ['js', 'script'],
     ['json', 'json'],
+    ['ktx2', 'texture'],
     ['mp3', 'audio'],
     ['mjs', 'script'],
     ['ply', 'gsplat'],
@@ -82,6 +84,28 @@ const processBufferView = (
  * while the application is running are created and registered on insertion, and begin loading
  * 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.
+ *
+ * Apart from `lazy`, these attributes are read once when the asset is created, so changing them
+ * later has no effect.
+ *
+ * @attribute {string} id - The identifier used to reference the asset from other elements.
+ * @attribute {string} src - The URL of the asset to load.
+ * @attribute {string} type - The asset type. Inferred from the `src` file extension when omitted.
+ * @attribute {string} data - Additional asset data, as a JSON object.
+ * @attribute {string} atlas - For a `sprite` asset, the `id` of the texture atlas asset it uses.
+ * The atlas must be declared before the sprite.
+ * @attribute {string} frame-keys - For a `sprite` asset, the atlas frame keys it uses, separated
+ * by spaces or commas.
+ * @attribute {number} pixels-per-unit - For a `sprite` asset, the number of pixels per world unit.
+ * @attribute {'simple' | 'sliced' | 'tiled'} render-mode - For a `sprite` asset, how the sprite is
+ * rendered when resized.
+ *
+ * @fires {Event} load - Fired each time the asset finishes loading, including a `lazy` asset
+ * loaded later and any subsequent reloads. Does not bubble — listen on this element, or use a
+ * capture-phase listener on an ancestor to observe every asset.
+ * @fires {ErrorEvent} error - Fired when the asset fails to load, with the engine's error in
+ * `message`. Does not bubble. The element still becomes ready — readiness means the load settled,
+ * not that it succeeded.
  */
 class AssetElement extends AsyncElement {
     private _lazy: boolean = false;
@@ -132,6 +156,16 @@ class AssetElement extends AsyncElement {
         this.destroyAsset();
     }
 
+    private _onAssetLoad() {
+        this.dispatchEvent(new Event('load'));
+    }
+
+    private _onAssetError(err: string | Error) {
+        this.dispatchEvent(new ErrorEvent('error', {
+            message: err instanceof Error ? err.message : String(err)
+        }));
+    }
+
     createAsset() {
         const id = this.getAttribute('id') || '';
         const src = this.getAttribute('src') || '';
@@ -169,6 +203,11 @@ class AssetElement extends AsyncElement {
         }
 
         this.asset.preload = !this._lazy;
+
+        // Forward the engine asset's load outcome as DOM events on this element, like <img>.
+        // Attached before the asset joins the registry, which is what starts a preloaded load.
+        this.asset.on('load', this._onAssetLoad, this);
+        this.asset.on('error', this._onAssetError, this);
     }
 
     /**
@@ -232,6 +271,9 @@ class AssetElement extends AsyncElement {
 
     destroyAsset() {
         if (this.asset) {
+            // A caller that keeps the Asset alive must not dispatch on a removed element
+            this.asset.off('load', this._onAssetLoad, this);
+            this.asset.off('error', this._onAssetError, this);
             // Deregister first so unload() can still notify the registry
             this.asset.registry?.remove(this.asset);
             this.asset.unload();
@@ -267,7 +309,7 @@ class AssetElement extends AsyncElement {
         return ['lazy'];
     }
 
-    attributeChangedCallback(name: string, _oldValue: string, newValue: string) {
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null) {
         if (name === 'lazy') {
             this.lazy = parseBool(newValue, false);
         }

package/src/async-element.ts

@@ -3,6 +3,9 @@ import { EntityElement } from './entity';
 
 /**
  * Base class for all PlayCanvas Web Components that initialize asynchronously.
+ *
+ * @fires {CustomEvent} ready - Fired once the element is fully initialized. Bubbles and is
+ * composed.
  */
 class AsyncElement extends HTMLElement {
     private _readyPromise: Promise<void>;
@@ -17,12 +20,22 @@ class AsyncElement extends HTMLElement {
         });
     }
 
-    get closestApp(): AppElement {
-        return this.parentElement?.closest('pc-app') as AppElement;
+    /**
+     * The nearest ancestor `<pc-app>` element, or `null` if this element has no `<pc-app>`
+     * ancestor. The search starts at the parent, so an element never resolves to itself.
+     * @returns The closest app element, or `null`.
+     */
+    get closestApp(): AppElement | null {
+        return this.parentElement?.closest('pc-app') as AppElement | null ?? null;
     }
 
-    get closestEntity(): EntityElement {
-        return this.parentElement?.closest('pc-entity') as EntityElement;
+    /**
+     * The nearest ancestor `<pc-entity>` element, or `null` if this element has no `<pc-entity>`
+     * ancestor. The search starts at the parent, so an element never resolves to itself.
+     * @returns The closest entity element, or `null`.
+     */
+    get closestEntity(): EntityElement | null {
+        return this.parentElement?.closest('pc-entity') as EntityElement | null ?? null;
     }
 
     /**