@playcanvas/web-components 0.10.1 → 0.11.1

package/src/app.ts

@@ -1,11 +1,10 @@
+import type { CameraComponent, GraphNode, GSplatComponent, Entity } from 'playcanvas';
 import {
     AppBase,
     AppOptions,
-    CameraComponent,
     createGraphicsDevice,
     ElementInput,
     FILLMODE_FILL_WINDOW,
-    GraphNode,
     Keyboard,
     Mouse,
     Picker,
@@ -62,17 +61,19 @@ 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 { LoadingBar } from './loading-bar';
-import { MaterialElement } from './material';
-import { ModuleElement } from './module';
-import { parseBool, parseEnum } from './parse';
+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
@@ -97,21 +98,49 @@ class AppElement extends AsyncElement {
 
     private _antialias = true;
 
-    private _depth = true;
+    private _depthBuffer = true;
 
-    private _stencil = true;
+    private _stencilBuffer = true;
 
-    private _highResolution = true;
+    private _maxPixelRatio = Infinity;
 
     private _loadingBar = true;
 
+    /**
+     * Set once the graphics options above have been handed to `createGraphicsDevice`, after which
+     * writing any of them changes nothing. Guards the warning in {@link _warnIfBooted}, and is
+     * cleared on disconnect so a re-connected element boots from its current attributes.
+     */
+    private _optionsLocked = false;
+
     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.
+     */
+    private _entityElements = new Map<GraphNode, EntityElement>();
 
     private _picker: Picker | null = null;
 
-    private _hasPointerListeners: { [key: string]: boolean } = {
+    private _hasPointerListeners: Record<string, boolean> = {
         pointerenter: false,
         pointerleave: false,
         pointerdown: false,
@@ -124,7 +153,7 @@ class AppElement extends AsyncElement {
     // 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
@@ -165,9 +194,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) {
@@ -178,29 +217,49 @@ 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']
         };
         const deviceTypes = backendToDeviceTypes[this._backend] || [];
 
+        this._optionsLocked = true;
+
         const device = await createGraphicsDevice(this._canvas, {
             // @ts-ignore - alpha needs to be documented
             alpha: this._alpha,
             antialias: this._antialias,
-            depth: this._depth,
+            depth: this._depthBuffer,
             deviceTypes: deviceTypes,
-            stencil: this._stencil
+            stencil: this._stencilBuffer
         });
-        device.maxPixelRatio = this._highResolution ? window.devicePixelRatio : 1;
+
+        // 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.
+        device.maxPixelRatio = this._maxPixelRatio;
 
         const createOptions = new AppOptions();
         createOptions.graphicsDevice = device;
@@ -278,31 +337,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
@@ -322,8 +397,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);
@@ -344,17 +432,30 @@ 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();
 
-        // Clean up the application
+        // Clean up the application. Destroying it destroys every entity, whose destroy hooks
+        // unregister them - clear() covers any entity the engine no longer reached.
         if (this._app) {
             this._app.destroy();
             this._app = null;
         }
+        this._entityElements.clear();
         this._loadProgress = 0;
         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);
 
@@ -365,13 +466,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);
 
@@ -388,22 +489,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<EntityElement>('pc-entity')).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) {
@@ -413,6 +512,7 @@ class AppElement extends AsyncElement {
         }
 
         this._picker = null;
+        this._hoveredEntity = null;
         this._pointerHandlers = {
             pointermove: null,
             pointerdown: null,
@@ -427,8 +527,81 @@ class AppElement extends AsyncElement {
         };
     }
 
+    /**
+     * Registers the element that created an entity. Called by EntityElement when it creates its
+     * entity.
+     *
+     * @param entity - The entity.
+     * @param element - The element that created it.
+     * @internal
+     */
+    _registerEntityElement(entity: Entity, element: EntityElement) {
+        this._entityElements.set(entity, element);
+    }
+
+    /**
+     * Removes the registration for a destroyed entity. Called by EntityElement.
+     *
+     * @param entity - The entity.
+     * @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.
+     *
+     * @param entity - The entity to look up.
+     * @returns The element backing the entity, or `null`.
+     */
+    elementFromEntity(entity: Entity): EntityElement | 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.
+     *
+     * @param node - The picked node, or `null`.
+     * @returns The owning element, or `null`.
+     */
+    private _elementFromNode(node: GraphNode | null): EntityElement | null {
+        while (node !== null) {
+            const element = this._entityElements.get(node);
+            if (element) {
+                return element;
+            }
+            node = node.parent;
+        }
+        return null;
+    }
+
+    /**
+     * Like {@link _elementFromNode}, but skips elements without a listener for `type`, so a hit
+     * on an unlistened child still reaches a listening ancestor.
+     *
+     * @param node - The picked node, or `null`.
+     * @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 {
+        while (node !== null) {
+            const element = this._entityElements.get(node);
+            if (element?._hasListeners(type)) {
+                return element;
+            }
+            node = node.parent;
+        }
+        return null;
+    }
+
     // 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.
@@ -465,7 +638,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
@@ -475,24 +648,16 @@ class AppElement extends AsyncElement {
         const node = await this._pickNode(event);
         if (token !== this._pickToken || !this._picker) return;
 
-        // Get the currently hovered entity by walking up the hierarchy
-        let newHoverEntity: EntityElement | null = null;
-        let currentNode = node;
-        while (currentNode !== null) {
-            const entityElement = this.querySelector(`pc-entity[name="${currentNode.name}"]`) as EntityElement;
-            if (entityElement) {
-                newHoverEntity = entityElement;
-                break;
-            }
-            currentNode = currentNode.parent;
-        }
+        // The hovered element is the nearest one up the node's parent chain, listening or not -
+        // dispatch is gated per event type below
+        const newHoverEntity = this._elementFromNode(node);
 
         // 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));
             }
         }
@@ -501,81 +666,103 @@ 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;
 
-        let currentNode = await this._pickNode(event);
+        const node = await this._pickNode(event);
         if (!this._picker) return; // the element disconnected while the pick was in flight
 
-        while (currentNode !== null) {
-            const entityElement = this.querySelector(`pc-entity[name="${currentNode.name}"]`) as EntityElement;
-            if (entityElement && entityElement.hasListeners('pointerdown')) {
-                entityElement.dispatchEvent(new PointerEvent('pointerdown', event));
-                break;
-            }
-            currentNode = currentNode.parent;
+        const entityElement = this._elementWithListener(node, 'pointerdown');
+        if (entityElement) {
+            entityElement.dispatchEvent(new PointerEvent('pointerdown', event));
         }
     }
 
-    async _onPointerUp(event: PointerEvent) {
+    private async _onPointerUp(event: PointerEvent) {
         if (!this._picker || !this.app) return;
 
         const node = await this._pickNode(event);
-        if (!node || !this._picker) return;
+        if (!this._picker) return; // the element disconnected while the pick was in flight
 
-        const entityElement = this.querySelector(`pc-entity[name="${node.name}"]`) as EntityElement;
-        if (entityElement && entityElement.hasListeners('pointerup')) {
+        const entityElement = this._elementWithListener(node, 'pointerup');
+        if (entityElement) {
             entityElement.dispatchEvent(new PointerEvent('pointerup', event));
         }
     }
 
-    _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<EntityElement>('pc-entity')).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
+                );
             }
         }
     }
 
     /**
-     * Sets the alpha flag.
+     * Warns that a graphics option was written too late to have any effect. These options are read
+     * once, when the element connects and creates its graphics device, so a later write updates
+     * only the element's own property - silently, without this.
+     *
+     * @param name - The name of the option, as its attribute.
+     */
+    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.`
+            );
+        }
+    }
+
+    /**
+     * Sets whether the frame buffer has an alpha channel, which is what lets the page show through
+     * wherever the scene has not drawn. Read only when the application boots.
      * @param value - The alpha flag.
      */
     set alpha(value: boolean) {
+        this._warnIfBooted('alpha');
         this._alpha = value;
     }
 
     /**
-     * Gets the alpha flag.
+     * Gets whether the frame buffer has an alpha channel.
      * @returns The alpha flag.
      */
     get alpha() {
@@ -583,15 +770,16 @@ class AppElement extends AsyncElement {
     }
 
     /**
-     * Sets the antialias flag.
+     * Sets whether the frame buffer is anti-aliased. Read only when the application boots.
      * @param value - The antialias flag.
      */
     set antialias(value: boolean) {
+        this._warnIfBooted('antialias');
         this._antialias = value;
     }
 
     /**
-     * Gets the antialias flag.
+     * Gets whether the frame buffer is anti-aliased.
      * @returns The antialias flag.
      */
     get antialias() {
@@ -600,10 +788,11 @@ class AppElement extends AsyncElement {
 
     /**
      * Sets the graphics backend. Defaults to 'webgpu', which falls back to 'webgl2' if WebGPU
-     * is not supported by the browser.
+     * is not supported by the browser. Read only when the application boots.
      * @param value - The graphics backend ('webgpu', 'webgl2', or 'null').
      */
     set backend(value: 'webgpu' | 'webgl2' | 'null') {
+        this._warnIfBooted('backend');
         this._backend = value;
     }
 
@@ -616,48 +805,21 @@ class AppElement extends AsyncElement {
     }
 
     /**
-     * Sets the depth flag.
-     * @param value - The depth flag.
+     * Sets whether the frame buffer has a depth buffer, which the renderer needs to resolve which
+     * surface is nearest the camera. Read only when the application boots.
+     * @param value - The depth buffer flag.
      */
-    set depth(value: boolean) {
-        this._depth = value;
+    set depthBuffer(value: boolean) {
+        this._warnIfBooted('depth-buffer');
+        this._depthBuffer = value;
     }
 
     /**
-     * Gets the depth flag.
-     * @returns The depth flag.
+     * Gets whether the frame buffer has a depth buffer.
+     * @returns The depth buffer flag.
      */
-    get depth() {
-        return this._depth;
-    }
-
-    /**
-     * Gets the hierarchy ready flag.
-     * @returns The hierarchy ready flag.
-     * @ignore
-     */
-    get hierarchyReady() {
-        return this._hierarchyReady;
-    }
-
-    /**
-     * Sets the high resolution flag. When true, the application will render at the device's
-     * physical resolution. When false, the application will render at CSS resolution.
-     * @param value - The high resolution flag.
-     */
-    set highResolution(value: boolean) {
-        this._highResolution = value;
-        if (this.app) {
-            this.app.graphicsDevice.maxPixelRatio = value ? window.devicePixelRatio : 1;
-        }
-    }
-
-    /**
-     * Gets the high resolution flag.
-     * @returns The high resolution flag.
-     */
-    get highResolution() {
-        return this._highResolution;
+    get depthBuffer() {
+        return this._depthBuffer;
     }
 
     /**
@@ -686,23 +848,49 @@ class AppElement extends AsyncElement {
     }
 
     /**
-     * Sets the stencil flag.
-     * @param value - The stencil flag.
+     * Sets the cap on the pixel ratio the application renders at. The canvas is sized by the
+     * smaller of this value and the display's own device pixel ratio, so the default of `Infinity`
+     * renders at full physical resolution, `1` renders at CSS resolution, and an intermediate
+     * value such as `2` keeps a dense display sharp without paying for every one of its pixels.
+     * Must be greater than 0. Unlike the other graphics options, this applies immediately.
+     * @param value - The maximum pixel ratio.
      */
-    set stencil(value: boolean) {
-        this._stencil = value;
+    set maxPixelRatio(value: number) {
+        this._maxPixelRatio = value;
+        if (this.app) {
+            this.app.graphicsDevice.maxPixelRatio = value;
+            this.app.resizeCanvas();
+        }
     }
 
     /**
-     * Gets the stencil flag.
-     * @returns The stencil flag.
+     * Gets the cap on the pixel ratio the application renders at.
+     * @returns The maximum pixel ratio.
      */
-    get stencil() {
-        return this._stencil;
+    get maxPixelRatio() {
+        return this._maxPixelRatio;
+    }
+
+    /**
+     * Sets whether the frame buffer has a stencil buffer, which stencil-based effects and UI
+     * masking need. Read only when the application boots.
+     * @param value - The stencil buffer flag.
+     */
+    set stencilBuffer(value: boolean) {
+        this._warnIfBooted('stencil-buffer');
+        this._stencilBuffer = value;
+    }
+
+    /**
+     * Gets whether the frame buffer has a stencil buffer.
+     * @returns The stencil buffer flag.
+     */
+    get stencilBuffer() {
+        return this._stencilBuffer;
     }
 
     static get observedAttributes() {
-        return ['alpha', 'antialias', 'backend', 'depth', 'stencil', 'high-resolution', 'loading-bar'];
+        return ['alpha', 'antialias', 'backend', 'depth-buffer', 'loading-bar', 'max-pixel-ratio', 'stencil-buffer'];
     }
 
     attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null) {
@@ -716,17 +904,17 @@ class AppElement extends AsyncElement {
             case 'backend':
                 this.backend = parseEnum(newValue, ['webgpu', 'webgl2', 'null'], 'webgpu', name);
                 break;
-            case 'depth':
-                this.depth = parseBool(newValue, true);
-                break;
-            case 'high-resolution':
-                this.highResolution = parseBool(newValue, true);
+            case 'depth-buffer':
+                this.depthBuffer = parseBool(newValue, true);
                 break;
             case 'loading-bar':
                 this.loadingBar = parseBool(newValue, true);
                 break;
-            case 'stencil':
-                this.stencil = parseBool(newValue, true);
+            case 'max-pixel-ratio':
+                this.maxPixelRatio = parseNumber(newValue, Infinity, name);
+                break;
+            case 'stencil-buffer':
+                this.stencilBuffer = parseBool(newValue, true);
                 break;
         }
     }
@@ -734,10 +922,4 @@ class AppElement extends AsyncElement {
 
 customElements.define('pc-app', AppElement);
 
-declare global {
-    interface HTMLElementTagNameMap {
-        'pc-app': AppElement;
-    }
-}
-
 export { AppElement };