@playcanvas/web-components 0.11.0 → 0.11.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcanvas/web-components",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "author": "PlayCanvas <support@playcanvas.com>",
   "homepage": "https://playcanvas.com",
   "description": "Web Components for the PlayCanvas Engine",
@@ -51,7 +51,10 @@
     "cem": "cem analyze && node utils/cem/validate.mjs",
     "dev": "concurrently \"npm run watch\" \"npm run serve\"",
     "docs": "typedoc",
+    "fmt": "prettier --check eslint.config.mjs prettier.config.mjs examples/js examples/assets/scripts src test vitest.config.ts",
+    "fmt:fix": "prettier --write eslint.config.mjs prettier.config.mjs examples/js examples/assets/scripts src test vitest.config.ts",
     "lint": "eslint examples/js examples/assets/scripts src test vitest.config.ts",
+    "lint:fix": "eslint examples/js examples/assets/scripts src test vitest.config.ts --fix",
     "serve": "serve",
     "test": "vitest run",
     "test:watch": "vitest",
@@ -72,27 +75,25 @@
   "devDependencies": {
     "@custom-elements-manifest/analyzer": "0.11.0",
     "@mediapipe/tasks-vision": "1.0.1",
-    "@playcanvas/eslint-config": "2.1.0",
+    "@playcanvas/eslint-config": "3.0.0-beta.8",
     "@rollup/plugin-commonjs": "29.0.3",
     "@rollup/plugin-node-resolve": "16.0.3",
     "@rollup/plugin-terser": "1.0.0",
     "@rollup/plugin-typescript": "12.3.0",
     "@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.9.0",
     "jsdom": "30.0.1",
-    "mediabunny": "1.52.2",
+    "mediabunny": "1.52.3",
     "opentype.js": "2.0.0",
     "playcanvas": "2.21.3",
-    "publint": "0.3.22",
+    "prettier": "3.9.6",
+    "publint": "0.3.23",
     "rollup": "4.62.4",
     "serve": "14.2.6",
     "tslib": "2.8.1",

package/src/app.ts

@@ -1,12 +1,10 @@
+import type { CameraComponent, GraphNode, GSplatComponent, Entity } from 'playcanvas';
 import {
     AppBase,
     AppOptions,
-    CameraComponent,
     createGraphicsDevice,
     ElementInput,
-    Entity,
     FILLMODE_FILL_WINDOW,
-    GraphNode,
     Keyboard,
     Mouse,
     Picker,
@@ -63,18 +61,20 @@ import {
     SoundManager,
     Lightmapper,
     XrManager,
-    MeshInstance,
-    GSplatComponent
+    MeshInstance
 } from 'playcanvas';
 
-import { AssetElement } from './asset';
+import type { AssetElement } from './asset';
 import { AsyncElement } from './async-element';
-import { EntityElement } from './entity';
+import type { EntityElement } from './entity';
 import { LoadingBar } from './loading-bar';
-import { MaterialElement } from './material';
-import { ModuleElement } from './module';
+import type { MaterialElement } from './material';
+import type { ModuleElement } from './module';
 import { parseBool, parseEnum, parseNumber } from './parse';
 
+/** The pointer event types the application synthesizes on `<pc-entity>` elements via picking. */
+const pointerEventTypes = ['pointermove', 'pointerdown', 'pointerup', 'pointerenter', 'pointerleave'] as const;
+
 /**
  * The AppElement interface provides properties and methods for manipulating
  * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-app/ | `<pc-app>`} elements.
@@ -115,7 +115,21 @@ class AppElement extends AsyncElement {
 
     private _bar: LoadingBar | null = null;
 
-    private _hierarchyReady = false;
+    /**
+     * 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.
+     */
+    private _bootGeneration = 0;
 
     /**
      * The elements backing this application's entities, keyed by the entity itself. Registered
@@ -126,7 +140,7 @@ class AppElement extends AsyncElement {
 
     private _picker: Picker | null = null;
 
-    private _hasPointerListeners: { [key: string]: boolean } = {
+    private _hasPointerListeners: Record<string, boolean> = {
         pointerenter: false,
         pointerleave: false,
         pointerdown: false,
@@ -139,7 +153,7 @@ class AppElement extends AsyncElement {
     // Identifies the newest in-flight hover pick, so out-of-order results can be discarded
     private _pickToken = 0;
 
-    private _pointerHandlers: { [key: string]: EventListener | null } = {
+    private _pointerHandlers: Record<string, EventListener | null> = {
         pointermove: null,
         pointerdown: null,
         pointerup: null
@@ -180,9 +194,19 @@ class AppElement extends AsyncElement {
 
         // 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.
+        pointerEventTypes.forEach((type) => {
+            this.addEventListener(`${type}:connect`, () => this._onPointerListenerAdded(type));
+            this.addEventListener(`${type}:disconnect`, () => this._onPointerListenerRemoved(type));
+        });
     }
 
     async connectedCallback() {
+        const generation = ++this._bootGeneration;
+
         // 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) {
@@ -193,14 +217,20 @@ class AppElement extends AsyncElement {
         const moduleElements = this.querySelectorAll<ModuleElement>(':scope > pc-module');
 
         // Wait for all modules to load
-        await Promise.all(Array.from(moduleElements).map(module => module.getLoadPromise()));
+        await Promise.all(Array.from(moduleElements).map((module) => module._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 to the element
         this._canvas = document.createElement('canvas');
         this.appendChild(this._canvas);
 
         // Configure device types based on backend selection
-        const backendToDeviceTypes: { [key: string]: string[] } = {
+        const backendToDeviceTypes: Record<string, string[]> = {
             webgpu: ['webgpu', 'webgl2'], // fallback to webgl2 if webgpu not available
             webgl2: ['webgl2'],
             null: ['null']
@@ -218,6 +248,14 @@ class AppElement extends AsyncElement {
             stencil: this._stencilBuffer
         });
 
+        // 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.
@@ -299,31 +337,47 @@ class AppElement extends AsyncElement {
 
         // Get all pc-asset elements that are direct children of the pc-app element
         const assetElements = this.querySelectorAll<AssetElement>(':scope > pc-asset');
-        Array.from(assetElements).forEach((assetElement) => {
-            assetElement.createAsset();
+        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<MaterialElement>(':scope > pc-material');
         Array.from(materialElements).forEach((materialElement) => {
-            materialElement.createMaterial();
+            materialElement._createMaterial();
         });
 
         // Create all entities
         const entityElements = this.querySelectorAll<EntityElement>('pc-entity');
         Array.from(entityElements).forEach((entityElement) => {
-            entityElement.createEntity(app);
+            entityElement._createEntity(app);
         });
 
         // Build hierarchy
         entityElements.forEach((entityElement) => {
-            entityElement.buildHierarchy(app);
+            entityElement._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
@@ -343,8 +397,21 @@ class AppElement extends AsyncElement {
         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);
@@ -365,6 +432,10 @@ class AppElement extends AsyncElement {
     }
 
     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();
 
@@ -379,6 +450,12 @@ class AppElement extends AsyncElement {
         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();
+
         // Remove event listeners
         window.removeEventListener('resize', this._onWindowResize);
 
@@ -389,13 +466,13 @@ class AppElement extends AsyncElement {
         }
     }
 
-    _onWindowResize() {
+    private _onWindowResize() {
         if (this.app) {
             this.app.resizeCanvas();
         }
     }
 
-    _pickerCreate() {
+    private _pickerCreate() {
         const { width, height } = this.app!.graphicsDevice;
         this._picker = new Picker(this.app!, width, height);
 
@@ -412,22 +489,20 @@ class AppElement extends AsyncElement {
         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) => {
-            this.addEventListener(`${type}:connect`, () => this._onPointerListenerAdded(type));
-            this.addEventListener(`${type}:disconnect`, () => this._onPointerListenerRemoved(type));
-
-            // Attach canvas handlers for listeners registered before this point (e.g. handlers
-            // created from onpointer* attributes when their elements were first upgraded)
-            const anyListeners = Array.from(this.querySelectorAll<EntityElement>('pc-entity'))
-            .some(entity => entity.hasListeners(type));
+        // Attach canvas handlers for listeners registered before this boot (e.g. handlers
+        // created from onpointer* attributes when their elements were first upgraded, or
+        // listeners carried over from before a re-boot)
+        pointerEventTypes.forEach((type) => {
+            const anyListeners = Array.from(this.querySelectorAll<EntityElement>('pc-entity')).some((entity) =>
+                entity._hasListeners(type)
+            );
             if (anyListeners) {
                 this._onPointerListenerAdded(type);
             }
         });
     }
 
-    _pickerDestroy() {
+    private _pickerDestroy() {
         if (this._canvas) {
             Object.entries(this._pointerHandlers).forEach(([type, handler]) => {
                 if (handler) {
@@ -437,6 +512,7 @@ class AppElement extends AsyncElement {
         }
 
         this._picker = null;
+        this._hoveredEntity = null;
         this._pointerHandlers = {
             pointermove: null,
             pointerdown: null,
@@ -457,7 +533,7 @@ class AppElement extends AsyncElement {
      *
      * @param entity - The entity.
      * @param element - The element that created it.
-     * @ignore
+     * @internal
      */
     _registerEntityElement(entity: Entity, element: EntityElement) {
         this._entityElements.set(entity, element);
@@ -467,7 +543,7 @@ class AppElement extends AsyncElement {
      * Removes the registration for a destroyed entity. Called by EntityElement.
      *
      * @param entity - The entity.
-     * @ignore
+     * @internal
      */
     _unregisterEntityElement(entity: Entity) {
         this._entityElements.delete(entity);
@@ -516,7 +592,7 @@ class AppElement extends AsyncElement {
     private _elementWithListener(node: GraphNode | null, type: string): EntityElement | null {
         while (node !== null) {
             const element = this._entityElements.get(node);
-            if (element?.hasListeners(type)) {
+            if (element?._hasListeners(type)) {
                 return element;
             }
             node = node.parent;
@@ -525,7 +601,7 @@ class AppElement extends AsyncElement {
     }
 
     // New helper to convert CSS coordinates to canvas (picker) coordinates
-    private _getPickerCoordinates(event: PointerEvent): { x: number, y: number } {
+    private _getPickerCoordinates(event: PointerEvent): { x: number; y: number } {
         // 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.
@@ -562,7 +638,7 @@ class AppElement extends AsyncElement {
         return item instanceof MeshInstance ? item.node : (item as GSplatComponent).entity;
     }
 
-    async _onPointerMove(event: PointerEvent) {
+    private 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
@@ -578,10 +654,10 @@ class AppElement extends AsyncElement {
 
         // Handle enter/leave events
         if (this._hoveredEntity !== newHoverEntity) {
-            if (this._hoveredEntity && this._hoveredEntity.hasListeners('pointerleave')) {
+            if (this._hoveredEntity && this._hoveredEntity._hasListeners('pointerleave')) {
                 this._hoveredEntity.dispatchEvent(new PointerEvent('pointerleave', event));
             }
-            if (newHoverEntity && newHoverEntity.hasListeners('pointerenter')) {
+            if (newHoverEntity && newHoverEntity._hasListeners('pointerenter')) {
                 newHoverEntity.dispatchEvent(new PointerEvent('pointerenter', event));
             }
         }
@@ -590,12 +666,12 @@ class AppElement extends AsyncElement {
         this._hoveredEntity = newHoverEntity;
 
         // Handle pointermove event
-        if (newHoverEntity && newHoverEntity.hasListeners('pointermove')) {
+        if (newHoverEntity && newHoverEntity._hasListeners('pointermove')) {
             newHoverEntity.dispatchEvent(new PointerEvent('pointermove', event));
         }
     }
 
-    async _onPointerDown(event: PointerEvent) {
+    private async _onPointerDown(event: PointerEvent) {
         if (!this._picker || !this.app) return;
 
         const node = await this._pickNode(event);
@@ -607,7 +683,7 @@ class AppElement extends AsyncElement {
         }
     }
 
-    async _onPointerUp(event: PointerEvent) {
+    private async _onPointerUp(event: PointerEvent) {
         if (!this._picker || !this.app) return;
 
         const node = await this._pickNode(event);
@@ -619,34 +695,43 @@ class AppElement extends AsyncElement {
         }
     }
 
-    _onPointerListenerAdded(type: string) {
+    private _onPointerListenerAdded(type: string) {
         if (!this._hasPointerListeners[type] && this._canvas) {
             this._hasPointerListeners[type] = true;
 
             // For enter/leave events, we need the move handler
-            const handler = (type === 'pointerenter' || type === 'pointerleave') ?
-                this._pointerHandlers.pointermove :
-                this._pointerHandlers[type];
+            const handler =
+                type === 'pointerenter' || type === 'pointerleave'
+                    ? this._pointerHandlers.pointermove
+                    : this._pointerHandlers[type];
 
             if (handler) {
-                this._canvas.addEventListener(type === 'pointerenter' || type === 'pointerleave' ? 'pointermove' : type, handler);
+                this._canvas.addEventListener(
+                    type === 'pointerenter' || type === 'pointerleave' ? 'pointermove' : type,
+                    handler
+                );
             }
         }
     }
 
-    _onPointerListenerRemoved(type: string) {
-        const hasListeners = Array.from(this.querySelectorAll<EntityElement>('pc-entity'))
-        .some(entity => entity.hasListeners(type));
+    private _onPointerListenerRemoved(type: string) {
+        const hasListeners = Array.from(this.querySelectorAll<EntityElement>('pc-entity')).some((entity) =>
+            entity._hasListeners(type)
+        );
 
         if (!hasListeners && this._canvas) {
             this._hasPointerListeners[type] = false;
 
-            const handler = (type === 'pointerenter' || type === 'pointerleave') ?
-                this._pointerHandlers.pointermove :
-                this._pointerHandlers[type];
+            const handler =
+                type === 'pointerenter' || type === 'pointerleave'
+                    ? this._pointerHandlers.pointermove
+                    : this._pointerHandlers[type];
 
             if (handler) {
-                this._canvas.removeEventListener(type === 'pointerenter' || type === 'pointerleave' ? 'pointermove' : type, handler);
+                this._canvas.removeEventListener(
+                    type === 'pointerenter' || type === 'pointerleave' ? 'pointermove' : type,
+                    handler
+                );
             }
         }
     }
@@ -660,7 +745,9 @@ class AppElement extends AsyncElement {
      */
     private _warnIfBooted(name: string) {
         if (this._optionsLocked) {
-            console.warn(`Attribute '${name}' on <pc-app> is only read when the application boots, so this change has no effect. Set it before the element is connected, or remove and re-insert the element to reboot with the new value.`);
+            console.warn(
+                `Attribute '${name}' on <pc-app> is only read when the application boots, so this change has no effect. Set it before the element is connected, or remove and re-insert the element to reboot with the new value.`
+            );
         }
     }
 
@@ -735,15 +822,6 @@ class AppElement extends AsyncElement {
         return this._depthBuffer;
     }
 
-    /**
-     * Gets the hierarchy ready flag.
-     * @returns The hierarchy ready flag.
-     * @ignore
-     */
-    get hierarchyReady() {
-        return this._hierarchyReady;
-    }
-
     /**
      * 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
@@ -844,10 +922,4 @@ class AppElement extends AsyncElement {
 
 customElements.define('pc-app', AppElement);
 
-declare global {
-    interface HTMLElementTagNameMap {
-        'pc-app': AppElement;
-    }
-}
-
 export { AppElement };

package/src/asset.ts

@@ -1,8 +1,9 @@
 import { Asset, SPRITE_RENDERMODE_SIMPLE, SPRITE_RENDERMODE_SLICED, SPRITE_RENDERMODE_TILED } from 'playcanvas';
 
+import { MeshoptDecoder } from '../lib/meshopt_decoder.module.js';
+
 import { AsyncElement } from './async-element';
 import { parseBool, parseEnum, parseNumber } from './parse';
-import { MeshoptDecoder } from '../lib/meshopt_decoder.module.js';
 
 const renderModes = new Map<'simple' | 'sliced' | 'tiled', number>([
     ['simple', SPRITE_RENDERMODE_SIMPLE],
@@ -33,12 +34,11 @@ const extToType = new Map([
     ['webp', 'texture']
 ]);
 
-
 // provide buffer view callback so we can handle models compressed with MeshOptimizer
 // https://github.com/zeux/meshoptimizer
 const processBufferView = (
     gltfBuffer: any,
-    buffers: Array<any>,
+    buffers: any[],
     continuation: (err: string | null, result: any) => void
 ) => {
     if (gltfBuffer.extensions && gltfBuffer.extensions.EXT_meshopt_compression) {
@@ -56,14 +56,7 @@ const processBufferView = (
             const result = new Uint8Array(count * stride);
             const source = new Uint8Array(buffer.buffer, buffer.byteOffset + byteOffset, byteLength);
 
-            MeshoptDecoder.decodeGltfBuffer(
-                result,
-                count,
-                stride,
-                source,
-                extensionDef.mode,
-                extensionDef.filter
-            );
+            MeshoptDecoder.decodeGltfBuffer(result, count, stride, source, extensionDef.mode, extensionDef.filter);
 
             continuation(null, result);
         });
@@ -108,7 +101,7 @@ const processBufferView = (
  * not that it succeeded.
  */
 class AssetElement extends AsyncElement {
-    private _lazy: boolean = false;
+    private _lazy = false;
 
     /**
      * The asset that is loaded. Available once the element is ready — await
@@ -122,7 +115,9 @@ class AssetElement extends AsyncElement {
 
         // Assets must be direct children of pc-app (matches the boot query ':scope > pc-asset')
         if (this.parentElement !== appElement) {
-            console.warn(`pc-asset '${this.getAttribute('id') ?? this.getAttribute('src')}' must be a direct child of pc-app - asset not created`);
+            console.warn(
+                `pc-asset '${this.getAttribute('id') ?? this.getAttribute('src')}' must be a direct child of pc-app - asset not created`
+            );
             return;
         }
 
@@ -137,7 +132,7 @@ class AssetElement extends AsyncElement {
             const app = appElement.app;
             if (!app) return; // pc-app is re-connecting; its own boot will create this asset
 
-            this.createAsset();
+            this._createAsset();
             if (this.asset) {
                 app.assets.add(this.asset); // add() auto-loads when preload is true
                 if (!this.lazy) {
@@ -146,14 +141,16 @@ class AssetElement extends AsyncElement {
             }
         }
 
-        // Never ready if createAsset failed (unsupported asset type)
+        // Never ready if _createAsset failed (unsupported asset type)
         if (this.asset) {
             this._onReady();
         }
     }
 
     disconnectedCallback() {
-        this.destroyAsset();
+        this._destroyAsset();
+        // Re-arm readiness so a re-inserted element announces the asset it creates then
+        this._resetReady();
     }
 
     private _onAssetLoad() {
@@ -161,12 +158,21 @@ class AssetElement extends AsyncElement {
     }
 
     private _onAssetError(err: string | Error) {
-        this.dispatchEvent(new ErrorEvent('error', {
-            message: err instanceof Error ? err.message : String(err)
-        }));
+        this.dispatchEvent(
+            new ErrorEvent('error', {
+                message: err instanceof Error ? err.message : String(err)
+            })
+        );
     }
 
-    createAsset() {
+    /**
+     * Creates the asset from the element's attributes. Called by the containing `<pc-app>`
+     * element during its boot sweep, and on connection for elements inserted while the
+     * application is already running.
+     *
+     * @internal
+     */
+    _createAsset() {
         const id = this.getAttribute('id') || '';
         const src = this.getAttribute('src') || '';
         let type = this.getAttribute('type');
@@ -268,8 +274,7 @@ class AssetElement extends AsyncElement {
         return data;
     }
 
-
-    destroyAsset() {
+    private _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);
@@ -300,6 +305,13 @@ class AssetElement extends AsyncElement {
         return this._lazy;
     }
 
+    /**
+     * Returns the {@link Asset} created by the `<pc-asset>` element with the given `id`, or
+     * `undefined` if there is no such element or its asset has not been created yet.
+     *
+     * @param id - The `id` of the `<pc-asset>` element.
+     * @returns The asset, or `undefined`.
+     */
     static get(id: string) {
         const assetElement = document.querySelector<AssetElement>(`pc-asset[id="${id}"]`);
         return assetElement?.asset;
@@ -318,10 +330,4 @@ class AssetElement extends AsyncElement {
 
 customElements.define('pc-asset', AssetElement);
 
-declare global {
-    interface HTMLElementTagNameMap {
-        'pc-asset': AssetElement;
-    }
-}
-
 export { AssetElement };