@playcanvas/web-components 0.15.0 → 0.16.0

package/dist/vscode.html-custom-data.json

@@ -906,6 +906,65 @@
       ],
       "references": []
     },
+    {
+      "name": "pc-anim-clip",
+      "description": "The AnimClipElement interface provides properties and methods for manipulating\n[`<pc-anim-clip>`](https://developer.playcanvas.com/user-manual/web-components/tags/pc-anim-clip/)\nelements. The AnimClipElement interface also inherits the properties and methods of the\nHTMLElement interface.\n\nA clip declares one named animation on its parent `<pc-anim>`. `name` is both the clip's name\nand the track looked up in the clip's source: an explicit `asset` (a `container`, an\n`animation` `.glb`, or an `animclip` JSON), or, without one, the container of the `<pc-model>`\nenclosing the parent `<pc-anim>`. A source holding a single track supplies it whatever it is\nnamed; in a multi-track source the track named `name` is chosen, falling back to the first\nwith a warning. The element becomes ready once its resolved track is assigned.\n\n---\n\n\n### **Events:**\n - **ready** - Fired when the element is fully initialized — once per readiness cycle, so an element that is torn down and re-initialized (for example by removing and re-inserting it) fires it again. Bubbles and is composed.\n\n### **Methods:**\n - **ready(): __** - Returns a promise that resolves with this element when it's ready. This is the low-level\nprimitive underlying whenReady, which is the recommended way to wait for elements.\n\nReadiness tracks the element's current lifecycle: once a ready element is torn down (for\nexample by removing it from the document), this returns a fresh promise that resolves when\nthe element is next ready. A promise obtained earlier stays resolved — call this again\nafter re-inserting an element rather than reusing a promise from before its removal.",
+      "attributes": [
+        {
+          "name": "asset",
+          "description": "The id of the `pc-asset` supplying the clip's track.",
+          "values": []
+        },
+        {
+          "name": "loop",
+          "description": "Whether the clip loops.",
+          "values": []
+        },
+        {
+          "name": "name",
+          "description": "The name of the clip.",
+          "values": []
+        },
+        {
+          "name": "speed",
+          "description": "The playback speed of the clip.",
+          "values": []
+        }
+      ],
+      "references": []
+    },
+    {
+      "name": "pc-anim",
+      "description": "The AnimComponentElement interface provides properties and methods for manipulating\n[`<pc-anim>`](https://developer.playcanvas.com/user-manual/web-components/tags/pc-anim/) elements.\nThe AnimComponentElement interface also inherits the properties and methods of the\nHTMLElement interface.\n\nThe element drives animation clips over the host entity's hierarchy. Clips come from\n`<pc-anim-clip>` children — or, when the element is a direct child of a `<pc-model>` and\ndeclares no clips, every animation of that model's container asset is assigned, named by track\nname, in container order. The first clip plays automatically (opt out with `activate=\"false\"`);\nswitch clips declaratively through the `clip` attribute, or imperatively through play\nand transition. Tracks bind to scene nodes by name, so any hierarchy whose node names\nmatch a clip's curves can be animated — a model's skeleton is simply the common case.\n\nThe engine reports no clip completion: a non-looping clip holds its last pose silently. Poll\nthe underlying AnimComponent (via component) for playback state beyond what\nthis element exposes.\n\n---\n\n\n### **Events:**\n - **ready** - Fired when the element is fully initialized — once per readiness cycle, so an element that is torn down and re-initialized (for example by removing and re-inserting it) fires it again. Bubbles and is composed.\n\n### **Methods:**\n - **pause()** - Pauses playback, preserving the playhead — play resumes from where it stopped.\n- **play(name: _string_)** - Resumes playback, optionally switching to a named clip first (a hard cut). A name that\nmatches no clip leaves the selection unchanged.\n- **ready(): __** - Returns a promise that resolves with this element when it's ready. This is the low-level\nprimitive underlying whenReady, which is the recommended way to wait for elements.\n\nReadiness tracks the element's current lifecycle: once a ready element is torn down (for\nexample by removing it from the document), this returns a fresh promise that resolves when\nthe element is next ready. A promise obtained earlier stays resolved — call this again\nafter re-inserting an element rather than reusing a promise from before its removal.\n- **transition(name: _string_, time: _number_)** - Cross-fades to a named clip and ensures playback is running. A name that matches no clip\nleaves the selection unchanged.",
+      "attributes": [
+        {
+          "name": "activate",
+          "description": "Whether playback starts automatically once a clip is assigned.",
+          "values": []
+        },
+        {
+          "name": "clip",
+          "description": "The name of the active clip.",
+          "values": []
+        },
+        {
+          "name": "enabled",
+          "description": "The enabled state of the component.",
+          "values": []
+        },
+        {
+          "name": "speed",
+          "description": "The playback speed multiplier applied across all clips.",
+          "values": []
+        },
+        {
+          "name": "transition-time",
+          "description": "The cross-fade duration of clip switches made through the `clip` attribute.",
+          "values": []
+        }
+      ],
+      "references": []
+    },
     {
       "name": "pc-button",
       "description": "The ButtonComponentElement interface provides properties and methods for manipulating\n[`<pc-button>`](https://developer.playcanvas.com/user-manual/web-components/tags/pc-button/) elements.\nThe ButtonComponentElement interface also inherits the properties and methods of the\nHTMLElement interface.\n\n---\n\n\n### **Events:**\n - **ready** - Fired when the element is fully initialized — once per readiness cycle, so an element that is torn down and re-initialized (for example by removing and re-inserting it) fires it again. Bubbles and is composed.\n\n### **Methods:**\n - **ready(): __** - Returns a promise that resolves with this element when it's ready. This is the low-level\nprimitive underlying whenReady, which is the recommended way to wait for elements.\n\nReadiness tracks the element's current lifecycle: once a ready element is torn down (for\nexample by removing it from the document), this returns a fresh promise that resolves when\nthe element is next ready. A promise obtained earlier stays resolved — call this again\nafter re-inserting an element rather than reusing a promise from before its removal.",

package/dist/web-types.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://raw.githubusercontent.com/JetBrains/web-types/master/schema/web-types.json",
   "name": "@playcanvas/web-components",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description-markup": "markdown",
   "contributions": {
     "html": {
@@ -1825,6 +1825,161 @@
             ]
           }
         },
+        {
+          "name": "pc-anim-clip",
+          "description": "The AnimClipElement interface provides properties and methods for manipulating\n[`<pc-anim-clip>`](https://developer.playcanvas.com/user-manual/web-components/tags/pc-anim-clip/)\nelements. The AnimClipElement interface also inherits the properties and methods of the\nHTMLElement interface.\n\nA clip declares one named animation on its parent `<pc-anim>`. `name` is both the clip's name\nand the track looked up in the clip's source: an explicit `asset` (a `container`, an\n`animation` `.glb`, or an `animclip` JSON), or, without one, the container of the `<pc-model>`\nenclosing the parent `<pc-anim>`. A source holding a single track supplies it whatever it is\nnamed; in a multi-track source the track named `name` is chosen, falling back to the first\nwith a warning. The element becomes ready once its resolved track is assigned.\n\n---\n\n\n### **Events:**\n - **ready** - Fired when the element is fully initialized — once per readiness cycle, so an element that is torn down and re-initialized (for example by removing and re-inserting it) fires it again. Bubbles and is composed.\n\n### **Methods:**\n - **ready(): __** - Returns a promise that resolves with this element when it's ready. This is the low-level\nprimitive underlying whenReady, which is the recommended way to wait for elements.\n\nReadiness tracks the element's current lifecycle: once a ready element is torn down (for\nexample by removing it from the document), this returns a fresh promise that resolves when\nthe element is next ready. A promise obtained earlier stays resolved — call this again\nafter re-inserting an element rather than reusing a promise from before its removal.",
+          "doc-url": "",
+          "attributes": [
+            {
+              "name": "asset",
+              "description": "The id of the `pc-asset` supplying the clip's track.",
+              "value": { "type": "string" }
+            },
+            {
+              "name": "loop",
+              "description": "Whether the clip loops.",
+              "value": { "type": "boolean", "default": "true" }
+            },
+            {
+              "name": "name",
+              "description": "The name of the clip.",
+              "value": { "type": "string" }
+            },
+            {
+              "name": "speed",
+              "description": "The playback speed of the clip.",
+              "value": { "type": "number", "default": "1" }
+            }
+          ],
+          "events": [
+            {
+              "name": "ready",
+              "type": "CustomEvent",
+              "description": "Fired when the element is fully initialized — once per readiness cycle, so an element that is torn down and re-initialized (for example by removing and re-inserting it) fires it again. Bubbles and is composed."
+            }
+          ],
+          "js": {
+            "properties": [
+              {
+                "name": "asset",
+                "description": "Gets the id of the `pc-asset` supplying the clip's track."
+              },
+              {
+                "name": "closestApp",
+                "description": "The nearest ancestor `<pc-app>` element, or `null` if this element has no `<pc-app>`\nancestor. The search starts at the parent, so an element never resolves to itself.",
+                "type": "AppElement | null"
+              },
+              {
+                "name": "closestEntity",
+                "description": "The nearest ancestor element that fronts an entity — `<pc-entity>` or `<pc-node>` — or\n`null` if this element has no such ancestor. The search starts at the parent, so an element\nnever resolves to itself.",
+                "type": "EntityBaseElement | null"
+              },
+              { "name": "loop", "description": "Gets whether the clip loops." },
+              { "name": "name", "description": "Gets the name of the clip." },
+              {
+                "name": "speed",
+                "description": "Gets the playback speed of the clip."
+              }
+            ],
+            "events": [
+              {
+                "name": "ready",
+                "type": "CustomEvent",
+                "description": "Fired when the element is fully initialized — once per readiness cycle, so an element that is torn down and re-initialized (for example by removing and re-inserting it) fires it again. Bubbles and is composed."
+              }
+            ]
+          }
+        },
+        {
+          "name": "pc-anim",
+          "description": "The AnimComponentElement interface provides properties and methods for manipulating\n[`<pc-anim>`](https://developer.playcanvas.com/user-manual/web-components/tags/pc-anim/) elements.\nThe AnimComponentElement interface also inherits the properties and methods of the\nHTMLElement interface.\n\nThe element drives animation clips over the host entity's hierarchy. Clips come from\n`<pc-anim-clip>` children — or, when the element is a direct child of a `<pc-model>` and\ndeclares no clips, every animation of that model's container asset is assigned, named by track\nname, in container order. The first clip plays automatically (opt out with `activate=\"false\"`);\nswitch clips declaratively through the `clip` attribute, or imperatively through play\nand transition. Tracks bind to scene nodes by name, so any hierarchy whose node names\nmatch a clip's curves can be animated — a model's skeleton is simply the common case.\n\nThe engine reports no clip completion: a non-looping clip holds its last pose silently. Poll\nthe underlying AnimComponent (via component) for playback state beyond what\nthis element exposes.\n\n---\n\n\n### **Events:**\n - **ready** - Fired when the element is fully initialized — once per readiness cycle, so an element that is torn down and re-initialized (for example by removing and re-inserting it) fires it again. Bubbles and is composed.\n\n### **Methods:**\n - **pause()** - Pauses playback, preserving the playhead — play resumes from where it stopped.\n- **play(name: _string_)** - Resumes playback, optionally switching to a named clip first (a hard cut). A name that\nmatches no clip leaves the selection unchanged.\n- **ready(): __** - Returns a promise that resolves with this element when it's ready. This is the low-level\nprimitive underlying whenReady, which is the recommended way to wait for elements.\n\nReadiness tracks the element's current lifecycle: once a ready element is torn down (for\nexample by removing it from the document), this returns a fresh promise that resolves when\nthe element is next ready. A promise obtained earlier stays resolved — call this again\nafter re-inserting an element rather than reusing a promise from before its removal.\n- **transition(name: _string_, time: _number_)** - Cross-fades to a named clip and ensures playback is running. A name that matches no clip\nleaves the selection unchanged.",
+          "doc-url": "",
+          "attributes": [
+            {
+              "name": "activate",
+              "description": "Whether playback starts automatically once a clip is assigned.",
+              "value": { "type": "boolean", "default": "true" }
+            },
+            {
+              "name": "clip",
+              "description": "The name of the active clip.",
+              "value": { "type": "string" }
+            },
+            {
+              "name": "enabled",
+              "description": "The enabled state of the component.",
+              "value": { "type": "boolean", "default": "true" }
+            },
+            {
+              "name": "speed",
+              "description": "The playback speed multiplier applied across all clips.",
+              "value": { "type": "number", "default": "1" }
+            },
+            {
+              "name": "transition-time",
+              "description": "The cross-fade duration of clip switches made through the `clip` attribute.",
+              "value": { "type": "number", "default": "0" }
+            }
+          ],
+          "events": [
+            {
+              "name": "ready",
+              "type": "CustomEvent",
+              "description": "Fired when the element is fully initialized — once per readiness cycle, so an element that is torn down and re-initialized (for example by removing and re-inserting it) fires it again. Bubbles and is composed."
+            }
+          ],
+          "js": {
+            "properties": [
+              {
+                "name": "activate",
+                "description": "Gets whether playback starts automatically once a clip is assigned."
+              },
+              {
+                "name": "clip",
+                "description": "Gets the name of the active clip."
+              },
+              {
+                "name": "clips",
+                "description": "Gets the names of the assigned clips.",
+                "type": "string[]"
+              },
+              {
+                "name": "closestApp",
+                "description": "The nearest ancestor `<pc-app>` element, or `null` if this element has no `<pc-app>`\nancestor. The search starts at the parent, so an element never resolves to itself.",
+                "type": "AppElement | null"
+              },
+              {
+                "name": "closestEntity",
+                "description": "The nearest ancestor element that fronts an entity — `<pc-entity>` or `<pc-node>` — or\n`null` if this element has no such ancestor. The search starts at the parent, so an element\nnever resolves to itself.",
+                "type": "EntityBaseElement | null"
+              },
+              {
+                "name": "component",
+                "description": "Gets the underlying PlayCanvas anim component.",
+                "type": "Component | null"
+              },
+              {
+                "name": "enabled",
+                "description": "Gets the enabled state of the component."
+              },
+              {
+                "name": "speed",
+                "description": "Gets the playback speed multiplier applied across all clips."
+              },
+              {
+                "name": "transitionTime",
+                "description": "Gets the cross-fade duration of clip switches made through the `clip` attribute."
+              }
+            ],
+            "events": [
+              {
+                "name": "ready",
+                "type": "CustomEvent",
+                "description": "Fired when the element is fully initialized — once per readiness cycle, so an element that is torn down and re-initialized (for example by removing and re-inserting it) fires it again. Bubbles and is composed."
+              }
+            ]
+          }
+        },
         {
           "name": "pc-button",
           "description": "The ButtonComponentElement interface provides properties and methods for manipulating\n[`<pc-button>`](https://developer.playcanvas.com/user-manual/web-components/tags/pc-button/) elements.\nThe ButtonComponentElement interface also inherits the properties and methods of the\nHTMLElement interface.\n\n---\n\n\n### **Events:**\n - **ready** - Fired when the element is fully initialized — once per readiness cycle, so an element that is torn down and re-initialized (for example by removing and re-inserting it) fires it again. Bubbles and is composed.\n\n### **Methods:**\n - **ready(): __** - Returns a promise that resolves with this element when it's ready. This is the low-level\nprimitive underlying whenReady, which is the recommended way to wait for elements.\n\nReadiness tracks the element's current lifecycle: once a ready element is torn down (for\nexample by removing it from the document), this returns a fresh promise that resolves when\nthe element is next ready. A promise obtained earlier stays resolved — call this again\nafter re-inserting an element rather than reusing a promise from before its removal.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcanvas/web-components",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "author": "PlayCanvas <support@playcanvas.com>",
   "homepage": "https://playcanvas.com",
   "description": "Web Components for the PlayCanvas Engine",

package/src/components/anim-clip.ts

@@ -0,0 +1,395 @@
+import type { Asset, EventHandle } from 'playcanvas';
+import { AnimTrack } from 'playcanvas';
+
+import { AssetElement, useAsset } from '../asset';
+import { AsyncElement } from '../async-element';
+import { ModelElement } from '../model';
+import { parseBool, parseNumber } from '../parse';
+
+import type { ContainerWithAnimations } from './anim-component';
+import { AnimComponentElement } from './anim-component';
+
+/**
+ * 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 `<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.
+     */
+    private _animElement: AnimComponentElement | null = null;
+
+    private _asset = '';
+
+    /**
+     * 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.
+     */
+    private _connectionGeneration = 0;
+
+    private _errorHandle: EventHandle | null = null;
+
+    /**
+     * 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.
+     */
+    private _loadGeneration = 0;
+
+    /**
+     * The pending asset subscriptions of the current resolution, if it is waiting for its asset.
+     * Held so that whatever supersedes the resolution can detach the handlers from the asset,
+     * rather than leave them registered until the asset settles (or forever, if it never does).
+     */
+    private _loadHandle: EventHandle | null = null;
+
+    private _loop = true;
+
+    private _name = '';
+
+    private _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.
+     */
+    private _warnedSource: string | null = 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.
+     */
+    private _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.
+     *
+     * @internal
+     */
+    _track: AnimTrack | null = 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();
+    }
+
+    protected get animElement(): AnimComponentElement | null {
+        const animElement = this.parentElement as AnimComponentElement;
+
+        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;
+    }
+
+    private _detachLoadHandlers() {
+        this._loadHandle?.off();
+        this._loadHandle = null;
+        this._errorHandle?.off();
+        this._errorHandle = null;
+    }
+
+    /**
+     * Reports a name-validation failure from the owning `<pc-anim>`, once per name value.
+     *
+     * @param message - The complaint.
+     * @internal
+     */
+    _markInvalid(message: string) {
+        if (this._warnedInvalid) {
+            return;
+        }
+        this._warnedInvalid = true;
+        console.warn(message);
+    }
+
+    /**
+     * 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
+     */
+    async _resolveTrack(animElement: AnimComponentElement) {
+        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;
+        }
+
+        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;
+        }
+
+        await model.ready();
+        if (generation !== this._loadGeneration) {
+            return;
+        }
+
+        const asset = AssetElement.get(model.asset);
+        if (!asset?.resource) {
+            // The model's load failed; it already reported the error
+            return;
+        }
+        this._extractTrack(asset, `model '${model.asset}'`);
+    }
+
+    /**
+     * 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.
+     */
+    private _warnSource(message: string) {
+        if (this._warnedSource === this._asset) {
+            return;
+        }
+        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.
+     */
+    private _extractTrack(asset: Asset, source: string) {
+        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: string = asset.type;
+
+        let candidates: unknown[];
+        switch (type) {
+            case 'container':
+                candidates = (asset.resource as ContainerWithAnimations).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 is AnimTrack => candidate instanceof AnimTrack);
+        if (tracks.length === 0) {
+            this._warnSource(`${label} - ${source} contains no usable animation track - clip not assigned`);
+            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._track = track;
+        if (this._animElement?._onClipResolved(this)) {
+            this._onReady();
+        }
+    }
+
+    /**
+     * 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.
+     */
+    set asset(value: string) {
+        this._asset = value;
+        this._warnedSource = null;
+        if (this._animElement) {
+            this._resetReady();
+            this._track = null;
+            this._resolveTrack(this._animElement);
+        }
+    }
+
+    /**
+     * 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.
+     */
+    set loop(value: boolean) {
+        this._loop = value;
+        this._animElement?._onClipParamsChanged(this);
+    }
+
+    /**
+     * Gets whether the clip loops.
+     * @returns Whether the clip loops.
+     */
+    get loop() {
+        return this._loop;
+    }
+
+    /**
+     * 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: string) {
+        this._name = value;
+        this._warnedInvalid = false;
+        if (this._animElement) {
+            this._resetReady();
+            this._animElement._refreshClips();
+        }
+    }
+
+    /**
+     * Gets the name of the clip.
+     * @returns The clip name.
+     */
+    get name() {
+        return this._name;
+    }
+
+    /**
+     * 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 speed(value: number) {
+        this._speed = value;
+        this._animElement?._onClipParamsChanged(this);
+    }
+
+    /**
+     * Gets the playback speed of the clip.
+     * @returns The playback speed.
+     */
+    get speed() {
+        return this._speed;
+    }
+
+    static get observedAttributes() {
+        return ['asset', 'loop', 'name', 'speed'];
+    }
+
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null) {
+        switch (name) {
+            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);
+
+export { AnimClipElement };