@playcanvas/web-components 0.19.0 → 0.21.0

package/dist/app.d.cts

@@ -62,25 +62,13 @@ declare class AppElement extends AsyncElement {
      * engine scene nodes back to their owning elements by identity - never by name.
      */
     private _entityElements;
-    private _picker;
-    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.
+     * The pointer-input subsystem: the picker, the canvas handlers, and the synthesized-event
+     * dispatch. The element drives its lifecycle (connect on boot, resize with the drawing
+     * buffer, listener syncs, disconnect on teardown) and hands it the two lookups it needs -
+     * everything else about pointer input lives in the controller.
      */
-    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;
+    private _pointer;
     private _app;
     private _loadProgress;
     /**
@@ -118,8 +106,6 @@ declare class AppElement extends AsyncElement {
      * an XR session presents - the session owns the buffer size.
      */
     private _syncCanvasSize;
-    private _pickerCreate;
-    private _pickerDestroy;
     /**
      * Returns the `<pc-entity>`, `<pc-model>` or `<pc-node>` element whose backing entity is
      * `entity`, or `null` if the entity is not fronted by an element of this application - for
@@ -130,86 +116,6 @@ declare class AppElement extends AsyncElement {
      * @returns The element fronting the entity, or `null`.
      */
     elementFromEntity(entity: Entity): EntityBaseElement | null;
-    /**
-     * Resolves the element that owns hover for a picked node: the nearest node up the parent
-     * chain - starting with the node itself - whose element listens for any of the hover event
-     * types. Skipping silent elements matches {@link _elementWithListener}, so a registered
-     * element with no hover listeners (a `<pc-model>` host, a plain child entity) is transparent
-     * to hover rather than swallowing a listening ancestor's enter/leave pair.
-     *
-     * @param node - The picked node, or `null`.
-     * @returns The hover-owning element, or `null`.
-     */
-    private _hoverTarget;
-    /**
-     * Like {@link _elementFromNode}, but skips elements without a listener for `type`, so a hit
-     * on an unlistened child still reaches a listening ancestor.
-     *
-     * @param node - The picked node, or `null`.
-     * @param type - The pointer event type a listener is required for.
-     * @returns The nearest listening element, or `null`.
-     */
-    private _elementWithListener;
-    /**
-     * Converts a pointer event's client coordinates into drawing-buffer coordinates - the space
-     * the pick buffer and the camera viewports are laid out in. When the canvas has no CSS box
-     * to map through (jsdom; a hidden canvas receives no pointer events in a browser), the
-     * client coordinates are passed through unmapped and `mapped` is false, so callers know the
-     * coordinates correspond to no real geometry.
-     *
-     * @param event - The pointer event to convert.
-     * @param canvas - The canvas the event was dispatched on.
-     * @returns The buffer-space coordinates, and whether they were actually mapped.
-     */
-    private _getPickerCoordinates;
-    /**
-     * Whether a camera's viewport contains the point. A camera renders into its normalized
-     * `rect`, whose origin is the bottom-left of the canvas while buffer coordinates run from
-     * the top-left - so the vertical test flips, as the engine's ElementInput flips it for UI
-     * input. The right and bottom edges are exclusive: a viewport rasterizes the half-open
-     * pixel range [left, right) x [top, bottom), so a coordinate on a shared edge belongs to
-     * the viewport whose first pixel it is - never to the one it just left, whose pick buffer
-     * holds nothing there.
-     *
-     * @param camera - The camera to test.
-     * @param x - The x coordinate, in buffer space.
-     * @param y - The y coordinate, in buffer space.
-     * @param canvas - The canvas the coordinates are relative to.
-     * @returns Whether the camera's viewport contains the point.
-     */
-    private _cameraContains;
-    /**
-     * Picks the scene under the pointer and returns the graph node that was hit, or `null`.
-     *
-     * The camera is resolved the way the engine's ElementInput resolves it for UI input:
-     * enabled cameras are tried topmost-first (they render in ascending `priority` order),
-     * skipping cameras that render to a texture and cameras whose viewport `rect` does not
-     * contain the pointer. A camera that picks nothing ends the search if it clears the color
-     * buffer - its background visually owns the pixel - and otherwise cedes to the cameras
-     * beneath it, so an overlay camera only intercepts picks where it actually drew something.
-     * The pick buffer is prepared per camera, so each camera picks from its own layers.
-     *
-     * The read back is asynchronous because the synchronous {@link Picker.getSelection} is not
-     * supported on WebGPU, where it returns an empty selection rather than failing - which
-     * silently disabled every `onpointer*` handler once WebGPU became the resolved backend. The
-     * async variant works on both backends and does not block the main thread on a GPU read.
-     *
-     * @param event - The pointer event to pick under.
-     * @returns The graph node under the pointer, or `null` if nothing was hit.
-     */
-    private _pickNode;
-    private _onPointerMove;
-    private _onPointerDown;
-    private _onPointerUp;
-    /**
-     * 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

@@ -62,25 +62,13 @@ declare class AppElement extends AsyncElement {
      * engine scene nodes back to their owning elements by identity - never by name.
      */
     private _entityElements;
-    private _picker;
-    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.
+     * The pointer-input subsystem: the picker, the canvas handlers, and the synthesized-event
+     * dispatch. The element drives its lifecycle (connect on boot, resize with the drawing
+     * buffer, listener syncs, disconnect on teardown) and hands it the two lookups it needs -
+     * everything else about pointer input lives in the controller.
      */
-    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;
+    private _pointer;
     private _app;
     private _loadProgress;
     /**
@@ -118,8 +106,6 @@ declare class AppElement extends AsyncElement {
      * an XR session presents - the session owns the buffer size.
      */
     private _syncCanvasSize;
-    private _pickerCreate;
-    private _pickerDestroy;
     /**
      * Returns the `<pc-entity>`, `<pc-model>` or `<pc-node>` element whose backing entity is
      * `entity`, or `null` if the entity is not fronted by an element of this application - for
@@ -130,86 +116,6 @@ declare class AppElement extends AsyncElement {
      * @returns The element fronting the entity, or `null`.
      */
     elementFromEntity(entity: Entity): EntityBaseElement | null;
-    /**
-     * Resolves the element that owns hover for a picked node: the nearest node up the parent
-     * chain - starting with the node itself - whose element listens for any of the hover event
-     * types. Skipping silent elements matches {@link _elementWithListener}, so a registered
-     * element with no hover listeners (a `<pc-model>` host, a plain child entity) is transparent
-     * to hover rather than swallowing a listening ancestor's enter/leave pair.
-     *
-     * @param node - The picked node, or `null`.
-     * @returns The hover-owning element, or `null`.
-     */
-    private _hoverTarget;
-    /**
-     * Like {@link _elementFromNode}, but skips elements without a listener for `type`, so a hit
-     * on an unlistened child still reaches a listening ancestor.
-     *
-     * @param node - The picked node, or `null`.
-     * @param type - The pointer event type a listener is required for.
-     * @returns The nearest listening element, or `null`.
-     */
-    private _elementWithListener;
-    /**
-     * Converts a pointer event's client coordinates into drawing-buffer coordinates - the space
-     * the pick buffer and the camera viewports are laid out in. When the canvas has no CSS box
-     * to map through (jsdom; a hidden canvas receives no pointer events in a browser), the
-     * client coordinates are passed through unmapped and `mapped` is false, so callers know the
-     * coordinates correspond to no real geometry.
-     *
-     * @param event - The pointer event to convert.
-     * @param canvas - The canvas the event was dispatched on.
-     * @returns The buffer-space coordinates, and whether they were actually mapped.
-     */
-    private _getPickerCoordinates;
-    /**
-     * Whether a camera's viewport contains the point. A camera renders into its normalized
-     * `rect`, whose origin is the bottom-left of the canvas while buffer coordinates run from
-     * the top-left - so the vertical test flips, as the engine's ElementInput flips it for UI
-     * input. The right and bottom edges are exclusive: a viewport rasterizes the half-open
-     * pixel range [left, right) x [top, bottom), so a coordinate on a shared edge belongs to
-     * the viewport whose first pixel it is - never to the one it just left, whose pick buffer
-     * holds nothing there.
-     *
-     * @param camera - The camera to test.
-     * @param x - The x coordinate, in buffer space.
-     * @param y - The y coordinate, in buffer space.
-     * @param canvas - The canvas the coordinates are relative to.
-     * @returns Whether the camera's viewport contains the point.
-     */
-    private _cameraContains;
-    /**
-     * Picks the scene under the pointer and returns the graph node that was hit, or `null`.
-     *
-     * The camera is resolved the way the engine's ElementInput resolves it for UI input:
-     * enabled cameras are tried topmost-first (they render in ascending `priority` order),
-     * skipping cameras that render to a texture and cameras whose viewport `rect` does not
-     * contain the pointer. A camera that picks nothing ends the search if it clears the color
-     * buffer - its background visually owns the pixel - and otherwise cedes to the cameras
-     * beneath it, so an overlay camera only intercepts picks where it actually drew something.
-     * The pick buffer is prepared per camera, so each camera picks from its own layers.
-     *
-     * The read back is asynchronous because the synchronous {@link Picker.getSelection} is not
-     * supported on WebGPU, where it returns an empty selection rather than failing - which
-     * silently disabled every `onpointer*` handler once WebGPU became the resolved backend. The
-     * async variant works on both backends and does not block the main thread on a GPU read.
-     *
-     * @param event - The pointer event to pick under.
-     * @returns The graph node under the pointer, or `null` if nothing was hit.
-     */
-    private _pickNode;
-    private _onPointerMove;
-    private _onPointerDown;
-    private _onPointerUp;
-    /**
-     * 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/asset-binding.d.cts

@@ -0,0 +1 @@
+export {};

package/dist/asset-binding.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -28,6 +28,11 @@ declare class AnimClipElement extends AsyncElement {
      */
     private _animElement;
     private _asset;
+    /**
+     * Watches the current source asset while it loads. Starting a new resolution or
+     * disconnecting cancels it, so a superseded source can never hand its track to the parent.
+     */
+    private _binding;
     /**
      * Incremented on every connect and disconnect, and captured by connectedCallback on entry —
      * a resume from an await abandons itself if the value has moved on, so a stale callback can
@@ -35,19 +40,13 @@ declare class AnimClipElement extends AsyncElement {
      * own callback.
      */
     private _connectionGeneration;
-    private _errorHandle;
     /**
      * Incremented on every track resolution and on disconnect, and captured by a resolution when
-     * it starts. A resolution that resumes from an await or an asset callback abandons itself if
-     * the value has moved on, so a superseded resolution cannot hand a stale track to the parent.
+     * it starts. A resolution that resumes from an await abandons itself if the value has moved
+     * on, so a superseded resolution cannot hand a stale track to the parent. The asset
+     * subscription itself is guarded by the binding above.
      */
     private _loadGeneration;
-    /**
-     * The pending asset subscriptions of the current resolution, if it is waiting for its asset.
-     * Held so that whatever supersedes the resolution can detach the handlers from the asset,
-     * rather than leave them registered until the asset settles (or forever, if it never does).
-     */
-    private _loadHandle;
     private _loop;
     private _name;
     private _speed;
@@ -64,7 +63,6 @@ declare class AnimClipElement extends AsyncElement {
     connectedCallback(): Promise<void>;
     disconnectedCallback(): void;
     protected get animElement(): AnimComponentElement | null;
-    private _detachLoadHandlers;
     /**
      * Complains about the clip's source, once per source value — resolutions re-run on host
      * cycles and model reloads, and must not repeat the complaint.

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

@@ -28,6 +28,11 @@ declare class AnimClipElement extends AsyncElement {
      */
     private _animElement;
     private _asset;
+    /**
+     * Watches the current source asset while it loads. Starting a new resolution or
+     * disconnecting cancels it, so a superseded source can never hand its track to the parent.
+     */
+    private _binding;
     /**
      * Incremented on every connect and disconnect, and captured by connectedCallback on entry —
      * a resume from an await abandons itself if the value has moved on, so a stale callback can
@@ -35,19 +40,13 @@ declare class AnimClipElement extends AsyncElement {
      * own callback.
      */
     private _connectionGeneration;
-    private _errorHandle;
     /**
      * Incremented on every track resolution and on disconnect, and captured by a resolution when
-     * it starts. A resolution that resumes from an await or an asset callback abandons itself if
-     * the value has moved on, so a superseded resolution cannot hand a stale track to the parent.
+     * it starts. A resolution that resumes from an await abandons itself if the value has moved
+     * on, so a superseded resolution cannot hand a stale track to the parent. The asset
+     * subscription itself is guarded by the binding above.
      */
     private _loadGeneration;
-    /**
-     * The pending asset subscriptions of the current resolution, if it is waiting for its asset.
-     * Held so that whatever supersedes the resolution can detach the handlers from the asset,
-     * rather than leave them registered until the asset settles (or forever, if it never does).
-     */
-    private _loadHandle;
     private _loop;
     private _name;
     private _speed;
@@ -64,7 +63,6 @@ declare class AnimClipElement extends AsyncElement {
     connectedCallback(): Promise<void>;
     disconnectedCallback(): void;
     protected get animElement(): AnimComponentElement | null;
-    private _detachLoadHandlers;
     /**
      * Complains about the clip's source, once per source value — resolutions re-run on host
      * cycles and model reloads, and must not repeat the complaint.

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

@@ -34,7 +34,7 @@ type ContainerWithAnimations = ContainerResource & {
  *
  * @category Components
  */
-declare class AnimComponentElement extends ComponentElement {
+declare class AnimComponentElement extends ComponentElement<AnimComponent> {
     /**
      * Whether playback starts automatically once a clip is assigned.
      */
@@ -179,10 +179,11 @@ declare class AnimComponentElement extends ComponentElement {
      */
     transition(name: string, time?: number): void;
     /**
-     * Gets the underlying PlayCanvas anim component.
-     * @returns The anim component.
+     * Gets the underlying PlayCanvas anim component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The anim component, or `null`.
      */
-    get component(): AnimComponent;
+    get component(): AnimComponent | null;
     /**
      * Gets the names of the assigned clips.
      * @returns The clip names, in assignment order.

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

@@ -34,7 +34,7 @@ type ContainerWithAnimations = ContainerResource & {
  *
  * @category Components
  */
-declare class AnimComponentElement extends ComponentElement {
+declare class AnimComponentElement extends ComponentElement<AnimComponent> {
     /**
      * Whether playback starts automatically once a clip is assigned.
      */
@@ -179,10 +179,11 @@ declare class AnimComponentElement extends ComponentElement {
      */
     transition(name: string, time?: number): void;
     /**
-     * Gets the underlying PlayCanvas anim component.
-     * @returns The anim component.
+     * Gets the underlying PlayCanvas anim component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The anim component, or `null`.
      */
-    get component(): AnimComponent;
+    get component(): AnimComponent | null;
     /**
      * Gets the names of the assigned clips.
      * @returns The clip names, in assignment order.

package/dist/components/audio-listener-component.d.cts

@@ -14,13 +14,14 @@ import { ComponentElement } from './component.cjs';
  *
  * @category Components
  */
-declare class AudioListenerComponentElement extends ComponentElement {
+declare class AudioListenerComponentElement extends ComponentElement<AudioListenerComponent> {
     /** @ignore */
     constructor();
     /**
-     * Gets the underlying PlayCanvas audio listener component.
-     * @returns The audio listener component.
+     * Gets the underlying PlayCanvas audio listener component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The audio listener component, or `null`.
      */
-    get component(): AudioListenerComponent;
+    get component(): AudioListenerComponent | null;
 }
 export { AudioListenerComponentElement };

package/dist/components/audio-listener-component.d.ts

@@ -14,13 +14,14 @@ import { ComponentElement } from './component.js';
  *
  * @category Components
  */
-declare class AudioListenerComponentElement extends ComponentElement {
+declare class AudioListenerComponentElement extends ComponentElement<AudioListenerComponent> {
     /** @ignore */
     constructor();
     /**
-     * Gets the underlying PlayCanvas audio listener component.
-     * @returns The audio listener component.
+     * Gets the underlying PlayCanvas audio listener component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The audio listener component, or `null`.
      */
-    get component(): AudioListenerComponent;
+    get component(): AudioListenerComponent | null;
 }
 export { AudioListenerComponentElement };

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

@@ -16,7 +16,7 @@ import { ComponentElement } from './component.cjs';
  *
  * @category Components
  */
-declare class ButtonComponentElement extends ComponentElement {
+declare class ButtonComponentElement extends ComponentElement<ButtonComponent> {
     private _active;
     private _image;
     private _hitPadding;
@@ -35,10 +35,11 @@ declare class ButtonComponentElement extends ComponentElement {
     constructor();
     protected getInitialComponentData(): Record<string, any>;
     /**
-     * Gets the underlying PlayCanvas button component.
-     * @returns The button component.
+     * Gets the underlying PlayCanvas button component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The button component, or `null`.
      */
-    get component(): ButtonComponent;
+    get component(): ButtonComponent | null;
     /**
      * Sets whether the button is active and responds to input.
      * @param value - Whether the button is active.
@@ -50,15 +51,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

@@ -16,7 +16,7 @@ import { ComponentElement } from './component.js';
  *
  * @category Components
  */
-declare class ButtonComponentElement extends ComponentElement {
+declare class ButtonComponentElement extends ComponentElement<ButtonComponent> {
     private _active;
     private _image;
     private _hitPadding;
@@ -35,10 +35,11 @@ declare class ButtonComponentElement extends ComponentElement {
     constructor();
     protected getInitialComponentData(): Record<string, any>;
     /**
-     * Gets the underlying PlayCanvas button component.
-     * @returns The button component.
+     * Gets the underlying PlayCanvas button component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The button component, or `null`.
      */
-    get component(): ButtonComponent;
+    get component(): ButtonComponent | null;
     /**
      * Sets whether the button is active and responds to input.
      * @param value - Whether the button is active.
@@ -50,15 +51,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/camera-component.d.cts

@@ -15,7 +15,7 @@ import { ComponentElement } from './component.cjs';
  *
  * @category Components
  */
-declare class CameraComponentElement extends ComponentElement {
+declare class CameraComponentElement extends ComponentElement<CameraComponent> {
     private _clearColor;
     private _clearColorBuffer;
     private _clearDepth;
@@ -88,10 +88,11 @@ declare class CameraComponentElement extends ComponentElement {
      */
     endXr(): void;
     /**
-     * Gets the underlying PlayCanvas camera component.
-     * @returns The camera component.
+     * Gets the underlying PlayCanvas camera component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The camera component, or `null`.
      */
-    get component(): CameraComponent;
+    get component(): CameraComponent | null;
     /**
      * Sets the clear color of the camera.
      * @param value - The clear color.

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

@@ -15,7 +15,7 @@ import { ComponentElement } from './component.js';
  *
  * @category Components
  */
-declare class CameraComponentElement extends ComponentElement {
+declare class CameraComponentElement extends ComponentElement<CameraComponent> {
     private _clearColor;
     private _clearColorBuffer;
     private _clearDepth;
@@ -88,10 +88,11 @@ declare class CameraComponentElement extends ComponentElement {
      */
     endXr(): void;
     /**
-     * Gets the underlying PlayCanvas camera component.
-     * @returns The camera component.
+     * Gets the underlying PlayCanvas camera component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The camera component, or `null`.
      */
-    get component(): CameraComponent;
+    get component(): CameraComponent | null;
     /**
      * Sets the clear color of the camera.
      * @param value - The clear color.

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

@@ -21,7 +21,7 @@ import { ComponentElement } from './component.cjs';
  *
  * @category Components
  */
-declare class CollisionComponentElement extends ComponentElement {
+declare class CollisionComponentElement extends ComponentElement<CollisionComponent> {
     private _angularOffset;
     private _axis;
     private _convexHull;
@@ -55,10 +55,11 @@ declare class CollisionComponentElement extends ComponentElement {
      */
     private _applyMeshGeometryDefault;
     /**
-     * Gets the underlying PlayCanvas collision component.
-     * @returns The collision component.
+     * Gets the underlying PlayCanvas collision component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The collision component, or `null`.
      */
-    get component(): CollisionComponent;
+    get component(): CollisionComponent | null;
     set angularOffset(value: Quat);
     get angularOffset(): Quat;
     set axis(value: number);

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

@@ -21,7 +21,7 @@ import { ComponentElement } from './component.js';
  *
  * @category Components
  */
-declare class CollisionComponentElement extends ComponentElement {
+declare class CollisionComponentElement extends ComponentElement<CollisionComponent> {
     private _angularOffset;
     private _axis;
     private _convexHull;
@@ -55,10 +55,11 @@ declare class CollisionComponentElement extends ComponentElement {
      */
     private _applyMeshGeometryDefault;
     /**
-     * Gets the underlying PlayCanvas collision component.
-     * @returns The collision component.
+     * Gets the underlying PlayCanvas collision component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The collision component, or `null`.
      */
-    get component(): CollisionComponent;
+    get component(): CollisionComponent | null;
     set angularOffset(value: Quat);
     get angularOffset(): Quat;
     set axis(value: number);