@playcanvas/web-components 0.13.0 → 0.14.0

package/dist/app.d.cts

@@ -131,10 +131,45 @@ declare class AppElement extends AsyncElement {
      * @returns The nearest listening element, or `null`.
      */
     private _elementWithListener;
+    /**
+     * 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;
+    /**
+     * 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;
     /**
      * 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

package/dist/app.d.ts

@@ -131,10 +131,45 @@ declare class AppElement extends AsyncElement {
      * @returns The nearest listening element, or `null`.
      */
     private _elementWithListener;
+    /**
+     * 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;
+    /**
+     * 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;
     /**
      * 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

package/dist/asset.d.cts

@@ -16,6 +16,10 @@ type MagFilterMode = 'nearest' | 'linear';
  * 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
@@ -146,7 +150,9 @@ declare class AssetElement extends AsyncElement {
      */
     get flipY(): boolean | null;
     /**
-     * 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);

package/dist/asset.d.ts

@@ -16,6 +16,10 @@ type MagFilterMode = 'nearest' | 'linear';
  * 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
@@ -146,7 +150,9 @@ declare class AssetElement extends AsyncElement {
      */
     get flipY(): boolean | null;
     /**
-     * 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);

package/dist/colors.d.cts

@@ -1 +1 @@
-export declare const CSS_COLORS: Record<string, string>;
+export {};

package/dist/colors.d.ts

@@ -1 +1 @@
-export declare const CSS_COLORS: Record<string, string>;
+export {};

package/dist/custom-elements.json

@@ -346,7 +346,7 @@
       "declarations": [
         {
           "kind": "class",
-          "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",
+          "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",
           "name": "AssetElement",
           "members": [
             {
@@ -1777,6 +1777,30 @@
             "name": "AsyncElementTagName",
             "module": "./async-element"
           }
+        },
+        {
+          "kind": "js",
+          "name": "HierarchyMaterial",
+          "declaration": {
+            "name": "HierarchyMaterial",
+            "module": "./model"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "HierarchyNode",
+          "declaration": {
+            "name": "HierarchyNode",
+            "module": "./model"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "MaterialOverrides",
+          "declaration": {
+            "name": "MaterialOverrides",
+            "module": "./node"
+          }
         }
       ]
     },
@@ -2715,6 +2739,22 @@
                 }
               }
             },
+            {
+              "kind": "field",
+              "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`.",
+              "parameters": [
+                {
+                  "description": "The material name.",
+                  "name": "value"
+                }
+              ],
+              "return": {
+                "type": {
+                  "text": ""
+                }
+              }
+            },
             {
               "kind": "field",
               "name": "normalMap",
@@ -3657,6 +3697,14 @@
               "default": "0",
               "description": "The UV channel the metalness map samples."
             },
+            {
+              "name": "name",
+              "type": {
+                "text": "string"
+              },
+              "fieldName": "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."
+            },
             {
               "name": "normal-map",
               "type": {
@@ -3937,6 +3985,10 @@
       "kind": "javascript-module",
       "path": "src/model.ts",
       "declarations": [
+        {
+          "kind": "variable",
+          "name": "index"
+        },
         {
           "kind": "class",
           "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",
@@ -4011,6 +4063,16 @@
               },
               "readonly": true
             },
+            {
+              "kind": "method",
+              "name": "hierarchy",
+              "return": {
+                "type": {
+                  "text": ""
+                }
+              },
+              "description": "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."
+            },
             {
               "kind": "method",
               "name": "ready",
@@ -4087,6 +4149,22 @@
             "name": "ModelElement",
             "module": "src/model.ts"
           }
+        },
+        {
+          "kind": "js",
+          "name": "HierarchyMaterial",
+          "declaration": {
+            "name": "HierarchyMaterial",
+            "module": "src/model.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "HierarchyNode",
+          "declaration": {
+            "name": "HierarchyNode",
+            "module": "src/model.ts"
+          }
         }
       ]
     },
@@ -4350,6 +4428,25 @@
                 }
               }
             },
+            {
+              "kind": "field",
+              "name": "materialOverrides",
+              "description": "Gets the material overrides.",
+              "parameters": [
+                {
+                  "description": "The mapping, or `null`.",
+                  "name": "value"
+                }
+              ],
+              "type": {
+                "text": "MaterialOverrides | null"
+              },
+              "return": {
+                "type": {
+                  "text": ""
+                }
+              }
+            },
             {
               "kind": "field",
               "name": "name",
@@ -4582,6 +4679,14 @@
               "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.",
               "fieldName": "index"
             },
+            {
+              "name": "material-overrides",
+              "type": {
+                "text": "string"
+              },
+              "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.",
+              "fieldName": "materialOverrides"
+            },
             {
               "name": "name",
               "type": {
@@ -4687,6 +4792,14 @@
             "name": "NodeElement",
             "module": "src/node.ts"
           }
+        },
+        {
+          "kind": "js",
+          "name": "MaterialOverrides",
+          "declaration": {
+            "name": "MaterialOverrides",
+            "module": "src/node.ts"
+          }
         }
       ]
     },

package/dist/entity-base.d.cts

@@ -1,12 +1,6 @@
 import type { Entity } from 'playcanvas';
 import type { AppElement } from './app.cjs';
 import { AsyncElement } from './async-element.cjs';
-/**
- * The attribute names of the inline `onpointer*` event handlers, shared by every element that
- * fronts an engine entity. Spread into `observedAttributes` by subclasses.
- * @ignore
- */
-declare const POINTER_ATTRIBUTES: readonly ["onpointerenter", "onpointerleave", "onpointerdown", "onpointerup", "onpointermove"];
 /**
  * The base class for elements that front an engine {@link Entity}: `<pc-entity>`, which creates
  * one, and `<pc-node>`, which binds to one inside a model's instantiated hierarchy. It carries
@@ -64,4 +58,4 @@ declare class EntityBaseElement extends AsyncElement {
     addEventListener(type: string, listener: EventListener, options?: boolean | AddEventListenerOptions): void;
     removeEventListener(type: string, listener: EventListener, options?: boolean | EventListenerOptions): void;
 }
-export { EntityBaseElement, POINTER_ATTRIBUTES };
+export { EntityBaseElement };

package/dist/entity-base.d.ts

@@ -1,12 +1,6 @@
 import type { Entity } from 'playcanvas';
 import type { AppElement } from './app.js';
 import { AsyncElement } from './async-element.js';
-/**
- * The attribute names of the inline `onpointer*` event handlers, shared by every element that
- * fronts an engine entity. Spread into `observedAttributes` by subclasses.
- * @ignore
- */
-declare const POINTER_ATTRIBUTES: readonly ["onpointerenter", "onpointerleave", "onpointerdown", "onpointerup", "onpointermove"];
 /**
  * The base class for elements that front an engine {@link Entity}: `<pc-entity>`, which creates
  * one, and `<pc-node>`, which binds to one inside a model's instantiated hierarchy. It carries
@@ -64,4 +58,4 @@ declare class EntityBaseElement extends AsyncElement {
     addEventListener(type: string, listener: EventListener, options?: boolean | AddEventListenerOptions): void;
     removeEventListener(type: string, listener: EventListener, options?: boolean | EventListenerOptions): void;
 }
-export { EntityBaseElement, POINTER_ATTRIBUTES };
+export { EntityBaseElement };

package/dist/index.d.cts

@@ -77,3 +77,5 @@ declare global {
 }
 export { AsyncElement, ModuleElement, AppElement, EntityElement, AssetElement, ButtonComponentElement, CameraComponentElement, CollisionComponentElement, ComponentElement, ElementComponentElement, LayoutChildComponentElement, LayoutGroupComponentElement, ParticleSystemComponentElement, LightComponentElement, ListenerComponentElement, RenderComponentElement, RigidBodyComponentElement, ScreenComponentElement, ScrollbarComponentElement, ScrollViewComponentElement, ScriptComponentElement, ScriptElement, SoundComponentElement, SoundSlotElement, GSplatComponentElement, EntityBaseElement, MaterialElement, ModelElement, NodeElement, SceneElement, SkyElement, whenReady };
 export type { AsyncElementTagName } from './async-element.cjs';
+export type { HierarchyMaterial, HierarchyNode } from './model.cjs';
+export type { MaterialOverrides } from './node.cjs';

package/dist/index.d.ts

@@ -77,3 +77,5 @@ declare global {
 }
 export { AsyncElement, ModuleElement, AppElement, EntityElement, AssetElement, ButtonComponentElement, CameraComponentElement, CollisionComponentElement, ComponentElement, ElementComponentElement, LayoutChildComponentElement, LayoutGroupComponentElement, ParticleSystemComponentElement, LightComponentElement, ListenerComponentElement, RenderComponentElement, RigidBodyComponentElement, ScreenComponentElement, ScrollbarComponentElement, ScrollViewComponentElement, ScriptComponentElement, ScriptElement, SoundComponentElement, SoundSlotElement, GSplatComponentElement, EntityBaseElement, MaterialElement, ModelElement, NodeElement, SceneElement, SkyElement, whenReady };
 export type { AsyncElementTagName } from './async-element.js';
+export type { HierarchyMaterial, HierarchyNode } from './model.js';
+export type { MaterialOverrides } from './node.js';

package/dist/loading-bar.d.cts

@@ -1,35 +1 @@
-/**
- * The slim progress bar `<pc-app>` shows while it boots and preloads. An implementation detail of
- * AppElement rather than a custom element, so its shape can change without a breaking change.
- *
- * 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`.
- */
-declare class LoadingBar {
-    private _track;
-    private _fill;
-    private _sweep;
-    private _removal;
-    /**
-     * Creates the bar and appends it to `parent`, starting in the indeterminate state.
-     * @param parent - The element to append the bar to.
-     */
-    constructor(parent: HTMLElement);
-    /**
-     * Reflects preload progress, switching the bar from indeterminate to determinate on the first
-     * call.
-     * @param loaded - The number of assets that have finished loading.
-     * @param total - The number of assets being preloaded.
-     */
-    progress(loaded: number, total: number): void;
-    /**
-     * Fills the bar, fades it out and removes it. Idempotent.
-     */
-    complete(): void;
-    /**
-     * Removes the bar immediately, cancelling any pending fade. Idempotent.
-     */
-    destroy(): void;
-}
-export { LoadingBar };
+export {};

package/dist/loading-bar.d.ts

@@ -1,35 +1 @@
-/**
- * The slim progress bar `<pc-app>` shows while it boots and preloads. An implementation detail of
- * AppElement rather than a custom element, so its shape can change without a breaking change.
- *
- * 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`.
- */
-declare class LoadingBar {
-    private _track;
-    private _fill;
-    private _sweep;
-    private _removal;
-    /**
-     * Creates the bar and appends it to `parent`, starting in the indeterminate state.
-     * @param parent - The element to append the bar to.
-     */
-    constructor(parent: HTMLElement);
-    /**
-     * Reflects preload progress, switching the bar from indeterminate to determinate on the first
-     * call.
-     * @param loaded - The number of assets that have finished loading.
-     * @param total - The number of assets being preloaded.
-     */
-    progress(loaded: number, total: number): void;
-    /**
-     * Fills the bar, fades it out and removes it. Idempotent.
-     */
-    complete(): void;
-    /**
-     * Removes the bar immediately, cancelling any pending fade. Idempotent.
-     */
-    destroy(): void;
-}
-export { LoadingBar };
+export {};

package/dist/material.d.cts

@@ -91,6 +91,7 @@ declare class MaterialElement extends HTMLElement {
     private _metalnessMapRotation;
     private _metalnessMapTiling;
     private _metalnessMapUv;
+    private _name;
     private _normalMap;
     private _normalMapOffset;
     private _normalMapRotation;
@@ -706,6 +707,18 @@ declare class MaterialElement extends HTMLElement {
      * @returns The UV channel.
      */
     get metalnessMapUv(): number;
+    /**
+     * Sets the name of the material.
+     * @param value - The material name.
+     */
+    set name(value: string);
+    /**
+     * 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(): string;
     /**
      * Sets the id of the `pc-asset` to use as the normal map.
      * @param value - The asset id.

package/dist/material.d.ts

@@ -91,6 +91,7 @@ declare class MaterialElement extends HTMLElement {
     private _metalnessMapRotation;
     private _metalnessMapTiling;
     private _metalnessMapUv;
+    private _name;
     private _normalMap;
     private _normalMapOffset;
     private _normalMapRotation;
@@ -706,6 +707,18 @@ declare class MaterialElement extends HTMLElement {
      * @returns The UV channel.
      */
     get metalnessMapUv(): number;
+    /**
+     * Sets the name of the material.
+     * @param value - The material name.
+     */
+    set name(value: string);
+    /**
+     * 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(): string;
     /**
      * Sets the id of the `pc-asset` to use as the normal map.
      * @param value - The asset id.

package/dist/model.d.cts

@@ -1,5 +1,60 @@
 import type { Entity } from 'playcanvas';
 import { AsyncElement } from './async-element.cjs';
+/**
+ * One material assignment of a {@link HierarchyNode} with a render component: a mesh instance's
+ * position within the component and the runtime name of its current material.
+ */
+type HierarchyMaterial = {
+    /** The mesh instance's position in the render component's `meshInstances` array. */
+    index: number;
+    /**
+     * The runtime name of the mesh instance's current material, reported as-is: the engine
+     * names an unnamed glTF material `Untitled`, and assigns a shared material named
+     * `defaultGlbMaterial` to a primitive authored without one — neither is a unique authored
+     * identifier. `null` when a script has cleared the assignment.
+     */
+    name: string | null;
+};
+/**
+ * One node of the tree returned by {@link ModelElement.hierarchy}. A plain-data snapshot —
+ * `JSON.stringify` serializes it — whose `toString()` renders the node's subtree as a printable
+ * tree.
+ */
+type HierarchyNode = {
+    /**
+     * The node's name as instantiated, which is the name `pc-node` binding resolves: the engine
+     * parser synthesizes `node_<index>` names for unnamed nodes and renames identically named
+     * siblings apart (`Wheel`, `Wheel1`, ...), so it can differ from the name authored in the
+     * source asset.
+     */
+    name: string;
+    /**
+     * The node's `/`-separated path below the model root — the path a `pc-node` bound to this
+     * node reports. The root's path is its own name.
+     */
+    path: string;
+    /**
+     * The node's position among identically named nodes in the model, counted in depth-first
+     * order over the whole tree: the match a `pc-node`'s `index` attribute selects when `name`
+     * alone is ambiguous.
+     */
+    index: number;
+    /** The types of the components attached to the node (e.g. 'render'), sorted. */
+    components: string[];
+    /**
+     * The material assignments of the node's render component, one entry per mesh instance in
+     * component order. Empty for a node without a render component.
+     */
+    materials: HierarchyMaterial[];
+    /** The node's children. */
+    children: HierarchyNode[];
+    /**
+     * Renders the subtree rooted at this node as a printable tree, one line per node: the name,
+     * `[index]` after a name that several nodes in the model share, the component types in
+     * parentheses, and the material names of a render component in braces.
+     */
+    toString(): string;
+};
 /**
  * The ModelElement interface provides properties and methods for manipulating
  * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-model/ | `<pc-model>`} elements.
@@ -44,6 +99,21 @@ declare class ModelElement extends AsyncElement {
      * @returns The model's root entity, or `null`.
      */
     get entity(): Entity | null;
+    /**
+     * 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(): HierarchyNode | null;
     connectedCallback(): void;
     disconnectedCallback(): void;
     private _detachLoadHandlers;
@@ -70,3 +140,4 @@ declare class ModelElement extends AsyncElement {
     attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
 }
 export { ModelElement };
+export type { HierarchyMaterial, HierarchyNode };