@playcanvas/web-components 0.12.0 → 0.13.0

package/dist/pwc.cjs

@@ -110,12 +110,18 @@ async function whenReady(target) {
 
 /**
  * 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`.
@@ -124,19 +130,22 @@ async function whenReady(target) {
  * @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);
         }
@@ -146,16 +155,22 @@ class ModuleElement extends HTMLElement {
                 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);
@@ -185,9 +200,9 @@ class LoadingBar {
         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%',
@@ -699,16 +714,44 @@ const getEntity = (ref) => {
 
 /** 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 {
     /**
@@ -768,6 +811,12 @@ class AppElement extends AsyncElement {
     };
     _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()`
@@ -794,8 +843,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.
@@ -806,6 +853,9 @@ 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) {
@@ -820,8 +870,11 @@ class AppElement extends AsyncElement {
         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 = {
@@ -831,14 +884,44 @@ class AppElement extends AsyncElement {
         };
         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.
@@ -917,9 +1000,19 @@ class AppElement extends AsyncElement {
         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)) {
@@ -995,8 +1088,6 @@ class AppElement extends AsyncElement {
             // 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();
         });
     }
@@ -1021,18 +1112,27 @@ class AppElement extends AsyncElement {
         // 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;
@@ -1370,7 +1470,7 @@ class AppElement extends AsyncElement {
         this._maxPixelRatio = value;
         if (this.app) {
             this.app.graphicsDevice.maxPixelRatio = value;
-            this.app.resizeCanvas();
+            this._syncCanvasSize();
         }
     }
     /**