@playcanvas/web-components 0.16.0 → 0.18.0

package/dist/index.d.ts

@@ -7,36 +7,37 @@
  * @module EngineWebComponents
  */
 import { AsyncElement, whenReady } from './async-element.js';
-import { ModuleElement } from './module.js';
+import { WasmElement } from './wasm.js';
 import { AppElement } from './app.js';
 import { EntityElement } from './entity.js';
+import { ModelElement } from './model.js';
 import { AssetElement } from './asset.js';
 import { AnimComponentElement } from './components/anim-component.js';
 import { AnimClipElement } from './components/anim-clip.js';
-import { ListenerComponentElement } from './components/listener-component.js';
+import { AudioListenerComponentElement } from './components/audio-listener-component.js';
 import { ButtonComponentElement } from './components/button-component.js';
 import { CameraComponentElement } from './components/camera-component.js';
 import { CollisionComponentElement } from './components/collision-component.js';
 import { ComponentElement } from './components/component.js';
 import { ElementComponentElement } from './components/element-component.js';
 import { JointComponentElement } from './components/joint-component.js';
-import { LayoutChildComponentElement } from './components/layoutchild-component.js';
-import { LayoutGroupComponentElement } from './components/layoutgroup-component.js';
+import { LayoutChildComponentElement } from './components/layout-child-component.js';
+import { LayoutGroupComponentElement } from './components/layout-group-component.js';
 import { LightComponentElement } from './components/light-component.js';
-import { ParticleSystemComponentElement } from './components/particlesystem-component.js';
+import { ParticleSystemComponentElement } from './components/particle-system-component.js';
 import { RenderComponentElement } from './components/render-component.js';
-import { RigidBodyComponentElement } from './components/rigidbody-component.js';
+import { RigidBodyComponentElement } from './components/rigid-body-component.js';
 import { ScreenComponentElement } from './components/screen-component.js';
 import { ScrollbarComponentElement } from './components/scrollbar-component.js';
-import { ScrollViewComponentElement } from './components/scrollview-component.js';
+import { ScrollViewComponentElement } from './components/scroll-view-component.js';
 import { ScriptComponentElement } from './components/script-component.js';
-import { ScriptElement } from './components/script.js';
+import { ScriptInstanceElement } from './components/script-instance.js';
 import { SoundComponentElement } from './components/sound-component.js';
 import { SoundSlotElement } from './components/sound-slot.js';
 import { GSplatComponentElement } from './components/gsplat-component.js';
 import { EntityBaseElement } from './entity-base.js';
+import { EntityOwnerElement } from './entity-owner.js';
 import { MaterialElement } from './material.js';
-import { ModelElement } from './model.js';
 import { NodeElement } from './node.js';
 import { SceneElement } from './scene.js';
 import { SkyElement } from './sky.js';
@@ -60,29 +61,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, AppElement, EntityElement, AssetElement, AnimComponentElement, AnimClipElement, ButtonComponentElement, CameraComponentElement, CollisionComponentElement, ComponentElement, ElementComponentElement, JointComponentElement, LayoutChildComponentElement, LayoutGroupComponentElement, ParticleSystemComponentElement, LightComponentElement, ListenerComponentElement, RenderComponentElement, RigidBodyComponentElement, ScreenComponentElement, ScrollbarComponentElement, ScrollViewComponentElement, ScriptComponentElement, ScriptElement, SoundComponentElement, SoundSlotElement, GSplatComponentElement, EntityBaseElement, MaterialElement, ModelElement, NodeElement, SceneElement, SkyElement, whenReady };
+export { AsyncElement, WasmElement, AppElement, EntityElement, AssetElement, AnimComponentElement, AnimClipElement, ButtonComponentElement, CameraComponentElement, CollisionComponentElement, ComponentElement, ElementComponentElement, JointComponentElement, LayoutChildComponentElement, LayoutGroupComponentElement, ParticleSystemComponentElement, LightComponentElement, AudioListenerComponentElement, RenderComponentElement, RigidBodyComponentElement, ScreenComponentElement, ScrollbarComponentElement, ScrollViewComponentElement, ScriptComponentElement, ScriptInstanceElement, SoundComponentElement, SoundSlotElement, GSplatComponentElement, EntityBaseElement, EntityOwnerElement, MaterialElement, ModelElement, NodeElement, SceneElement, SkyElement, whenReady };
+export type { AddressMode, MagFilterMode, MinFilterMode } from './asset.js';
 export type { AsyncElementTagName } from './async-element.js';
+export type { JointType, MotionMode } from './components/joint-component.js';
+export type { BlendType, ColorChannel, CullMode, FresnelModel, OccludeSpecular, OpacityDither, ScalarChannel } from './material.js';
 export type { HierarchyMaterial, HierarchyNode } from './model.js';
-export type { MaterialOverrides } from './node.js';
+export type { MaterialOverrides, NodeBindingState } from './node.js';

package/dist/material.d.cts

@@ -1,11 +1,18 @@
 import { Color, StandardMaterial, Vec2 } from 'playcanvas';
-type BlendType = 'none' | 'normal' | 'additive' | 'additive-alpha' | 'premultiplied' | 'multiplicative' | 'multiplicative-2x' | 'screen' | 'min' | 'max' | 'subtractive';
-type CullMode = 'none' | 'back' | 'front' | 'front-and-back';
-type FresnelModel = 'none' | 'schlick';
-type OccludeSpecular = 'none' | 'ao' | 'gloss-dependent';
-type OpacityDither = 'none' | 'bayer8' | 'bluenoise' | 'ignnoise';
-type ColorChannel = 'r' | 'g' | 'b' | 'a' | 'rgb';
-type ScalarChannel = 'r' | 'g' | 'b' | 'a';
+/** The blend modes for a material. */
+export type BlendType = 'none' | 'normal' | 'additive' | 'additive-alpha' | 'premultiplied' | 'multiplicative' | 'multiplicative-2x' | 'screen' | 'min' | 'max' | 'subtractive';
+/** The face culling modes for a material. */
+export type CullMode = 'none' | 'back' | 'front' | 'front-and-back';
+/** The Fresnel models for a material. */
+export type FresnelModel = 'none' | 'schlick';
+/** The specular occlusion modes for a material. */
+export type OccludeSpecular = 'none' | 'ao' | 'gloss-dependent';
+/** The opacity dithering modes for a material. */
+export type OpacityDither = 'none' | 'bayer8' | 'bluenoise' | 'ignnoise';
+/** The texture channels a color map can sample. */
+export type ColorChannel = 'r' | 'g' | 'b' | 'a' | 'rgb';
+/** The texture channels a scalar map can sample. */
+export type ScalarChannel = 'r' | 'g' | 'b' | 'a';
 /**
  * The MaterialElement interface provides properties and methods for manipulating
  * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-material/ | `<pc-material>`} elements.
@@ -30,6 +37,10 @@ type ScalarChannel = 'r' | 'g' | 'b' | 'a';
  * 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/dist/material.d.ts

@@ -1,11 +1,18 @@
 import { Color, StandardMaterial, Vec2 } from 'playcanvas';
-type BlendType = 'none' | 'normal' | 'additive' | 'additive-alpha' | 'premultiplied' | 'multiplicative' | 'multiplicative-2x' | 'screen' | 'min' | 'max' | 'subtractive';
-type CullMode = 'none' | 'back' | 'front' | 'front-and-back';
-type FresnelModel = 'none' | 'schlick';
-type OccludeSpecular = 'none' | 'ao' | 'gloss-dependent';
-type OpacityDither = 'none' | 'bayer8' | 'bluenoise' | 'ignnoise';
-type ColorChannel = 'r' | 'g' | 'b' | 'a' | 'rgb';
-type ScalarChannel = 'r' | 'g' | 'b' | 'a';
+/** The blend modes for a material. */
+export type BlendType = 'none' | 'normal' | 'additive' | 'additive-alpha' | 'premultiplied' | 'multiplicative' | 'multiplicative-2x' | 'screen' | 'min' | 'max' | 'subtractive';
+/** The face culling modes for a material. */
+export type CullMode = 'none' | 'back' | 'front' | 'front-and-back';
+/** The Fresnel models for a material. */
+export type FresnelModel = 'none' | 'schlick';
+/** The specular occlusion modes for a material. */
+export type OccludeSpecular = 'none' | 'ao' | 'gloss-dependent';
+/** The opacity dithering modes for a material. */
+export type OpacityDither = 'none' | 'bayer8' | 'bluenoise' | 'ignnoise';
+/** The texture channels a color map can sample. */
+export type ColorChannel = 'r' | 'g' | 'b' | 'a' | 'rgb';
+/** The texture channels a scalar map can sample. */
+export type ScalarChannel = 'r' | 'g' | 'b' | 'a';
 /**
  * The MaterialElement interface provides properties and methods for manipulating
  * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-material/ | `<pc-material>`} elements.
@@ -30,6 +37,10 @@ type ScalarChannel = 'r' | 'g' | 'b' | 'a';
  * 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/dist/model.d.cts

@@ -1,5 +1,5 @@
 import type { Entity } from 'playcanvas';
-import { AsyncElement } from './async-element.cjs';
+import { EntityOwnerElement } from './entity-owner.cjs';
 /**
  * One material assignment of a {@link HierarchyNode} with a render component: a mesh instance's
  * position within the component and the runtime name of its current material.
@@ -61,14 +61,47 @@ type HierarchyNode = {
  * 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.
@@ -76,14 +109,14 @@ type HierarchyNode = {
  * error in `message`. Does not bubble. The element still becomes ready — readiness means the load
  * settled, not that it succeeded.
  */
-declare class ModelElement extends AsyncElement {
+declare class ModelElement extends EntityOwnerElement {
     private _asset;
-    private _entity;
+    private _contentEntity;
     /**
-     * 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;
     /**
@@ -94,11 +127,12 @@ declare class ModelElement extends AsyncElement {
     private _loadHandle;
     private _errorHandle;
     /**
-     * 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;
+    get contentEntity(): Entity | null;
     /**
      * Returns a snapshot of the instantiated node tree, or `null` while there is none (the
      * container asset has not loaded, or the element has left the document). One call grounds a
@@ -109,23 +143,37 @@ declare 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;
     connectedCallback(): void;
     disconnectedCallback(): void;
+    /**
+     * 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 _onBuilt(): void;
+    /**
+     * 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 _onEntityDestroy(entity: Entity): void;
     private _detachLoadHandlers;
     /**
-     * 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;
     private _instantiate;
-    private _loadModel;
-    private _unloadModel;
+    private _destroyContent;
+    private _loadContent;
     /**
      * Sets the id of the `pc-asset` to use for the model.
      * @param value - The asset ID.

package/dist/model.d.ts

@@ -1,5 +1,5 @@
 import type { Entity } from 'playcanvas';
-import { AsyncElement } from './async-element.js';
+import { EntityOwnerElement } from './entity-owner.js';
 /**
  * One material assignment of a {@link HierarchyNode} with a render component: a mesh instance's
  * position within the component and the runtime name of its current material.
@@ -61,14 +61,47 @@ type HierarchyNode = {
  * 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.
@@ -76,14 +109,14 @@ type HierarchyNode = {
  * error in `message`. Does not bubble. The element still becomes ready — readiness means the load
  * settled, not that it succeeded.
  */
-declare class ModelElement extends AsyncElement {
+declare class ModelElement extends EntityOwnerElement {
     private _asset;
-    private _entity;
+    private _contentEntity;
     /**
-     * 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;
     /**
@@ -94,11 +127,12 @@ declare class ModelElement extends AsyncElement {
     private _loadHandle;
     private _errorHandle;
     /**
-     * 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;
+    get contentEntity(): Entity | null;
     /**
      * Returns a snapshot of the instantiated node tree, or `null` while there is none (the
      * container asset has not loaded, or the element has left the document). One call grounds a
@@ -109,23 +143,37 @@ declare 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;
     connectedCallback(): void;
     disconnectedCallback(): void;
+    /**
+     * 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 _onBuilt(): void;
+    /**
+     * 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 _onEntityDestroy(entity: Entity): void;
     private _detachLoadHandlers;
     /**
-     * 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;
     private _instantiate;
-    private _loadModel;
-    private _unloadModel;
+    private _destroyContent;
+    private _loadContent;
     /**
      * Sets the id of the `pc-asset` to use for the model.
      * @param value - The asset ID.

package/dist/node.d.cts

@@ -6,7 +6,7 @@ import { EntityBaseElement } from './entity-base.cjs';
  * `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';
 /**
  * A sparse mapping from selector to `pc-material` id, as carried by the `material-overrides`
  * attribute and `materialOverrides` property. A `name:X` key selects every mesh instance of the
@@ -38,6 +38,11 @@ type MaterialOverrides = Readonly<Record<string, string>>;
  * 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,

package/dist/node.d.ts

@@ -6,7 +6,7 @@ import { EntityBaseElement } from './entity-base.js';
  * `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';
 /**
  * A sparse mapping from selector to `pc-material` id, as carried by the `material-overrides`
  * attribute and `materialOverrides` property. A `name:X` key selects every mesh instance of the
@@ -38,6 +38,11 @@ type MaterialOverrides = Readonly<Record<string, string>>;
  * 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,