@playcanvas/web-components 0.12.0 → 0.13.0

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,
@@ -76,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 {
     /**
@@ -165,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()`
@@ -194,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.
@@ -209,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) {
@@ -227,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
@@ -241,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
@@ -332,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)) {
@@ -426,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();
         });
     }
@@ -458,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)) {
@@ -468,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() {
@@ -495,9 +584,9 @@ 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<EntityBaseElement>('pc-entity, pc-node')
-            ).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);
             }
@@ -718,9 +807,9 @@ class AppElement extends AsyncElement {
     }
 
     private _onPointerListenerRemoved(type: string) {
-        const hasListeners = Array.from(
-            this.querySelectorAll<EntityBaseElement>('pc-entity, pc-node')
-        ).some((entity) => entity._hasListeners(type));
+        const hasListeners = Array.from(this.querySelectorAll<EntityBaseElement>('pc-entity, pc-node')).some((entity) =>
+            entity._hasListeners(type)
+        );
 
         if (!hasListeners && this._canvas) {
             this._hasPointerListeners[type] = false;
@@ -862,7 +951,7 @@ class AppElement extends AsyncElement {
         this._maxPixelRatio = value;
         if (this.app) {
             this.app.graphicsDevice.maxPixelRatio = value;
-            this.app.resizeCanvas();
+            this._syncCanvasSize();
         }
     }
 

package/src/async-element.ts

@@ -96,7 +96,8 @@ type AsyncElementTagName = {
 /**
  * Waits for the first element matching the given tag name to be fully initialized. Note that the
  * promise never settles if the element cannot finish initializing (for example, a `<pc-script>`
- * that is not a direct child of `<pc-scripts>`). A component element outside a `<pc-entity>` is
+ * that is not a direct child of `<pc-scripts>`, or a `<pc-app>` that could not create a graphics
+ * device — listen for its `error` event instead). A component element outside a `<pc-entity>` is
  * the exception: it still becomes ready, but its `component` is `null`. Either way, a misplaced
  * element logs a warning naming the parent it requires.
  * @param target - The tag name of the element to wait for (e.g. `'pc-app'`).
@@ -120,7 +121,8 @@ function whenReady<T extends AsyncElement>(target: T): Promise<T>;
 /**
  * Waits for the first element matching the given CSS selector to be fully initialized. Note that
  * the promise never settles if the element cannot finish initializing (for example, a `<pc-script>`
- * that is not a direct child of `<pc-scripts>`). A component element outside a `<pc-entity>` is
+ * that is not a direct child of `<pc-scripts>`, or a `<pc-app>` that could not create a graphics
+ * device — listen for its `error` event instead). A component element outside a `<pc-entity>` is
  * the exception: it still becomes ready, but its `component` is `null`. Either way, a misplaced
  * element logs a warning naming the parent it requires.
  * @param target - A CSS selector matching the element to wait for (e.g. `'#my-app'`).

package/src/loading-bar.ts

@@ -28,9 +28,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%',

package/src/module.ts

@@ -1,13 +1,21 @@
 import { basisInitialize, WasmModule } from 'playcanvas';
 
+import { AsyncElement } from './async-element';
+
 /**
  * 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`.
@@ -16,21 +24,25 @@ import { basisInitialize, WasmModule } from 'playcanvas';
  * @attribute {string} fallback - The URL of the module's asm.js fallback script, used when
  * WebAssembly is unavailable.
  */
-class ModuleElement extends HTMLElement {
-    private loadPromise: Promise<void>;
+class ModuleElement extends AsyncElement {
+    private _loadPromise: Promise<void> | null = null;
 
-    /** @ignore */
-    constructor() {
-        super();
-        this.loadPromise = this.loadModule();
+    connectedCallback() {
+        this._getLoadPromise();
     }
 
-    private async loadModule(): Promise<void> {
-        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 };
+    private async _loadModule(): Promise<void> {
+        const name = this.getAttribute('name');
+        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') {
             basisInitialize(config);
@@ -41,17 +53,24 @@ class ModuleElement extends HTMLElement {
                 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(): Promise<void> {
-        return this.loadPromise;
+        if (!this._loadPromise) {
+            this._loadPromise = this._loadModule();
+        }
+        return this._loadPromise;
     }
 }