@playcanvas/web-components 0.15.0 → 0.16.0

package/dist/pwc.cjs

@@ -2926,214 +2926,1391 @@ const useAsset = (id) => {
     return asset;
 };
 
+/**
+ * Formats one line of the printable hierarchy: the node's name, an `[index]` marker when the
+ * name is shared by several nodes in the model, the attached component types, and the material
+ * names of a render component.
+ *
+ * @param node - The node to format.
+ * @param counts - The number of nodes bearing each name.
+ * @returns The formatted line.
+ */
+const formatNode = (node, counts) => {
+    const index = (counts.get(node.name) ?? 0) > 1 ? ` [${node.index}]` : '';
+    const components = node.components.length > 0 ? ` (${node.components.join(', ')})` : '';
+    // Braces rather than brackets: `[N]` already means a match index on this line
+    const materials = node.materials.length > 0 ? ` {${node.materials.map((slot) => slot.name ?? 'null').join(', ')}}` : '';
+    return `${node.name}${index}${components}${materials}`;
+};
+/**
+ * Formats the printable form of a hierarchy subtree.
+ *
+ * @param root - The subtree root.
+ * @param counts - The number of nodes bearing each name.
+ * @returns The tree, one line per node.
+ */
+const formatHierarchy = (root, counts) => {
+    const lines = [formatNode(root, counts)];
+    const walk = (node, prefix) => {
+        node.children.forEach((child, i) => {
+            const last = i === node.children.length - 1;
+            lines.push(`${prefix}${last ? '└─ ' : '├─ '}${formatNode(child, counts)}`);
+            walk(child, `${prefix}${last ? '   ' : '│  '}`);
+        });
+    };
+    walk(root, '');
+    return lines.join('\n');
+};
+/**
+ * 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.
+ */
+class ModelElement extends AsyncElement {
+    _asset = '';
+    _entity = null;
+    /**
+     * 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.
+     */
+    _loadGeneration = 0;
+    /**
+     * 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).
+     */
+    _loadHandle = null;
+    _errorHandle = null;
+    /**
+     * 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() {
+        return this._entity;
+    }
+    /**
+     * Returns a snapshot of the instantiated node tree, or `null` while there is none (the
+     * container asset has not loaded, or the element has left the document). One call grounds a
+     * session — a browser console, a test, an agent — in the vocabulary `pc-node` binding
+     * resolves against: the instantiated names ({@link HierarchyNode.name}), paths, match
+     * indices, attached component types and the material assignments of render components
+     * ({@link HierarchyNode.materials}). `String(...)` of the result, or of any node in it,
+     * is the printable form.
+     *
+     * The snapshot is plain data, computed afresh each call: it does not follow later changes
+     * to the hierarchy, and mutating it changes nothing.
+     *
+     * @returns The root of the instantiated node tree, or `null`.
+     */
+    hierarchy() {
+        const root = this._entity;
+        if (!root) {
+            return null;
+        }
+        // Ordinals are assigned in the traversal resolution searches — pre-order depth-first
+        // from the model root, the root itself included — so each node's index is exactly what
+        // a pc-node's index attribute selects. Once the walk completes, the map holds the total
+        // count per name, which is what the printable form reads to annotate only shared names.
+        const ordinals = new Map();
+        const describe = (entity, pathBelowRoot) => {
+            const index = ordinals.get(entity.name) ?? 0;
+            ordinals.set(entity.name, index + 1);
+            const node = {
+                name: entity.name,
+                // The root has no path below itself; its own name stands in, as it does for
+                // the path a pc-node bound to the root reports.
+                path: pathBelowRoot || entity.name,
+                index,
+                // A plain GraphNode grafted into the hierarchy has no component storage
+                components: Object.keys(entity.c ?? {}).sort(),
+                materials: (entity.render?.meshInstances ?? []).map((meshInstance, slot) => ({
+                    index: slot,
+                    name: meshInstance.material?.name ?? null
+                })),
+                children: entity.children.map((child) => describe(child, pathBelowRoot ? `${pathBelowRoot}/${child.name}` : child.name))
+            };
+            // Non-enumerable, keeping the snapshot plain data under JSON.stringify, spreads and
+            // key enumeration. Deferred to call time, by which the ordinal map holds its totals.
+            Object.defineProperty(node, 'toString', {
+                enumerable: false,
+                value: () => formatHierarchy(node, ordinals)
+            });
+            return node;
+        };
+        return describe(root, '');
+    }
+    connectedCallback() {
+        // A model outside an application is inert and never becomes ready, so awaiting it hangs.
+        // Warn rather than fail silently, naming the parent it requires, as every other misplaced
+        // element does.
+        if (!this.closestApp) {
+            const label = this._asset ? ` '${this._asset}'` : '';
+            console.warn(`pc-model${label} must be a descendant of pc-app - model not created`);
+            return;
+        }
+        this._loadModel();
+    }
+    disconnectedCallback() {
+        this._loadGeneration++;
+        this._detachLoadHandlers();
+        this._unloadModel();
+        this._resetReady();
+    }
+    _detachLoadHandlers() {
+        this._loadHandle?.off();
+        this._loadHandle = null;
+        this._errorHandle?.off();
+        this._errorHandle = null;
+    }
+    /**
+     * 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.
+     */
+    _announceLoad() {
+        this._onReady();
+        this.dispatchEvent(new Event('load'));
+    }
+    _instantiate(container) {
+        const generation = this._loadGeneration;
+        const entity = container.instantiateRenderEntity();
+        this._entity = entity;
+        // The parent's readiness re-arms when it is torn down, so these can resume in a later
+        // connection cycle. The entity is captured above and the generation re-checked, so a
+        // stale resume cannot parent an entity a newer cycle has already destroyed.
+        const parentEntityElement = this.closestEntity;
+        if (parentEntityElement) {
+            parentEntityElement.ready().then(() => {
+                if (generation !== this._loadGeneration) {
+                    return;
+                }
+                parentEntityElement.entity.addChild(entity);
+                this._announceLoad();
+            });
+        }
+        else {
+            const appElement = this.closestApp;
+            if (appElement) {
+                appElement.ready().then(() => {
+                    if (generation !== this._loadGeneration) {
+                        return;
+                    }
+                    appElement.app.root.addChild(entity);
+                    this._announceLoad();
+                });
+            }
+        }
+    }
+    async _loadModel() {
+        this._unloadModel();
+        // Supersede any load already in flight - only the newest load may instantiate
+        const generation = ++this._loadGeneration;
+        this._detachLoadHandlers();
+        // Re-arm readiness so a waiter obtained after an asset change resolves against the new
+        // hierarchy. A no-op on first connection, where readiness is still pending.
+        this._resetReady();
+        const appElement = this.closestApp;
+        if (!appElement) {
+            // Outside pc-app; connectedCallback already warned. Reached through the asset setter.
+            return;
+        }
+        await appElement.ready();
+        // The element may have been removed, or another load started, while we waited
+        if (generation !== this._loadGeneration) {
+            return;
+        }
+        const asset = useAsset(this._asset);
+        if (!asset) {
+            // An empty id is a legitimate transient (the asset may be assigned later); a
+            // non-empty one that resolves to nothing is a dead end - say so rather than staying
+            // silently pending.
+            if (this._asset) {
+                console.warn(`pc-model could not find asset '${this._asset}' - model not created`);
+            }
+            return;
+        }
+        if (asset.loaded) {
+            this._instantiate(asset.resource);
+        }
+        else {
+            // The generation is re-checked even though a superseded handler is detached: the
+            // detach relies on how the engine's event emitter treats removal, while the check
+            // holds on its own. Whichever of load/error fires first detaches the other.
+            this._loadHandle = asset.once('load', () => {
+                this._detachLoadHandlers();
+                if (generation !== this._loadGeneration) {
+                    return;
+                }
+                this._instantiate(asset.resource);
+            });
+            this._errorHandle = asset.once('error', (err) => {
+                this._detachLoadHandlers();
+                if (generation !== this._loadGeneration) {
+                    return;
+                }
+                // A failed load settles readiness with a null entity, mirroring pc-asset:
+                // readiness means the load settled, not that it succeeded.
+                this.dispatchEvent(new ErrorEvent('error', {
+                    message: err instanceof Error ? err.message : String(err)
+                }));
+                this._onReady();
+            });
+        }
+    }
+    _unloadModel() {
+        this._entity?.destroy();
+        this._entity = null;
+    }
+    /**
+     * Sets the id of the `pc-asset` to use for the model.
+     * @param value - The asset ID.
+     */
+    set asset(value) {
+        this._asset = value;
+        if (this.isConnected) {
+            this._loadModel();
+        }
+    }
+    /**
+     * Gets the id of the `pc-asset` to use for the model.
+     * @returns The asset ID.
+     */
+    get asset() {
+        return this._asset;
+    }
+    static get observedAttributes() {
+        return ['asset'];
+    }
+    attributeChangedCallback(name, _oldValue, newValue) {
+        switch (name) {
+            case 'asset':
+                this.asset = newValue ?? '';
+                break;
+        }
+    }
+}
+customElements.define('pc-model', ModelElement);
+
 /**
  * Represents a component in the PlayCanvas engine.
  *
  * @category Components
  */
-class ComponentElement extends AsyncElement {
-    _componentName;
-    _enabled = true;
-    _component = null;
-    _appElement = null;
+class ComponentElement extends AsyncElement {
+    _componentName;
+    _enabled = true;
+    _component = null;
+    _appElement = null;
+    /**
+     * The element hosting this component, held so the host's readiness cycles can be observed
+     * even after `closestEntity` would no longer resolve (during teardown).
+     */
+    _hostElement = null;
+    /**
+     * The listener re-applying this component when the host's readiness cycles. Held for
+     * removal on disconnect.
+     */
+    _hostReadyListener = null;
+    /**
+     * Incremented on every connect and disconnect. connectedCallback captures the value on entry
+     * and abandons itself wherever it resumes from an await if the value has moved on — so a
+     * callback whose element was removed cannot act on a torn-down tree, and one whose element
+     * was removed and re-inserted (which runs a callback of its own) cannot add the component a
+     * second time.
+     */
+    _connectionGeneration = 0;
+    /**
+     * Creates a new ComponentElement instance.
+     *
+     * @param componentName - The name of the component.
+     * @ignore
+     */
+    constructor(componentName) {
+        super();
+        this._componentName = componentName;
+    }
+    /**
+     * Returns the data the component is created with. Overridden by subclasses to supply the
+     * initial values of their cached properties.
+     *
+     * @returns The initial component data.
+     */
+    getInitialComponentData() {
+        return {};
+    }
+    /**
+     * Creates the component on the host's current entity, removing it first from a previous
+     * entity that is still alive (a retargeted `<pc-node>` moves its decorations with it). When
+     * the entity already has a component of this type — a glTF node arriving with its authored
+     * `render` component, say — warns and leaves `component` null. The element-level warning is
+     * load-bearing: the engine's own duplicate-addComponent warning is Debug-stripped from
+     * production builds, which would otherwise leave a silent null.
+     */
+    _applyComponent() {
+        const entity = this._hostElement?.entity ?? null;
+        if (this._component && this._component.entity === entity) {
+            return;
+        }
+        // A retarget leaves the previous component on a still-live entity - remove it so the
+        // decoration follows the element, or vanishes with a dissolved binding. A destroyed
+        // entity took its components with it.
+        const previous = this._component;
+        if (previous?.entity && previous.entity.c[this._componentName] === previous) {
+            previous.entity.removeComponent(this._componentName);
+        }
+        this._component = null;
+        if (!entity) {
+            return;
+        }
+        if (entity.c[this._componentName]) {
+            const label = this.id ? ` '${this.id}'` : '';
+            console.warn(`${this.tagName.toLowerCase()}${label} - '${entity.name}' already has a '${this._componentName}' component - component not added`);
+            return;
+        }
+        this._component = entity.addComponent(this._componentName, this.getInitialComponentData());
+    }
+    async _addComponent() {
+        const generation = this._connectionGeneration;
+        const entityElement = this.closestEntity;
+        if (!entityElement) {
+            // A component can only exist on an entity, so an element placed outside one is inert.
+            // It still becomes ready (with a null `component`), so warn rather than fail silently
+            const label = this.id ? ` '${this.id}'` : '';
+            console.warn(`${this.tagName.toLowerCase()}${label} must be a descendant of pc-entity - component not added`);
+            return;
+        }
+        await entityElement.ready();
+        // The element may have been removed, or removed and re-inserted, while the entity became
+        // ready — the component belongs to the connection that owns the current generation.
+        if (generation !== this._connectionGeneration) {
+            return;
+        }
+        this._hostElement = entityElement;
+        this._applyComponent();
+        // Re-apply when the host's readiness cycles without this element disconnecting: a
+        // `<pc-node>` rebinding after its model reloads or retargets, or a re-created entity.
+        // The 'ready' event bubbles, so events from descendants pass through this host - only
+        // the host's own cycles count. Readiness is cycled here too, so decorations one level
+        // down re-apply the same way.
+        this._hostReadyListener = (event) => {
+            if (event.target !== this._hostElement) {
+                return;
+            }
+            if (generation !== this._connectionGeneration) {
+                return;
+            }
+            this._hostCycled();
+        };
+        entityElement.addEventListener('ready', this._hostReadyListener);
+    }
+    /**
+     * Re-evaluates this component against the host's current entity: applied to a new entity,
+     * moved from a still-live old one, or removed when the host no longer fronts an entity at
+     * all. Readiness follows - it cycles with a re-application and stays unresolved while the
+     * host is unbound. Called by the host-ready listener, and directly by a `<pc-node>`
+     * dissolving its binding: the one transition that fires no ready event to ride.
+     *
+     * @internal
+     */
+    _hostCycled() {
+        this._resetReady();
+        this._applyComponent();
+        if (this._hostElement?.entity) {
+            this.initComponent();
+            this._onReady();
+        }
+    }
+    /**
+     * Configures the newly added component. Overridden by subclasses whose setup goes beyond
+     * the initial data — child-element handling, asset resolution and the like.
+     */
+    initComponent() {
+        // optional hook
+    }
+    async connectedCallback() {
+        const generation = ++this._connectionGeneration;
+        this._appElement = this.closestApp ?? null;
+        await this._appElement?.ready();
+        // The element may have been removed, or removed and re-inserted, while the application
+        // became ready. A re-insertion runs a connectedCallback of its own, so a stale resume
+        // must not add the component alongside it.
+        if (generation !== this._connectionGeneration) {
+            return;
+        }
+        await this._addComponent();
+        if (generation !== this._connectionGeneration) {
+            return;
+        }
+        this.initComponent();
+        this._onReady();
+    }
+    disconnectedCallback() {
+        // Invalidate any connectedCallback still suspended on an await
+        this._connectionGeneration++;
+        if (this._hostElement && this._hostReadyListener) {
+            this._hostElement.removeEventListener('ready', this._hostReadyListener);
+        }
+        this._hostElement = null;
+        this._hostReadyListener = null;
+        // Remove the component when the element is disconnected. Skip this when the owning
+        // application has already been destroyed — removing a <pc-app> disconnects it before
+        // its children, taking the component systems with it.
+        if (this._appElement?.app && this._component?.entity) {
+            this._component.entity.removeComponent(this._componentName);
+        }
+        this._component = null;
+        this._appElement = null;
+        this._resetReady();
+    }
+    /**
+     * The PlayCanvas component instance. `null` until the element is ready, and also for an
+     * element that is not a descendant of a `<pc-entity>` — await {@link whenReady} or the
+     * element's `ready()` promise before accessing it.
+     * @returns The component instance, or `null`.
+     */
+    get component() {
+        return this._component;
+    }
+    /**
+     * Sets the enabled state of the component.
+     * @param value - The enabled state of the component.
+     */
+    set enabled(value) {
+        this._enabled = value;
+        if (this.component) {
+            this.component.enabled = value;
+        }
+    }
+    /**
+     * Gets the enabled state of the component.
+     * @returns The enabled state of the component.
+     */
+    get enabled() {
+        return this._enabled;
+    }
+    static get observedAttributes() {
+        return ['enabled'];
+    }
+    attributeChangedCallback(name, _oldValue, newValue) {
+        switch (name) {
+            case 'enabled':
+                this.enabled = parseBool(newValue, true);
+                break;
+        }
+    }
+}
+
+/**
+ * The AnimComponentElement interface provides properties and methods for manipulating
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-anim/ | `<pc-anim>`} elements.
+ * The AnimComponentElement interface also inherits the properties and methods of the
+ * {@link HTMLElement} interface.
+ *
+ * The element drives animation clips over the host entity's hierarchy. Clips come from
+ * `<pc-anim-clip>` children — or, when the element is a direct child of a `<pc-model>` and
+ * declares no clips, every animation of that model's container asset is assigned, named by track
+ * name, in container order. The first clip plays automatically (opt out with `activate="false"`);
+ * switch clips declaratively through the `clip` attribute, or imperatively through {@link play}
+ * and {@link transition}. Tracks bind to scene nodes by name, so any hierarchy whose node names
+ * match a clip's curves can be animated — a model's skeleton is simply the common case.
+ *
+ * The engine reports no clip completion: a non-looping clip holds its last pose silently. Poll
+ * the underlying {@link AnimComponent} (via {@link component}) for playback state beyond what
+ * this element exposes.
+ *
+ * @category Components
+ */
+class AnimComponentElement extends ComponentElement {
+    /**
+     * Whether playback starts automatically once a clip is assigned.
+     */
+    _activate = true;
+    /**
+     * The clip elements whose states are currently assigned, by clip name. The single writer of
+     * a state: a later clip child re-using an adopted name is rejected as a duplicate.
+     */
+    _assignedClips = new Map();
+    /**
+     * Whether the current clip set was auto-assigned from the enclosing model rather than
+     * declared by clip children.
+     */
+    _autoAssigned = false;
+    /**
+     * The name of the active clip.
+     */
+    _clip = '';
+    /**
+     * The element the model-readiness listener is attached to, held so disconnection can detach
+     * it after `closestEntity` no longer resolves.
+     */
+    _modelListenerTarget = null;
+    /**
+     * Incremented whenever the clip source changes, and captured by an auto-assign pass on
+     * entry — a pass resuming from an await abandons itself if the value has moved on, so a
+     * superseded pass cannot assign clips alongside declared children or a newer pass.
+     */
+    _sourceGeneration = 0;
+    /**
+     * The playback speed multiplier applied across all clips.
+     */
+    _speed = 1;
+    /**
+     * The cross-fade duration of declarative clip switches, in seconds.
+     */
+    _transitionTime = 0;
+    /**
+     * The unknown clip name already warned about, so a repeated selection of the same missing
+     * name complains once.
+     */
+    _warnedClip = null;
+    /**
+     * Rebinds when a model under the host announces readiness. The engine resolves each curve
+     * once, at the first tick after assignment, and never retries — and its mesh-instance
+     * broadcast fires before an instantiated hierarchy is parented, so a model that loads after
+     * the clips were assigned would otherwise stay silently unbound. A re-instantiation of the
+     * implicit clip source (the parent `<pc-model>`) means a new container, so the clip set
+     * refreshes instead — unless every clip declares its own asset, where a rebind suffices.
+     */
+    _onModelReady = (event) => {
+        if (!(event.target instanceof ModelElement) || !this.component) {
+            return;
+        }
+        if (event.target === this.parentElement) {
+            const implicit = this._autoAssigned ||
+                [...this._assignedClips.values()].some(clip => !clip.asset);
+            if (implicit) {
+                this._refreshClips();
+                return;
+            }
+        }
+        this.component.rebind();
+    };
+    /** @ignore */
+    constructor() {
+        super('anim');
+    }
+    getInitialComponentData() {
+        // The engine assigns creation data in key order and `activate` gates playback, so it
+        // must precede any future key that builds layers (e.g. a state graph)
+        return {
+            activate: this._activate,
+            speed: this._speed
+        };
+    }
+    initComponent() {
+        if (!this.component) {
+            return;
+        }
+        // A host readiness cycle can re-run this. An identical re-add is deduped by the DOM;
+        // the explicit swap handles the listener target changing across connections.
+        const host = this.closestEntity;
+        if (host && host !== this._modelListenerTarget) {
+            this._modelListenerTarget?.removeEventListener('ready', this._onModelReady);
+            host.addEventListener('ready', this._onModelReady);
+            this._modelListenerTarget = host;
+        }
+        this._applyClips();
+    }
+    disconnectedCallback() {
+        this._modelListenerTarget?.removeEventListener('ready', this._onModelReady);
+        this._modelListenerTarget = null;
+        // Invalidate any auto-assign still awaiting its model, and drop the adoption
+        // bookkeeping so a reconnection starts clean
+        this._sourceGeneration++;
+        this._assignedClips.clear();
+        this._autoAssigned = false;
+        super.disconnectedCallback();
+    }
+    /**
+     * The clip children in DOM order. Read afresh each pass — the DOM is the single source of
+     * truth for the declared clip set.
+     */
+    _clipElements() {
+        return Array.from(this.querySelectorAll(':scope > pc-anim-clip'));
+    }
+    /**
+     * Assigns a clip's state. Until the clip's real track resolves, the engine's own placeholder
+     * track stands in — it keeps the layer playable, so `activate` can start playback and the
+     * declared `clip` selection can apply before any asset has loaded.
+     */
+    _assignClip(clip) {
+        this.component.assignAnimation(clip.name, clip._track ?? playcanvas.AnimTrack.EMPTY, undefined, clip.speed, clip.loop);
+    }
+    /**
+     * Validates a clip child and, when valid, assigns its state and starts its track resolution.
+     *
+     * @param clip - The clip element.
+     * @returns Whether the clip was adopted.
+     */
+    _adoptClip(clip) {
+        const name = clip.name;
+        if (!name) {
+            clip._markInvalid('pc-anim-clip must have a name - clip not assigned');
+            return false;
+        }
+        if (name.indexOf('.') !== -1) {
+            clip._markInvalid(`pc-anim-clip '${name}' - '.' in a clip name is reserved for blend tree paths - clip not assigned`);
+            return false;
+        }
+        if (this._assignedClips.has(name)) {
+            clip._markInvalid(`pc-anim-clip '${name}' - an earlier clip already uses this name - clip not assigned`);
+            return false;
+        }
+        this._assignedClips.set(name, clip);
+        this._assignClip(clip);
+        clip._resolveTrack(this);
+        return true;
+    }
+    /**
+     * Assigns the current clip set: the declared clip children when there are any, otherwise the
+     * enclosing model's clips. Runs against a fresh component after a host cycle, so the
+     * adoption bookkeeping rebuilds from scratch.
+     */
+    _applyClips(restore) {
+        if (!this.component) {
+            return;
+        }
+        this._sourceGeneration++;
+        this._assignedClips.clear();
+        this._autoAssigned = false;
+        const clips = this._clipElements();
+        if (clips.length === 0) {
+            this._kickAutoAssign(restore);
+            return;
+        }
+        for (const clip of clips) {
+            this._adoptClip(clip);
+        }
+        this._applySelection(restore);
+    }
+    /**
+     * Assigns every clip of the enclosing model's container, named by track name, in container
+     * order. Names the engine cannot host — dotted (reserved for blend tree paths) or already
+     * taken — are skipped with a warning naming each.
+     */
+    async _kickAutoAssign(restore) {
+        const generation = this._sourceGeneration;
+        const model = this.parentElement;
+        if (!(model instanceof ModelElement)) {
+            // Not inside a model: an empty component, driven through the JS API
+            return;
+        }
+        await model.ready();
+        // The source may have changed while the model loaded - a declared clip child appearing
+        // flips the element over to declared mode, and wins
+        const component = this.component;
+        if (generation !== this._sourceGeneration || !component || this._clipElements().length > 0) {
+            return;
+        }
+        const container = AssetElement.get(model.asset)?.resource;
+        if (!container) {
+            // The load failed; the model already reported it
+            return;
+        }
+        const label = this.id ? ` '${this.id}'` : '';
+        if (container.animations.length === 0) {
+            console.warn(`pc-anim${label} - model '${model.asset}' has no animations`);
+            return;
+        }
+        const seen = new Set();
+        for (const animationAsset of container.animations) {
+            const track = animationAsset.resource;
+            if (!(track instanceof playcanvas.AnimTrack)) {
+                continue;
+            }
+            if (track.name.indexOf('.') !== -1) {
+                console.warn(`pc-anim${label} - track '${track.name}' - '.' in a clip name is reserved for blend tree paths - track skipped`);
+                continue;
+            }
+            if (seen.has(track.name)) {
+                console.warn(`pc-anim${label} - duplicate track name '${track.name}' - track skipped`);
+                continue;
+            }
+            seen.add(track.name);
+            component.assignAnimation(track.name, track);
+        }
+        this._autoAssigned = seen.size > 0;
+        this._applySelection(restore);
+    }
+    /**
+     * Applies the active-clip selection: the declared `clip` when it names an assigned state,
+     * else a captured pre-rebuild state when it survived, else the engine's default (the first
+     * assigned clip). A restore also reinstates the playhead and both playing flags exactly as
+     * captured — the reassignment that preceded it set both to the `activate` outcome, which is
+     * not necessarily the state the rebuild interrupted.
+     */
+    _applySelection(restore) {
+        const component = this.component;
+        const layer = component ? component.baseLayer : null;
+        if (!component || !layer) {
+            return;
+        }
+        if (this._clip && !layer.states.includes(this._clip)) {
+            this._warnUnknownClip(this._clip);
+        }
+        let target = null;
+        if (this._clip && layer.states.includes(this._clip)) {
+            target = this._clip;
+        }
+        else if (restore && layer.states.includes(restore.state)) {
+            target = restore.state;
+        }
+        if (target && layer.activeState !== target) {
+            layer.play(target);
+        }
+        if (restore) {
+            if (target === restore.state) {
+                layer.activeStateCurrentTime = restore.time;
+            }
+            layer.playing = restore.layerPlaying;
+            component.playing = restore.playing;
+        }
+    }
+    _warnUnknownClip(name) {
+        if (this._warnedClip === name) {
+            return;
+        }
+        this._warnedClip = name;
+        const label = this.id ? ` '${this.id}'` : '';
+        console.warn(`pc-anim${label} has no clip named '${name}' - selection unchanged`);
+    }
+    /**
+     * Rebuilds the clip set from the DOM, restoring the active clip and playhead when they
+     * survive the rebuild. The engine cannot remove a state from a loaded graph (unassigning
+     * only empties the state's tracks), so removals, renames and source changes drop the whole
+     * graph and reassign.
+     *
+     * @internal
+     */
+    _refreshClips() {
+        const component = this.component;
+        if (!component) {
+            return;
+        }
+        const layer = component.baseLayer;
+        const restore = layer ? {
+            state: layer.activeState,
+            time: layer.activeStateCurrentTime,
+            playing: component.playing,
+            layerPlaying: layer.playing
+        } : undefined;
+        component.removeStateGraph();
+        this._applyClips(restore);
+    }
+    /**
+     * Adopts a clip child announced by its connectedCallback. The initComponent sweep adopts
+     * children already present, so this is a no-op for those; it serves clips appended later,
+     * and flips an auto-assigned element over to its declared children — declared clips win.
+     *
+     * @param clip - The clip element.
+     * @internal
+     */
+    _registerClip(clip) {
+        if (!this.component) {
+            return;
+        }
+        if (this._autoAssigned) {
+            this._refreshClips();
+            return;
+        }
+        if (this._assignedClips.get(clip.name) === clip) {
+            return;
+        }
+        // A clip child appearing supersedes an auto-assign still awaiting its model
+        this._sourceGeneration++;
+        if (this._adoptClip(clip)) {
+            this._applySelection();
+        }
+    }
+    /**
+     * Releases a disconnected clip child. Rebuilds the set — a state cannot be removed from a
+     * live graph — and the removal of the last child inside a `<pc-model>` flips the element
+     * back to auto-assigning the model's clips.
+     *
+     * @param clip - The clip element.
+     * @internal
+     */
+    _unregisterClip(clip) {
+        if (!this.component) {
+            // The whole subtree is coming down (parents disconnect first) - nothing to rebuild
+            return;
+        }
+        if (this._assignedClips.get(clip.name) !== clip) {
+            // The clip never held a state (invalid or duplicate name)
+            return;
+        }
+        this._refreshClips();
+    }
+    /**
+     * Swaps a clip's resolved track in for the placeholder (or for its previous track after an
+     * asset change). A swap of the active clip restarts it: the engine preserves the playhead
+     * through a track replacement, which would land mid-way into unrelated animation.
+     *
+     * @param clip - The clip element.
+     * @returns Whether the clip still owns its state — the resolution may have been superseded
+     * by a rebuild that dropped it.
+     * @internal
+     */
+    _onClipResolved(clip) {
+        const component = this.component;
+        if (!component || this._assignedClips.get(clip.name) !== clip) {
+            return false;
+        }
+        this._assignClip(clip);
+        const layer = component.baseLayer;
+        if (layer && layer.activeState === clip.name) {
+            layer.play(clip.name);
+        }
+        return true;
+    }
+    /**
+     * Applies a clip's changed speed or loop. The engine bakes both into the playback state it
+     * creates on state entry, so a live change re-enters the state and restores the playhead.
+     *
+     * @param clip - The clip element.
+     * @internal
+     */
+    _onClipParamsChanged(clip) {
+        const component = this.component;
+        if (!component || this._assignedClips.get(clip.name) !== clip) {
+            return;
+        }
+        this._assignClip(clip);
+        const layer = component.baseLayer;
+        if (layer && layer.activeState === clip.name) {
+            const time = layer.activeStateCurrentTime;
+            layer.play(clip.name);
+            layer.activeStateCurrentTime = time;
+        }
+    }
+    /**
+     * Resumes playback, optionally switching to a named clip first (a hard cut). A name that
+     * matches no clip leaves the selection unchanged.
+     *
+     * @param name - The name of the clip to play. Resumes the current clip when omitted.
+     */
+    play(name) {
+        const component = this.component;
+        const layer = component ? component.baseLayer : null;
+        if (!component || !layer) {
+            return;
+        }
+        // layer.play sets the layer controller's playing flag; the component's is the system
+        // gate. Setting both is what makes this a resume regardless of how playback stopped.
+        if (name !== undefined) {
+            if (!layer.states.includes(name)) {
+                return;
+            }
+            layer.play(name);
+        }
+        else {
+            layer.play();
+        }
+        component.playing = true;
+    }
+    /**
+     * Pauses playback, preserving the playhead — {@link play} resumes from where it stopped.
+     */
+    pause() {
+        if (!this.component) {
+            return;
+        }
+        // Only the component flag - the single gate the system tick reads - is cleared. The
+        // layer controller's flag is left as-is so a pause is exactly reversible, whether
+        // resumed through play() (which sets both) or through the component API directly.
+        this.component.playing = false;
+    }
+    /**
+     * Cross-fades to a named clip and ensures playback is running. A name that matches no clip
+     * leaves the selection unchanged.
+     *
+     * @param name - The name of the clip to fade to.
+     * @param time - The fade duration in seconds. Defaults to the `transition-time` attribute.
+     */
+    transition(name, time) {
+        const component = this.component;
+        const layer = component ? component.baseLayer : null;
+        if (!component || !layer || !layer.states.includes(name)) {
+            return;
+        }
+        layer.transition(name, Math.max(0, time ?? this._transitionTime));
+        layer.playing = true;
+        component.playing = true;
+    }
+    /**
+     * Gets the underlying PlayCanvas anim component.
+     * @returns The anim component.
+     */
+    get component() {
+        return super.component;
+    }
+    /**
+     * Gets the names of the assigned clips.
+     * @returns The clip names, in assignment order.
+     */
+    get clips() {
+        const layer = this.component ? this.component.baseLayer : null;
+        return layer ? layer.states.filter(state => !playcanvas.ANIM_CONTROL_STATES.includes(state)) : [];
+    }
+    /**
+     * Sets whether playback starts automatically once a clip is assigned. Defaults to `true`.
+     * Applies when clips are assigned — it does not stop a clip that is already playing.
+     * @param value - Whether playback starts automatically.
+     */
+    set activate(value) {
+        this._activate = value;
+        if (this.component) {
+            this.component.activate = value;
+        }
+    }
+    /**
+     * Gets whether playback starts automatically once a clip is assigned.
+     * @returns Whether playback starts automatically.
+     */
+    get activate() {
+        return this._activate;
+    }
+    /**
+     * Sets the name of the active clip. Changing it switches playback, cross-fading over
+     * `transition-time` seconds (a hard cut at 0). An empty value leaves the current clip
+     * playing; a name that matches no clip warns and leaves the selection unchanged.
+     * @param value - The name of the active clip.
+     */
+    set clip(value) {
+        this._clip = value;
+        const component = this.component;
+        const layer = component ? component.baseLayer : null;
+        if (!component || !layer || !value) {
+            return;
+        }
+        if (!layer.states.includes(value)) {
+            this._warnUnknownClip(value);
+            return;
+        }
+        if (layer.activeState === value) {
+            return;
+        }
+        if (this._transitionTime > 0) {
+            this.transition(value);
+        }
+        else {
+            this.play(value);
+        }
+    }
+    /**
+     * Gets the name of the active clip.
+     * @returns The name of the active clip.
+     */
+    get clip() {
+        return this._clip;
+    }
+    /**
+     * Sets the playback speed multiplier applied across all clips, where 0 freezes playback.
+     * Defaults to 1.
+     * @param value - The playback speed multiplier.
+     */
+    set speed(value) {
+        this._speed = value;
+        if (this.component) {
+            this.component.speed = value;
+        }
+    }
+    /**
+     * Gets the playback speed multiplier applied across all clips.
+     * @returns The playback speed multiplier.
+     */
+    get speed() {
+        return this._speed;
+    }
+    /**
+     * Sets the cross-fade duration of clip switches made through the `clip` attribute, in
+     * seconds. Defaults to 0 (a hard cut).
+     * @param value - The cross-fade duration in seconds.
+     */
+    set transitionTime(value) {
+        this._transitionTime = value;
+    }
+    /**
+     * Gets the cross-fade duration of clip switches made through the `clip` attribute.
+     * @returns The cross-fade duration in seconds.
+     */
+    get transitionTime() {
+        return this._transitionTime;
+    }
+    static get observedAttributes() {
+        return [...super.observedAttributes, 'activate', 'clip', 'speed', 'transition-time'];
+    }
+    attributeChangedCallback(name, _oldValue, newValue) {
+        super.attributeChangedCallback(name, _oldValue, newValue);
+        switch (name) {
+            case 'activate':
+                this.activate = parseBool(newValue, true);
+                break;
+            case 'clip':
+                this.clip = newValue ?? '';
+                break;
+            case 'speed':
+                this.speed = parseNumber(newValue, 1, name);
+                break;
+            case 'transition-time':
+                this.transitionTime = parseNumber(newValue, 0, name);
+                break;
+        }
+    }
+}
+customElements.define('pc-anim', AnimComponentElement);
+
+/**
+ * The AnimClipElement interface provides properties and methods for manipulating
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-anim-clip/ | `<pc-anim-clip>`}
+ * elements. The AnimClipElement interface also inherits the properties and methods of the
+ * {@link HTMLElement} interface.
+ *
+ * A clip declares one named animation on its parent `<pc-anim>`. `name` is both the clip's name
+ * and the track looked up in the clip's source: an explicit `asset` (a `container`, an
+ * `animation` `.glb`, or an `animclip` JSON), or, without one, the container of the `<pc-model>`
+ * enclosing the parent `<pc-anim>`. A source holding a single track supplies it whatever it is
+ * named; in a multi-track source the track named `name` is chosen, falling back to the first
+ * with a warning. The element becomes ready once its resolved track is assigned.
+ *
+ * @category Components
+ */
+class AnimClipElement extends AsyncElement {
     /**
-     * The element hosting this component, held so the host's readiness cycles can be observed
-     * even after `closestEntity` would no longer resolve (during teardown).
+     * The `<pc-anim>` this clip was adopted by, captured when the parent adopts the clip and on
+     * connection.
+     *
+     * `disconnectedCallback` cannot rediscover it: by the time the element is disconnected its
+     * `parentElement` is already `null`, so a lookup would both fail to find the component and
+     * emit a misleading "must be a direct child" warning for what is an ordinary removal.
      */
-    _hostElement = null;
+    _animElement = null;
+    _asset = '';
     /**
-     * The listener re-applying this component when the host's readiness cycles. Held for
-     * removal on disconnect.
+     * 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
+     * neither act on a torn-down tree nor register its clip alongside a re-inserted element's
+     * own callback.
      */
-    _hostReadyListener = null;
+    _connectionGeneration = 0;
+    _errorHandle = null;
     /**
-     * Incremented on every connect and disconnect. connectedCallback captures the value on entry
-     * and abandons itself wherever it resumes from an await if the value has moved on — so a
-     * callback whose element was removed cannot act on a torn-down tree, and one whose element
-     * was removed and re-inserted (which runs a callback of its own) cannot add the component a
-     * second time.
+     * 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.
      */
-    _connectionGeneration = 0;
+    _loadGeneration = 0;
     /**
-     * Creates a new ComponentElement instance.
+     * 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).
+     */
+    _loadHandle = null;
+    _loop = true;
+    _name = '';
+    _speed = 1;
+    /**
+     * The source complaint already made — the asset id it was made for, or `''` for the
+     * no-asset-no-model case — so re-resolutions (host cycles, model reloads) do not repeat it.
+     */
+    _warnedSource = null;
+    /**
+     * Whether the owning `<pc-anim>` already rejected this clip's name — its sweeps re-run on
+     * host cycles and must not repeat the complaint.
+     */
+    _warnedInvalid = false;
+    /**
+     * The clip's resolved track. `null` until resolution completes, during which the owning
+     * `<pc-anim>` assigns the engine's placeholder track in its stead.
      *
-     * @param componentName - The name of the component.
-     * @ignore
+     * @internal
      */
-    constructor(componentName) {
-        super();
-        this._componentName = componentName;
+    _track = null;
+    async connectedCallback() {
+        const generation = ++this._connectionGeneration;
+        const animElement = this.animElement;
+        await animElement?.ready();
+        // The element may have been removed (perhaps re-inserted, which runs a callback of its
+        // own), or its parent torn down, while we were waiting. A <pc-app> disconnects before
+        // its children, so by the time we resume the component can already be gone - see the
+        // matching guard in disconnectedCallback below.
+        const component = animElement ? animElement.component : null;
+        if (generation !== this._connectionGeneration || !animElement || !component) {
+            return;
+        }
+        this._animElement = animElement;
+        animElement._registerClip(this);
+    }
+    disconnectedCallback() {
+        // Invalidate any connectedCallback or track resolution still suspended on an await
+        this._connectionGeneration++;
+        this._loadGeneration++;
+        this._detachLoadHandlers();
+        // Uses the cached parent rather than a fresh lookup, since parentElement is already null
+        // by now. The component itself is null if the whole <pc-app> is being torn down —
+        // parents disconnect first and have already removed the component.
+        this._animElement?._unregisterClip(this);
+        this._animElement = null;
+        this._track = null;
+        this._resetReady();
+    }
+    get animElement() {
+        const animElement = this.parentElement;
+        if (!(animElement instanceof AnimComponentElement)) {
+            const label = this._name ? ` '${this._name}'` : '';
+            console.warn(`pc-anim-clip${label} must be a direct child of a pc-anim element`);
+            return null;
+        }
+        return animElement;
+    }
+    _detachLoadHandlers() {
+        this._loadHandle?.off();
+        this._loadHandle = null;
+        this._errorHandle?.off();
+        this._errorHandle = null;
     }
     /**
-     * Returns the data the component is created with. Overridden by subclasses to supply the
-     * initial values of their cached properties.
+     * Reports a name-validation failure from the owning `<pc-anim>`, once per name value.
      *
-     * @returns The initial component data.
+     * @param message - The complaint.
+     * @internal
      */
-    getInitialComponentData() {
-        return {};
+    _markInvalid(message) {
+        if (this._warnedInvalid) {
+            return;
+        }
+        this._warnedInvalid = true;
+        console.warn(message);
     }
     /**
-     * Creates the component on the host's current entity, removing it first from a previous
-     * entity that is still alive (a retargeted `<pc-node>` moves its decorations with it). When
-     * the entity already has a component of this type — a glTF node arriving with its authored
-     * `render` component, say — warns and leaves `component` null. The element-level warning is
-     * load-bearing: the engine's own duplicate-addComponent warning is Debug-stripped from
-     * production builds, which would otherwise leave a silent null.
+     * Resolves the clip's track from its source and hands it to the owning `<pc-anim>`. Called
+     * by the parent whenever the clip is (re)adopted, and again when the source changes; a newer
+     * resolution supersedes one still in flight. The element becomes ready once the resolved
+     * track is assigned.
+     *
+     * @param animElement - The owning `<pc-anim>`.
+     * @internal
      */
-    _applyComponent() {
-        const entity = this._hostElement?.entity ?? null;
-        if (this._component && this._component.entity === entity) {
+    async _resolveTrack(animElement) {
+        this._animElement = animElement;
+        const generation = ++this._loadGeneration;
+        this._detachLoadHandlers();
+        if (this._asset) {
+            const asset = useAsset(this._asset);
+            if (!asset) {
+                this._warnSource(`pc-anim-clip '${this._name}' could not find asset '${this._asset}' - clip not assigned`);
+                return;
+            }
+            if (asset.loaded) {
+                this._extractTrack(asset, `asset '${this._asset}'`);
+                return;
+            }
+            // Whichever of load/error fires first detaches the other. The generation is
+            // re-checked even though a superseded handler is detached: the detach relies on how
+            // the engine's event emitter treats removal, while the check holds on its own.
+            this._loadHandle = asset.once('load', () => {
+                this._detachLoadHandlers();
+                if (generation !== this._loadGeneration) {
+                    return;
+                }
+                this._extractTrack(asset, `asset '${this._asset}'`);
+            });
+            this._errorHandle = asset.once('error', () => {
+                this._detachLoadHandlers();
+                if (generation !== this._loadGeneration) {
+                    return;
+                }
+                this._warnSource(`pc-anim-clip '${this._name}' - asset '${this._asset}' failed to load - clip not assigned`);
+            });
             return;
         }
-        // A retarget leaves the previous component on a still-live entity - remove it so the
-        // decoration follows the element, or vanishes with a dissolved binding. A destroyed
-        // entity took its components with it.
-        const previous = this._component;
-        if (previous?.entity && previous.entity.c[this._componentName] === previous) {
-            previous.entity.removeComponent(this._componentName);
+        const model = animElement.parentElement;
+        if (!(model instanceof ModelElement)) {
+            this._warnSource(`pc-anim-clip '${this._name}' has no asset and no enclosing pc-model - clip not assigned`);
+            return;
         }
-        this._component = null;
-        if (!entity) {
+        await model.ready();
+        if (generation !== this._loadGeneration) {
             return;
         }
-        if (entity.c[this._componentName]) {
-            const label = this.id ? ` '${this.id}'` : '';
-            console.warn(`${this.tagName.toLowerCase()}${label} - '${entity.name}' already has a '${this._componentName}' component - component not added`);
+        const asset = AssetElement.get(model.asset);
+        if (!asset?.resource) {
+            // The model's load failed; it already reported the error
             return;
         }
-        this._component = entity.addComponent(this._componentName, this.getInitialComponentData());
+        this._extractTrack(asset, `model '${model.asset}'`);
     }
-    async _addComponent() {
-        const generation = this._connectionGeneration;
-        const entityElement = this.closestEntity;
-        if (!entityElement) {
-            // A component can only exist on an entity, so an element placed outside one is inert.
-            // It still becomes ready (with a null `component`), so warn rather than fail silently
-            const label = this.id ? ` '${this.id}'` : '';
-            console.warn(`${this.tagName.toLowerCase()}${label} must be a descendant of pc-entity - component not added`);
+    /**
+     * 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.
+     */
+    _warnSource(message) {
+        if (this._warnedSource === this._asset) {
             return;
         }
-        await entityElement.ready();
-        // The element may have been removed, or removed and re-inserted, while the entity became
-        // ready — the component belongs to the connection that owns the current generation.
-        if (generation !== this._connectionGeneration) {
+        this._warnedSource = this._asset;
+        console.warn(message);
+    }
+    /**
+     * Picks the clip's track out of a loaded source asset: the track named `name`, or a lone
+     * track whatever it is named, or the first of several with a warning.
+     *
+     * @param asset - The loaded source asset.
+     * @param source - How warnings name the source.
+     */
+    _extractTrack(asset, source) {
+        const label = `pc-anim-clip '${this._name}'`;
+        // Widened: the engine registers an 'animclip' handler but omits the type from the
+        // Asset.type union
+        const type = asset.type;
+        let candidates;
+        switch (type) {
+            case 'container':
+                candidates = asset.resource.animations.map((animationAsset) => animationAsset.resource);
+                break;
+            case 'animation':
+                candidates = asset.resources;
+                break;
+            case 'animclip':
+                candidates = [asset.resource];
+                break;
+            default:
+                this._warnSource(`${label} - ${source} has type '${asset.type}', expected 'container', 'animation' or 'animclip' - clip not assigned`);
+                return;
+        }
+        // A JSON 'animation' asset parses to the engine's legacy Animation class, which the anim
+        // system rejects - only real AnimTracks qualify
+        const tracks = candidates.filter((candidate) => candidate instanceof playcanvas.AnimTrack);
+        if (tracks.length === 0) {
+            this._warnSource(`${label} - ${source} contains no usable animation track - clip not assigned`);
             return;
         }
-        this._hostElement = entityElement;
-        this._applyComponent();
-        // Re-apply when the host's readiness cycles without this element disconnecting: a
-        // `<pc-node>` rebinding after its model reloads or retargets, or a re-created entity.
-        // The 'ready' event bubbles, so events from descendants pass through this host - only
-        // the host's own cycles count. Readiness is cycled here too, so decorations one level
-        // down re-apply the same way.
-        this._hostReadyListener = (event) => {
-            if (event.target !== this._hostElement) {
-                return;
-            }
-            if (generation !== this._connectionGeneration) {
-                return;
+        let track = tracks.find((candidate) => candidate.name === this._name);
+        if (!track) {
+            track = tracks[0];
+            if (tracks.length > 1) {
+                console.warn(`${label} - no track named '${this._name}' in ${source} - using '${track.name}' (available: ${tracks.map((candidate) => candidate.name).join(', ')})`);
             }
-            this._hostCycled();
-        };
-        entityElement.addEventListener('ready', this._hostReadyListener);
+        }
+        this._track = track;
+        if (this._animElement?._onClipResolved(this)) {
+            this._onReady();
+        }
     }
     /**
-     * Re-evaluates this component against the host's current entity: applied to a new entity,
-     * moved from a still-live old one, or removed when the host no longer fronts an entity at
-     * all. Readiness follows - it cycles with a re-application and stays unresolved while the
-     * host is unbound. Called by the host-ready listener, and directly by a `<pc-node>`
-     * dissolving its binding: the one transition that fires no ready event to ride.
-     *
-     * @internal
+     * Sets the id of the `pc-asset` supplying the clip's track: a `container`, an `animation`
+     * `.glb`, or an `animclip` JSON. When empty, the track comes from the container of the
+     * `<pc-model>` enclosing the parent `<pc-anim>`.
+     * @param value - The asset id.
      */
-    _hostCycled() {
-        this._resetReady();
-        this._applyComponent();
-        if (this._hostElement?.entity) {
-            this.initComponent();
-            this._onReady();
+    set asset(value) {
+        this._asset = value;
+        this._warnedSource = null;
+        if (this._animElement) {
+            this._resetReady();
+            this._track = null;
+            this._resolveTrack(this._animElement);
         }
     }
     /**
-     * Configures the newly added component. Overridden by subclasses whose setup goes beyond
-     * the initial data — child-element handling, asset resolution and the like.
+     * Gets the id of the `pc-asset` supplying the clip's track.
+     * @returns The asset id.
+     */
+    get asset() {
+        return this._asset;
+    }
+    /**
+     * Sets whether the clip loops. A non-looping clip holds its last pose when it ends — the
+     * engine reports no completion. Defaults to `true`.
+     * @param value - Whether the clip loops.
      */
-    initComponent() {
-        // optional hook
+    set loop(value) {
+        this._loop = value;
+        this._animElement?._onClipParamsChanged(this);
     }
-    async connectedCallback() {
-        const generation = ++this._connectionGeneration;
-        this._appElement = this.closestApp ?? null;
-        await this._appElement?.ready();
-        // The element may have been removed, or removed and re-inserted, while the application
-        // became ready. A re-insertion runs a connectedCallback of its own, so a stale resume
-        // must not add the component alongside it.
-        if (generation !== this._connectionGeneration) {
-            return;
-        }
-        await this._addComponent();
-        if (generation !== this._connectionGeneration) {
-            return;
-        }
-        this.initComponent();
-        this._onReady();
+    /**
+     * Gets whether the clip loops.
+     * @returns Whether the clip loops.
+     */
+    get loop() {
+        return this._loop;
     }
-    disconnectedCallback() {
-        // Invalidate any connectedCallback still suspended on an await
-        this._connectionGeneration++;
-        if (this._hostElement && this._hostReadyListener) {
-            this._hostElement.removeEventListener('ready', this._hostReadyListener);
-        }
-        this._hostElement = null;
-        this._hostReadyListener = null;
-        // Remove the component when the element is disconnected. Skip this when the owning
-        // application has already been destroyed — removing a <pc-app> disconnects it before
-        // its children, taking the component systems with it.
-        if (this._appElement?.app && this._component?.entity) {
-            this._component.entity.removeComponent(this._componentName);
+    /**
+     * Sets the name of the clip: the name it is played by, and the track looked up in the
+     * clip's source. Names must be unique within a `<pc-anim>` and must not contain `.`.
+     * @param value - The clip name.
+     */
+    set name(value) {
+        this._name = value;
+        this._warnedInvalid = false;
+        if (this._animElement) {
+            this._resetReady();
+            this._animElement._refreshClips();
         }
-        this._component = null;
-        this._appElement = null;
-        this._resetReady();
     }
     /**
-     * The PlayCanvas component instance. `null` until the element is ready, and also for an
-     * element that is not a descendant of a `<pc-entity>` — await {@link whenReady} or the
-     * element's `ready()` promise before accessing it.
-     * @returns The component instance, or `null`.
+     * Gets the name of the clip.
+     * @returns The clip name.
      */
-    get component() {
-        return this._component;
+    get name() {
+        return this._name;
     }
     /**
-     * Sets the enabled state of the component.
-     * @param value - The enabled state of the component.
+     * Sets the playback speed of the clip, where negative values play it backwards. Applies
+     * immediately, preserving the playhead. Defaults to 1.
+     * @param value - The playback speed.
      */
-    set enabled(value) {
-        this._enabled = value;
-        if (this.component) {
-            this.component.enabled = value;
-        }
+    set speed(value) {
+        this._speed = value;
+        this._animElement?._onClipParamsChanged(this);
     }
     /**
-     * Gets the enabled state of the component.
-     * @returns The enabled state of the component.
+     * Gets the playback speed of the clip.
+     * @returns The playback speed.
      */
-    get enabled() {
-        return this._enabled;
+    get speed() {
+        return this._speed;
     }
     static get observedAttributes() {
-        return ['enabled'];
+        return ['asset', 'loop', 'name', 'speed'];
     }
     attributeChangedCallback(name, _oldValue, newValue) {
         switch (name) {
-            case 'enabled':
-                this.enabled = parseBool(newValue, true);
+            case 'asset':
+                this.asset = newValue ?? '';
+                break;
+            case 'loop':
+                this.loop = parseBool(newValue, true);
+                break;
+            case 'name':
+                this.name = newValue ?? '';
+                break;
+            case 'speed':
+                this.speed = parseNumber(newValue, 1, name);
                 break;
         }
     }
 }
+customElements.define('pc-anim-clip', AnimClipElement);
 
 /**
  * The ListenerComponentElement interface provides properties and methods for manipulating
@@ -11247,574 +12424,284 @@ class SoundSlotElement extends AsyncElement {
      * Gets the overlap flag of the sound slot.
      * @returns The overlap flag.
      */
-    get overlap() {
-        return this._overlap;
-    }
-    /**
-     * Sets the pitch of the sound slot.
-     * @param value - The pitch.
-     */
-    set pitch(value) {
-        this._pitch = value;
-        if (this.soundSlot) {
-            this.soundSlot.pitch = value;
-        }
-    }
-    /**
-     * Gets the pitch of the sound slot.
-     * @returns The pitch.
-     */
-    get pitch() {
-        return this._pitch;
-    }
-    /**
-     * Sets the start time of the sound slot.
-     * @param value - The start time.
-     */
-    set startTime(value) {
-        this._startTime = value;
-        if (this.soundSlot) {
-            this.soundSlot.startTime = value;
-        }
-    }
-    /**
-     * Gets the start time of the sound slot.
-     * @returns The start time.
-     */
-    get startTime() {
-        return this._startTime;
-    }
-    /**
-     * Sets the volume of the sound slot.
-     * @param value - The volume.
-     */
-    set volume(value) {
-        this._volume = value;
-        if (this.soundSlot) {
-            this.soundSlot.volume = value;
-        }
-    }
-    /**
-     * Gets the volume of the sound slot.
-     * @returns The volume.
-     */
-    get volume() {
-        return this._volume;
-    }
-    static get observedAttributes() {
-        return ['asset', 'auto-play', 'duration', 'loop', 'name', 'overlap', 'pitch', 'start-time', 'volume'];
-    }
-    attributeChangedCallback(name, _oldValue, newValue) {
-        switch (name) {
-            case 'asset':
-                this.asset = newValue ?? '';
-                break;
-            case 'auto-play':
-                this.autoPlay = parseBool(newValue, false);
-                break;
-            case 'duration':
-                this.duration = parseNumber(newValue, null, name);
-                break;
-            case 'loop':
-                this.loop = parseBool(newValue, false);
-                break;
-            case 'name':
-                this.name = newValue ?? '';
-                break;
-            case 'overlap':
-                this.overlap = parseBool(newValue, false);
-                break;
-            case 'pitch':
-                this.pitch = parseNumber(newValue, 1, name);
-                break;
-            case 'start-time':
-                this.startTime = parseNumber(newValue, 0, name);
-                break;
-            case 'volume':
-                this.volume = parseNumber(newValue, 1, name);
-                break;
-        }
-    }
-}
-customElements.define('pc-sound', SoundSlotElement);
-
-/**
- * The GSplatComponentElement interface provides properties and methods for manipulating
- * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-gsplat/ | `<pc-gsplat>`} elements.
- * The GSplatComponentElement interface also inherits the properties and methods of the
- * {@link HTMLElement} interface.
- *
- * @category Components
- */
-class GSplatComponentElement extends ComponentElement {
-    _asset = '';
-    _castShadows = false;
-    _lodBaseDistance = 5;
-    _lodMultiplier = 3;
-    _lodRangeMin = 0;
-    _lodRangeMax = 99;
-    /** @ignore */
-    constructor() {
-        super('gsplat');
-    }
-    getInitialComponentData() {
-        return {
-            asset: useAsset(this._asset),
-            castShadows: this._castShadows,
-            lodBaseDistance: this._lodBaseDistance,
-            lodMultiplier: this._lodMultiplier,
-            lodRangeMin: this._lodRangeMin,
-            lodRangeMax: this._lodRangeMax
-        };
-    }
-    /**
-     * Gets the underlying PlayCanvas gsplat component.
-     * @returns The gsplat component.
-     */
-    get component() {
-        return super.component;
-    }
-    /**
-     * Sets id of the `pc-asset` to use for the splat.
-     * @param value - The asset ID.
-     */
-    set asset(value) {
-        this._asset = value;
-        const asset = useAsset(value);
-        if (this.component && asset) {
-            this.component.asset = asset;
-        }
-    }
-    /**
-     * Gets the id of the `pc-asset` to use for the splat.
-     * @returns The asset ID.
-     */
-    get asset() {
-        return this._asset;
-    }
-    /**
-     * Sets whether the splat casts shadows.
-     * @param value - Whether the splat casts shadows.
-     */
-    set castShadows(value) {
-        this._castShadows = value;
-        if (this.component) {
-            this.component.castShadows = value;
-        }
-    }
-    /**
-     * Gets whether the splat casts shadows.
-     * @returns Whether the splat casts shadows.
-     */
-    get castShadows() {
-        return this._castShadows;
-    }
-    /**
-     * Sets the base distance for the first LOD transition (LOD 0 to LOD 1). Splats closer than
-     * this distance use the highest quality LOD. Each subsequent LOD level transitions at a
-     * progressively larger distance, controlled by {@link lodMultiplier}. Clamped to a minimum of
-     * 0.1. Defaults to 5. Only affects assets that contain LOD levels (e.g. `.lod-meta.json`).
-     * @param value - The LOD base distance.
-     */
-    set lodBaseDistance(value) {
-        this._lodBaseDistance = value;
-        if (this.component) {
-            this.component.lodBaseDistance = value;
-        }
-    }
-    /**
-     * Gets the base distance for the first LOD transition.
-     * @returns The LOD base distance.
-     */
-    get lodBaseDistance() {
-        return this._lodBaseDistance;
+    get overlap() {
+        return this._overlap;
     }
     /**
-     * Sets the multiplier between successive LOD distance thresholds. Each LOD level transitions
-     * at this factor times the previous level's distance, creating a geometric progression. Lower
-     * values keep higher quality at distance; higher values switch to coarser LODs sooner. Clamped
-     * to a minimum of 1.2. Defaults to 3. Only affects assets that contain LOD levels (e.g.
-     * `.lod-meta.json`).
-     * @param value - The LOD multiplier.
+     * Sets the pitch of the sound slot.
+     * @param value - The pitch.
      */
-    set lodMultiplier(value) {
-        this._lodMultiplier = value;
-        if (this.component) {
-            this.component.lodMultiplier = value;
+    set pitch(value) {
+        this._pitch = value;
+        if (this.soundSlot) {
+            this.soundSlot.pitch = value;
         }
     }
     /**
-     * Gets the multiplier between successive LOD distance thresholds.
-     * @returns The LOD multiplier.
+     * Gets the pitch of the sound slot.
+     * @returns The pitch.
      */
-    get lodMultiplier() {
-        return this._lodMultiplier;
+    get pitch() {
+        return this._pitch;
     }
     /**
-     * Sets the minimum allowed LOD index (inclusive). The LOD selected by distance is clamped so it
-     * never goes finer (lower index) than this value. Raising it avoids downloading the highest
-     * quality (largest) LOD files. Defaults to 0. Only affects assets that contain LOD levels (e.g.
-     * `.lod-meta.json`).
-     * @param value - The minimum LOD index.
+     * Sets the start time of the sound slot.
+     * @param value - The start time.
      */
-    set lodRangeMin(value) {
-        this._lodRangeMin = value;
-        if (this.component) {
-            this.component.lodRangeMin = value;
+    set startTime(value) {
+        this._startTime = value;
+        if (this.soundSlot) {
+            this.soundSlot.startTime = value;
         }
     }
     /**
-     * Gets the minimum allowed LOD index.
-     * @returns The minimum LOD index.
+     * Gets the start time of the sound slot.
+     * @returns The start time.
      */
-    get lodRangeMin() {
-        return this._lodRangeMin;
+    get startTime() {
+        return this._startTime;
     }
     /**
-     * Sets the maximum allowed LOD index (inclusive). The LOD selected by distance is clamped so it
-     * never goes coarser (higher index) than this value. The default of 99 effectively means "no
-     * cap". Defaults to 99. Only affects assets that contain LOD levels (e.g. `.lod-meta.json`).
-     * @param value - The maximum LOD index.
+     * Sets the volume of the sound slot.
+     * @param value - The volume.
      */
-    set lodRangeMax(value) {
-        this._lodRangeMax = value;
-        if (this.component) {
-            this.component.lodRangeMax = value;
+    set volume(value) {
+        this._volume = value;
+        if (this.soundSlot) {
+            this.soundSlot.volume = value;
         }
     }
     /**
-     * Gets the maximum allowed LOD index.
-     * @returns The maximum LOD index.
+     * Gets the volume of the sound slot.
+     * @returns The volume.
      */
-    get lodRangeMax() {
-        return this._lodRangeMax;
+    get volume() {
+        return this._volume;
     }
     static get observedAttributes() {
-        return [
-            ...super.observedAttributes,
-            'asset',
-            'cast-shadows',
-            'lod-base-distance',
-            'lod-multiplier',
-            'lod-range-min',
-            'lod-range-max'
-        ];
+        return ['asset', 'auto-play', 'duration', 'loop', 'name', 'overlap', 'pitch', 'start-time', 'volume'];
     }
     attributeChangedCallback(name, _oldValue, newValue) {
-        super.attributeChangedCallback(name, _oldValue, newValue);
         switch (name) {
             case 'asset':
                 this.asset = newValue ?? '';
                 break;
-            case 'cast-shadows':
-                this.castShadows = parseBool(newValue, false);
+            case 'auto-play':
+                this.autoPlay = parseBool(newValue, false);
                 break;
-            case 'lod-base-distance':
-                this.lodBaseDistance = parseNumber(newValue, 5, name);
+            case 'duration':
+                this.duration = parseNumber(newValue, null, name);
                 break;
-            case 'lod-multiplier':
-                this.lodMultiplier = parseNumber(newValue, 3, name);
+            case 'loop':
+                this.loop = parseBool(newValue, false);
                 break;
-            case 'lod-range-min':
-                this.lodRangeMin = parseNumber(newValue, 0, name);
+            case 'name':
+                this.name = newValue ?? '';
                 break;
-            case 'lod-range-max':
-                this.lodRangeMax = parseNumber(newValue, 99, name);
+            case 'overlap':
+                this.overlap = parseBool(newValue, false);
+                break;
+            case 'pitch':
+                this.pitch = parseNumber(newValue, 1, name);
+                break;
+            case 'start-time':
+                this.startTime = parseNumber(newValue, 0, name);
+                break;
+            case 'volume':
+                this.volume = parseNumber(newValue, 1, name);
                 break;
         }
     }
 }
-customElements.define('pc-gsplat', GSplatComponentElement);
+customElements.define('pc-sound', SoundSlotElement);
 
 /**
- * Formats one line of the printable hierarchy: the node's name, an `[index]` marker when the
- * name is shared by several nodes in the model, the attached component types, and the material
- * names of a render component.
- *
- * @param node - The node to format.
- * @param counts - The number of nodes bearing each name.
- * @returns The formatted line.
- */
-const formatNode = (node, counts) => {
-    const index = (counts.get(node.name) ?? 0) > 1 ? ` [${node.index}]` : '';
-    const components = node.components.length > 0 ? ` (${node.components.join(', ')})` : '';
-    // Braces rather than brackets: `[N]` already means a match index on this line
-    const materials = node.materials.length > 0 ? ` {${node.materials.map((slot) => slot.name ?? 'null').join(', ')}}` : '';
-    return `${node.name}${index}${components}${materials}`;
-};
-/**
- * Formats the printable form of a hierarchy subtree.
- *
- * @param root - The subtree root.
- * @param counts - The number of nodes bearing each name.
- * @returns The tree, one line per node.
- */
-const formatHierarchy = (root, counts) => {
-    const lines = [formatNode(root, counts)];
-    const walk = (node, prefix) => {
-        node.children.forEach((child, i) => {
-            const last = i === node.children.length - 1;
-            lines.push(`${prefix}${last ? '└─ ' : '├─ '}${formatNode(child, counts)}`);
-            walk(child, `${prefix}${last ? '   ' : '│  '}`);
-        });
-    };
-    walk(root, '');
-    return lines.join('\n');
-};
-/**
- * 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
+ * The GSplatComponentElement interface provides properties and methods for manipulating
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-gsplat/ | `<pc-gsplat>`} elements.
+ * The GSplatComponentElement 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.
+ * @category Components
  */
-class ModelElement extends AsyncElement {
+class GSplatComponentElement extends ComponentElement {
     _asset = '';
-    _entity = null;
-    /**
-     * 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.
-     */
-    _loadGeneration = 0;
-    /**
-     * 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).
-     */
-    _loadHandle = null;
-    _errorHandle = null;
-    /**
-     * 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() {
-        return this._entity;
+    _castShadows = false;
+    _lodBaseDistance = 5;
+    _lodMultiplier = 3;
+    _lodRangeMin = 0;
+    _lodRangeMax = 99;
+    /** @ignore */
+    constructor() {
+        super('gsplat');
     }
-    /**
-     * Returns a snapshot of the instantiated node tree, or `null` while there is none (the
-     * container asset has not loaded, or the element has left the document). One call grounds a
-     * session — a browser console, a test, an agent — in the vocabulary `pc-node` binding
-     * resolves against: the instantiated names ({@link HierarchyNode.name}), paths, match
-     * indices, attached component types and the material assignments of render components
-     * ({@link HierarchyNode.materials}). `String(...)` of the result, or of any node in it,
-     * is the printable form.
-     *
-     * The snapshot is plain data, computed afresh each call: it does not follow later changes
-     * to the hierarchy, and mutating it changes nothing.
-     *
-     * @returns The root of the instantiated node tree, or `null`.
-     */
-    hierarchy() {
-        const root = this._entity;
-        if (!root) {
-            return null;
-        }
-        // Ordinals are assigned in the traversal resolution searches — pre-order depth-first
-        // from the model root, the root itself included — so each node's index is exactly what
-        // a pc-node's index attribute selects. Once the walk completes, the map holds the total
-        // count per name, which is what the printable form reads to annotate only shared names.
-        const ordinals = new Map();
-        const describe = (entity, pathBelowRoot) => {
-            const index = ordinals.get(entity.name) ?? 0;
-            ordinals.set(entity.name, index + 1);
-            const node = {
-                name: entity.name,
-                // The root has no path below itself; its own name stands in, as it does for
-                // the path a pc-node bound to the root reports.
-                path: pathBelowRoot || entity.name,
-                index,
-                // A plain GraphNode grafted into the hierarchy has no component storage
-                components: Object.keys(entity.c ?? {}).sort(),
-                materials: (entity.render?.meshInstances ?? []).map((meshInstance, slot) => ({
-                    index: slot,
-                    name: meshInstance.material?.name ?? null
-                })),
-                children: entity.children.map((child) => describe(child, pathBelowRoot ? `${pathBelowRoot}/${child.name}` : child.name))
-            };
-            // Non-enumerable, keeping the snapshot plain data under JSON.stringify, spreads and
-            // key enumeration. Deferred to call time, by which the ordinal map holds its totals.
-            Object.defineProperty(node, 'toString', {
-                enumerable: false,
-                value: () => formatHierarchy(node, ordinals)
-            });
-            return node;
+    getInitialComponentData() {
+        return {
+            asset: useAsset(this._asset),
+            castShadows: this._castShadows,
+            lodBaseDistance: this._lodBaseDistance,
+            lodMultiplier: this._lodMultiplier,
+            lodRangeMin: this._lodRangeMin,
+            lodRangeMax: this._lodRangeMax
         };
-        return describe(root, '');
     }
-    connectedCallback() {
-        // A model outside an application is inert and never becomes ready, so awaiting it hangs.
-        // Warn rather than fail silently, naming the parent it requires, as every other misplaced
-        // element does.
-        if (!this.closestApp) {
-            const label = this._asset ? ` '${this._asset}'` : '';
-            console.warn(`pc-model${label} must be a descendant of pc-app - model not created`);
-            return;
+    /**
+     * Gets the underlying PlayCanvas gsplat component.
+     * @returns The gsplat component.
+     */
+    get component() {
+        return super.component;
+    }
+    /**
+     * Sets id of the `pc-asset` to use for the splat.
+     * @param value - The asset ID.
+     */
+    set asset(value) {
+        this._asset = value;
+        const asset = useAsset(value);
+        if (this.component && asset) {
+            this.component.asset = asset;
         }
-        this._loadModel();
     }
-    disconnectedCallback() {
-        this._loadGeneration++;
-        this._detachLoadHandlers();
-        this._unloadModel();
-        this._resetReady();
+    /**
+     * Gets the id of the `pc-asset` to use for the splat.
+     * @returns The asset ID.
+     */
+    get asset() {
+        return this._asset;
     }
-    _detachLoadHandlers() {
-        this._loadHandle?.off();
-        this._loadHandle = null;
-        this._errorHandle?.off();
-        this._errorHandle = null;
+    /**
+     * Sets whether the splat casts shadows.
+     * @param value - Whether the splat casts shadows.
+     */
+    set castShadows(value) {
+        this._castShadows = value;
+        if (this.component) {
+            this.component.castShadows = value;
+        }
     }
     /**
-     * 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.
+     * Gets whether the splat casts shadows.
+     * @returns Whether the splat casts shadows.
      */
-    _announceLoad() {
-        this._onReady();
-        this.dispatchEvent(new Event('load'));
+    get castShadows() {
+        return this._castShadows;
     }
-    _instantiate(container) {
-        const generation = this._loadGeneration;
-        const entity = container.instantiateRenderEntity();
-        this._entity = entity;
-        // @ts-ignore
-        if (container.animations.length > 0) {
-            entity.addComponent('anim');
-            // @ts-ignore
-            entity.anim.assignAnimation('animation', container.animations[0].resource);
-        }
-        // The parent's readiness re-arms when it is torn down, so these can resume in a later
-        // connection cycle. The entity is captured above and the generation re-checked, so a
-        // stale resume cannot parent an entity a newer cycle has already destroyed.
-        const parentEntityElement = this.closestEntity;
-        if (parentEntityElement) {
-            parentEntityElement.ready().then(() => {
-                if (generation !== this._loadGeneration) {
-                    return;
-                }
-                parentEntityElement.entity.addChild(entity);
-                this._announceLoad();
-            });
-        }
-        else {
-            const appElement = this.closestApp;
-            if (appElement) {
-                appElement.ready().then(() => {
-                    if (generation !== this._loadGeneration) {
-                        return;
-                    }
-                    appElement.app.root.addChild(entity);
-                    this._announceLoad();
-                });
-            }
+    /**
+     * Sets the base distance for the first LOD transition (LOD 0 to LOD 1). Splats closer than
+     * this distance use the highest quality LOD. Each subsequent LOD level transitions at a
+     * progressively larger distance, controlled by {@link lodMultiplier}. Clamped to a minimum of
+     * 0.1. Defaults to 5. Only affects assets that contain LOD levels (e.g. `.lod-meta.json`).
+     * @param value - The LOD base distance.
+     */
+    set lodBaseDistance(value) {
+        this._lodBaseDistance = value;
+        if (this.component) {
+            this.component.lodBaseDistance = value;
         }
     }
-    async _loadModel() {
-        this._unloadModel();
-        // Supersede any load already in flight - only the newest load may instantiate
-        const generation = ++this._loadGeneration;
-        this._detachLoadHandlers();
-        // Re-arm readiness so a waiter obtained after an asset change resolves against the new
-        // hierarchy. A no-op on first connection, where readiness is still pending.
-        this._resetReady();
-        const appElement = this.closestApp;
-        if (!appElement) {
-            // Outside pc-app; connectedCallback already warned. Reached through the asset setter.
-            return;
-        }
-        await appElement.ready();
-        // The element may have been removed, or another load started, while we waited
-        if (generation !== this._loadGeneration) {
-            return;
-        }
-        const asset = useAsset(this._asset);
-        if (!asset) {
-            // An empty id is a legitimate transient (the asset may be assigned later); a
-            // non-empty one that resolves to nothing is a dead end - say so rather than staying
-            // silently pending.
-            if (this._asset) {
-                console.warn(`pc-model could not find asset '${this._asset}' - model not created`);
-            }
-            return;
-        }
-        if (asset.loaded) {
-            this._instantiate(asset.resource);
+    /**
+     * Gets the base distance for the first LOD transition.
+     * @returns The LOD base distance.
+     */
+    get lodBaseDistance() {
+        return this._lodBaseDistance;
+    }
+    /**
+     * Sets the multiplier between successive LOD distance thresholds. Each LOD level transitions
+     * at this factor times the previous level's distance, creating a geometric progression. Lower
+     * values keep higher quality at distance; higher values switch to coarser LODs sooner. Clamped
+     * to a minimum of 1.2. Defaults to 3. Only affects assets that contain LOD levels (e.g.
+     * `.lod-meta.json`).
+     * @param value - The LOD multiplier.
+     */
+    set lodMultiplier(value) {
+        this._lodMultiplier = value;
+        if (this.component) {
+            this.component.lodMultiplier = value;
         }
-        else {
-            // The generation is re-checked even though a superseded handler is detached: the
-            // detach relies on how the engine's event emitter treats removal, while the check
-            // holds on its own. Whichever of load/error fires first detaches the other.
-            this._loadHandle = asset.once('load', () => {
-                this._detachLoadHandlers();
-                if (generation !== this._loadGeneration) {
-                    return;
-                }
-                this._instantiate(asset.resource);
-            });
-            this._errorHandle = asset.once('error', (err) => {
-                this._detachLoadHandlers();
-                if (generation !== this._loadGeneration) {
-                    return;
-                }
-                // A failed load settles readiness with a null entity, mirroring pc-asset:
-                // readiness means the load settled, not that it succeeded.
-                this.dispatchEvent(new ErrorEvent('error', {
-                    message: err instanceof Error ? err.message : String(err)
-                }));
-                this._onReady();
-            });
+    }
+    /**
+     * Gets the multiplier between successive LOD distance thresholds.
+     * @returns The LOD multiplier.
+     */
+    get lodMultiplier() {
+        return this._lodMultiplier;
+    }
+    /**
+     * Sets the minimum allowed LOD index (inclusive). The LOD selected by distance is clamped so it
+     * never goes finer (lower index) than this value. Raising it avoids downloading the highest
+     * quality (largest) LOD files. Defaults to 0. Only affects assets that contain LOD levels (e.g.
+     * `.lod-meta.json`).
+     * @param value - The minimum LOD index.
+     */
+    set lodRangeMin(value) {
+        this._lodRangeMin = value;
+        if (this.component) {
+            this.component.lodRangeMin = value;
         }
     }
-    _unloadModel() {
-        this._entity?.destroy();
-        this._entity = null;
+    /**
+     * Gets the minimum allowed LOD index.
+     * @returns The minimum LOD index.
+     */
+    get lodRangeMin() {
+        return this._lodRangeMin;
     }
     /**
-     * Sets the id of the `pc-asset` to use for the model.
-     * @param value - The asset ID.
+     * Sets the maximum allowed LOD index (inclusive). The LOD selected by distance is clamped so it
+     * never goes coarser (higher index) than this value. The default of 99 effectively means "no
+     * cap". Defaults to 99. Only affects assets that contain LOD levels (e.g. `.lod-meta.json`).
+     * @param value - The maximum LOD index.
      */
-    set asset(value) {
-        this._asset = value;
-        if (this.isConnected) {
-            this._loadModel();
+    set lodRangeMax(value) {
+        this._lodRangeMax = value;
+        if (this.component) {
+            this.component.lodRangeMax = value;
         }
     }
     /**
-     * Gets the id of the `pc-asset` to use for the model.
-     * @returns The asset ID.
+     * Gets the maximum allowed LOD index.
+     * @returns The maximum LOD index.
      */
-    get asset() {
-        return this._asset;
+    get lodRangeMax() {
+        return this._lodRangeMax;
     }
     static get observedAttributes() {
-        return ['asset'];
+        return [
+            ...super.observedAttributes,
+            'asset',
+            'cast-shadows',
+            'lod-base-distance',
+            'lod-multiplier',
+            'lod-range-min',
+            'lod-range-max'
+        ];
     }
     attributeChangedCallback(name, _oldValue, newValue) {
+        super.attributeChangedCallback(name, _oldValue, newValue);
         switch (name) {
             case 'asset':
                 this.asset = newValue ?? '';
                 break;
+            case 'cast-shadows':
+                this.castShadows = parseBool(newValue, false);
+                break;
+            case 'lod-base-distance':
+                this.lodBaseDistance = parseNumber(newValue, 5, name);
+                break;
+            case 'lod-multiplier':
+                this.lodMultiplier = parseNumber(newValue, 3, name);
+                break;
+            case 'lod-range-min':
+                this.lodRangeMin = parseNumber(newValue, 0, name);
+                break;
+            case 'lod-range-max':
+                this.lodRangeMax = parseNumber(newValue, 99, name);
+                break;
         }
     }
 }
-customElements.define('pc-model', ModelElement);
+customElements.define('pc-gsplat', GSplatComponentElement);
 
 /**
  * Parses one mapping into its valid rules, warning for each entry that is not one: an unknown
@@ -13179,6 +14066,8 @@ class SkyElement extends AsyncElement {
 }
 customElements.define('pc-sky', SkyElement);
 
+exports.AnimClipElement = AnimClipElement;
+exports.AnimComponentElement = AnimComponentElement;
 exports.AppElement = AppElement;
 exports.AssetElement = AssetElement;
 exports.AsyncElement = AsyncElement;