@playcanvas/web-components 0.19.0 → 0.20.0

package/dist/vscode.html-custom-data.json

@@ -1153,7 +1153,7 @@
         },
         {
           "name": "image",
-          "description": "The reference to the `<pc-entity>` whose image element is used for visual transitions.",
+          "description": "The reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#` selector) to the entity whose image element is used for visual transitions, or empty for the button's own entity.",
           "values": []
         },
         {
@@ -1648,12 +1648,12 @@
         },
         {
           "name": "entity-a",
-          "description": "The reference to the `<pc-entity>` providing the first constrained body.",
+          "description": "The reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#` selector) to the element providing the first constrained body.",
           "values": []
         },
         {
           "name": "entity-b",
-          "description": "The reference to the `<pc-entity>` providing the second constrained body.",
+          "description": "The reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#` selector) to the element providing the second constrained body, or empty for the world-space case.",
           "values": []
         },
         {
@@ -2192,11 +2192,11 @@
     },
     {
       "name": "pc-script-instance",
-      "description": "The `<pc-script-instance>` element attaches one script class, named by `name`, to\nthe entity of its parent `<pc-script>`. Its other attributes set script attributes of the same\nname, and `attributes` takes a JSON object instead. Must be a direct child of `<pc-script>`.\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- **scriptattributeschange** - Fired when the script's attributes change. The `detail` carries the new `attributes` object. Bubbles.\n- **scriptenablechange** - Fired when the script's enabled state changes. The `detail` carries the new `enabled` state. Bubbles.\n- **scriptnamechange** - Fired when the script is renamed on a live element. The `detail` carries `oldName` and `newName`. Bubbles.",
+      "description": "The `<pc-script-instance>` element attaches one script class, named by `name`, to\nthe entity of its parent `<pc-script>`. Its other attributes set script attributes of the same\nname, and `attributes` takes a JSON object instead. An `entity:` value is an entity name —\nwrite `entity:#id` for an element id. Must be a direct child of `<pc-script>`.\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- **scriptattributeschange** - Fired when the script's attributes change. The `detail` carries the new `attributes` object. Bubbles.\n- **scriptenablechange** - Fired when the script's enabled state changes. The `detail` carries the new `enabled` state. Bubbles.\n- **scriptnamechange** - Fired when the script is renamed on a live element. The `detail` carries `oldName` and `newName`. Bubbles.",
       "attributes": [
         {
           "name": "attributes",
-          "description": "The attributes of the script.",
+          "description": "The attributes of the script as an object whose `asset:`, `entity:`, `vec2:`, `vec3:`, `vec4:` and `color:` prefixed values are resolved when applied — an `entity:` value being an entity name (nearest enclosing entity first, then outward, then the document) or a document-wide `#` selector (`entity:#id`), never a bare element id.",
           "values": []
         },
         {
@@ -2228,7 +2228,7 @@
         },
         {
           "name": "content",
-          "description": "The reference to the `<pc-entity>` used as the content.",
+          "description": "The reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#` selector) to the entity used as the content.",
           "values": []
         },
         {
@@ -2244,7 +2244,7 @@
         },
         {
           "name": "horizontal-scrollbar",
-          "description": "The reference to the `<pc-entity>` containing the horizontal scrollbar.",
+          "description": "The reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#` selector) to the entity containing the horizontal scrollbar.",
           "values": []
         },
         {
@@ -2278,7 +2278,7 @@
         },
         {
           "name": "vertical-scrollbar",
-          "description": "The reference to the `<pc-entity>` containing the vertical scrollbar.",
+          "description": "The reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#` selector) to the entity containing the vertical scrollbar.",
           "values": []
         },
         {
@@ -2288,7 +2288,7 @@
         },
         {
           "name": "viewport",
-          "description": "The reference to the `<pc-entity>` used as the viewport.",
+          "description": "The reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#` selector) to the entity used as the viewport.",
           "values": []
         }
       ],
@@ -2310,7 +2310,7 @@
         },
         {
           "name": "handle",
-          "description": "The reference to the `<pc-entity>` used as the scrollbar handle.",
+          "description": "The reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#` selector) to the entity used as the scrollbar handle.",
           "values": []
         },
         {

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.19.0",
+  "version": "0.20.0",
   "description-markup": "markdown",
   "contributions": {
     "html": {
@@ -2253,7 +2253,7 @@
             },
             {
               "name": "image",
-              "description": "The reference to the `<pc-entity>` whose image element is used for visual transitions.",
+              "description": "The reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#` selector) to the entity whose image element is used for visual transitions, or empty for the button's own entity.",
               "value": { "type": "string" }
             },
             {
@@ -2346,7 +2346,7 @@
               },
               {
                 "name": "image",
-                "description": "Gets the reference to the `<pc-entity>` whose image element is used for visual transitions."
+                "description": "Gets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`\nselector) to the entity whose image element is used for visual transitions, or empty for\nthe button's own entity."
               },
               {
                 "name": "inactiveSpriteAsset",
@@ -3199,12 +3199,12 @@
             },
             {
               "name": "entity-a",
-              "description": "The reference to the `<pc-entity>` providing the first constrained body.",
+              "description": "The reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#` selector) to the element providing the first constrained body.",
               "value": { "type": "string" }
             },
             {
               "name": "entity-b",
-              "description": "The reference to the `<pc-entity>` providing the second constrained body.",
+              "description": "The reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#` selector) to the element providing the second constrained body, or empty for the world-space case.",
               "value": { "type": "string" }
             },
             {
@@ -3383,11 +3383,11 @@
               },
               {
                 "name": "entityA",
-                "description": "Gets the reference to the `<pc-entity>` providing the first constrained body."
+                "description": "Gets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`\nselector) to the element providing the first constrained body."
               },
               {
                 "name": "entityB",
-                "description": "Gets the reference to the `<pc-entity>` providing the second constrained body."
+                "description": "Gets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`\nselector) to the element providing the second constrained body, or empty for the\nworld-space case."
               },
               {
                 "name": "limits",
@@ -4352,12 +4352,12 @@
         },
         {
           "name": "pc-script-instance",
-          "description": "The `<pc-script-instance>` element attaches one script class, named by `name`, to\nthe entity of its parent `<pc-script>`. Its other attributes set script attributes of the same\nname, and `attributes` takes a JSON object instead. Must be a direct child of `<pc-script>`.\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- **scriptattributeschange** - Fired when the script's attributes change. The `detail` carries the new `attributes` object. Bubbles.\n- **scriptenablechange** - Fired when the script's enabled state changes. The `detail` carries the new `enabled` state. Bubbles.\n- **scriptnamechange** - Fired when the script is renamed on a live element. The `detail` carries `oldName` and `newName`. Bubbles.",
+          "description": "The `<pc-script-instance>` element attaches one script class, named by `name`, to\nthe entity of its parent `<pc-script>`. Its other attributes set script attributes of the same\nname, and `attributes` takes a JSON object instead. An `entity:` value is an entity name —\nwrite `entity:#id` for an element id. Must be a direct child of `<pc-script>`.\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- **scriptattributeschange** - Fired when the script's attributes change. The `detail` carries the new `attributes` object. Bubbles.\n- **scriptenablechange** - Fired when the script's enabled state changes. The `detail` carries the new `enabled` state. Bubbles.\n- **scriptnamechange** - Fired when the script is renamed on a live element. The `detail` carries `oldName` and `newName`. Bubbles.",
           "doc-url": "https://developer.playcanvas.com/user-manual/web-components/tags/pc-script-instance/",
           "attributes": [
             {
               "name": "attributes",
-              "description": "The attributes of the script.",
+              "description": "The attributes of the script as an object whose `asset:`, `entity:`, `vec2:`, `vec3:`, `vec4:` and `color:` prefixed values are resolved when applied — an `entity:` value being an entity name (nearest enclosing entity first, then outward, then the document) or a document-wide `#` selector (`entity:#id`), never a bare element id.",
               "value": { "type": "string" }
             },
             {
@@ -4417,7 +4417,7 @@
               },
               {
                 "name": "scriptAttributes",
-                "description": "Gets the attributes of the script.",
+                "description": "Gets the attributes of the script as an object whose `asset:`, `entity:`, `vec2:`, `vec3:`,\n`vec4:` and `color:` prefixed values are resolved when applied — an `entity:` value being\nan entity name (nearest enclosing entity first, then outward, then the document) or a\ndocument-wide `#` selector (`entity:#id`), never a bare element id.",
                 "type": "Record<string, any>"
               }
             ],
@@ -4457,7 +4457,7 @@
             },
             {
               "name": "content",
-              "description": "The reference to the `<pc-entity>` used as the content.",
+              "description": "The reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#` selector) to the entity used as the content.",
               "value": { "type": "string" }
             },
             {
@@ -4477,7 +4477,7 @@
             },
             {
               "name": "horizontal-scrollbar",
-              "description": "The reference to the `<pc-entity>` containing the horizontal scrollbar.",
+              "description": "The reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#` selector) to the entity containing the horizontal scrollbar.",
               "value": { "type": "string" }
             },
             {
@@ -4513,7 +4513,7 @@
             },
             {
               "name": "vertical-scrollbar",
-              "description": "The reference to the `<pc-entity>` containing the vertical scrollbar.",
+              "description": "The reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#` selector) to the entity containing the vertical scrollbar.",
               "value": { "type": "string" }
             },
             {
@@ -4526,7 +4526,7 @@
             },
             {
               "name": "viewport",
-              "description": "The reference to the `<pc-entity>` used as the viewport.",
+              "description": "The reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#` selector) to the entity used as the viewport.",
               "value": { "type": "string" }
             }
           ],
@@ -4560,7 +4560,7 @@
               },
               {
                 "name": "content",
-                "description": "Gets the reference to the `<pc-entity>` used as the content."
+                "description": "Gets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`\nselector) to the entity used as the content."
               },
               {
                 "name": "enabled",
@@ -4573,7 +4573,7 @@
               },
               {
                 "name": "horizontalScrollbar",
-                "description": "Gets the reference to the `<pc-entity>` containing the horizontal scrollbar."
+                "description": "Gets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`\nselector) to the entity containing the horizontal scrollbar."
               },
               {
                 "name": "horizontalScrollbarVisibility",
@@ -4597,7 +4597,7 @@
               },
               {
                 "name": "verticalScrollbar",
-                "description": "Gets the reference to the `<pc-entity>` containing the vertical scrollbar."
+                "description": "Gets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`\nselector) to the entity containing the vertical scrollbar."
               },
               {
                 "name": "verticalScrollbarVisibility",
@@ -4605,7 +4605,7 @@
               },
               {
                 "name": "viewport",
-                "description": "Gets the reference to the `<pc-entity>` used as the viewport."
+                "description": "Gets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`\nselector) to the entity used as the viewport."
               }
             ],
             "events": [
@@ -4629,7 +4629,7 @@
             },
             {
               "name": "handle",
-              "description": "The reference to the `<pc-entity>` used as the scrollbar handle.",
+              "description": "The reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#` selector) to the entity used as the scrollbar handle.",
               "value": { "type": "string" }
             },
             {
@@ -4681,7 +4681,7 @@
               },
               {
                 "name": "handle",
-                "description": "Gets the reference to the `<pc-entity>` used as the scrollbar handle."
+                "description": "Gets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`\nselector) to the entity used as the scrollbar handle."
               },
               {
                 "name": "handleSize",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcanvas/web-components",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "author": "PlayCanvas <support@playcanvas.com>",
   "homepage": "https://playcanvas.com",
   "description": "Web Components for the PlayCanvas Engine",
@@ -99,12 +99,12 @@
     "eslint": "9.39.5",
     "globals": "17.11.0",
     "jsdom": "30.0.1",
-    "mediabunny": "1.55.3",
+    "mediabunny": "1.55.4",
     "opentype.js": "2.0.0",
     "playcanvas": "2.21.4",
     "prettier": "3.9.6",
     "publint": "0.3.24",
-    "rollup": "4.63.0",
+    "rollup": "4.63.1",
     "serve": "14.2.6",
     "tslib": "2.8.1",
     "typedoc": "0.28.20",

package/src/app.ts

@@ -252,6 +252,13 @@ class AppElement extends AsyncElement {
      */
     private _lastClick: { element: EntityBaseElement; time: number; count: number } | null = null;
 
+    /**
+     * Serializes dispatch of the discrete synthesized events (pointerdown, pointerup, click),
+     * whose picks resolve in GPU order, not canvas-event order. Replaced on teardown, so a pick
+     * that never resolves cannot stall the dispatches of a later boot.
+     */
+    private _dispatchChain: Promise<void> = Promise.resolve();
+
     private _app: AppBase | null = null;
 
     private _loadProgress = 0;
@@ -648,10 +655,9 @@ class AppElement extends AsyncElement {
         const { width, height } = this.app!.graphicsDevice;
         this._picker = new Picker(this.app!, width, height);
 
-        // Create bound handlers but don't attach them yet. The handlers pick asynchronously, so
-        // each is wrapped to discard the promise - a listener must not return one, and nothing
-        // awaits the result.
-        const listener = (handler: (event: PointerEvent) => Promise<void>): EventListener => {
+        // Create bound handlers but don't attach them yet. The move handler is async, so it is
+        // wrapped to discard the promise - a listener must not return one.
+        const listener = (handler: (event: PointerEvent) => void | Promise<void>): EventListener => {
             return (event: Event) => {
                 handler.call(this, event as PointerEvent);
             };
@@ -690,6 +696,9 @@ class AppElement extends AsyncElement {
         this._downPicks.clear();
         this._clickListened = false;
         this._lastClick = null;
+
+        // Replace the chain: a pick that never resolves must not stall a later boot's dispatches
+        this._dispatchChain = Promise.resolve();
     }
 
     /**
@@ -912,9 +921,23 @@ class AppElement extends AsyncElement {
         }
     }
 
-    private async _onPointerDown(event: PointerEvent) {
+    /**
+     * Appends a dispatch step to {@link _dispatchChain}. Must be called synchronously from the
+     * canvas event handler - the order of appends is what carries canvas-event order. A step
+     * that rejects is reported and released, so the steps queued behind it still dispatch.
+     *
+     * @param step - The dispatch work to run once every earlier step has finished.
+     */
+    private _chainDispatch(step: () => Promise<void>) {
+        this._dispatchChain = this._dispatchChain.then(step).catch((error) => {
+            console.error(error);
+        });
+    }
+
+    private _onPointerDown(event: PointerEvent) {
         if (!this._picker || !this.app) return;
 
+        // Picks stay concurrent - only the dispatch of the results is serialized
         const pick = this._pickNode(event);
 
         // A click concludes on the matching pointerup, which needs to know what the press
@@ -925,16 +948,18 @@ class AppElement extends AsyncElement {
             this._downPicks.set(event.pointerId, pick);
         }
 
-        const node = await pick;
-        if (!this._picker) return; // the element disconnected while the pick was in flight
+        this._chainDispatch(async () => {
+            const node = await pick;
+            if (!this._picker) return; // the element disconnected while the pick was in flight
 
-        const entityElement = this._elementWithListener(node, 'pointerdown');
-        if (entityElement) {
-            entityElement.dispatchEvent(new PointerEvent('pointerdown', event));
-        }
+            const entityElement = this._elementWithListener(node, 'pointerdown');
+            if (entityElement) {
+                entityElement.dispatchEvent(new PointerEvent('pointerdown', event));
+            }
+        });
     }
 
-    private async _onPointerUp(event: PointerEvent) {
+    private _onPointerUp(event: PointerEvent) {
         if (!this._picker || !this.app) return;
 
         // The press pick this release may conclude as a click. Claimed synchronously, so the
@@ -942,39 +967,49 @@ class AppElement extends AsyncElement {
         const downPick = this._downPicks.get(event.pointerId);
         this._downPicks.delete(event.pointerId);
 
-        const node = await this._pickNode(event);
-        if (!this._picker) return; // the element disconnected while the pick was in flight
+        const pick = this._pickNode(event);
 
-        const entityElement = this._elementWithListener(node, 'pointerup');
-        if (entityElement) {
-            entityElement.dispatchEvent(new PointerEvent('pointerup', event));
-        }
+        this._chainDispatch(async () => {
+            const node = await pick;
+            if (!this._picker) return; // the element disconnected while the pick was in flight
+
+            const entityElement = this._elementWithListener(node, 'pointerup');
+            if (entityElement) {
+                entityElement.dispatchEvent(new PointerEvent('pointerup', event));
+            }
+        });
 
         // A click fires where the DOM fires it: at the nearest common inclusive ancestor of
-        // what the press and the release picked, for the primary button only. The press pick
-        // may still be in flight - a quick tap resolves in pick order, not event order.
+        // what the press and the release picked, for the primary button only. Appended after
+        // the release's own step, so it dispatches after the pointerup that concludes it.
         if (!downPick || event.button !== 0) return;
-        const downNode = await downPick;
-        if (!this._picker) return;
-
-        const clickElement = this._elementWithListener(commonAncestor(downNode, node), 'click');
-        if (clickElement) {
-            const click = new PointerEvent('click', event);
-
-            // The init above copied pointerup's `detail`, which the Pointer Events spec fixes
-            // at 0 - but click is exempt: its detail is the click count, chained here as the
-            // platform chains it (same target, within the double-click window). Overridden
-            // with defineProperty because an event instance used as an init dict cannot have
-            // single fields replaced.
-            const time = performance.now();
-            const last = this._lastClick;
-            const count =
-                last && last.element === clickElement && time - last.time <= CLICK_CHAIN_MS ? last.count + 1 : 1;
-            this._lastClick = { element: clickElement, time, count };
-            Object.defineProperty(click, 'detail', { value: count });
-
-            clickElement.dispatchEvent(click);
-        }
+
+        this._chainDispatch(async () => {
+            // A rejected pick was already reported by the press or release step that awaited it;
+            // here it just means no click can conclude.
+            const picked = await Promise.all([downPick, pick]).catch(() => null);
+            if (!picked || !this._picker) return;
+
+            const [downNode, upNode] = picked;
+            const clickElement = this._elementWithListener(commonAncestor(downNode, upNode), 'click');
+            if (clickElement) {
+                const click = new PointerEvent('click', event);
+
+                // The init above copied pointerup's `detail`, which the Pointer Events spec fixes
+                // at 0 - but click is exempt: its detail is the click count, chained here as the
+                // platform chains it (same target, within the double-click window). Overridden
+                // with defineProperty because an event instance used as an init dict cannot have
+                // single fields replaced.
+                const time = performance.now();
+                const last = this._lastClick;
+                const count =
+                    last && last.element === clickElement && time - last.time <= CLICK_CHAIN_MS ? last.count + 1 : 1;
+                this._lastClick = { element: clickElement, time, count };
+                Object.defineProperty(click, 'detail', { value: count });
+
+                clickElement.dispatchEvent(click);
+            }
+        });
     }
 
     /**

package/src/components/button-component.ts

@@ -2,7 +2,7 @@ import type { ButtonComponent } from 'playcanvas';
 import { BUTTON_TRANSITION_MODE_SPRITE_CHANGE, BUTTON_TRANSITION_MODE_TINT, Color, Vec4 } from 'playcanvas';
 
 import { useAsset } from '../asset';
-import { getEntity, parseBool, parseColor, parseEnum, parseNumber, parseVec4 } from '../parse';
+import { parseBool, parseColor, parseEnum, parseNumber, parseVec4, resolveEntity } from '../parse';
 
 import { ComponentElement } from './component';
 
@@ -76,7 +76,9 @@ class ButtonComponentElement extends ComponentElement {
 
         // The image entity defaults to the button's own entity (which carries the image element)
         // when no explicit reference is provided.
-        const imageEntity = this._image ? getEntity(this._image) : this.closestEntity?.entity;
+        const imageEntity = this._image
+            ? resolveEntity(this._image, this, 'image', 'reference ignored')
+            : this.closestEntity?.entity;
         if (imageEntity) {
             data.imageEntity = imageEntity;
         }
@@ -127,22 +129,28 @@ class ButtonComponentElement extends ComponentElement {
     }
 
     /**
-     * Sets the reference (CSS selector, element id or entity name) to the `<pc-entity>` whose image
-     * element is used for visual transitions. Defaults to the button's own entity — inside a
-     * `<pc-model>`, that is the model's host entity, so supply an explicit reference to target a
-     * UI entity instead.
+     * Sets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the entity whose image element is used for visual transitions. An exact name
+     * resolves against the nearest enclosing entity first, then outward, then the document.
+     * Defaults to the button's own entity — inside a `<pc-model>`, that is the model's host
+     * entity, so supply an explicit reference to target a UI entity instead. A non-empty
+     * reference that does not resolve warns and is ignored.
      * @param value - The image entity reference.
      */
     set image(value: string) {
         this._image = value;
-        const entity = getEntity(value);
-        if (this.component && entity) {
-            this.component.imageEntity = entity;
+        if (this.component) {
+            const entity = resolveEntity(value, this, 'image', 'reference ignored');
+            if (entity) {
+                this.component.imageEntity = entity;
+            }
         }
     }
 
     /**
-     * Gets the reference to the `<pc-entity>` whose image element is used for visual transitions.
+     * Gets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the entity whose image element is used for visual transitions, or empty for
+     * the button's own entity.
      * @returns The image entity reference.
      */
     get image() {

package/src/components/joint-component.ts

@@ -1,7 +1,7 @@
 import type { JointComponent } from 'playcanvas';
 import { Vec2, Vec3 } from 'playcanvas';
 
-import { getEntity, parseBool, parseEnum, parseNumber, parseVec2, parseVec3 } from '../parse';
+import { parseBool, parseEnum, parseNumber, parseVec2, parseVec3, resolveEntity } from '../parse';
 
 import { ComponentElement } from './component';
 
@@ -25,7 +25,12 @@ export type MotionMode = 'locked' | 'limited' | 'free';
  * 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.
+ * space. A reference can name any entity-fronting element — `<pc-entity>`, `<pc-model>` or
+ * `<pc-node>`, so a ragdoll can join a model's own skeleton nodes by name — and a name resolves
+ * against the nearest enclosing entity first, then outward through the entity hierarchy, then the
+ * document, while a `#` selector resolves document-wide. A `<template>` prefab with one
+ * entity-fronting root can therefore wire its joints by name and stay self-contained when cloned.
+ * The underlying engine component is in alpha, so its API may change.
  *
  * @elementSummary The `<pc-joint>` element constrains two rigid bodies to each other — a hinged
  * door, a swinging chain, a sliding drawer. Its entity's transform is the joint frame, and
@@ -210,8 +215,8 @@ class JointComponentElement extends ComponentElement {
             breakImpulse: this._breakImpulse,
             enableCollision: this._enableCollision,
             enableLimits: this._enableLimits,
-            entityA: getEntity(this._entityA),
-            entityB: getEntity(this._entityB),
+            entityA: resolveEntity(this._entityA, this, 'entity-a', 'constraint not created'),
+            entityB: resolveEntity(this._entityB, this, 'entity-b', 'constraint not created'),
             limits: this._limits,
             linearDamping: this._linearDamping,
             linearEquilibrium: this._linearEquilibrium,
@@ -495,20 +500,24 @@ class JointComponentElement extends ComponentElement {
     }
 
     /**
-     * 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.
+     * Sets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the element providing the first constrained body. An exact name resolves
+     * against the nearest enclosing entity first, then outward, then the document. The reference
+     * resolves when it is set, so an entity created later is picked up by setting the attribute
+     * again. A non-empty reference that does not resolve warns, naming which of the two causes it
+     * hit.
      * @param value - The first body's entity reference.
      */
     set entityA(value: string) {
         this._entityA = value;
         if (this.component) {
-            this.component.entityA = getEntity(value);
+            this.component.entityA = resolveEntity(value, this, 'entity-a', 'constraint not created');
         }
     }
 
     /**
-     * Gets the reference to the `<pc-entity>` providing the first constrained body.
+     * Gets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the element providing the first constrained body.
      * @returns The first body's entity reference.
      */
     get entityA() {
@@ -516,21 +525,26 @@ class JointComponentElement extends ComponentElement {
     }
 
     /**
-     * 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.
+     * Sets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the element providing the second constrained body, or empty to constrain the
+     * first body to a fixed point in world space. An exact name resolves against the nearest
+     * enclosing entity first, then outward, then the document. The reference resolves when it is
+     * set, so an entity created later is picked up by setting the attribute again. A non-empty
+     * reference that does not resolve warns; an empty one is the documented world-space case and
+     * stays silent.
      * @param value - The second body's entity reference.
      */
     set entityB(value: string) {
         this._entityB = value;
         if (this.component) {
-            this.component.entityB = getEntity(value);
+            this.component.entityB = resolveEntity(value, this, 'entity-b', 'constraint not created');
         }
     }
 
     /**
-     * Gets the reference to the `<pc-entity>` providing the second constrained body.
+     * Gets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the element providing the second constrained body, or empty for the
+     * world-space case.
      * @returns The second body's entity reference.
      */
     get entityB() {