@playcanvas/web-components 0.15.0 → 0.17.0

package/src/components/{listener-component.ts → audio-listener-component.ts}

@@ -3,14 +3,16 @@ import type { AudioListenerComponent } from 'playcanvas';
 import { ComponentElement } from './component';
 
 /**
- * The ListenerComponentElement interface provides properties and methods for manipulating
- * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-listener/ | `<pc-listener>`} elements.
- * The ListenerComponentElement interface also inherits the properties and methods of the
+ * The AudioListenerComponentElement interface provides properties and methods for manipulating
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-audio-listener/ | `<pc-audio-listener>`} elements.
+ * The AudioListenerComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link AudioListenerComponent} (`audiolistener`).
+ *
  * @category Components
  */
-class ListenerComponentElement extends ComponentElement {
+class AudioListenerComponentElement extends ComponentElement {
     /** @ignore */
     constructor() {
         super('audiolistener');
@@ -25,6 +27,6 @@ class ListenerComponentElement extends ComponentElement {
     }
 }
 
-customElements.define('pc-listener', ListenerComponentElement);
+customElements.define('pc-audio-listener', AudioListenerComponentElement);
 
-export { ListenerComponentElement };
+export { AudioListenerComponentElement };

package/src/components/button-component.ts

@@ -17,6 +17,8 @@ const transitionModes = new Map<'tint' | 'sprite', number>([
  * The ButtonComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link ButtonComponent} (`button`).
+ *
  * @category Components
  */
 class ButtonComponentElement extends ComponentElement {
@@ -121,7 +123,9 @@ class ButtonComponentElement extends ComponentElement {
 
     /**
      * Sets the reference (CSS selector, element id or entity name) to the `<pc-entity>` whose image
-     * element is used for visual transitions. Defaults to the button's own entity.
+     * element is used for visual transitions. Defaults to the button's own entity — inside a
+     * `<pc-model>`, that is the model's host entity, so supply an explicit reference to target a
+     * UI entity instead.
      * @param value - The image entity reference.
      */
     set image(value: string) {

package/src/components/camera-component.ts

@@ -41,6 +41,8 @@ const tonemaps = new Map<'none' | 'linear' | 'filmic' | 'hejl' | 'aces' | 'aces2
  * The CameraComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link CameraComponent} (`camera`).
+ *
  * @category Components
  */
 class CameraComponentElement extends ComponentElement {

package/src/components/collision-component.ts

@@ -17,6 +17,8 @@ import { ComponentElement } from './component';
  * retargets or rebinds picks up the new node's geometry. An entity with no asset-backed render
  * component warns, and the collider has no shape.
  *
+ * Engine component: {@link CollisionComponent} (`collision`).
+ *
  * @category Components
  */
 class CollisionComponentElement extends ComponentElement {
@@ -64,7 +66,9 @@ class CollisionComponentElement extends ComponentElement {
      * no attribute to supply it - so the host's visible geometry, the meaning a mesh collider
      * on a glTF node carries, fills the gap. Runs on every application (so a rebound `pc-node`
      * recomputes it) and on a runtime switch to `type="mesh"`; an explicitly assigned
-     * `renderAsset` is never overwritten.
+     * `renderAsset` is never overwritten. A `pc-model` host entity never carries a render
+     * component (the instantiated content beneath it does), so a mesh collider that should take
+     * an asset's geometry belongs on a bound `pc-node`.
      */
     private _applyMeshGeometryDefault() {
         const component = this.component;

package/src/components/component.ts

@@ -109,7 +109,7 @@ class ComponentElement extends AsyncElement {
             // 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`
+                `${this.tagName.toLowerCase()}${label} must be a descendant of pc-entity, pc-model or pc-node - component not added`
             );
             return;
         }
@@ -214,8 +214,9 @@ class ComponentElement extends AsyncElement {
 
     /**
      * 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.
+     * element that is not a descendant of an entity-fronting element (`<pc-entity>`,
+     * `<pc-model>` or `<pc-node>`) — await {@link whenReady} or the element's `ready()` promise
+     * before accessing it.
      * @returns The component instance, or `null`.
      */
     get component(): Component | null {

package/src/components/element-component.ts

@@ -12,6 +12,13 @@ import { ComponentElement } from './component';
  * The ElementComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Despite the name, this is not a base class or a generic wrapper: it is the engine's 2D UI
+ * component, which gives its host entity a rectangle in a `<pc-screen>` hierarchy that draws
+ * either an image, a line of text or nothing (`type="image"`, `"text"` or `"group"`). The tag
+ * spells the engine component it adds, as every component element does.
+ *
+ * Engine component: {@link ElementComponent} (`element`).
+ *
  * @category Components
  */
 class ElementComponentElement extends ComponentElement {

package/src/components/gsplat-component.ts

@@ -11,6 +11,8 @@ import { ComponentElement } from './component';
  * The GSplatComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link GSplatComponent} (`gsplat`).
+ *
  * @category Components
  */
 class GSplatComponentElement extends ComponentElement {

package/src/components/joint-component.ts

@@ -26,6 +26,8 @@ type MotionMode = 'locked' | 'limited' | 'free';
  * constraint breaks. A broken joint no longer constrains its bodies; calling `refreshFrames()` on
  * the underlying component re-attaches it. Bubbles and is composed.
  *
+ * Engine component: {@link JointComponent} (`joint`).
+ *
  * @category Components
  */
 class JointComponentElement extends ComponentElement {

package/src/components/{layoutchild-component.ts → layout-child-component.ts}

@@ -6,10 +6,12 @@ import { ComponentElement } from './component';
 
 /**
  * The LayoutChildComponentElement interface provides properties and methods for manipulating
- * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-layoutchild/ | `<pc-layoutchild>`} elements.
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-layout-child/ | `<pc-layout-child>`} elements.
  * The LayoutChildComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link LayoutChildComponent} (`layoutchild`).
+ *
  * @category Components
  */
 class LayoutChildComponentElement extends ComponentElement {
@@ -229,6 +231,6 @@ class LayoutChildComponentElement extends ComponentElement {
     }
 }
 
-customElements.define('pc-layoutchild', LayoutChildComponentElement);
+customElements.define('pc-layout-child', LayoutChildComponentElement);
 
 export { LayoutChildComponentElement };

package/src/components/{layoutgroup-component.ts → layout-group-component.ts}

@@ -28,10 +28,12 @@ const fittings = new Map<'none' | 'stretch' | 'shrink' | 'both', number>([
 
 /**
  * The LayoutGroupComponentElement interface provides properties and methods for manipulating
- * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-layoutgroup/ | `<pc-layoutgroup>`} elements.
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-layout-group/ | `<pc-layout-group>`} elements.
  * The LayoutGroupComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link LayoutGroupComponent} (`layoutgroup`).
+ *
  * @category Components
  */
 class LayoutGroupComponentElement extends ComponentElement {
@@ -304,6 +306,6 @@ class LayoutGroupComponentElement extends ComponentElement {
     }
 }
 
-customElements.define('pc-layoutgroup', LayoutGroupComponentElement);
+customElements.define('pc-layout-group', LayoutGroupComponentElement);
 
 export { LayoutGroupComponentElement };

package/src/components/light-component.ts

@@ -37,6 +37,8 @@ const shadowTypes = new Map<
  * The LightComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link LightComponent} (`light`).
+ *
  * @category Components
  */
 class LightComponentElement extends ComponentElement {

package/src/components/{particlesystem-component.ts → particle-system-component.ts}

@@ -6,10 +6,12 @@ import { ComponentElement } from './component';
 
 /**
  * The ParticleSystemComponentElement interface provides properties and methods for manipulating
- * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-particles/ | `<pc-particles>`} elements.
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-particle-system/ | `<pc-particle-system>`} elements.
  * The ParticleSystemComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link ParticleSystemComponent} (`particlesystem`).
+ *
  * @category Components
  */
 class ParticleSystemComponentElement extends ComponentElement {
@@ -147,6 +149,6 @@ class ParticleSystemComponentElement extends ComponentElement {
     }
 }
 
-customElements.define('pc-particles', ParticleSystemComponentElement);
+customElements.define('pc-particle-system', ParticleSystemComponentElement);
 
 export { ParticleSystemComponentElement };

package/src/components/render-component.ts

@@ -15,6 +15,8 @@ import { ComponentElement } from './component';
  * to `box`). It does not cover the engine's `asset` render type, since there is no way to supply
  * a render asset here — use `pc-model` for glTF content instead.
  *
+ * Engine component: {@link RenderComponent} (`render`).
+ *
  * @category Components
  */
 class RenderComponentElement extends ComponentElement {

package/src/components/{rigidbody-component.ts → rigid-body-component.ts}

@@ -7,10 +7,12 @@ import { ComponentElement } from './component';
 
 /**
  * The RigidBodyComponentElement interface provides properties and methods for manipulating
- * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-rigidbody/ | `<pc-rigidbody>`} elements.
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-rigid-body/ | `<pc-rigid-body>`} elements.
  * The RigidBodyComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link RigidBodyComponent} (`rigidbody`).
+ *
  * @category Components
  */
 class RigidBodyComponentElement extends ComponentElement {
@@ -235,6 +237,6 @@ class RigidBodyComponentElement extends ComponentElement {
     }
 }
 
-customElements.define('pc-rigidbody', RigidBodyComponentElement);
+customElements.define('pc-rigid-body', RigidBodyComponentElement);
 
 export { RigidBodyComponentElement };

package/src/components/screen-component.ts

@@ -20,6 +20,8 @@ const scaleModes = new Map<'none' | 'blend', string>([
  * The ScreenComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link ScreenComponent} (`screen`).
+ *
  * @category Components
  */
 class ScreenComponentElement extends ComponentElement {

package/src/components/script-component.ts

@@ -15,14 +15,14 @@ import {
 } from '../parse';
 
 import { ComponentElement } from './component';
-import { ScriptElement } from './script';
+import { ScriptInstanceElement } from './script-instance';
 
 /**
- * Attributes on `pc-script` that never map to script attributes: the element's own API (derived
+ * Attributes on `pc-script-instance` that never map to script attributes: the element's own API (derived
  * from its observed attributes) plus reserved and global HTML attribute names.
  */
 const RESERVED_ATTRIBUTES = new Set([
-    ...ScriptElement.observedAttributes,
+    ...ScriptInstanceElement.observedAttributes,
     'accesskey',
     'autocapitalize',
     'autofocus',
@@ -54,7 +54,7 @@ const RESERVED_ATTRIBUTES = new Set([
 ]);
 
 /**
- * Checks whether a `pc-script` attribute name is reserved (and so never maps to a script
+ * Checks whether a `pc-script-instance` attribute name is reserved (and so never maps to a script
  * attribute). Reserved names are the element's own API, global HTML attribute names, `data-*`
  * and `aria-*` attributes, names starting with `_` (framework-stamped attributes), and real
  * inline event handler names (`onclick` etc. — detected via the platform, so script attributes
@@ -244,10 +244,12 @@ export type ScriptNameChangeEvent = {
 
 /**
  * The ScriptComponentElement interface provides properties and methods for manipulating
- * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-scripts/ | `<pc-scripts>`} elements.
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-script/ | `<pc-script>`} elements.
  * The ScriptComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link ScriptComponent} (`script`).
+ *
  * @category Components
  */
 class ScriptComponentElement extends ComponentElement {
@@ -268,15 +270,24 @@ class ScriptComponentElement extends ComponentElement {
 
     connectedCallback() {
         // (Re-)observe on every connection - disconnectedCallback disconnects the observer.
-        // Attribute changes on child pc-script elements are watched here too: per-property
+        // Attribute changes on child pc-script-instance elements are watched here too: per-property
         // script attributes are not statically known, so they cannot use observedAttributes.
         this.observer.observe(this, { childList: true, subtree: true, attributes: true });
         return super.connectedCallback();
     }
 
     protected initComponent() {
-        // Handle initial script elements
-        this.querySelectorAll<ScriptElement>(':scope > pc-script').forEach((scriptElement) => {
+        this.querySelectorAll<ScriptInstanceElement>(':scope > pc-script-instance').forEach((scriptElement) => {
+            // A host readiness cycle re-runs this against a component that can have survived it
+            // (a pc-model reloading content on its stable host entity). The engine rejects a
+            // duplicate create - returning null, silently in production builds - which would
+            // skip attribute application entirely. A surviving instance is re-asserted instead,
+            // so both cycle outcomes leave the component reflecting the element's declared state.
+            const script = this.scriptFor(scriptElement);
+            if (script) {
+                this.applyDeclaredState(script, scriptElement);
+                return;
+            }
             this.createScript(scriptElement);
         });
     }
@@ -424,12 +435,12 @@ class ScriptComponentElement extends ComponentElement {
     }
 
     /**
-     * Returns the camelCase keys of the per-property attributes present on a `pc-script`
+     * Returns the camelCase keys of the per-property attributes present on a `pc-script-instance`
      * element.
-     * @param scriptElement - The `pc-script` element.
+     * @param scriptElement - The `pc-script-instance` element.
      * @returns The camelCase keys.
      */
-    private inlineKeys(scriptElement: ScriptElement): Set<string> {
+    private inlineKeys(scriptElement: ScriptInstanceElement): Set<string> {
         const keys = new Set<string>();
         for (const attr of Array.from(scriptElement.attributes)) {
             if (!isReservedAttribute(attr.name)) {
@@ -440,13 +451,13 @@ class ScriptComponentElement extends ComponentElement {
     }
 
     /**
-     * Resolves the script instance owned by a `pc-script` element. Returns `null` when the
+     * Resolves the script instance owned by a `pc-script-instance` element. Returns `null` when the
      * element has no created script, or when its name resolves to a script created by a
      * different element (e.g. a duplicate-named sibling).
-     * @param scriptElement - The `pc-script` element.
+     * @param scriptElement - The `pc-script-instance` element.
      * @returns The owned script, or `null`.
      */
-    private scriptFor(scriptElement: ScriptElement): Script | null {
+    private scriptFor(scriptElement: ScriptInstanceElement): Script | null {
         const name = scriptElement.getAttribute('name');
         if (!name || !this.component) return null;
 
@@ -455,7 +466,7 @@ class ScriptComponentElement extends ComponentElement {
     }
 
     private handleScriptAttributesChange(event: ScriptAttributesChangeEvent) {
-        const scriptElement = event.target as ScriptElement;
+        const scriptElement = event.target as ScriptInstanceElement;
         const script = this.scriptFor(scriptElement);
         if (script) {
             // Per-property attributes stay authoritative: keys they pin are excluded here
@@ -464,7 +475,7 @@ class ScriptComponentElement extends ComponentElement {
     }
 
     private handleScriptEnableChange(event: ScriptEnableChangeEvent) {
-        const scriptElement = event.target as ScriptElement;
+        const scriptElement = event.target as ScriptInstanceElement;
 
         // Apply any queued per-property changes first, so that initialize() (fired by the
         // engine on first effective enable) sees every attribute value set this tick
@@ -477,7 +488,7 @@ class ScriptComponentElement extends ComponentElement {
     }
 
     /**
-     * Handles a runtime `name` change on a child `pc-script`, swapping the engine script instance
+     * Handles a runtime `name` change on a child `pc-script-instance`, swapping the engine script instance
      * to match. Without this the element would keep pointing at the old-name instance: the old
      * script would go on running while every subsequent update (attribute changes, enable
      * changes, destruction on removal) resolved the new name and silently no-opped.
@@ -487,10 +498,10 @@ class ScriptComponentElement extends ComponentElement {
      * @param event - The name change event.
      */
     private handleScriptNameChange(event: ScriptNameChangeEvent) {
-        const scriptElement = event.target as ScriptElement;
+        const scriptElement = event.target as ScriptInstanceElement;
 
-        // Only direct children are managed, matching initComponent's ':scope > pc-script'
-        // contract - the event bubbles, so a deeper pc-script must not be created here
+        // Only direct children are managed, matching initComponent's ':scope > pc-script-instance'
+        // contract - the event bubbles, so a deeper pc-script-instance must not be created here
         if (scriptElement.parentElement !== this) return;
 
         // Before the component exists there is nothing to swap: initComponent creates from
@@ -509,14 +520,14 @@ class ScriptComponentElement extends ComponentElement {
     }
 
     /**
-     * Creates the script instance for a `pc-script` element. The instance is created disabled,
+     * Creates the script instance for a `pc-script-instance` element. The instance is created disabled,
      * the element's converted attributes are merged over the instance's defaults (which is what
      * allows plain numeric arrays to be typed against those defaults), and only then is the
      * declared enabled state applied — so `initialize()` runs with every attribute in place.
-     * @param scriptElement - The `pc-script` element to create the script instance for.
+     * @param scriptElement - The `pc-script-instance` element to create the script instance for.
      * @returns The created script, or `null`.
      */
-    private createScript(scriptElement: ScriptElement): Script | null {
+    private createScript(scriptElement: ScriptInstanceElement): Script | null {
         const name = scriptElement.getAttribute('name');
         if (!name || !this.component) return null;
 
@@ -525,11 +536,7 @@ class ScriptComponentElement extends ComponentElement {
 
         scriptElement._script = script;
 
-        // The JSON blob first with per-property-shadowed keys stripped, then the per-property
-        // attributes: each property is written exactly once and individual attributes win
-        this.applyAttributes(script, scriptElement.scriptAttributes, this.inlineKeys(scriptElement));
-        this.applyInlineAttributes(script, scriptElement);
-        script.enabled = scriptElement.enabled;
+        this.applyDeclaredState(script, scriptElement);
 
         scriptElement._onScriptCreated();
 
@@ -537,14 +544,28 @@ class ScriptComponentElement extends ComponentElement {
     }
 
     /**
-     * Applies the per-property attributes present on a `pc-script` element — any attribute that
+     * Applies a `pc-script-instance` element's declared state to a script instance: the `attributes` JSON
+     * first with per-property-shadowed keys stripped, then the per-property attributes — each
+     * property is written exactly once and individual attributes win — and finally the declared
+     * enabled state, so `initialize()` runs with every attribute in place.
+     * @param script - The script instance.
+     * @param scriptElement - The `pc-script-instance` element holding the declared state.
+     */
+    private applyDeclaredState(script: Script, scriptElement: ScriptInstanceElement) {
+        this.applyAttributes(script, scriptElement.scriptAttributes, this.inlineKeys(scriptElement));
+        this.applyInlineAttributes(script, scriptElement);
+        script.enabled = scriptElement.enabled;
+    }
+
+    /**
+     * Applies the per-property attributes present on a `pc-script-instance` element — any attribute that
      * is not part of the element's own API or a reserved HTML attribute name. These are applied
      * after the `attributes` JSON, so an individual attribute always takes precedence over the
      * blob.
      * @param script - The script to apply the attributes to.
-     * @param scriptElement - The `pc-script` element holding the attributes.
+     * @param scriptElement - The `pc-script-instance` element holding the attributes.
      */
-    private applyInlineAttributes(script: any, scriptElement: ScriptElement) {
+    private applyInlineAttributes(script: any, scriptElement: ScriptInstanceElement) {
         const scriptName = scriptElement.getAttribute('name') ?? '';
         for (const attr of Array.from(scriptElement.attributes)) {
             if (!isReservedAttribute(attr.name)) {
@@ -554,13 +575,13 @@ class ScriptComponentElement extends ComponentElement {
     }
 
     /**
-     * Applies a single per-property attribute change to the script of a `pc-script` element.
+     * Applies a single per-property attribute change to the script of a `pc-script-instance` element.
      * When the attribute has been removed, the value from the `attributes` JSON (if any) takes
      * effect again.
-     * @param scriptElement - The `pc-script` element whose attribute changed.
+     * @param scriptElement - The `pc-script-instance` element whose attribute changed.
      * @param attributeName - The name of the changed attribute.
      */
-    private applyScriptProperty(scriptElement: ScriptElement, attributeName: string) {
+    private applyScriptProperty(scriptElement: ScriptInstanceElement, attributeName: string) {
         const script = this.scriptFor(scriptElement);
         if (!script) return;
 
@@ -596,7 +617,7 @@ class ScriptComponentElement extends ComponentElement {
 
             if (typeof current === 'function' || SCRIPT_API_MEMBERS.has(key)) {
                 console.warn(
-                    `Ignoring attribute '${attributeName}' on pc-script '${scriptName}' - '${key}' is part of the Script API.`
+                    `Ignoring attribute '${attributeName}' on pc-script-instance '${scriptName}' - '${key}' is part of the Script API.`
                 );
                 return;
             }
@@ -651,11 +672,11 @@ class ScriptComponentElement extends ComponentElement {
 
     private handleMutations(mutations: MutationRecord[]) {
         for (const mutation of mutations) {
-            // Handle per-property attribute changes on child pc-script elements
+            // Handle per-property attribute changes on child pc-script-instance elements
             if (mutation.type === 'attributes') {
                 const target = mutation.target;
                 if (
-                    target instanceof ScriptElement &&
+                    target instanceof ScriptInstanceElement &&
                     target.parentElement === this &&
                     mutation.attributeName &&
                     !isReservedAttribute(mutation.attributeName)
@@ -667,17 +688,17 @@ class ScriptComponentElement extends ComponentElement {
 
             // Only direct children are managed - the observer watches the subtree for attribute
             // changes, but deeper childList records must not create or destroy scripts
-            // (matching initComponent's ':scope > pc-script' contract)
+            // (matching initComponent's ':scope > pc-script-instance' contract)
             if (mutation.target !== this) {
                 continue;
             }
 
-            // Handle removed nodes first, so that replacing a pc-script with a same-named one
+            // Handle removed nodes first, so that replacing a pc-script-instance with a same-named one
             // destroys the old script before the replacement is created. Only destroy a script
             // this element actually owns - a duplicate-named element whose own create() failed
             // must not take down the live script on removal.
             mutation.removedNodes.forEach((node) => {
-                if (node instanceof ScriptElement) {
+                if (node instanceof ScriptInstanceElement) {
                     const scriptName = node.getAttribute('name');
                     if (
                         scriptName &&
@@ -693,7 +714,7 @@ class ScriptComponentElement extends ComponentElement {
 
             // Handle added nodes
             mutation.addedNodes.forEach((node) => {
-                if (node instanceof ScriptElement) {
+                if (node instanceof ScriptInstanceElement) {
                     this.createScript(node);
                 }
             });
@@ -714,6 +735,6 @@ class ScriptComponentElement extends ComponentElement {
     }
 }
 
-customElements.define('pc-scripts', ScriptComponentElement);
+customElements.define('pc-script', ScriptComponentElement);
 
 export { ScriptComponentElement };

package/src/components/{script.ts → script-instance.ts}

@@ -4,8 +4,8 @@ import { AsyncElement } from '../async-element';
 import { parseBool } from '../parse';
 
 /**
- * The ScriptElement interface provides properties and methods for manipulating
- * `<pc-script>` elements. The ScriptElement interface also inherits the properties and
+ * The ScriptInstanceElement interface provides properties and methods for manipulating
+ * `<pc-script-instance>` elements. The ScriptInstanceElement interface also inherits the properties and
  * methods of the {@link AsyncElement} interface.
  *
  * Script attributes can be supplied through two channels:
@@ -27,7 +27,7 @@ import { parseBool } from '../parse';
  * new-name one, re-applying both attribute channels to it.
  *
  * The element becomes ready once its script instance has been created by the parent
- * `<pc-scripts>` element.
+ * `<pc-script>` element.
  *
  * @fires {CustomEvent} scriptattributeschange - Fired when the script's attributes change. The
  * `detail` carries the new `attributes` object. Bubbles.
@@ -36,13 +36,13 @@ import { parseBool } from '../parse';
  * @fires {CustomEvent} scriptnamechange - Fired when the script is renamed on a live element. The
  * `detail` carries `oldName` and `newName`. Bubbles.
  */
-class ScriptElement extends AsyncElement {
+class ScriptInstanceElement extends AsyncElement {
     private _attributes: Record<string, any> = {};
 
     private _enabled = true;
 
     /**
-     * The Script instance created for this element by its parent `<pc-scripts>` element.
+     * The Script instance created for this element by its parent `<pc-script>` element.
      * @internal
      */
     _script: Script | null = null;
@@ -97,11 +97,11 @@ class ScriptElement extends AsyncElement {
 
     /**
      * Sets the name of the script to create. The `name` attribute is the single source of truth
-     * (it is what the parent `<pc-scripts>` element reads when creating the instance), so the
+     * (it is what the parent `<pc-script>` element reads when creating the instance), so the
      * property writes through to it — assigning before insertion works as expected:
      *
      * ```js
-     * const script = document.createElement('pc-script');
+     * const script = document.createElement('pc-script-instance');
      * script.name = 'rotate';
      * scriptsElement.appendChild(script);
      * await script.ready();
@@ -131,11 +131,11 @@ class ScriptElement extends AsyncElement {
     }
 
     connectedCallback() {
-        // Script instances are created by the parent pc-scripts element, so an element placed
+        // Script instances are created by the parent pc-script element, so an element placed
         // anywhere else is inert and never becomes ready - warn rather than hang silently
-        if (this.parentElement?.tagName !== 'PC-SCRIPTS') {
+        if (this.parentElement?.tagName !== 'PC-SCRIPT') {
             console.warn(
-                `pc-script '${this.getAttribute('name')}' must be a direct child of pc-scripts - script not created`
+                `pc-script-instance '${this.getAttribute('name')}' must be a direct child of pc-script - script not created`
             );
         }
     }
@@ -149,7 +149,7 @@ class ScriptElement extends AsyncElement {
     }
 
     /**
-     * Called by the parent `<pc-scripts>` element when the script instance has been created.
+     * Called by the parent `<pc-script>` element when the script instance has been created.
      * Creation can happen more than once per connection (a runtime `name` change recreates the
      * instance), but `_onReady` signals readiness at most once per cycle.
      * @internal
@@ -173,7 +173,7 @@ class ScriptElement extends AsyncElement {
                     this.scriptAttributes = JSON.parse(newValue);
                 } catch (error) {
                     console.warn(
-                        `Invalid 'attributes' JSON on pc-script '${this.getAttribute('name')}': ${(error as Error).message}`
+                        `Invalid 'attributes' JSON on pc-script-instance '${this.getAttribute('name')}': ${(error as Error).message}`
                     );
                 }
                 break;
@@ -197,6 +197,6 @@ class ScriptElement extends AsyncElement {
     }
 }
 
-customElements.define('pc-script', ScriptElement);
+customElements.define('pc-script-instance', ScriptInstanceElement);
 
-export { ScriptElement };
+export { ScriptInstanceElement };