@playcanvas/web-components 0.11.0 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcanvas/web-components",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "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",
+    "playcanvas": "2.22.0-beta.10",
+    "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,21 @@ 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 type { EntityBaseElement } from './entity-base';
 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,18 +116,33 @@ 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
-     * by EntityElement at creation and removed when an entity is destroyed, this joins engine
-     * scene nodes back to their owning elements by identity - never by name.
+     * by EntityElement at creation (and NodeElement at binding) and removed when an entity is
+     * destroyed or unbound, this joins engine scene nodes back to their owning elements by
+     * identity - never by name.
      */
-    private _entityElements = new Map<GraphNode, EntityElement>();
+    private _entityElements = new Map<GraphNode, EntityBaseElement>();
 
     private _picker: Picker | null = null;
 
-    private _hasPointerListeners: { [key: string]: boolean } = {
+    private _hasPointerListeners: Record<string, boolean> = {
         pointerenter: false,
         pointerleave: false,
         pointerdown: false,
@@ -134,12 +150,12 @@ class AppElement extends AsyncElement {
         pointermove: false
     };
 
-    private _hoveredEntity: EntityElement | null = null;
+    private _hoveredEntity: EntityBaseElement | 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 } = {
+    private _pointerHandlers: Record<string, EventListener | null> = {
         pointermove: null,
         pointerdown: null,
         pointerup: null
@@ -180,9 +196,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 +219,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 +250,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 +339,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 +399,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 +434,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 +452,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 +468,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 +491,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<EntityBaseElement>('pc-entity, pc-node')
+            ).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 +514,7 @@ class AppElement extends AsyncElement {
         }
 
         this._picker = null;
+        this._hoveredEntity = null;
         this._pointerHandlers = {
             pointermove: null,
             pointerdown: null,
@@ -452,14 +530,14 @@ class AppElement extends AsyncElement {
     }
 
     /**
-     * Registers the element that created an entity. Called by EntityElement when it creates its
-     * entity.
+     * Registers the element that fronts an entity. Called by EntityElement when it creates its
+     * entity, and by NodeElement when it binds one.
      *
      * @param entity - The entity.
-     * @param element - The element that created it.
-     * @ignore
+     * @param element - The element that fronts it.
+     * @internal
      */
-    _registerEntityElement(entity: Entity, element: EntityElement) {
+    _registerEntityElement(entity: Entity, element: EntityBaseElement) {
         this._entityElements.set(entity, element);
     }
 
@@ -467,34 +545,35 @@ 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);
     }
 
     /**
-     * Returns the `<pc-entity>` element whose backing entity is `entity`, or `null` if the
-     * entity was not created by an element of this application - for example, a node inside a
-     * model's instantiated hierarchy, or an entity created through the engine API.
+     * Returns the `<pc-entity>` or `<pc-node>` element whose backing entity is `entity`, or
+     * `null` if the entity is not fronted by an element of this application - for example, an
+     * unbound node inside a model's instantiated hierarchy, or an entity created through the
+     * engine API.
      *
      * @param entity - The entity to look up.
-     * @returns The element backing the entity, or `null`.
+     * @returns The element fronting the entity, or `null`.
      */
-    elementFromEntity(entity: Entity): EntityElement | null {
+    elementFromEntity(entity: Entity): EntityBaseElement | null {
         return this._entityElements.get(entity) ?? null;
     }
 
     /**
      * Resolves the element that owns a picked node: the nearest node up the parent chain -
-     * starting with the node itself - that was created by a `<pc-entity>` of this application.
-     * A hit inside a model's instantiated hierarchy therefore resolves to the element hosting
-     * the model.
+     * starting with the node itself - that is fronted by a `<pc-entity>` or `<pc-node>` of this
+     * application. A hit inside a model's instantiated hierarchy therefore resolves to the
+     * nearest bound `<pc-node>`, or failing that the element hosting the model.
      *
      * @param node - The picked node, or `null`.
      * @returns The owning element, or `null`.
      */
-    private _elementFromNode(node: GraphNode | null): EntityElement | null {
+    private _elementFromNode(node: GraphNode | null): EntityBaseElement | null {
         while (node !== null) {
             const element = this._entityElements.get(node);
             if (element) {
@@ -513,10 +592,10 @@ class AppElement extends AsyncElement {
      * @param type - The pointer event type a listener is required for.
      * @returns The nearest listening element, or `null`.
      */
-    private _elementWithListener(node: GraphNode | null, type: string): EntityElement | null {
+    private _elementWithListener(node: GraphNode | null, type: string): EntityBaseElement | 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 +604,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 +641,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 +657,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 +669,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 +686,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 +698,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<EntityBaseElement>('pc-entity, pc-node')
+        ).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 +748,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 +825,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 +925,4 @@ class AppElement extends AsyncElement {
 
 customElements.define('pc-app', AppElement);
 
-declare global {
-    interface HTMLElementTagNameMap {
-        'pc-app': AppElement;
-    }
-}
-
 export { AppElement };