@playcanvas/web-components 0.13.1 → 0.15.0

package/dist/pwc.mjs

@@ -182,6 +182,7 @@ const REMOVAL_DELAY_MS = 250;
  * All styling is inline, so the library injects no stylesheet. The colors and height resolve CSS
  * custom properties — `--pc-loading-bar-color`, `--pc-loading-bar-background` and
  * `--pc-loading-bar-height` — so a page can theme the bar from `pc-app` or `:root`.
+ * @internal
  */
 class LoadingBar {
     _track;
@@ -280,6 +281,11 @@ class LoadingBar {
     }
 }
 
+/**
+ * The CSS color keywords, lowercase name to hex value. Read by `parseColor` to accept color
+ * names as attribute values.
+ * @internal
+ */
 const CSS_COLORS = {
     aliceblue: '#f0f8ff',
     antiquewhite: '#faebd7',
@@ -455,7 +461,7 @@ const CSS_COLORS = {
  * @param value - The value to split.
  * @param count - The required number of components.
  * @returns The parsed components, or `null`.
- * @ignore
+ * @internal
  */
 const parseComponents = (value, count) => {
     const components = value.trim().split(/\s+/).map(Number);
@@ -486,6 +492,7 @@ const cloneDefault = (value) => {
  * @param value - The attribute value to parse (`null` when the attribute is absent).
  * @param defaultValue - The value to use when the attribute is absent or removed.
  * @returns The parsed boolean.
+ * @internal
  */
 const parseBool = (value, defaultValue) => {
     return value === null ? defaultValue : value !== 'false';
@@ -501,6 +508,7 @@ const parseBool = (value, defaultValue) => {
  * @param defaultValue - The value to use when the attribute is absent or invalid.
  * @param attribute - The attribute name, used in the warning message.
  * @returns The parsed Color object.
+ * @internal
  */
 const parseColor = (value, defaultValue, attribute) => {
     if (value === null) {
@@ -542,6 +550,7 @@ const parseColor = (value, defaultValue, attribute) => {
  * @param defaultValue - The value to use when the attribute is absent or invalid.
  * @param attribute - The attribute name, used in the warning message.
  * @returns The resolved enum name.
+ * @internal
  */
 const parseEnum = (value, valid, defaultValue, attribute) => {
     if (value === null) {
@@ -563,6 +572,7 @@ const parseEnum = (value, valid, defaultValue, attribute) => {
  * @param defaultValue - The value to use when the attribute is absent or invalid.
  * @param attribute - The attribute name, used in the warning message.
  * @returns The parsed number.
+ * @internal
  */
 const parseNumber = (value, defaultValue, attribute) => {
     if (value === null) {
@@ -585,6 +595,7 @@ const parseNumber = (value, defaultValue, attribute) => {
  * @param defaultValue - The value to use when the attribute is absent or invalid.
  * @param attribute - The attribute name, used in the warning message.
  * @returns The parsed Quat object.
+ * @internal
  */
 const parseQuat = (value, defaultValue, attribute) => {
     if (value === null) {
@@ -608,6 +619,7 @@ const parseQuat = (value, defaultValue, attribute) => {
  * @param value - The attribute value to parse (`null` when the attribute is absent).
  * @param defaultValue - The value to use when the attribute is absent or removed.
  * @returns The parsed tag names.
+ * @internal
  */
 const parseTags = (value, defaultValue = []) => {
     if (value === null) {
@@ -629,6 +641,7 @@ const parseTags = (value, defaultValue = []) => {
  * @param defaultValue - The value to use when the attribute is absent or invalid.
  * @param attribute - The attribute name, used in the warning message.
  * @returns The parsed Vec2 object.
+ * @internal
  */
 const parseVec2 = (value, defaultValue, attribute) => {
     if (value === null) {
@@ -650,6 +663,7 @@ const parseVec2 = (value, defaultValue, attribute) => {
  * @param defaultValue - The value to use when the attribute is absent or invalid.
  * @param attribute - The attribute name, used in the warning message.
  * @returns The parsed Vec3 object.
+ * @internal
  */
 const parseVec3 = (value, defaultValue, attribute) => {
     if (value === null) {
@@ -671,6 +685,7 @@ const parseVec3 = (value, defaultValue, attribute) => {
  * @param defaultValue - The value to use when the attribute is absent or invalid.
  * @param attribute - The attribute name, used in the warning message.
  * @returns The parsed Vec4 object.
+ * @internal
  */
 const parseVec4 = (value, defaultValue, attribute) => {
     if (value === null) {
@@ -690,6 +705,7 @@ const parseVec4 = (value, defaultValue, attribute) => {
  *
  * @param ref - The reference string to resolve.
  * @returns The resolved entity, or `null`.
+ * @internal
  */
 const getEntity = (ref) => {
     if (!ref) {
@@ -859,6 +875,23 @@ class AppElement extends AsyncElement {
         if (this._loadingBar && !this._bar) {
             this._bar = new LoadingBar(this);
         }
+        // Upgrade the subtree before reading anything out of it. A subtree cloned from a
+        // <template> arrives entirely unupgraded - template content lives in an inert document,
+        // where custom element definitions are never looked up - and appending the clone upgrades
+        // its elements in tree order, this one before its descendants. The module query below would
+        // otherwise find plain HTMLElements with no _getLoadPromise to call, and the boot would die
+        // there, leaving the element permanently unready: no canvas, no entities, no application.
+        //
+        // Upgrading is the fix here rather than skipping whatever has not upgraded, because a
+        // <pc-module> is the one child that nothing else ever builds on its own behalf - skipping
+        // it would drop the wasm module the app asked for, silently and only for cloned apps.
+        // Upgrading runs each descendant's connectedCallback synchronously, a few lines earlier
+        // than the parser's path runs them but into the same state they see there: no application
+        // yet and _hierarchyReady false, so they defer to the sweeps below. A descendant that
+        // disconnects this element from there is caught by the generation check after the await,
+        // as any other disconnect is. An already-upgraded subtree - every other insertion path -
+        // is left completely untouched.
+        customElements.upgrade(this);
         // Get all pc-module elements that are direct children of the pc-app element
         const moduleElements = this.querySelectorAll(':scope > pc-module');
         // Wait for all modules to load
@@ -1594,7 +1627,7 @@ customElements.define('pc-app', AppElement);
 /**
  * The attribute names of the inline `onpointer*` event handlers, shared by every element that
  * fronts an engine entity. Spread into `observedAttributes` by subclasses.
- * @ignore
+ * @internal
  */
 const POINTER_ATTRIBUTES = [
     'onpointerenter',
@@ -1710,6 +1743,30 @@ class EntityBaseElement extends AsyncElement {
     }
 }
 
+/**
+ * Creates and parents the entities of every descendant `<pc-entity>` of `root`, in two passes so
+ * that no parent's existence depends on document order. Called wherever a subtree could not build
+ * itself: an element inserted into an application that is already running, and a `<pc-node>` whose
+ * children waited for it to bind.
+ *
+ * Descendants that are not yet custom elements are skipped, because there is nothing useful to do
+ * for them and reaching for `_createEntity` would throw. A subtree cloned from a `<template>`
+ * arrives entirely unupgraded — template content lives in an inert document, where custom element
+ * definitions are never looked up — and appending the clone upgrades its elements in tree order,
+ * an element before its descendants. So a sweep from an element's own `connectedCallback` sees
+ * plain `HTMLElement`s below it. Each becomes an `EntityElement` moments later and its own
+ * `connectedCallback` creates and parents it, by which time the ancestor it parents under has its
+ * entity — the same guarantee tree order gives this sweep.
+ *
+ * @param root - The element whose descendant entities to build.
+ * @param app - The application to create the entities in.
+ * @internal
+ */
+const buildDescendantEntities = (root, app) => {
+    const children = Array.from(root.querySelectorAll('pc-entity')).filter((child) => child instanceof EntityElement);
+    children.forEach((child) => child._createEntity(app));
+    children.forEach((child) => child._buildHierarchy(app));
+};
 /**
  * The EntityElement interface provides properties and methods for manipulating
  * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-entity/ | `<pc-entity>`} elements.
@@ -1858,13 +1915,7 @@ class EntityElement extends EntityBaseElement {
             this._createEntity(app);
             this._buildHierarchy(app);
             // Handle any child entities that might exist
-            const childEntities = this.querySelectorAll('pc-entity');
-            childEntities.forEach((child) => {
-                child._createEntity(app);
-            });
-            childEntities.forEach((child) => {
-                child._buildHierarchy(app);
-            });
+            buildDescendantEntities(this, app);
         }
     }
     disconnectedCallback() {
@@ -4637,219 +4688,1092 @@ class ElementComponentElement extends ComponentElement {
     set width(value) {
         this._width = value;
         if (this.component) {
-            this.component.width = value;
+            this.component.width = value;
+        }
+    }
+    /**
+     * Gets the width of the element component.
+     * @returns The width.
+     */
+    get width() {
+        return this._width;
+    }
+    /**
+     * Sets whether the element component should wrap lines.
+     * @param value - Whether to wrap lines.
+     */
+    set wrapLines(value) {
+        this._wrapLines = value;
+        if (this.component) {
+            this.component.wrapLines = value;
+        }
+    }
+    /**
+     * Gets whether the element component should wrap lines.
+     * @returns Whether to wrap lines.
+     */
+    get wrapLines() {
+        return this._wrapLines;
+    }
+    /**
+     * Sets whether a text element should automatically reduce its font size (down to `min-font-size`)
+     * so the text fits within the element's width. Requires `auto-width` to be `false`.
+     * @param value - Whether to auto-fit the width.
+     */
+    set autoFitWidth(value) {
+        this._autoFitWidth = value;
+        if (this.component) {
+            this.component.autoFitWidth = value;
+        }
+    }
+    /**
+     * Gets whether a text element automatically reduces its font size to fit its width.
+     * @returns Whether the width is auto-fit.
+     */
+    get autoFitWidth() {
+        return this._autoFitWidth;
+    }
+    /**
+     * Sets whether a text element should automatically reduce its font size (down to `min-font-size`)
+     * so the text fits within the element's height. Requires `auto-height` to be `false`.
+     * @param value - Whether to auto-fit the height.
+     */
+    set autoFitHeight(value) {
+        this._autoFitHeight = value;
+        if (this.component) {
+            this.component.autoFitHeight = value;
+        }
+    }
+    /**
+     * Gets whether a text element automatically reduces its font size to fit its height.
+     * @returns Whether the height is auto-fit.
+     */
+    get autoFitHeight() {
+        return this._autoFitHeight;
+    }
+    /**
+     * Sets the smallest font size a text element may use when auto-fitting.
+     * @param value - The minimum font size.
+     */
+    set minFontSize(value) {
+        this._minFontSize = value;
+        if (this.component) {
+            this.component.minFontSize = value;
+        }
+    }
+    /**
+     * Gets the smallest font size a text element may use when auto-fitting.
+     * @returns The minimum font size.
+     */
+    get minFontSize() {
+        return this._minFontSize;
+    }
+    /**
+     * Sets the largest font size a text element may use when auto-fitting.
+     * @param value - The maximum font size.
+     */
+    set maxFontSize(value) {
+        this._maxFontSize = value;
+        if (this.component) {
+            this.component.maxFontSize = value;
+        }
+    }
+    /**
+     * Gets the largest font size a text element may use when auto-fitting.
+     * @returns The maximum font size.
+     */
+    get maxFontSize() {
+        return this._maxFontSize;
+    }
+    static get observedAttributes() {
+        return [
+            ...super.observedAttributes,
+            'anchor',
+            'auto-width',
+            'auto-height',
+            'auto-fit-width',
+            'auto-fit-height',
+            'color',
+            'enable-markup',
+            'font-asset',
+            'font-size',
+            'max-font-size',
+            'min-font-size',
+            'height',
+            'line-height',
+            'margin',
+            'mask',
+            'opacity',
+            'pivot',
+            'pixels-per-unit',
+            'sprite-asset',
+            'sprite-frame',
+            'text',
+            'texture-asset',
+            'type',
+            'use-input',
+            'width',
+            'wrap-lines'
+        ];
+    }
+    attributeChangedCallback(name, _oldValue, newValue) {
+        super.attributeChangedCallback(name, _oldValue, newValue);
+        switch (name) {
+            case 'anchor':
+                this.anchor = parseVec4(newValue, new Vec4(0.5, 0.5, 0.5, 0.5), name);
+                break;
+            case 'auto-width':
+                this.autoWidth = parseBool(newValue, true);
+                break;
+            case 'auto-height':
+                this.autoHeight = parseBool(newValue, true);
+                break;
+            case 'auto-fit-width':
+                this.autoFitWidth = parseBool(newValue, false);
+                break;
+            case 'auto-fit-height':
+                this.autoFitHeight = parseBool(newValue, false);
+                break;
+            case 'color':
+                this.color = parseColor(newValue, Color.WHITE, name);
+                break;
+            case 'enable-markup':
+                this.enableMarkup = parseBool(newValue, false);
+                break;
+            case 'font-asset':
+                this.fontAsset = newValue ?? '';
+                break;
+            case 'font-size':
+                this.fontSize = parseNumber(newValue, 32, name);
+                break;
+            case 'max-font-size':
+                this.maxFontSize = parseNumber(newValue, 32, name);
+                break;
+            case 'min-font-size':
+                this.minFontSize = parseNumber(newValue, 8, name);
+                break;
+            case 'height':
+                this.height = parseNumber(newValue, 0, name);
+                break;
+            case 'line-height':
+                this.lineHeight = parseNumber(newValue, 32, name);
+                break;
+            case 'margin':
+                this.margin = parseVec4(newValue, null, name);
+                break;
+            case 'mask':
+                this.mask = parseBool(newValue, false);
+                break;
+            case 'opacity':
+                this.opacity = parseNumber(newValue, 1, name);
+                break;
+            case 'pivot':
+                this.pivot = parseVec2(newValue, new Vec2(0.5, 0.5), name);
+                break;
+            case 'pixels-per-unit':
+                this.pixelsPerUnit = parseNumber(newValue, null, name);
+                break;
+            case 'sprite-asset':
+                this.spriteAsset = newValue ?? '';
+                break;
+            case 'sprite-frame':
+                this.spriteFrame = parseNumber(newValue, 0, name);
+                break;
+            case 'text':
+                this.text = newValue ?? '';
+                break;
+            case 'texture-asset':
+                this.textureAsset = newValue ?? '';
+                break;
+            case 'type':
+                this.type = parseEnum(newValue, ['group', 'image', 'text'], 'group', name);
+                break;
+            case 'use-input':
+                this.useInput = parseBool(newValue, false);
+                break;
+            case 'width':
+                this.width = parseNumber(newValue, 0, name);
+                break;
+            case 'wrap-lines':
+                this.wrapLines = parseBool(newValue, false);
+                break;
+        }
+    }
+}
+customElements.define('pc-element', ElementComponentElement);
+
+/**
+ * The JointComponentElement interface provides properties and methods for manipulating
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-joint/ | `<pc-joint>`} elements.
+ * The JointComponentElement interface also inherits the properties and methods of the
+ * {@link HTMLElement} interface.
+ *
+ * The entity holding the joint is not itself constrained. Its world transform defines the joint
+ * frame — the anchor point and axes the constraint operates about — with the local X axis as the
+ * primary axis: a hinge rotates about it, a slider translates along it and a ball joint twists
+ * about it. The constrained bodies are referenced by `entity-a` and `entity-b`, both of which need
+ * a rigid body component; leaving `entity-b` empty constrains `entity-a` to a fixed point in world
+ * space. The underlying engine component is in alpha, so its API may change.
+ *
+ * @fires {CustomEvent} break - Fired when the impulse on the joint exceeds `break-impulse` and the
+ * constraint breaks. A broken joint no longer constrains its bodies; calling `refreshFrames()` on
+ * the underlying component re-attaches it. Bubbles and is composed.
+ *
+ * @category Components
+ */
+class JointComponentElement extends ComponentElement {
+    /**
+     * The spring damping of the joint per angular axis.
+     */
+    _angularDamping = new Vec3(1, 1, 1);
+    /**
+     * The rest angle of the joint's angular springs.
+     */
+    _angularEquilibrium = new Vec3();
+    /**
+     * The rotation limits of the joint about its X axis.
+     */
+    _angularLimitsX = new Vec2();
+    /**
+     * The rotation limits of the joint about its Y axis.
+     */
+    _angularLimitsY = new Vec2();
+    /**
+     * The rotation limits of the joint about its Z axis.
+     */
+    _angularLimitsZ = new Vec2();
+    /**
+     * The rotational degree of freedom of the joint about its X axis.
+     */
+    _angularMotionX = 'locked';
+    /**
+     * The rotational degree of freedom of the joint about its Y axis.
+     */
+    _angularMotionY = 'locked';
+    /**
+     * The rotational degree of freedom of the joint about its Z axis.
+     */
+    _angularMotionZ = 'locked';
+    /**
+     * The spring stiffness of the joint per angular axis.
+     */
+    _angularStiffness = new Vec3();
+    /**
+     * The impulse above which the joint breaks.
+     */
+    _breakImpulse = Infinity;
+    /**
+     * Whether collision is enabled between the constrained bodies.
+     */
+    _enableCollision = false;
+    /**
+     * Whether the joint's limits are enforced.
+     */
+    _enableLimits = false;
+    /**
+     * The reference to the entity providing the first constrained body.
+     */
+    _entityA = '';
+    /**
+     * The reference to the entity providing the second constrained body.
+     */
+    _entityB = '';
+    /**
+     * The rotation or travel limits of the joint.
+     */
+    _limits = new Vec2(-45, 45);
+    /**
+     * The spring damping of the joint per linear axis.
+     */
+    _linearDamping = new Vec3(1, 1, 1);
+    /**
+     * The rest point of the joint's linear springs.
+     */
+    _linearEquilibrium = new Vec3();
+    /**
+     * The translation limits of the joint along its X axis.
+     */
+    _linearLimitsX = new Vec2();
+    /**
+     * The translation limits of the joint along its Y axis.
+     */
+    _linearLimitsY = new Vec2();
+    /**
+     * The translation limits of the joint along its Z axis.
+     */
+    _linearLimitsZ = new Vec2();
+    /**
+     * The linear degree of freedom of the joint along its X axis.
+     */
+    _linearMotionX = 'locked';
+    /**
+     * The linear degree of freedom of the joint along its Y axis.
+     */
+    _linearMotionY = 'locked';
+    /**
+     * The linear degree of freedom of the joint along its Z axis.
+     */
+    _linearMotionZ = 'locked';
+    /**
+     * The spring stiffness of the joint per linear axis.
+     */
+    _linearStiffness = new Vec3();
+    /**
+     * The maximum torque or force of the joint's motor.
+     */
+    _maxMotorForce = 0;
+    /**
+     * The target speed of the joint's motor.
+     */
+    _motorSpeed = 0;
+    /**
+     * The maximum swing of the joint around the joint frame's Y axis.
+     */
+    _swingLimitY = 45;
+    /**
+     * The maximum swing of the joint around the joint frame's Z axis.
+     */
+    _swingLimitZ = 45;
+    /**
+     * The maximum twist of the joint about its primary axis.
+     */
+    _twistLimit = 20;
+    /**
+     * The type of the joint.
+     */
+    _type = 'fixed';
+    /** @ignore */
+    constructor() {
+        super('joint');
+    }
+    getInitialComponentData() {
+        return {
+            angularDamping: this._angularDamping,
+            angularEquilibrium: this._angularEquilibrium,
+            angularLimitsX: this._angularLimitsX,
+            angularLimitsY: this._angularLimitsY,
+            angularLimitsZ: this._angularLimitsZ,
+            angularMotionX: this._angularMotionX,
+            angularMotionY: this._angularMotionY,
+            angularMotionZ: this._angularMotionZ,
+            angularStiffness: this._angularStiffness,
+            breakImpulse: this._breakImpulse,
+            enableCollision: this._enableCollision,
+            enableLimits: this._enableLimits,
+            entityA: getEntity(this._entityA),
+            entityB: getEntity(this._entityB),
+            limits: this._limits,
+            linearDamping: this._linearDamping,
+            linearEquilibrium: this._linearEquilibrium,
+            linearLimitsX: this._linearLimitsX,
+            linearLimitsY: this._linearLimitsY,
+            linearLimitsZ: this._linearLimitsZ,
+            linearMotionX: this._linearMotionX,
+            linearMotionY: this._linearMotionY,
+            linearMotionZ: this._linearMotionZ,
+            linearStiffness: this._linearStiffness,
+            maxMotorForce: this._maxMotorForce,
+            motorSpeed: this._motorSpeed,
+            swingLimitY: this._swingLimitY,
+            swingLimitZ: this._swingLimitZ,
+            twistLimit: this._twistLimit,
+            type: this._type
+        };
+    }
+    _onBreak() {
+        this.dispatchEvent(new CustomEvent('break', { bubbles: true, composed: true }));
+    }
+    initComponent() {
+        const component = this.component;
+        if (!component) {
+            return;
+        }
+        // A host readiness cycle can re-run this against the same surviving component instance,
+        // so the off/on pair keeps the subscription single either way. Component removal destroys
+        // the instance and its listeners with it, so there is no disconnect-side teardown.
+        component.off('break', this._onBreak, this);
+        component.on('break', this._onBreak, this);
+    }
+    /**
+     * Gets the underlying PlayCanvas joint component.
+     * @returns The joint component.
+     */
+    get component() {
+        return super.component;
+    }
+    /**
+     * Sets the spring damping of a 6dof joint per angular axis, used on axes with a non-zero
+     * angular-stiffness.
+     * @param value - The angular spring damping.
+     */
+    set angularDamping(value) {
+        this._angularDamping = value;
+        if (this.component) {
+            this.component.angularDamping = value;
+        }
+    }
+    /**
+     * Gets the spring damping of the joint per angular axis.
+     * @returns The angular spring damping.
+     */
+    get angularDamping() {
+        return this._angularDamping;
+    }
+    /**
+     * Sets the rest angle of a 6dof joint's angular springs in degrees per axis, used on axes with
+     * a non-zero angular-stiffness.
+     * @param value - The angular spring rest angles.
+     */
+    set angularEquilibrium(value) {
+        this._angularEquilibrium = value;
+        if (this.component) {
+            this.component.angularEquilibrium = value;
+        }
+    }
+    /**
+     * Gets the rest angle of the joint's angular springs.
+     * @returns The angular spring rest angles.
+     */
+    get angularEquilibrium() {
+        return this._angularEquilibrium;
+    }
+    /**
+     * Sets the lower and upper rotation limit of a 6dof joint about its X axis in degrees, used
+     * when angular-motion-x is limited.
+     * @param value - The X axis rotation limits.
+     */
+    set angularLimitsX(value) {
+        this._angularLimitsX = value;
+        if (this.component) {
+            this.component.angularLimitsX = value;
+        }
+    }
+    /**
+     * Gets the rotation limits of the joint about its X axis.
+     * @returns The X axis rotation limits.
+     */
+    get angularLimitsX() {
+        return this._angularLimitsX;
+    }
+    /**
+     * Sets the lower and upper rotation limit of a 6dof joint about its Y axis in degrees, used
+     * when angular-motion-y is limited.
+     * @param value - The Y axis rotation limits.
+     */
+    set angularLimitsY(value) {
+        this._angularLimitsY = value;
+        if (this.component) {
+            this.component.angularLimitsY = value;
+        }
+    }
+    /**
+     * Gets the rotation limits of the joint about its Y axis.
+     * @returns The Y axis rotation limits.
+     */
+    get angularLimitsY() {
+        return this._angularLimitsY;
+    }
+    /**
+     * Sets the lower and upper rotation limit of a 6dof joint about its Z axis in degrees, used
+     * when angular-motion-z is limited.
+     * @param value - The Z axis rotation limits.
+     */
+    set angularLimitsZ(value) {
+        this._angularLimitsZ = value;
+        if (this.component) {
+            this.component.angularLimitsZ = value;
+        }
+    }
+    /**
+     * Gets the rotation limits of the joint about its Z axis.
+     * @returns The Z axis rotation limits.
+     */
+    get angularLimitsZ() {
+        return this._angularLimitsZ;
+    }
+    /**
+     * Sets how a 6dof joint constrains rotation about its X axis. Can be `locked`, `limited` or
+     * `free`. Defaults to `locked`.
+     * @param value - The X axis rotational degree of freedom.
+     */
+    set angularMotionX(value) {
+        this._angularMotionX = value;
+        if (this.component) {
+            this.component.angularMotionX = value;
+        }
+    }
+    /**
+     * Gets how the joint constrains rotation about its X axis.
+     * @returns The X axis rotational degree of freedom.
+     */
+    get angularMotionX() {
+        return this._angularMotionX;
+    }
+    /**
+     * Sets how a 6dof joint constrains rotation about its Y axis. Can be `locked`, `limited` or
+     * `free`. Defaults to `locked`.
+     * @param value - The Y axis rotational degree of freedom.
+     */
+    set angularMotionY(value) {
+        this._angularMotionY = value;
+        if (this.component) {
+            this.component.angularMotionY = value;
+        }
+    }
+    /**
+     * Gets how the joint constrains rotation about its Y axis.
+     * @returns The Y axis rotational degree of freedom.
+     */
+    get angularMotionY() {
+        return this._angularMotionY;
+    }
+    /**
+     * Sets how a 6dof joint constrains rotation about its Z axis. Can be `locked`, `limited` or
+     * `free`. Defaults to `locked`.
+     * @param value - The Z axis rotational degree of freedom.
+     */
+    set angularMotionZ(value) {
+        this._angularMotionZ = value;
+        if (this.component) {
+            this.component.angularMotionZ = value;
+        }
+    }
+    /**
+     * Gets how the joint constrains rotation about its Z axis.
+     * @returns The Z axis rotational degree of freedom.
+     */
+    get angularMotionZ() {
+        return this._angularMotionZ;
+    }
+    /**
+     * Sets the spring stiffness of a 6dof joint per angular axis, where 0 disables the spring on
+     * that axis.
+     * @param value - The angular spring stiffness.
+     */
+    set angularStiffness(value) {
+        this._angularStiffness = value;
+        if (this.component) {
+            this.component.angularStiffness = value;
+        }
+    }
+    /**
+     * Gets the spring stiffness of the joint per angular axis.
+     * @returns The angular spring stiffness.
+     */
+    get angularStiffness() {
+        return this._angularStiffness;
+    }
+    /**
+     * Sets the impulse in newton seconds above which the joint breaks. Defaults to `Infinity`,
+     * which makes the joint unbreakable.
+     * @param value - The break impulse.
+     */
+    set breakImpulse(value) {
+        this._breakImpulse = value;
+        if (this.component) {
+            this.component.breakImpulse = value;
+        }
+    }
+    /**
+     * Gets the impulse above which the joint breaks.
+     * @returns The break impulse.
+     */
+    get breakImpulse() {
+        return this._breakImpulse;
+    }
+    /**
+     * Sets whether collision is enabled between the two constrained bodies.
+     * @param value - Whether collision is enabled.
+     */
+    set enableCollision(value) {
+        this._enableCollision = value;
+        if (this.component) {
+            this.component.enableCollision = value;
+        }
+    }
+    /**
+     * Gets whether collision is enabled between the two constrained bodies.
+     * @returns Whether collision is enabled.
+     */
+    get enableCollision() {
+        return this._enableCollision;
+    }
+    /**
+     * Sets whether the limits of a hinge, slider or ball joint are enforced.
+     * @param value - Whether the limits are enforced.
+     */
+    set enableLimits(value) {
+        this._enableLimits = value;
+        if (this.component) {
+            this.component.enableLimits = value;
+        }
+    }
+    /**
+     * Gets whether the limits of the joint are enforced.
+     * @returns Whether the limits are enforced.
+     */
+    get enableLimits() {
+        return this._enableLimits;
+    }
+    /**
+     * Sets the reference (CSS selector, element id or entity name) to the `<pc-entity>` providing
+     * the first constrained body. The reference resolves when it is set, so an entity created
+     * later is picked up by setting the attribute again.
+     * @param value - The first body's entity reference.
+     */
+    set entityA(value) {
+        this._entityA = value;
+        if (this.component) {
+            this.component.entityA = getEntity(value);
+        }
+    }
+    /**
+     * Gets the reference to the `<pc-entity>` providing the first constrained body.
+     * @returns The first body's entity reference.
+     */
+    get entityA() {
+        return this._entityA;
+    }
+    /**
+     * Sets the reference (CSS selector, element id or entity name) to the `<pc-entity>` providing
+     * the second constrained body, or empty to constrain the first body to a fixed point in world
+     * space. The reference resolves when it is set, so an entity created later is picked up by
+     * setting the attribute again.
+     * @param value - The second body's entity reference.
+     */
+    set entityB(value) {
+        this._entityB = value;
+        if (this.component) {
+            this.component.entityB = getEntity(value);
+        }
+    }
+    /**
+     * Gets the reference to the `<pc-entity>` providing the second constrained body.
+     * @returns The second body's entity reference.
+     */
+    get entityB() {
+        return this._entityB;
+    }
+    /**
+     * Sets the lower and upper limit of a hinge joint's rotation in degrees, or a slider joint's
+     * travel in meters, applied when enable-limits is set.
+     * @param value - The rotation or travel limits.
+     */
+    set limits(value) {
+        this._limits = value;
+        if (this.component) {
+            this.component.limits = value;
+        }
+    }
+    /**
+     * Gets the rotation or travel limits of the joint.
+     * @returns The rotation or travel limits.
+     */
+    get limits() {
+        return this._limits;
+    }
+    /**
+     * Sets the spring damping of a 6dof joint per linear axis, used on axes with a non-zero
+     * linear-stiffness.
+     * @param value - The linear spring damping.
+     */
+    set linearDamping(value) {
+        this._linearDamping = value;
+        if (this.component) {
+            this.component.linearDamping = value;
+        }
+    }
+    /**
+     * Gets the spring damping of the joint per linear axis.
+     * @returns The linear spring damping.
+     */
+    get linearDamping() {
+        return this._linearDamping;
+    }
+    /**
+     * Sets the rest point of a 6dof joint's linear springs in meters per axis, used on axes with a
+     * non-zero linear-stiffness.
+     * @param value - The linear spring rest points.
+     */
+    set linearEquilibrium(value) {
+        this._linearEquilibrium = value;
+        if (this.component) {
+            this.component.linearEquilibrium = value;
+        }
+    }
+    /**
+     * Gets the rest point of the joint's linear springs.
+     * @returns The linear spring rest points.
+     */
+    get linearEquilibrium() {
+        return this._linearEquilibrium;
+    }
+    /**
+     * Sets the lower and upper translation limit of a 6dof joint along its X axis in meters, used
+     * when linear-motion-x is limited.
+     * @param value - The X axis translation limits.
+     */
+    set linearLimitsX(value) {
+        this._linearLimitsX = value;
+        if (this.component) {
+            this.component.linearLimitsX = value;
+        }
+    }
+    /**
+     * Gets the translation limits of the joint along its X axis.
+     * @returns The X axis translation limits.
+     */
+    get linearLimitsX() {
+        return this._linearLimitsX;
+    }
+    /**
+     * Sets the lower and upper translation limit of a 6dof joint along its Y axis in meters, used
+     * when linear-motion-y is limited.
+     * @param value - The Y axis translation limits.
+     */
+    set linearLimitsY(value) {
+        this._linearLimitsY = value;
+        if (this.component) {
+            this.component.linearLimitsY = value;
+        }
+    }
+    /**
+     * Gets the translation limits of the joint along its Y axis.
+     * @returns The Y axis translation limits.
+     */
+    get linearLimitsY() {
+        return this._linearLimitsY;
+    }
+    /**
+     * Sets the lower and upper translation limit of a 6dof joint along its Z axis in meters, used
+     * when linear-motion-z is limited.
+     * @param value - The Z axis translation limits.
+     */
+    set linearLimitsZ(value) {
+        this._linearLimitsZ = value;
+        if (this.component) {
+            this.component.linearLimitsZ = value;
+        }
+    }
+    /**
+     * Gets the translation limits of the joint along its Z axis.
+     * @returns The Z axis translation limits.
+     */
+    get linearLimitsZ() {
+        return this._linearLimitsZ;
+    }
+    /**
+     * Sets how a 6dof joint constrains translation along its X axis. Can be `locked`, `limited` or
+     * `free`. Defaults to `locked`.
+     * @param value - The X axis linear degree of freedom.
+     */
+    set linearMotionX(value) {
+        this._linearMotionX = value;
+        if (this.component) {
+            this.component.linearMotionX = value;
+        }
+    }
+    /**
+     * Gets how the joint constrains translation along its X axis.
+     * @returns The X axis linear degree of freedom.
+     */
+    get linearMotionX() {
+        return this._linearMotionX;
+    }
+    /**
+     * Sets how a 6dof joint constrains translation along its Y axis. Can be `locked`, `limited` or
+     * `free`. Defaults to `locked`.
+     * @param value - The Y axis linear degree of freedom.
+     */
+    set linearMotionY(value) {
+        this._linearMotionY = value;
+        if (this.component) {
+            this.component.linearMotionY = value;
+        }
+    }
+    /**
+     * Gets how the joint constrains translation along its Y axis.
+     * @returns The Y axis linear degree of freedom.
+     */
+    get linearMotionY() {
+        return this._linearMotionY;
+    }
+    /**
+     * Sets how a 6dof joint constrains translation along its Z axis. Can be `locked`, `limited` or
+     * `free`. Defaults to `locked`.
+     * @param value - The Z axis linear degree of freedom.
+     */
+    set linearMotionZ(value) {
+        this._linearMotionZ = value;
+        if (this.component) {
+            this.component.linearMotionZ = value;
+        }
+    }
+    /**
+     * Gets how the joint constrains translation along its Z axis.
+     * @returns The Z axis linear degree of freedom.
+     */
+    get linearMotionZ() {
+        return this._linearMotionZ;
+    }
+    /**
+     * Sets the spring stiffness of a 6dof joint per linear axis, where 0 disables the spring on
+     * that axis.
+     * @param value - The linear spring stiffness.
+     */
+    set linearStiffness(value) {
+        this._linearStiffness = value;
+        if (this.component) {
+            this.component.linearStiffness = value;
+        }
+    }
+    /**
+     * Gets the spring stiffness of the joint per linear axis.
+     * @returns The linear spring stiffness.
+     */
+    get linearStiffness() {
+        return this._linearStiffness;
+    }
+    /**
+     * Sets the maximum torque in newton meters of a hinge joint's motor, or the maximum force in
+     * newtons of a slider joint's motor, where 0 disables the motor.
+     * @param value - The maximum motor torque or force.
+     */
+    set maxMotorForce(value) {
+        this._maxMotorForce = value;
+        if (this.component) {
+            this.component.maxMotorForce = value;
         }
     }
     /**
-     * Gets the width of the element component.
-     * @returns The width.
+     * Gets the maximum torque or force of the joint's motor.
+     * @returns The maximum motor torque or force.
      */
-    get width() {
-        return this._width;
+    get maxMotorForce() {
+        return this._maxMotorForce;
     }
     /**
-     * Sets whether the element component should wrap lines.
-     * @param value - Whether to wrap lines.
+     * Sets the target speed of a hinge joint's motor in degrees per second, or a slider joint's
+     * motor in meters per second, active while max-motor-force is greater than 0.
+     * @param value - The motor's target speed.
      */
-    set wrapLines(value) {
-        this._wrapLines = value;
+    set motorSpeed(value) {
+        this._motorSpeed = value;
         if (this.component) {
-            this.component.wrapLines = value;
+            this.component.motorSpeed = value;
         }
     }
     /**
-     * Gets whether the element component should wrap lines.
-     * @returns Whether to wrap lines.
+     * Gets the target speed of the joint's motor.
+     * @returns The motor's target speed.
      */
-    get wrapLines() {
-        return this._wrapLines;
+    get motorSpeed() {
+        return this._motorSpeed;
     }
     /**
-     * Sets whether a text element should automatically reduce its font size (down to `min-font-size`)
-     * so the text fits within the element's width. Requires `auto-width` to be `false`.
-     * @param value - Whether to auto-fit the width.
+     * Sets the maximum swing of a ball joint around the joint frame's Y axis in degrees, applied
+     * when enable-limits is set.
+     * @param value - The Y axis swing limit.
      */
-    set autoFitWidth(value) {
-        this._autoFitWidth = value;
+    set swingLimitY(value) {
+        this._swingLimitY = value;
         if (this.component) {
-            this.component.autoFitWidth = value;
+            this.component.swingLimitY = value;
         }
     }
     /**
-     * Gets whether a text element automatically reduces its font size to fit its width.
-     * @returns Whether the width is auto-fit.
+     * Gets the maximum swing of the joint around the joint frame's Y axis.
+     * @returns The Y axis swing limit.
      */
-    get autoFitWidth() {
-        return this._autoFitWidth;
+    get swingLimitY() {
+        return this._swingLimitY;
     }
     /**
-     * Sets whether a text element should automatically reduce its font size (down to `min-font-size`)
-     * so the text fits within the element's height. Requires `auto-height` to be `false`.
-     * @param value - Whether to auto-fit the height.
+     * Sets the maximum swing of a ball joint around the joint frame's Z axis in degrees, applied
+     * when enable-limits is set.
+     * @param value - The Z axis swing limit.
      */
-    set autoFitHeight(value) {
-        this._autoFitHeight = value;
+    set swingLimitZ(value) {
+        this._swingLimitZ = value;
         if (this.component) {
-            this.component.autoFitHeight = value;
+            this.component.swingLimitZ = value;
         }
     }
     /**
-     * Gets whether a text element automatically reduces its font size to fit its height.
-     * @returns Whether the height is auto-fit.
+     * Gets the maximum swing of the joint around the joint frame's Z axis.
+     * @returns The Z axis swing limit.
      */
-    get autoFitHeight() {
-        return this._autoFitHeight;
+    get swingLimitZ() {
+        return this._swingLimitZ;
     }
     /**
-     * Sets the smallest font size a text element may use when auto-fitting.
-     * @param value - The minimum font size.
+     * Sets the maximum twist of a ball joint about its primary axis in degrees, applied when
+     * enable-limits is set.
+     * @param value - The twist limit.
      */
-    set minFontSize(value) {
-        this._minFontSize = value;
+    set twistLimit(value) {
+        this._twistLimit = value;
         if (this.component) {
-            this.component.minFontSize = value;
+            this.component.twistLimit = value;
         }
     }
     /**
-     * Gets the smallest font size a text element may use when auto-fitting.
-     * @returns The minimum font size.
+     * Gets the maximum twist of the joint about its primary axis.
+     * @returns The twist limit.
      */
-    get minFontSize() {
-        return this._minFontSize;
+    get twistLimit() {
+        return this._twistLimit;
     }
     /**
-     * Sets the largest font size a text element may use when auto-fitting.
-     * @param value - The maximum font size.
+     * Sets the type of the joint. Can be `fixed`, `ball`, `hinge`, `slider` or `6dof`. Defaults to
+     * `fixed`.
+     * @param value - The joint type.
      */
-    set maxFontSize(value) {
-        this._maxFontSize = value;
+    set type(value) {
+        this._type = value;
         if (this.component) {
-            this.component.maxFontSize = value;
+            this.component.type = value;
         }
     }
     /**
-     * Gets the largest font size a text element may use when auto-fitting.
-     * @returns The maximum font size.
+     * Gets the type of the joint.
+     * @returns The joint type.
      */
-    get maxFontSize() {
-        return this._maxFontSize;
+    get type() {
+        return this._type;
     }
     static get observedAttributes() {
         return [
             ...super.observedAttributes,
-            'anchor',
-            'auto-width',
-            'auto-height',
-            'auto-fit-width',
-            'auto-fit-height',
-            'color',
-            'enable-markup',
-            'font-asset',
-            'font-size',
-            'max-font-size',
-            'min-font-size',
-            'height',
-            'line-height',
-            'margin',
-            'mask',
-            'opacity',
-            'pivot',
-            'pixels-per-unit',
-            'sprite-asset',
-            'sprite-frame',
-            'text',
-            'texture-asset',
-            'type',
-            'use-input',
-            'width',
-            'wrap-lines'
+            'angular-damping',
+            'angular-equilibrium',
+            'angular-limits-x',
+            'angular-limits-y',
+            'angular-limits-z',
+            'angular-motion-x',
+            'angular-motion-y',
+            'angular-motion-z',
+            'angular-stiffness',
+            'break-impulse',
+            'enable-collision',
+            'enable-limits',
+            'entity-a',
+            'entity-b',
+            'limits',
+            'linear-damping',
+            'linear-equilibrium',
+            'linear-limits-x',
+            'linear-limits-y',
+            'linear-limits-z',
+            'linear-motion-x',
+            'linear-motion-y',
+            'linear-motion-z',
+            'linear-stiffness',
+            'max-motor-force',
+            'motor-speed',
+            'swing-limit-y',
+            'swing-limit-z',
+            'twist-limit',
+            'type'
         ];
     }
     attributeChangedCallback(name, _oldValue, newValue) {
         super.attributeChangedCallback(name, _oldValue, newValue);
         switch (name) {
-            case 'anchor':
-                this.anchor = parseVec4(newValue, new Vec4(0.5, 0.5, 0.5, 0.5), name);
+            case 'angular-damping':
+                this.angularDamping = parseVec3(newValue, Vec3.ONE, name);
                 break;
-            case 'auto-width':
-                this.autoWidth = parseBool(newValue, true);
+            case 'angular-equilibrium':
+                this.angularEquilibrium = parseVec3(newValue, Vec3.ZERO, name);
                 break;
-            case 'auto-height':
-                this.autoHeight = parseBool(newValue, true);
+            case 'angular-limits-x':
+                this.angularLimitsX = parseVec2(newValue, Vec2.ZERO, name);
                 break;
-            case 'auto-fit-width':
-                this.autoFitWidth = parseBool(newValue, false);
+            case 'angular-limits-y':
+                this.angularLimitsY = parseVec2(newValue, Vec2.ZERO, name);
                 break;
-            case 'auto-fit-height':
-                this.autoFitHeight = parseBool(newValue, false);
+            case 'angular-limits-z':
+                this.angularLimitsZ = parseVec2(newValue, Vec2.ZERO, name);
                 break;
-            case 'color':
-                this.color = parseColor(newValue, Color.WHITE, name);
+            case 'angular-motion-x':
+                this.angularMotionX = parseEnum(newValue, ['locked', 'limited', 'free'], 'locked', name);
                 break;
-            case 'enable-markup':
-                this.enableMarkup = parseBool(newValue, false);
+            case 'angular-motion-y':
+                this.angularMotionY = parseEnum(newValue, ['locked', 'limited', 'free'], 'locked', name);
                 break;
-            case 'font-asset':
-                this.fontAsset = newValue ?? '';
+            case 'angular-motion-z':
+                this.angularMotionZ = parseEnum(newValue, ['locked', 'limited', 'free'], 'locked', name);
                 break;
-            case 'font-size':
-                this.fontSize = parseNumber(newValue, 32, name);
+            case 'angular-stiffness':
+                this.angularStiffness = parseVec3(newValue, Vec3.ZERO, name);
                 break;
-            case 'max-font-size':
-                this.maxFontSize = parseNumber(newValue, 32, name);
+            case 'break-impulse':
+                this.breakImpulse = parseNumber(newValue, Infinity, name);
                 break;
-            case 'min-font-size':
-                this.minFontSize = parseNumber(newValue, 8, name);
+            case 'enable-collision':
+                this.enableCollision = parseBool(newValue, false);
                 break;
-            case 'height':
-                this.height = parseNumber(newValue, 0, name);
+            case 'enable-limits':
+                this.enableLimits = parseBool(newValue, false);
                 break;
-            case 'line-height':
-                this.lineHeight = parseNumber(newValue, 32, name);
+            case 'entity-a':
+                this.entityA = newValue ?? '';
                 break;
-            case 'margin':
-                this.margin = parseVec4(newValue, null, name);
+            case 'entity-b':
+                this.entityB = newValue ?? '';
                 break;
-            case 'mask':
-                this.mask = parseBool(newValue, false);
+            case 'limits':
+                this.limits = parseVec2(newValue, new Vec2(-45, 45), name);
                 break;
-            case 'opacity':
-                this.opacity = parseNumber(newValue, 1, name);
+            case 'linear-damping':
+                this.linearDamping = parseVec3(newValue, Vec3.ONE, name);
                 break;
-            case 'pivot':
-                this.pivot = parseVec2(newValue, new Vec2(0.5, 0.5), name);
+            case 'linear-equilibrium':
+                this.linearEquilibrium = parseVec3(newValue, Vec3.ZERO, name);
                 break;
-            case 'pixels-per-unit':
-                this.pixelsPerUnit = parseNumber(newValue, null, name);
+            case 'linear-limits-x':
+                this.linearLimitsX = parseVec2(newValue, Vec2.ZERO, name);
                 break;
-            case 'sprite-asset':
-                this.spriteAsset = newValue ?? '';
+            case 'linear-limits-y':
+                this.linearLimitsY = parseVec2(newValue, Vec2.ZERO, name);
                 break;
-            case 'sprite-frame':
-                this.spriteFrame = parseNumber(newValue, 0, name);
+            case 'linear-limits-z':
+                this.linearLimitsZ = parseVec2(newValue, Vec2.ZERO, name);
                 break;
-            case 'text':
-                this.text = newValue ?? '';
+            case 'linear-motion-x':
+                this.linearMotionX = parseEnum(newValue, ['locked', 'limited', 'free'], 'locked', name);
                 break;
-            case 'texture-asset':
-                this.textureAsset = newValue ?? '';
+            case 'linear-motion-y':
+                this.linearMotionY = parseEnum(newValue, ['locked', 'limited', 'free'], 'locked', name);
                 break;
-            case 'type':
-                this.type = parseEnum(newValue, ['group', 'image', 'text'], 'group', name);
+            case 'linear-motion-z':
+                this.linearMotionZ = parseEnum(newValue, ['locked', 'limited', 'free'], 'locked', name);
                 break;
-            case 'use-input':
-                this.useInput = parseBool(newValue, false);
+            case 'linear-stiffness':
+                this.linearStiffness = parseVec3(newValue, Vec3.ZERO, name);
                 break;
-            case 'width':
-                this.width = parseNumber(newValue, 0, name);
+            case 'max-motor-force':
+                this.maxMotorForce = parseNumber(newValue, 0, name);
                 break;
-            case 'wrap-lines':
-                this.wrapLines = parseBool(newValue, false);
+            case 'motor-speed':
+                this.motorSpeed = parseNumber(newValue, 0, name);
+                break;
+            case 'swing-limit-y':
+                this.swingLimitY = parseNumber(newValue, 45, name);
+                break;
+            case 'swing-limit-z':
+                this.swingLimitZ = parseNumber(newValue, 45, name);
+                break;
+            case 'twist-limit':
+                this.twistLimit = parseNumber(newValue, 20, name);
+                break;
+            case 'type':
+                this.type = parseEnum(newValue, ['fixed', 'ball', 'hinge', 'slider', '6dof'], 'fixed', name);
                 break;
         }
     }
 }
-customElements.define('pc-element', ElementComponentElement);
+customElements.define('pc-joint', JointComponentElement);
 
 /**
  * The LayoutChildComponentElement interface provides properties and methods for manipulating
@@ -6055,6 +6979,7 @@ class MaterialElement extends HTMLElement {
     _metalnessMapRotation = 0;
     _metalnessMapTiling = new Vec2(1, 1);
     _metalnessMapUv = 0;
+    _name = 'Untitled';
     _normalMap = '';
     _normalMapOffset = new Vec2(0, 0);
     _normalMapRotation = 0;
@@ -6172,6 +7097,7 @@ class MaterialElement extends HTMLElement {
         material.metalnessMapRotation = this._metalnessMapRotation;
         material.metalnessMapTiling = this._metalnessMapTiling;
         material.metalnessMapUv = this._metalnessMapUv;
+        material.name = this._name;
         material.normalMapOffset = this._normalMapOffset;
         material.normalMapRotation = this._normalMapRotation;
         material.normalMapTiling = this._normalMapTiling;
@@ -7258,6 +8184,26 @@ class MaterialElement extends HTMLElement {
     get metalnessMapUv() {
         return this._metalnessMapUv;
     }
+    /**
+     * Sets the name of the material.
+     * @param value - The material name.
+     */
+    set name(value) {
+        this._name = value;
+        if (this.material) {
+            // A label rather than shader state, so no update() is scheduled
+            this.material.name = value;
+        }
+    }
+    /**
+     * Gets the name of the material - the label shown wherever materials surface by name, such
+     * as profilers, GPU captures and the assignments `pc-model.hierarchy()` reports. Purely a
+     * label: element references resolve through `id`.
+     * @returns The material name.
+     */
+    get name() {
+        return this._name;
+    }
     /**
      * Sets the id of the `pc-asset` to use as the normal map.
      * @param value - The asset id.
@@ -7829,6 +8775,7 @@ class MaterialElement extends HTMLElement {
             'metalness-map-rotation',
             'metalness-map-tiling',
             'metalness-map-uv',
+            'name',
             'normal-map',
             'normal-map-offset',
             'normal-map-rotation',
@@ -8029,6 +8976,9 @@ class MaterialElement extends HTMLElement {
             case 'metalness-map-uv':
                 this.metalnessMapUv = parseNumber(newValue, 0, name);
                 break;
+            case 'name':
+                this.name = newValue ?? 'Untitled';
+                break;
             case 'normal-map':
                 this.normalMap = newValue ?? '';
                 break;
@@ -10574,6 +11524,41 @@ class GSplatComponentElement extends ComponentElement {
 }
 customElements.define('pc-gsplat', GSplatComponentElement);
 
+/**
+ * Formats one line of the printable hierarchy: the node's name, an `[index]` marker when the
+ * name is shared by several nodes in the model, the attached component types, and the material
+ * names of a render component.
+ *
+ * @param node - The node to format.
+ * @param counts - The number of nodes bearing each name.
+ * @returns The formatted line.
+ */
+const formatNode = (node, counts) => {
+    const index = (counts.get(node.name) ?? 0) > 1 ? ` [${node.index}]` : '';
+    const components = node.components.length > 0 ? ` (${node.components.join(', ')})` : '';
+    // Braces rather than brackets: `[N]` already means a match index on this line
+    const materials = node.materials.length > 0 ? ` {${node.materials.map((slot) => slot.name ?? 'null').join(', ')}}` : '';
+    return `${node.name}${index}${components}${materials}`;
+};
+/**
+ * Formats the printable form of a hierarchy subtree.
+ *
+ * @param root - The subtree root.
+ * @param counts - The number of nodes bearing each name.
+ * @returns The tree, one line per node.
+ */
+const formatHierarchy = (root, counts) => {
+    const lines = [formatNode(root, counts)];
+    const walk = (node, prefix) => {
+        node.children.forEach((child, i) => {
+            const last = i === node.children.length - 1;
+            lines.push(`${prefix}${last ? '└─ ' : '├─ '}${formatNode(child, counts)}`);
+            walk(child, `${prefix}${last ? '   ' : '│  '}`);
+        });
+    };
+    walk(root, '');
+    return lines.join('\n');
+};
 /**
  * The ModelElement interface provides properties and methods for manipulating
  * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-model/ | `<pc-model>`} elements.
@@ -10620,6 +11605,57 @@ class ModelElement extends AsyncElement {
     get entity() {
         return this._entity;
     }
+    /**
+     * Returns a snapshot of the instantiated node tree, or `null` while there is none (the
+     * container asset has not loaded, or the element has left the document). One call grounds a
+     * session — a browser console, a test, an agent — in the vocabulary `pc-node` binding
+     * resolves against: the instantiated names ({@link HierarchyNode.name}), paths, match
+     * indices, attached component types and the material assignments of render components
+     * ({@link HierarchyNode.materials}). `String(...)` of the result, or of any node in it,
+     * is the printable form.
+     *
+     * The snapshot is plain data, computed afresh each call: it does not follow later changes
+     * to the hierarchy, and mutating it changes nothing.
+     *
+     * @returns The root of the instantiated node tree, or `null`.
+     */
+    hierarchy() {
+        const root = this._entity;
+        if (!root) {
+            return null;
+        }
+        // Ordinals are assigned in the traversal resolution searches — pre-order depth-first
+        // from the model root, the root itself included — so each node's index is exactly what
+        // a pc-node's index attribute selects. Once the walk completes, the map holds the total
+        // count per name, which is what the printable form reads to annotate only shared names.
+        const ordinals = new Map();
+        const describe = (entity, pathBelowRoot) => {
+            const index = ordinals.get(entity.name) ?? 0;
+            ordinals.set(entity.name, index + 1);
+            const node = {
+                name: entity.name,
+                // The root has no path below itself; its own name stands in, as it does for
+                // the path a pc-node bound to the root reports.
+                path: pathBelowRoot || entity.name,
+                index,
+                // A plain GraphNode grafted into the hierarchy has no component storage
+                components: Object.keys(entity.c ?? {}).sort(),
+                materials: (entity.render?.meshInstances ?? []).map((meshInstance, slot) => ({
+                    index: slot,
+                    name: meshInstance.material?.name ?? null
+                })),
+                children: entity.children.map((child) => describe(child, pathBelowRoot ? `${pathBelowRoot}/${child.name}` : child.name))
+            };
+            // Non-enumerable, keeping the snapshot plain data under JSON.stringify, spreads and
+            // key enumeration. Deferred to call time, by which the ordinal map holds its totals.
+            Object.defineProperty(node, 'toString', {
+                enumerable: false,
+                value: () => formatHierarchy(node, ordinals)
+            });
+            return node;
+        };
+        return describe(root, '');
+    }
     connectedCallback() {
         // A model outside an application is inert and never becomes ready, so awaiting it hangs.
         // Warn rather than fail silently, naming the parent it requires, as every other misplaced
@@ -10778,6 +11814,74 @@ class ModelElement extends AsyncElement {
 }
 customElements.define('pc-model', ModelElement);
 
+/**
+ * Parses one mapping into its valid rules, warning for each entry that is not one: an unknown
+ * or missing selector prefix, an empty `name:` value, an `index:` value that is not a
+ * non-negative integer, or a replacement id that is not a non-empty string. An invalid rule
+ * behaves exactly as if absent from the mapping.
+ *
+ * @param overrides - The mapping to parse.
+ * @param label - The element description for warnings.
+ * @returns The valid rules.
+ */
+const parseMaterialRules = (overrides, label) => {
+    const rules = [];
+    for (const [selector, id] of Object.entries(overrides)) {
+        if (typeof id !== 'string' || id === '') {
+            console.warn(`${label} material-overrides '${selector}' needs a pc-material id - rule ignored`);
+        }
+        else if (selector.startsWith('name:')) {
+            // The text after the prefix is the selector value, exactly as written - a material
+            // name may legitimately begin or end with whitespace
+            const name = selector.slice('name:'.length);
+            if (name === '') {
+                console.warn(`${label} material-overrides 'name:' selector is empty - rule ignored`);
+            }
+            else {
+                rules.push({ kind: 'name', name, id });
+            }
+        }
+        else if (selector.startsWith('index:')) {
+            // Whitespace around the number is tolerated; Number('') is 0, so blank means NaN
+            const text = selector.slice('index:'.length).trim();
+            const index = text === '' ? NaN : Number(text);
+            if (!Number.isInteger(index) || index < 0) {
+                console.warn(`${label} material-overrides '${selector}' is not a non-negative integer index - rule ignored`);
+            }
+            else {
+                rules.push({ kind: 'index', index, id });
+            }
+        }
+        else {
+            console.warn(`${label} material-overrides '${selector}' has no 'name:' or 'index:' prefix - rule ignored`);
+        }
+    }
+    return rules;
+};
+/**
+ * Parses the material-overrides attribute text. Anything but a JSON object — malformed JSON, an
+ * array, a primitive — warns and yields `null`, the absent mapping: a stale mapping must not
+ * survive an attribute value the DOM no longer represents.
+ *
+ * @param text - The attribute text.
+ * @param label - The element description for warnings.
+ * @returns The mapping, or `null`.
+ */
+const parseMaterialOverridesAttribute = (text, label) => {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        console.warn(`${label} material-overrides is not valid JSON - treated as absent: ${error.message}`);
+        return null;
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        console.warn(`${label} material-overrides must be a JSON object - treated as absent`);
+        return null;
+    }
+    return parsed;
+};
 /**
  * Computes the Levenshtein distance between two strings, for near-miss suggestions in the
  * resolution warnings.
@@ -10833,6 +11937,13 @@ const levenshtein = (a, b) => {
  * "x y z" triple.
  * @attribute {string} scale - Overrides the node's local scale, as an "x y z" triple.
  * @attribute {string} tags - Overrides the node's tags, separated by spaces or commas.
+ * @attribute {string} material-overrides - Overrides material assignments on the bound node's
+ * render component, as a JSON object from selector to `pc-material` id — for example
+ * `{"name:CarPaint": "candy-red", "index:7": "smoked-glass"}`. A `name:X` key selects every mesh
+ * instance whose baseline material is named `X`; an `index:N` key selects mesh instance `N` and
+ * wins over a name rule for the same instance. Assignments no rule matches keep their baseline
+ * materials, and removing the attribute restores all of them. Use `pc-model.hierarchy()` to
+ * discover the names and indices a node offers.
  * @attribute {string} onpointerenter - Script to run when the pointer moves onto the node.
  * @attribute {string} onpointerleave - Script to run when the pointer moves off the node.
  * @attribute {string} onpointermove - Script to run when the pointer moves over the node.
@@ -10868,12 +11979,25 @@ class NodeElement extends EntityBaseElement {
     _destroyHandle = null;
     /** The authored values displaced by this element's overrides, captured per property. */
     _authored = {};
+    /**
+     * The model-authored render component of the bound node, recorded at bind — before child
+     * decorations build — so a render component added later by a child `pc-render` can never
+     * become the override target. `null` when the bound node has none.
+     */
+    _authoredRender = null;
+    /**
+     * The baseline assignments displaced by the material overrides, captured for every mesh
+     * instance when the first non-empty mapping applies and released when the mapping goes
+     * absent (restoring them) or the binding dissolves.
+     */
+    _baseline = null;
     // Override values. `null` means "no override": the authored value stays in force.
     _enabled = null;
     _position = null;
     _rotation = null;
     _scale = null;
     _tags = null;
+    _materialOverrides = null;
     /**
      * The binding state: `pending` until the host instantiates and `name` resolves, `bound`
      * once decorated, `missing`/`ambiguous`/`duplicate` when resolution failed (each also
@@ -11007,6 +12131,7 @@ class NodeElement extends EntityBaseElement {
         this._destroyHandle = target.once('destroy', this._onEntityDestroy, this);
         this._state = 'bound';
         this._path = this._pathOf(target, hostEntity);
+        this._authoredRender = target.render ?? null;
         this._applyOverrides();
         this._onReady();
         this._buildChildren();
@@ -11037,6 +12162,7 @@ class NodeElement extends EntityBaseElement {
         this._entity = null;
         this._path = null;
         this._authored = {};
+        this._authoredRender = null;
         // Component decorations come off through the same hook the host-ready cycle uses. A
         // dissolve that never rebinds fires no ready event, so the sweep is explicit - after
         // `_entity` is cleared, so the hook sees a host without an entity.
@@ -11058,6 +12184,9 @@ class NodeElement extends EntityBaseElement {
         this._entity = null;
         this._path = null;
         this._authored = {};
+        this._authoredRender = null;
+        // The mesh instances died with the entity - the capture is dropped, not restored
+        this._baseline = null;
         this._state = 'pending';
         this._resetReady();
     }
@@ -11072,13 +12201,7 @@ class NodeElement extends EntityBaseElement {
         if (!app) {
             return;
         }
-        const childEntities = this.querySelectorAll('pc-entity');
-        childEntities.forEach((child) => {
-            child._createEntity(app);
-        });
-        childEntities.forEach((child) => {
-            child._buildHierarchy(app);
-        });
+        buildDescendantEntities(this, app);
     }
     /**
      * Applies every override that is explicitly set, capturing the authored value it displaces.
@@ -11099,6 +12222,9 @@ class NodeElement extends EntityBaseElement {
         if (this._tags !== null) {
             this.tags = this._tags;
         }
+        if (this._materialOverrides !== null) {
+            this._applyMaterialOverrides();
+        }
     }
     /**
      * Restores every authored value this element's overrides displaced. The override values
@@ -11124,6 +12250,104 @@ class NodeElement extends EntityBaseElement {
             entity.tags.add(authored.tags);
         }
         this._authored = {};
+        this._restoreBaseline();
+    }
+    /**
+     * Applies the material mapping to the authored render component: parse the mapping's valid
+     * rules, capture the baseline on first application, then recompute every assignment from
+     * that baseline - name rules write over it, index rules write over them, so `index:` wins -
+     * and assign whatever changed. An absent mapping, or one with no valid rules, restores the
+     * baseline instead. Called while bound, from `_applyOverrides` and the property setter.
+     */
+    _applyMaterialOverrides() {
+        const label = `pc-node '${this._name}'`;
+        const rules = this._materialOverrides ? parseMaterialRules(this._materialOverrides, label) : [];
+        if (rules.length === 0) {
+            this._restoreBaseline();
+            return;
+        }
+        if (!this._baseline) {
+            if (!this._authoredRender) {
+                console.warn(`${label} is bound to a node without an authored render component - material-overrides ignored`);
+                return;
+            }
+            this._baseline = this._authoredRender.meshInstances.map((meshInstance) => ({
+                meshInstance,
+                material: meshInstance.material ?? null,
+                name: meshInstance.material?.name ?? null
+            }));
+        }
+        const baseline = this._baseline;
+        /** Resolves a replacement id, warning when it does not resolve. */
+        const resolveReplacement = (id) => {
+            const material = MaterialElement.get(id);
+            if (!material) {
+                console.warn(`${label} material-overrides could not resolve pc-material '${id}' - rule ignored`);
+            }
+            return material ?? null;
+        };
+        // Recompute the whole list from the baseline: name rules write over it, index rules
+        // write over them. Recomputing makes mapping edits order-independent, and a rule whose
+        // replacement does not resolve simply leaves the layer below it in force.
+        const resolved = baseline.map((assignment) => assignment.material);
+        for (const rule of rules) {
+            if (rule.kind !== 'name') {
+                continue;
+            }
+            const material = resolveReplacement(rule.id);
+            if (!material) {
+                continue;
+            }
+            let matched = false;
+            baseline.forEach((assignment, index) => {
+                if (assignment.name === rule.name) {
+                    resolved[index] = material;
+                    matched = true;
+                }
+            });
+            if (!matched) {
+                const names = baseline.map((assignment) => `'${assignment.name}'`).join(', ');
+                console.warn(`${label} material-overrides 'name:${rule.name}' matches no assignment - ` +
+                    `baseline names: ${names || '(none)'}`);
+            }
+        }
+        for (const rule of rules) {
+            if (rule.kind !== 'index') {
+                continue;
+            }
+            if (rule.index >= baseline.length) {
+                console.warn(`${label} material-overrides 'index:${rule.index}' is out of range - ` +
+                    `${baseline.length} assignment(s)`);
+                continue;
+            }
+            const material = resolveReplacement(rule.id);
+            if (material) {
+                resolved[rule.index] = material;
+            }
+        }
+        baseline.forEach((assignment, index) => {
+            // The engine setter rebuilds material and shader state even for a redundant write,
+            // so only actual changes are assigned
+            if (assignment.meshInstance.material !== resolved[index]) {
+                assignment.meshInstance.material = resolved[index];
+            }
+        });
+    }
+    /**
+     * Restores every baseline assignment the material overrides displaced and releases the
+     * capture, so the next non-empty mapping captures afresh. Safe to call without a capture.
+     */
+    _restoreBaseline() {
+        const baseline = this._baseline;
+        if (!baseline) {
+            return;
+        }
+        this._baseline = null;
+        for (const assignment of baseline) {
+            if (assignment.meshInstance.material !== assignment.material) {
+                assignment.meshInstance.material = assignment.material;
+            }
+        }
     }
     /**
      * Renders the path of `node` below `root`, for the `path` property and the resolution
@@ -11344,8 +12568,41 @@ class NodeElement extends EntityBaseElement {
     get tags() {
         return this._tags;
     }
+    /**
+     * Sets the material overrides: a sparse mapping from selector to `pc-material` id, applied
+     * to the bound node's authored render component. A `name:X` key selects every mesh instance
+     * whose baseline material is named `X`; an `index:N` key selects mesh instance `N` and wins
+     * over a name rule for the same instance. Assignments no rule matches keep their baseline
+     * materials. `null` clears the mapping, restoring every baseline assignment.
+     * @param value - The mapping, or `null`.
+     */
+    set materialOverrides(value) {
+        // Copied and frozen: later caller mutation of the passed object must not silently
+        // disagree with the mapping the element applied
+        this._materialOverrides = value === null ? null : Object.freeze({ ...value });
+        if (this._state === 'bound') {
+            this._applyMaterialOverrides();
+        }
+    }
+    /**
+     * Gets the material overrides.
+     * @returns The mapping, or `null` while no override is set.
+     */
+    get materialOverrides() {
+        return this._materialOverrides;
+    }
     static get observedAttributes() {
-        return ['enabled', 'index', 'name', 'position', 'rotation', 'scale', 'tags', ...POINTER_ATTRIBUTES];
+        return [
+            'enabled',
+            'index',
+            'material-overrides',
+            'name',
+            'position',
+            'rotation',
+            'scale',
+            'tags',
+            ...POINTER_ATTRIBUTES
+        ];
     }
     attributeChangedCallback(name, _oldValue, newValue) {
         switch (name) {
@@ -11370,6 +12627,10 @@ class NodeElement extends EntityBaseElement {
                     }
                 }
                 break;
+            case 'material-overrides':
+                this.materialOverrides =
+                    newValue === null ? null : parseMaterialOverridesAttribute(newValue, `pc-node '${this._name}'`);
+                break;
             case 'name':
                 this.name = newValue ?? '';
                 break;
@@ -11916,5 +13177,5 @@ class SkyElement extends AsyncElement {
 }
 customElements.define('pc-sky', SkyElement);
 
-export { AppElement, AssetElement, AsyncElement, ButtonComponentElement, CameraComponentElement, CollisionComponentElement, ComponentElement, ElementComponentElement, EntityBaseElement, EntityElement, GSplatComponentElement, LayoutChildComponentElement, LayoutGroupComponentElement, LightComponentElement, ListenerComponentElement, MaterialElement, ModelElement, ModuleElement, NodeElement, ParticleSystemComponentElement, RenderComponentElement, RigidBodyComponentElement, SceneElement, ScreenComponentElement, ScriptComponentElement, ScriptElement, ScrollViewComponentElement, ScrollbarComponentElement, SkyElement, SoundComponentElement, SoundSlotElement, whenReady };
+export { AppElement, AssetElement, AsyncElement, ButtonComponentElement, CameraComponentElement, CollisionComponentElement, ComponentElement, ElementComponentElement, EntityBaseElement, EntityElement, GSplatComponentElement, JointComponentElement, LayoutChildComponentElement, LayoutGroupComponentElement, LightComponentElement, ListenerComponentElement, MaterialElement, ModelElement, ModuleElement, NodeElement, ParticleSystemComponentElement, RenderComponentElement, RigidBodyComponentElement, SceneElement, ScreenComponentElement, ScriptComponentElement, ScriptElement, ScrollViewComponentElement, ScrollbarComponentElement, SkyElement, SoundComponentElement, SoundSlotElement, whenReady };
 //# sourceMappingURL=pwc.mjs.map