@playcanvas/web-components 0.11.1 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcanvas/web-components",
-  "version": "0.11.1",
+  "version": "0.13.0",
   "author": "PlayCanvas <support@playcanvas.com>",
   "homepage": "https://playcanvas.com",
   "description": "Web Components for the PlayCanvas Engine",
@@ -32,14 +32,23 @@
   "web-types": "dist/web-types.json",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/pwc.mjs",
-      "require": "./dist/pwc.cjs"
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/pwc.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/pwc.cjs"
+      }
     },
     "./dist/*": "./dist/*",
     "./package.json": "./package.json"
   },
   "type": "module",
+  "sideEffects": true,
+  "engines": {
+    "node": ">=18.3.0"
+  },
   "files": [
     "dist",
     "src"
@@ -47,7 +56,7 @@
   "scripts": {
     "prebuild": "node -e \"fs.rmSync('dist', { recursive: true, force: true })\"",
     "build": "rollup -c",
-    "postbuild": "npm run cem",
+    "postbuild": "node utils/fix-declarations.mjs && npm run cem",
     "cem": "cem analyze && node utils/cem/validate.mjs",
     "dev": "concurrently \"npm run watch\" \"npm run serve\"",
     "docs": "typedoc",
@@ -89,9 +98,9 @@
     "eslint": "9.39.5",
     "globals": "17.9.0",
     "jsdom": "30.0.1",
-    "mediabunny": "1.52.3",
+    "mediabunny": "1.53.0",
     "opentype.js": "2.0.0",
-    "playcanvas": "2.21.3",
+    "playcanvas": "2.22.0-beta.12",
     "prettier": "3.9.6",
     "publint": "0.3.23",
     "rollup": "4.62.4",

package/src/app.ts

@@ -1,10 +1,10 @@
-import type { CameraComponent, GraphNode, GSplatComponent, Entity } from 'playcanvas';
+import type { CameraComponent, GraphicsDevice, GraphNode, GSplatComponent, Entity } from 'playcanvas';
 import {
     AppBase,
     AppOptions,
     createGraphicsDevice,
     ElementInput,
-    FILLMODE_FILL_WINDOW,
+    FILLMODE_NONE,
     Keyboard,
     Mouse,
     Picker,
@@ -67,6 +67,7 @@ import {
 import type { AssetElement } from './asset';
 import { AsyncElement } from './async-element';
 import type { EntityElement } from './entity';
+import type { EntityBaseElement } from './entity-base';
 import { LoadingBar } from './loading-bar';
 import type { MaterialElement } from './material';
 import type { ModuleElement } from './module';
@@ -75,16 +76,45 @@ 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;
 
+/**
+ * Gives `pc-app` the sizing contract of a replaced element (`<video>`, `<img>`): a block-level
+ * box that the page's CSS sizes, defaulting to the canvas's own 300x150 intrinsic size, with the
+ * canvas and loading bar anchored to it. `:where()` keeps every declaration at zero specificity,
+ * so any page rule - however plain - overrides these defaults.
+ */
+const ensureBaseStyles = () => {
+    const id = 'pc-app-styles';
+    if (document.getElementById(id)) {
+        return;
+    }
+    const style = document.createElement('style');
+    style.id = id;
+    style.textContent = ':where(pc-app) { display: block; position: relative; width: 300px; height: 150px; }';
+    document.head.appendChild(style);
+};
+
 /**
  * The AppElement interface provides properties and methods for manipulating
  * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-app/ | `<pc-app>`} elements.
  * The AppElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * The element is sized like a replaced element such as `<video>`: a block-level box that the
+ * page's CSS controls, 300x150 by default. The application's canvas always fills the element,
+ * and the drawing buffer resolution follows the element's size (capped by `max-pixel-ratio`),
+ * tracked live via a ResizeObserver — so the element can be embedded at any size, resized by
+ * its container, or made fullscreen with ordinary CSS such as `width: 100vw; height: 100dvh`.
+ *
  * @fires {ProgressEvent} progress - Fired while the application preloads its assets. `loaded` and
  * `total` are asset counts, not bytes, and an asset that fails to load still counts as loaded.
  * Fired at least once per boot, and the final event always has `loaded` equal to `total`. Does
  * not bubble.
+ *
+ * @fires {ErrorEvent} error - Fired when the application cannot boot because no graphics device
+ * could be created (for example, a browser with WebGL disabled). `message` names the requested
+ * backends and `error` holds the underlying failure. The element never becomes ready
+ * and `app` stays `null` — listen for this event to show a fallback UI. Removing the element and
+ * re-inserting it retries the boot with its current attributes. Does not bubble.
  */
 class AppElement extends AsyncElement {
     /**
@@ -133,10 +163,11 @@ class AppElement extends AsyncElement {
 
     /**
      * 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;
 
@@ -148,7 +179,7 @@ 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;
@@ -163,6 +194,13 @@ class AppElement extends AsyncElement {
 
     private _loadProgress = 0;
 
+    /**
+     * Tracks the element's box so the drawing buffer and picker follow it. Created per boot once
+     * the application exists, and disconnected on teardown. `null` where ResizeObserver is
+     * unavailable (jsdom), where the boot-time resolution set is the only sizing that happens.
+     */
+    private _resizeObserver: ResizeObserver | null = null;
+
     /**
      * The PlayCanvas application instance. `null` until the element is ready, and again once it
      * has been removed from the document — await {@link whenReady} or the element's `ready()`
@@ -192,9 +230,6 @@ class AppElement extends AsyncElement {
     constructor() {
         super();
 
-        // 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.
@@ -207,6 +242,10 @@ class AppElement extends AsyncElement {
     async connectedCallback() {
         const generation = ++this._bootGeneration;
 
+        // Installed before the loading bar is created: the bar anchors to this element, which
+        // these styles make a positioned block box
+        ensureBaseStyles();
+
         // 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) {
@@ -225,8 +264,11 @@ class AppElement extends AsyncElement {
             return;
         }
 
-        // Create and append the canvas to the element
+        // Create and append the canvas, filling the element's content box - the page sizes the
+        // element, and everything else follows. touch-action: none keeps touch drags driving the
+        // engine's input handlers instead of scrolling the page.
         this._canvas = document.createElement('canvas');
+        this._canvas.style.cssText = 'display: block; width: 100%; height: 100%; touch-action: none;';
         this.appendChild(this._canvas);
 
         // Configure device types based on backend selection
@@ -239,14 +281,46 @@ class AppElement extends AsyncElement {
 
         this._optionsLocked = true;
 
-        const device = await createGraphicsDevice(this._canvas, {
-            // @ts-ignore - alpha needs to be documented
-            alpha: this._alpha,
-            antialias: this._antialias,
-            depth: this._depthBuffer,
-            deviceTypes: deviceTypes,
-            stencil: this._stencilBuffer
-        });
+        // createGraphicsDevice appends its final null-device fallback to the array in place, so
+        // the requested list is captured now for the failure message.
+        const requested = deviceTypes.join(', ');
+
+        let device: GraphicsDevice;
+        try {
+            device = await createGraphicsDevice(this._canvas, {
+                // @ts-ignore - alpha needs to be documented
+                alpha: this._alpha,
+                antialias: this._antialias,
+                depth: this._depthBuffer,
+                deviceTypes: deviceTypes,
+                stencil: this._stencilBuffer
+            });
+        } catch (error) {
+            // The element may have been removed while device creation was failing. The teardown
+            // has already cleaned up, and the failure belongs to a boot that no longer owns the
+            // element.
+            if (generation !== this._bootGeneration) {
+                return;
+            }
+
+            // Return the element to its pre-boot state - no dead canvas, no loading bar stuck at
+            // zero - before announcing the failure. Readiness deliberately stays pending: nothing
+            // it would announce (the app, the entity hierarchy) exists, so a device-less element
+            // joins the documented never-ready cases and the failure surfaces through the error
+            // event instead.
+            if (this._canvas && this.contains(this._canvas)) {
+                this.removeChild(this._canvas);
+            }
+            this._canvas = null;
+            this._bar?.destroy();
+            this._bar = null;
+
+            const reason = error instanceof Error ? error.message : String(error);
+            const message = `pc-app failed to create a graphics device (${requested}) - ${reason}`;
+            console.error(message, error);
+            this.dispatchEvent(new ErrorEvent('error', { message, error }));
+            return;
+        }
 
         // 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
@@ -330,11 +404,22 @@ class AppElement extends AsyncElement {
         this._app = app;
         app.init(createOptions);
 
-        app.setCanvasFillMode(FILLMODE_FILL_WINDOW);
+        // FILLMODE_NONE leaves the canvas's CSS sizing alone (the engine's other fill modes
+        // stamp window-derived pixel sizes onto it); RESOLUTION_AUTO sizes the drawing buffer
+        // from the canvas's client size
+        app.setCanvasFillMode(FILLMODE_NONE);
         app.setCanvasResolution(RESOLUTION_AUTO);
 
         this._pickerCreate();
 
+        // Track the element's box rather than the window: containers resize without any window
+        // event (splitter drags, flex reflow, animations). Guarded because jsdom has no
+        // ResizeObserver - there, the resolution set above is the only sizing that happens.
+        if (typeof ResizeObserver !== 'undefined') {
+            this._resizeObserver = new ResizeObserver(() => this._syncCanvasSize());
+            this._resizeObserver.observe(this);
+        }
+
         // Get all pc-asset elements that are direct children of the pc-app element
         const assetElements = this.querySelectorAll<AssetElement>(':scope > pc-asset');
         for (const assetElement of Array.from(assetElements)) {
@@ -424,9 +509,6 @@ class AppElement extends AsyncElement {
             // first rAF tick
             app.once('frameend', () => this._bar?.complete());
 
-            // Handle window resize to keep the canvas responsive
-            window.addEventListener('resize', this._onWindowResize);
-
             this._onReady();
         });
     }
@@ -456,8 +538,9 @@ class AppElement extends AsyncElement {
         this._hierarchyReady = false;
         this._resetReady();
 
-        // Remove event listeners
-        window.removeEventListener('resize', this._onWindowResize);
+        // Stop tracking the element's size
+        this._resizeObserver?.disconnect();
+        this._resizeObserver = null;
 
         // Remove the canvas
         if (this._canvas && this.contains(this._canvas)) {
@@ -466,10 +549,18 @@ class AppElement extends AsyncElement {
         }
     }
 
-    private _onWindowResize() {
-        if (this.app) {
-            this.app.resizeCanvas();
+    /**
+     * Syncs the drawing buffer and the picker to the canvas's current CSS size. The picker must
+     * track the buffer, or picks would land at stale coordinates after a resize. Skipped while
+     * an XR session presents - the session owns the buffer size.
+     */
+    private _syncCanvasSize() {
+        if (!this.app || this.app.xr?.active) {
+            return;
         }
+        this.app.updateCanvasSize();
+        const { width, height } = this.app.graphicsDevice;
+        this._picker?.resize(width, height);
     }
 
     private _pickerCreate() {
@@ -493,8 +584,8 @@ class AppElement extends AsyncElement {
         // 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)
+            const anyListeners = Array.from(this.querySelectorAll<EntityBaseElement>('pc-entity, pc-node')).some(
+                (entity) => entity._hasListeners(type)
             );
             if (anyListeners) {
                 this._onPointerListenerAdded(type);
@@ -528,14 +619,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.
+     * @param element - The element that fronts it.
      * @internal
      */
-    _registerEntityElement(entity: Entity, element: EntityElement) {
+    _registerEntityElement(entity: Entity, element: EntityBaseElement) {
         this._entityElements.set(entity, element);
     }
 
@@ -550,27 +641,28 @@ class AppElement extends AsyncElement {
     }
 
     /**
-     * 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) {
@@ -589,7 +681,7 @@ 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)) {
@@ -715,7 +807,7 @@ class AppElement extends AsyncElement {
     }
 
     private _onPointerListenerRemoved(type: string) {
-        const hasListeners = Array.from(this.querySelectorAll<EntityElement>('pc-entity')).some((entity) =>
+        const hasListeners = Array.from(this.querySelectorAll<EntityBaseElement>('pc-entity, pc-node')).some((entity) =>
             entity._hasListeners(type)
         );
 
@@ -859,7 +951,7 @@ class AppElement extends AsyncElement {
         this._maxPixelRatio = value;
         if (this.app) {
             this.app.graphicsDevice.maxPixelRatio = value;
-            this.app.resizeCanvas();
+            this._syncCanvasSize();
         }
     }