@playcanvas/web-components 0.16.0 → 0.17.0

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 };

package/src/components/{scrollview-component.ts → scroll-view-component.ts}

@@ -25,10 +25,12 @@ const visibilities = new Map<'always' | 'when-required', number>([
 
 /**
  * The ScrollViewComponentElement interface provides properties and methods for manipulating
- * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-scrollview/ | `<pc-scrollview>`} elements.
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-scroll-view/ | `<pc-scroll-view>`} elements.
  * The ScrollViewComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link ScrollViewComponent} (`scrollview`).
+ *
  * @category Components
  */
 class ScrollViewComponentElement extends ComponentElement {
@@ -437,6 +439,6 @@ class ScrollViewComponentElement extends ComponentElement {
     }
 }
 
-customElements.define('pc-scrollview', ScrollViewComponentElement);
+customElements.define('pc-scroll-view', ScrollViewComponentElement);
 
 export { ScrollViewComponentElement };

package/src/components/scrollbar-component.ts

@@ -16,6 +16,8 @@ const orientations = new Map<'horizontal' | 'vertical', number>([
  * The ScrollbarComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link ScrollbarComponent} (`scrollbar`).
+ *
  * @category Components
  */
 class ScrollbarComponentElement extends ComponentElement {

package/src/components/sound-component.ts

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

package/src/components/sound-slot.ts

@@ -8,7 +8,7 @@ import { SoundComponentElement } from './sound-component';
 
 /**
  * The SoundSlotElement interface provides properties and methods for manipulating
- * `<pc-sound>` elements. The SoundSlotElement interface also inherits the properties and
+ * `<pc-sound-slot>` elements. The SoundSlotElement interface also inherits the properties and
  * methods of the {@link AsyncElement} interface.
  */
 class SoundSlotElement extends AsyncElement {
@@ -31,7 +31,7 @@ class SoundSlotElement extends AsyncElement {
     private _volume = 1;
 
     /**
-     * The `<pc-sounds>` this slot was added to, captured at connect time.
+     * The `<pc-sound>` this slot was added to, captured at connect time.
      *
      * `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
@@ -106,7 +106,7 @@ class SoundSlotElement extends AsyncElement {
         const soundElement = this.parentElement as SoundComponentElement;
 
         if (!(soundElement instanceof SoundComponentElement)) {
-            console.warn('pc-sound must be a direct child of a pc-sounds element');
+            console.warn('pc-sound-slot must be a direct child of a pc-sound element');
             return null;
         }
 
@@ -324,6 +324,6 @@ class SoundSlotElement extends AsyncElement {
     }
 }
 
-customElements.define('pc-sound', SoundSlotElement);
+customElements.define('pc-sound-slot', SoundSlotElement);
 
 export { SoundSlotElement };

package/src/entity-base.ts

@@ -17,11 +17,12 @@ export const POINTER_ATTRIBUTES = [
 ] as const;
 
 /**
- * The base class for elements that front an engine {@link Entity}: `<pc-entity>`, which creates
- * one, and `<pc-node>`, which binds to one inside a model's instantiated hierarchy. It carries
- * what both need — the `entity` contract, registration with the owning application (which joins
- * picked scene nodes back to elements by identity, never by name), and the pointer listener
- * bookkeeping that lets the application lazily attach its canvas handlers.
+ * The base class for elements that front an engine {@link Entity}: `<pc-entity>` and
+ * `<pc-model>`, which create one, and `<pc-node>`, which binds to one inside a model's
+ * instantiated hierarchy. It carries what all of them need — the `entity` contract, registration
+ * with the owning application (which joins picked scene nodes back to elements by identity,
+ * never by name), and the pointer listener bookkeeping that lets the application lazily attach
+ * its canvas handlers.
  */
 class EntityBaseElement extends AsyncElement {
     protected _entity: Entity | null = null;