@playcanvas/web-components 0.13.1 → 0.14.0

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

@@ -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 };

package/dist/model.d.ts

@@ -1,5 +1,60 @@
 import type { Entity } from 'playcanvas';
 import { AsyncElement } from './async-element.js';
+/**
+ * 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 };

package/dist/node.d.cts

@@ -7,6 +7,13 @@ import { EntityBaseElement } from './entity-base.cjs';
  * naming the cause.
  */
 type NodeBindingState = 'pending' | 'bound' | 'missing' | 'ambiguous' | 'duplicate';
+/**
+ * A sparse mapping from selector to `pc-material` id, as carried by the `material-overrides`
+ * attribute and `materialOverrides` property. A `name:X` key selects every mesh instance of the
+ * bound node's render component whose baseline material is named `X`; an `index:N` key selects
+ * mesh instance `N` and wins over a name rule for the same instance.
+ */
+type MaterialOverrides = Readonly<Record<string, string>>;
 /**
  * The NodeElement interface provides properties and methods for manipulating
  * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-node/ | `<pc-node>`}
@@ -41,6 +48,13 @@ type NodeBindingState = 'pending' | 'bound' | 'missing' | 'ambiguous' | 'duplica
  * "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.
@@ -76,11 +90,24 @@ declare class NodeElement extends EntityBaseElement {
     private _destroyHandle;
     /** The authored values displaced by this element's overrides, captured per property. */
     private _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.
+     */
+    private _authoredRender;
+    /**
+     * 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.
+     */
+    private _baseline;
     private _enabled;
     private _position;
     private _rotation;
     private _scale;
     private _tags;
+    private _materialOverrides;
     /**
      * The binding state: `pending` until the host instantiates and `name` resolves, `bound`
      * once decorated, `missing`/`ambiguous`/`duplicate` when resolution failed (each also
@@ -149,6 +176,19 @@ declare class NodeElement extends EntityBaseElement {
      * themselves are kept - they re-apply on the next binding.
      */
     private _revertOverrides;
+    /**
+     * 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.
+     */
+    private _applyMaterialOverrides;
+    /**
+     * 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.
+     */
+    private _restoreBaseline;
     /**
      * Renders the path of `node` below `root`, for the `path` property and the resolution
      * warnings.
@@ -247,7 +287,22 @@ declare class NodeElement extends EntityBaseElement {
      * @returns The tags, or `null` while no override is set.
      */
     get tags(): string[] | null;
+    /**
+     * 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: MaterialOverrides | null);
+    /**
+     * Gets the material overrides.
+     * @returns The mapping, or `null` while no override is set.
+     */
+    get materialOverrides(): MaterialOverrides | null;
     static get observedAttributes(): string[];
     attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
 }
 export { NodeElement };
+export type { MaterialOverrides };