@playcanvas/web-components 0.12.0 → 0.13.0

package/dist/pwc.js

@@ -1,7 +1,7 @@
 (function (global, factory) {
     typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports, require('playcanvas')) :
     typeof define === 'function' && define.amd ? define(['exports', 'playcanvas'], factory) :
-    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.pd = {}, global.pc));
+    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.pwc = {}, global.pc));
 })(this, (function (exports, playcanvas) { 'use strict';
 
     /**
@@ -112,12 +112,18 @@
 
     /**
      * The ModuleElement interface provides properties and methods for manipulating
-     * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-module/ | `<pc-module>`} elements.
-     * The ModuleElement interface also inherits the properties and methods of the
-     * {@link HTMLElement} interface.
+     * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-module/ | `<pc-module>`}
+     * elements. The ModuleElement interface also inherits the properties and methods of the
+     * {@link AsyncElement} interface.
+     *
+     * The attributes are read once, when the module starts loading - on the element's first
+     * connection, or earlier if a containing `<pc-app>` boots first and collects it - so changing
+     * them later has no effect. The element becomes ready once the module has loaded. WebAssembly
+     * modules configure engine-global state that never unloads, so readiness is not re-armed by
+     * removing the element, and a re-inserted element does not load again.
      *
-     * Note that these attributes are read once when the element is created, so changing them later
-     * has no effect.
+     * A `<pc-module>` without a `name` warns and never becomes ready; a containing `<pc-app>` still
+     * boots.
      *
      * @attribute {string} name - The name of the WebAssembly module to configure, e.g. `Basis` or
      * `Ammo`.
@@ -126,19 +132,22 @@
      * @attribute {string} fallback - The URL of the module's asm.js fallback script, used when
      * WebAssembly is unavailable.
      */
-    class ModuleElement extends HTMLElement {
-        loadPromise;
-        /** @ignore */
-        constructor() {
-            super();
-            this.loadPromise = this.loadModule();
+    class ModuleElement extends AsyncElement {
+        _loadPromise = null;
+        connectedCallback() {
+            this._getLoadPromise();
         }
-        async loadModule() {
+        async _loadModule() {
             const name = this.getAttribute('name');
-            const glueUrl = this.getAttribute('glue');
-            const wasmUrl = this.getAttribute('wasm');
-            const fallbackUrl = this.getAttribute('fallback');
-            const config = { glueUrl, wasmUrl, fallbackUrl };
+            if (!name) {
+                console.warn("pc-module requires a 'name' attribute - no module was configured");
+                return;
+            }
+            const config = {
+                glueUrl: this.getAttribute('glue') ?? undefined,
+                wasmUrl: this.getAttribute('wasm') ?? undefined,
+                fallbackUrl: this.getAttribute('fallback') ?? undefined
+            };
             if (name === 'Basis') {
                 playcanvas.basisInitialize(config);
             }
@@ -148,16 +157,22 @@
                     playcanvas.WasmModule.getInstance(name, () => resolve());
                 });
             }
+            this._onReady();
         }
         /**
-         * 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 promise that settles when the module has loaded, starting the load if it has
+         * not already started - a containing `<pc-app>` boots in document order, so it may collect
+         * this element before the element's own connectedCallback has run. A missing `name` resolves
+         * the promise without configuring anything, so a misconfigured module never blocks the app.
          *
          * @returns The load promise.
          * @internal
          */
         _getLoadPromise() {
-            return this.loadPromise;
+            if (!this._loadPromise) {
+                this._loadPromise = this._loadModule();
+            }
+            return this._loadPromise;
         }
     }
     customElements.define('pc-module', ModuleElement);
@@ -187,9 +202,9 @@
             this._track.setAttribute('aria-label', 'Loading');
             this._track.setAttribute('aria-valuemin', '0');
             this._track.setAttribute('aria-valuemax', '100');
-            // Fixed positioning matches the canvas, which always fills the window (FILLMODE_FILL_WINDOW)
+            // Anchored to the pc-app element, which the library's base styles make a positioned box
             this._track.style.cssText = [
-                'position: fixed',
+                'position: absolute',
                 'top: 0',
                 'left: 0',
                 'width: 100%',
@@ -701,16 +716,44 @@
 
     /** The pointer event types the application synthesizes on `<pc-entity>` elements via picking. */
     const pointerEventTypes = ['pointermove', 'pointerdown', 'pointerup', 'pointerenter', 'pointerleave'];
+    /**
+     * 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 {
         /**
@@ -770,6 +813,12 @@
         };
         _app = null;
         _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.
+         */
+        _resizeObserver = 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()`
@@ -796,8 +845,6 @@
          */
         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.
@@ -808,6 +855,9 @@
         }
         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) {
@@ -822,8 +872,11 @@
             if (generation !== this._bootGeneration) {
                 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
             const backendToDeviceTypes = {
@@ -833,14 +886,44 @@
             };
             const deviceTypes = backendToDeviceTypes[this._backend] || [];
             this._optionsLocked = true;
-            const device = await playcanvas.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;
+            try {
+                device = await playcanvas.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
             // this boot's to release.
@@ -919,9 +1002,19 @@
             const app = new playcanvas.AppBase(this._canvas);
             this._app = app;
             app.init(createOptions);
-            app.setCanvasFillMode(playcanvas.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(playcanvas.FILLMODE_NONE);
             app.setCanvasResolution(playcanvas.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(':scope > pc-asset');
             for (const assetElement of Array.from(assetElements)) {
@@ -997,8 +1090,6 @@
                 // Dismiss the bar only once a frame has actually rendered; ready fires before the
                 // first rAF tick
                 app.once('frameend', () => this._bar?.complete());
-                // Handle window resize to keep the canvas responsive
-                window.addEventListener('resize', this._onWindowResize);
                 this._onReady();
             });
         }
@@ -1023,18 +1114,27 @@
             // no longer holds.
             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)) {
                 this.removeChild(this._canvas);
                 this._canvas = null;
             }
         }
-        _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.
+         */
+        _syncCanvasSize() {
+            if (!this.app || this.app.xr?.active) {
+                return;
             }
+            this.app.updateCanvasSize();
+            const { width, height } = this.app.graphicsDevice;
+            this._picker?.resize(width, height);
         }
         _pickerCreate() {
             const { width, height } = this.app.graphicsDevice;
@@ -1372,7 +1472,7 @@
             this._maxPixelRatio = value;
             if (this.app) {
                 this.app.graphicsDevice.maxPixelRatio = value;
-                this.app.resizeCanvas();
+                this._syncCanvasSize();
             }
         }
         /**