@playcanvas/web-components 0.10.1 → 0.11.1

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 };

package/src/async-element.ts

@@ -1,17 +1,20 @@
-import { AppElement } from './app';
-import { EntityElement } from './entity';
+import type { AppElement } from './app';
+import type { 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.
+ * @fires {CustomEvent} ready - Fired when the element is fully initialized — once per readiness
+ * cycle, so an element that is torn down and re-initialized (for example by removing and
+ * re-inserting it) fires it again. Bubbles and is composed.
  */
 class AsyncElement extends HTMLElement {
     private _readyPromise: Promise<void>;
 
     private _readyResolve!: () => void;
 
+    private _readyResolved = false;
+
     /** @ignore */
     constructor() {
         super();
@@ -26,7 +29,7 @@ class AsyncElement extends HTMLElement {
      * @returns The closest app element, or `null`.
      */
     get closestApp(): AppElement | null {
-        return this.parentElement?.closest('pc-app') as AppElement | null ?? null;
+        return (this.parentElement?.closest('pc-app') as AppElement | null) ?? null;
     }
 
     /**
@@ -35,22 +38,45 @@ class AsyncElement extends HTMLElement {
      * @returns The closest entity element, or `null`.
      */
     get closestEntity(): EntityElement | null {
-        return this.parentElement?.closest('pc-entity') as EntityElement | null ?? null;
+        return (this.parentElement?.closest('pc-entity') as EntityElement | null) ?? null;
     }
 
     /**
      * Called when the element is fully initialized and ready. Subclasses should call this when
      * they're ready. Resolves the ready promise and dispatches a bubbling, composed `ready`
-     * event.
+     * event. Signals at most once per readiness cycle: a repeat call before {@link _resetReady}
+     * has re-armed the promise does nothing.
      */
     protected _onReady() {
+        if (this._readyResolved) return;
+        this._readyResolved = true;
         this._readyResolve();
         this.dispatchEvent(new CustomEvent('ready', { bubbles: true, composed: true }));
     }
 
+    /**
+     * Returns the ready promise to its pending state. Subclasses should call this when the
+     * resource their readiness announced is torn down (typically from `disconnectedCallback`),
+     * so that a later re-initialization can signal readiness again. Does nothing while the
+     * promise is still pending — an in-flight waiter carries over to the next readiness cycle
+     * rather than being stranded on a promise nothing will ever resolve.
+     */
+    protected _resetReady() {
+        if (!this._readyResolved) return;
+        this._readyResolved = false;
+        this._readyPromise = new Promise<void>((resolve) => {
+            this._readyResolve = resolve;
+        });
+    }
+
     /**
      * Returns a promise that resolves with this element when it's ready. This is the low-level
      * primitive underlying {@link whenReady}, which is the recommended way to wait for elements.
+     *
+     * Readiness tracks the element's current lifecycle: once a ready element is torn down (for
+     * example by removing it from the document), this returns a fresh promise that resolves when
+     * the element is next ready. A promise obtained earlier stays resolved — call this again
+     * after re-inserting an element rather than reusing a promise from before its removal.
      * @returns A promise that resolves with this element when it's ready.
      */
     ready(): Promise<this> {
@@ -63,7 +89,7 @@ class AsyncElement extends HTMLElement {
  * classes extend {@link AsyncElement}).
  */
 type AsyncElementTagName = {
-    [K in keyof HTMLElementTagNameMap]: HTMLElementTagNameMap[K] extends AsyncElement ? K : never
+    [K in keyof HTMLElementTagNameMap]: HTMLElementTagNameMap[K] extends AsyncElement ? K : never;
 }[keyof HTMLElementTagNameMap];
 
 /**

package/src/components/button-component.ts

@@ -1,9 +1,11 @@
-import { BUTTON_TRANSITION_MODE_SPRITE_CHANGE, BUTTON_TRANSITION_MODE_TINT, ButtonComponent, Color, Vec4 } from 'playcanvas';
+import type { ButtonComponent } from 'playcanvas';
+import { BUTTON_TRANSITION_MODE_SPRITE_CHANGE, BUTTON_TRANSITION_MODE_TINT, Color, Vec4 } from 'playcanvas';
 
 import { AssetElement } from '../asset';
-import { ComponentElement } from './component';
 import { getEntity, parseBool, parseColor, parseEnum, parseNumber, parseVec4 } from '../parse';
 
+import { ComponentElement } from './component';
+
 const transitionModes = new Map<'tint' | 'sprite', number>([
     ['tint', BUTTON_TRANSITION_MODE_TINT],
     ['sprite', BUTTON_TRANSITION_MODE_SPRITE_CHANGE]
@@ -51,7 +53,7 @@ class ButtonComponentElement extends ComponentElement {
         super('button');
     }
 
-    getInitialComponentData() {
+    protected getInitialComponentData() {
         const data: Record<string, any> = {
             active: this._active,
             hitPadding: this._hitPadding,
@@ -448,10 +450,4 @@ class ButtonComponentElement extends ComponentElement {
 
 customElements.define('pc-button', ButtonComponentElement);
 
-declare global {
-    interface HTMLElementTagNameMap {
-        'pc-button': ButtonComponentElement;
-    }
-}
-
 export { ButtonComponentElement };

package/src/components/camera-component.ts

@@ -1,8 +1,30 @@
-import { CameraComponent, Color, Vec4, GAMMA_NONE, GAMMA_SRGB, PROJECTION_ORTHOGRAPHIC, PROJECTION_PERSPECTIVE, TONEMAP_LINEAR, TONEMAP_FILMIC, TONEMAP_NEUTRAL, TONEMAP_ACES2, TONEMAP_ACES, TONEMAP_HEJL, TONEMAP_NONE, XRTYPE_VR } from 'playcanvas';
+import type { CameraComponent } from 'playcanvas';
+import {
+    Color,
+    Vec4,
+    GAMMA_NONE,
+    GAMMA_SRGB,
+    PROJECTION_ORTHOGRAPHIC,
+    PROJECTION_PERSPECTIVE,
+    TONEMAP_LINEAR,
+    TONEMAP_FILMIC,
+    TONEMAP_NEUTRAL,
+    TONEMAP_ACES2,
+    TONEMAP_ACES,
+    TONEMAP_HEJL,
+    TONEMAP_NONE,
+    XRTYPE_VR
+} from 'playcanvas';
 
-import { ComponentElement } from './component';
 import { parseBool, parseColor, parseEnum, parseNumber, parseVec4 } from '../parse';
 
+import { ComponentElement } from './component';
+
+const projections = new Map<'perspective' | 'orthographic', number>([
+    ['perspective', PROJECTION_PERSPECTIVE],
+    ['orthographic', PROJECTION_ORTHOGRAPHIC]
+]);
+
 const tonemaps = new Map<'none' | 'linear' | 'filmic' | 'hejl' | 'aces' | 'aces2' | 'neutral', number>([
     ['none', TONEMAP_NONE],
     ['linear', TONEMAP_LINEAR],
@@ -46,7 +68,7 @@ class CameraComponentElement extends ComponentElement {
 
     private _nearClip = 0.1;
 
-    private _orthographic = false;
+    private _projection: 'perspective' | 'orthographic' = 'perspective';
 
     private _orthoHeight = 10;
 
@@ -63,7 +85,7 @@ class CameraComponentElement extends ComponentElement {
         super('camera');
     }
 
-    getInitialComponentData() {
+    protected getInitialComponentData() {
         return {
             clearColor: this._clearColor,
             clearColorBuffer: this._clearColorBuffer,
@@ -77,12 +99,12 @@ class CameraComponentElement extends ComponentElement {
             gammaCorrection: this._gamma === 'srgb' ? GAMMA_SRGB : GAMMA_NONE,
             horizontalFov: this._horizontalFov,
             nearClip: this._nearClip,
-            projection: this._orthographic ? PROJECTION_ORTHOGRAPHIC : PROJECTION_PERSPECTIVE,
+            projection: projections.get(this._projection) ?? PROJECTION_PERSPECTIVE,
             orthoHeight: this._orthoHeight,
             priority: this._priority,
             rect: this._rect,
             scissorRect: this._scissorRect,
-            toneMapping: tonemaps.get(this._tonemap)
+            toneMapping: tonemaps.get(this._tonemap) ?? TONEMAP_NONE
         };
     }
 
@@ -96,7 +118,10 @@ class CameraComponentElement extends ComponentElement {
      * @param type - The type of XR mode to start.
      * @param space - The space to start the camera in.
      */
-    startXr(type: 'immersive-ar' | 'immersive-vr', space: 'bounded-floor' | 'local' | 'local-floor' | 'unbounded' | 'viewer') {
+    startXr(
+        type: 'immersive-ar' | 'immersive-vr',
+        space: 'bounded-floor' | 'local' | 'local-floor' | 'unbounded' | 'viewer'
+    ) {
         if (this.component && this.xrAvailable) {
             this.component.startXr(type, space, {
                 callback: (err: any) => {
@@ -352,25 +377,6 @@ class CameraComponentElement extends ComponentElement {
         return this._nearClip;
     }
 
-    /**
-     * Sets the orthographic projection of the camera.
-     * @param value - The orthographic projection.
-     */
-    set orthographic(value) {
-        this._orthographic = value;
-        if (this.component) {
-            this.component.projection = value ? PROJECTION_ORTHOGRAPHIC : PROJECTION_PERSPECTIVE;
-        }
-    }
-
-    /**
-     * Gets the orthographic projection of the camera.
-     * @returns The orthographic projection.
-     */
-    get orthographic(): boolean {
-        return this._orthographic;
-    }
-
     /**
      * Sets the orthographic height of the camera.
      * @param value - The orthographic height.
@@ -409,6 +415,25 @@ class CameraComponentElement extends ComponentElement {
         return this._priority;
     }
 
+    /**
+     * Sets the projection of the camera. Use `orthoHeight` to size an orthographic projection.
+     * @param value - The projection ('perspective' or 'orthographic').
+     */
+    set projection(value: 'perspective' | 'orthographic') {
+        this._projection = value;
+        if (this.component) {
+            this.component.projection = projections.get(value) ?? PROJECTION_PERSPECTIVE;
+        }
+    }
+
+    /**
+     * Gets the projection of the camera.
+     * @returns The projection.
+     */
+    get projection() {
+        return this._projection;
+    }
+
     /**
      * Sets the rect of the camera.
      * @param value - The rect.
@@ -481,9 +506,9 @@ class CameraComponentElement extends ComponentElement {
             'gamma',
             'horizontal-fov',
             'near-clip',
-            'orthographic',
             'ortho-height',
             'priority',
+            'projection',
             'rect',
             'scissor-rect',
             'tonemap'
@@ -530,15 +555,15 @@ class CameraComponentElement extends ComponentElement {
             case 'near-clip':
                 this.nearClip = parseNumber(newValue, 0.1, name);
                 break;
-            case 'orthographic':
-                this.orthographic = parseBool(newValue, false);
-                break;
             case 'ortho-height':
                 this.orthoHeight = parseNumber(newValue, 10, name);
                 break;
             case 'priority':
                 this.priority = parseNumber(newValue, 0, name);
                 break;
+            case 'projection':
+                this.projection = parseEnum(newValue, projections, 'perspective', name);
+                break;
             case 'rect':
                 this.rect = parseVec4(newValue, new Vec4(0, 0, 1, 1), name);
                 break;
@@ -554,10 +579,4 @@ class CameraComponentElement extends ComponentElement {
 
 customElements.define('pc-camera', CameraComponentElement);
 
-declare global {
-    interface HTMLElementTagNameMap {
-        'pc-camera': CameraComponentElement;
-    }
-}
-
 export { CameraComponentElement };

package/src/components/collision-component.ts

@@ -1,8 +1,10 @@
-import { CollisionComponent, Quat, Vec3 } from 'playcanvas';
+import type { CollisionComponent } from 'playcanvas';
+import { Quat, Vec3 } from 'playcanvas';
 
-import { ComponentElement } from './component';
 import { parseBool, parseEnum, parseNumber, parseQuat, parseVec3 } from '../parse';
 
+import { ComponentElement } from './component';
+
 /**
  * The CollisionComponentElement interface provides properties and methods for manipulating
  * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-collision/ | `<pc-collision>`} elements.
@@ -14,17 +16,17 @@ import { parseBool, parseEnum, parseNumber, parseQuat, parseVec3 } from '../pars
 class CollisionComponentElement extends ComponentElement {
     private _angularOffset: Quat = new Quat();
 
-    private _axis: number = 1;
+    private _axis = 1;
 
-    private _convexHull: boolean = false;
+    private _convexHull = false;
 
     private _halfExtents: Vec3 = new Vec3(0.5, 0.5, 0.5);
 
-    private _height: number = 2;
+    private _height = 2;
 
     private _linearOffset: Vec3 = new Vec3();
 
-    private _radius: number = 0.5;
+    private _radius = 0.5;
 
     private _type: 'box' | 'capsule' | 'compound' | 'cone' | 'cylinder' | 'mesh' | 'sphere' = 'box';
 
@@ -33,7 +35,7 @@ class CollisionComponentElement extends ComponentElement {
         super('collision');
     }
 
-    getInitialComponentData() {
+    protected getInitialComponentData() {
         return {
             axis: this._axis,
             angularOffset: this._angularOffset,
@@ -143,7 +145,17 @@ class CollisionComponentElement extends ComponentElement {
     }
 
     static get observedAttributes() {
-        return [...super.observedAttributes, 'angular-offset', 'axis', 'convex-hull', 'half-extents', 'height', 'linear-offset', 'radius', 'type'];
+        return [
+            ...super.observedAttributes,
+            'angular-offset',
+            'axis',
+            'convex-hull',
+            'half-extents',
+            'height',
+            'linear-offset',
+            'radius',
+            'type'
+        ];
     }
 
     attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null) {
@@ -172,7 +184,12 @@ class CollisionComponentElement extends ComponentElement {
                 this.radius = parseNumber(newValue, 0.5, name);
                 break;
             case 'type':
-                this.type = parseEnum(newValue, ['box', 'capsule', 'compound', 'cone', 'cylinder', 'mesh', 'sphere'], 'box', name);
+                this.type = parseEnum(
+                    newValue,
+                    ['box', 'capsule', 'compound', 'cone', 'cylinder', 'mesh', 'sphere'],
+                    'box',
+                    name
+                );
                 break;
         }
     }
@@ -180,10 +197,4 @@ class CollisionComponentElement extends ComponentElement {
 
 customElements.define('pc-collision', CollisionComponentElement);
 
-declare global {
-    interface HTMLElementTagNameMap {
-        'pc-collision': CollisionComponentElement;
-    }
-}
-
 export { CollisionComponentElement };

package/src/components/component.ts

@@ -1,6 +1,6 @@
-import { Component } from 'playcanvas';
+import type { Component } from 'playcanvas';
 
-import { AppElement } from '../app';
+import type { AppElement } from '../app';
 import { AsyncElement } from '../async-element';
 import { parseBool } from '../parse';
 
@@ -18,6 +18,15 @@ class ComponentElement extends AsyncElement {
 
     private _appElement: AppElement | null = null;
 
+    /**
+     * Incremented on every connect and disconnect. connectedCallback captures the value on entry
+     * and abandons itself wherever it resumes from an await if the value has moved on — so a
+     * callback whose element was removed cannot act on a torn-down tree, and one whose element
+     * was removed and re-inserted (which runs a callback of its own) cannot add the component a
+     * second time.
+     */
+    private _connectionGeneration = 0;
+
     /**
      * Creates a new ComponentElement instance.
      *
@@ -30,38 +39,78 @@ class ComponentElement extends AsyncElement {
         this._componentName = componentName;
     }
 
-    // Method to be overridden by subclasses to provide initial component data
-    getInitialComponentData() {
+    /**
+     * Returns the data the component is created with. Overridden by subclasses to supply the
+     * initial values of their cached properties.
+     *
+     * @returns The initial component data.
+     */
+    protected getInitialComponentData() {
         return {};
     }
 
-    async addComponent() {
+    private async _addComponent() {
+        const generation = this._connectionGeneration;
+
         const entityElement = this.closestEntity;
         if (!entityElement) {
             // A component can only exist on an entity, so an element placed outside one is inert.
             // It still becomes ready (with a null `component`), so warn rather than fail silently
             const label = this.id ? ` '${this.id}'` : '';
-            console.warn(`${this.tagName.toLowerCase()}${label} must be a descendant of pc-entity - component not added`);
+            console.warn(
+                `${this.tagName.toLowerCase()}${label} must be a descendant of pc-entity - component not added`
+            );
             return;
         }
 
         await entityElement.ready();
+
+        // The element may have been removed, or removed and re-inserted, while the entity became
+        // ready — the component belongs to the connection that owns the current generation.
+        if (generation !== this._connectionGeneration) {
+            return;
+        }
+
         // Add the component to the entity
         const data = this.getInitialComponentData();
         this._component = entityElement.entity!.addComponent(this._componentName, data);
     }
 
-    initComponent() {}
+    /**
+     * Configures the newly added component. Overridden by subclasses whose setup goes beyond
+     * the initial data — child-element handling, asset resolution and the like.
+     */
+    protected initComponent() {
+        // optional hook
+    }
 
     async connectedCallback() {
+        const generation = ++this._connectionGeneration;
+
         this._appElement = this.closestApp ?? null;
         await this._appElement?.ready();
-        await this.addComponent();
+
+        // The element may have been removed, or removed and re-inserted, while the application
+        // became ready. A re-insertion runs a connectedCallback of its own, so a stale resume
+        // must not add the component alongside it.
+        if (generation !== this._connectionGeneration) {
+            return;
+        }
+
+        await this._addComponent();
+
+        if (generation !== this._connectionGeneration) {
+            return;
+        }
+
         this.initComponent();
         this._onReady();
     }
 
     disconnectedCallback() {
+        // Invalidate any connectedCallback still suspended on an await
+        this._connectionGeneration++;
+
         // Remove the component when the element is disconnected. Skip this when the owning
         // application has already been destroyed — removing a <pc-app> disconnects it before
         // its children, taking the component systems with it.
@@ -70,6 +119,7 @@ class ComponentElement extends AsyncElement {
         }
         this._component = null;
         this._appElement = null;
+        this._resetReady();
     }
 
     /**