@playcanvas/web-components 0.13.1 → 0.15.0

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

@@ -17,6 +17,7 @@ import { CameraComponentElement } from './components/camera-component.cjs';
 import { CollisionComponentElement } from './components/collision-component.cjs';
 import { ComponentElement } from './components/component.cjs';
 import { ElementComponentElement } from './components/element-component.cjs';
+import { JointComponentElement } from './components/joint-component.cjs';
 import { LayoutChildComponentElement } from './components/layoutchild-component.cjs';
 import { LayoutGroupComponentElement } from './components/layoutgroup-component.cjs';
 import { LightComponentElement } from './components/light-component.cjs';
@@ -40,6 +41,7 @@ import { SkyElement } from './sky.cjs';
 import type { ScriptAttributesChangeEvent, ScriptEnableChangeEvent, ScriptNameChangeEvent } from './components/script-component.cjs';
 declare global {
     interface HTMLElementEventMap {
+        break: CustomEvent;
         scriptattributeschange: ScriptAttributesChangeEvent;
         scriptenablechange: ScriptEnableChangeEvent;
         scriptnamechange: ScriptNameChangeEvent;
@@ -53,6 +55,7 @@ declare global {
         'pc-element': ElementComponentElement;
         'pc-entity': EntityElement;
         'pc-gsplat': GSplatComponentElement;
+        'pc-joint': JointComponentElement;
         'pc-layoutchild': LayoutChildComponentElement;
         'pc-layoutgroup': LayoutGroupComponentElement;
         'pc-light': LightComponentElement;
@@ -75,5 +78,7 @@ declare global {
         'pc-sounds': SoundComponentElement;
     }
 }
-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 { AsyncElement, ModuleElement, AppElement, EntityElement, AssetElement, ButtonComponentElement, CameraComponentElement, CollisionComponentElement, ComponentElement, ElementComponentElement, JointComponentElement, 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

@@ -17,6 +17,7 @@ import { CameraComponentElement } from './components/camera-component.js';
 import { CollisionComponentElement } from './components/collision-component.js';
 import { ComponentElement } from './components/component.js';
 import { ElementComponentElement } from './components/element-component.js';
+import { JointComponentElement } from './components/joint-component.js';
 import { LayoutChildComponentElement } from './components/layoutchild-component.js';
 import { LayoutGroupComponentElement } from './components/layoutgroup-component.js';
 import { LightComponentElement } from './components/light-component.js';
@@ -40,6 +41,7 @@ import { SkyElement } from './sky.js';
 import type { ScriptAttributesChangeEvent, ScriptEnableChangeEvent, ScriptNameChangeEvent } from './components/script-component.js';
 declare global {
     interface HTMLElementEventMap {
+        break: CustomEvent;
         scriptattributeschange: ScriptAttributesChangeEvent;
         scriptenablechange: ScriptEnableChangeEvent;
         scriptnamechange: ScriptNameChangeEvent;
@@ -53,6 +55,7 @@ declare global {
         'pc-element': ElementComponentElement;
         'pc-entity': EntityElement;
         'pc-gsplat': GSplatComponentElement;
+        'pc-joint': JointComponentElement;
         'pc-layoutchild': LayoutChildComponentElement;
         'pc-layoutgroup': LayoutGroupComponentElement;
         'pc-light': LightComponentElement;
@@ -75,5 +78,7 @@ declare global {
         'pc-sounds': SoundComponentElement;
     }
 }
-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 { AsyncElement, ModuleElement, AppElement, EntityElement, AssetElement, ButtonComponentElement, CameraComponentElement, CollisionComponentElement, ComponentElement, ElementComponentElement, JointComponentElement, 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 };

package/dist/node.d.ts

@@ -7,6 +7,13 @@ import { EntityBaseElement } from './entity-base.js';
  * 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 };