@playcanvas/web-components 0.13.0 → 0.14.0

package/dist/pwc.mjs

@@ -182,6 +182,7 @@ const REMOVAL_DELAY_MS = 250;
  * All styling is inline, so the library injects no stylesheet. The colors and height resolve CSS
  * custom properties — `--pc-loading-bar-color`, `--pc-loading-bar-background` and
  * `--pc-loading-bar-height` — so a page can theme the bar from `pc-app` or `:root`.
+ * @internal
  */
 class LoadingBar {
     _track;
@@ -280,6 +281,11 @@ class LoadingBar {
     }
 }
 
+/**
+ * The CSS color keywords, lowercase name to hex value. Read by `parseColor` to accept color
+ * names as attribute values.
+ * @internal
+ */
 const CSS_COLORS = {
     aliceblue: '#f0f8ff',
     antiquewhite: '#faebd7',
@@ -455,7 +461,7 @@ const CSS_COLORS = {
  * @param value - The value to split.
  * @param count - The required number of components.
  * @returns The parsed components, or `null`.
- * @ignore
+ * @internal
  */
 const parseComponents = (value, count) => {
     const components = value.trim().split(/\s+/).map(Number);
@@ -486,6 +492,7 @@ const cloneDefault = (value) => {
  * @param value - The attribute value to parse (`null` when the attribute is absent).
  * @param defaultValue - The value to use when the attribute is absent or removed.
  * @returns The parsed boolean.
+ * @internal
  */
 const parseBool = (value, defaultValue) => {
     return value === null ? defaultValue : value !== 'false';
@@ -501,6 +508,7 @@ const parseBool = (value, defaultValue) => {
  * @param defaultValue - The value to use when the attribute is absent or invalid.
  * @param attribute - The attribute name, used in the warning message.
  * @returns The parsed Color object.
+ * @internal
  */
 const parseColor = (value, defaultValue, attribute) => {
     if (value === null) {
@@ -542,6 +550,7 @@ const parseColor = (value, defaultValue, attribute) => {
  * @param defaultValue - The value to use when the attribute is absent or invalid.
  * @param attribute - The attribute name, used in the warning message.
  * @returns The resolved enum name.
+ * @internal
  */
 const parseEnum = (value, valid, defaultValue, attribute) => {
     if (value === null) {
@@ -563,6 +572,7 @@ const parseEnum = (value, valid, defaultValue, attribute) => {
  * @param defaultValue - The value to use when the attribute is absent or invalid.
  * @param attribute - The attribute name, used in the warning message.
  * @returns The parsed number.
+ * @internal
  */
 const parseNumber = (value, defaultValue, attribute) => {
     if (value === null) {
@@ -585,6 +595,7 @@ const parseNumber = (value, defaultValue, attribute) => {
  * @param defaultValue - The value to use when the attribute is absent or invalid.
  * @param attribute - The attribute name, used in the warning message.
  * @returns The parsed Quat object.
+ * @internal
  */
 const parseQuat = (value, defaultValue, attribute) => {
     if (value === null) {
@@ -608,6 +619,7 @@ const parseQuat = (value, defaultValue, attribute) => {
  * @param value - The attribute value to parse (`null` when the attribute is absent).
  * @param defaultValue - The value to use when the attribute is absent or removed.
  * @returns The parsed tag names.
+ * @internal
  */
 const parseTags = (value, defaultValue = []) => {
     if (value === null) {
@@ -629,6 +641,7 @@ const parseTags = (value, defaultValue = []) => {
  * @param defaultValue - The value to use when the attribute is absent or invalid.
  * @param attribute - The attribute name, used in the warning message.
  * @returns The parsed Vec2 object.
+ * @internal
  */
 const parseVec2 = (value, defaultValue, attribute) => {
     if (value === null) {
@@ -650,6 +663,7 @@ const parseVec2 = (value, defaultValue, attribute) => {
  * @param defaultValue - The value to use when the attribute is absent or invalid.
  * @param attribute - The attribute name, used in the warning message.
  * @returns The parsed Vec3 object.
+ * @internal
  */
 const parseVec3 = (value, defaultValue, attribute) => {
     if (value === null) {
@@ -671,6 +685,7 @@ const parseVec3 = (value, defaultValue, attribute) => {
  * @param defaultValue - The value to use when the attribute is absent or invalid.
  * @param attribute - The attribute name, used in the warning message.
  * @returns The parsed Vec4 object.
+ * @internal
  */
 const parseVec4 = (value, defaultValue, attribute) => {
     if (value === null) {
@@ -690,6 +705,7 @@ const parseVec4 = (value, defaultValue, attribute) => {
  *
  * @param ref - The reference string to resolve.
  * @returns The resolved entity, or `null`.
+ * @internal
  */
 const getEntity = (ref) => {
     if (!ref) {
@@ -1248,21 +1264,63 @@ class AppElement extends AsyncElement {
         }
         return null;
     }
-    // New helper to convert CSS coordinates to canvas (picker) coordinates
-    _getPickerCoordinates(event) {
-        // 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.
+     */
+    _getPickerCoordinates(event, canvas) {
+        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.
+     */
+    _cameraContains(camera, x, y, canvas) {
+        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
@@ -1272,16 +1330,40 @@ class AppElement extends AsyncElement {
      * @returns The graph node under the pointer, or `null` if nothing was hit.
      */
     async _pickNode(event) {
-        const camera = this.app.root.findComponent('camera');
-        if (!camera)
-            return null;
-        const { x, y } = this._getPickerCoordinates(event);
-        this._picker.prepare(camera, this.app.scene);
-        const selection = await this._picker.getSelectionAsync(x, y);
-        if (selection.length === 0)
+        const app = this.app;
+        const picker = this._picker;
+        const canvas = this._canvas;
+        if (!app || !picker || !canvas)
             return null;
-        const item = selection[0];
-        return item instanceof MeshInstance ? item.node : item.entity;
+        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;
+            picker.prepare(camera, app.scene);
+            const selection = await picker.getSelectionAsync(x, y);
+            // The element may have disconnected while the read back was in flight.
+            if (!this._picker || !this.app)
+                return null;
+            if (selection.length > 0) {
+                const item = selection[0];
+                return item instanceof MeshInstance ? item.node : item.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;
     }
     async _onPointerMove(event) {
         if (!this._picker || !this.app)
@@ -1528,7 +1610,7 @@ customElements.define('pc-app', AppElement);
 /**
  * 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 = [
     'onpointerenter',
@@ -2225,6 +2307,10 @@ const processBufferView = (gltfBuffer, buffers, continuation) => {
  * 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
@@ -2424,7 +2510,9 @@ class AssetElement extends AsyncElement {
         if (type === 'sprite') {
             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);
@@ -2585,13 +2673,18 @@ class AssetElement extends AsyncElement {
         return this._flipY;
     }
     /**
-     * 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) {
         this._lazy = value;
         if (this.asset) {
             this.asset.preload = !value;
+            if (!value) {
+                this.asset.registry?.load(this.asset);
+            }
         }
     }
     /**
@@ -2775,6 +2868,26 @@ 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
+ */
+const useAsset = (id) => {
+    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;
+};
 
 /**
  * Represents a component in the PlayCanvas engine.
@@ -3058,15 +3171,15 @@ class ButtonComponentElement extends ComponentElement {
         if (imageEntity) {
             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;
         }
@@ -3228,7 +3341,7 @@ class ButtonComponentElement extends ComponentElement {
      */
     set hoverSpriteAsset(value) {
         this._hoverSpriteAsset = value;
-        const asset = AssetElement.get(value);
+        const asset = useAsset(value);
         if (this.component && asset) {
             this.component.hoverSpriteAsset = asset.id;
         }
@@ -3264,7 +3377,7 @@ class ButtonComponentElement extends ComponentElement {
      */
     set pressedSpriteAsset(value) {
         this._pressedSpriteAsset = value;
-        const asset = AssetElement.get(value);
+        const asset = useAsset(value);
         if (this.component && asset) {
             this.component.pressedSpriteAsset = asset.id;
         }
@@ -3300,7 +3413,7 @@ class ButtonComponentElement extends ComponentElement {
      */
     set inactiveSpriteAsset(value) {
         this._inactiveSpriteAsset = value;
-        const asset = AssetElement.get(value);
+        const asset = useAsset(value);
         if (this.component && asset) {
             this.component.inactiveSpriteAsset = asset.id;
         }
@@ -4158,15 +4271,15 @@ 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;
         }
@@ -4280,7 +4393,7 @@ class ElementComponentElement extends ComponentElement {
      */
     set fontAsset(value) {
         this._fontAsset = value;
-        const asset = AssetElement.get(value);
+        const asset = useAsset(value);
         if (this.component && asset) {
             this.component.fontAsset = asset.id;
         }
@@ -4435,7 +4548,7 @@ class ElementComponentElement extends ComponentElement {
      */
     set spriteAsset(value) {
         this._spriteAsset = value;
-        const asset = AssetElement.get(value);
+        const asset = useAsset(value);
         if (this.component && asset) {
             this.component.spriteAsset = asset.id;
         }
@@ -4487,7 +4600,7 @@ class ElementComponentElement extends ComponentElement {
      */
     set textureAsset(value) {
         this._textureAsset = value;
-        const asset = AssetElement.get(value);
+        const asset = useAsset(value);
         if (this.component && asset) {
             this.component.textureAsset = asset.id;
         }
@@ -5722,13 +5835,14 @@ class ParticleSystemComponentElement extends ComponentElement {
         super('particlesystem');
     }
     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.colorMapAsset) {
             const id = asset.resource.colorMapAsset;
-            const colorMapAsset = AssetElement.get(id)?.id;
+            const colorMapAsset = useAsset(id)?.id;
             if (colorMapAsset) {
                 asset.resource.colorMapAsset = colorMapAsset;
             }
@@ -5754,9 +5868,8 @@ class ParticleSystemComponentElement extends ComponentElement {
         }
     }
     async _loadAsset() {
-        const appElement = await this.closestApp?.ready();
-        const app = appElement?.app;
-        const asset = AssetElement.get(this._asset);
+        await this.closestApp?.ready();
+        const asset = useAsset(this._asset);
         if (!asset) {
             return;
         }
@@ -5767,7 +5880,6 @@ class ParticleSystemComponentElement extends ComponentElement {
             asset.once('load', () => {
                 this.applyConfig(asset.resource);
             });
-            app.assets.load(asset);
         }
     }
     /**
@@ -5959,6 +6071,7 @@ class MaterialElement extends HTMLElement {
     _metalnessMapRotation = 0;
     _metalnessMapTiling = new Vec2(1, 1);
     _metalnessMapUv = 0;
+    _name = 'Untitled';
     _normalMap = '';
     _normalMapOffset = new Vec2(0, 0);
     _normalMapRotation = 0;
@@ -6076,6 +6189,7 @@ class MaterialElement extends HTMLElement {
         material.metalnessMapRotation = this._metalnessMapRotation;
         material.metalnessMapTiling = this._metalnessMapTiling;
         material.metalnessMapUv = this._metalnessMapUv;
+        material.name = this._name;
         material.normalMapOffset = this._normalMapOffset;
         material.normalMapRotation = this._normalMapRotation;
         material.normalMapTiling = this._normalMapTiling;
@@ -6183,7 +6297,7 @@ class MaterialElement extends HTMLElement {
             this._scheduleUpdate();
             return;
         }
-        const asset = AssetElement.get(id);
+        const asset = useAsset(id);
         if (!asset)
             return;
         if (asset.loaded) {
@@ -7162,6 +7276,26 @@ class MaterialElement extends HTMLElement {
     get metalnessMapUv() {
         return this._metalnessMapUv;
     }
+    /**
+     * Sets the name of the material.
+     * @param value - The material name.
+     */
+    set name(value) {
+        this._name = value;
+        if (this.material) {
+            // A label rather than shader state, so no update() is scheduled
+            this.material.name = value;
+        }
+    }
+    /**
+     * Gets 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. Purely a
+     * label: element references resolve through `id`.
+     * @returns The material name.
+     */
+    get name() {
+        return this._name;
+    }
     /**
      * Sets the id of the `pc-asset` to use as the normal map.
      * @param value - The asset id.
@@ -7733,6 +7867,7 @@ class MaterialElement extends HTMLElement {
             'metalness-map-rotation',
             'metalness-map-tiling',
             'metalness-map-uv',
+            'name',
             'normal-map',
             'normal-map-offset',
             'normal-map-rotation',
@@ -7933,6 +8068,9 @@ class MaterialElement extends HTMLElement {
             case 'metalness-map-uv':
                 this.metalnessMapUv = parseNumber(newValue, 0, name);
                 break;
+            case 'name':
+                this.name = newValue ?? 'Untitled';
+                break;
             case 'normal-map':
                 this.normalMap = newValue ?? '';
                 break;
@@ -9284,7 +9422,7 @@ const camelToKebab = (name) => {
  * @returns The asset, or `raw`.
  */
 const assetConversion = (rest, raw) => {
-    const asset = AssetElement.get(rest);
+    const asset = useAsset(rest);
     if (asset) {
         return asset;
     }
@@ -10104,7 +10242,7 @@ class SoundSlotElement extends AsyncElement {
     set asset(value) {
         this._asset = value;
         if (this.soundSlot) {
-            const id = AssetElement.get(value)?.id;
+            const id = useAsset(value)?.id;
             if (id) {
                 this.soundSlot.asset = id;
             }
@@ -10311,7 +10449,7 @@ class GSplatComponentElement extends ComponentElement {
     }
     getInitialComponentData() {
         return {
-            asset: AssetElement.get(this._asset),
+            asset: useAsset(this._asset),
             castShadows: this._castShadows,
             lodBaseDistance: this._lodBaseDistance,
             lodMultiplier: this._lodMultiplier,
@@ -10332,7 +10470,7 @@ class GSplatComponentElement extends ComponentElement {
      */
     set asset(value) {
         this._asset = value;
-        const asset = AssetElement.get(value);
+        const asset = useAsset(value);
         if (this.component && asset) {
             this.component.asset = asset;
         }
@@ -10478,6 +10616,41 @@ class GSplatComponentElement extends ComponentElement {
 }
 customElements.define('pc-gsplat', GSplatComponentElement);
 
+/**
+ * Formats one line of the printable hierarchy: the node's name, an `[index]` marker when the
+ * name is shared by several nodes in the model, the attached component types, and the material
+ * names of a render component.
+ *
+ * @param node - The node to format.
+ * @param counts - The number of nodes bearing each name.
+ * @returns The formatted line.
+ */
+const formatNode = (node, counts) => {
+    const index = (counts.get(node.name) ?? 0) > 1 ? ` [${node.index}]` : '';
+    const components = node.components.length > 0 ? ` (${node.components.join(', ')})` : '';
+    // Braces rather than brackets: `[N]` already means a match index on this line
+    const materials = node.materials.length > 0 ? ` {${node.materials.map((slot) => slot.name ?? 'null').join(', ')}}` : '';
+    return `${node.name}${index}${components}${materials}`;
+};
+/**
+ * Formats the printable form of a hierarchy subtree.
+ *
+ * @param root - The subtree root.
+ * @param counts - The number of nodes bearing each name.
+ * @returns The tree, one line per node.
+ */
+const formatHierarchy = (root, counts) => {
+    const lines = [formatNode(root, counts)];
+    const walk = (node, prefix) => {
+        node.children.forEach((child, i) => {
+            const last = i === node.children.length - 1;
+            lines.push(`${prefix}${last ? '└─ ' : '├─ '}${formatNode(child, counts)}`);
+            walk(child, `${prefix}${last ? '   ' : '│  '}`);
+        });
+    };
+    walk(root, '');
+    return lines.join('\n');
+};
 /**
  * The ModelElement interface provides properties and methods for manipulating
  * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-model/ | `<pc-model>`} elements.
@@ -10524,6 +10697,57 @@ class ModelElement extends AsyncElement {
     get entity() {
         return this._entity;
     }
+    /**
+     * Returns a snapshot of the instantiated node tree, or `null` while there is none (the
+     * container asset has not loaded, or the element has left the document). One call grounds a
+     * session — a browser console, a test, an agent — in the vocabulary `pc-node` binding
+     * resolves against: the instantiated names ({@link HierarchyNode.name}), paths, match
+     * indices, attached component types and the material assignments of render components
+     * ({@link HierarchyNode.materials}). `String(...)` of the result, or of any node in it,
+     * is the printable form.
+     *
+     * The snapshot is plain data, computed afresh each call: it does not follow later changes
+     * to the hierarchy, and mutating it changes nothing.
+     *
+     * @returns The root of the instantiated node tree, or `null`.
+     */
+    hierarchy() {
+        const root = this._entity;
+        if (!root) {
+            return null;
+        }
+        // Ordinals are assigned in the traversal resolution searches — pre-order depth-first
+        // from the model root, the root itself included — so each node's index is exactly what
+        // a pc-node's index attribute selects. Once the walk completes, the map holds the total
+        // count per name, which is what the printable form reads to annotate only shared names.
+        const ordinals = new Map();
+        const describe = (entity, pathBelowRoot) => {
+            const index = ordinals.get(entity.name) ?? 0;
+            ordinals.set(entity.name, index + 1);
+            const node = {
+                name: entity.name,
+                // The root has no path below itself; its own name stands in, as it does for
+                // the path a pc-node bound to the root reports.
+                path: pathBelowRoot || entity.name,
+                index,
+                // A plain GraphNode grafted into the hierarchy has no component storage
+                components: Object.keys(entity.c ?? {}).sort(),
+                materials: (entity.render?.meshInstances ?? []).map((meshInstance, slot) => ({
+                    index: slot,
+                    name: meshInstance.material?.name ?? null
+                })),
+                children: entity.children.map((child) => describe(child, pathBelowRoot ? `${pathBelowRoot}/${child.name}` : child.name))
+            };
+            // Non-enumerable, keeping the snapshot plain data under JSON.stringify, spreads and
+            // key enumeration. Deferred to call time, by which the ordinal map holds its totals.
+            Object.defineProperty(node, 'toString', {
+                enumerable: false,
+                value: () => formatHierarchy(node, ordinals)
+            });
+            return node;
+        };
+        return describe(root, '');
+    }
     connectedCallback() {
         // A model outside an application is inert and never becomes ready, so awaiting it hangs.
         // Warn rather than fail silently, naming the parent it requires, as every other misplaced
@@ -10610,8 +10834,7 @@ class ModelElement extends AsyncElement {
         if (generation !== this._loadGeneration) {
             return;
         }
-        const app = appElement.app;
-        const asset = AssetElement.get(this._asset);
+        const asset = useAsset(this._asset);
         if (!asset) {
             // An empty id is a legitimate transient (the asset may be assigned later); a
             // non-empty one that resolves to nothing is a dead end - say so rather than staying
@@ -10647,7 +10870,6 @@ class ModelElement extends AsyncElement {
                 }));
                 this._onReady();
             });
-            app.assets.load(asset);
         }
     }
     _unloadModel() {
@@ -10684,6 +10906,74 @@ class ModelElement extends AsyncElement {
 }
 customElements.define('pc-model', ModelElement);
 
+/**
+ * Parses one mapping into its valid rules, warning for each entry that is not one: an unknown
+ * or missing selector prefix, an empty `name:` value, an `index:` value that is not a
+ * non-negative integer, or a replacement id that is not a non-empty string. An invalid rule
+ * behaves exactly as if absent from the mapping.
+ *
+ * @param overrides - The mapping to parse.
+ * @param label - The element description for warnings.
+ * @returns The valid rules.
+ */
+const parseMaterialRules = (overrides, label) => {
+    const rules = [];
+    for (const [selector, id] of Object.entries(overrides)) {
+        if (typeof id !== 'string' || id === '') {
+            console.warn(`${label} material-overrides '${selector}' needs a pc-material id - rule ignored`);
+        }
+        else if (selector.startsWith('name:')) {
+            // The text after the prefix is the selector value, exactly as written - a material
+            // name may legitimately begin or end with whitespace
+            const name = selector.slice('name:'.length);
+            if (name === '') {
+                console.warn(`${label} material-overrides 'name:' selector is empty - rule ignored`);
+            }
+            else {
+                rules.push({ kind: 'name', name, id });
+            }
+        }
+        else if (selector.startsWith('index:')) {
+            // Whitespace around the number is tolerated; Number('') is 0, so blank means NaN
+            const text = selector.slice('index:'.length).trim();
+            const index = text === '' ? NaN : Number(text);
+            if (!Number.isInteger(index) || index < 0) {
+                console.warn(`${label} material-overrides '${selector}' is not a non-negative integer index - rule ignored`);
+            }
+            else {
+                rules.push({ kind: 'index', index, id });
+            }
+        }
+        else {
+            console.warn(`${label} material-overrides '${selector}' has no 'name:' or 'index:' prefix - rule ignored`);
+        }
+    }
+    return rules;
+};
+/**
+ * Parses the material-overrides attribute text. Anything but a JSON object — malformed JSON, an
+ * array, a primitive — warns and yields `null`, the absent mapping: a stale mapping must not
+ * survive an attribute value the DOM no longer represents.
+ *
+ * @param text - The attribute text.
+ * @param label - The element description for warnings.
+ * @returns The mapping, or `null`.
+ */
+const parseMaterialOverridesAttribute = (text, label) => {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        console.warn(`${label} material-overrides is not valid JSON - treated as absent: ${error.message}`);
+        return null;
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        console.warn(`${label} material-overrides must be a JSON object - treated as absent`);
+        return null;
+    }
+    return parsed;
+};
 /**
  * Computes the Levenshtein distance between two strings, for near-miss suggestions in the
  * resolution warnings.
@@ -10739,6 +11029,13 @@ const levenshtein = (a, b) => {
  * "x y z" triple.
  * @attribute {string} scale - Overrides the node's local scale, as an "x y z" triple.
  * @attribute {string} tags - Overrides the node's tags, separated by spaces or commas.
+ * @attribute {string} material-overrides - 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.
  * @attribute {string} onpointerenter - Script to run when the pointer moves onto the node.
  * @attribute {string} onpointerleave - Script to run when the pointer moves off the node.
  * @attribute {string} onpointermove - Script to run when the pointer moves over the node.
@@ -10774,12 +11071,25 @@ class NodeElement extends EntityBaseElement {
     _destroyHandle = null;
     /** The authored values displaced by this element's overrides, captured per property. */
     _authored = {};
+    /**
+     * The model-authored render component of the bound node, recorded at bind — before child
+     * decorations build — so a render component added later by a child `pc-render` can never
+     * become the override target. `null` when the bound node has none.
+     */
+    _authoredRender = null;
+    /**
+     * The baseline assignments displaced by the material overrides, captured for every mesh
+     * instance when the first non-empty mapping applies and released when the mapping goes
+     * absent (restoring them) or the binding dissolves.
+     */
+    _baseline = null;
     // Override values. `null` means "no override": the authored value stays in force.
     _enabled = null;
     _position = null;
     _rotation = null;
     _scale = null;
     _tags = null;
+    _materialOverrides = null;
     /**
      * The binding state: `pending` until the host instantiates and `name` resolves, `bound`
      * once decorated, `missing`/`ambiguous`/`duplicate` when resolution failed (each also
@@ -10913,6 +11223,7 @@ class NodeElement extends EntityBaseElement {
         this._destroyHandle = target.once('destroy', this._onEntityDestroy, this);
         this._state = 'bound';
         this._path = this._pathOf(target, hostEntity);
+        this._authoredRender = target.render ?? null;
         this._applyOverrides();
         this._onReady();
         this._buildChildren();
@@ -10943,6 +11254,7 @@ class NodeElement extends EntityBaseElement {
         this._entity = null;
         this._path = null;
         this._authored = {};
+        this._authoredRender = null;
         // Component decorations come off through the same hook the host-ready cycle uses. A
         // dissolve that never rebinds fires no ready event, so the sweep is explicit - after
         // `_entity` is cleared, so the hook sees a host without an entity.
@@ -10964,6 +11276,9 @@ class NodeElement extends EntityBaseElement {
         this._entity = null;
         this._path = null;
         this._authored = {};
+        this._authoredRender = null;
+        // The mesh instances died with the entity - the capture is dropped, not restored
+        this._baseline = null;
         this._state = 'pending';
         this._resetReady();
     }
@@ -11005,6 +11320,9 @@ class NodeElement extends EntityBaseElement {
         if (this._tags !== null) {
             this.tags = this._tags;
         }
+        if (this._materialOverrides !== null) {
+            this._applyMaterialOverrides();
+        }
     }
     /**
      * Restores every authored value this element's overrides displaced. The override values
@@ -11030,6 +11348,104 @@ class NodeElement extends EntityBaseElement {
             entity.tags.add(authored.tags);
         }
         this._authored = {};
+        this._restoreBaseline();
+    }
+    /**
+     * Applies the material mapping to the authored render component: parse the mapping's valid
+     * rules, capture the baseline on first application, then recompute every assignment from
+     * that baseline - name rules write over it, index rules write over them, so `index:` wins -
+     * and assign whatever changed. An absent mapping, or one with no valid rules, restores the
+     * baseline instead. Called while bound, from `_applyOverrides` and the property setter.
+     */
+    _applyMaterialOverrides() {
+        const label = `pc-node '${this._name}'`;
+        const rules = this._materialOverrides ? parseMaterialRules(this._materialOverrides, label) : [];
+        if (rules.length === 0) {
+            this._restoreBaseline();
+            return;
+        }
+        if (!this._baseline) {
+            if (!this._authoredRender) {
+                console.warn(`${label} is bound to a node without an authored render component - material-overrides ignored`);
+                return;
+            }
+            this._baseline = this._authoredRender.meshInstances.map((meshInstance) => ({
+                meshInstance,
+                material: meshInstance.material ?? null,
+                name: meshInstance.material?.name ?? null
+            }));
+        }
+        const baseline = this._baseline;
+        /** Resolves a replacement id, warning when it does not resolve. */
+        const resolveReplacement = (id) => {
+            const material = MaterialElement.get(id);
+            if (!material) {
+                console.warn(`${label} material-overrides could not resolve pc-material '${id}' - rule ignored`);
+            }
+            return material ?? null;
+        };
+        // Recompute the whole list from the baseline: name rules write over it, index rules
+        // write over them. Recomputing makes mapping edits order-independent, and a rule whose
+        // replacement does not resolve simply leaves the layer below it in force.
+        const resolved = baseline.map((assignment) => assignment.material);
+        for (const rule of rules) {
+            if (rule.kind !== 'name') {
+                continue;
+            }
+            const material = resolveReplacement(rule.id);
+            if (!material) {
+                continue;
+            }
+            let matched = false;
+            baseline.forEach((assignment, index) => {
+                if (assignment.name === rule.name) {
+                    resolved[index] = material;
+                    matched = true;
+                }
+            });
+            if (!matched) {
+                const names = baseline.map((assignment) => `'${assignment.name}'`).join(', ');
+                console.warn(`${label} material-overrides 'name:${rule.name}' matches no assignment - ` +
+                    `baseline names: ${names || '(none)'}`);
+            }
+        }
+        for (const rule of rules) {
+            if (rule.kind !== 'index') {
+                continue;
+            }
+            if (rule.index >= baseline.length) {
+                console.warn(`${label} material-overrides 'index:${rule.index}' is out of range - ` +
+                    `${baseline.length} assignment(s)`);
+                continue;
+            }
+            const material = resolveReplacement(rule.id);
+            if (material) {
+                resolved[rule.index] = material;
+            }
+        }
+        baseline.forEach((assignment, index) => {
+            // The engine setter rebuilds material and shader state even for a redundant write,
+            // so only actual changes are assigned
+            if (assignment.meshInstance.material !== resolved[index]) {
+                assignment.meshInstance.material = resolved[index];
+            }
+        });
+    }
+    /**
+     * Restores every baseline assignment the material overrides displaced and releases the
+     * capture, so the next non-empty mapping captures afresh. Safe to call without a capture.
+     */
+    _restoreBaseline() {
+        const baseline = this._baseline;
+        if (!baseline) {
+            return;
+        }
+        this._baseline = null;
+        for (const assignment of baseline) {
+            if (assignment.meshInstance.material !== assignment.material) {
+                assignment.meshInstance.material = assignment.material;
+            }
+        }
     }
     /**
      * Renders the path of `node` below `root`, for the `path` property and the resolution
@@ -11250,8 +11666,41 @@ class NodeElement extends EntityBaseElement {
     get tags() {
         return this._tags;
     }
+    /**
+     * Sets the material overrides: a sparse mapping from selector to `pc-material` id, applied
+     * to the bound node's authored render component. 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. `null` clears the mapping, restoring every baseline assignment.
+     * @param value - The mapping, or `null`.
+     */
+    set materialOverrides(value) {
+        // Copied and frozen: later caller mutation of the passed object must not silently
+        // disagree with the mapping the element applied
+        this._materialOverrides = value === null ? null : Object.freeze({ ...value });
+        if (this._state === 'bound') {
+            this._applyMaterialOverrides();
+        }
+    }
+    /**
+     * Gets the material overrides.
+     * @returns The mapping, or `null` while no override is set.
+     */
+    get materialOverrides() {
+        return this._materialOverrides;
+    }
     static get observedAttributes() {
-        return ['enabled', 'index', 'name', 'position', 'rotation', 'scale', 'tags', ...POINTER_ATTRIBUTES];
+        return [
+            'enabled',
+            'index',
+            'material-overrides',
+            'name',
+            'position',
+            'rotation',
+            'scale',
+            'tags',
+            ...POINTER_ATTRIBUTES
+        ];
     }
     attributeChangedCallback(name, _oldValue, newValue) {
         switch (name) {
@@ -11276,6 +11725,10 @@ class NodeElement extends EntityBaseElement {
                     }
                 }
                 break;
+            case 'material-overrides':
+                this.materialOverrides =
+                    newValue === null ? null : parseMaterialOverridesAttribute(newValue, `pc-node '${this._name}'`);
+                break;
             case 'name':
                 this.name = newValue ?? '';
                 break;
@@ -11612,7 +12065,7 @@ class SkyElement extends AsyncElement {
             return;
         }
         this._appElement = appElement;
-        const asset = AssetElement.get(this._asset);
+        const asset = useAsset(this._asset);
         if (!asset) {
             return;
         }
@@ -11631,7 +12084,6 @@ class SkyElement extends AsyncElement {
                 }
                 this._generateSkybox(asset);
             });
-            app.assets.load(asset);
         }
     }
     _unloadSkybox() {