@playcanvas/web-components 0.16.0 → 0.18.0

package/src/index.ts

@@ -9,38 +9,39 @@
 
 /* eslint-disable import-x/order */
 
-// Note that order matters here (e.g. pc-entity must be defined before components)
+// Note that order matters here (e.g. pc-entity and pc-model must be defined before components)
 import { AsyncElement, whenReady } from './async-element';
-import { ModuleElement } from './module';
+import { WasmElement } from './wasm';
 import { AppElement } from './app';
 import { EntityElement } from './entity';
+import { ModelElement } from './model';
 import { AssetElement } from './asset';
 import { AnimComponentElement } from './components/anim-component';
 import { AnimClipElement } from './components/anim-clip';
-import { ListenerComponentElement } from './components/listener-component';
+import { AudioListenerComponentElement } from './components/audio-listener-component';
 import { ButtonComponentElement } from './components/button-component';
 import { CameraComponentElement } from './components/camera-component';
 import { CollisionComponentElement } from './components/collision-component';
 import { ComponentElement } from './components/component';
 import { ElementComponentElement } from './components/element-component';
 import { JointComponentElement } from './components/joint-component';
-import { LayoutChildComponentElement } from './components/layoutchild-component';
-import { LayoutGroupComponentElement } from './components/layoutgroup-component';
+import { LayoutChildComponentElement } from './components/layout-child-component';
+import { LayoutGroupComponentElement } from './components/layout-group-component';
 import { LightComponentElement } from './components/light-component';
-import { ParticleSystemComponentElement } from './components/particlesystem-component';
+import { ParticleSystemComponentElement } from './components/particle-system-component';
 import { RenderComponentElement } from './components/render-component';
-import { RigidBodyComponentElement } from './components/rigidbody-component';
+import { RigidBodyComponentElement } from './components/rigid-body-component';
 import { ScreenComponentElement } from './components/screen-component';
 import { ScrollbarComponentElement } from './components/scrollbar-component';
-import { ScrollViewComponentElement } from './components/scrollview-component';
+import { ScrollViewComponentElement } from './components/scroll-view-component';
 import { ScriptComponentElement } from './components/script-component';
-import { ScriptElement } from './components/script';
+import { ScriptInstanceElement } from './components/script-instance';
 import { SoundComponentElement } from './components/sound-component';
 import { SoundSlotElement } from './components/sound-slot';
 import { GSplatComponentElement } from './components/gsplat-component';
 import { EntityBaseElement } from './entity-base';
+import { EntityOwnerElement } from './entity-owner';
 import { MaterialElement } from './material';
-import { ModelElement } from './model';
 import { NodeElement } from './node';
 import { SceneElement } from './scene';
 import { SkyElement } from './sky';
@@ -71,32 +72,32 @@ declare global {
         'pc-entity': EntityElement;
         'pc-gsplat': GSplatComponentElement;
         'pc-joint': JointComponentElement;
-        'pc-layoutchild': LayoutChildComponentElement;
-        'pc-layoutgroup': LayoutGroupComponentElement;
+        'pc-layout-child': LayoutChildComponentElement;
+        'pc-layout-group': LayoutGroupComponentElement;
         'pc-light': LightComponentElement;
-        'pc-listener': ListenerComponentElement;
+        'pc-audio-listener': AudioListenerComponentElement;
         'pc-material': MaterialElement;
         'pc-model': ModelElement;
-        'pc-module': ModuleElement;
+        'pc-wasm': WasmElement;
         'pc-node': NodeElement;
-        'pc-particles': ParticleSystemComponentElement;
+        'pc-particle-system': ParticleSystemComponentElement;
         'pc-render': RenderComponentElement;
-        'pc-rigidbody': RigidBodyComponentElement;
+        'pc-rigid-body': RigidBodyComponentElement;
         'pc-scene': SceneElement;
         'pc-screen': ScreenComponentElement;
-        'pc-script': ScriptElement;
-        'pc-scripts': ScriptComponentElement;
+        'pc-script-instance': ScriptInstanceElement;
+        'pc-script': ScriptComponentElement;
         'pc-scrollbar': ScrollbarComponentElement;
-        'pc-scrollview': ScrollViewComponentElement;
+        'pc-scroll-view': ScrollViewComponentElement;
         'pc-sky': SkyElement;
-        'pc-sound': SoundSlotElement;
-        'pc-sounds': SoundComponentElement;
+        'pc-sound-slot': SoundSlotElement;
+        'pc-sound': SoundComponentElement;
     }
 }
 
 export {
     AsyncElement,
-    ModuleElement,
+    WasmElement,
     AppElement,
     EntityElement,
     AssetElement,
@@ -112,18 +113,19 @@ export {
     LayoutGroupComponentElement,
     ParticleSystemComponentElement,
     LightComponentElement,
-    ListenerComponentElement,
+    AudioListenerComponentElement,
     RenderComponentElement,
     RigidBodyComponentElement,
     ScreenComponentElement,
     ScrollbarComponentElement,
     ScrollViewComponentElement,
     ScriptComponentElement,
-    ScriptElement,
+    ScriptInstanceElement,
     SoundComponentElement,
     SoundSlotElement,
     GSplatComponentElement,
     EntityBaseElement,
+    EntityOwnerElement,
     MaterialElement,
     ModelElement,
     NodeElement,
@@ -132,6 +134,17 @@ export {
     whenReady
 };
 
+export type { AddressMode, MagFilterMode, MinFilterMode } from './asset';
 export type { AsyncElementTagName } from './async-element';
+export type { JointType, MotionMode } from './components/joint-component';
+export type {
+    BlendType,
+    ColorChannel,
+    CullMode,
+    FresnelModel,
+    OccludeSpecular,
+    OpacityDither,
+    ScalarChannel
+} from './material';
 export type { HierarchyMaterial, HierarchyNode } from './model';
-export type { MaterialOverrides } from './node';
+export type { MaterialOverrides, NodeBindingState } from './node';

package/src/material.ts

@@ -29,7 +29,8 @@ import type { AppElement } from './app';
 import { useAsset } from './asset';
 import { parseBool, parseColor, parseEnum, parseNumber, parseVec2 } from './parse';
 
-type BlendType =
+/** The blend modes for a material. */
+export type BlendType =
     | 'none'
     | 'normal'
     | 'additive'
@@ -56,7 +57,8 @@ const blendTypes = new Map<BlendType, number>([
     ['subtractive', BLEND_SUBTRACTIVE]
 ]);
 
-type CullMode = 'none' | 'back' | 'front' | 'front-and-back';
+/** The face culling modes for a material. */
+export type CullMode = 'none' | 'back' | 'front' | 'front-and-back';
 
 const cullModes = new Map<CullMode, number>([
     ['none', CULLFACE_NONE],
@@ -65,14 +67,16 @@ const cullModes = new Map<CullMode, number>([
     ['front-and-back', CULLFACE_FRONTANDBACK]
 ]);
 
-type FresnelModel = 'none' | 'schlick';
+/** The Fresnel models for a material. */
+export type FresnelModel = 'none' | 'schlick';
 
 const fresnelModels = new Map<FresnelModel, number>([
     ['none', FRESNEL_NONE],
     ['schlick', FRESNEL_SCHLICK]
 ]);
 
-type OccludeSpecular = 'none' | 'ao' | 'gloss-dependent';
+/** The specular occlusion modes for a material. */
+export type OccludeSpecular = 'none' | 'ao' | 'gloss-dependent';
 
 const occludeSpeculars = new Map<OccludeSpecular, number>([
     ['none', SPECOCC_NONE],
@@ -80,17 +84,20 @@ const occludeSpeculars = new Map<OccludeSpecular, number>([
     ['gloss-dependent', SPECOCC_GLOSSDEPENDENT]
 ]);
 
+/** The opacity dithering modes for a material. */
+export type OpacityDither = 'none' | 'bayer8' | 'bluenoise' | 'ignnoise';
+
 // The DITHER_* constants are strings whose values are exactly these names, so a parsed value is
 // assigned to the material unchanged rather than mapped through a table.
-type OpacityDither = 'none' | 'bayer8' | 'bluenoise' | 'ignnoise';
-
 const opacityDithers: OpacityDither[] = ['none', 'bayer8', 'bluenoise', 'ignnoise'];
 
-type ColorChannel = 'r' | 'g' | 'b' | 'a' | 'rgb';
+/** The texture channels a color map can sample. */
+export type ColorChannel = 'r' | 'g' | 'b' | 'a' | 'rgb';
 
 const colorChannels: ColorChannel[] = ['r', 'g', 'b', 'a', 'rgb'];
 
-type ScalarChannel = 'r' | 'g' | 'b' | 'a';
+/** The texture channels a scalar map can sample. */
+export type ScalarChannel = 'r' | 'g' | 'b' | 'a';
 
 const scalarChannels: ScalarChannel[] = ['r', 'g', 'b', 'a'];
 
@@ -136,6 +143,10 @@ type TextureSlot =
  * The two aliases are documented here rather than on an accessor, because they resolve to the
  * `gloss` properties and would otherwise inherit gloss's description - which reads inverted.
  *
+ * @elementSummary The `<pc-material>` element defines a physically based material, which
+ * `<pc-render>` elements apply by naming its `id`. It is metal/rough by default, with `metalness`
+ * starting at 0. Must be a direct child of `<pc-app>`.
+ *
  * @attribute {number} roughness - The roughness of the material, from 0 (shiny) to 1 (rough). An
  * alias for `gloss` that also inverts it, so do not combine it with the `gloss` attributes.
  * @attribute {string} roughness-map - The id of the `pc-asset` to use as the roughness map. An

package/src/model.ts

@@ -1,7 +1,10 @@
 import type { ContainerResource, Entity, EventHandle } from 'playcanvas';
+import { Vec3 } from 'playcanvas';
 
 import { useAsset } from './asset';
-import { AsyncElement } from './async-element';
+import { POINTER_ATTRIBUTES } from './entity-base';
+import { buildDescendantEntities, EntityOwnerElement } from './entity-owner';
+import { parseBool, parseTags, parseVec3 } from './parse';
 
 /**
  * One material assignment of a {@link HierarchyNode} with a render component: a mesh instance's
@@ -104,14 +107,47 @@ const formatHierarchy = (root: HierarchyNode, counts: ReadonlyMap<string, number
  * The ModelElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
- * The element becomes ready once its container asset has loaded and the instantiated hierarchy has
- * been added to the scene — `entity` is non-null by then. A failed load also settles readiness,
- * with `entity` remaining `null`: readiness means the load settled, not that it succeeded — listen
- * for `error`, or check `entity`, to tell the outcomes apart. Changing `asset` re-arms readiness
- * and instantiates anew, so a `ready()` obtained after the change resolves against the new
- * hierarchy. A `pc-model` outside a `pc-app`, or referencing an unknown asset id, warns and never
- * becomes ready.
+ * The element creates and fronts a stable host entity: `entity` is that host, created when the
+ * application builds its hierarchy and kept across `asset` changes, so the element's transform
+ * and tags are instance placement that composes with whatever transform the asset authored on
+ * its root. The instantiated content is parented beneath the host and exposed as
+ * {@link contentEntity}.
  *
+ * The element becomes ready once its current asset selection has settled: the container asset
+ * has loaded and its content root has been parented beneath the host, the load has failed
+ * (`contentEntity` stays `null` — listen for `error`, or check `contentEntity`, to tell the
+ * outcomes apart), or no asset is assigned at all. Changing `asset` re-arms readiness and
+ * instantiates anew, so a `ready()` obtained after the change resolves against the new content.
+ * A `pc-model` outside a `pc-app`, or referencing an unknown asset id, warns and never becomes
+ * ready.
+ *
+ * The pointer events below are dispatched by the containing `<pc-app>` element when the pointer
+ * intersects the model's geometry, exactly as for `<pc-entity>` — a hit on a content node that no
+ * `pc-node` fronts resolves to this element.
+ *
+ * @elementSummary The `<pc-model>` element instantiates a 3D model from a container asset
+ * (typically a GLB) beneath an entity of its own, so the element's transform and tags place the
+ * instance in the scene. Its `<pc-node>` children override what the asset authored. Place it in the
+ * `<pc-scene>`, or nest it under a `<pc-entity>`, another `<pc-model>` or a `<pc-node>`.
+ *
+ * @attribute {boolean} enabled - The enabled state of the model.
+ * @attribute {string} name - The name of the model.
+ * @attribute {string} position - The position of the model.
+ * @attribute {string} rotation - The rotation of the model.
+ * @attribute {string} scale - The scale of the model.
+ * @attribute {string} tags - The tags of the model.
+ * @attribute {string} onpointerenter - Script to run when the pointer moves onto the model.
+ * @attribute {string} onpointerleave - Script to run when the pointer moves off the model.
+ * @attribute {string} onpointermove - Script to run when the pointer moves over the model.
+ * @attribute {string} onpointerdown - Script to run when a pointer button is pressed over the
+ * model.
+ * @attribute {string} onpointerup - Script to run when a pointer button is released over the
+ * model.
+ * @fires {PointerEvent} pointerenter - Fired when the pointer moves onto the model.
+ * @fires {PointerEvent} pointerleave - Fired when the pointer moves off the model.
+ * @fires {PointerEvent} pointermove - Fired when the pointer moves over the model.
+ * @fires {PointerEvent} pointerdown - Fired when a pointer button is pressed over the model.
+ * @fires {PointerEvent} pointerup - Fired when a pointer button is released over the model.
  * @fires {Event} load - Fired each time a container asset finishes instantiating, including
  * re-instantiation after `asset` changes. Does not bubble — listen on this element, or use a
  * capture-phase listener on an ancestor.
@@ -119,16 +155,16 @@ const formatHierarchy = (root: HierarchyNode, counts: ReadonlyMap<string, number
  * error in `message`. Does not bubble. The element still becomes ready — readiness means the load
  * settled, not that it succeeded.
  */
-class ModelElement extends AsyncElement {
+class ModelElement extends EntityOwnerElement {
     private _asset = '';
 
-    private _entity: Entity | null = null;
+    private _contentEntity: Entity | null = null;
 
     /**
-     * Incremented on every new load and on disconnect, and captured by a load when it starts. A
-     * load that resumes from an await or a load callback abandons itself if the value has moved
-     * on, so a superseded load can neither instantiate a second entity nor parent one that has
-     * since been destroyed.
+     * Incremented on every new load, on disconnect, and when the host entity dies, and captured
+     * by a load when it starts. A load that resumes from an await or a load callback abandons
+     * itself if the value has moved on, so a superseded load can neither instantiate a second
+     * content root nor parent one under a host a newer cycle has already replaced.
      */
     private _loadGeneration = 0;
 
@@ -142,12 +178,13 @@ class ModelElement extends AsyncElement {
     private _errorHandle: EventHandle | null = null;
 
     /**
-     * The root entity of the instantiated model. `null` until the container asset has loaded
-     * and been instantiated, and again once the element has been removed from the document.
-     * @returns The model's root entity, or `null`.
+     * The root entity of the instantiated model content, parented beneath the host entity.
+     * `null` until the container asset has loaded and been instantiated, after a failed load,
+     * and again once the element has been removed from the document.
+     * @returns The content root entity, or `null`.
      */
-    get entity(): Entity | null {
-        return this._entity;
+    get contentEntity(): Entity | null {
+        return this._contentEntity;
     }
 
     /**
@@ -160,12 +197,13 @@ class ModelElement extends AsyncElement {
      * is the printable form.
      *
      * The snapshot is plain data, computed afresh each call: it does not follow later changes
-     * to the hierarchy, and mutating it changes nothing.
+     * to the hierarchy, and mutating it changes nothing. It covers the instantiated content
+     * only — the host entity the element fronts is not part of the asset's node tree.
      *
      * @returns The root of the instantiated node tree, or `null`.
      */
     hierarchy(): HierarchyNode | null {
-        const root = this._entity;
+        const root = this._contentEntity;
         if (!root) {
             return null;
         }
@@ -214,19 +252,59 @@ class ModelElement extends AsyncElement {
         // A model outside an application is inert and never becomes ready, so awaiting it hangs.
         // Warn rather than fail silently, naming the parent it requires, as every other misplaced
         // element does.
-        if (!this.closestApp) {
+        const closestApp = this.closestApp;
+        if (!closestApp) {
             const label = this._asset ? ` '${this._asset}'` : '';
             console.warn(`pc-model${label} must be a descendant of pc-app - model not created`);
             return;
         }
-        this._loadModel();
+
+        // If the app is already running, create the host immediately; during a boot, the app's
+        // own sweep does it. Either way, _onBuilt starts the content load once the host is
+        // parented.
+        if (closestApp._hierarchyReady) {
+            const app = closestApp.app!;
+
+            this._createEntity(app);
+            this._buildHierarchy(app);
+
+            // A build that deferred (an unresolved pc-node above) defers the whole subtree with
+            // it - the node's bind sweeps it.
+            if (this._built) {
+                buildDescendantEntities(this, app);
+            }
+        }
     }
 
     disconnectedCallback() {
+        // Destroying the host destroys the instantiated content with it, and the destroy hook
+        // resets the element. The generation guard comes first so a load suspended on an await
+        // cannot resume against the torn-down element.
         this._loadGeneration++;
         this._detachLoadHandlers();
-        this._unloadModel();
-        this._resetReady();
+        this._entity?.destroy();
+    }
+
+    /**
+     * Starts (or restarts) the content load once the host has been parented. Readiness is not
+     * announced here — it tracks the content settling, not the host entering the scene graph.
+     */
+    protected override _onBuilt() {
+        this._loadContent();
+    }
+
+    /**
+     * Extends the owner reset for the content: the engine's destroy cascade has already taken
+     * the content root down with the host subtree, so only the reference and the in-flight load
+     * are dropped here. The next build re-creates the host and re-instantiates the content.
+     *
+     * @param entity - The host entity that was destroyed.
+     */
+    protected override _onEntityDestroy(entity: Entity) {
+        this._loadGeneration++;
+        this._detachLoadHandlers();
+        this._contentEntity = null;
+        super._onEntityDestroy(entity);
     }
 
     private _detachLoadHandlers() {
@@ -237,9 +315,9 @@ class ModelElement extends AsyncElement {
     }
 
     /**
-     * Resolves readiness and dispatches the `load` event. Called once the instantiated hierarchy
-     * has been parented — readiness means "in the scene graph", matching `pc-entity`, so a ready
-     * model's entity always has world transforms.
+     * Resolves readiness and dispatches the `load` event. Called once the instantiated content
+     * has been parented beneath the host — the host itself is already in the scene graph by
+     * then, so a ready model's content always has world transforms.
      */
     private _announceLoad() {
         this._onReady();
@@ -247,46 +325,29 @@ class ModelElement extends AsyncElement {
     }
 
     private _instantiate(container: ContainerResource) {
-        const generation = this._loadGeneration;
-
-        const entity = container.instantiateRenderEntity();
-        this._entity = entity;
+        const content = container.instantiateRenderEntity();
+        this._contentEntity = content;
+        this._entity!.addChild(content);
+        this._announceLoad();
+    }
 
-        // The parent's readiness re-arms when it is torn down, so these can resume in a later
-        // connection cycle. The entity is captured above and the generation re-checked, so a
-        // stale resume cannot parent an entity a newer cycle has already destroyed.
-        const parentEntityElement = this.closestEntity;
-        if (parentEntityElement) {
-            parentEntityElement.ready().then(() => {
-                if (generation !== this._loadGeneration) {
-                    return;
-                }
-                parentEntityElement.entity!.addChild(entity);
-                this._announceLoad();
-            });
-        } else {
-            const appElement = this.closestApp;
-            if (appElement) {
-                appElement.ready().then(() => {
-                    if (generation !== this._loadGeneration) {
-                        return;
-                    }
-                    appElement.app!.root.addChild(entity);
-                    this._announceLoad();
-                });
-            }
-        }
+    private _destroyContent() {
+        this._contentEntity?.destroy();
+        this._contentEntity = null;
     }
 
-    private async _loadModel() {
-        this._unloadModel();
+    private async _loadContent() {
+        // The old content goes down synchronously, so a reader that checks after an asset change
+        // never sees the outgoing hierarchy. The host survives - components and child entities
+        // attached to it carry over to the new content.
+        this._destroyContent();
 
         // Supersede any load already in flight - only the newest load may instantiate
         const generation = ++this._loadGeneration;
         this._detachLoadHandlers();
 
         // Re-arm readiness so a waiter obtained after an asset change resolves against the new
-        // hierarchy. A no-op on first connection, where readiness is still pending.
+        // content. A no-op on first connection, where readiness is still pending.
         this._resetReady();
 
         const appElement = this.closestApp;
@@ -302,14 +363,25 @@ class ModelElement extends AsyncElement {
             return;
         }
 
+        // The host may not be parented yet - a model under a pc-node that has not bound, reached
+        // through the asset setter. Nothing settles here: _onBuilt re-runs this load once the
+        // host builds.
+        if (!this._entity || !this._built) {
+            return;
+        }
+
+        if (this._asset === '') {
+            // No asset assigned is a settled selection: the element is a usable host (components
+            // attach, waiters resolve) with no content. Assigning an asset later re-arms.
+            this._onReady();
+            return;
+        }
+
         const asset = useAsset(this._asset);
         if (!asset) {
-            // An empty id is a legitimate transient (the asset may be assigned later); a
-            // non-empty one that resolves to nothing is a dead end - say so rather than staying
+            // A non-empty id that resolves to nothing is a dead end - say so rather than staying
             // silently pending.
-            if (this._asset) {
-                console.warn(`pc-model could not find asset '${this._asset}' - model not created`);
-            }
+            console.warn(`pc-model could not find asset '${this._asset}' - model not created`);
             return;
         }
 
@@ -331,7 +403,7 @@ class ModelElement extends AsyncElement {
                 if (generation !== this._loadGeneration) {
                     return;
                 }
-                // A failed load settles readiness with a null entity, mirroring pc-asset:
+                // A failed load settles readiness with a null contentEntity, mirroring pc-asset:
                 // readiness means the load settled, not that it succeeded.
                 this.dispatchEvent(
                     new ErrorEvent('error', {
@@ -343,11 +415,6 @@ class ModelElement extends AsyncElement {
         }
     }
 
-    private _unloadModel() {
-        this._entity?.destroy();
-        this._entity = null;
-    }
-
     /**
      * Sets the id of the `pc-asset` to use for the model.
      * @param value - The asset ID.
@@ -355,7 +422,7 @@ class ModelElement extends AsyncElement {
     set asset(value: string) {
         this._asset = value;
         if (this.isConnected) {
-            this._loadModel();
+            this._loadContent();
         }
     }
 
@@ -368,7 +435,7 @@ class ModelElement extends AsyncElement {
     }
 
     static get observedAttributes() {
-        return ['asset'];
+        return ['asset', 'enabled', 'name', 'position', 'rotation', 'scale', 'tags', ...POINTER_ATTRIBUTES];
     }
 
     attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null) {
@@ -376,6 +443,31 @@ class ModelElement extends AsyncElement {
             case 'asset':
                 this.asset = newValue ?? '';
                 break;
+            case 'enabled':
+                this.enabled = parseBool(newValue, true);
+                break;
+            case 'name':
+                this.name = newValue ?? 'Untitled';
+                break;
+            case 'position':
+                this.position = parseVec3(newValue, Vec3.ZERO, name);
+                break;
+            case 'rotation':
+                this.rotation = parseVec3(newValue, Vec3.ZERO, name);
+                break;
+            case 'scale':
+                this.scale = parseVec3(newValue, Vec3.ONE, name);
+                break;
+            case 'tags':
+                this.tags = parseTags(newValue);
+                break;
+            case 'onpointerenter':
+            case 'onpointerleave':
+            case 'onpointerdown':
+            case 'onpointerup':
+            case 'onpointermove':
+                this._updateInlineHandler(name, newValue);
+                break;
         }
     }
 }

package/src/node.ts

@@ -2,9 +2,9 @@ import type { Entity, EventHandle, GraphNode, Material, MeshInstance, Quat, Rend
 import { Vec3 } from 'playcanvas';
 
 import { ComponentElement } from './components/component';
-import { buildDescendantEntities } from './entity';
-import type { EntityElement } from './entity';
 import { EntityBaseElement, POINTER_ATTRIBUTES } from './entity-base';
+import { buildDescendantEntities } from './entity-owner';
+import type { EntityOwnerElement } from './entity-owner';
 import { MaterialElement } from './material';
 import { ModelElement } from './model';
 import { parseBool, parseTags, parseVec3 } from './parse';
@@ -15,7 +15,7 @@ import { parseBool, parseTags, parseVec3 } from './parse';
  * `missing`/`ambiguous`/`duplicate` when resolution failed — each accompanied by a warning
  * naming the cause.
  */
-type NodeBindingState = 'pending' | 'bound' | 'missing' | 'ambiguous' | 'duplicate';
+export type NodeBindingState = 'pending' | 'bound' | 'missing' | 'ambiguous' | 'duplicate';
 
 /**
  * The authored values a bound node's overrides displaced, captured per property when the first
@@ -164,6 +164,11 @@ const levenshtein = (a: string, b: string): number => {
  * The pointer events below are dispatched by the containing `<pc-app>` element when the pointer
  * intersects the bound node's geometry, exactly as for `<pc-entity>`.
  *
+ * @elementSummary The `<pc-node>` element binds to a node inside the hierarchy a `<pc-model>`
+ * instantiated and declares overrides against it: a transform, an enabled state, tags, components
+ * to add, or content to attach. Its `name` is a lookup, never a rename. Must be a descendant of
+ * `<pc-model>`.
+ *
  * @attribute {string} name - The name of the node to bind, resolved within the nearest ancestor
  * `pc-model` (or `pc-node`) once it has instantiated.
  * @attribute {number} index - Which match to bind when `name` matches more than one node,
@@ -318,7 +323,10 @@ class NodeElement extends EntityBaseElement {
      * is retained untouched — a redundant edit must not flicker overrides through a revert.
      */
     private _rebind() {
-        const hostEntity = this._host?.entity ?? null;
+        // A model fronts a host entity of its own; the names this element resolves are the
+        // asset's, so the search starts at the instantiated content root, not the wrapper.
+        const host = this._host;
+        const hostEntity = (host instanceof ModelElement ? host.contentEntity : host?.entity) ?? null;
 
         if (!hostEntity || !this._name) {
             // Host not instantiated (or nothing to look up yet): return to pending. An assigned
@@ -435,8 +443,9 @@ class NodeElement extends EntityBaseElement {
         this._revertOverrides();
 
         // Attachment points anchor to the bound node, so they cannot outlive the binding. Each
-        // destroyed entity resets its element, which the next _buildChildren re-creates.
-        this.querySelectorAll<EntityElement>('pc-entity').forEach((child) => {
+        // destroyed entity resets its element, which the next _buildChildren re-creates - a
+        // model host among them re-instantiates its content when it rebuilds.
+        this.querySelectorAll<EntityOwnerElement>('pc-entity, pc-model').forEach((child) => {
             if (child.closestEntity === this) {
                 child.entity?.destroy();
             }

package/src/scene.ts

@@ -9,6 +9,9 @@ import { parseColor, parseEnum, parseNumber, parseVec3 } from './parse';
  * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-scene/ | `<pc-scene>`} elements.
  * The SceneElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
+ *
+ * @elementSummary The `<pc-scene>` element holds the entity hierarchy the application renders,
+ * along with the scene-wide fog and gravity settings. Must be a direct child of `<pc-app>`.
  */
 class SceneElement extends AsyncElement {
     /**

package/src/sky.ts

@@ -10,6 +10,10 @@ import { parseBool, parseEnum, parseNumber, parseVec3 } from './parse';
  * The SkyElement interface provides properties and methods for manipulating
  * `<pc-sky>` elements. The SkyElement interface also inherits the properties and
  * methods of the {@link HTMLElement} interface.
+ *
+ * @elementSummary The `<pc-sky>` element renders a skybox from a texture asset, projected as an
+ * infinite background, a box or a dome, and optionally lights the scene from it. Must be a direct
+ * child of `<pc-scene>`.
  */
 class SkyElement extends AsyncElement {
     private _asset = '';