@playcanvas/web-components 0.13.1 → 0.15.0

package/dist/web-types.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://raw.githubusercontent.com/JetBrains/web-types/master/schema/web-types.json",
   "name": "@playcanvas/web-components",
-  "version": "0.13.1",
+  "version": "0.15.0",
   "description-markup": "markdown",
   "contributions": {
     "html": {
@@ -785,6 +785,11 @@
               "description": "The UV channel the metalness map samples.",
               "value": { "type": "number", "default": "0" }
             },
+            {
+              "name": "name",
+              "description": "The name of the material - the label shown wherever materials surface by name, such as profilers, GPU captures and the assignments `pc-model.hierarchy()` reports.",
+              "value": { "type": "string" }
+            },
             {
               "name": "normal-map",
               "description": "The id of the `pc-asset` used as the normal map.",
@@ -1162,6 +1167,10 @@
                 "name": "metalnessMapUv",
                 "description": "Gets the UV channel the metalness map samples."
               },
+              {
+                "name": "name",
+                "description": "Gets the name of the material - the label shown wherever materials surface by name, such\nas profilers, GPU captures and the assignments `pc-model.hierarchy()` reports. Purely a\nlabel: element references resolve through `id`."
+              },
               {
                 "name": "normalMap",
                 "description": "Gets the id of the `pc-asset` used as the normal map."
@@ -1284,7 +1293,7 @@
         },
         {
           "name": "pc-model",
-          "description": "The ModelElement interface provides properties and methods for manipulating\n[`<pc-model>`](https://developer.playcanvas.com/user-manual/web-components/tags/pc-model/) elements.\nThe ModelElement interface also inherits the properties and methods of the\nHTMLElement interface.\n\nThe element becomes ready once its container asset has loaded and the instantiated hierarchy has\nbeen added to the scene — `entity` is non-null by then. A failed load also settles readiness,\nwith `entity` remaining `null`: readiness means the load settled, not that it succeeded — listen\nfor `error`, or check `entity`, to tell the outcomes apart. Changing `asset` re-arms readiness\nand instantiates anew, so a `ready()` obtained after the change resolves against the new\nhierarchy. A `pc-model` outside a `pc-app`, or referencing an unknown asset id, warns and never\nbecomes ready.\n\n---\n\n\n### **Events:**\n - **error** - Fired when the container asset fails to load, with the engine's error in `message`. Does not bubble. The element still becomes ready — readiness means the load settled, not that it succeeded.\n- **load** - Fired each time a container asset finishes instantiating, including re-instantiation after `asset` changes. Does not bubble — listen on this element, or use a capture-phase listener on an ancestor.\n- **ready** - Fired when the element is fully initialized — once per readiness cycle, so an element that is torn down and re-initialized (for example by removing and re-inserting it) fires it again. Bubbles and is composed.\n\n### **Methods:**\n - **ready(): __** - Returns a promise that resolves with this element when it's ready. This is the low-level\nprimitive underlying whenReady, which is the recommended way to wait for elements.\n\nReadiness tracks the element's current lifecycle: once a ready element is torn down (for\nexample by removing it from the document), this returns a fresh promise that resolves when\nthe element is next ready. A promise obtained earlier stays resolved — call this again\nafter re-inserting an element rather than reusing a promise from before its removal.",
+          "description": "The ModelElement interface provides properties and methods for manipulating\n[`<pc-model>`](https://developer.playcanvas.com/user-manual/web-components/tags/pc-model/) elements.\nThe ModelElement interface also inherits the properties and methods of the\nHTMLElement interface.\n\nThe element becomes ready once its container asset has loaded and the instantiated hierarchy has\nbeen added to the scene — `entity` is non-null by then. A failed load also settles readiness,\nwith `entity` remaining `null`: readiness means the load settled, not that it succeeded — listen\nfor `error`, or check `entity`, to tell the outcomes apart. Changing `asset` re-arms readiness\nand instantiates anew, so a `ready()` obtained after the change resolves against the new\nhierarchy. A `pc-model` outside a `pc-app`, or referencing an unknown asset id, warns and never\nbecomes ready.\n\n---\n\n\n### **Events:**\n - **error** - Fired when the container asset fails to load, with the engine's error in `message`. Does not bubble. The element still becomes ready — readiness means the load settled, not that it succeeded.\n- **load** - Fired each time a container asset finishes instantiating, including re-instantiation after `asset` changes. Does not bubble — listen on this element, or use a capture-phase listener on an ancestor.\n- **ready** - Fired when the element is fully initialized — once per readiness cycle, so an element that is torn down and re-initialized (for example by removing and re-inserting it) fires it again. Bubbles and is composed.\n\n### **Methods:**\n - **hierarchy(): __** - Returns a snapshot of the instantiated node tree, or `null` while there is none (the\ncontainer asset has not loaded, or the element has left the document). One call grounds a\nsession — a browser console, a test, an agent — in the vocabulary `pc-node` binding\nresolves against: the instantiated names (HierarchyNode.name), paths, match\nindices, attached component types and the material assignments of render components\n(HierarchyNode.materials). `String(...)` of the result, or of any node in it,\nis the printable form.\n\nThe snapshot is plain data, computed afresh each call: it does not follow later changes\nto the hierarchy, and mutating it changes nothing.\n- **ready(): __** - Returns a promise that resolves with this element when it's ready. This is the low-level\nprimitive underlying whenReady, which is the recommended way to wait for elements.\n\nReadiness tracks the element's current lifecycle: once a ready element is torn down (for\nexample by removing it from the document), this returns a fresh promise that resolves when\nthe element is next ready. A promise obtained earlier stays resolved — call this again\nafter re-inserting an element rather than reusing a promise from before its removal.",
           "doc-url": "",
           "attributes": [
             {
@@ -1422,6 +1431,11 @@
               "description": "Which match to bind when `name` matches more than one node, 0-based in depth-first order. Optional for a unique match; required for an ambiguous one.",
               "value": { "type": "string" }
             },
+            {
+              "name": "material-overrides",
+              "description": "Overrides material assignments on the bound node's render component, as a JSON object from selector to `pc-material` id — for example `{\"name:CarPaint\": \"candy-red\", \"index:7\": \"smoked-glass\"}`. A `name:X` key selects every mesh instance whose baseline material is named `X`; an `index:N` key selects mesh instance `N` and wins over a name rule for the same instance. Assignments no rule matches keep their baseline materials, and removing the attribute restores all of them. Use `pc-model.hierarchy()` to discover the names and indices a node offers.",
+              "value": { "type": "string" }
+            },
             {
               "name": "name",
               "description": "The name of the node to bind, resolved within the nearest ancestor `pc-model` (or `pc-node`) once it has instantiated.",
@@ -1532,6 +1546,11 @@
                 "description": "Gets which match to bind.",
                 "type": "number | null"
               },
+              {
+                "name": "materialOverrides",
+                "description": "Gets the material overrides.",
+                "type": "MaterialOverrides | null"
+              },
               {
                 "name": "name",
                 "description": "Gets the name of the node to bind.",
@@ -2694,6 +2713,353 @@
             ]
           }
         },
+        {
+          "name": "pc-joint",
+          "description": "The JointComponentElement interface provides properties and methods for manipulating\n[`<pc-joint>`](https://developer.playcanvas.com/user-manual/web-components/tags/pc-joint/) elements.\nThe JointComponentElement interface also inherits the properties and methods of the\nHTMLElement interface.\n\nThe entity holding the joint is not itself constrained. Its world transform defines the joint\nframe — the anchor point and axes the constraint operates about — with the local X axis as the\nprimary axis: a hinge rotates about it, a slider translates along it and a ball joint twists\nabout it. The constrained bodies are referenced by `entity-a` and `entity-b`, both of which need\na rigid body component; leaving `entity-b` empty constrains `entity-a` to a fixed point in world\nspace. The underlying engine component is in alpha, so its API may change.\n\n---\n\n\n### **Events:**\n - **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.\n- **ready** - Fired when the element is fully initialized — once per readiness cycle, so an element that is torn down and re-initialized (for example by removing and re-inserting it) fires it again. Bubbles and is composed.\n\n### **Methods:**\n - **ready(): __** - Returns a promise that resolves with this element when it's ready. This is the low-level\nprimitive underlying whenReady, which is the recommended way to wait for elements.\n\nReadiness tracks the element's current lifecycle: once a ready element is torn down (for\nexample by removing it from the document), this returns a fresh promise that resolves when\nthe element is next ready. A promise obtained earlier stays resolved — call this again\nafter re-inserting an element rather than reusing a promise from before its removal.",
+          "doc-url": "",
+          "attributes": [
+            {
+              "name": "angular-damping",
+              "description": "The spring damping of the joint per angular axis. Accepts 3 space-separated numbers.",
+              "value": { "type": "string", "default": "1 1 1" }
+            },
+            {
+              "name": "angular-equilibrium",
+              "description": "The rest angle of the joint's angular springs. Accepts 3 space-separated numbers.",
+              "value": { "type": "string", "default": "0 0 0" }
+            },
+            {
+              "name": "angular-limits-x",
+              "description": "The rotation limits of the joint about its X axis. Accepts 2 space-separated numbers.",
+              "value": { "type": "string", "default": "0 0" }
+            },
+            {
+              "name": "angular-limits-y",
+              "description": "The rotation limits of the joint about its Y axis. Accepts 2 space-separated numbers.",
+              "value": { "type": "string", "default": "0 0" }
+            },
+            {
+              "name": "angular-limits-z",
+              "description": "The rotation limits of the joint about its Z axis. Accepts 2 space-separated numbers.",
+              "value": { "type": "string", "default": "0 0" }
+            },
+            {
+              "name": "angular-motion-x",
+              "description": "How the joint constrains rotation about its X axis.",
+              "value": {
+                "type": "'locked' | 'limited' | 'free'",
+                "default": "locked"
+              }
+            },
+            {
+              "name": "angular-motion-y",
+              "description": "How the joint constrains rotation about its Y axis.",
+              "value": {
+                "type": "'locked' | 'limited' | 'free'",
+                "default": "locked"
+              }
+            },
+            {
+              "name": "angular-motion-z",
+              "description": "How the joint constrains rotation about its Z axis.",
+              "value": {
+                "type": "'locked' | 'limited' | 'free'",
+                "default": "locked"
+              }
+            },
+            {
+              "name": "angular-stiffness",
+              "description": "The spring stiffness of the joint per angular axis. Accepts 3 space-separated numbers.",
+              "value": { "type": "string", "default": "0 0 0" }
+            },
+            {
+              "name": "break-impulse",
+              "description": "The impulse above which the joint breaks.",
+              "value": { "type": "number", "default": "Infinity" }
+            },
+            {
+              "name": "enable-collision",
+              "description": "Whether collision is enabled between the two constrained bodies.",
+              "value": { "type": "boolean", "default": "false" }
+            },
+            {
+              "name": "enable-limits",
+              "description": "Whether the limits of the joint are enforced.",
+              "value": { "type": "boolean", "default": "false" }
+            },
+            {
+              "name": "enabled",
+              "description": "The enabled state of the component.",
+              "value": { "type": "boolean", "default": "true" }
+            },
+            {
+              "name": "entity-a",
+              "description": "The reference to the `<pc-entity>` providing the first constrained body.",
+              "value": { "type": "string" }
+            },
+            {
+              "name": "entity-b",
+              "description": "The reference to the `<pc-entity>` providing the second constrained body.",
+              "value": { "type": "string" }
+            },
+            {
+              "name": "limits",
+              "description": "The rotation or travel limits of the joint. Accepts 2 space-separated numbers.",
+              "value": { "type": "string", "default": "-45 45" }
+            },
+            {
+              "name": "linear-damping",
+              "description": "The spring damping of the joint per linear axis. Accepts 3 space-separated numbers.",
+              "value": { "type": "string", "default": "1 1 1" }
+            },
+            {
+              "name": "linear-equilibrium",
+              "description": "The rest point of the joint's linear springs. Accepts 3 space-separated numbers.",
+              "value": { "type": "string", "default": "0 0 0" }
+            },
+            {
+              "name": "linear-limits-x",
+              "description": "The translation limits of the joint along its X axis. Accepts 2 space-separated numbers.",
+              "value": { "type": "string", "default": "0 0" }
+            },
+            {
+              "name": "linear-limits-y",
+              "description": "The translation limits of the joint along its Y axis. Accepts 2 space-separated numbers.",
+              "value": { "type": "string", "default": "0 0" }
+            },
+            {
+              "name": "linear-limits-z",
+              "description": "The translation limits of the joint along its Z axis. Accepts 2 space-separated numbers.",
+              "value": { "type": "string", "default": "0 0" }
+            },
+            {
+              "name": "linear-motion-x",
+              "description": "How the joint constrains translation along its X axis.",
+              "value": {
+                "type": "'locked' | 'limited' | 'free'",
+                "default": "locked"
+              }
+            },
+            {
+              "name": "linear-motion-y",
+              "description": "How the joint constrains translation along its Y axis.",
+              "value": {
+                "type": "'locked' | 'limited' | 'free'",
+                "default": "locked"
+              }
+            },
+            {
+              "name": "linear-motion-z",
+              "description": "How the joint constrains translation along its Z axis.",
+              "value": {
+                "type": "'locked' | 'limited' | 'free'",
+                "default": "locked"
+              }
+            },
+            {
+              "name": "linear-stiffness",
+              "description": "The spring stiffness of the joint per linear axis. Accepts 3 space-separated numbers.",
+              "value": { "type": "string", "default": "0 0 0" }
+            },
+            {
+              "name": "max-motor-force",
+              "description": "The maximum torque or force of the joint's motor.",
+              "value": { "type": "number", "default": "0" }
+            },
+            {
+              "name": "motor-speed",
+              "description": "The target speed of the joint's motor.",
+              "value": { "type": "number", "default": "0" }
+            },
+            {
+              "name": "swing-limit-y",
+              "description": "The maximum swing of the joint around the joint frame's Y axis.",
+              "value": { "type": "number", "default": "45" }
+            },
+            {
+              "name": "swing-limit-z",
+              "description": "The maximum swing of the joint around the joint frame's Z axis.",
+              "value": { "type": "number", "default": "45" }
+            },
+            {
+              "name": "twist-limit",
+              "description": "The maximum twist of the joint about its primary axis.",
+              "value": { "type": "number", "default": "20" }
+            },
+            {
+              "name": "type",
+              "description": "The type of the joint.",
+              "value": {
+                "type": "'fixed' | 'ball' | 'hinge' | 'slider' | '6dof'",
+                "default": "fixed"
+              }
+            }
+          ],
+          "events": [
+            {
+              "name": "break",
+              "type": "CustomEvent",
+              "description": "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."
+            },
+            {
+              "name": "ready",
+              "type": "CustomEvent",
+              "description": "Fired when the element is fully initialized — once per readiness cycle, so an element that is torn down and re-initialized (for example by removing and re-inserting it) fires it again. Bubbles and is composed."
+            }
+          ],
+          "js": {
+            "properties": [
+              {
+                "name": "angularDamping",
+                "description": "Gets the spring damping of the joint per angular axis."
+              },
+              {
+                "name": "angularEquilibrium",
+                "description": "Gets the rest angle of the joint's angular springs."
+              },
+              {
+                "name": "angularLimitsX",
+                "description": "Gets the rotation limits of the joint about its X axis."
+              },
+              {
+                "name": "angularLimitsY",
+                "description": "Gets the rotation limits of the joint about its Y axis."
+              },
+              {
+                "name": "angularLimitsZ",
+                "description": "Gets the rotation limits of the joint about its Z axis."
+              },
+              {
+                "name": "angularMotionX",
+                "description": "Gets how the joint constrains rotation about its X axis."
+              },
+              {
+                "name": "angularMotionY",
+                "description": "Gets how the joint constrains rotation about its Y axis."
+              },
+              {
+                "name": "angularMotionZ",
+                "description": "Gets how the joint constrains rotation about its Z axis."
+              },
+              {
+                "name": "angularStiffness",
+                "description": "Gets the spring stiffness of the joint per angular axis."
+              },
+              {
+                "name": "breakImpulse",
+                "description": "Gets the impulse above which the joint breaks."
+              },
+              {
+                "name": "closestApp",
+                "description": "The nearest ancestor `<pc-app>` element, or `null` if this element has no `<pc-app>`\nancestor. The search starts at the parent, so an element never resolves to itself.",
+                "type": "AppElement | null"
+              },
+              {
+                "name": "closestEntity",
+                "description": "The nearest ancestor element that fronts an entity — `<pc-entity>` or `<pc-node>` — or\n`null` if this element has no such ancestor. The search starts at the parent, so an element\nnever resolves to itself.",
+                "type": "EntityBaseElement | null"
+              },
+              {
+                "name": "component",
+                "description": "Gets the underlying PlayCanvas joint component.",
+                "type": "Component | null"
+              },
+              {
+                "name": "enableCollision",
+                "description": "Gets whether collision is enabled between the two constrained bodies."
+              },
+              {
+                "name": "enabled",
+                "description": "Gets the enabled state of the component."
+              },
+              {
+                "name": "enableLimits",
+                "description": "Gets whether the limits of the joint are enforced."
+              },
+              {
+                "name": "entityA",
+                "description": "Gets the reference to the `<pc-entity>` providing the first constrained body."
+              },
+              {
+                "name": "entityB",
+                "description": "Gets the reference to the `<pc-entity>` providing the second constrained body."
+              },
+              {
+                "name": "limits",
+                "description": "Gets the rotation or travel limits of the joint."
+              },
+              {
+                "name": "linearDamping",
+                "description": "Gets the spring damping of the joint per linear axis."
+              },
+              {
+                "name": "linearEquilibrium",
+                "description": "Gets the rest point of the joint's linear springs."
+              },
+              {
+                "name": "linearLimitsX",
+                "description": "Gets the translation limits of the joint along its X axis."
+              },
+              {
+                "name": "linearLimitsY",
+                "description": "Gets the translation limits of the joint along its Y axis."
+              },
+              {
+                "name": "linearLimitsZ",
+                "description": "Gets the translation limits of the joint along its Z axis."
+              },
+              {
+                "name": "linearMotionX",
+                "description": "Gets how the joint constrains translation along its X axis."
+              },
+              {
+                "name": "linearMotionY",
+                "description": "Gets how the joint constrains translation along its Y axis."
+              },
+              {
+                "name": "linearMotionZ",
+                "description": "Gets how the joint constrains translation along its Z axis."
+              },
+              {
+                "name": "linearStiffness",
+                "description": "Gets the spring stiffness of the joint per linear axis."
+              },
+              {
+                "name": "maxMotorForce",
+                "description": "Gets the maximum torque or force of the joint's motor."
+              },
+              {
+                "name": "motorSpeed",
+                "description": "Gets the target speed of the joint's motor."
+              },
+              {
+                "name": "swingLimitY",
+                "description": "Gets the maximum swing of the joint around the joint frame's Y axis."
+              },
+              {
+                "name": "swingLimitZ",
+                "description": "Gets the maximum swing of the joint around the joint frame's Z axis."
+              },
+              {
+                "name": "twistLimit",
+                "description": "Gets the maximum twist of the joint about its primary axis."
+              },
+              { "name": "type", "description": "Gets the type of the joint." }
+            ],
+            "events": [
+              {
+                "name": "break",
+                "type": "CustomEvent",
+                "description": "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."
+              },
+              {
+                "name": "ready",
+                "type": "CustomEvent",
+                "description": "Fired when the element is fully initialized — once per readiness cycle, so an element that is torn down and re-initialized (for example by removing and re-inserting it) fires it again. Bubbles and is composed."
+              }
+            ]
+          }
+        },
         {
           "name": "pc-layoutchild",
           "description": "The LayoutChildComponentElement interface provides properties and methods for manipulating\n[`<pc-layoutchild>`](https://developer.playcanvas.com/user-manual/web-components/tags/pc-layoutchild/) elements.\nThe LayoutChildComponentElement interface also inherits the properties and methods of the\nHTMLElement interface.\n\n---\n\n\n### **Events:**\n - **ready** - Fired when the element is fully initialized — once per readiness cycle, so an element that is torn down and re-initialized (for example by removing and re-inserting it) fires it again. Bubbles and is composed.\n\n### **Methods:**\n - **ready(): __** - Returns a promise that resolves with this element when it's ready. This is the low-level\nprimitive underlying whenReady, which is the recommended way to wait for elements.\n\nReadiness tracks the element's current lifecycle: once a ready element is torn down (for\nexample by removing it from the document), this returns a fresh promise that resolves when\nthe element is next ready. A promise obtained earlier stays resolved — call this again\nafter re-inserting an element rather than reusing a promise from before its removal.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcanvas/web-components",
-  "version": "0.13.1",
+  "version": "0.15.0",
   "author": "PlayCanvas <support@playcanvas.com>",
   "homepage": "https://playcanvas.com",
   "description": "Web Components for the PlayCanvas Engine",
@@ -71,6 +71,7 @@
     "test:unit": "vitest run --project unit",
     "test:elements": "vitest run --project elements",
     "test:integration": "vitest run --project integration",
+    "test:examples": "vitest run --project examples",
     "publint": "publint",
     "type-check": "npm run type-check:src && npm run type-check:test",
     "type-check:src": "tsc --noEmit -p tsconfig.json",
@@ -96,11 +97,11 @@
     "custom-element-vs-code-integration": "1.5.0",
     "earcut": "3.2.3",
     "eslint": "9.39.5",
-    "globals": "17.9.0",
+    "globals": "17.11.0",
     "jsdom": "30.0.1",
-    "mediabunny": "1.53.0",
+    "mediabunny": "1.53.1",
     "opentype.js": "2.0.0",
-    "playcanvas": "2.22.0-beta.12",
+    "playcanvas": "2.21.4",
     "prettier": "3.9.6",
     "publint": "0.3.23",
     "rollup": "4.62.4",

package/src/app.ts

@@ -252,6 +252,24 @@ class AppElement extends AsyncElement {
             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<ModuleElement>(':scope > pc-module');
 

package/src/colors.ts

@@ -1,3 +1,8 @@
+/**
+ * The CSS color keywords, lowercase name to hex value. Read by `parseColor` to accept color
+ * names as attribute values.
+ * @internal
+ */
 export const CSS_COLORS: Record<string, string> = {
     aliceblue: '#f0f8ff',
     antiquewhite: '#faebd7',