@playcanvas/web-components 0.18.0 → 0.20.0

package/dist/app.d.cts

@@ -63,10 +63,30 @@ declare class AppElement extends AsyncElement {
      */
     private _entityElements;
     private _picker;
-    private _hasPointerListeners;
     private _hoveredEntity;
     private _pickToken;
     private _pointerHandlers;
+    /**
+     * The pick of each pointer's primary-button press, keyed by pointerId and kept while a click
+     * may still conclude it. The promise is stored rather than its result, so a release can
+     * await a press pick that has not resolved yet. Entries are removed by the matching
+     * pointerup or pointercancel, and only ever stored while some element listens for click -
+     * which is also what keeps those two canvas listeners attached.
+     */
+    private _downPicks;
+    /** Whether any element in the tree listens for click. Maintained by _syncCanvasListeners. */
+    private _clickListened;
+    /**
+     * The previous click's target, time and count, for chaining successive clicks into the
+     * click count that `detail` carries. `null` until a click has fired.
+     */
+    private _lastClick;
+    /**
+     * Serializes dispatch of the discrete synthesized events (pointerdown, pointerup, click),
+     * whose picks resolve in GPU order, not canvas-event order. Replaced on teardown, so a pick
+     * that never resolves cannot stall the dispatches of a later boot.
+     */
+    private _dispatchChain;
     private _app;
     private _loadProgress;
     /**
@@ -185,10 +205,25 @@ declare class AppElement extends AsyncElement {
      */
     private _pickNode;
     private _onPointerMove;
+    /**
+     * Appends a dispatch step to {@link _dispatchChain}. Must be called synchronously from the
+     * canvas event handler - the order of appends is what carries canvas-event order. A step
+     * that rejects is reported and released, so the steps queued behind it still dispatch.
+     *
+     * @param step - The dispatch work to run once every earlier step has finished.
+     */
+    private _chainDispatch;
     private _onPointerDown;
     private _onPointerUp;
-    private _onPointerListenerAdded;
-    private _onPointerListenerRemoved;
+    /**
+     * Attaches exactly the canvas listeners the tree's current element listeners need, and
+     * detaches the rest. Recomputed whenever a listener connects or disconnects anywhere under
+     * this element: several synthesized types can need the same canvas listener (enter, leave
+     * and move all ride the move pick; click rides the down/up pair), so one type's removal
+     * must not detach a listener another type still uses. Re-attaching an attached listener is
+     * a no-op by EventTarget semantics, so no attach state is kept.
+     */
+    private _syncCanvasListeners;
     /**
      * Warns that a graphics option was written too late to have any effect. These options are read
      * once, when the element connects and creates its graphics device, so a later write updates

package/dist/app.d.ts

@@ -63,10 +63,30 @@ declare class AppElement extends AsyncElement {
      */
     private _entityElements;
     private _picker;
-    private _hasPointerListeners;
     private _hoveredEntity;
     private _pickToken;
     private _pointerHandlers;
+    /**
+     * The pick of each pointer's primary-button press, keyed by pointerId and kept while a click
+     * may still conclude it. The promise is stored rather than its result, so a release can
+     * await a press pick that has not resolved yet. Entries are removed by the matching
+     * pointerup or pointercancel, and only ever stored while some element listens for click -
+     * which is also what keeps those two canvas listeners attached.
+     */
+    private _downPicks;
+    /** Whether any element in the tree listens for click. Maintained by _syncCanvasListeners. */
+    private _clickListened;
+    /**
+     * The previous click's target, time and count, for chaining successive clicks into the
+     * click count that `detail` carries. `null` until a click has fired.
+     */
+    private _lastClick;
+    /**
+     * Serializes dispatch of the discrete synthesized events (pointerdown, pointerup, click),
+     * whose picks resolve in GPU order, not canvas-event order. Replaced on teardown, so a pick
+     * that never resolves cannot stall the dispatches of a later boot.
+     */
+    private _dispatchChain;
     private _app;
     private _loadProgress;
     /**
@@ -185,10 +205,25 @@ declare class AppElement extends AsyncElement {
      */
     private _pickNode;
     private _onPointerMove;
+    /**
+     * Appends a dispatch step to {@link _dispatchChain}. Must be called synchronously from the
+     * canvas event handler - the order of appends is what carries canvas-event order. A step
+     * that rejects is reported and released, so the steps queued behind it still dispatch.
+     *
+     * @param step - The dispatch work to run once every earlier step has finished.
+     */
+    private _chainDispatch;
     private _onPointerDown;
     private _onPointerUp;
-    private _onPointerListenerAdded;
-    private _onPointerListenerRemoved;
+    /**
+     * Attaches exactly the canvas listeners the tree's current element listeners need, and
+     * detaches the rest. Recomputed whenever a listener connects or disconnects anywhere under
+     * this element: several synthesized types can need the same canvas listener (enter, leave
+     * and move all ride the move pick; click rides the down/up pair), so one type's removal
+     * must not detach a listener another type still uses. Re-attaching an attached listener is
+     * a no-op by EventTarget semantics, so no attach state is kept.
+     */
+    private _syncCanvasListeners;
     /**
      * Warns that a graphics option was written too late to have any effect. These options are read
      * once, when the element connects and creates its graphics device, so a later write updates

package/dist/components/anim-clip.d.cts

@@ -16,8 +16,6 @@ import { AnimComponentElement } from './anim-component.cjs';
  * @elementSummary The `<pc-anim-clip>` element declares one named animation clip on its parent
  * `<pc-anim>`, taken from the `asset` it names or, without one, from the enclosing `<pc-model>`'s
  * own animations. Must be a direct child of `<pc-anim>`.
- *
- * @category Components
  */
 declare class AnimClipElement extends AsyncElement {
     /**

package/dist/components/anim-clip.d.ts

@@ -16,8 +16,6 @@ import { AnimComponentElement } from './anim-component.js';
  * @elementSummary The `<pc-anim-clip>` element declares one named animation clip on its parent
  * `<pc-anim>`, taken from the `asset` it names or, without one, from the enclosing `<pc-model>`'s
  * own animations. Must be a direct child of `<pc-anim>`.
- *
- * @category Components
  */
 declare class AnimClipElement extends AsyncElement {
     /**

package/dist/components/button-component.d.cts

@@ -50,15 +50,19 @@ declare class ButtonComponentElement extends ComponentElement {
      */
     get active(): boolean;
     /**
-     * Sets the reference (CSS selector, element id or entity name) to the `<pc-entity>` whose image
-     * element is used for visual transitions. Defaults to the button's own entity — inside a
-     * `<pc-model>`, that is the model's host entity, so supply an explicit reference to target a
-     * UI entity instead.
+     * Sets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the entity whose image element is used for visual transitions. An exact name
+     * resolves against the nearest enclosing entity first, then outward, then the document.
+     * Defaults to the button's own entity — inside a `<pc-model>`, that is the model's host
+     * entity, so supply an explicit reference to target a UI entity instead. A non-empty
+     * reference that does not resolve warns and is ignored.
      * @param value - The image entity reference.
      */
     set image(value: string);
     /**
-     * Gets the reference to the `<pc-entity>` whose image element is used for visual transitions.
+     * Gets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the entity whose image element is used for visual transitions, or empty for
+     * the button's own entity.
      * @returns The image entity reference.
      */
     get image(): string;

package/dist/components/button-component.d.ts

@@ -50,15 +50,19 @@ declare class ButtonComponentElement extends ComponentElement {
      */
     get active(): boolean;
     /**
-     * Sets the reference (CSS selector, element id or entity name) to the `<pc-entity>` whose image
-     * element is used for visual transitions. Defaults to the button's own entity — inside a
-     * `<pc-model>`, that is the model's host entity, so supply an explicit reference to target a
-     * UI entity instead.
+     * Sets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the entity whose image element is used for visual transitions. An exact name
+     * resolves against the nearest enclosing entity first, then outward, then the document.
+     * Defaults to the button's own entity — inside a `<pc-model>`, that is the model's host
+     * entity, so supply an explicit reference to target a UI entity instead. A non-empty
+     * reference that does not resolve warns and is ignored.
      * @param value - The image entity reference.
      */
     set image(value: string);
     /**
-     * Gets the reference to the `<pc-entity>` whose image element is used for visual transitions.
+     * Gets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the entity whose image element is used for visual transitions, or empty for
+     * the button's own entity.
      * @returns The image entity reference.
      */
     get image(): string;

package/dist/components/joint-component.d.cts

@@ -19,7 +19,12 @@ export type MotionMode = 'locked' | 'limited' | 'free';
  * primary axis: a hinge rotates about it, a slider translates along it and a ball joint twists
  * about it. The constrained bodies are referenced by `entity-a` and `entity-b`, both of which need
  * a rigid body component; leaving `entity-b` empty constrains `entity-a` to a fixed point in world
- * space. The underlying engine component is in alpha, so its API may change.
+ * space. A reference can name any entity-fronting element — `<pc-entity>`, `<pc-model>` or
+ * `<pc-node>`, so a ragdoll can join a model's own skeleton nodes by name — and a name resolves
+ * against the nearest enclosing entity first, then outward through the entity hierarchy, then the
+ * document, while a `#` selector resolves document-wide. A `<template>` prefab with one
+ * entity-fronting root can therefore wire its joints by name and stay self-contained when cloned.
+ * The underlying engine component is in alpha, so its API may change.
  *
  * @elementSummary The `<pc-joint>` element constrains two rigid bodies to each other — a hinged
  * door, a swinging chain, a sliding drawer. Its entity's transform is the joint frame, and
@@ -327,27 +332,36 @@ declare class JointComponentElement extends ComponentElement {
      */
     get enableLimits(): boolean;
     /**
-     * Sets the reference (CSS selector, element id or entity name) to the `<pc-entity>` providing
-     * the first constrained body. The reference resolves when it is set, so an entity created
-     * later is picked up by setting the attribute again.
+     * Sets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the element providing the first constrained body. An exact name resolves
+     * against the nearest enclosing entity first, then outward, then the document. The reference
+     * resolves when it is set, so an entity created later is picked up by setting the attribute
+     * again. A non-empty reference that does not resolve warns, naming which of the two causes it
+     * hit.
      * @param value - The first body's entity reference.
      */
     set entityA(value: string);
     /**
-     * Gets the reference to the `<pc-entity>` providing the first constrained body.
+     * Gets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the element providing the first constrained body.
      * @returns The first body's entity reference.
      */
     get entityA(): string;
     /**
-     * Sets the reference (CSS selector, element id or entity name) to the `<pc-entity>` providing
-     * the second constrained body, or empty to constrain the first body to a fixed point in world
-     * space. The reference resolves when it is set, so an entity created later is picked up by
-     * setting the attribute again.
+     * Sets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the element providing the second constrained body, or empty to constrain the
+     * first body to a fixed point in world space. An exact name resolves against the nearest
+     * enclosing entity first, then outward, then the document. The reference resolves when it is
+     * set, so an entity created later is picked up by setting the attribute again. A non-empty
+     * reference that does not resolve warns; an empty one is the documented world-space case and
+     * stays silent.
      * @param value - The second body's entity reference.
      */
     set entityB(value: string);
     /**
-     * Gets the reference to the `<pc-entity>` providing the second constrained body.
+     * Gets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the element providing the second constrained body, or empty for the
+     * world-space case.
      * @returns The second body's entity reference.
      */
     get entityB(): string;

package/dist/components/joint-component.d.ts

@@ -19,7 +19,12 @@ export type MotionMode = 'locked' | 'limited' | 'free';
  * primary axis: a hinge rotates about it, a slider translates along it and a ball joint twists
  * about it. The constrained bodies are referenced by `entity-a` and `entity-b`, both of which need
  * a rigid body component; leaving `entity-b` empty constrains `entity-a` to a fixed point in world
- * space. The underlying engine component is in alpha, so its API may change.
+ * space. A reference can name any entity-fronting element — `<pc-entity>`, `<pc-model>` or
+ * `<pc-node>`, so a ragdoll can join a model's own skeleton nodes by name — and a name resolves
+ * against the nearest enclosing entity first, then outward through the entity hierarchy, then the
+ * document, while a `#` selector resolves document-wide. A `<template>` prefab with one
+ * entity-fronting root can therefore wire its joints by name and stay self-contained when cloned.
+ * The underlying engine component is in alpha, so its API may change.
  *
  * @elementSummary The `<pc-joint>` element constrains two rigid bodies to each other — a hinged
  * door, a swinging chain, a sliding drawer. Its entity's transform is the joint frame, and
@@ -327,27 +332,36 @@ declare class JointComponentElement extends ComponentElement {
      */
     get enableLimits(): boolean;
     /**
-     * Sets the reference (CSS selector, element id or entity name) to the `<pc-entity>` providing
-     * the first constrained body. The reference resolves when it is set, so an entity created
-     * later is picked up by setting the attribute again.
+     * Sets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the element providing the first constrained body. An exact name resolves
+     * against the nearest enclosing entity first, then outward, then the document. The reference
+     * resolves when it is set, so an entity created later is picked up by setting the attribute
+     * again. A non-empty reference that does not resolve warns, naming which of the two causes it
+     * hit.
      * @param value - The first body's entity reference.
      */
     set entityA(value: string);
     /**
-     * Gets the reference to the `<pc-entity>` providing the first constrained body.
+     * Gets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the element providing the first constrained body.
      * @returns The first body's entity reference.
      */
     get entityA(): string;
     /**
-     * Sets the reference (CSS selector, element id or entity name) to the `<pc-entity>` providing
-     * the second constrained body, or empty to constrain the first body to a fixed point in world
-     * space. The reference resolves when it is set, so an entity created later is picked up by
-     * setting the attribute again.
+     * Sets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the element providing the second constrained body, or empty to constrain the
+     * first body to a fixed point in world space. An exact name resolves against the nearest
+     * enclosing entity first, then outward, then the document. The reference resolves when it is
+     * set, so an entity created later is picked up by setting the attribute again. A non-empty
+     * reference that does not resolve warns; an empty one is the documented world-space case and
+     * stays silent.
      * @param value - The second body's entity reference.
      */
     set entityB(value: string);
     /**
-     * Gets the reference to the `<pc-entity>` providing the second constrained body.
+     * Gets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the element providing the second constrained body, or empty for the
+     * world-space case.
      * @returns The second body's entity reference.
      */
     get entityB(): string;

package/dist/components/script-component.d.cts

@@ -38,8 +38,10 @@ declare 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)

package/dist/components/script-component.d.ts

@@ -38,8 +38,10 @@ declare 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)

package/dist/components/script-instance.d.cts

@@ -12,7 +12,9 @@ import { AsyncElement } from '../async-element.cjs';
  *   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`).
  *
@@ -28,7 +30,8 @@ import { AsyncElement } from '../async-element.cjs';
  *
  * @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.
@@ -43,14 +46,19 @@ declare 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>);
     /**
-     * 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/dist/components/script-instance.d.ts

@@ -12,7 +12,9 @@ import { AsyncElement } from '../async-element.js';
  *   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`).
  *
@@ -28,7 +30,8 @@ import { AsyncElement } from '../async-element.js';
  *
  * @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.
@@ -43,14 +46,19 @@ declare 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>);
     /**
-     * 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/dist/components/scroll-view-component.d.cts

@@ -135,46 +135,58 @@ declare class ScrollViewComponentElement extends ComponentElement {
      */
     get verticalScrollbarVisibility(): "always" | "when-required";
     /**
-     * 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);
     /**
-     * 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(): string;
     /**
-     * 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);
     /**
-     * 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(): string;
     /**
-     * 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);
     /**
-     * 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(): string;
     /**
-     * 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);
     /**
-     * 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(): string;

package/dist/components/scroll-view-component.d.ts

@@ -135,46 +135,58 @@ declare class ScrollViewComponentElement extends ComponentElement {
      */
     get verticalScrollbarVisibility(): "always" | "when-required";
     /**
-     * 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);
     /**
-     * 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(): string;
     /**
-     * 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);
     /**
-     * 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(): string;
     /**
-     * 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);
     /**
-     * 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(): string;
     /**
-     * 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);
     /**
-     * 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(): string;

package/dist/components/scrollbar-component.d.cts

@@ -59,13 +59,16 @@ declare class ScrollbarComponentElement extends ComponentElement {
      */
     get handleSize(): number;
     /**
-     * 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);
     /**
-     * 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(): string;