@playcanvas/web-components 0.12.0 → 0.13.1

package/dist/model.d.cts

@@ -0,0 +1,72 @@
+import type { Entity } from 'playcanvas';
+import { AsyncElement } from './async-element.cjs';
+/**
+ * The ModelElement interface provides properties and methods for manipulating
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-model/ | `<pc-model>`} elements.
+ * The ModelElement interface also inherits the properties and methods of the
+ * {@link HTMLElement} interface.
+ *
+ * The element becomes ready once its container asset has loaded and the instantiated hierarchy has
+ * been added to the scene — `entity` is non-null by then. A failed load also settles readiness,
+ * with `entity` remaining `null`: readiness means the load settled, not that it succeeded — listen
+ * for `error`, or check `entity`, to tell the outcomes apart. Changing `asset` re-arms readiness
+ * and instantiates anew, so a `ready()` obtained after the change resolves against the new
+ * hierarchy. A `pc-model` outside a `pc-app`, or referencing an unknown asset id, warns and never
+ * becomes ready.
+ *
+ * @fires {Event} load - Fired each time a container asset finishes instantiating, including
+ * re-instantiation after `asset` changes. Does not bubble — listen on this element, or use a
+ * capture-phase listener on an ancestor.
+ * @fires {ErrorEvent} error - Fired when the container asset fails to load, with the engine's
+ * error in `message`. Does not bubble. The element still becomes ready — readiness means the load
+ * settled, not that it succeeded.
+ */
+declare class ModelElement extends AsyncElement {
+    private _asset;
+    private _entity;
+    /**
+     * Incremented on every new load and on disconnect, and captured by a load when it starts. A
+     * load that resumes from an await or a load callback abandons itself if the value has moved
+     * on, so a superseded load can neither instantiate a second entity nor parent one that has
+     * since been destroyed.
+     */
+    private _loadGeneration;
+    /**
+     * The pending asset subscriptions of the current load, if it is waiting for its asset. Held
+     * so that whatever supersedes the load 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 _errorHandle;
+    /**
+     * The root entity of the instantiated model. `null` until the container asset has loaded
+     * and been instantiated, and again once the element has been removed from the document.
+     * @returns The model's root entity, or `null`.
+     */
+    get entity(): Entity | null;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private _detachLoadHandlers;
+    /**
+     * Resolves readiness and dispatches the `load` event. Called once the instantiated hierarchy
+     * has been parented — readiness means "in the scene graph", matching `pc-entity`, so a ready
+     * model's entity always has world transforms.
+     */
+    private _announceLoad;
+    private _instantiate;
+    private _loadModel;
+    private _unloadModel;
+    /**
+     * Sets the id of the `pc-asset` to use for the model.
+     * @param value - The asset ID.
+     */
+    set asset(value: string);
+    /**
+     * Gets the id of the `pc-asset` to use for the model.
+     * @returns The asset ID.
+     */
+    get asset(): string;
+    static get observedAttributes(): string[];
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
+}
+export { ModelElement };

package/dist/model.d.ts

@@ -1,5 +1,5 @@
 import type { Entity } from 'playcanvas';
-import { AsyncElement } from './async-element';
+import { AsyncElement } from './async-element.js';
 /**
  * The ModelElement interface provides properties and methods for manipulating
  * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-model/ | `<pc-model>`} elements.

package/dist/module.d.cts

@@ -0,0 +1,29 @@
+import { AsyncElement } from './async-element.cjs';
+/**
+ * The ModuleElement interface provides properties and methods for manipulating
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-module/ | `<pc-module>`}
+ * elements. The ModuleElement interface also inherits the properties and methods of the
+ * {@link AsyncElement} interface.
+ *
+ * The attributes are read once, when the module starts loading - on the element's first
+ * connection, or earlier if a containing `<pc-app>` boots first and collects it - so changing
+ * them later has no effect. The element becomes ready once the module has loaded. WebAssembly
+ * modules configure engine-global state that never unloads, so readiness is not re-armed by
+ * removing the element, and a re-inserted element does not load again.
+ *
+ * A `<pc-module>` without a `name` warns and never becomes ready; a containing `<pc-app>` still
+ * boots.
+ *
+ * @attribute {string} name - The name of the WebAssembly module to configure, e.g. `Basis` or
+ * `Ammo`.
+ * @attribute {string} glue - The URL of the module's glue script.
+ * @attribute {string} wasm - The URL of the module's WebAssembly binary.
+ * @attribute {string} fallback - The URL of the module's asm.js fallback script, used when
+ * WebAssembly is unavailable.
+ */
+declare class ModuleElement extends AsyncElement {
+    private _loadPromise;
+    connectedCallback(): void;
+    private _loadModule;
+}
+export { ModuleElement };

package/dist/module.d.ts

@@ -1,11 +1,18 @@
+import { AsyncElement } from './async-element.js';
 /**
  * The ModuleElement interface provides properties and methods for manipulating
- * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-module/ | `<pc-module>`} elements.
- * The ModuleElement interface also inherits the properties and methods of the
- * {@link HTMLElement} interface.
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-module/ | `<pc-module>`}
+ * elements. The ModuleElement interface also inherits the properties and methods of the
+ * {@link AsyncElement} interface.
  *
- * Note that these attributes are read once when the element is created, so changing them later
- * has no effect.
+ * The attributes are read once, when the module starts loading - on the element's first
+ * connection, or earlier if a containing `<pc-app>` boots first and collects it - so changing
+ * them later has no effect. The element becomes ready once the module has loaded. WebAssembly
+ * modules configure engine-global state that never unloads, so readiness is not re-armed by
+ * removing the element, and a re-inserted element does not load again.
+ *
+ * A `<pc-module>` without a `name` warns and never becomes ready; a containing `<pc-app>` still
+ * boots.
  *
  * @attribute {string} name - The name of the WebAssembly module to configure, e.g. `Basis` or
  * `Ammo`.
@@ -14,10 +21,9 @@
  * @attribute {string} fallback - The URL of the module's asm.js fallback script, used when
  * WebAssembly is unavailable.
  */
-declare class ModuleElement extends HTMLElement {
-    private loadPromise;
-    /** @ignore */
-    constructor();
-    private loadModule;
+declare class ModuleElement extends AsyncElement {
+    private _loadPromise;
+    connectedCallback(): void;
+    private _loadModule;
 }
 export { ModuleElement };

package/dist/node.d.cts

@@ -0,0 +1,253 @@
+import { Vec3 } from 'playcanvas';
+import { EntityBaseElement } from './entity-base.cjs';
+/**
+ * The binding states a `<pc-node>` element moves through. `pending` while the host has not yet
+ * instantiated (or no `name` is assigned), `bound` once a node has been resolved and decorated,
+ * `missing`/`ambiguous`/`duplicate` when resolution failed — each accompanied by a warning
+ * naming the cause.
+ */
+type NodeBindingState = 'pending' | 'bound' | 'missing' | 'ambiguous' | 'duplicate';
+/**
+ * The NodeElement interface provides properties and methods for manipulating
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-node/ | `<pc-node>`}
+ * elements. The NodeElement interface also inherits the properties and methods of the
+ * {@link HTMLElement} interface.
+ *
+ * A `pc-node` is an override element: where `pc-entity` creates an entity, `pc-node` binds to a
+ * node a `pc-model` loaded and declares overrides against the authored asset — components to
+ * add, properties to change, content to attach. Attributes present apply as overrides; attributes
+ * absent leave authored values untouched, and removing an attribute (or assigning `null` to the
+ * matching property) restores the authored value.
+ *
+ * `name` selects among the host model's nodes (first match in depth-first order), nesting a
+ * `pc-node` inside another scopes the search to that subtree, and `index` picks among identically
+ * named matches. When `name` matches more than one node and no `index` is given, the element
+ * warns and binds nothing.
+ *
+ * The element becomes ready once bound, and never while unresolved — a missing or ambiguous
+ * name warns and records the failure in `state`, readiness stays unresolved, and descendants
+ * wait with it.
+ *
+ * The pointer events below are dispatched by the containing `<pc-app>` element when the pointer
+ * intersects the bound node's geometry, exactly as for `<pc-entity>`.
+ *
+ * @attribute {string} name - The name of the node to bind, resolved within the nearest ancestor
+ * `pc-model` (or `pc-node`) once it has instantiated.
+ * @attribute {number} index - Which match to bind when `name` matches more than one node,
+ * 0-based in depth-first order. Optional for a unique match; required for an ambiguous one.
+ * @attribute {boolean} enabled - Overrides the node's enabled state.
+ * @attribute {string} position - Overrides the node's local position, as an "x y z" triple.
+ * @attribute {string} rotation - Overrides the node's local rotation (Euler angles), as an
+ * "x y z" triple.
+ * @attribute {string} scale - Overrides the node's local scale, as an "x y z" triple.
+ * @attribute {string} tags - Overrides the node's tags, separated by spaces or commas.
+ * @attribute {string} onpointerenter - Script to run when the pointer moves onto the node.
+ * @attribute {string} onpointerleave - Script to run when the pointer moves off the node.
+ * @attribute {string} onpointermove - Script to run when the pointer moves over the node.
+ * @attribute {string} onpointerdown - Script to run when a pointer button is pressed over the
+ * node.
+ * @attribute {string} onpointerup - Script to run when a pointer button is released over the
+ * node.
+ * @fires {PointerEvent} pointerenter - Fired when the pointer moves onto the node.
+ * @fires {PointerEvent} pointerleave - Fired when the pointer moves off the node.
+ * @fires {PointerEvent} pointermove - Fired when the pointer moves over the node.
+ * @fires {PointerEvent} pointerdown - Fired when a pointer button is pressed over the node.
+ * @fires {PointerEvent} pointerup - Fired when a pointer button is released over the node.
+ */
+declare class NodeElement extends EntityBaseElement {
+    private _name;
+    private _index;
+    private _state;
+    private _path;
+    /**
+     * The element whose entity roots this element's search: the nearest ancestor `pc-node`, or
+     * failing that the nearest ancestor `pc-model`. Resolved on connection.
+     */
+    private _host;
+    /**
+     * The listener following the host's binding cycles. Both host kinds announce each cycle
+     * with a `ready` event — `pc-model` on every instantiation, `pc-node` on every bind.
+     */
+    private _hostListener;
+    /**
+     * The subscription to the bound entity's destruction, detached on unbind so a retargeted
+     * element cannot be reset by the eventual death of a node it no longer fronts.
+     */
+    private _destroyHandle;
+    /** The authored values displaced by this element's overrides, captured per property. */
+    private _authored;
+    private _enabled;
+    private _position;
+    private _rotation;
+    private _scale;
+    private _tags;
+    /**
+     * The binding state: `pending` until the host instantiates and `name` resolves, `bound`
+     * once decorated, `missing`/`ambiguous`/`duplicate` when resolution failed (each also
+     * warns). Useful for asserting a document's bindings programmatically.
+     * @returns The binding state.
+     */
+    get state(): NodeBindingState;
+    /**
+     * The path of the bound node below the search root, `/`-separated, or `null` while not
+     * bound.
+     * @returns The bound node's path, or `null`.
+     */
+    get path(): string | null;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /**
+     * Re-resolves the binding against the host's current hierarchy: on connection, on a `name`
+     * or `index` change, and on every host cycle (a model [re]instantiating, an enclosing
+     * `pc-node` [re]binding). When re-resolution yields the entity already bound, the binding
+     * is retained untouched — a redundant edit must not flicker overrides through a revert.
+     */
+    private _rebind;
+    /**
+     * Resolves `name` (and `index`) to an entity under `hostEntity`, warning and recording the
+     * failure state when it cannot.
+     *
+     * @param hostEntity - The root of the search.
+     * @returns The resolved entity, or `null`.
+     */
+    private _resolve;
+    /**
+     * Binds `target`: registers it (making it a pick target), hooks its destruction, applies
+     * this element's overrides, announces readiness and builds the deferred child subtree.
+     *
+     * @param target - The entity to bind.
+     * @param hostEntity - The search root, for the path.
+     */
+    private _bind;
+    /**
+     * Dissolves the current binding, restoring every authored value this element's overrides
+     * displaced and removing the decorations this binding hosts: attachment entities are
+     * destroyed (re-created against the next binding) and component decorations are removed
+     * from the abandoned node. Both sweeps are scoped by `closestEntity`, so a still-bound
+     * nested `pc-node` keeps its own decorations. Safe to call in any state.
+     */
+    private _unbind;
+    /**
+     * Handles the destruction of the bound entity - its model unloading, reloading, or a script
+     * destroying it. There is nothing to revert on a destroyed entity; the element returns to
+     * pending and the host's next cycle re-resolves it.
+     */
+    private _onEntityDestroy;
+    /**
+     * Creates and parents the entities of child `pc-entity` elements - the attachment points.
+     * Mirrors the runtime-insertion path in EntityElement.connectedCallback: children were
+     * deferred while this host was unresolved (or reset when a previous binding dissolved), and
+     * build here once it binds.
+     */
+    private _buildChildren;
+    /**
+     * Applies every override that is explicitly set, capturing the authored value it displaces.
+     */
+    private _applyOverrides;
+    /**
+     * Restores every authored value this element's overrides displaced. The override values
+     * themselves are kept - they re-apply on the next binding.
+     */
+    private _revertOverrides;
+    /**
+     * Renders the path of `node` below `root`, for the `path` property and the resolution
+     * warnings.
+     *
+     * @param node - The node to describe.
+     * @param root - The search root.
+     * @returns The `/`-separated path.
+     */
+    private _pathOf;
+    /**
+     * Describes the search root for warnings: the model's asset id, or the enclosing node's
+     * name.
+     * @returns The description.
+     */
+    private _describeHost;
+    /**
+     * Finds the node name nearest to the missing `name`, for the miss warning. The names are
+     * already in hand from resolution, so the suggestion is nearly free.
+     *
+     * @param hostEntity - The root of the search.
+     * @returns The closest name within an edit distance of 2, or `null`.
+     */
+    private _closestName;
+    /**
+     * Sets the name of the node to bind. A change retargets: the current binding's overrides
+     * revert and the new name resolves afresh. `name` on a `pc-node` is never a rename of the
+     * authored node - it is only ever a reference.
+     * @param value - The node name.
+     */
+    set name(value: string);
+    /**
+     * Gets the name of the node to bind.
+     * @returns The node name.
+     */
+    get name(): string;
+    /**
+     * Sets which match to bind when `name` matches more than one node, 0-based in depth-first
+     * order. A change retargets, like `name`. `null` means unset - required when the name is
+     * ambiguous, optional otherwise.
+     * @param value - The match index, or `null`.
+     */
+    set index(value: number | null);
+    /**
+     * Gets which match to bind.
+     * @returns The match index, or `null` when unset.
+     */
+    get index(): number | null;
+    /**
+     * Sets the enabled override. `null` clears it, restoring the authored state.
+     * @param value - The enabled state, or `null`.
+     */
+    set enabled(value: boolean | null);
+    /**
+     * Gets the enabled override.
+     * @returns The enabled state, or `null` while no override is set.
+     */
+    get enabled(): boolean | null;
+    /**
+     * Sets the local position override. `null` clears it, restoring the authored position.
+     * @param value - The position, or `null`.
+     */
+    set position(value: Vec3 | null);
+    /**
+     * Gets the local position override.
+     * @returns The position, or `null` while no override is set.
+     */
+    get position(): Vec3 | null;
+    /**
+     * Sets the local rotation override, as Euler angles in degrees. `null` clears it, restoring
+     * the authored rotation.
+     * @param value - The rotation, or `null`.
+     */
+    set rotation(value: Vec3 | null);
+    /**
+     * Gets the local rotation override.
+     * @returns The rotation, or `null` while no override is set.
+     */
+    get rotation(): Vec3 | null;
+    /**
+     * Sets the local scale override. `null` clears it, restoring the authored scale.
+     * @param value - The scale, or `null`.
+     */
+    set scale(value: Vec3 | null);
+    /**
+     * Gets the local scale override.
+     * @returns The scale, or `null` while no override is set.
+     */
+    get scale(): Vec3 | null;
+    /**
+     * Sets the tags override. `null` clears it, restoring the authored tags.
+     * @param value - The tags, or `null`.
+     */
+    set tags(value: string[] | null);
+    /**
+     * Gets the tags override.
+     * @returns The tags, or `null` while no override is set.
+     */
+    get tags(): string[] | null;
+    static get observedAttributes(): string[];
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
+}
+export { NodeElement };

package/dist/node.d.ts

@@ -1,5 +1,5 @@
 import { Vec3 } from 'playcanvas';
-import { EntityBaseElement } from './entity-base';
+import { EntityBaseElement } from './entity-base.js';
 /**
  * The binding states a `<pc-node>` element moves through. `pending` while the host has not yet
  * instantiated (or no `name` is assigned), `bound` once a node has been resolved and decorated,

package/dist/parse.d.cts

@@ -0,0 +1,147 @@
+/**
+ * Converts HTML attribute values into the values the engine expects. Every element's
+ * `attributeChangedCallback` funnels through this module.
+ *
+ * The parsers share one contract:
+ *
+ * - A `null` value means the attribute is absent or was removed, and yields the supplied default.
+ * - A malformed value yields the same default and logs exactly one `console.warn` naming the
+ *   attribute, so misuse is reported rather than thrown — nothing here throws or rejects.
+ * - A math-type default is cloned on the way out, which is what makes it safe to pass the engine's
+ *   shared frozen constants (`Vec3.ZERO`, `Color.WHITE`) as defaults.
+ * - `parseBool` and `parseTags` take no attribute name, because every value is valid for them and
+ *   so they never warn.
+ *
+ * `getEntity` is the exception: it resolves a reference to a live entity rather than parsing a
+ * literal, and returns `null` instead of falling back to a default.
+ */
+import type { Entity } from 'playcanvas';
+import { Color, Quat, Vec2, Vec3, Vec4 } from 'playcanvas';
+/**
+ * Splits an attribute value into exactly `count` numeric components. Returns `null` when the
+ * value does not consist of exactly `count` whitespace-separated finite numbers.
+ *
+ * @param value - The value to split.
+ * @param count - The required number of components.
+ * @returns The parsed components, or `null`.
+ * @ignore
+ */
+export declare const parseComponents: (value: string, count: number) => number[] | null;
+/**
+ * Parse a boolean attribute value. The same rules apply to every boolean attribute:
+ *
+ * - Attribute absent (or removed): the supplied default is used.
+ * - Attribute set to the string 'false': `false`.
+ * - Attribute present with any other value, including the empty string of a bare boolean
+ *   attribute (e.g. `<pc-light cast-shadows>`): `true`.
+ *
+ * @param value - The attribute value to parse (`null` when the attribute is absent).
+ * @param defaultValue - The value to use when the attribute is absent or removed.
+ * @returns The parsed boolean.
+ */
+export declare const parseBool: (value: string | null, defaultValue: boolean) => boolean;
+/**
+ * Parse a color attribute value. The expected format is a CSS color name (e.g. 'rebeccapurple'),
+ * a hex color (e.g. '#ff0000' or '#f00'), or 3 or 4 space-separated numbers in the range 0 to 1
+ * (e.g. '1 0.5 0.5' or '1 0.5 0.5 0.5'). Returns `defaultValue` (cloned, when it is a color)
+ * when the attribute is absent (`null`), or when the value is malformed — the latter also logs
+ * a warning.
+ *
+ * @param value - The attribute value to parse (`null` when the attribute is absent).
+ * @param defaultValue - The value to use when the attribute is absent or invalid.
+ * @param attribute - The attribute name, used in the warning message.
+ * @returns The parsed Color object.
+ */
+export declare const parseColor: <T extends Color | null>(value: string | null, defaultValue: T, attribute: string) => Color | T;
+/**
+ * Resolves an enum attribute value against its set of valid names. Returns the value when it is
+ * one of the valid names. Returns `defaultValue` when the attribute is absent (`null`), or when
+ * the value is invalid — the latter also logs a warning listing the valid names.
+ *
+ * @param value - The attribute value to parse (`null` when the attribute is absent).
+ * @param valid - The valid names: an array, or a map whose keys are the valid names. Only the keys
+ * are read, so the map's value type is unconstrained - engine enums are mostly numeric constants,
+ * but some (e.g. `SCALEMODE_BLEND`) are strings.
+ * @param defaultValue - The value to use when the attribute is absent or invalid.
+ * @param attribute - The attribute name, used in the warning message.
+ * @returns The resolved enum name.
+ */
+export declare const parseEnum: <T extends string>(value: string | null, valid: readonly T[] | ReadonlyMap<T, unknown>, defaultValue: T, attribute: string) => T;
+/**
+ * Parses a number attribute value. Returns the parsed number when the value is a finite number.
+ * Returns `defaultValue` when the attribute is absent (`null`), or when the value is not a
+ * finite number — the latter also logs a warning.
+ *
+ * @param value - The attribute value to parse (`null` when the attribute is absent).
+ * @param defaultValue - The value to use when the attribute is absent or invalid.
+ * @param attribute - The attribute name, used in the warning message.
+ * @returns The parsed number.
+ */
+export declare const parseNumber: <T extends number | null>(value: string | null, defaultValue: T, attribute: string) => number | T;
+/**
+ * Parse an Euler-angles attribute value into a quaternion. The expected format is 3
+ * space-separated angles in degrees (e.g. '0 90 0'). Returns `defaultValue` (cloned, when it is
+ * a quaternion) when the attribute is absent (`null`), or when the value is malformed — the
+ * latter also logs a warning.
+ *
+ * @param value - The attribute value to parse (`null` when the attribute is absent).
+ * @param defaultValue - The value to use when the attribute is absent or invalid.
+ * @param attribute - The attribute name, used in the warning message.
+ * @returns The parsed Quat object.
+ */
+export declare const parseQuat: <T extends Quat | null>(value: string | null, defaultValue: T, attribute: string) => Quat | T;
+/**
+ * Parse a tags attribute value. The expected format is a comma-separated list of tag names
+ * (e.g. 'enemy, flying'). Surrounding whitespace is trimmed from each name and empty names are
+ * discarded, so a trailing comma or a doubled separator does not produce a blank tag. Returns a
+ * copy of `defaultValue` when the attribute is absent or removed (`null`).
+ *
+ * Every value is valid, so this never warns.
+ *
+ * @param value - The attribute value to parse (`null` when the attribute is absent).
+ * @param defaultValue - The value to use when the attribute is absent or removed.
+ * @returns The parsed tag names.
+ */
+export declare const parseTags: (value: string | null, defaultValue?: string[]) => string[];
+/**
+ * Parse a Vec2 attribute value. The expected format is 2 space-separated numbers (e.g. '1 2').
+ * Returns `defaultValue` (cloned, when it is a vector) when the attribute is absent (`null`),
+ * or when the value is malformed — the latter also logs a warning.
+ *
+ * @param value - The attribute value to parse (`null` when the attribute is absent).
+ * @param defaultValue - The value to use when the attribute is absent or invalid.
+ * @param attribute - The attribute name, used in the warning message.
+ * @returns The parsed Vec2 object.
+ */
+export declare const parseVec2: <T extends Vec2 | null>(value: string | null, defaultValue: T, attribute: string) => Vec2 | T;
+/**
+ * Parse a Vec3 attribute value. The expected format is 3 space-separated numbers (e.g. '1 2 3').
+ * Returns `defaultValue` (cloned, when it is a vector) when the attribute is absent (`null`),
+ * or when the value is malformed — the latter also logs a warning.
+ *
+ * @param value - The attribute value to parse (`null` when the attribute is absent).
+ * @param defaultValue - The value to use when the attribute is absent or invalid.
+ * @param attribute - The attribute name, used in the warning message.
+ * @returns The parsed Vec3 object.
+ */
+export declare const parseVec3: <T extends Vec3 | null>(value: string | null, defaultValue: T, attribute: string) => Vec3 | T;
+/**
+ * Parse a Vec4 attribute value. The expected format is 4 space-separated numbers
+ * (e.g. '1 2 3 4'). Returns `defaultValue` (cloned, when it is a vector) when the attribute is
+ * absent (`null`), or when the value is malformed — the latter also logs a warning.
+ *
+ * @param value - The attribute value to parse (`null` when the attribute is absent).
+ * @param defaultValue - The value to use when the attribute is absent or invalid.
+ * @param attribute - The attribute name, used in the warning message.
+ * @returns The parsed Vec4 object.
+ */
+export declare const parseVec4: <T extends Vec4 | null>(value: string | null, defaultValue: T, attribute: string) => Vec4 | T;
+/**
+ * Resolves a reference string to the {@link Entity} backing a `<pc-entity>` element. The reference
+ * can be a CSS selector (e.g. `#my-id`, `pc-entity[name="Foo"]`), a bare element id, or a bare
+ * entity name. Returns `null` if no matching element (or backing entity) is found.
+ *
+ * @param ref - The reference string to resolve.
+ * @returns The resolved entity, or `null`.
+ */
+export declare const getEntity: (ref: string) => Entity | null;