@playcanvas/web-components 0.19.0 → 0.21.0

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

@@ -15,7 +15,7 @@ import { ComponentElement } from './component.cjs';
  *
  * @category Components
  */
-declare class ScreenComponentElement extends ComponentElement {
+declare class ScreenComponentElement extends ComponentElement<ScreenComponent> {
     private _screenSpace;
     private _resolution;
     private _referenceResolution;
@@ -33,10 +33,11 @@ declare class ScreenComponentElement extends ComponentElement {
         screenSpace: boolean;
     };
     /**
-     * Gets the underlying PlayCanvas screen component.
-     * @returns The screen component.
+     * Gets the underlying PlayCanvas screen component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The screen component, or `null`.
      */
-    get component(): ScreenComponent;
+    get component(): ScreenComponent | null;
     set priority(value: number);
     get priority(): number;
     set referenceResolution(value: Vec2);

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

@@ -15,7 +15,7 @@ import { ComponentElement } from './component.js';
  *
  * @category Components
  */
-declare class ScreenComponentElement extends ComponentElement {
+declare class ScreenComponentElement extends ComponentElement<ScreenComponent> {
     private _screenSpace;
     private _resolution;
     private _referenceResolution;
@@ -33,10 +33,11 @@ declare class ScreenComponentElement extends ComponentElement {
         screenSpace: boolean;
     };
     /**
-     * Gets the underlying PlayCanvas screen component.
-     * @returns The screen component.
+     * Gets the underlying PlayCanvas screen component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The screen component, or `null`.
      */
-    get component(): ScreenComponent;
+    get component(): ScreenComponent | null;
     set priority(value: number);
     get priority(): number;
     set referenceResolution(value: Vec2);

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

@@ -29,7 +29,7 @@ export type ScriptNameChangeEvent = {
  *
  * @category Components
  */
-declare class ScriptComponentElement extends ComponentElement {
+declare class ScriptComponentElement extends ComponentElement<ScriptComponent> {
     private observer;
     /** @ignore */
     constructor();
@@ -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)
@@ -169,9 +171,10 @@ declare class ScriptComponentElement extends ComponentElement {
     private handleMutations;
     disconnectedCallback(): void;
     /**
-     * Gets the underlying PlayCanvas script component.
-     * @returns The script component.
+     * Gets the underlying PlayCanvas script component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The script component, or `null`.
      */
-    get component(): ScriptComponent;
+    get component(): ScriptComponent | null;
 }
 export { ScriptComponentElement };

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

@@ -29,7 +29,7 @@ export type ScriptNameChangeEvent = {
  *
  * @category Components
  */
-declare class ScriptComponentElement extends ComponentElement {
+declare class ScriptComponentElement extends ComponentElement<ScriptComponent> {
     private observer;
     /** @ignore */
     constructor();
@@ -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)
@@ -169,9 +171,10 @@ declare class ScriptComponentElement extends ComponentElement {
     private handleMutations;
     disconnectedCallback(): void;
     /**
-     * Gets the underlying PlayCanvas script component.
-     * @returns The script component.
+     * Gets the underlying PlayCanvas script component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The script component, or `null`.
      */
-    get component(): ScriptComponent;
+    get component(): ScriptComponent | null;
 }
 export { ScriptComponentElement };

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

@@ -15,7 +15,7 @@ import { ComponentElement } from './component.cjs';
  *
  * @category Components
  */
-declare class ScrollViewComponentElement extends ComponentElement {
+declare class ScrollViewComponentElement extends ComponentElement<ScrollViewComponent> {
     private _horizontal;
     private _vertical;
     private _scrollMode;
@@ -33,10 +33,11 @@ declare class ScrollViewComponentElement extends ComponentElement {
     constructor();
     protected getInitialComponentData(): Record<string, any>;
     /**
-     * Gets the underlying PlayCanvas scroll view component.
-     * @returns The scroll view component.
+     * Gets the underlying PlayCanvas scroll view component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The scroll view component, or `null`.
      */
-    get component(): ScrollViewComponent;
+    get component(): ScrollViewComponent | null;
     /**
      * Sets whether scrolling along the horizontal axis is enabled. This is a toggle, unlike the
      * `orientation` of a `<pc-scrollbar>`, for which `horizontal` is one of the accepted values.
@@ -135,46 +136,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

@@ -15,7 +15,7 @@ import { ComponentElement } from './component.js';
  *
  * @category Components
  */
-declare class ScrollViewComponentElement extends ComponentElement {
+declare class ScrollViewComponentElement extends ComponentElement<ScrollViewComponent> {
     private _horizontal;
     private _vertical;
     private _scrollMode;
@@ -33,10 +33,11 @@ declare class ScrollViewComponentElement extends ComponentElement {
     constructor();
     protected getInitialComponentData(): Record<string, any>;
     /**
-     * Gets the underlying PlayCanvas scroll view component.
-     * @returns The scroll view component.
+     * Gets the underlying PlayCanvas scroll view component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The scroll view component, or `null`.
      */
-    get component(): ScrollViewComponent;
+    get component(): ScrollViewComponent | null;
     /**
      * Sets whether scrolling along the horizontal axis is enabled. This is a toggle, unlike the
      * `orientation` of a `<pc-scrollbar>`, for which `horizontal` is one of the accepted values.
@@ -135,46 +136,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

@@ -14,7 +14,7 @@ import { ComponentElement } from './component.cjs';
  *
  * @category Components
  */
-declare class ScrollbarComponentElement extends ComponentElement {
+declare class ScrollbarComponentElement extends ComponentElement<ScrollbarComponent> {
     private _orientation;
     private _value;
     private _handleSize;
@@ -23,10 +23,11 @@ declare class ScrollbarComponentElement extends ComponentElement {
     constructor();
     protected getInitialComponentData(): Record<string, any>;
     /**
-     * Gets the underlying PlayCanvas scrollbar component.
-     * @returns The scrollbar component.
+     * Gets the underlying PlayCanvas scrollbar component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The scrollbar component, or `null`.
      */
-    get component(): ScrollbarComponent;
+    get component(): ScrollbarComponent | null;
     /**
      * Sets the orientation of the scrollbar. Can be `horizontal` or `vertical`. Defaults to
      * `horizontal`.
@@ -59,13 +60,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;

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

@@ -14,7 +14,7 @@ import { ComponentElement } from './component.js';
  *
  * @category Components
  */
-declare class ScrollbarComponentElement extends ComponentElement {
+declare class ScrollbarComponentElement extends ComponentElement<ScrollbarComponent> {
     private _orientation;
     private _value;
     private _handleSize;
@@ -23,10 +23,11 @@ declare class ScrollbarComponentElement extends ComponentElement {
     constructor();
     protected getInitialComponentData(): Record<string, any>;
     /**
-     * Gets the underlying PlayCanvas scrollbar component.
-     * @returns The scrollbar component.
+     * Gets the underlying PlayCanvas scrollbar component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The scrollbar component, or `null`.
      */
-    get component(): ScrollbarComponent;
+    get component(): ScrollbarComponent | null;
     /**
      * Sets the orientation of the scrollbar. Can be `horizontal` or `vertical`. Defaults to
      * `horizontal`.
@@ -59,13 +60,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;

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

@@ -14,7 +14,7 @@ import { ComponentElement } from './component.cjs';
  *
  * @category Components
  */
-declare class SoundComponentElement extends ComponentElement {
+declare class SoundComponentElement extends ComponentElement<SoundComponent> {
     private _distanceModel;
     private _maxDistance;
     private _pitch;
@@ -34,10 +34,11 @@ declare class SoundComponentElement extends ComponentElement {
         volume: number;
     };
     /**
-     * Gets the underlying PlayCanvas sound component.
-     * @returns The sound component.
+     * Gets the underlying PlayCanvas sound component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The sound component, or `null`.
      */
-    get component(): SoundComponent;
+    get component(): SoundComponent | null;
     /**
      * Sets which algorithm to use to reduce the volume of the sound as it moves away from the listener.
      * @param value - The distance model.

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

@@ -14,7 +14,7 @@ import { ComponentElement } from './component.js';
  *
  * @category Components
  */
-declare class SoundComponentElement extends ComponentElement {
+declare class SoundComponentElement extends ComponentElement<SoundComponent> {
     private _distanceModel;
     private _maxDistance;
     private _pitch;
@@ -34,10 +34,11 @@ declare class SoundComponentElement extends ComponentElement {
         volume: number;
     };
     /**
-     * Gets the underlying PlayCanvas sound component.
-     * @returns The sound component.
+     * Gets the underlying PlayCanvas sound component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The sound component, or `null`.
      */
-    get component(): SoundComponent;
+    get component(): SoundComponent | null;
     /**
      * Sets which algorithm to use to reduce the volume of the sound as it moves away from the listener.
      * @param value - The distance model.