@playcanvas/web-components 0.14.0 → 0.16.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.14.0",
+  "version": "0.16.0",
   "description-markup": "markdown",
   "contributions": {
     "html": {
@@ -1825,6 +1825,161 @@
             ]
           }
         },
+        {
+          "name": "pc-anim-clip",
+          "description": "The AnimClipElement interface provides properties and methods for manipulating\n[`<pc-anim-clip>`](https://developer.playcanvas.com/user-manual/web-components/tags/pc-anim-clip/)\nelements. The AnimClipElement interface also inherits the properties and methods of the\nHTMLElement interface.\n\nA clip declares one named animation on its parent `<pc-anim>`. `name` is both the clip's name\nand the track looked up in the clip's source: an explicit `asset` (a `container`, an\n`animation` `.glb`, or an `animclip` JSON), or, without one, the container of the `<pc-model>`\nenclosing the parent `<pc-anim>`. A source holding a single track supplies it whatever it is\nnamed; in a multi-track source the track named `name` is chosen, falling back to the first\nwith a warning. The element becomes ready once its resolved track is assigned.\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.",
+          "doc-url": "",
+          "attributes": [
+            {
+              "name": "asset",
+              "description": "The id of the `pc-asset` supplying the clip's track.",
+              "value": { "type": "string" }
+            },
+            {
+              "name": "loop",
+              "description": "Whether the clip loops.",
+              "value": { "type": "boolean", "default": "true" }
+            },
+            {
+              "name": "name",
+              "description": "The name of the clip.",
+              "value": { "type": "string" }
+            },
+            {
+              "name": "speed",
+              "description": "The playback speed of the clip.",
+              "value": { "type": "number", "default": "1" }
+            }
+          ],
+          "events": [
+            {
+              "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": "asset",
+                "description": "Gets the id of the `pc-asset` supplying the clip's track."
+              },
+              {
+                "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": "loop", "description": "Gets whether the clip loops." },
+              { "name": "name", "description": "Gets the name of the clip." },
+              {
+                "name": "speed",
+                "description": "Gets the playback speed of the clip."
+              }
+            ],
+            "events": [
+              {
+                "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-anim",
+          "description": "The AnimComponentElement interface provides properties and methods for manipulating\n[`<pc-anim>`](https://developer.playcanvas.com/user-manual/web-components/tags/pc-anim/) elements.\nThe AnimComponentElement interface also inherits the properties and methods of the\nHTMLElement interface.\n\nThe element drives animation clips over the host entity's hierarchy. Clips come from\n`<pc-anim-clip>` children — or, when the element is a direct child of a `<pc-model>` and\ndeclares no clips, every animation of that model's container asset is assigned, named by track\nname, in container order. The first clip plays automatically (opt out with `activate=\"false\"`);\nswitch clips declaratively through the `clip` attribute, or imperatively through play\nand transition. Tracks bind to scene nodes by name, so any hierarchy whose node names\nmatch a clip's curves can be animated — a model's skeleton is simply the common case.\n\nThe engine reports no clip completion: a non-looping clip holds its last pose silently. Poll\nthe underlying AnimComponent (via component) for playback state beyond what\nthis element exposes.\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 - **pause()** - Pauses playback, preserving the playhead — play resumes from where it stopped.\n- **play(name: _string_)** - Resumes playback, optionally switching to a named clip first (a hard cut). A name that\nmatches no clip leaves the selection unchanged.\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.\n- **transition(name: _string_, time: _number_)** - Cross-fades to a named clip and ensures playback is running. A name that matches no clip\nleaves the selection unchanged.",
+          "doc-url": "",
+          "attributes": [
+            {
+              "name": "activate",
+              "description": "Whether playback starts automatically once a clip is assigned.",
+              "value": { "type": "boolean", "default": "true" }
+            },
+            {
+              "name": "clip",
+              "description": "The name of the active clip.",
+              "value": { "type": "string" }
+            },
+            {
+              "name": "enabled",
+              "description": "The enabled state of the component.",
+              "value": { "type": "boolean", "default": "true" }
+            },
+            {
+              "name": "speed",
+              "description": "The playback speed multiplier applied across all clips.",
+              "value": { "type": "number", "default": "1" }
+            },
+            {
+              "name": "transition-time",
+              "description": "The cross-fade duration of clip switches made through the `clip` attribute.",
+              "value": { "type": "number", "default": "0" }
+            }
+          ],
+          "events": [
+            {
+              "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": "activate",
+                "description": "Gets whether playback starts automatically once a clip is assigned."
+              },
+              {
+                "name": "clip",
+                "description": "Gets the name of the active clip."
+              },
+              {
+                "name": "clips",
+                "description": "Gets the names of the assigned clips.",
+                "type": "string[]"
+              },
+              {
+                "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 anim component.",
+                "type": "Component | null"
+              },
+              {
+                "name": "enabled",
+                "description": "Gets the enabled state of the component."
+              },
+              {
+                "name": "speed",
+                "description": "Gets the playback speed multiplier applied across all clips."
+              },
+              {
+                "name": "transitionTime",
+                "description": "Gets the cross-fade duration of clip switches made through the `clip` attribute."
+              }
+            ],
+            "events": [
+              {
+                "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-button",
           "description": "The ButtonComponentElement interface provides properties and methods for manipulating\n[`<pc-button>`](https://developer.playcanvas.com/user-manual/web-components/tags/pc-button/) elements.\nThe ButtonComponentElement 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.",
@@ -2713,6 +2868,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.14.0",
+  "version": "0.16.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",
@@ -100,7 +101,7 @@
     "jsdom": "30.0.1",
     "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');