From f4db74554e21cecb62c3cce8981d874e7735a346 Mon Sep 17 00:00:00 2001
From: Will Eastcott <will@playcanvas.com>
Date: Mon, 31 Aug 2026 00:07:09 +0100
Subject: [PATCH 1/2] Resolve bare entity names against the nearest enclosing
 scope

An exact entity-name match now resolves lexically through the entity
hierarchy first - the closest entity-fronting ancestor's inclusive
subtree, then each outer one, then the containing pc-app - before the
existing document-wide selector/id/name lookup runs unchanged as the
fallback. A <template> prefab with one root pc-entity can therefore
wire its joints and script attributes by bare name and stay
self-contained when cloned: every clone's references bind within
itself, where the document-wide lookup bound them all to the first
instance.

The scoped phase queries only pc-entity[name=...], so selectors and
ids keep their document-wide meaning and a non-entity element can
never divert it. resolveEntity now takes the resolving element instead
of a tag string - it scopes the lookup and names the message - and
resolves once instead of twice on the failure path. All warning
messages are byte-identical.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 src/components/button-component.ts            |  12 +-
 src/components/joint-component.ts             |  27 +--
 src/components/script-component.ts            |  26 +--
 src/components/script-instance.ts             |  10 +-
 src/components/scroll-view-component.ts       |  46 +++--
 src/components/scrollbar-component.ts         |   8 +-
 src/parse.ts                                  | 110 +++++++++---
 .../components/joint-component.test.ts        |  23 +++
 .../components/script-component.test.ts       |  26 +++
 test/integration/get-entity.test.ts           | 161 +++++++++++++++++-
 test/integration/template-clone.test.ts       |  48 ++++++
 11 files changed, 412 insertions(+), 85 deletions(-)

diff --git a/src/components/button-component.ts b/src/components/button-component.ts
index cc09dac..25416ad 100644
--- a/src/components/button-component.ts
+++ b/src/components/button-component.ts
@@ -77,7 +77,7 @@ 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
-            ? resolveEntity(this._image, 'pc-button', 'image', 'reference ignored')
+            ? resolveEntity(this._image, this, 'image', 'reference ignored')
             : this.closestEntity?.entity;
         if (imageEntity) {
             data.imageEntity = imageEntity;
@@ -130,15 +130,17 @@ 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. A non-empty reference that does not resolve warns and is ignored.
+     * element is used for visual transitions. An exact entity 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;
         if (this.component) {
-            const entity = resolveEntity(value, 'pc-button', 'image', 'reference ignored');
+            const entity = resolveEntity(value, this, 'image', 'reference ignored');
             if (entity) {
                 this.component.imageEntity = entity;
             }
diff --git a/src/components/joint-component.ts b/src/components/joint-component.ts
index 221f64d..92f4a79 100644
--- a/src/components/joint-component.ts
+++ b/src/components/joint-component.ts
@@ -25,7 +25,10 @@ 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. An exact entity-name reference resolves against the nearest enclosing entity first, then
+ * outward through the entity hierarchy, then the document — so a `<template>` prefab with one root
+ * `<pc-entity>` can 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 +213,8 @@ class JointComponentElement extends ComponentElement {
             breakImpulse: this._breakImpulse,
             enableCollision: this._enableCollision,
             enableLimits: this._enableLimits,
-            entityA: resolveEntity(this._entityA, 'pc-joint', 'entity-a', 'constraint not created'),
-            entityB: resolveEntity(this._entityB, 'pc-joint', 'entity-b', 'constraint not created'),
+            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,
@@ -496,15 +499,16 @@ 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. A non-empty reference that does not
-     * resolve warns, naming which of the two causes it hit.
+     * the first constrained body. An exact entity 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 = resolveEntity(value, 'pc-joint', 'entity-a', 'constraint not created');
+            this.component.entityA = resolveEntity(value, this, 'entity-a', 'constraint not created');
         }
     }
 
@@ -519,15 +523,16 @@ 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. A non-empty reference that does not resolve warns; an empty one
-     * is the documented world-space case and stays silent.
+     * space. An exact entity 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 = resolveEntity(value, 'pc-joint', 'entity-b', 'constraint not created');
+            this.component.entityB = resolveEntity(value, this, 'entity-b', 'constraint not created');
         }
     }
 
diff --git a/src/components/script-component.ts b/src/components/script-component.ts
index 07ec782..353ebe9 100644
--- a/src/components/script-component.ts
+++ b/src/components/script-component.ts
@@ -109,10 +109,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.
@@ -131,18 +132,22 @@ 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. The failure warning names which of the three
- * causes ({@link unresolvedCause}) it hit.
+ * CSS selector, an element id or an entity name — an exact entity name resolves against the
+ * nearest enclosing entity first, then outward, then the document. 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 - ${unresolvedCause(findEntityElement(rest))}.`);
+    console.warn(
+        `Unable to resolve '${raw}' in script attributes - ${unresolvedCause(findEntityElement(rest, from))}.`
+    );
     return raw;
 };
 
@@ -302,7 +307,8 @@ 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.
+     *   selector, an element id or an entity name; an exact entity name resolves against this
+     *   element's nearest enclosing entity first, then outward, then the document.
      * - "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)
@@ -316,7 +322,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)) {
diff --git a/src/components/script-instance.ts b/src/components/script-instance.ts
index 4ed9d75..eaec03b 100644
--- a/src/components/script-instance.ts
+++ b/src/components/script-instance.ts
@@ -15,7 +15,8 @@ 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 naming an exact entity name resolves against the
+ *   nearest enclosing entity first, then outward, then the document.
  * - **The `attributes` JSON attribute**: an object supporting nested structures and attribute
  *   names that collide with reserved HTML attribute names (e.g. `title`).
  *
@@ -54,9 +55,10 @@ 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 exact entity name against the nearest enclosing
+     * entity first, then outward, then the document), 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>) {
diff --git a/src/components/scroll-view-component.ts b/src/components/scroll-view-component.ts
index 4041b66..973a9cc 100644
--- a/src/components/scroll-view-component.ts
+++ b/src/components/scroll-view-component.ts
@@ -82,32 +82,22 @@ class ScrollViewComponentElement extends ComponentElement {
             verticalScrollbarVisibility: visibilities.get(this._verticalScrollbarVisibility)
         };
 
-        const viewport = resolveEntity(this._viewport, 'pc-scroll-view', 'viewport', 'reference ignored');
+        const viewport = resolveEntity(this._viewport, this, 'viewport', 'reference ignored');
         if (viewport) {
             data.viewportEntity = viewport;
         }
 
-        const content = resolveEntity(this._content, 'pc-scroll-view', 'content', 'reference ignored');
+        const content = resolveEntity(this._content, this, 'content', 'reference ignored');
         if (content) {
             data.contentEntity = content;
         }
 
-        const horizontalScrollbar = resolveEntity(
-            this._horizontalScrollbar,
-            'pc-scroll-view',
-            'horizontal-scrollbar',
-            'reference ignored'
-        );
+        const horizontalScrollbar = resolveEntity(this._horizontalScrollbar, this, 'horizontal-scrollbar', 'reference ignored');
         if (horizontalScrollbar) {
             data.horizontalScrollbarEntity = horizontalScrollbar;
         }
 
-        const verticalScrollbar = resolveEntity(
-            this._verticalScrollbar,
-            'pc-scroll-view',
-            'vertical-scrollbar',
-            'reference ignored'
-        );
+        const verticalScrollbar = resolveEntity(this._verticalScrollbar, this, 'vertical-scrollbar', 'reference ignored');
         if (verticalScrollbar) {
             data.verticalScrollbarEntity = verticalScrollbar;
         }
@@ -305,14 +295,15 @@ 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. A non-empty reference that
-     * does not resolve warns and is ignored.
+     * viewport, which clips the content to the scroll view's bounds. An exact entity 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;
         if (this.component) {
-            const entity = resolveEntity(value, 'pc-scroll-view', 'viewport', 'reference ignored');
+            const entity = resolveEntity(value, this, 'viewport', 'reference ignored');
             if (entity) {
                 this.component.viewportEntity = entity;
             }
@@ -329,14 +320,15 @@ 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. A non-empty reference that does not
-     * resolve warns and is ignored.
+     * content, which is moved as the scroll view is scrolled. An exact entity 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;
         if (this.component) {
-            const entity = resolveEntity(value, 'pc-scroll-view', 'content', 'reference ignored');
+            const entity = resolveEntity(value, this, 'content', 'reference ignored');
             if (entity) {
                 this.component.contentEntity = entity;
             }
@@ -353,14 +345,15 @@ class ScrollViewComponentElement extends ComponentElement {
 
     /**
      * Sets the reference (CSS selector, element id or entity name) to the `<pc-entity>` containing
-     * the horizontal `<pc-scrollbar>`. A non-empty reference that does not resolve warns and is
-     * ignored.
+     * the horizontal `<pc-scrollbar>`. An exact entity 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;
         if (this.component) {
-            const entity = resolveEntity(value, 'pc-scroll-view', 'horizontal-scrollbar', 'reference ignored');
+            const entity = resolveEntity(value, this, 'horizontal-scrollbar', 'reference ignored');
             if (entity) {
                 this.component.horizontalScrollbarEntity = entity;
             }
@@ -377,14 +370,15 @@ class ScrollViewComponentElement extends ComponentElement {
 
     /**
      * Sets the reference (CSS selector, element id or entity name) to the `<pc-entity>` containing
-     * the vertical `<pc-scrollbar>`. A non-empty reference that does not resolve warns and is
-     * ignored.
+     * the vertical `<pc-scrollbar>`. An exact entity 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;
         if (this.component) {
-            const entity = resolveEntity(value, 'pc-scroll-view', 'vertical-scrollbar', 'reference ignored');
+            const entity = resolveEntity(value, this, 'vertical-scrollbar', 'reference ignored');
             if (entity) {
                 this.component.verticalScrollbarEntity = entity;
             }
diff --git a/src/components/scrollbar-component.ts b/src/components/scrollbar-component.ts
index 5420843..ea5ff5e 100644
--- a/src/components/scrollbar-component.ts
+++ b/src/components/scrollbar-component.ts
@@ -45,7 +45,7 @@ class ScrollbarComponentElement extends ComponentElement {
             handleSize: this._handleSize
         };
 
-        const handle = resolveEntity(this._handle, 'pc-scrollbar', 'handle', 'reference ignored');
+        const handle = resolveEntity(this._handle, this, 'handle', 'reference ignored');
         if (handle) {
             data.handleEntity = handle;
         }
@@ -121,13 +121,15 @@ class ScrollbarComponentElement extends ComponentElement {
 
     /**
      * Sets the reference (CSS selector, element id or entity name) to the `<pc-entity>` used as the
-     * scrollbar handle. A non-empty reference that does not resolve warns and is ignored.
+     * scrollbar handle. An exact entity 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;
         if (this.component) {
-            const entity = resolveEntity(value, 'pc-scrollbar', 'handle', 'reference ignored');
+            const entity = resolveEntity(value, this, 'handle', 'reference ignored');
             if (entity) {
                 this.component.handleEntity = entity;
             }
diff --git a/src/parse.ts b/src/parse.ts
index fc9341d..bb61936 100644
--- a/src/parse.ts
+++ b/src/parse.ts
@@ -12,10 +12,12 @@
  * - `parseBool` and `parseTags` take no attribute name, because every value is valid for them and
  *   so they never warn.
  *
- * `findEntityElement` and `getEntity` are the exceptions: they resolve a reference against the
- * document rather than parsing a literal, and return `null` instead of falling back to a default.
- * 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.
+ * `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. An exact entity-name
+ * match resolves lexically through the entity hierarchy first; otherwise the reference is
+ * interpreted against the document as a CSS selector, element id or entity name. 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';
@@ -340,32 +342,97 @@ const query = (selector: string): Element | 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 and so act as the scopes of the lexical name lookup.
+ */
+const ENTITY_SCOPES = 'pc-entity, pc-model, pc-node';
+
 /**
  * Resolves a reference string to the element it names. The reference can be a CSS selector (e.g.
  * `#my-id`, `pc-entity[name="Foo"]`), a bare element id, or a bare entity name.
  *
+ * When `from` is supplied, an exact entity-name match resolves lexically first: the closest
+ * entity-fronting ancestor's inclusive subtree, then each outer entity-fronting ancestor, then the
+ * containing `<pc-app>`. This is what lets a `<template>` prefab reference its own entities by
+ * name — every clone resolves within itself before the document-wide lookup below could reach an
+ * earlier clone — provided the prefab has a single root `<pc-entity>` to be the enclosing scope.
+ * Otherwise (and as the fallback) the reference is interpreted against the document as a CSS
+ * selector, then an element id, then an entity name.
+ *
  * 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.
+ * @param from - The element resolving the reference, whose entity-fronting ancestors scope the
+ * name lookup. Omitted, the lookup is document-wide only.
  * @returns The matched element, or `null`.
  * @internal
  */
-export const findEntityElement = (ref: string): Element | null => {
+export const findEntityElement = (ref: string, from?: Element): Element | null => {
     if (!ref) {
         return 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 nameSelector = `pc-entity[name="${ref.replace(/["\\]/g, '\\$&')}"]`;
+
+    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;
+            }
+        }
+    }
+
     // Try the reference as a CSS selector. An invalid selector (e.g. a bare name containing
     // spaces) falls through to the id/name lookups below.
     let element = query(ref);
 
     if (!element) {
-        // 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.
-        element =
-            document.getElementById(ref) ?? query(`pc-entity[name="${ref.replace(/["\\]/g, '\\$&')}"]`);
+        element = document.getElementById(ref) ?? query(nameSelector);
     }
 
     return element;
@@ -374,14 +441,18 @@ export const findEntityElement = (ref: string): Element | 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.
+ * entity name — an exact entity-name match resolves lexically through the entity hierarchy first
+ * when `from` is supplied ({@link findEntityElement} details the 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 lookup is document-wide only.
  * @returns The resolved entity, or `null`.
  * @internal
  */
-export const getEntity = (ref: string): Entity | null => {
-    return (findEntityElement(ref) as { entity?: Entity } | null)?.entity ?? null;
+export const getEntity = (ref: string, from?: Element): Entity | null => {
+    return entityOf(findEntityElement(ref, from));
 };
 
 /**
@@ -407,8 +478,9 @@ export const unresolvedCause = (element: Element | null): string => {
 };
 
 /**
- * Resolves a reference string to the {@link Entity} backing a `<pc-entity>` element, warning when
- * a non-empty reference does not resolve - otherwise the reference fails silently, invisible
+ * Resolves a reference string to the {@link Entity} backing a `<pc-entity>` 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.
  *
@@ -416,26 +488,26 @@ export const unresolvedCause = (element: Element | null): string => {
  * elements (`pc-joint` `entity-b`, `pc-button` `image`) a documented value of its own.
  *
  * @param ref - The reference string to resolve.
- * @param tag - The resolving element's tag name, for the message.
+ * @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, tag: string, attribute: string, consequence: string): Entity | null => {
+export const resolveEntity = (ref: string, from: Element, attribute: string, consequence: string): Entity | null => {
     if (!ref) {
         return null;
     }
 
-    const entity = getEntity(ref);
+    const element = findEntityElement(ref, from);
+    const entity = entityOf(element);
     if (!entity) {
-        const element = findEntityElement(ref);
         const advice =
             element && !('entity' in element)
                 ? `Point ${attribute} at a pc-entity instead.`
                 : `Assign ${attribute} again once the entity exists.`;
         console.warn(
-            `${tag} could not resolve ${attribute} '${ref}' - ${unresolvedCause(element)} - ${consequence}. ${advice}`
+            `${from.tagName.toLowerCase()} could not resolve ${attribute} '${ref}' - ${unresolvedCause(element)} - ${consequence}. ${advice}`
         );
     }
     return entity;
diff --git a/test/integration/components/joint-component.test.ts b/test/integration/components/joint-component.test.ts
index fa2b0c3..215a541 100644
--- a/test/integration/components/joint-component.test.ts
+++ b/test/integration/components/joint-component.test.ts
@@ -3,6 +3,7 @@ import { Vec2, Vec3 } from 'playcanvas';
 import { describe, expect, it } from 'vitest';
 
 import type { JointComponentElement } from '../../../src/components/joint-component';
+import type { EntityElement } from '../../../src/entity';
 import { bootApp } from '../../helpers/app';
 import { useGuard } from '../../helpers/guard';
 
@@ -183,6 +184,28 @@ describe('<pc-joint>', () => {
             expect(component.entityB).toBe(app.root.findByName('anchor'));
         });
 
+        it('resolves a duplicated name to the nearest enclosing match', async () => {
+            // A decoy body with the same name earlier in the document: the reference must resolve
+            // through the joint's enclosing entities, not first-in-document - the rule that makes
+            // a cloned template's joints bind their own clone.
+            const { get } = await bootApp(`
+                <pc-entity name="anchor"><pc-rigid-body></pc-rigid-body></pc-entity>
+                <pc-entity name="assembly">
+                    <pc-entity id="near-anchor" name="anchor"><pc-rigid-body></pc-rigid-body></pc-entity>
+                    <pc-entity name="frame"><pc-joint entity-a="anchor"></pc-joint></pc-entity>
+                </pc-entity>
+            `);
+            const joint = get<JointComponentElement>('pc-joint');
+            const near = get<EntityElement>('#near-anchor');
+
+            expect(joint.component.entityA, 'resolved at creation').toBe(near.entity);
+
+            // And again through the setter path on reassignment
+            joint.setAttribute('entity-a', '');
+            joint.setAttribute('entity-a', 'anchor');
+            expect(joint.component.entityA, 'resolved on reassignment').toBe(near.entity);
+        });
+
         it('retargets a body when the attribute changes at runtime', async () => {
             const { app, get } = await bootApp(
                 `${scene('entity-a="bob" entity-b="anchor"')}
diff --git a/test/integration/components/script-component.test.ts b/test/integration/components/script-component.test.ts
index 27648af..639bb2f 100644
--- a/test/integration/components/script-component.test.ts
+++ b/test/integration/components/script-component.test.ts
@@ -3,6 +3,7 @@ import { describe, expect, it } from 'vitest';
 
 import type { ScriptComponentElement } from '../../../src/components/script-component';
 import type { ScriptInstanceElement } from '../../../src/components/script-instance';
+import type { EntityElement } from '../../../src/entity';
 import { bootApp } from '../../helpers/app';
 import { useGuard } from '../../helpers/guard';
 import { readyWithin } from '../../helpers/ready';
@@ -169,6 +170,31 @@ describe('<pc-script>', () => {
             expect(script.target).toBe(app.root.findByName('target'));
         });
 
+        it('resolves an entity: reference against the enclosing scope first', async () => {
+            // A same-named decoy earlier in the document: the reference must resolve to the
+            // host's own child, the rule that lets a cloned template's script attributes point at
+            // sibling entities. Bespoke setup, because the host subtree carries the target.
+            const handle = await bootApp('<pc-entity name="target"></pc-entity>');
+            handle.app.scripts.add(Probe);
+            const decoy = handle.get<EntityElement>('pc-entity[name="target"]');
+
+            const host = document.createElement('pc-entity');
+            host.innerHTML = `
+                <pc-entity name="target"></pc-entity>
+                <pc-script>
+                    <pc-script-instance name="probe" attributes='{"target": "entity:target"}'></pc-script-instance>
+                </pc-script>
+            `;
+            handle.appElement.appendChild(host);
+
+            const scriptElement = host.querySelector<ScriptInstanceElement>('pc-script-instance')!;
+            await readyWithin(scriptElement);
+            const script = scriptElement.script as Probe;
+
+            expect(script.target).toBe(host.querySelector<EntityElement>('pc-entity')!.entity);
+            expect(script.target).not.toBe(decoy.entity);
+        });
+
         it('warns and keeps the raw value when nothing matches the reference', async () => {
             const { script } = await bootReference('entity:#nope');
 
diff --git a/test/integration/get-entity.test.ts b/test/integration/get-entity.test.ts
index 3625a4c..6936b25 100644
--- a/test/integration/get-entity.test.ts
+++ b/test/integration/get-entity.test.ts
@@ -1,5 +1,6 @@
 import { describe, expect, it } from 'vitest';
 
+import type { EntityElement } from '../../src/entity';
 import { getEntity, resolveEntity } from '../../src/parse';
 import { bootApp } from '../helpers/app';
 import { useGuard } from '../helpers/guard';
@@ -80,21 +81,25 @@ describe('entity references', () => {
     });
 
     describe('resolveEntity', () => {
+        // A disconnected caller has no enclosing scopes, so resolution stays document-wide - the
+        // path these messages were pinned against. Its tag names the warning.
+        const caller = () => document.createElement('pc-test');
+
         it('returns the entity silently when the reference resolves', async () => {
             const { app } = await bootApp(markup);
-            expect(resolveEntity('#cube-id', 'pc-test', 'target', 'reference ignored')).toBe(
+            expect(resolveEntity('#cube-id', caller(), 'target', 'reference ignored')).toBe(
                 app.root.findByName('Cube')
             );
         });
 
         it('returns null silently for an empty reference', async () => {
             await bootApp(markup);
-            expect(resolveEntity('', 'pc-test', 'target', 'reference ignored')).toBeNull();
+            expect(resolveEntity('', caller(), 'target', 'reference ignored')).toBeNull();
         });
 
         it('warns with the caller-supplied meaning when nothing matches', async () => {
             await bootApp(markup);
-            expect(resolveEntity('#nope', 'pc-test', 'target', 'reference ignored')).toBeNull();
+            expect(resolveEntity('#nope', caller(), 'target', 'reference ignored')).toBeNull();
             warnings.expect(
                 "pc-test could not resolve target '#nope' - nothing in the document matches it - " +
                     'reference ignored. Assign target again once the entity exists.'
@@ -113,7 +118,7 @@ describe('entity references', () => {
             try {
                 warnings.expect('pc-entity must be a descendant of pc-app - entity not created');
 
-                expect(resolveEntity('#pending', 'pc-test', 'target', 'reference ignored')).toBeNull();
+                expect(resolveEntity('#pending', caller(), 'target', 'reference ignored')).toBeNull();
                 warnings.expect(
                     "pc-test could not resolve target '#pending' - <pc-entity> matches it but is not backing " +
                         'an entity yet - reference ignored. Assign target again once the entity exists.'
@@ -125,7 +130,7 @@ describe('entity references', () => {
 
         it('warns with the wrong-target cause and advice when the match cannot back an entity', async () => {
             await bootApp('<div id="plain"></div>');
-            expect(resolveEntity('#plain', 'pc-test', 'target', 'reference ignored')).toBeNull();
+            expect(resolveEntity('#plain', caller(), 'target', 'reference ignored')).toBeNull();
             warnings.expect(
                 "pc-test could not resolve target '#plain' - <div> matches it but cannot back an entity - " +
                     'reference ignored. Point target at a pc-entity instead.'
@@ -137,11 +142,153 @@ describe('entity references', () => {
 
             // A quote is escaped into the name selector; a newline cannot be, and must be
             // absorbed - the null-and-warn contract holds for arbitrary references
-            expect(resolveEntity('bad"name', 'pc-test', 'target', 'reference ignored')).toBeNull();
+            expect(resolveEntity('bad"name', caller(), 'target', 'reference ignored')).toBeNull();
             warnings.expect(`pc-test could not resolve target 'bad"name' - nothing in the document matches it`);
 
-            expect(resolveEntity('bad\nname', 'pc-test', 'target', 'reference ignored')).toBeNull();
+            expect(resolveEntity('bad\nname', caller(), 'target', 'reference ignored')).toBeNull();
+            warnings.expect("pc-test could not resolve target 'bad\nname' - nothing in the document matches it");
+        });
+    });
+
+    describe('scoped resolution', () => {
+        /**
+         * Two same-named subtrees, with the <pc-test> probe (an unregistered element - inert, and
+         * its tag names resolveEntity's messages) inside the second: an exact entity-name match
+         * must resolve through the probe's enclosing entities, never first-in-document. This is
+         * what lets a cloned <template> prefab reference its own entities.
+         */
+        const DUPLICATES = `
+            <pc-entity name="first">
+                <pc-entity name="dup"></pc-entity>
+            </pc-entity>
+            <pc-entity name="second">
+                <pc-entity name="dup"></pc-entity>
+                <pc-test></pc-test>
+            </pc-entity>
+        `;
+
+        it('resolves a duplicated bare name to the nearest enclosing entity scope', async () => {
+            const { get } = await bootApp(DUPLICATES);
+            const near = get<EntityElement>('pc-entity[name="second"] > pc-entity[name="dup"]');
+
+            expect(getEntity('dup', get('pc-test')), 'scoped, the enclosing subtree wins').toBe(near.entity);
+
+            const far = get<EntityElement>('pc-entity[name="first"] > pc-entity[name="dup"]');
+            expect(getEntity('dup'), 'unscoped, document order still wins').toBe(far.entity);
+        });
+
+        it('resolves the enclosing entity itself, so a clone can name its own root', async () => {
+            const { get } = await bootApp(`
+                <pc-entity name="chassis"></pc-entity>
+                <pc-entity id="own" name="chassis"><pc-test></pc-test></pc-entity>
+            `);
+
+            expect(getEntity('chassis', get('pc-test'))).toBe(get<EntityElement>('#own').entity);
+        });
+
+        it('climbs past the entity chain to the containing application before the document', async () => {
+            const { app, get } = await bootApp(`
+                <pc-entity name="roof"></pc-entity>
+                <pc-entity name="host"><pc-test></pc-test></pc-entity>
+            `);
+
+            // A same-named pc-entity outside the application, placed ahead of it in document
+            // order. It backs no entity (and warns so), which is what tells the two paths apart:
+            // the application scope resolves the live entity, while the document-wide name lookup
+            // finds the entity-less outsider first and yields nothing.
+            const outside = document.createElement('pc-entity');
+            outside.setAttribute('name', 'roof');
+            document.body.insertBefore(outside, document.body.firstChild);
+            try {
+                warnings.expect("pc-entity 'roof' must be a descendant of pc-app - entity not created");
+
+                expect(getEntity('roof', get('pc-test'))).toBe(app.root.findByName('roof'));
+                expect(getEntity('roof')).toBeNull();
+            } finally {
+                outside.remove();
+            }
+        });
+
+        it('prefers an in-scope entity name over a document id match', async () => {
+            const { app, get } = await bootApp(`<pc-entity id="dup" name="ById"></pc-entity>${DUPLICATES}`);
+            const near = get<EntityElement>('pc-entity[name="second"] > pc-entity[name="dup"]');
+
+            // Unscoped, the id lookup wins (pinned above); scoped, the lexical name phase runs
+            // first, so a page-level id cannot shadow a prefab's internal wiring.
+            expect(getEntity('dup')).toBe(app.root.findByName('ById'));
+            expect(getEntity('dup', get('pc-test'))).toBe(near.entity);
+        });
+
+        it('resolves selector and id references document-wide from inside a scope', async () => {
+            const { get } = await bootApp(`
+                <pc-entity name="first">
+                    <pc-entity id="first-dup" name="dup"></pc-entity>
+                </pc-entity>
+                <pc-entity name="second">
+                    <pc-entity name="dup"></pc-entity>
+                    <pc-test></pc-test>
+                </pc-entity>
+            `);
+            const far = get<EntityElement>('#first-dup');
+
+            // No entity is *named* the reference text, so the lexical phase misses and the
+            // document resolver interprets the reference - selectors and ids keep their
+            // document-wide meaning even from inside a scope.
+            expect(getEntity('pc-entity[name="dup"]', get('pc-test'))).toBe(far.entity);
+            expect(getEntity('#first-dup', get('pc-test'))).toBe(far.entity);
+        });
+
+        it('does not skip a nearer name match that backs no entity yet', async () => {
+            const { get } = await bootApp(`
+                <pc-entity name="dup"></pc-entity>
+                <pc-entity name="outer">
+                    <pc-entity id="near" name="dup"></pc-entity>
+                    <pc-test></pc-test>
+                </pc-entity>
+            `);
+
+            // The nearest name match is what the author meant: with its entity destroyed it
+            // reports the timing cause rather than silently deferring to the farther live one.
+            get<EntityElement>('#near').entity!.destroy();
+
+            expect(resolveEntity('dup', get('pc-test'), 'target', 'reference ignored')).toBeNull();
+            warnings.expect(
+                "pc-test could not resolve target 'dup' - <pc-entity> matches it but is not backing " +
+                    'an entity yet - reference ignored. Assign target again once the entity exists.'
+            );
+        });
+
+        it('falls back to the document when nothing in scope matches', async () => {
+            const { app, get } = await bootApp(`
+                <pc-entity id="cube-id" name="Cube"></pc-entity>
+                <pc-entity name="host"><pc-test></pc-test></pc-entity>
+            `);
+            const cube = app.root.findByName('Cube');
+
+            expect(getEntity('#cube-id', get('pc-test')), 'a connected caller').toBe(cube);
+            expect(getEntity('cube-id', document.createElement('div')), 'a disconnected one').toBe(cube);
+        });
+
+        it('warns without throwing for a reference no CSS string can express, from inside a scope', async () => {
+            const { get } = await bootApp('<pc-entity name="host"><pc-test></pc-test></pc-entity>');
+
+            // Quote/backslash escaping cannot express a newline, so every scope's lookup must
+            // absorb the invalid selector rather than throw.
+            expect(resolveEntity('bad\nname', get('pc-test'), 'target', 'reference ignored')).toBeNull();
             warnings.expect("pc-test could not resolve target 'bad\nname' - nothing in the document matches it");
         });
+
+        it('resolves a name the scoped selector must escape', async () => {
+            const { get } = await bootApp(`
+                <pc-entity name="host">
+                    <pc-entity name="pc-entity["></pc-entity>
+                    <pc-test></pc-test>
+                </pc-entity>
+            `);
+
+            expect(getEntity('pc-entity[', get('pc-test'))).toBe(
+                get<EntityElement>('pc-entity[name="pc-entity["]').entity
+            );
+        });
     });
 });
diff --git a/test/integration/template-clone.test.ts b/test/integration/template-clone.test.ts
index e784adf..0ace7b2 100644
--- a/test/integration/template-clone.test.ts
+++ b/test/integration/template-clone.test.ts
@@ -3,6 +3,7 @@ import { describe, expect, it, vi } from 'vitest';
 
 import type { AppElement } from '../../src/app';
 import type { AssetElement } from '../../src/asset';
+import type { JointComponentElement } from '../../src/components/joint-component';
 import type { EntityElement } from '../../src/entity';
 import type { MaterialElement } from '../../src/material';
 import type { ModelElement } from '../../src/model';
@@ -30,6 +31,24 @@ const ENTRY_TEMPLATE = `
     </template>
 `;
 
+/**
+ * A prefab wired by bare entity names — the shape scoped resolution exists for. The joint sits
+ * before the entities it references, so each clone also pins forward references within itself,
+ * and the single root `<pc-entity>` is the documented requirement for a self-contained prefab:
+ * it is the enclosing scope the names resolve through.
+ */
+const CHAIN_TEMPLATE = `
+    <template id="chain">
+        <pc-entity name="Link">
+            <pc-entity name="Frame">
+                <pc-joint entity-a="Anchor" entity-b="Bob"></pc-joint>
+            </pc-entity>
+            <pc-entity name="Anchor"><pc-rigid-body></pc-rigid-body></pc-entity>
+            <pc-entity name="Bob"><pc-rigid-body type="dynamic"></pc-rigid-body></pc-entity>
+        </pc-entity>
+    </template>
+`;
+
 /** A meshless glTF with a single named node, for the `<pc-node>` case. */
 const STAGE_SRC = `data:application/json,${encodeURIComponent(
     JSON.stringify({
@@ -131,6 +150,35 @@ describe('a <template>-cloned subtree', () => {
         expect(uncaught.seen).toEqual([]);
     });
 
+    it('resolves entity references inside a cloned subtree to that clone, not an earlier one', async () => {
+        const { get, container } = await bootApp(`<pc-entity name="Content"></pc-entity>${CHAIN_TEMPLATE}`);
+        const content = get<EntityElement>('pc-entity[name="Content"]');
+        const template = get<HTMLTemplateElement>('template');
+
+        content.appendChild(template.content.cloneNode(true));
+        content.appendChild(template.content.cloneNode(true));
+        await settle(container);
+
+        // Every clone's joint binds that clone's own bodies. The guard fails this test if any
+        // reference warned on the way.
+        const links = Array.from(content.querySelectorAll<EntityElement>(':scope > pc-entity'));
+        expect(links).toHaveLength(2);
+        for (const link of links) {
+            const joint = link.querySelector<JointComponentElement>('pc-joint')!;
+            expect(joint.component.entityA).toBe(link.querySelector<EntityElement>('pc-entity[name="Anchor"]')!.entity);
+            expect(joint.component.entityB).toBe(link.querySelector<EntityElement>('pc-entity[name="Bob"]')!.entity);
+        }
+
+        // The decisive half: the second clone did not bind the first clone's entities, which is
+        // what a document-wide lookup produces - it finds the first instance in document order.
+        const [first, second] = links;
+        expect(second.querySelector<JointComponentElement>('pc-joint')!.component.entityA).not.toBe(
+            first.querySelector<EntityElement>('pc-entity[name="Anchor"]')!.entity
+        );
+
+        expect(uncaught.seen).toEqual([]);
+    });
+
     it('builds a cloned <pc-node> subtree appended to an instantiated <pc-model>', async () => {
         const { get } = await bootApp(`
             <pc-asset id="stage" type="container" src="${STAGE_SRC}"></pc-asset>

From 92dbff8f0adbc784ce7e93e8bd9daaa6ead3d99e Mon Sep 17 00:00:00 2001
From: Will Eastcott <will@playcanvas.com>
Date: Mon, 31 Aug 2026 00:16:21 +0100
Subject: [PATCH 2/2] Build the AR Wiener Storm chain from a template

The six capsule segments and five 6dof flex joints move from ~90 lines
of addComponent calls in wiener-storm.mjs into a <template> in the
example page, wired by bare entity names: names resolve against the
nearest enclosing entity first, so every clone's joints bind that
clone's own segments - one template, many wieners. The single root
pc-entity is what keeps each clone's names self-contained.

The script now clones the template per throw, scales the clone's
positions and capsules to its random size before it upgrades, appends
it under the owning application's pc-scene (entities parent to the
application root, keeping the spawn pose world space), and launches
once the clone's components report ready. The throw is guarded: a
pending set tracks clones until the launch commits to the live list,
readiness is raced against a destroy promise so a clone removed
mid-flight cannot strand the await, and teardown removes pending and
live clones alike. What has no declarative surface stays in script:
the solver tuning, the stop-ERP stiffening, the bone riding and the
launch solve.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 examples/ar-wiener-storm.html            |  55 +++-
 examples/assets/scripts/wiener-storm.mjs | 321 +++++++++++++----------
 2 files changed, 239 insertions(+), 137 deletions(-)

diff --git a/examples/ar-wiener-storm.html b/examples/ar-wiener-storm.html
index 48e55db..3d1a006 100644
--- a/examples/ar-wiener-storm.html
+++ b/examples/ar-wiener-storm.html
@@ -262,12 +262,65 @@
                 <!-- The wiener cannon -->
                 <pc-entity name="wiener-storm">
                     <pc-script>
-                        <pc-script-instance name="wienerStorm" wiener-asset="asset:wiener" target="entity:head-proxy" rate="2.5"></pc-script-instance>
+                        <pc-script-instance name="wienerStorm" wiener-asset="asset:wiener" target="entity:head-proxy" rate="2.5" template="#wiener-template"></pc-script-instance>
                     </pc-script>
                 </pc-entity>
             </pc-scene>
         </pc-app>
 
+        <!-- One wiener: six capsule bodies linked by five 6dof flex joints whose angular
+             springs pull it back straight - a raw wiener is floppy, not a rag. Authored in
+             the model's meters; the cannon scales each clone to its own size in scene
+             units. The joints reference the segments by bare name, and names resolve
+             against the nearest enclosing entity first - so every clone's joints bind that
+             clone's own segments, which is what lets one template spawn many wieners. The
+             single root pc-entity is what keeps the names self-contained. -->
+        <template id="wiener-template">
+            <pc-entity name="wiener">
+                <pc-entity name="seg-0" position="0 -0.0575 0">
+                    <pc-collision type="capsule" radius="0.0115" height="0.027"></pc-collision>
+                    <pc-rigid-body type="dynamic" mass="0.02" friction="0.4" angular-damping="0.5"></pc-rigid-body>
+                </pc-entity>
+                <pc-entity name="seg-1" position="0 -0.0345 0">
+                    <pc-collision type="capsule" radius="0.0115" height="0.027"></pc-collision>
+                    <pc-rigid-body type="dynamic" mass="0.02" friction="0.4" angular-damping="0.5"></pc-rigid-body>
+                </pc-entity>
+                <pc-entity name="seg-2" position="0 -0.0115 0">
+                    <pc-collision type="capsule" radius="0.0115" height="0.027"></pc-collision>
+                    <pc-rigid-body type="dynamic" mass="0.02" friction="0.4" angular-damping="0.5"></pc-rigid-body>
+                </pc-entity>
+                <pc-entity name="seg-3" position="0 0.0115 0">
+                    <pc-collision type="capsule" radius="0.0115" height="0.027"></pc-collision>
+                    <pc-rigid-body type="dynamic" mass="0.02" friction="0.4" angular-damping="0.5"></pc-rigid-body>
+                </pc-entity>
+                <pc-entity name="seg-4" position="0 0.0345 0">
+                    <pc-collision type="capsule" radius="0.0115" height="0.027"></pc-collision>
+                    <pc-rigid-body type="dynamic" mass="0.02" friction="0.4" angular-damping="0.5"></pc-rigid-body>
+                </pc-entity>
+                <pc-entity name="seg-5" position="0 0.0575 0">
+                    <pc-collision type="capsule" radius="0.0115" height="0.027"></pc-collision>
+                    <pc-rigid-body type="dynamic" mass="0.02" friction="0.4" angular-damping="0.5"></pc-rigid-body>
+                </pc-entity>
+                <!-- Bending swings about each junction's local X and Z, twisting about Y.
+                     Five joints share the total fold, and twist is nearly locked. -->
+                <pc-entity name="flex-0" position="0 -0.046 0">
+                    <pc-joint type="6dof" entity-a="seg-0" entity-b="seg-1" angular-motion-x="limited" angular-motion-y="limited" angular-motion-z="limited" angular-limits-x="-10 10" angular-limits-y="-1.5 1.5" angular-limits-z="-10 10" angular-stiffness="6 8 6"></pc-joint>
+                </pc-entity>
+                <pc-entity name="flex-1" position="0 -0.023 0">
+                    <pc-joint type="6dof" entity-a="seg-1" entity-b="seg-2" angular-motion-x="limited" angular-motion-y="limited" angular-motion-z="limited" angular-limits-x="-10 10" angular-limits-y="-1.5 1.5" angular-limits-z="-10 10" angular-stiffness="6 8 6"></pc-joint>
+                </pc-entity>
+                <pc-entity name="flex-2" position="0 0 0">
+                    <pc-joint type="6dof" entity-a="seg-2" entity-b="seg-3" angular-motion-x="limited" angular-motion-y="limited" angular-motion-z="limited" angular-limits-x="-10 10" angular-limits-y="-1.5 1.5" angular-limits-z="-10 10" angular-stiffness="6 8 6"></pc-joint>
+                </pc-entity>
+                <pc-entity name="flex-3" position="0 0.023 0">
+                    <pc-joint type="6dof" entity-a="seg-3" entity-b="seg-4" angular-motion-x="limited" angular-motion-y="limited" angular-motion-z="limited" angular-limits-x="-10 10" angular-limits-y="-1.5 1.5" angular-limits-z="-10 10" angular-stiffness="6 8 6"></pc-joint>
+                </pc-entity>
+                <pc-entity name="flex-4" position="0 0.046 0">
+                    <pc-joint type="6dof" entity-a="seg-4" entity-b="seg-5" angular-motion-x="limited" angular-motion-y="limited" angular-motion-z="limited" angular-limits-x="-10 10" angular-limits-y="-1.5 1.5" angular-limits-z="-10 10" angular-stiffness="6 8 6"></pc-joint>
+                </pc-entity>
+            </pc-entity>
+        </template>
+
         <script>
             // In ?sim mode the synthetic head pose replaces the webcam entirely - remove
             // the camera feed script before the app boots (this classic script runs at
diff --git a/examples/assets/scripts/wiener-storm.mjs b/examples/assets/scripts/wiener-storm.mjs
index 28f81f2..30631e3 100644
--- a/examples/assets/scripts/wiener-storm.mjs
+++ b/examples/assets/scripts/wiener-storm.mjs
@@ -1,29 +1,4 @@
-import { Entity, Quat, Script, Vec2, Vec3 } from 'playcanvas';
-
-/** The local Y centers of the six physics segments, one per skin bone, in authored meters. */
-const SEG_CENTERS = [-0.0575, -0.0345, -0.0115, 0.0115, 0.0345, 0.0575];
-
-/** The local Y positions of the five flex joints between them, in authored meters. */
-const JOINT_HEIGHTS = [-0.046, -0.023, 0, 0.023, 0.046];
-
-/** The capsule length of one segment in authored meters (overlapping the neighbors a little). */
-const SEG_HEIGHT = 0.027;
-
-/** The capsule radius of one segment in authored meters. */
-const SEG_RADIUS = 0.0115;
-
-/** How far one flex joint may bend, in degrees. Five joints share the total fold. */
-const BEND_LIMIT = 10;
-
-/** How far one flex joint may twist about the wiener's length, in degrees - a raw wiener
- * flexes but barely twists at all. */
-const TWIST_LIMIT = 1.5;
-
-/** The angular spring stiffness pulling each joint back straight. */
-const BEND_STIFFNESS = 6;
-
-/** The angular spring stiffness resisting twist. */
-const TWIST_STIFFNESS = 8;
+import { Quat, Script, Vec2, Vec3 } from 'playcanvas';
 
 /**
  * Lobs a steady barrage of wieners at the user's head. Works in MediaPipe's camera space, as
@@ -42,6 +17,11 @@ const TWIST_STIFFNESS = 8;
  * an impact folds the chain around whatever it hit in a smooth curve and the springs wobble it
  * straight again - no scripted deformation, just physics.
  *
+ * The chain itself is markup: `template` names a `<template>` holding one wiener, its segments
+ * and joints wired by bare entity names, which resolve within each clone - one template, many
+ * wieners. This script clones it per throw, scales the clone to its own random size, launches
+ * the bodies once the components report ready, and rides the skin on them.
+ *
  * Throwing runs while a face is tracked (`face:found`/`face:lost`), which the `?sim` and
  * no-camera fallback modes of the face tracking script also report.
  *
@@ -72,11 +52,20 @@ export class WienerStorm extends Script {
     /**
      * The head proxy entity: throws are aimed at its position at launch, and a wiener
      * colliding with it fires `wiener:hit`.
-     * @type {Entity}
+     * @type {import('playcanvas').Entity}
      * @attribute
      */
     target = null;
 
+    /**
+     * A CSS selector for the `<template>` holding one wiener: a single root `pc-entity` (the
+     * scope its bare-name joint references resolve within) carrying the capsule segments and
+     * flex joints, authored in the model's meters.
+     * @type {string}
+     * @attribute
+     */
+    template = '#wiener-template';
+
     /**
      * The average number of wieners thrown per second at storm category 1. Each category
      * above that adds 30%.
@@ -187,6 +176,31 @@ export class WienerStorm extends Script {
     /** @private */
     _live = [];
 
+    /**
+     * Cloned wiener elements whose components are still attaching. Tracked so teardown can
+     * remove a clone that has not committed to `_live` yet.
+     * @private
+     */
+    _pending = new Set();
+
+    /**
+     * Resolves when the script is destroyed. Raced against the clone components' readiness,
+     * because a removed element's ready() never settles. A dedicated field: the engine owns
+     * `_destroyed` as the script's boolean destruction flag.
+     * @private
+     */
+    _destroyPromise = null;
+
+    /** @private */
+    _resolveDestroyed = null;
+
+    /**
+     * Where clones are appended: the owning application's `<pc-scene>`, so their entities
+     * parent to the application root and the spawn pose is world space by construction.
+     * @private
+     */
+    _spawnRoot = null;
+
     /** @private */
     _active = false;
 
@@ -218,6 +232,16 @@ export class WienerStorm extends Script {
     _tmpQuat = new Quat();
 
     initialize() {
+        this._destroyPromise = new Promise((resolve) => {
+            this._resolveDestroyed = resolve;
+        });
+
+        // The owning application's DOM, found by which <pc-app> fronts this script's entity -
+        // a page can hold several applications, so the first one is not necessarily ours.
+        const appElement = Array.from(document.querySelectorAll('pc-app'))
+            .find(candidate => candidate.elementFromEntity?.(this.entity));
+        this._spawnRoot = appElement?.querySelector('pc-scene') ?? appElement ?? null;
+
         // The scene is in centimeters, so gravity is in centimeters per second squared
         const gravity = this.app.systems.rigidbody.gravity;
         this._prevGravity.copy(gravity);
@@ -248,8 +272,16 @@ export class WienerStorm extends Script {
         this.on('destroy', () => {
             this.app.off('face:found', onFound);
             this.app.off('face:lost', onLost);
+            // Unblock any throw awaiting its clone's readiness, then take down every clone -
+            // committed or not. Removing the element destroys its entity via the web-components
+            // lifecycle.
+            this._resolveDestroyed();
+            for (const element of this._pending) {
+                element.remove();
+            }
+            this._pending.clear();
             for (const wiener of this._live) {
-                wiener.container.destroy();
+                wiener.element.remove();
             }
             this._live.length = 0;
             this.app.systems.rigidbody.gravity.copy(this._prevGravity);
@@ -298,24 +330,31 @@ export class WienerStorm extends Script {
 
             if (wiener.age > this.lifetime || wiener.segments[2].getPosition().y < -160) {
                 if (!wiener.hitHead) this.app.fire('wiener:missed');
-                wiener.container.destroy();
+                wiener.element.remove();
                 this._live.splice(i, 1);
             }
         }
     }
 
     /**
-     * Spawns one wiener on the frontal hemisphere and throws it at the head.
+     * Spawns one wiener from the template on the frontal hemisphere and throws it at the head.
+     * Async: the clone's components attach microtasks after it is appended, so the launch waits
+     * for them to report ready - still ahead of the next physics step. Fired and forgotten from
+     * update(), guarded against the script being destroyed mid-flight.
      * @private
      */
-    _throw() {
+    async _throw() {
         // An unresolved target reference arrives as a raw string, so guard on the method
-        if (!this.wienerAsset?.resource || !this.target?.getPosition) return;
+        if (!this.wienerAsset?.resource || !this.target?.getPosition || !this._spawnRoot) return;
+
+        const template = document.querySelector(this.template);
+        if (!template?.content) return;
 
-        while (this._live.length >= this.maxLive) {
+        // Pending clones count against the cap so a burst of in-flight throws cannot overshoot it
+        while (this._live.length > 0 && this._live.length + this._pending.size >= this.maxLive) {
             const retired = this._live.shift();
             if (!retired.hitHead) this.app.fire('wiener:missed');
-            retired.container.destroy();
+            retired.element.remove();
         }
 
         // A spawn point on the hemisphere between the head and the screen: +Z is out of
@@ -358,116 +397,126 @@ export class WienerStorm extends Script {
         const scale = 0.9 + Math.random() * 0.22;
         const k = this.modelScale * scale;
 
-        // The container holds the whole wiener for lifecycle only - the segment bodies fly
-        // in world space regardless of their parent
-        const container = new Entity('wiener');
-        container.setPosition(pos);
-        this._tmpQuat.setFromEulerAngles(Math.random() * 360, Math.random() * 360, Math.random() * 360);
-        container.setRotation(this._tmpQuat);
-        this.app.root.addChild(container);
-
-        const wiener = {
-            container: container,
-            segments: [],
-            bones: [],
-            posOffsets: [],
-            rotOffsets: [],
-            age: 0,
-            hitHead: false
-        };
+        // One wiener from the template. The root entity holds the whole wiener for lifecycle
+        // and scope - the segment bodies fly in world space regardless of their parent.
+        const clone = template.content.cloneNode(true);
+        const element = clone.querySelector('pc-entity');
+        if (!element) return;
+
+        // The template is authored in the model's meters: scale every position and capsule to
+        // this wiener's size in scene units before the clone upgrades, and stamp the dynamics
+        // that derive from script attributes.
+        for (const part of element.querySelectorAll('pc-entity')) {
+            const [x, y, z] = part.getAttribute('position').split(/\s+/).map(Number);
+            part.setAttribute('position', `${x * k} ${y * k} ${z * k}`);
+        }
+        for (const collision of element.querySelectorAll('pc-collision')) {
+            collision.setAttribute('radius', Number(collision.getAttribute('radius')) * k);
+            collision.setAttribute('height', Number(collision.getAttribute('height')) * k);
+        }
+        for (const body of element.querySelectorAll('pc-rigid-body')) {
+            body.setAttribute('restitution', this.restitution);
+            // Ammo damping is exponential per second, matching the launch solve
+            body.setAttribute('linear-damping', 1 - Math.exp(-drag));
+        }
 
-        for (const center of SEG_CENTERS) {
-            const segment = new Entity('wiener-segment');
-            segment.setLocalPosition(0, center * k, 0);
-            container.addChild(segment);
-            segment.addComponent('collision', {
-                type: 'capsule',
-                radius: SEG_RADIUS * k,
-                height: SEG_HEIGHT * k
-            });
-            segment.addComponent('rigidbody', {
-                type: 'dynamic',
-                mass: 0.02,
-                restitution: this.restitution,
-                friction: 0.4,
-                // Ammo damping is exponential per second, matching the launch solve
-                linearDamping: 1 - Math.exp(-drag),
-                angularDamping: 0.5
-            });
-
-            segment.collision.on('collisionstart', (result) => {
-                // A settling wiener restarts the contact every micro-bounce, so a direct
-                // hit only counts once per wiener
-                if (!wiener.hitHead && this.target && result.other === this.target) {
-                    wiener.hitHead = true;
-                    // The post-bounce speed is a fine proxy for how hard it landed
-                    this.app.fire('wiener:hit', segment.rigidbody.linearVelocity.length());
-                }
-            });
+        // The spawn pose is world space: the clone lands under <pc-scene>, so its entity
+        // parents to the application root
+        element.setAttribute('position', `${pos.x} ${pos.y} ${pos.z}`);
+        element.setAttribute(
+            'rotation',
+            `${Math.random() * 360} ${Math.random() * 360} ${Math.random() * 360}`
+        );
+
+        // Pending until the launch commits, so teardown can find a half-initialized clone
+        this._pending.add(element);
+        this._spawnRoot.appendChild(clone);
 
-            wiener.segments.push(segment);
+        // The entities exist as soon as appendChild returns; the components attach microtasks
+        // later. Raced against destruction, because a removed element's ready() never settles.
+        const parts = [...element.querySelectorAll('pc-collision, pc-rigid-body, pc-joint')];
+        await Promise.race([Promise.all(parts.map(part => part.ready())), this._destroyPromise]);
+
+        if (this._destroyed || !element.isConnected) {
+            this._pending.delete(element);
+            element.remove();
+            return;
         }
 
-        // The 6dof joints make the chain flex: bending swings about the local X and Z of
-        // each junction, twisting about Y, and angular springs pull the wiener straight
-        // again - a raw wiener is floppy, not a rag
-        for (let j = 0; j < JOINT_HEIGHTS.length; j++) {
-            const joint = new Entity('wiener-joint');
-            joint.setLocalPosition(0, JOINT_HEIGHTS[j] * k, 0);
-            container.addChild(joint);
-            joint.addComponent('joint', {
-                type: '6dof',
-                entityA: wiener.segments[j],
-                entityB: wiener.segments[j + 1],
-                angularMotionX: 'limited',
-                angularMotionY: 'limited',
-                angularMotionZ: 'limited',
-                angularLimitsX: new Vec2(-BEND_LIMIT, BEND_LIMIT),
-                angularLimitsY: new Vec2(-TWIST_LIMIT, TWIST_LIMIT),
-                angularLimitsZ: new Vec2(-BEND_LIMIT, BEND_LIMIT),
-                angularStiffness: new Vec3(BEND_STIFFNESS, TWIST_STIFFNESS, BEND_STIFFNESS)
-            });
-
-            // At Ammo's default stop ERP a hard head impact blows straight through the
-            // limits for a few frames, folding the wiener far past them. Stiffen the
-            // limit correction on every axis, set on the native constraint directly
+        try {
+            const wiener = {
+                element: element,
+                segments: [...element.querySelectorAll('pc-entity[name^="seg-"]')].map(seg => seg.entity),
+                bones: [],
+                posOffsets: [],
+                rotOffsets: [],
+                age: 0,
+                hitHead: false
+            };
+
+            for (const segment of wiener.segments) {
+                segment.collision.on('collisionstart', (result) => {
+                    // A settling wiener restarts the contact every micro-bounce, so a direct
+                    // hit only counts once per wiener
+                    if (!wiener.hitHead && this.target && result.other === this.target) {
+                        wiener.hitHead = true;
+                        // The post-bounce speed is a fine proxy for how hard it landed
+                        this.app.fire('wiener:hit', segment.rigidbody.linearVelocity.length());
+                    }
+                });
+            }
+
+            // At Ammo's default stop ERP a hard head impact blows straight through the joint
+            // limits for a few frames, folding the wiener far past them. Stiffen the limit
+            // correction on every axis, set on the native constraint directly
             // (2 is BT_CONSTRAINT_STOP_ERP)
-            const constraint = joint.joint.constraint;
-            for (let axis = 0; axis < 6; axis++) {
-                constraint?.setParam(2, 0.8, axis);
+            for (const jointElement of element.querySelectorAll('pc-joint')) {
+                const constraint = jointElement.component.constraint;
+                for (let axis = 0; axis < 6; axis++) {
+                    constraint?.setParam(2, 0.8, axis);
+                }
             }
-        }
 
-        // The skinned model rides along: each bone copies its segment body every frame,
-        // through the offsets between them captured at this rest pose
-        const model = this.wienerAsset.resource.instantiateRenderEntity();
-        model.setLocalScale(k, k, k);
-        container.addChild(model);
-
-        for (let b = 0; b < wiener.segments.length; b++) {
-            const segment = wiener.segments[b];
-            const bone = model.findByName(`B${b}`);
-            const invRot = this._tmpQuat.copy(segment.getRotation()).invert();
-            wiener.bones.push(bone);
-            wiener.posOffsets.push(invRot.transformVector(new Vec3().sub2(bone.getPosition(), segment.getPosition())));
-            wiener.rotOffsets.push(new Quat().mul2(invRot, bone.getRotation()));
-        }
+            // The skinned model rides along: each bone copies its segment body every frame,
+            // through the offsets between them captured at this rest pose
+            const containerEntity = element.entity;
+            const model = this.wienerAsset.resource.instantiateRenderEntity();
+            model.setLocalScale(k, k, k);
+            containerEntity.addChild(model);
 
-        // Throw the chain as one rigid motion: a shared tumble plus the velocity that
-        // tumble adds at each segment's offset from the middle
-        const omega = new Vec3(
-            Math.random() * 2 - 1,
-            Math.random() * 2 - 1,
-            Math.random() * 2 - 1
-        ).normalize().mulScalar(2 + Math.random() * 2.5);
-        const mid = this._tmpVec2.copy(container.getPosition());
-        for (const segment of wiener.segments) {
-            const arm = this._tmpVec.sub2(segment.getPosition(), mid);
-            const spin = new Vec3().cross(omega, arm);
-            segment.rigidbody.linearVelocity = spin.add(velocity);
-            segment.rigidbody.angularVelocity = omega;
-        }
+            for (let b = 0; b < wiener.segments.length; b++) {
+                const segment = wiener.segments[b];
+                const bone = model.findByName(`B${b}`);
+                const invRot = this._tmpQuat.copy(segment.getRotation()).invert();
+                wiener.bones.push(bone);
+                wiener.posOffsets.push(
+                    invRot.transformVector(new Vec3().sub2(bone.getPosition(), segment.getPosition()))
+                );
+                wiener.rotOffsets.push(new Quat().mul2(invRot, bone.getRotation()));
+            }
 
-        this._live.push(wiener);
+            // Throw the chain as one rigid motion: a shared tumble plus the velocity that
+            // tumble adds at each segment's offset from the middle
+            const omega = new Vec3(
+                Math.random() * 2 - 1,
+                Math.random() * 2 - 1,
+                Math.random() * 2 - 1
+            ).normalize().mulScalar(2 + Math.random() * 2.5);
+            const mid = this._tmpVec2.copy(containerEntity.getPosition());
+            for (const segment of wiener.segments) {
+                const arm = this._tmpVec.sub2(segment.getPosition(), mid);
+                const spin = new Vec3().cross(omega, arm);
+                segment.rigidbody.linearVelocity = spin.add(velocity);
+                segment.rigidbody.angularVelocity = omega;
+            }
+
+            this._pending.delete(element);
+            this._live.push(wiener);
+        } catch (error) {
+            // A half-initialized clone must never survive untracked
+            this._pending.delete(element);
+            element.remove();
+            console.warn(`wienerStorm failed to launch a wiener: ${error}`);
+        }
     }
 }