@playcanvas/web-components 0.10.1 → 0.11.1

package/src/model.ts

@@ -1,4 +1,4 @@
-import { ContainerResource, Entity } from 'playcanvas';
+import type { ContainerResource, Entity, EventHandle } from 'playcanvas';
 
 import { AssetElement } from './asset';
 import { AsyncElement } from './async-element';
@@ -10,39 +10,83 @@ import { AsyncElement } from './async-element';
  * {@link HTMLElement} interface.
  */
 class ModelElement extends AsyncElement {
-    private _asset: string = '';
+    private _asset = '';
 
     private _entity: Entity | null = 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 can neither instantiate a second entity nor parent one that has
+     * since been destroyed.
+     */
+    private _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).
+     */
+    private _loadHandle: EventHandle | null = null;
+
+    /**
+     * The root entity of the instantiated model. `null` until the container asset has loaded
+     * and been instantiated, and again once the element has been removed from the document.
+     * @returns The model's root entity, or `null`.
+     */
+    get entity(): Entity | null {
+        return this._entity;
+    }
+
     connectedCallback() {
         this._loadModel();
         this._onReady();
     }
 
     disconnectedCallback() {
+        this._loadGeneration++;
+        this._detachLoadHandler();
         this._unloadModel();
+        this._resetReady();
+    }
+
+    private _detachLoadHandler() {
+        this._loadHandle?.off();
+        this._loadHandle = null;
     }
 
     private _instantiate(container: ContainerResource) {
-        this._entity = container.instantiateRenderEntity();
+        const generation = this._loadGeneration;
+
+        const entity = container.instantiateRenderEntity();
+        this._entity = entity;
 
         // @ts-ignore
         if (container.animations.length > 0) {
-            this._entity.addComponent('anim');
+            entity.addComponent('anim');
             // @ts-ignore
-            this._entity.anim.assignAnimation('animation', container.animations[0].resource);
+            entity.anim.assignAnimation('animation', container.animations[0].resource);
         }
 
+        // The parent's readiness re-arms when it is torn down, so these can resume in a later
+        // connection cycle. The entity is captured above and the generation re-checked, so a
+        // stale resume cannot parent an entity a newer cycle has already destroyed.
         const parentEntityElement = this.closestEntity;
         if (parentEntityElement) {
             parentEntityElement.ready().then(() => {
-                parentEntityElement.entity!.addChild(this._entity!);
+                if (generation !== this._loadGeneration) {
+                    return;
+                }
+                parentEntityElement.entity!.addChild(entity);
             });
         } else {
             const appElement = this.closestApp;
             if (appElement) {
                 appElement.ready().then(() => {
-                    appElement.app!.root.addChild(this._entity!);
+                    if (generation !== this._loadGeneration) {
+                        return;
+                    }
+                    appElement.app!.root.addChild(entity);
                 });
             }
         }
@@ -51,7 +95,17 @@ class ModelElement extends AsyncElement {
     private async _loadModel() {
         this._unloadModel();
 
+        // Supersede any load already in flight - only the newest load may instantiate
+        const generation = ++this._loadGeneration;
+        this._detachLoadHandler();
+
         const appElement = await this.closestApp?.ready();
+
+        // The element may have been removed, or another load started, while we waited
+        if (generation !== this._loadGeneration) {
+            return;
+        }
+
         const app = appElement?.app;
 
         const asset = AssetElement.get(this._asset);
@@ -62,7 +116,14 @@ class ModelElement extends AsyncElement {
         if (asset.loaded) {
             this._instantiate(asset.resource as ContainerResource);
         } else {
-            asset.once('load', () => {
+            // 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._instantiate(asset.resource as ContainerResource);
             });
             app!.assets.load(asset);
@@ -108,10 +169,4 @@ class ModelElement extends AsyncElement {
 
 customElements.define('pc-model', ModelElement);
 
-declare global {
-    interface HTMLElementTagNameMap {
-        'pc-model': ModelElement;
-    }
-}
-
 export { ModelElement };

package/src/module.ts

@@ -43,17 +43,18 @@ class ModuleElement extends HTMLElement {
         }
     }
 
-    public getLoadPromise(): Promise<void> {
+    /**
+     * 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 load promise.
+     * @internal
+     */
+    _getLoadPromise(): Promise<void> {
         return this.loadPromise;
     }
 }
 
 customElements.define('pc-module', ModuleElement);
 
-declare global {
-    interface HTMLElementTagNameMap {
-        'pc-module': ModuleElement;
-    }
-}
-
 export { ModuleElement };

package/src/parse.ts

@@ -16,7 +16,8 @@
  * literal, and returns `null` instead of falling back to a default.
  */
 
-import { Color, Entity, Quat, Vec2, Vec3, Vec4 } from 'playcanvas';
+import type { Entity } from 'playcanvas';
+import { Color, Quat, Vec2, Vec3, Vec4 } from 'playcanvas';
 
 import { CSS_COLORS } from './colors';
 
@@ -31,7 +32,7 @@ import { CSS_COLORS } from './colors';
  */
 export const parseComponents = (value: string, count: number): number[] | null => {
     const components = value.trim().split(/\s+/).map(Number);
-    if (components.length !== count || components.some(component => !Number.isFinite(component))) {
+    if (components.length !== count || components.some((component) => !Number.isFinite(component))) {
         return null;
     }
     return components;
@@ -77,7 +78,11 @@ export const parseBool = (value: string | null, defaultValue: boolean): boolean
  * @param attribute - The attribute name, used in the warning message.
  * @returns The parsed Color object.
  */
-export const parseColor = <T extends Color | null>(value: string | null, defaultValue: T, attribute: string): Color | T => {
+export const parseColor = <T extends Color | null>(
+    value: string | null,
+    defaultValue: T,
+    attribute: string
+): Color | T => {
     if (value === null) {
         return cloneDefault(defaultValue);
     }
@@ -92,7 +97,10 @@ export const parseColor = <T extends Color | null>(value: string | null, default
     if (/^#(?:[0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/i.test(value)) {
         let hex = value.slice(1);
         if (hex.length === 3 || hex.length === 4) {
-            hex = hex.split('').map(char => char + char).join('');
+            hex = hex
+                .split('')
+                .map((char) => char + char)
+                .join('');
         }
         return new Color().fromString(`#${hex}`);
     }
@@ -103,7 +111,9 @@ export const parseColor = <T extends Color | null>(value: string | null, default
         return new Color(components);
     }
 
-    console.warn(`Invalid value '${value}' for attribute '${attribute}'. Expected a CSS color name, a hex color or 3 or 4 space-separated numbers. Using '${defaultValue}'.`);
+    console.warn(
+        `Invalid value '${value}' for attribute '${attribute}'. Expected a CSS color name, a hex color or 3 or 4 space-separated numbers. Using '${defaultValue}'.`
+    );
     return cloneDefault(defaultValue);
 };
 
@@ -113,25 +123,29 @@ export const parseColor = <T extends Color | null>(value: string | null, default
  * the value is invalid — the latter also logs a warning listing the valid names.
  *
  * @param value - The attribute value to parse (`null` when the attribute is absent).
- * @param valid - The valid names: an array, or a map whose keys are the valid names.
+ * @param valid - The valid names: an array, or a map whose keys are the valid names. Only the keys
+ * are read, so the map's value type is unconstrained - engine enums are mostly numeric constants,
+ * but some (e.g. `SCALEMODE_BLEND`) are strings.
  * @param defaultValue - The value to use when the attribute is absent or invalid.
  * @param attribute - The attribute name, used in the warning message.
  * @returns The resolved enum name.
  */
 export const parseEnum = <T extends string>(
     value: string | null,
-    valid: readonly T[] | ReadonlyMap<T, number>,
+    valid: readonly T[] | ReadonlyMap<T, unknown>,
     defaultValue: T,
     attribute: string
 ): T => {
     if (value === null) {
         return defaultValue;
     }
-    const names = Array.isArray(valid) ? valid : [...(valid as ReadonlyMap<T, number>).keys()];
+    const names: readonly T[] = Array.isArray(valid) ? valid : [...valid.keys()];
     if (names.includes(value as T)) {
         return value as T;
     }
-    console.warn(`Invalid value '${value}' for attribute '${attribute}'. Valid values: ${names.join(', ')}. Using '${defaultValue}'.`);
+    console.warn(
+        `Invalid value '${value}' for attribute '${attribute}'. Valid values: ${names.join(', ')}. Using '${defaultValue}'.`
+    );
     return defaultValue;
 };
 
@@ -145,13 +159,19 @@ export const parseEnum = <T extends string>(
  * @param attribute - The attribute name, used in the warning message.
  * @returns The parsed number.
  */
-export const parseNumber = <T extends number | null>(value: string | null, defaultValue: T, attribute: string): number | T => {
+export const parseNumber = <T extends number | null>(
+    value: string | null,
+    defaultValue: T,
+    attribute: string
+): number | T => {
     if (value === null) {
         return defaultValue;
     }
     const number = value.trim() === '' ? NaN : Number(value);
     if (!Number.isFinite(number)) {
-        console.warn(`Invalid value '${value}' for attribute '${attribute}'. Expected a finite number. Using '${defaultValue}'.`);
+        console.warn(
+            `Invalid value '${value}' for attribute '${attribute}'. Expected a finite number. Using '${defaultValue}'.`
+        );
         return defaultValue;
     }
     return number;
@@ -168,13 +188,19 @@ export const parseNumber = <T extends number | null>(value: string | null, defau
  * @param attribute - The attribute name, used in the warning message.
  * @returns The parsed Quat object.
  */
-export const parseQuat = <T extends Quat | null>(value: string | null, defaultValue: T, attribute: string): Quat | T => {
+export const parseQuat = <T extends Quat | null>(
+    value: string | null,
+    defaultValue: T,
+    attribute: string
+): Quat | T => {
     if (value === null) {
         return cloneDefault(defaultValue);
     }
     const components = parseComponents(value, 3);
     if (!components) {
-        console.warn(`Invalid value '${value}' for attribute '${attribute}'. Expected 3 space-separated numbers. Using '${defaultValue}'.`);
+        console.warn(
+            `Invalid value '${value}' for attribute '${attribute}'. Expected 3 space-separated numbers. Using '${defaultValue}'.`
+        );
         return cloneDefault(defaultValue);
     }
     return new Quat().setFromEulerAngles(components[0], components[1], components[2]);
@@ -198,7 +224,10 @@ export const parseTags = (value: string | null, defaultValue: string[] = []): st
         // caller's default, or a later mutation would write back through it.
         return [...defaultValue];
     }
-    return value.split(',').map(tag => tag.trim()).filter(tag => tag !== '');
+    return value
+        .split(',')
+        .map((tag) => tag.trim())
+        .filter((tag) => tag !== '');
 };
 
 /**
@@ -211,13 +240,19 @@ export const parseTags = (value: string | null, defaultValue: string[] = []): st
  * @param attribute - The attribute name, used in the warning message.
  * @returns The parsed Vec2 object.
  */
-export const parseVec2 = <T extends Vec2 | null>(value: string | null, defaultValue: T, attribute: string): Vec2 | T => {
+export const parseVec2 = <T extends Vec2 | null>(
+    value: string | null,
+    defaultValue: T,
+    attribute: string
+): Vec2 | T => {
     if (value === null) {
         return cloneDefault(defaultValue);
     }
     const components = parseComponents(value, 2);
     if (!components) {
-        console.warn(`Invalid value '${value}' for attribute '${attribute}'. Expected 2 space-separated numbers. Using '${defaultValue}'.`);
+        console.warn(
+            `Invalid value '${value}' for attribute '${attribute}'. Expected 2 space-separated numbers. Using '${defaultValue}'.`
+        );
         return cloneDefault(defaultValue);
     }
     return new Vec2(components);
@@ -233,13 +268,19 @@ export const parseVec2 = <T extends Vec2 | null>(value: string | null, defaultVa
  * @param attribute - The attribute name, used in the warning message.
  * @returns The parsed Vec3 object.
  */
-export const parseVec3 = <T extends Vec3 | null>(value: string | null, defaultValue: T, attribute: string): Vec3 | T => {
+export const parseVec3 = <T extends Vec3 | null>(
+    value: string | null,
+    defaultValue: T,
+    attribute: string
+): Vec3 | T => {
     if (value === null) {
         return cloneDefault(defaultValue);
     }
     const components = parseComponents(value, 3);
     if (!components) {
-        console.warn(`Invalid value '${value}' for attribute '${attribute}'. Expected 3 space-separated numbers. Using '${defaultValue}'.`);
+        console.warn(
+            `Invalid value '${value}' for attribute '${attribute}'. Expected 3 space-separated numbers. Using '${defaultValue}'.`
+        );
         return cloneDefault(defaultValue);
     }
     return new Vec3(components);
@@ -255,13 +296,19 @@ export const parseVec3 = <T extends Vec3 | null>(value: string | null, defaultVa
  * @param attribute - The attribute name, used in the warning message.
  * @returns The parsed Vec4 object.
  */
-export const parseVec4 = <T extends Vec4 | null>(value: string | null, defaultValue: T, attribute: string): Vec4 | T => {
+export const parseVec4 = <T extends Vec4 | null>(
+    value: string | null,
+    defaultValue: T,
+    attribute: string
+): Vec4 | T => {
     if (value === null) {
         return cloneDefault(defaultValue);
     }
     const components = parseComponents(value, 4);
     if (!components) {
-        console.warn(`Invalid value '${value}' for attribute '${attribute}'. Expected 4 space-separated numbers. Using '${defaultValue}'.`);
+        console.warn(
+            `Invalid value '${value}' for attribute '${attribute}'. Expected 4 space-separated numbers. Using '${defaultValue}'.`
+        );
         return cloneDefault(defaultValue);
     }
     return new Vec4(components);

package/src/scene.ts

@@ -1,4 +1,5 @@
-import { Color, Scene, Vec3 } from 'playcanvas';
+import type { Scene } from 'playcanvas';
+import { Color, Vec3 } from 'playcanvas';
 
 import { AsyncElement } from './async-element';
 import { parseColor, parseEnum, parseNumber, parseVec3 } from './parse';
@@ -77,12 +78,20 @@ class SceneElement extends AsyncElement {
         }
 
         this._scene = app.scene;
-        this.updateSceneSettings();
+        this._updateSceneSettings();
 
         this._onReady();
     }
 
-    updateSceneSettings() {
+    disconnectedCallback() {
+        // The scene belongs to the application, and removing this element - or the <pc-app>
+        // above it, which disconnects first - parts the two. Re-arm readiness so a re-inserted
+        // element announces the scene it acquires then, not the one it lost here.
+        this._scene = null;
+        this._resetReady();
+    }
+
+    private _updateSceneSettings() {
         if (this._scene) {
             this._scene.fog.type = this._fog;
             this._scene.fog.color = this._fogColor;
@@ -251,10 +260,4 @@ class SceneElement extends AsyncElement {
 
 customElements.define('pc-scene', SceneElement);
 
-declare global {
-    interface HTMLElementTagNameMap {
-        'pc-scene': SceneElement;
-    }
-}
-
 export { SceneElement };

package/src/sky.ts

@@ -1,6 +1,7 @@
-import { Asset, EnvLighting, LAYERID_SKYBOX, Quat, Scene, Texture, Vec3 } from 'playcanvas';
+import type { Asset, EventHandle, Scene, Texture } from 'playcanvas';
+import { EnvLighting, LAYERID_SKYBOX, Quat, Vec3 } from 'playcanvas';
 
-import { AppElement } from './app';
+import type { AppElement } from './app';
 import { AssetElement } from './asset';
 import { AsyncElement } from './async-element';
 import { parseBool, parseEnum, parseNumber, parseVec3 } from './parse';
@@ -19,7 +20,7 @@ class SkyElement extends AsyncElement {
 
     private _rotation = new Vec3();
 
-    private _level = 0;
+    private _mipLevel = 0;
 
     private _lighting = false;
 
@@ -31,14 +32,36 @@ class SkyElement extends AsyncElement {
 
     private _appElement: AppElement | null = 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.
+     */
+    private _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).
+     */
+    private _loadHandle: EventHandle | null = null;
+
     connectedCallback() {
         this._loadSkybox();
         this._onReady();
     }
 
     disconnectedCallback() {
+        this._loadGeneration++;
+        this._detachLoadHandler();
         this._unloadSkybox();
         this._appElement = null;
+        this._resetReady();
+    }
+
+    private _detachLoadHandler() {
+        this._loadHandle?.off();
+        this._loadHandle = null;
     }
 
     private _generateSkybox(asset: Asset) {
@@ -48,11 +71,18 @@ class SkyElement extends AsyncElement {
 
         const skybox = EnvLighting.generateSkyboxCubemap(source);
         skybox.anisotropy = 4;
+        // This element owns what it generated (see _unloadSkybox) - replacing a skybox from an
+        // earlier load must release it, not orphan it on the GPU
+        this._scene.skybox?.destroy();
         this._scene.skybox = skybox;
 
         if (this._lighting) {
             const lighting = EnvLighting.generateLightingSource(source);
             const envAtlas = EnvLighting.generateAtlas(lighting);
+            // The lighting source is an intermediate: the atlas is rendered from it and it is
+            // not needed afterwards
+            lighting.destroy();
+            this._scene.envAtlas?.destroy();
             this._scene.envAtlas = envAtlas;
         }
 
@@ -65,11 +95,21 @@ class SkyElement extends AsyncElement {
         this._scene.sky.node.setLocalScale(this._scale);
         this._scene.sky.center = this._center;
         this._scene.skyboxIntensity = this._intensity;
-        this._scene.skyboxMip = this._level;
+        this._scene.skyboxMip = this._mipLevel;
     }
 
     private async _loadSkybox() {
+        // Supersede any load already in flight - only the newest load may generate the skybox
+        const generation = ++this._loadGeneration;
+        this._detachLoadHandler();
+
         const appElement = await this.closestApp?.ready();
+
+        // The element may have been removed, or another load started, while we waited
+        if (generation !== this._loadGeneration) {
+            return;
+        }
+
         const app = appElement?.app;
         if (!appElement || !app) {
             return;
@@ -87,7 +127,14 @@ class SkyElement extends AsyncElement {
         if (asset.loaded) {
             this._generateSkybox(asset);
         } else {
-            asset.once('load', () => {
+            // 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);
             });
             app.assets.load(asset);
@@ -170,25 +217,6 @@ class SkyElement extends AsyncElement {
         return this._intensity;
     }
 
-    /**
-     * Sets the mip level of the skybox.
-     * @param value - The mip level.
-     */
-    set level(value: number) {
-        this._level = value;
-        if (this._scene) {
-            this._scene.skyboxMip = this._level;
-        }
-    }
-
-    /**
-     * Gets the mip level of the skybox.
-     * @returns The mip level.
-     */
-    get level() {
-        return this._level;
-    }
-
     /**
      * Sets whether the skybox is used as a light source.
      * @param value - Whether to use lighting.
@@ -205,6 +233,26 @@ class SkyElement extends AsyncElement {
         return this._lighting;
     }
 
+    /**
+     * Sets the mip level of the skybox, where 0 is the sharpest. Raising it selects a blurrier mip,
+     * which is how a skybox is softened without blurring the texture itself.
+     * @param value - The mip level.
+     */
+    set mipLevel(value: number) {
+        this._mipLevel = value;
+        if (this._scene) {
+            this._scene.skyboxMip = this._mipLevel;
+        }
+    }
+
+    /**
+     * Gets the mip level of the skybox.
+     * @returns The mip level.
+     */
+    get mipLevel() {
+        return this._mipLevel;
+    }
+
     /**
      * Sets the Euler rotation of the skybox.
      * @param value - The rotation.
@@ -267,7 +315,7 @@ class SkyElement extends AsyncElement {
     }
 
     static get observedAttributes() {
-        return ['asset', 'center', 'intensity', 'level', 'lighting', 'rotation', 'scale', 'type'];
+        return ['asset', 'center', 'intensity', 'lighting', 'mip-level', 'rotation', 'scale', 'type'];
     }
 
     attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null) {
@@ -281,12 +329,12 @@ class SkyElement extends AsyncElement {
             case 'intensity':
                 this.intensity = parseNumber(newValue, 1, name);
                 break;
-            case 'level':
-                this.level = parseNumber(newValue, 0, name);
-                break;
             case 'lighting':
                 this.lighting = parseBool(newValue, false);
                 break;
+            case 'mip-level':
+                this.mipLevel = parseNumber(newValue, 0, name);
+                break;
             case 'rotation':
                 this.rotation = parseVec3(newValue, Vec3.ZERO, name);
                 break;
@@ -302,10 +350,4 @@ class SkyElement extends AsyncElement {
 
 customElements.define('pc-sky', SkyElement);
 
-declare global {
-    interface HTMLElementTagNameMap {
-        'pc-sky': SkyElement;
-    }
-}
-
 export { SkyElement };