@playcanvas/web-components 0.17.0 → 0.19.0

package/src/components/light-component.ts

@@ -39,9 +39,17 @@ const shadowTypes = new Map<
  *
  * Engine component: {@link LightComponent} (`light`).
  *
+ * @elementSummary The `<pc-light>` element lights the scene from its entity — as a directional,
+ * omni or spot light — with attributes for color, intensity, range and shadows. Must be a child of
+ * a `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+ *
  * @category Components
  */
 class LightComponentElement extends ComponentElement {
+    private _cascadeBlend = 0;
+
+    private _cascadeDistribution = 0.5;
+
     private _castShadows = false;
 
     private _color = new Color(1, 1, 1);
@@ -50,15 +58,17 @@ class LightComponentElement extends ComponentElement {
 
     private _intensity = 1;
 
-    private _normalOffsetBias = 0.05;
+    private _normalOffsetBias = 0;
+
+    private _numCascades = 1;
 
     private _outerConeAngle = 45;
 
     private _range = 10;
 
-    private _shadowBias = 0.2;
+    private _shadowBias = 0.05;
 
-    private _shadowDistance = 16;
+    private _shadowDistance = 40;
 
     private _shadowIntensity = 1;
 
@@ -77,7 +87,7 @@ class LightComponentElement extends ComponentElement {
 
     private _type: 'directional' | 'omni' | 'spot' = 'directional';
 
-    private _vsmBias = 0.01;
+    private _vsmBias = 0.0025;
 
     private _vsmBlurSize = 11;
 
@@ -96,11 +106,14 @@ class LightComponentElement extends ComponentElement {
 
     protected getInitialComponentData() {
         return {
+            cascadeBlend: this._cascadeBlend,
+            cascadeDistribution: this._cascadeDistribution,
             castShadows: this._castShadows,
             color: this._color,
             innerConeAngle: this._innerConeAngle,
             intensity: this._intensity,
             normalOffsetBias: this._normalOffsetBias,
+            numCascades: this._numCascades,
             outerConeAngle: this._outerConeAngle,
             penumbraFalloff: this._penumbraFalloff,
             penumbraSize: this._penumbraSize,
@@ -111,7 +124,7 @@ class LightComponentElement extends ComponentElement {
             shadowIntensity: this._shadowIntensity,
             shadowResolution: this._shadowResolution,
             shadowSamples: this._shadowSamples,
-            shadowType: shadowTypes.get(this._shadowType),
+            shadowType: shadowTypes.get(this._shadowType) ?? SHADOW_PCF3_32F,
             type: this._type,
             vsmBias: this._vsmBias,
             vsmBlurSize: this._vsmBlurSize
@@ -126,6 +139,51 @@ class LightComponentElement extends ComponentElement {
         return super.component as LightComponent;
     }
 
+    /**
+     * Sets the fraction of each shadow cascade that is blended into the next one, from 0 (no
+     * blending) to 1, which applies only to `directional` lights with `num-cascades` greater than
+     * 1. Defaults to 0.
+     * @param value - The cascade blend factor.
+     */
+    set cascadeBlend(value: number) {
+        this._cascadeBlend = value;
+        if (this.component) {
+            this.component.cascadeBlend = value;
+        }
+    }
+
+    /**
+     * Gets the cascade blend factor of the light, from 0 (no blending) to 1, which applies only to
+     * `directional` lights with `num-cascades` greater than 1.
+     * @returns The cascade blend factor.
+     */
+    get cascadeBlend() {
+        return this._cascadeBlend;
+    }
+
+    /**
+     * Sets the distribution of the camera frustum split between shadow cascades, from 0 (linear
+     * split) to 1 (logarithmic split, concentrating shadow resolution near the camera), which
+     * applies only to `directional` lights with `num-cascades` greater than 1. Defaults to 0.5.
+     * @param value - The cascade distribution.
+     */
+    set cascadeDistribution(value: number) {
+        this._cascadeDistribution = value;
+        if (this.component) {
+            this.component.cascadeDistribution = value;
+        }
+    }
+
+    /**
+     * Gets the cascade distribution of the light, from 0 (linear split) to 1 (logarithmic split,
+     * concentrating shadow resolution near the camera), which applies only to `directional` lights
+     * with `num-cascades` greater than 1.
+     * @returns The cascade distribution.
+     */
+    get cascadeDistribution() {
+        return this._cascadeDistribution;
+    }
+
     /**
      * Sets the cast shadows flag of the light.
      * @param value - The cast shadows flag.
@@ -221,6 +279,27 @@ class LightComponentElement extends ComponentElement {
         return this._normalOffsetBias;
     }
 
+    /**
+     * Sets the number of shadow cascades of the light, an integer from 1 (no cascades) to 4, which
+     * applies only to `directional` lights. Defaults to 1.
+     * @param value - The number of shadow cascades.
+     */
+    set numCascades(value: number) {
+        this._numCascades = value;
+        if (this.component) {
+            this.component.numCascades = value;
+        }
+    }
+
+    /**
+     * Gets the number of shadow cascades of the light, an integer from 1 (no cascades) to 4, which
+     * applies only to `directional` lights.
+     * @returns The number of shadow cascades.
+     */
+    get numCascades() {
+        return this._numCascades;
+    }
+
     /**
      * Sets the outer cone angle of the light.
      * @param value - The outer cone angle.
@@ -512,11 +591,14 @@ class LightComponentElement extends ComponentElement {
     static get observedAttributes() {
         return [
             ...super.observedAttributes,
-            'color',
+            'cascade-blend',
+            'cascade-distribution',
             'cast-shadows',
-            'intensity',
+            'color',
             'inner-cone-angle',
+            'intensity',
             'normal-offset-bias',
+            'num-cascades',
             'outer-cone-angle',
             'penumbra-falloff',
             'penumbra-size',
@@ -538,12 +620,18 @@ class LightComponentElement extends ComponentElement {
         super.attributeChangedCallback(name, _oldValue, newValue);
 
         switch (name) {
-            case 'color':
-                this.color = parseColor(newValue, Color.WHITE, name);
+            case 'cascade-blend':
+                this.cascadeBlend = parseNumber(newValue, 0, name);
+                break;
+            case 'cascade-distribution':
+                this.cascadeDistribution = parseNumber(newValue, 0.5, name);
                 break;
             case 'cast-shadows':
                 this.castShadows = parseBool(newValue, false);
                 break;
+            case 'color':
+                this.color = parseColor(newValue, Color.WHITE, name);
+                break;
             case 'inner-cone-angle':
                 this.innerConeAngle = parseNumber(newValue, 40, name);
                 break;
@@ -551,7 +639,10 @@ class LightComponentElement extends ComponentElement {
                 this.intensity = parseNumber(newValue, 1, name);
                 break;
             case 'normal-offset-bias':
-                this.normalOffsetBias = parseNumber(newValue, 0.05, name);
+                this.normalOffsetBias = parseNumber(newValue, 0, name);
+                break;
+            case 'num-cascades':
+                this.numCascades = parseNumber(newValue, 1, name);
                 break;
             case 'outer-cone-angle':
                 this.outerConeAngle = parseNumber(newValue, 45, name);
@@ -566,20 +657,20 @@ class LightComponentElement extends ComponentElement {
                 this.range = parseNumber(newValue, 10, name);
                 break;
             case 'shadow-bias':
-                this.shadowBias = parseNumber(newValue, 0.2, name);
-                break;
-            case 'shadow-distance':
-                this.shadowDistance = parseNumber(newValue, 16, name);
+                this.shadowBias = parseNumber(newValue, 0.05, name);
                 break;
             case 'shadow-blocker-samples':
                 this.shadowBlockerSamples = parseNumber(newValue, 16, name);
                 break;
-            case 'shadow-resolution':
-                this.shadowResolution = parseNumber(newValue, 1024, name);
+            case 'shadow-distance':
+                this.shadowDistance = parseNumber(newValue, 40, name);
                 break;
             case 'shadow-intensity':
                 this.shadowIntensity = parseNumber(newValue, 1, name);
                 break;
+            case 'shadow-resolution':
+                this.shadowResolution = parseNumber(newValue, 1024, name);
+                break;
             case 'shadow-samples':
                 this.shadowSamples = parseNumber(newValue, 16, name);
                 break;
@@ -590,7 +681,7 @@ class LightComponentElement extends ComponentElement {
                 this.type = parseEnum(newValue, ['directional', 'omni', 'spot'], 'directional', name);
                 break;
             case 'vsm-bias':
-                this.vsmBias = parseNumber(newValue, 0.01, name);
+                this.vsmBias = parseNumber(newValue, 0.0025, name);
                 break;
             case 'vsm-blur-size':
                 this.vsmBlurSize = parseNumber(newValue, 11, name);

package/src/components/particle-system-component.ts

@@ -12,6 +12,10 @@ import { ComponentElement } from './component';
  *
  * Engine component: {@link ParticleSystemComponent} (`particlesystem`).
  *
+ * @elementSummary The `<pc-particle-system>` element emits particles from its entity, with
+ * attributes for the emitter's shape, rate, lifetime, textures and blending. Must be a child of a
+ * `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+ *
  * @category Components
  */
 class ParticleSystemComponentElement extends ComponentElement {

package/src/components/render-component.ts

@@ -17,6 +17,11 @@ import { ComponentElement } from './component';
  *
  * Engine component: {@link RenderComponent} (`render`).
  *
+ * @elementSummary The `<pc-render>` element renders one of the engine's built-in primitives at its
+ * entity — box, sphere, capsule, cone, cylinder or plane — shaded by the `<pc-material>` its
+ * `material` attribute names. For glTF content, use `<pc-model>` instead. Must be a child of a
+ * `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+ *
  * @category Components
  */
 class RenderComponentElement extends ComponentElement {

package/src/components/rigid-body-component.ts

@@ -13,6 +13,11 @@ import { ComponentElement } from './component';
  *
  * Engine component: {@link RigidBodyComponent} (`rigidbody`).
  *
+ * @elementSummary The `<pc-rigid-body>` element hands its entity to the physics simulation, with
+ * attributes for its type, mass, friction and restitution. It needs a sibling `<pc-collision>` for
+ * its shape, and `Ammo` loaded through `<pc-wasm>`. Must be a child of a `<pc-entity>`,
+ * `<pc-model>` or `<pc-node>`.
+ *
  * @category Components
  */
 class RigidBodyComponentElement extends ComponentElement {

package/src/components/screen-component.ts

@@ -22,6 +22,10 @@ const scaleModes = new Map<'none' | 'blend', string>([
  *
  * Engine component: {@link ScreenComponent} (`screen`).
  *
+ * @elementSummary The `<pc-screen>` element gives its entity a 2D space — in screen space or in the
+ * world — that a hierarchy of `<pc-element>` descendants lays out inside. Must be a child of a
+ * `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+ *
  * @category Components
  */
 class ScreenComponentElement extends ComponentElement {

package/src/components/script-component.ts

@@ -250,6 +250,9 @@ export type ScriptNameChangeEvent = {
  *
  * Engine component: {@link ScriptComponent} (`script`).
  *
+ * @elementSummary The `<pc-script>` element holds the `<pc-script-instance>` children that attach
+ * scripts to its entity. Must be a child of a `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+ *
  * @category Components
  */
 class ScriptComponentElement extends ComponentElement {

package/src/components/script-instance.ts

@@ -29,6 +29,10 @@ import { parseBool } from '../parse';
  * The element becomes ready once its script instance has been created by the parent
  * `<pc-script>` element.
  *
+ * @elementSummary The `<pc-script-instance>` element attaches one script class, named by `name`, to
+ * the entity of its parent `<pc-script>`. Its other attributes set script attributes of the same
+ * name, and `attributes` takes a JSON object instead. Must be a direct child of `<pc-script>`.
+ *
  * @fires {CustomEvent} scriptattributeschange - Fired when the script's attributes change. The
  * `detail` carries the new `attributes` object. Bubbles.
  * @fires {CustomEvent} scriptenablechange - Fired when the script's enabled state changes. The

package/src/components/scroll-view-component.ts

@@ -31,6 +31,10 @@ const visibilities = new Map<'always' | 'when-required', number>([
  *
  * Engine component: {@link ScrollViewComponent} (`scrollview`).
  *
+ * @elementSummary The `<pc-scroll-view>` element scrolls a larger content entity within a clipped
+ * viewport at its entity, optionally driven by the `<pc-scrollbar>` elements it references. Must be
+ * a child of a `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+ *
  * @category Components
  */
 class ScrollViewComponentElement extends ComponentElement {

package/src/components/scrollbar-component.ts

@@ -18,6 +18,10 @@ const orientations = new Map<'horizontal' | 'vertical', number>([
  *
  * Engine component: {@link ScrollbarComponent} (`scrollbar`).
  *
+ * @elementSummary The `<pc-scrollbar>` element gives its entity a draggable handle reporting a
+ * position from 0 to 1, which a `<pc-scroll-view>` references to scroll its content. Must be a
+ * child of a `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+ *
  * @category Components
  */
 class ScrollbarComponentElement extends ComponentElement {

package/src/components/sound-component.ts

@@ -12,6 +12,10 @@ import { ComponentElement } from './component';
  *
  * Engine component: {@link SoundComponent} (`sound`).
  *
+ * @elementSummary The `<pc-sound>` element holds the `<pc-sound-slot>` children that play sounds at
+ * its entity, along with the positional audio settings they share. Must be a child of a
+ * `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+ *
  * @category Components
  */
 class SoundComponentElement extends ComponentElement {

package/src/components/sound-slot.ts

@@ -10,6 +10,9 @@ import { SoundComponentElement } from './sound-component';
  * The SoundSlotElement interface provides properties and methods for manipulating
  * `<pc-sound-slot>` elements. The SoundSlotElement interface also inherits the properties and
  * methods of the {@link AsyncElement} interface.
+ *
+ * @elementSummary The `<pc-sound-slot>` element declares one named sound on its parent `<pc-sound>`
+ * — its asset, volume, pitch, looping and autoplay. Must be a direct child of `<pc-sound>`.
  */
 class SoundSlotElement extends AsyncElement {
     private _asset = '';

package/src/entity-base.ts

@@ -4,18 +4,29 @@ import type { AppElement } from './app';
 import { AsyncElement } from './async-element';
 
 /**
- * The attribute names of the inline `onpointer*` event handlers, shared by every element that
- * fronts an engine entity. Spread into `observedAttributes` by subclasses.
+ * The event types the containing `<pc-app>` synthesizes on entity-fronting elements via picking:
+ * the `pointer*` events, plus `click` — which concludes a primary-button press and release, and
+ * is delivered as a `PointerEvent` exactly as modern browsers deliver native clicks.
  * @internal
  */
-export const POINTER_ATTRIBUTES = [
-    'onpointerenter',
-    'onpointerleave',
-    'onpointerdown',
-    'onpointerup',
-    'onpointermove'
+export const SYNTHESIZED_EVENTS = [
+    'pointerenter',
+    'pointerleave',
+    'pointerdown',
+    'pointerup',
+    'pointermove',
+    'click'
 ] as const;
 
+const SYNTHESIZED_EVENT_SET: ReadonlySet<string> = new Set(SYNTHESIZED_EVENTS);
+
+/**
+ * The attribute names of the inline event handlers (`onpointerdown`, `onclick`, ...), shared by
+ * every element that fronts an engine entity. Spread into `observedAttributes` by subclasses.
+ * @internal
+ */
+export const EVENT_ATTRIBUTES = SYNTHESIZED_EVENTS.map((type) => `on${type}`);
+
 /**
  * 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
@@ -34,12 +45,13 @@ class EntityBaseElement extends AsyncElement {
     protected _appElement: AppElement | null = null;
 
     /**
-     * The pointer event listeners for the entity.
+     * The event listeners registered on the element, by type.
      */
     private _listeners: Record<string, EventListener[]> = {};
 
     /**
-     * The event types for which an inline `onpointer*` attribute is currently present.
+     * The event types for which an inline handler attribute (`onpointerdown`, `onclick`, ...)
+     * is currently present.
      */
     private _inlineHandlerTypes = new Set<string>();
 
@@ -75,10 +87,10 @@ class EntityBaseElement extends AsyncElement {
     }
 
     /**
-     * Tracks whether an inline `onpointer*` attribute is present. The browser itself compiles and
+     * Tracks whether an inline handler attribute is present. The browser itself compiles and
      * runs these attributes — they are standard `GlobalEventHandlers`, so setting one replaces
      * the previous handler and removing it removes the handler, exactly like `onclick` on any
-     * HTML element. But because they bypass {@link addEventListener}, the connect/disconnect
+     * HTML element. But because they bypass {@link EventTarget.addEventListener}, the connect/disconnect
      * bookkeeping that lets the application lazily attach its canvas pointer handlers must be
      * kept in sync here.
      *
@@ -105,7 +117,7 @@ class EntityBaseElement extends AsyncElement {
         }
         this._listeners[type].push(listener);
         super.addEventListener(type, listener, options);
-        if (type.startsWith('pointer')) {
+        if (SYNTHESIZED_EVENT_SET.has(type)) {
             this.dispatchEvent(new CustomEvent(`${type}:connect`, { bubbles: true }));
         }
     }
@@ -115,15 +127,15 @@ class EntityBaseElement extends AsyncElement {
             this._listeners[type] = this._listeners[type].filter((l) => l !== listener);
         }
         super.removeEventListener(type, listener, options);
-        if (type.startsWith('pointer')) {
+        if (SYNTHESIZED_EVENT_SET.has(type)) {
             this.dispatchEvent(new CustomEvent(`${type}:disconnect`, { bubbles: true }));
         }
     }
 
     /**
      * Whether the element has a listener for an event type, registered either with
-     * {@link addEventListener} or with the matching inline `onpointer*` attribute. Read by the
-     * containing `<pc-app>` element to gate pointer event synthesis.
+     * {@link EventTarget.addEventListener} or with the matching inline handler attribute. Read by the
+     * containing `<pc-app>` element to gate event synthesis.
      *
      * @param type - The event type.
      * @returns Whether a listener is registered.

package/src/entity-owner.ts

@@ -69,7 +69,7 @@ class EntityOwnerElement extends EntityBaseElement {
     private _tags: string[] = [];
 
     /**
-     * Whether the hierarchy has been built for this entity — set once {@link _buildHierarchy} has
+     * Whether the hierarchy has been built for this entity — set once `_buildHierarchy` has
      * parented it. Read by subclasses that gate work on the entity being in the scene graph.
      */
     protected _built = false;
@@ -170,7 +170,7 @@ class EntityOwnerElement extends EntityBaseElement {
     }
 
     /**
-     * Called by {@link _buildHierarchy} once the backing entity has been parented — exactly once
+     * Called by `_buildHierarchy` once the backing entity has been parented — exactly once
      * per build cycle. The default announces readiness, which is what a parented `<pc-entity>`
      * means; `<pc-model>` overrides it to start loading content instead, because its readiness
      * tracks the content settling rather than the host entering the scene graph.

package/src/entity.ts

@@ -1,6 +1,6 @@
 import { Vec3 } from 'playcanvas';
 
-import { POINTER_ATTRIBUTES } from './entity-base';
+import { EVENT_ATTRIBUTES } from './entity-base';
 import { buildDescendantEntities, EntityOwnerElement } from './entity-owner';
 import { parseBool, parseTags, parseVec3 } from './parse';
 
@@ -12,8 +12,13 @@ import { parseBool, parseTags, parseVec3 } from './parse';
  *
  * The pointer events below are dispatched by the containing `<pc-app>` element when the pointer
  * intersects this entity's geometry. They are only generated while the entity has a listener for
- * them, registered either with {@link addEventListener} or with the matching inline `onpointer*`
- * attribute.
+ * them, registered either with {@link EventTarget.addEventListener} or with the matching inline
+ * attribute (`onpointerdown`, `onclick`, ...).
+ *
+ * @elementSummary The `<pc-entity>` element creates an entity: a named, transformable node of the
+ * scene hierarchy, and the host for component elements such as `<pc-camera>`, `<pc-light>` and
+ * `<pc-render>`. Place it in the `<pc-scene>`, or nest it under another `<pc-entity>`, a
+ * `<pc-model>` or a `<pc-node>` to parent it there.
  *
  * @attribute {boolean} enabled - The enabled state of the entity.
  * @attribute {string} name - The name of the entity.
@@ -28,11 +33,17 @@ import { parseBool, parseTags, parseVec3 } from './parse';
  * entity.
  * @attribute {string} onpointerup - Script to run when a pointer button is released over the
  * entity.
+ * @attribute {string} onclick - Script to run when the entity is clicked: a primary pointer
+ * button pressed and then released over it.
  * @fires {PointerEvent} pointerenter - Fired when the pointer moves onto the entity.
  * @fires {PointerEvent} pointerleave - Fired when the pointer moves off the entity.
  * @fires {PointerEvent} pointermove - Fired when the pointer moves over the entity.
  * @fires {PointerEvent} pointerdown - Fired when a pointer button is pressed over the entity.
  * @fires {PointerEvent} pointerup - Fired when a pointer button is released over the entity.
+ * @fires {PointerEvent} click - Fired when a primary pointer button is pressed and then released
+ * over the entity. A press and release that picked different entities fires on their nearest
+ * common ancestor instead, as in the DOM. `detail` carries the click count, so a double click
+ * arrives as a click whose `detail` is 2.
  */
 class EntityElement extends EntityOwnerElement {
     connectedCallback() {
@@ -72,7 +83,7 @@ class EntityElement extends EntityOwnerElement {
     }
 
     static get observedAttributes() {
-        return ['enabled', 'name', 'position', 'rotation', 'scale', 'tags', ...POINTER_ATTRIBUTES];
+        return ['enabled', 'name', 'position', 'rotation', 'scale', 'tags', ...EVENT_ATTRIBUTES];
     }
 
     attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null) {
@@ -100,6 +111,7 @@ class EntityElement extends EntityOwnerElement {
             case 'onpointerdown':
             case 'onpointerup':
             case 'onpointermove':
+            case 'onclick':
                 this._updateInlineHandler(name, newValue);
                 break;
         }

package/src/index.ts

@@ -134,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