@playcanvas/web-components 0.13.0 → 0.14.0

package/dist/vscode.html-custom-data.json

@@ -50,7 +50,7 @@
     },
     {
       "name": "pc-asset",
-      "description": "The AssetElement interface provides properties and methods for manipulating\n[`<pc-asset>`](https://developer.playcanvas.com/user-manual/web-components/tags/pc-asset/) elements.\nThe AssetElement interface also inherits the properties and methods of the\nHTMLElement interface.\n\nThe element becomes ready once the containing application has started and the asset is in the\nstate declared by the markup: loaded for preloaded assets (even if loading failed — check the\nasset's `resource`), or registered and awaiting a load for `lazy` assets. Elements inserted\nwhile the application is running are created and registered on insertion, and begin loading\nimmediately unless `lazy`. A `pc-asset` must be a direct child of `pc-app` — elements placed\nelsewhere, or with an unsupported asset type, never become ready.\n\nFor `texture` and `textureatlas` assets, the texture options (`address-u`, `address-v`,\n`min-filter`, `mag-filter`, `anisotropy`, `mipmaps`, `srgb`, `flip-y`) apply when the texture is\ncreated and — like `lazy` — are observed: changing one updates a texture that has already\nloaded, and removing one restores the engine default. Changing `srgb` or `mipmaps` on a loaded\ntexture recreates the underlying GPU resource, so prefer declaring those up front. Each option\noverrides the matching key in the `data` JSON; options left unset write nothing, leaving the\nengine's per-format defaults in force.\n\nApart from `lazy` and the texture options, these attributes are read once when the asset is\ncreated, so changing them later has no effect.\n\n---\n\n\n### **Events:**\n - **error** - Fired when the asset fails to load, with the engine's error in `message`. Does not bubble. The element still becomes ready — readiness means the load settled, not that it succeeded.\n- **load** - Fired each time the asset finishes loading, including a `lazy` asset loaded later and any subsequent reloads. Does not bubble — listen on this element, or use a capture-phase listener on an ancestor to observe every asset.\n- **ready** - Fired when the element is fully initialized — once per readiness cycle, so an element that is torn down and re-initialized (for example by removing and re-inserting it) fires it again. Bubbles and is composed.\n\n### **Methods:**\n - **get(id: _string_): __** - Returns the Asset created by the `<pc-asset>` element with the given `id`, or\n`undefined` if there is no such element or its asset has not been created yet.\n- **ready(): __** - Returns a promise that resolves with this element when it's ready. This is the low-level\nprimitive underlying whenReady, which is the recommended way to wait for elements.\n\nReadiness tracks the element's current lifecycle: once a ready element is torn down (for\nexample by removing it from the document), this returns a fresh promise that resolves when\nthe element is next ready. A promise obtained earlier stays resolved — call this again\nafter re-inserting an element rather than reusing a promise from before its removal.",
+      "description": "The AssetElement interface provides properties and methods for manipulating\n[`<pc-asset>`](https://developer.playcanvas.com/user-manual/web-components/tags/pc-asset/) elements.\nThe AssetElement interface also inherits the properties and methods of the\nHTMLElement interface.\n\nThe element becomes ready once the containing application has started and the asset is in the\nstate declared by the markup: loaded for preloaded assets (even if loading failed — check the\nasset's `resource`), or registered and awaiting a load for `lazy` assets. Elements inserted\nwhile the application is running are created and registered on insertion, and begin loading\nimmediately unless `lazy`. A `pc-asset` must be a direct child of `pc-app` — elements placed\nelsewhere, or with an unsupported asset type, never become ready.\n\nA `lazy` asset loads on first use: the first time any element resolves it by `id` — a model,\na material map, a sky, a script `asset:` reference — or when the `lazy` attribute is removed,\nwhichever comes first. Until then it stays registered and unloaded.\n\nFor `texture` and `textureatlas` assets, the texture options (`address-u`, `address-v`,\n`min-filter`, `mag-filter`, `anisotropy`, `mipmaps`, `srgb`, `flip-y`) apply when the texture is\ncreated and — like `lazy` — are observed: changing one updates a texture that has already\nloaded, and removing one restores the engine default. Changing `srgb` or `mipmaps` on a loaded\ntexture recreates the underlying GPU resource, so prefer declaring those up front. Each option\noverrides the matching key in the `data` JSON; options left unset write nothing, leaving the\nengine's per-format defaults in force.\n\nApart from `lazy` and the texture options, these attributes are read once when the asset is\ncreated, so changing them later has no effect.\n\n---\n\n\n### **Events:**\n - **error** - Fired when the asset fails to load, with the engine's error in `message`. Does not bubble. The element still becomes ready — readiness means the load settled, not that it succeeded.\n- **load** - Fired each time the asset finishes loading, including a `lazy` asset loaded later and any subsequent reloads. Does not bubble — listen on this element, or use a capture-phase listener on an ancestor to observe every asset.\n- **ready** - Fired when the element is fully initialized — once per readiness cycle, so an element that is torn down and re-initialized (for example by removing and re-inserting it) fires it again. Bubbles and is composed.\n\n### **Methods:**\n - **get(id: _string_): __** - Returns the Asset created by the `<pc-asset>` element with the given `id`, or\n`undefined` if there is no such element or its asset has not been created yet.\n- **ready(): __** - Returns a promise that resolves with this element when it's ready. This is the low-level\nprimitive underlying whenReady, which is the recommended way to wait for elements.\n\nReadiness tracks the element's current lifecycle: once a ready element is torn down (for\nexample by removing it from the document), this returns a fresh promise that resolves when\nthe element is next ready. A promise obtained earlier stays resolved — call this again\nafter re-inserting an element rather than reusing a promise from before its removal.",
       "attributes": [
         {
           "name": "address-u",
@@ -544,6 +544,11 @@
           "description": "The UV channel the metalness map samples.",
           "values": []
         },
+        {
+          "name": "name",
+          "description": "The name of the material - the label shown wherever materials surface by name, such as profilers, GPU captures and the assignments `pc-model.hierarchy()` reports.",
+          "values": []
+        },
         {
           "name": "normal-map",
           "description": "The id of the `pc-asset` used as the normal map.",
@@ -698,7 +703,7 @@
     },
     {
       "name": "pc-model",
-      "description": "The ModelElement interface provides properties and methods for manipulating\n[`<pc-model>`](https://developer.playcanvas.com/user-manual/web-components/tags/pc-model/) elements.\nThe ModelElement interface also inherits the properties and methods of the\nHTMLElement interface.\n\nThe element becomes ready once its container asset has loaded and the instantiated hierarchy has\nbeen added to the scene — `entity` is non-null by then. A failed load also settles readiness,\nwith `entity` remaining `null`: readiness means the load settled, not that it succeeded — listen\nfor `error`, or check `entity`, to tell the outcomes apart. Changing `asset` re-arms readiness\nand instantiates anew, so a `ready()` obtained after the change resolves against the new\nhierarchy. A `pc-model` outside a `pc-app`, or referencing an unknown asset id, warns and never\nbecomes ready.\n\n---\n\n\n### **Events:**\n - **error** - Fired when the container asset fails to load, with the engine's error in `message`. Does not bubble. The element still becomes ready — readiness means the load settled, not that it succeeded.\n- **load** - Fired each time a container asset finishes instantiating, including re-instantiation after `asset` changes. Does not bubble — listen on this element, or use a capture-phase listener on an ancestor.\n- **ready** - Fired when the element is fully initialized — once per readiness cycle, so an element that is torn down and re-initialized (for example by removing and re-inserting it) fires it again. Bubbles and is composed.\n\n### **Methods:**\n - **ready(): __** - Returns a promise that resolves with this element when it's ready. This is the low-level\nprimitive underlying whenReady, which is the recommended way to wait for elements.\n\nReadiness tracks the element's current lifecycle: once a ready element is torn down (for\nexample by removing it from the document), this returns a fresh promise that resolves when\nthe element is next ready. A promise obtained earlier stays resolved — call this again\nafter re-inserting an element rather than reusing a promise from before its removal.",
+      "description": "The ModelElement interface provides properties and methods for manipulating\n[`<pc-model>`](https://developer.playcanvas.com/user-manual/web-components/tags/pc-model/) elements.\nThe ModelElement interface also inherits the properties and methods of the\nHTMLElement interface.\n\nThe element becomes ready once its container asset has loaded and the instantiated hierarchy has\nbeen added to the scene — `entity` is non-null by then. A failed load also settles readiness,\nwith `entity` remaining `null`: readiness means the load settled, not that it succeeded — listen\nfor `error`, or check `entity`, to tell the outcomes apart. Changing `asset` re-arms readiness\nand instantiates anew, so a `ready()` obtained after the change resolves against the new\nhierarchy. A `pc-model` outside a `pc-app`, or referencing an unknown asset id, warns and never\nbecomes ready.\n\n---\n\n\n### **Events:**\n - **error** - Fired when the container asset fails to load, with the engine's error in `message`. Does not bubble. The element still becomes ready — readiness means the load settled, not that it succeeded.\n- **load** - Fired each time a container asset finishes instantiating, including re-instantiation after `asset` changes. Does not bubble — listen on this element, or use a capture-phase listener on an ancestor.\n- **ready** - Fired when the element is fully initialized — once per readiness cycle, so an element that is torn down and re-initialized (for example by removing and re-inserting it) fires it again. Bubbles and is composed.\n\n### **Methods:**\n - **hierarchy(): __** - Returns a snapshot of the instantiated node tree, or `null` while there is none (the\ncontainer asset has not loaded, or the element has left the document). One call grounds a\nsession — a browser console, a test, an agent — in the vocabulary `pc-node` binding\nresolves against: the instantiated names (HierarchyNode.name), paths, match\nindices, attached component types and the material assignments of render components\n(HierarchyNode.materials). `String(...)` of the result, or of any node in it,\nis the printable form.\n\nThe snapshot is plain data, computed afresh each call: it does not follow later changes\nto the hierarchy, and mutating it changes nothing.\n- **ready(): __** - Returns a promise that resolves with this element when it's ready. This is the low-level\nprimitive underlying whenReady, which is the recommended way to wait for elements.\n\nReadiness tracks the element's current lifecycle: once a ready element is torn down (for\nexample by removing it from the document), this returns a fresh promise that resolves when\nthe element is next ready. A promise obtained earlier stays resolved — call this again\nafter re-inserting an element rather than reusing a promise from before its removal.",
       "attributes": [
         {
           "name": "asset",
@@ -749,6 +754,11 @@
           "description": "Which match to bind when `name` matches more than one node, 0-based in depth-first order. Optional for a unique match; required for an ambiguous one.",
           "values": []
         },
+        {
+          "name": "material-overrides",
+          "description": "Overrides material assignments on the bound node's render component, as a JSON object from selector to `pc-material` id — for example `{\"name:CarPaint\": \"candy-red\", \"index:7\": \"smoked-glass\"}`. A `name:X` key selects every mesh instance whose baseline material is named `X`; an `index:N` key selects mesh instance `N` and wins over a name rule for the same instance. Assignments no rule matches keep their baseline materials, and removing the attribute restores all of them. Use `pc-model.hierarchy()` to discover the names and indices a node offers.",
+          "values": []
+        },
         {
           "name": "name",
           "description": "The name of the node to bind, resolved within the nearest ancestor `pc-model` (or `pc-node`) once it has instantiated.",

package/dist/web-types.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://raw.githubusercontent.com/JetBrains/web-types/master/schema/web-types.json",
   "name": "@playcanvas/web-components",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description-markup": "markdown",
   "contributions": {
     "html": {
@@ -139,7 +139,7 @@
         },
         {
           "name": "pc-asset",
-          "description": "The AssetElement interface provides properties and methods for manipulating\n[`<pc-asset>`](https://developer.playcanvas.com/user-manual/web-components/tags/pc-asset/) elements.\nThe AssetElement interface also inherits the properties and methods of the\nHTMLElement interface.\n\nThe element becomes ready once the containing application has started and the asset is in the\nstate declared by the markup: loaded for preloaded assets (even if loading failed — check the\nasset's `resource`), or registered and awaiting a load for `lazy` assets. Elements inserted\nwhile the application is running are created and registered on insertion, and begin loading\nimmediately unless `lazy`. A `pc-asset` must be a direct child of `pc-app` — elements placed\nelsewhere, or with an unsupported asset type, never become ready.\n\nFor `texture` and `textureatlas` assets, the texture options (`address-u`, `address-v`,\n`min-filter`, `mag-filter`, `anisotropy`, `mipmaps`, `srgb`, `flip-y`) apply when the texture is\ncreated and — like `lazy` — are observed: changing one updates a texture that has already\nloaded, and removing one restores the engine default. Changing `srgb` or `mipmaps` on a loaded\ntexture recreates the underlying GPU resource, so prefer declaring those up front. Each option\noverrides the matching key in the `data` JSON; options left unset write nothing, leaving the\nengine's per-format defaults in force.\n\nApart from `lazy` and the texture options, these attributes are read once when the asset is\ncreated, so changing them later has no effect.\n\n---\n\n\n### **Events:**\n - **error** - Fired when the asset fails to load, with the engine's error in `message`. Does not bubble. The element still becomes ready — readiness means the load settled, not that it succeeded.\n- **load** - Fired each time the asset finishes loading, including a `lazy` asset loaded later and any subsequent reloads. Does not bubble — listen on this element, or use a capture-phase listener on an ancestor to observe every asset.\n- **ready** - Fired when the element is fully initialized — once per readiness cycle, so an element that is torn down and re-initialized (for example by removing and re-inserting it) fires it again. Bubbles and is composed.\n\n### **Methods:**\n - **get(id: _string_): __** - Returns the Asset created by the `<pc-asset>` element with the given `id`, or\n`undefined` if there is no such element or its asset has not been created yet.\n- **ready(): __** - Returns a promise that resolves with this element when it's ready. This is the low-level\nprimitive underlying whenReady, which is the recommended way to wait for elements.\n\nReadiness tracks the element's current lifecycle: once a ready element is torn down (for\nexample by removing it from the document), this returns a fresh promise that resolves when\nthe element is next ready. A promise obtained earlier stays resolved — call this again\nafter re-inserting an element rather than reusing a promise from before its removal.",
+          "description": "The AssetElement interface provides properties and methods for manipulating\n[`<pc-asset>`](https://developer.playcanvas.com/user-manual/web-components/tags/pc-asset/) elements.\nThe AssetElement interface also inherits the properties and methods of the\nHTMLElement interface.\n\nThe element becomes ready once the containing application has started and the asset is in the\nstate declared by the markup: loaded for preloaded assets (even if loading failed — check the\nasset's `resource`), or registered and awaiting a load for `lazy` assets. Elements inserted\nwhile the application is running are created and registered on insertion, and begin loading\nimmediately unless `lazy`. A `pc-asset` must be a direct child of `pc-app` — elements placed\nelsewhere, or with an unsupported asset type, never become ready.\n\nA `lazy` asset loads on first use: the first time any element resolves it by `id` — a model,\na material map, a sky, a script `asset:` reference — or when the `lazy` attribute is removed,\nwhichever comes first. Until then it stays registered and unloaded.\n\nFor `texture` and `textureatlas` assets, the texture options (`address-u`, `address-v`,\n`min-filter`, `mag-filter`, `anisotropy`, `mipmaps`, `srgb`, `flip-y`) apply when the texture is\ncreated and — like `lazy` — are observed: changing one updates a texture that has already\nloaded, and removing one restores the engine default. Changing `srgb` or `mipmaps` on a loaded\ntexture recreates the underlying GPU resource, so prefer declaring those up front. Each option\noverrides the matching key in the `data` JSON; options left unset write nothing, leaving the\nengine's per-format defaults in force.\n\nApart from `lazy` and the texture options, these attributes are read once when the asset is\ncreated, so changing them later has no effect.\n\n---\n\n\n### **Events:**\n - **error** - Fired when the asset fails to load, with the engine's error in `message`. Does not bubble. The element still becomes ready — readiness means the load settled, not that it succeeded.\n- **load** - Fired each time the asset finishes loading, including a `lazy` asset loaded later and any subsequent reloads. Does not bubble — listen on this element, or use a capture-phase listener on an ancestor to observe every asset.\n- **ready** - Fired when the element is fully initialized — once per readiness cycle, so an element that is torn down and re-initialized (for example by removing and re-inserting it) fires it again. Bubbles and is composed.\n\n### **Methods:**\n - **get(id: _string_): __** - Returns the Asset created by the `<pc-asset>` element with the given `id`, or\n`undefined` if there is no such element or its asset has not been created yet.\n- **ready(): __** - Returns a promise that resolves with this element when it's ready. This is the low-level\nprimitive underlying whenReady, which is the recommended way to wait for elements.\n\nReadiness tracks the element's current lifecycle: once a ready element is torn down (for\nexample by removing it from the document), this returns a fresh promise that resolves when\nthe element is next ready. A promise obtained earlier stays resolved — call this again\nafter re-inserting an element rather than reusing a promise from before its removal.",
           "doc-url": "",
           "attributes": [
             {
@@ -785,6 +785,11 @@
               "description": "The UV channel the metalness map samples.",
               "value": { "type": "number", "default": "0" }
             },
+            {
+              "name": "name",
+              "description": "The name of the material - the label shown wherever materials surface by name, such as profilers, GPU captures and the assignments `pc-model.hierarchy()` reports.",
+              "value": { "type": "string" }
+            },
             {
               "name": "normal-map",
               "description": "The id of the `pc-asset` used as the normal map.",
@@ -1162,6 +1167,10 @@
                 "name": "metalnessMapUv",
                 "description": "Gets the UV channel the metalness map samples."
               },
+              {
+                "name": "name",
+                "description": "Gets the name of the material - the label shown wherever materials surface by name, such\nas profilers, GPU captures and the assignments `pc-model.hierarchy()` reports. Purely a\nlabel: element references resolve through `id`."
+              },
               {
                 "name": "normalMap",
                 "description": "Gets the id of the `pc-asset` used as the normal map."
@@ -1284,7 +1293,7 @@
         },
         {
           "name": "pc-model",
-          "description": "The ModelElement interface provides properties and methods for manipulating\n[`<pc-model>`](https://developer.playcanvas.com/user-manual/web-components/tags/pc-model/) elements.\nThe ModelElement interface also inherits the properties and methods of the\nHTMLElement interface.\n\nThe element becomes ready once its container asset has loaded and the instantiated hierarchy has\nbeen added to the scene — `entity` is non-null by then. A failed load also settles readiness,\nwith `entity` remaining `null`: readiness means the load settled, not that it succeeded — listen\nfor `error`, or check `entity`, to tell the outcomes apart. Changing `asset` re-arms readiness\nand instantiates anew, so a `ready()` obtained after the change resolves against the new\nhierarchy. A `pc-model` outside a `pc-app`, or referencing an unknown asset id, warns and never\nbecomes ready.\n\n---\n\n\n### **Events:**\n - **error** - Fired when the container asset fails to load, with the engine's error in `message`. Does not bubble. The element still becomes ready — readiness means the load settled, not that it succeeded.\n- **load** - Fired each time a container asset finishes instantiating, including re-instantiation after `asset` changes. Does not bubble — listen on this element, or use a capture-phase listener on an ancestor.\n- **ready** - Fired when the element is fully initialized — once per readiness cycle, so an element that is torn down and re-initialized (for example by removing and re-inserting it) fires it again. Bubbles and is composed.\n\n### **Methods:**\n - **ready(): __** - Returns a promise that resolves with this element when it's ready. This is the low-level\nprimitive underlying whenReady, which is the recommended way to wait for elements.\n\nReadiness tracks the element's current lifecycle: once a ready element is torn down (for\nexample by removing it from the document), this returns a fresh promise that resolves when\nthe element is next ready. A promise obtained earlier stays resolved — call this again\nafter re-inserting an element rather than reusing a promise from before its removal.",
+          "description": "The ModelElement interface provides properties and methods for manipulating\n[`<pc-model>`](https://developer.playcanvas.com/user-manual/web-components/tags/pc-model/) elements.\nThe ModelElement interface also inherits the properties and methods of the\nHTMLElement interface.\n\nThe element becomes ready once its container asset has loaded and the instantiated hierarchy has\nbeen added to the scene — `entity` is non-null by then. A failed load also settles readiness,\nwith `entity` remaining `null`: readiness means the load settled, not that it succeeded — listen\nfor `error`, or check `entity`, to tell the outcomes apart. Changing `asset` re-arms readiness\nand instantiates anew, so a `ready()` obtained after the change resolves against the new\nhierarchy. A `pc-model` outside a `pc-app`, or referencing an unknown asset id, warns and never\nbecomes ready.\n\n---\n\n\n### **Events:**\n - **error** - Fired when the container asset fails to load, with the engine's error in `message`. Does not bubble. The element still becomes ready — readiness means the load settled, not that it succeeded.\n- **load** - Fired each time a container asset finishes instantiating, including re-instantiation after `asset` changes. Does not bubble — listen on this element, or use a capture-phase listener on an ancestor.\n- **ready** - Fired when the element is fully initialized — once per readiness cycle, so an element that is torn down and re-initialized (for example by removing and re-inserting it) fires it again. Bubbles and is composed.\n\n### **Methods:**\n - **hierarchy(): __** - Returns a snapshot of the instantiated node tree, or `null` while there is none (the\ncontainer asset has not loaded, or the element has left the document). One call grounds a\nsession — a browser console, a test, an agent — in the vocabulary `pc-node` binding\nresolves against: the instantiated names (HierarchyNode.name), paths, match\nindices, attached component types and the material assignments of render components\n(HierarchyNode.materials). `String(...)` of the result, or of any node in it,\nis the printable form.\n\nThe snapshot is plain data, computed afresh each call: it does not follow later changes\nto the hierarchy, and mutating it changes nothing.\n- **ready(): __** - Returns a promise that resolves with this element when it's ready. This is the low-level\nprimitive underlying whenReady, which is the recommended way to wait for elements.\n\nReadiness tracks the element's current lifecycle: once a ready element is torn down (for\nexample by removing it from the document), this returns a fresh promise that resolves when\nthe element is next ready. A promise obtained earlier stays resolved — call this again\nafter re-inserting an element rather than reusing a promise from before its removal.",
           "doc-url": "",
           "attributes": [
             {
@@ -1422,6 +1431,11 @@
               "description": "Which match to bind when `name` matches more than one node, 0-based in depth-first order. Optional for a unique match; required for an ambiguous one.",
               "value": { "type": "string" }
             },
+            {
+              "name": "material-overrides",
+              "description": "Overrides material assignments on the bound node's render component, as a JSON object from selector to `pc-material` id — for example `{\"name:CarPaint\": \"candy-red\", \"index:7\": \"smoked-glass\"}`. A `name:X` key selects every mesh instance whose baseline material is named `X`; an `index:N` key selects mesh instance `N` and wins over a name rule for the same instance. Assignments no rule matches keep their baseline materials, and removing the attribute restores all of them. Use `pc-model.hierarchy()` to discover the names and indices a node offers.",
+              "value": { "type": "string" }
+            },
             {
               "name": "name",
               "description": "The name of the node to bind, resolved within the nearest ancestor `pc-model` (or `pc-node`) once it has instantiated.",
@@ -1532,6 +1546,11 @@
                 "description": "Gets which match to bind.",
                 "type": "number | null"
               },
+              {
+                "name": "materialOverrides",
+                "description": "Gets the material overrides.",
+                "type": "MaterialOverrides | null"
+              },
               {
                 "name": "name",
                 "description": "Gets the name of the node to bind.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcanvas/web-components",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "author": "PlayCanvas <support@playcanvas.com>",
   "homepage": "https://playcanvas.com",
   "description": "Web Components for the PlayCanvas Engine",
@@ -96,9 +96,9 @@
     "custom-element-vs-code-integration": "1.5.0",
     "earcut": "3.2.3",
     "eslint": "9.39.5",
-    "globals": "17.9.0",
+    "globals": "17.11.0",
     "jsdom": "30.0.1",
-    "mediabunny": "1.53.0",
+    "mediabunny": "1.53.1",
     "opentype.js": "2.0.0",
     "playcanvas": "2.22.0-beta.12",
     "prettier": "3.9.6",

package/src/app.ts

@@ -692,22 +692,68 @@ class AppElement extends AsyncElement {
         return null;
     }
 
-    // New helper to convert CSS coordinates to canvas (picker) coordinates
-    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.
-        const scaleX = this._canvas!.width / canvasRect.width;
-        const scaleY = this._canvas!.height / canvasRect.height;
-        // Convert the client coordinates accordingly.
-        const x = (event.clientX - canvasRect.left) * scaleX;
-        const y = (event.clientY - canvasRect.top) * scaleY;
-        return { x, y };
+    /**
+     * Converts a pointer event's client coordinates into drawing-buffer coordinates - the space
+     * the pick buffer and the camera viewports are laid out in. When the canvas has no CSS box
+     * to map through (jsdom; a hidden canvas receives no pointer events in a browser), the
+     * client coordinates are passed through unmapped and `mapped` is false, so callers know the
+     * coordinates correspond to no real geometry.
+     *
+     * @param event - The pointer event to convert.
+     * @param canvas - The canvas the event was dispatched on.
+     * @returns The buffer-space coordinates, and whether they were actually mapped.
+     */
+    private _getPickerCoordinates(
+        event: PointerEvent,
+        canvas: HTMLCanvasElement
+    ): { x: number; y: number; mapped: boolean } {
+        const canvasRect = canvas.getBoundingClientRect();
+        if (canvasRect.width === 0 || canvasRect.height === 0) {
+            return { x: event.clientX, y: event.clientY, mapped: false };
+        }
+        const scaleX = canvas.width / canvasRect.width;
+        const scaleY = canvas.height / canvasRect.height;
+        return {
+            x: (event.clientX - canvasRect.left) * scaleX,
+            y: (event.clientY - canvasRect.top) * scaleY,
+            mapped: true
+        };
+    }
+
+    /**
+     * Whether a camera's viewport contains the point. A camera renders into its normalized
+     * `rect`, whose origin is the bottom-left of the canvas while buffer coordinates run from
+     * the top-left - so the vertical test flips, as the engine's ElementInput flips it for UI
+     * input. The right and bottom edges are exclusive: a viewport rasterizes the half-open
+     * pixel range [left, right) x [top, bottom), so a coordinate on a shared edge belongs to
+     * the viewport whose first pixel it is - never to the one it just left, whose pick buffer
+     * holds nothing there.
+     *
+     * @param camera - The camera to test.
+     * @param x - The x coordinate, in buffer space.
+     * @param y - The y coordinate, in buffer space.
+     * @param canvas - The canvas the coordinates are relative to.
+     * @returns Whether the camera's viewport contains the point.
+     */
+    private _cameraContains(camera: CameraComponent, x: number, y: number, canvas: HTMLCanvasElement): boolean {
+        const rect = camera.rect;
+        const left = rect.x * canvas.width;
+        const bottom = (1 - rect.y) * canvas.height;
+        const top = bottom - rect.w * canvas.height;
+        return x >= left && x < left + rect.z * canvas.width && y >= top && y < bottom;
     }
 
     /**
      * Picks the scene under the pointer and returns the graph node that was hit, or `null`.
      *
+     * The camera is resolved the way the engine's ElementInput resolves it for UI input:
+     * enabled cameras are tried topmost-first (they render in ascending `priority` order),
+     * skipping cameras that render to a texture and cameras whose viewport `rect` does not
+     * contain the pointer. A camera that picks nothing ends the search if it clears the color
+     * buffer - its background visually owns the pixel - and otherwise cedes to the cameras
+     * beneath it, so an overlay camera only intercepts picks where it actually drew something.
+     * The pick buffer is prepared per camera, so each camera picks from its own layers.
+     *
      * The read back is asynchronous because the synchronous {@link Picker.getSelection} is not
      * supported on WebGPU, where it returns an empty selection rather than failing - which
      * silently disabled every `onpointer*` handler once WebGPU became the resolved backend. The
@@ -717,17 +763,44 @@ class AppElement extends AsyncElement {
      * @returns The graph node under the pointer, or `null` if nothing was hit.
      */
     private async _pickNode(event: PointerEvent): Promise<GraphNode | null> {
-        const camera = this.app!.root.findComponent('camera') as CameraComponent;
-        if (!camera) return null;
+        const app = this.app;
+        const picker = this._picker;
+        const canvas = this._canvas;
+        if (!app || !picker || !canvas) return null;
+
+        const { x, y, mapped } = this._getPickerCoordinates(event, canvas);
+
+        // Walked from the end: the array is sorted by ascending priority, so the last camera
+        // renders last and sits on top. Read through .at() because a pick handler may remove
+        // cameras while an earlier iteration's read back is in flight.
+        const cameras = app.systems.camera?.cameras ?? [];
+        for (let i = cameras.length - 1; i >= 0; i--) {
+            const camera = cameras.at(i);
+
+            // A camera rendering to a texture is not on the canvas.
+            if (!camera || camera.renderTarget) continue;
+
+            // Coordinates that could not be mapped cannot be tested for containment.
+            if (mapped && !this._cameraContains(camera, x, y, canvas)) continue;
 
-        const { x, y } = this._getPickerCoordinates(event);
+            picker.prepare(camera, app.scene);
+            const selection = await picker.getSelectionAsync(x, y);
 
-        this._picker!.prepare(camera, this.app!.scene);
-        const selection = await this._picker!.getSelectionAsync(x, y);
-        if (selection.length === 0) return null;
+            // The element may have disconnected while the read back was in flight.
+            if (!this._picker || !this.app) return null;
 
-        const item = selection[0];
-        return item instanceof MeshInstance ? item.node : (item as GSplatComponent).entity;
+            if (selection.length > 0) {
+                const item = selection[0];
+                return item instanceof MeshInstance ? item.node : (item as GSplatComponent).entity;
+            }
+
+            // Nothing hit. A camera that clears the color buffer paints its background over
+            // everything beneath it, so the miss is final; one that does not is an overlay
+            // that the cameras beneath show through, so they get their turn.
+            if (camera.clearColorBuffer) return null;
+        }
+
+        return null;
     }
 
     private async _onPointerMove(event: PointerEvent) {

package/src/asset.ts

@@ -153,6 +153,10 @@ const processBufferView = (
  * immediately unless `lazy`. A `pc-asset` must be a direct child of `pc-app` — elements placed
  * elsewhere, or with an unsupported asset type, never become ready.
  *
+ * A `lazy` asset loads on first use: the first time any element resolves it by `id` — a model,
+ * a material map, a sky, a script `asset:` reference — or when the `lazy` attribute is removed,
+ * whichever comes first. Until then it stays registered and unloaded.
+ *
  * For `texture` and `textureatlas` assets, the texture options (`address-u`, `address-v`,
  * `min-filter`, `mag-filter`, `anisotropy`, `mipmaps`, `srgb`, `flip-y`) apply when the texture is
  * created and — like `lazy` — are observed: changing one updates a texture that has already
@@ -385,7 +389,9 @@ class AssetElement extends AsyncElement {
             data = data ?? {};
 
             // Resolve the referenced texture atlas to its (numeric) asset id. The atlas must be
-            // declared before the sprite so its asset already exists in the registry.
+            // declared before the sprite so its asset already exists in the registry. Resolved
+            // with get, not useAsset: creation-time wiring is not a use, and the engine's
+            // sprite handler loads the atlas when the sprite itself loads.
             const atlas = this.getAttribute('atlas') ?? data.textureAtlasAsset;
             if (typeof atlas === 'string') {
                 const atlasAsset = AssetElement.get(atlas);
@@ -564,13 +570,18 @@ class AssetElement extends AsyncElement {
     }
 
     /**
-     * Sets whether the asset should be loaded lazily.
+     * Sets whether the asset should be loaded lazily. A lazy asset is registered without being
+     * loaded; it loads on first use - the first time any element resolves it by `id` - or when
+     * this flag is cleared on a registered asset, whichever comes first.
      * @param value - The lazy loading flag.
      */
     set lazy(value: boolean) {
         this._lazy = value;
         if (this.asset) {
             this.asset.preload = !value;
+            if (!value) {
+                this.asset.registry?.load(this.asset);
+            }
         }
     }
 
@@ -760,4 +771,25 @@ class AssetElement extends AsyncElement {
 
 customElements.define('pc-asset', AssetElement);
 
+/**
+ * Resolves an asset reference for use: {@link AssetElement.get}, plus starting the load of a
+ * registered asset that has not begun one - a `lazy` asset. Every element that consumes assets
+ * resolves its references here, which is what makes `lazy` mean load on first use without any
+ * consumer having to remember the load. The load is asynchronous - callers observe the asset's
+ * `load` event for the resource.
+ *
+ * @param id - The `id` of the `<pc-asset>` element.
+ * @returns The asset, or `undefined`.
+ * @internal
+ */
+export const useAsset = (id: string) => {
+    const asset = AssetElement.get(id);
+    // load() ignores an asset that is already loaded or loading, so repeated resolution
+    // costs nothing.
+    if (asset) {
+        asset.registry?.load(asset);
+    }
+    return asset;
+};
+
 export { AssetElement };

package/src/colors.ts

@@ -1,3 +1,8 @@
+/**
+ * The CSS color keywords, lowercase name to hex value. Read by `parseColor` to accept color
+ * names as attribute values.
+ * @internal
+ */
 export const CSS_COLORS: Record<string, string> = {
     aliceblue: '#f0f8ff',
     antiquewhite: '#faebd7',

package/src/components/button-component.ts

@@ -1,7 +1,7 @@
 import type { ButtonComponent } from 'playcanvas';
 import { BUTTON_TRANSITION_MODE_SPRITE_CHANGE, BUTTON_TRANSITION_MODE_TINT, Color, Vec4 } from 'playcanvas';
 
-import { AssetElement } from '../asset';
+import { useAsset } from '../asset';
 import { getEntity, parseBool, parseColor, parseEnum, parseNumber, parseVec4 } from '../parse';
 
 import { ComponentElement } from './component';
@@ -74,17 +74,17 @@ class ButtonComponentElement extends ComponentElement {
             data.imageEntity = imageEntity;
         }
 
-        const hoverSpriteAsset = AssetElement.get(this._hoverSpriteAsset);
+        const hoverSpriteAsset = useAsset(this._hoverSpriteAsset);
         if (hoverSpriteAsset) {
             data.hoverSpriteAsset = hoverSpriteAsset.id;
         }
 
-        const pressedSpriteAsset = AssetElement.get(this._pressedSpriteAsset);
+        const pressedSpriteAsset = useAsset(this._pressedSpriteAsset);
         if (pressedSpriteAsset) {
             data.pressedSpriteAsset = pressedSpriteAsset.id;
         }
 
-        const inactiveSpriteAsset = AssetElement.get(this._inactiveSpriteAsset);
+        const inactiveSpriteAsset = useAsset(this._inactiveSpriteAsset);
         if (inactiveSpriteAsset) {
             data.inactiveSpriteAsset = inactiveSpriteAsset.id;
         }
@@ -265,7 +265,7 @@ class ButtonComponentElement extends ComponentElement {
      */
     set hoverSpriteAsset(value: string) {
         this._hoverSpriteAsset = value;
-        const asset = AssetElement.get(value);
+        const asset = useAsset(value);
         if (this.component && asset) {
             this.component.hoverSpriteAsset = asset.id as any;
         }
@@ -305,7 +305,7 @@ class ButtonComponentElement extends ComponentElement {
      */
     set pressedSpriteAsset(value: string) {
         this._pressedSpriteAsset = value;
-        const asset = AssetElement.get(value);
+        const asset = useAsset(value);
         if (this.component && asset) {
             this.component.pressedSpriteAsset = asset.id as any;
         }
@@ -345,7 +345,7 @@ class ButtonComponentElement extends ComponentElement {
      */
     set inactiveSpriteAsset(value: string) {
         this._inactiveSpriteAsset = value;
-        const asset = AssetElement.get(value);
+        const asset = useAsset(value);
         if (this.component && asset) {
             this.component.inactiveSpriteAsset = asset.id as any;
         }

package/src/components/element-component.ts

@@ -1,7 +1,7 @@
 import type { ElementComponent } from 'playcanvas';
 import { Color, Vec2, Vec4 } from 'playcanvas';
 
-import { AssetElement } from '../asset';
+import { useAsset } from '../asset';
 import { parseBool, parseColor, parseEnum, parseNumber, parseVec2, parseVec4 } from '../parse';
 
 import { ComponentElement } from './component';
@@ -118,17 +118,17 @@ class ElementComponentElement extends ComponentElement {
 
         // Asset references are resolved from `<pc-asset>` element ids to engine asset ids. They are
         // only included when they resolve, so image/group elements (with no font) don't error.
-        const fontAsset = AssetElement.get(this._fontAsset);
+        const fontAsset = useAsset(this._fontAsset);
         if (fontAsset) {
             data.fontAsset = fontAsset.id;
         }
 
-        const spriteAsset = AssetElement.get(this._spriteAsset);
+        const spriteAsset = useAsset(this._spriteAsset);
         if (spriteAsset) {
             data.spriteAsset = spriteAsset.id;
         }
 
-        const textureAsset = AssetElement.get(this._textureAsset);
+        const textureAsset = useAsset(this._textureAsset);
         if (textureAsset) {
             data.textureAsset = textureAsset.id;
         }
@@ -257,7 +257,7 @@ class ElementComponentElement extends ComponentElement {
      */
     set fontAsset(value: string) {
         this._fontAsset = value;
-        const asset = AssetElement.get(value);
+        const asset = useAsset(value);
         if (this.component && asset) {
             this.component.fontAsset = asset.id;
         }
@@ -430,7 +430,7 @@ class ElementComponentElement extends ComponentElement {
      */
     set spriteAsset(value: string) {
         this._spriteAsset = value;
-        const asset = AssetElement.get(value);
+        const asset = useAsset(value);
         if (this.component && asset) {
             this.component.spriteAsset = asset.id;
         }
@@ -488,7 +488,7 @@ class ElementComponentElement extends ComponentElement {
      */
     set textureAsset(value: string) {
         this._textureAsset = value;
-        const asset = AssetElement.get(value);
+        const asset = useAsset(value);
         if (this.component && asset) {
             this.component.textureAsset = asset.id;
         }

package/src/components/gsplat-component.ts

@@ -1,6 +1,6 @@
 import type { GSplatComponent } from 'playcanvas';
 
-import { AssetElement } from '../asset';
+import { useAsset } from '../asset';
 import { parseBool, parseNumber } from '../parse';
 
 import { ComponentElement } from './component';
@@ -33,7 +33,7 @@ class GSplatComponentElement extends ComponentElement {
 
     protected getInitialComponentData() {
         return {
-            asset: AssetElement.get(this._asset),
+            asset: useAsset(this._asset),
             castShadows: this._castShadows,
             lodBaseDistance: this._lodBaseDistance,
             lodMultiplier: this._lodMultiplier,
@@ -56,7 +56,7 @@ class GSplatComponentElement extends ComponentElement {
      */
     set asset(value: string) {
         this._asset = value;
-        const asset = AssetElement.get(value);
+        const asset = useAsset(value);
         if (this.component && asset) {
             this.component.asset = asset;
         }

package/src/components/particlesystem-component.ts

@@ -1,6 +1,6 @@
 import type { ParticleSystemComponent } from 'playcanvas';
 
-import { AssetElement } from '../asset';
+import { useAsset } from '../asset';
 
 import { ComponentElement } from './component';
 
@@ -21,14 +21,15 @@ class ParticleSystemComponentElement extends ComponentElement {
     }
 
     protected getInitialComponentData() {
-        const asset = AssetElement.get(this._asset);
-        if (!asset) {
+        const asset = useAsset(this._asset);
+        // A lazy config has no resource yet - _loadAsset applies it once the load completes
+        if (!asset || !asset.resource) {
             return {};
         }
 
         if ((asset.resource as any).colorMapAsset) {
             const id = (asset.resource as any).colorMapAsset;
-            const colorMapAsset = AssetElement.get(id)?.id;
+            const colorMapAsset = useAsset(id)?.id;
             if (colorMapAsset) {
                 (asset.resource as any).colorMapAsset = colorMapAsset;
             }
@@ -59,10 +60,9 @@ class ParticleSystemComponentElement extends ComponentElement {
     }
 
     private async _loadAsset() {
-        const appElement = await this.closestApp?.ready();
-        const app = appElement?.app;
+        await this.closestApp?.ready();
 
-        const asset = AssetElement.get(this._asset);
+        const asset = useAsset(this._asset);
         if (!asset) {
             return;
         }
@@ -73,7 +73,6 @@ class ParticleSystemComponentElement extends ComponentElement {
             asset.once('load', () => {
                 this.applyConfig(asset.resource);
             });
-            app!.assets.load(asset);
         }
     }
 

package/src/components/script-component.ts

@@ -1,7 +1,7 @@
 import type { ScriptComponent, Script } from 'playcanvas';
 import { Color, Quat, Vec2, Vec3, Vec4 } from 'playcanvas';
 
-import { AssetElement } from '../asset';
+import { useAsset } from '../asset';
 import {
     getEntity,
     parseBool,
@@ -119,7 +119,7 @@ type Conversion = (rest: string, raw: string) => any;
  * @returns The asset, or `raw`.
  */
 const assetConversion: Conversion = (rest, raw) => {
-    const asset = AssetElement.get(rest);
+    const asset = useAsset(rest);
     if (asset) {
         return asset;
     }

package/src/components/sound-slot.ts

@@ -1,6 +1,6 @@
 import type { SoundSlot } from 'playcanvas';
 
-import { AssetElement } from '../asset';
+import { useAsset } from '../asset';
 import { AsyncElement } from '../async-element';
 import { parseBool, parseNumber } from '../parse';
 
@@ -120,7 +120,7 @@ class SoundSlotElement extends AsyncElement {
     set asset(value: string) {
         this._asset = value;
         if (this.soundSlot) {
-            const id = AssetElement.get(value)?.id;
+            const id = useAsset(value)?.id;
             if (id) {
                 this.soundSlot.asset = id;
             }

package/src/entity-base.ts

@@ -6,9 +6,9 @@ import { AsyncElement } from './async-element';
 /**
  * The attribute names of the inline `onpointer*` event handlers, shared by every element that
  * fronts an engine entity. Spread into `observedAttributes` by subclasses.
- * @ignore
+ * @internal
  */
-const POINTER_ATTRIBUTES = [
+export const POINTER_ATTRIBUTES = [
     'onpointerenter',
     'onpointerleave',
     'onpointerdown',
@@ -133,4 +133,4 @@ class EntityBaseElement extends AsyncElement {
     }
 }
 
-export { EntityBaseElement, POINTER_ATTRIBUTES };
+export { EntityBaseElement };

package/src/index.ts

@@ -123,3 +123,5 @@ export {
 };
 
 export type { AsyncElementTagName } from './async-element';
+export type { HierarchyMaterial, HierarchyNode } from './model';
+export type { MaterialOverrides } from './node';