@playcanvas/web-components 0.19.0 → 0.20.0

package/src/components/script-component.ts

@@ -3,7 +3,9 @@ import { Color, Quat, Vec2, Vec3, Vec4 } from 'playcanvas';
 
 import { useAsset } from '../asset';
 import {
+    findEntityElement,
     getEntity,
+    idHint,
     parseBool,
     parseColor,
     parseComponents,
@@ -11,7 +13,8 @@ import {
     parseQuat,
     parseVec2,
     parseVec3,
-    parseVec4
+    parseVec4,
+    unresolvedCause
 } from '../parse';
 
 import { ComponentElement } from './component';
@@ -107,10 +110,11 @@ const camelToKebab = (name: string): string => {
 
 /**
  * A conversion applied to a script attribute value carrying an explicit type prefix. Receives the
- * text after the prefix plus the raw value, and returns the raw value (having warned) when it
- * cannot resolve or parse it — callers rely on that identity to tell failure from success.
+ * text after the prefix, the raw value, and the element the value is declared under — which
+ * scopes entity references — and returns the raw value (having warned) when it cannot resolve or
+ * parse it — callers rely on that identity to tell failure from success.
  */
-type Conversion = (rest: string, raw: string) => any;
+type Conversion = (rest: string, raw: string, from: Element) => any;
 
 /**
  * Resolves an `asset:` prefix to the Asset created by the `pc-asset` element with that id.
@@ -128,18 +132,25 @@ const assetConversion: Conversion = (rest, raw) => {
 };
 
 /**
- * Resolves an `entity:` prefix to the Entity backing a `pc-entity` element. The reference can be a
- * CSS selector, an element id or an entity name.
+ * Resolves an `entity:` prefix to the Entity backing a `pc-entity`, `pc-model` or `pc-node`
+ * element. The reference is a name — resolved against the nearest enclosing entity first, then
+ * outward, then the document — or a document-wide `#` selector. The failure warning names which
+ * of the three causes ({@link unresolvedCause}) it hit.
  * @param rest - The entity reference.
  * @param raw - The raw value, returned unchanged when the reference does not resolve.
+ * @param from - The element the value is declared under, which scopes the reference.
  * @returns The entity, or `raw`.
  */
-const entityConversion: Conversion = (rest, raw) => {
-    const entity = getEntity(rest);
+const entityConversion: Conversion = (rest, raw, from) => {
+    const entity = getEntity(rest, from);
     if (entity) {
         return entity;
     }
-    console.warn(`Unable to resolve '${raw}' in script attributes - no pc-entity found matching '${rest}'.`);
+    const element = findEntityElement(rest, from);
+    const hint = element ? '' : idHint(rest, 'entity:');
+    console.warn(
+        `Unable to resolve '${raw}' in script attributes - ${unresolvedCause(element)}.${hint ? ` ${hint}` : ''}`
+    );
     return raw;
 };
 
@@ -298,8 +309,10 @@ class ScriptComponentElement extends ComponentElement {
     /**
      * Recursively converts raw attribute data into proper PlayCanvas types. Supported conversions:
      * - "asset:id" → the Asset created by the `pc-asset` element with that id
-     * - "entity:ref" → the Entity backing a `pc-entity` element. The reference can be a CSS
-     *   selector, an element id or an entity name.
+     * - "entity:ref" → the Entity backing a `pc-entity`, `pc-model` or `pc-node` element. The
+     *   reference is a name, resolved against this element's nearest enclosing entity first,
+     *   then outward, then the document — or a document-wide `#` selector (`entity:#id`). A bare
+     *   value is always a name, never an id.
      * - "vec2:1 2" → new Vec2(1, 2)
      * - "vec3:1 2 3" → new Vec3(1, 2, 3)
      * - "vec4:1 2 3 4" → new Vec4(1, 2, 3, 4)
@@ -313,7 +326,7 @@ class ScriptComponentElement extends ComponentElement {
     private convertAttributes(item: any): any {
         if (typeof item === 'string') {
             const match = matchConversion(item);
-            return match ? match.convert(match.rest, item) : item;
+            return match ? match.convert(match.rest, item, this) : item;
         }
 
         if (Array.isArray(item)) {

package/src/components/script-instance.ts

@@ -15,7 +15,9 @@ import { parseBool } from '../parse';
  *   Values are parsed according to the type of the attribute's current value — initially the
  *   script's declared default (numbers, booleans, strings, Vec2/3/4, Color, Quat as Euler
  *   angles) — and the `asset:`/`entity:`/`vec2:`/`vec3:`/`vec4:`/`color:` prefixes may be used
- *   to be explicit.
+ *   to be explicit. An `entity:` reference is an entity name — resolved against the nearest
+ *   enclosing entity first, then outward, then the document — or a document-wide `#` selector
+ *   (`entity:#id`); a bare value is always a name, never an element id.
  * - **The `attributes` JSON attribute**: an object supporting nested structures and attribute
  *   names that collide with reserved HTML attribute names (e.g. `title`).
  *
@@ -31,7 +33,8 @@ import { parseBool } from '../parse';
  *
  * @elementSummary The `<pc-script-instance>` element attaches one script class, named by `name`, to
  * the entity of its parent `<pc-script>`. Its other attributes set script attributes of the same
- * name, and `attributes` takes a JSON object instead. Must be a direct child of `<pc-script>`.
+ * name, and `attributes` takes a JSON object instead. An `entity:` value is an entity name —
+ * write `entity:#id` for an element id. Must be a direct child of `<pc-script>`.
  *
  * @fires {CustomEvent} scriptattributeschange - Fired when the script's attributes change. The
  * `detail` carries the new `attributes` object. Bubbles.
@@ -54,9 +57,11 @@ class ScriptInstanceElement extends AsyncElement {
     /**
      * Sets the attributes of the script as an object. Values are converted with the same rules
      * as the `attributes` attribute: `asset:`/`entity:` references and `vec2:`/`vec3:`/`vec4:`/
-     * `color:` prefixed strings are resolved, and a plain numeric array is converted to the
-     * type of the attribute it targets when that attribute currently holds a Vec2, Vec3, Vec4
-     * or Color.
+     * `color:` prefixed strings are resolved (an entity name against the nearest enclosing
+     * entity first, then outward, then the document — or a document-wide `#` selector; a bare
+     * value is always a name, never an element id), and a plain numeric array is converted to
+     * the type of the attribute it targets when that attribute currently holds a Vec2, Vec3,
+     * Vec4 or Color.
      * @param value - The attributes of the script.
      */
     set scriptAttributes(value: Record<string, any>) {
@@ -70,7 +75,10 @@ class ScriptInstanceElement extends AsyncElement {
     }
 
     /**
-     * Gets the attributes of the script.
+     * Gets 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.
      * @returns The attributes of the script.
      */
     get scriptAttributes(): Record<string, any> {

package/src/components/scroll-view-component.ts

@@ -8,7 +8,7 @@ import {
     Vec2
 } from 'playcanvas';
 
-import { getEntity, parseBool, parseEnum, parseNumber, parseVec2 } from '../parse';
+import { parseBool, parseEnum, parseNumber, parseVec2, resolveEntity } from '../parse';
 
 import { ComponentElement } from './component';
 
@@ -82,22 +82,22 @@ class ScrollViewComponentElement extends ComponentElement {
             verticalScrollbarVisibility: visibilities.get(this._verticalScrollbarVisibility)
         };
 
-        const viewport = getEntity(this._viewport);
+        const viewport = resolveEntity(this._viewport, this, 'viewport', 'reference ignored');
         if (viewport) {
             data.viewportEntity = viewport;
         }
 
-        const content = getEntity(this._content);
+        const content = resolveEntity(this._content, this, 'content', 'reference ignored');
         if (content) {
             data.contentEntity = content;
         }
 
-        const horizontalScrollbar = getEntity(this._horizontalScrollbar);
+        const horizontalScrollbar = resolveEntity(this._horizontalScrollbar, this, 'horizontal-scrollbar', 'reference ignored');
         if (horizontalScrollbar) {
             data.horizontalScrollbarEntity = horizontalScrollbar;
         }
 
-        const verticalScrollbar = getEntity(this._verticalScrollbar);
+        const verticalScrollbar = resolveEntity(this._verticalScrollbar, this, 'vertical-scrollbar', 'reference ignored');
         if (verticalScrollbar) {
             data.verticalScrollbarEntity = verticalScrollbar;
         }
@@ -294,20 +294,25 @@ class ScrollViewComponentElement extends ComponentElement {
     }
 
     /**
-     * Sets the reference (CSS selector, element id or entity name) to the `<pc-entity>` used as the
-     * viewport, which clips the content to the scroll view's bounds.
+     * Sets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the entity used as the viewport, which clips the content to the scroll view's
+     * bounds. An exact name resolves against the nearest enclosing entity first, then outward,
+     * then the document. A non-empty reference that does not resolve warns and is ignored.
      * @param value - The viewport entity reference.
      */
     set viewport(value: string) {
         this._viewport = value;
-        const entity = getEntity(value);
-        if (this.component && entity) {
-            this.component.viewportEntity = entity;
+        if (this.component) {
+            const entity = resolveEntity(value, this, 'viewport', 'reference ignored');
+            if (entity) {
+                this.component.viewportEntity = entity;
+            }
         }
     }
 
     /**
-     * Gets the reference to the `<pc-entity>` used as the viewport.
+     * Gets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the entity used as the viewport.
      * @returns The viewport entity reference.
      */
     get viewport() {
@@ -315,20 +320,25 @@ class ScrollViewComponentElement extends ComponentElement {
     }
 
     /**
-     * Sets the reference (CSS selector, element id or entity name) to the `<pc-entity>` used as the
-     * content, which is moved as the scroll view is scrolled.
+     * Sets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the entity used as the content, which is moved as the scroll view is
+     * scrolled. An exact name resolves against the nearest enclosing entity first, then outward,
+     * then the document. A non-empty reference that does not resolve warns and is ignored.
      * @param value - The content entity reference.
      */
     set content(value: string) {
         this._content = value;
-        const entity = getEntity(value);
-        if (this.component && entity) {
-            this.component.contentEntity = entity;
+        if (this.component) {
+            const entity = resolveEntity(value, this, 'content', 'reference ignored');
+            if (entity) {
+                this.component.contentEntity = entity;
+            }
         }
     }
 
     /**
-     * Gets the reference to the `<pc-entity>` used as the content.
+     * Gets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the entity used as the content.
      * @returns The content entity reference.
      */
     get content() {
@@ -336,20 +346,25 @@ class ScrollViewComponentElement extends ComponentElement {
     }
 
     /**
-     * Sets the reference (CSS selector, element id or entity name) to the `<pc-entity>` containing
-     * the horizontal `<pc-scrollbar>`.
+     * Sets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the entity containing the horizontal `<pc-scrollbar>`. An exact name resolves
+     * against the nearest enclosing entity first, then outward, then the document. A non-empty
+     * reference that does not resolve warns and is ignored.
      * @param value - The horizontal scrollbar entity reference.
      */
     set horizontalScrollbar(value: string) {
         this._horizontalScrollbar = value;
-        const entity = getEntity(value);
-        if (this.component && entity) {
-            this.component.horizontalScrollbarEntity = entity;
+        if (this.component) {
+            const entity = resolveEntity(value, this, 'horizontal-scrollbar', 'reference ignored');
+            if (entity) {
+                this.component.horizontalScrollbarEntity = entity;
+            }
         }
     }
 
     /**
-     * Gets the reference to the `<pc-entity>` containing the horizontal scrollbar.
+     * Gets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the entity containing the horizontal scrollbar.
      * @returns The horizontal scrollbar entity reference.
      */
     get horizontalScrollbar() {
@@ -357,20 +372,25 @@ class ScrollViewComponentElement extends ComponentElement {
     }
 
     /**
-     * Sets the reference (CSS selector, element id or entity name) to the `<pc-entity>` containing
-     * the vertical `<pc-scrollbar>`.
+     * Sets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the entity containing the vertical `<pc-scrollbar>`. An exact name resolves
+     * against the nearest enclosing entity first, then outward, then the document. A non-empty
+     * reference that does not resolve warns and is ignored.
      * @param value - The vertical scrollbar entity reference.
      */
     set verticalScrollbar(value: string) {
         this._verticalScrollbar = value;
-        const entity = getEntity(value);
-        if (this.component && entity) {
-            this.component.verticalScrollbarEntity = entity;
+        if (this.component) {
+            const entity = resolveEntity(value, this, 'vertical-scrollbar', 'reference ignored');
+            if (entity) {
+                this.component.verticalScrollbarEntity = entity;
+            }
         }
     }
 
     /**
-     * Gets the reference to the `<pc-entity>` containing the vertical scrollbar.
+     * Gets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the entity containing the vertical scrollbar.
      * @returns The vertical scrollbar entity reference.
      */
     get verticalScrollbar() {

package/src/components/scrollbar-component.ts

@@ -1,7 +1,7 @@
 import type { ScrollbarComponent } from 'playcanvas';
 import { ORIENTATION_HORIZONTAL, ORIENTATION_VERTICAL } from 'playcanvas';
 
-import { getEntity, parseEnum, parseNumber } from '../parse';
+import { parseEnum, parseNumber, resolveEntity } from '../parse';
 
 import { ComponentElement } from './component';
 
@@ -45,7 +45,7 @@ class ScrollbarComponentElement extends ComponentElement {
             handleSize: this._handleSize
         };
 
-        const handle = getEntity(this._handle);
+        const handle = resolveEntity(this._handle, this, 'handle', 'reference ignored');
         if (handle) {
             data.handleEntity = handle;
         }
@@ -120,20 +120,25 @@ class ScrollbarComponentElement extends ComponentElement {
     }
 
     /**
-     * Sets the reference (CSS selector, element id or entity name) to the `<pc-entity>` used as the
-     * scrollbar handle.
+     * Sets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the entity used as the scrollbar handle. An exact name resolves against the
+     * nearest enclosing entity first, then outward, then the document. A non-empty reference that
+     * does not resolve warns and is ignored.
      * @param value - The handle entity reference.
      */
     set handle(value: string) {
         this._handle = value;
-        const entity = getEntity(value);
-        if (this.component && entity) {
-            this.component.handleEntity = entity;
+        if (this.component) {
+            const entity = resolveEntity(value, this, 'handle', 'reference ignored');
+            if (entity) {
+                this.component.handleEntity = entity;
+            }
         }
     }
 
     /**
-     * Gets the reference to the `<pc-entity>` used as the scrollbar handle.
+     * Gets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the entity used as the scrollbar handle.
      * @returns The handle entity reference.
      */
     get handle() {

package/src/parse.ts

@@ -12,8 +12,13 @@
  * - `parseBool` and `parseTags` take no attribute name, because every value is valid for them and
  *   so they never warn.
  *
- * `getEntity` is the exception: it resolves a reference to a live entity rather than parsing a
- * literal, and returns `null` instead of falling back to a default.
+ * `findEntityElement` and `getEntity` are the exceptions: they resolve a reference rather than
+ * parsing a literal, and return `null` instead of falling back to a default. A reference
+ * beginning with `#` is a document-wide selector (an element id, or any selector rooted in one);
+ * anything else is an entity name, resolved lexically through the entity hierarchy first and
+ * against the document after — never as a selector or an id. They also do not warn - what an
+ * unresolved reference means depends on the element holding it - so elements report through
+ * `resolveEntity`, which takes that meaning as parameters.
  */
 
 import type { Entity } from 'playcanvas';
@@ -324,32 +329,224 @@ export const parseVec4 = <T extends Vec4 | null>(
 };
 
 /**
- * Resolves a reference string to the {@link Entity} backing a `<pc-entity>` element. The reference
- * can be a CSS selector (e.g. `#my-id`, `pc-entity[name="Foo"]`), a bare element id, or a bare
- * entity name. Returns `null` if no matching element (or backing entity) is found.
+ * Runs querySelector, absorbing the SyntaxError an unparseable selector throws - references are
+ * arbitrary author text, so a lookup must fail to `null`, never throw.
+ *
+ * @param selector - The selector to query.
+ * @returns The matched element, or `null`.
+ */
+const query = (selector: string): Element | null => {
+    try {
+        return document.querySelector(selector);
+    } catch {
+        return null;
+    }
+};
+
+/**
+ * Runs a lookup against one scope, checking the scope element itself before its subtree — a
+ * reference deep in a cloned prefab must be able to name the prefab's root. Absorbs the
+ * SyntaxError of an invalid selector like {@link query}: escaping quotes and backslashes does not
+ * make arbitrary text a valid CSS string (a reference containing a newline still throws), so a
+ * lookup must fail to `null`, never throw.
+ *
+ * @param scope - The element whose inclusive subtree to search.
+ * @param selector - The selector to query.
+ * @returns The matched element, or `null`.
+ */
+const queryScope = (scope: Element, selector: string): Element | null => {
+    try {
+        return scope.matches(selector) ? scope : scope.querySelector(selector);
+    } catch {
+        return null;
+    }
+};
+
+/**
+ * Reads the entity a resolved element is backing, through the `entity` accessor every
+ * entity-fronting element exposes. `null` for no element, and for an element backing nothing.
+ *
+ * @param element - The element to read, or `null`.
+ * @returns The backing entity, or `null`.
+ */
+const entityOf = (element: Element | null): Entity | null => {
+    return (element as { entity?: Entity } | null)?.entity ?? null;
+};
+
+/**
+ * The elements that front an entity: what a bare name can resolve to, and the scopes of the
+ * lexical name lookup.
+ */
+const ENTITY_KINDS = ['pc-entity', 'pc-model', 'pc-node'] as const;
+
+/**
+ * The entity-fronting elements as one selector, for the scope walk.
+ */
+const ENTITY_SCOPES = ENTITY_KINDS.join(', ');
+
+/**
+ * Resolves a reference string to the element it names. The grammar is closed — every reference
+ * has exactly one interpretation:
+ *
+ * - A reference beginning with `#` is a document-wide CSS selector — an element id (`#body`), or
+ *   any selector rooted in one (`#hud pc-entity`). It is authoritative: the name lookup never
+ *   runs for it, so an unusually named entity cannot shadow it.
+ * - Any other reference is the name of an entity-fronting element (`<pc-entity>`, `<pc-model>` or
+ *   `<pc-node>` — for a node, the glTF node name it binds), and nothing else. A bare reference is
+ *   never interpreted as a selector or an element id, so adding or renaming elements can never
+ *   change which form it takes.
+ *
+ * When `from` is supplied, a name resolves lexically first: the closest entity-fronting
+ * ancestor's inclusive subtree, then each outer entity-fronting ancestor, then the containing
+ * `<pc-app>`, then the document. This is what lets a `<template>` prefab reference its own
+ * entities by name — every clone resolves within itself before a document-wide lookup could reach
+ * an earlier clone — provided the prefab has a single entity-fronting root to be the enclosing
+ * scope.
+ *
+ * Separate from {@link getEntity} so a caller reporting a failure can tell the causes apart
+ * ({@link unresolvedCause} words them): nothing in the document matches the reference, or
+ * something matches but is not backing an entity (yet, or ever).
  *
  * @param ref - The reference string to resolve.
- * @returns The resolved entity, or `null`.
+ * @param from - The element resolving the reference, whose entity-fronting ancestors scope the
+ * name lookup. Omitted, the name lookup is document-wide only.
+ * @returns The matched element, or `null`.
  * @internal
  */
-export const getEntity = (ref: string): Entity | null => {
+export const findEntityElement = (ref: string, from?: Element): Element | null => {
     if (!ref) {
         return null;
     }
 
-    let element: Element | null = null;
+    // A '#' reference is document-wide and bypasses the name lookup entirely - an entity named
+    // '#body' must never shadow the element whose id is 'body'.
+    if (ref.startsWith('#')) {
+        return query(ref);
+    }
 
-    // Try the reference as a CSS selector. An invalid selector (e.g. a bare name containing
-    // spaces) throws, in which case we fall back to id/name lookups below.
-    try {
-        element = document.querySelector(ref);
-    } catch {
-        element = null;
+    // The name lands inside a quoted CSS string, so its quotes and backslashes are escaped -
+    // a name like `say "hi"` must resolve, not turn the lookup into a SyntaxError.
+    const escaped = ref.replace(/["\\]/g, '\\$&');
+    const nameSelector = ENTITY_KINDS.map(kind => `${kind}[name="${escaped}"]`).join(', ');
+
+    if (from) {
+        let scope = from.parentElement?.closest(ENTITY_SCOPES);
+        while (scope) {
+            const element = queryScope(scope, nameSelector);
+            if (element) {
+                return element;
+            }
+            scope = scope.parentElement?.closest(ENTITY_SCOPES);
+        }
+
+        const app = from.parentElement?.closest('pc-app');
+        if (app) {
+            const element = queryScope(app, nameSelector);
+            if (element) {
+                return element;
+            }
+        }
     }
 
+    return query(nameSelector);
+};
+
+/**
+ * Resolves a reference string to the {@link Entity} backing an entity-fronting element
+ * (`<pc-entity>`, `<pc-model>` or `<pc-node>`). The reference is a name — resolved lexically
+ * through the entity hierarchy first when `from` is supplied — or a document-wide `#` selector
+ * ({@link findEntityElement} details the grammar and order). Returns `null` if no matching
+ * element (or backing entity) is found.
+ *
+ * @param ref - The reference string to resolve.
+ * @param from - The element resolving the reference, whose entity-fronting ancestors scope the
+ * name lookup. Omitted, the name lookup is document-wide only.
+ * @returns The resolved entity, or `null`.
+ * @internal
+ */
+export const getEntity = (ref: string, from?: Element): Entity | null => {
+    return entityOf(findEntityElement(ref, from));
+};
+
+/**
+ * Describes why a non-empty reference did not resolve, for a warning. Three causes, because they
+ * have three different fixes: nothing matches (usually a typo), the matched element is not backing
+ * an entity yet (usually timing - a `pc-node` whose asset has not loaded - so resolving again
+ * later can work), or the matched element can never back one (the reference points at the wrong
+ * element, so only correcting it can). Capability is the `entity` accessor every entity-backing
+ * element inherits from EntityBaseElement.
+ *
+ * @param element - The element the reference matched, or `null` when nothing did.
+ * @returns The cause, phrased to follow `could not resolve ... -`.
+ * @internal
+ */
+export const unresolvedCause = (element: Element | null): string => {
     if (!element) {
-        element = document.getElementById(ref) ?? document.querySelector(`pc-entity[name="${ref}"]`);
+        return 'nothing in the document matches it';
     }
+    const tag = `<${element.tagName.toLowerCase()}>`;
+    return 'entity' in element
+        ? `${tag} matches it but is not backing an entity yet`
+        : `${tag} matches it but cannot back an entity`;
+};
 
-    return (element as { entity?: Entity } | null)?.entity ?? null;
+/**
+ * Builds the migration pointer for a bare reference that names nothing but matches the id of an
+ * entity-fronting element - it was almost certainly meant as an id, so point at the form that
+ * expresses it, escaped so the suggestion actually parses as a selector (an id like `a:b` must
+ * be written `#a\:b`). Empty when the reference is already a `#` form, matches no id, or the id
+ * belongs to an element that could never back an entity - suggesting it would only trade this
+ * warning for the wrong-target one.
+ *
+ * @param ref - The unresolved reference.
+ * @param prefix - Text the suggested form must carry in the caller's syntax (e.g. `entity:`).
+ * @returns The advice sentence, or an empty string.
+ * @internal
+ */
+export const idHint = (ref: string, prefix = ''): string => {
+    const match = !ref.startsWith('#') && document.getElementById(ref);
+    return match && 'entity' in match
+        ? `A bare reference is a name - write '${prefix}#${CSS.escape(ref)}' to reference the element with that id.`
+        : '';
+};
+
+/**
+ * Resolves a reference string to the {@link Entity} backing an entity-fronting element, scoped to
+ * the resolving element ({@link findEntityElement} details the order) and warning when a
+ * non-empty reference does not resolve - otherwise the reference fails silently, invisible
+ * except through the behavior it should have driven. The message names which of the three causes
+ * ({@link unresolvedCause}) it hit, and advises reassigning later only when that can work.
+ *
+ * An empty reference stays silent: it is the unset state of an optional attribute, and on some
+ * elements (`pc-joint` `entity-b`, `pc-button` `image`) a documented value of its own.
+ *
+ * @param ref - The reference string to resolve.
+ * @param from - The element resolving the reference; scopes the lookup and names the message.
+ * @param attribute - The attribute being resolved, for the message.
+ * @param consequence - What the unresolved reference means for the element, for the message.
+ * @returns The resolved entity, or `null`.
+ * @internal
+ */
+export const resolveEntity = (ref: string, from: Element, attribute: string, consequence: string): Entity | null => {
+    if (!ref) {
+        return null;
+    }
+
+    const element = findEntityElement(ref, from);
+    const entity = entityOf(element);
+    if (!entity) {
+        let advice = `Assign ${attribute} again once the entity exists.`;
+        if (element && !('entity' in element)) {
+            advice = `Point ${attribute} at a pc-entity, pc-model or pc-node instead.`;
+        } else if (!element) {
+            const hint = idHint(ref);
+            if (hint) {
+                advice = hint;
+            }
+        }
+        console.warn(
+            `${from.tagName.toLowerCase()} could not resolve ${attribute} '${ref}' - ${unresolvedCause(element)} - ${consequence}. ${advice}`
+        );
+    }
+    return entity;
 };