@pacem/pacem-3d 1.0.0-bessel → 1.0.0-binet

package/dist/browser/pacem-3d.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-3d v1.0.0-bessel (https://js.pacem.it)
+ * @pacem/pacem-3d v1.0.0-binet (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */
@@ -7,10 +7,12 @@
     'use strict';
 
     //namespace Pacem.Drawing3D {
+    /** Converts a `"x y z"` attribute string to/from a {@link Vector3D}. */
     const Point3DConverter = {
         convert: (attr) => pacemNumerical.Geometry.LinearAlgebra.Vector3D.parse(attr),
         convertBack: (prop) => `${prop.x || 0} ${prop.y || 0} ${prop.z || 0}`
     };
+    /** Converts a `"x y z"` (3 components) or `"n"` (single uniform component, broadcast to all 3 axes) attribute string to/from a {@link Vector3D}. Used e.g. for `scale`/`offset`. */
     const Point3DOrNumberConverter = {
         convert: (attr) => {
             const arr = pacemFoundation.parseAsNumericalArray(attr);
@@ -29,10 +31,12 @@
         },
         convertBack: (prop) => `${prop.x || 0} ${prop.y || 0} ${prop.z || 0}`
     };
+    /** Converts a `"x y z w"` attribute string to/from a {@link Quaternion}. Used e.g. for `rotate`. */
     const QuaternionConverter = {
         convert: (attr) => pacemNumerical.Geometry.LinearAlgebra.Quaternion.parse(attr),
         convertBack: (prop) => `${prop.x || 0} ${prop.y || 0} ${prop.z || 0} ${prop.w || 0}`
     };
+    /** Converts an attribute string to/from either a `boolean` (`"true"`/`"false"`) or a `number`. */
     const BooleanOrNumberConverter = {
         convert: (attr) => {
             if (attr === 'true')
@@ -44,7 +48,9 @@
         convertBack: (prop) => prop.toString()
     };
 
+    /** Middle segment shared by every custom element tag name in this package (e.g. `pacem-3d`, `pacem-3d-mesh`). */
     const TAG_MIDDLE_NAME = "3d";
+    /** Conversion factor from degrees to radians. */
     const DEG2RAD = Math.PI / 180;
 
     var __decorate$l = (undefined && undefined.__decorate) || function (decorators, target, key, desc) {
@@ -54,6 +60,12 @@
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components.Drawing3D {
+    /**
+     * `<pacem-3d>`: the root 3d stage element. Hosts the {@link RenderableElement} scene graph (groups, meshes, lights,
+     * cameras) declared as children or provided via {@link datasource}, delegates all actual scene-building/rendering/
+     * hit-testing to the pluggable {@link adapter} ({@link Pacem3DAdapterElement}), and dispatches pointer interaction
+     * events ({@link RenderableEvent}/{@link DragEvent}) for the items under the cursor.
+     */
     let Pacem3DElement = class Pacem3DElement extends pacemCore.Components.PacemItemsContainerElement {
         constructor() {
             super(...arguments);
@@ -118,9 +130,11 @@
         validate(item) {
             return item instanceof RenderableElement;
         }
+        /** @readonly Gets the DOM element the scene is mounted into. */
         get stage() {
             return this._container;
         }
+        /** @readonly Gets the technology-dependent native scene instance, as reported by the active {@link adapter}. */
         get scene() {
             return this.adapter && this.adapter.getScene(this);
         }
@@ -265,9 +279,11 @@
             super.disconnectedCallback();
         }
         #size;
+        /** @readonly Gets the current viewport size, as last reported by the internal resize observer. */
         get size() {
             return this.#size;
         }
+        /** Renders the whole scene through the active {@link adapter}, or just updates the given `item` if provided. */
         render(item, deepUpdate, now = performance.now()) {
             if (!pacemCore.Utils.isNull(item)) {
                 const adapter = this.adapter;
@@ -330,38 +346,49 @@
         else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
+    /** Type guard checking whether `object` implements the {@link Stage} contract. */
     function isStage(object) {
         return !pacemCore.Utils.isNull(object) && 'render' in object && typeof object['render'] === 'function';
     }
+    /** Type guard checking whether `object` implements the {@link Renderable} contract (i.e. it is attached to a valid {@link Stage}). */
     function isRenderable(object) {
         return isStage(object?.stage);
     }
+    /** Type guard checking whether `object` implements the {@link Ui3DObject} contract (i.e. it exposes a {@link Ui3DObject.transformMatrix}). */
     function isUi3DObject(object) {
         return 'transformMatrix' in object && isRenderable(object);
     }
+    /** Type guard checking whether `object` implements the {@link Camera} contract. */
     function isCamera(object) {
         return 'type' in object && 'up' in object && 'lookAt' in object && isRenderable(object);
     }
+    /** Type guard checking whether `object` is a {@link PerspectiveCamera}. */
     function isPerspectiveCamera(object) {
         return isCamera(object) && 'type' in object && object.type === 'perspective';
     }
+    /** Type guard checking whether `object` is an {@link OrthographicCamera}. */
     function isOrthographicCamera(object) {
         return isCamera(object) && 'type' in object && object.type === 'orthographic';
     }
+    /** Type guard checking whether `object` implements the {@link Light} contract. */
     function isLight(object) {
         return 'type' in object && (object.type === 'ambient' || object.type === 'omni' || object.type === 'direction' || object.type == 'spot') && isRenderable(object);
     }
+    /** Type guard checking whether `object` implements the {@link Mesh} contract. */
     function isMesh(object) {
         return 'geometry' in object && isUi3DObject(object);
     }
+    /** Type guard checking whether `object` implements the {@link NodeGeometry} contract. */
     function isGeometry(object) {
         return 'positions' in object && pacemCore.Utils.isArray(object.positions);
     }
+    /** Type guard checking whether `object` implements the {@link MeshGeometry} contract (a {@link NodeGeometry} with triangle indices/normals/UVs). */
     function isMeshGeometry(object) {
         return ('triangleIndices' in object && pacemCore.Utils.isArray(object.triangleIndices)
             || 'normals' in object && pacemCore.Utils.isArray(object.normals)
             || 'textureCoordinates' in object && pacemCore.Utils.isArray(object.textureCoordinates)) && isGeometry(object);
     }
+    /** Type guard checking whether `object` implements the {@link Group} contract. */
     function isGroup(object) {
         return 'childRenderables' in object && pacemCore.Utils.isArray(object['childRenderables']) && isUi3DObject(object);
     }
@@ -397,6 +424,7 @@
         const orthogonal = pacemNumerical.Geometry.LinearAlgebra.Vector3D.cross(vAB, vAC);
         return pacemNumerical.Geometry.LinearAlgebra.Vector3D.unit(orthogonal);
     }
+    /** Base class for the custom UI events dispatched by 3d elements/the stage, carrying the source pointer's projected {@link point} in 3d world space alongside the original DOM event. */
     class UI3DEvent extends pacemCore.CustomUIEvent {
         constructor(type, eventInit, originalEvent, point) {
             super(type, eventInit, originalEvent);
@@ -408,24 +436,36 @@
             return this.#point;
         }
     }
+    /** Event dispatched while a {@link Renderable} item is being dragged (`itemdragstart`/`itemdrag`/`itemdragend`-like events), carrying a {@link DragEventArgs} payload. */
     class DragEvent extends UI3DEvent {
     }
+    /** Event dispatched for pointer interactions (click/over/out/down/up) with a {@link Renderable} item, carrying the item itself as its `detail`. */
     class RenderableEvent extends UI3DEvent {
         constructor(type, args, originalEvent, p) {
             super(type, { detail: args, bubbles: true, cancelable: true }, originalEvent, p);
         }
     }
+    /** Identifies which aspect of a {@link Renderable} changed since the last render, so the adapter can update only the stale part of the underlying native object. */
     var StalePropertyFlag;
     (function (StalePropertyFlag) {
+        /** The object's {@link Renderable.position} changed. */
         StalePropertyFlag["Position"] = "position";
+        /** The object's {@link Ui3DObject.transformMatrix} (rotate/scale/offset) changed. */
         StalePropertyFlag["Transform"] = "transform";
+        /** The mesh/line {@link NodeGeometry} changed. */
         StalePropertyFlag["Geometry"] = "geometry";
+        /** The group's child collection changed. */
         StalePropertyFlag["Children"] = "children";
+        /** The mesh's {@link Material}/{@link Mesh.backMaterial} changed. */
         StalePropertyFlag["Material"] = "material";
+        /** A {@link Light}-specific property (color, intensity, target, ...) changed. */
         StalePropertyFlag["Light"] = "light";
+        /** A {@link Camera}-specific property (near, far, fov, frustum, ...) changed. */
         StalePropertyFlag["Camera"] = "camera";
+        /** The object's {@link Renderable.hide} visibility changed. */
         StalePropertyFlag["Visibility"] = "visibility";
     })(StalePropertyFlag || (StalePropertyFlag = {}));
+    /** Type guard checking whether `object` implements the {@link Interaction} contract. */
     function isInteraction(object) {
         return typeof object === 'object' && 'time' in object && typeof object['time'] === 'number';
     }
@@ -439,12 +479,20 @@
         GROUP_SELECTOR: pacemCore.P + '-' + TAG_MIDDLE_NAME + '-group',
         DEFAULT_COORDS: { x: 0, y: 0, z: 0 }
     };
+    /**
+     * Abstract base of every scene-graph custom element usable inside a {@link Pacem3DElement} stage (groups, meshes,
+     * native objects, lights, cameras). Implements {@link Renderable}, wires the element into the ancestor stage/parent
+     * chain, and tracks which aspects of the object are stale (via {@link StalePropertyFlag}) so the active
+     * {@link Pacem3DAdapterElement} can update only what changed on the next render.
+     */
     class RenderableElement extends pacemCore.Components.PacemCrossItemsContainerElement {
         constructor() {
             super(...arguments);
+            /** Gets or sets the element's position, in 3d world (or parent-local) space. */
             this.position = Constants.DEFAULT_COORDS;
             this.#staleFlags = [];
         }
+        /** When implemented in a derived class (e.g. {@link Pacem3DGroupElement}), determines whether `_` may be nested under this element. Denies any child by default. */
         validate(_) {
             // by default no children allowed (Group will except)
             return false;
@@ -453,9 +501,11 @@
             // override
             return this.parent || this.stage;
         }
+        /** @readonly Gets the ancestor {@link Pacem3DElement} stage this element belongs to. */
         get stage() {
             return this['_scene'] = this['_scene'] || pacemCore.CustomElementUtils.findAncestorOfType(this, Pacem3DElement);
         }
+        /** @readonly Gets the closest ancestor {@link RenderableElement} (e.g. the containing group), if any. */
         get parent() {
             return this['_drawableParent'] = this['_drawableParent'] || pacemCore.CustomElementUtils.findAncestor(this, i => i instanceof RenderableElement);
         }
@@ -479,6 +529,7 @@
             }
         }
         #staleFlags;
+        /** @readonly Gets the list of {@link StalePropertyFlag}s accumulated since the element was last rendered/updated by the adapter. */
         get flags() {
             return this.#staleFlags;
         }
@@ -502,6 +553,11 @@
     __decorate$k([
         pacemCore.Watch({ emit: false, converter: pacemCore.PropertyConverters.Boolean })
     ], RenderableElement.prototype, "inert", void 0);
+    /**
+     * Abstract base of every {@link RenderableElement} that also carries an affine 3d transform (rotate/scale/offset,
+     * combined into {@link transformMatrix}). Extended by {@link Pacem3DGroupElement}, {@link Pacem3DMeshElement} and
+     * {@link Pacem3DObjectElement}.
+     */
     class Ui3DElement extends RenderableElement {
         // #endregion
         propertyChangedCallback(name, old, val, first) {
@@ -573,12 +629,14 @@
     __decorate$k([
         pacemCore.Watch({ emit: false, converter: pacemCore.PropertyConverters.Number })
     ], Ui3DElement.prototype, "translateZ", void 0);
+    /** `<pacem-3d-group>`: a {@link Ui3DElement} container that groups child {@link RenderableElement}s (declarative or from {@link datasource}) so its own transform applies to all of them. */
     let Pacem3DGroupElement = class Pacem3DGroupElement extends Ui3DElement {
         validate(child) {
             // overrides default denial
             return child instanceof RenderableElement;
         }
         #children = [];
+        /** @readonly Gets the renderable children currently belonging to the group. */
         get childRenderables() {
             return this.#children;
         }
@@ -599,6 +657,7 @@
     Pacem3DGroupElement = __decorate$k([
         pacemCore.CustomElement({ tagName: Constants.GROUP_SELECTOR })
     ], Pacem3DGroupElement);
+    /** `<pacem-3d-mesh>`: a {@link Ui3DElement} that renders a {@link NodeGeometry} (mesh or line) with a front/back {@link Material}. */
     let Pacem3DMeshElement = class Pacem3DMeshElement extends Ui3DElement {
         propertyChangedCallback(name, old, val, first) {
             super.propertyChangedCallback(name, old, val, first);
@@ -625,6 +684,7 @@
     Pacem3DMeshElement = __decorate$k([
         pacemCore.CustomElement({ tagName: Constants.MESH_SELECTOR })
     ], Pacem3DMeshElement);
+    /** `<pacem-3d-object>`: a {@link Ui3DElement} that loads/embeds a pre-built 3d asset (`obj`, `fbx`, or a native scene-graph object) instead of an explicit {@link Pacem3DMeshElement} geometry. */
     let Pacem3DObjectElement = class Pacem3DObjectElement extends Ui3DElement {
         propertyChangedCallback(name, old, val, first) {
             super.propertyChangedCallback(name, old, val, first);
@@ -642,12 +702,17 @@
     Pacem3DObjectElement = __decorate$k([
         pacemCore.CustomElement({ tagName: Constants.OBJECT_SELECTOR })
     ], Pacem3DObjectElement);
+    /** `<pacem-3d-light>`: a {@link RenderableElement} light source (point/omni, spot or directional) illuminating the scene. */
     let Pacem3DLightElement = class Pacem3DLightElement extends RenderableElement {
         constructor() {
             super(...arguments);
+            /** Gets or sets the light intensity/brightness. */
             this.intensity = .85;
+            /** Gets or sets the point the light is aimed at (spotlight-specific). */
             this.target = Constants.DEFAULT_COORDS;
+            /** Gets or sets the light color. */
             this.color = '#fff';
+            /** Gets or sets the kind of light source. */
             this.type = 'omni';
         }
         propertyChangedCallback(name, old, val, first) {
@@ -677,12 +742,21 @@
     Pacem3DLightElement = __decorate$k([
         pacemCore.CustomElement({ tagName: Constants.LIGHT_SELECTOR })
     ], Pacem3DLightElement);
+    /**
+     * Abstract base of the camera custom elements ({@link Pacem3DPerspectiveCameraElement}, {@link Pacem3DOrthographicCameraElement})
+     * that can be added to a {@link Pacem3DElement} stage. Implements {@link Camera}, tracking the eye-to-target
+     * {@link boundingSphere} used e.g. by {@link Pacem3DAdapterElement.zoomFit}.
+     */
     class Pacem3DCameraElement extends RenderableElement {
         constructor() {
             super(...arguments);
+            /** Gets or sets the near clipping plane distance. */
             this.near = 0.1;
+            /** Gets or sets the far clipping plane distance. */
             this.far = 1000.0;
+            /** Gets or sets the up vector, in world coordinates. */
             this.up = pacemNumerical.Geometry.LinearAlgebra.Vector3D.j();
+            /** Gets or sets the target the camera looks at, in world coordinates. */
             this.lookAt = Constants.DEFAULT_COORDS;
         }
         #sphere;
@@ -694,6 +768,7 @@
             const currentValue = this.#sphere = { center, radius };
             this.dispatchEvent(new pacemCore.PropertyChangeEvent({ currentValue, propertyName: 'boundingSphere', oldValue }));
         }
+        /** @readonly Gets the sphere centered on {@link lookAt} with radius equal to the eye-to-target distance. */
         get boundingSphere() {
             return this.#sphere;
         }
@@ -723,15 +798,20 @@
     __decorate$k([
         pacemCore.Watch({ emit: false, converter: Point3DConverter })
     ], Pacem3DCameraElement.prototype, "lookAt", void 0);
+    /** `<pacem-3d-perspective-camera>`: a {@link Pacem3DCameraElement} that projects the scene through a perspective frustum (vanishing point), defined by {@link fov} and {@link aspect}. */
     let Pacem3DPerspectiveCameraElement = class Pacem3DPerspectiveCameraElement extends Pacem3DCameraElement {
         constructor() {
             super(...arguments);
+            /** Gets or sets the vertical field of view, in degrees. */
             this.fov = 45;
+            /** Gets or sets the viewport width/height ratio. */
             this.aspect = 1;
         }
+        /** @readonly Gets the camera discriminator: always `"perspective"`. */
         get type() {
             return "perspective";
         }
+        /** @readonly Gets the viewport width/height ratio (alias of {@link aspect}). */
         get aspectRatio() {
             return this.aspect;
         }
@@ -754,14 +834,20 @@
     Pacem3DPerspectiveCameraElement = __decorate$k([
         pacemCore.CustomElement({ tagName: Constants.PERSPECTIVE_CAMERA_SELECTOR })
     ], Pacem3DPerspectiveCameraElement);
+    /** `<pacem-3d-orthographic-camera>`: a {@link Pacem3DCameraElement} that projects the scene through a fixed, non-diminishing (parallel) frustum, defined by the {@link top}/{@link left}/{@link bottom}/{@link right} coordinates. */
     let Pacem3DOrthographicCameraElement = class Pacem3DOrthographicCameraElement extends Pacem3DCameraElement {
         constructor() {
             super(...arguments);
+            /** Gets or sets the top frustum coordinate (e.g. 1). */
             this.top = 1;
+            /** Gets or sets the left frustum coordinate (e.g. -1). */
             this.left = -1;
+            /** Gets or sets the bottom frustum coordinate (e.g. -1). */
             this.bottom = -1;
+            /** Gets or sets the right frustum coordinate (e.g. 1). */
             this.right = 1;
         }
+        /** @readonly Gets the camera discriminator: always `"orthographic"`. */
         get type() {
             return "orthographic";
         }
@@ -792,12 +878,19 @@
     Pacem3DOrthographicCameraElement = __decorate$k([
         pacemCore.CustomElement({ tagName: Constants.ORTHO_CAMERA_SELECTOR })
     ], Pacem3DOrthographicCameraElement);
+    /**
+     * Pluggable rendering-backend contract assignable to a {@link Pacem3DElement}'s `adapter` property. Concrete adapters
+     * ({@link Pacem3DThreeAdapterElement} for Three.js/WebGL, {@link Pacem3DWebgpuAdapterElement} for WebGPU) are
+     * responsible for initializing/disposing the underlying native scene and DOM surface, sizing it, translating the
+     * {@link RenderableElement} scene graph into native objects, hit-testing (raycasting) and producing snapshot images.
+     */
     class Pacem3DAdapterElement extends pacemCore.PacemEventTarget {
     }
 
     //namespace Pacem.Components.Drawing3D {
     /** @deprecated*/
     class Pacem3DDetector {
+        /** Probes the browser for WebGL support by attempting to create a rendering context, populating {@link info} and {@link supported}. */
         constructor() {
             this._detected = {
                 supported: false, info: {}
@@ -861,9 +954,11 @@
                 addLine('misc', 'Supported Extensions', ctx.getSupportedExtensions() || []);
             }
         }
+        /** @readonly Gets the detected WebGL capabilities/limits, grouped by section (`main`, `bits`, `shader`, `tex`, `misc`). */
         get info() {
             return this._detected.info;
         }
+        /** @readonly Gets whether a WebGL rendering context could be created on this browser/device. */
         get supported() {
             return this._detected.supported;
         }
@@ -876,6 +971,7 @@
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Drawing3D {
+    /** Identifies the shading model (and, correspondingly, the concrete `Material` shape) applied to a mesh's faces. */
     var KnownShader;
     (function (KnownShader) {
         KnownShader["Basic"] = "basic";
@@ -885,34 +981,49 @@
         KnownShader["Line"] = "line";
         KnownShader["Custom"] = "custom";
     })(KnownShader || (KnownShader = {}));
+    /** Type guard checking whether `obj` implements the {@link Material} contract. */
     function isMaterial(obj) {
         return /*'color' in obj &&*/ 'shader' in obj;
     }
+    /** Type guard checking whether `obj` implements the {@link BasicMaterial} contract. */
     function isBasicMaterial(obj) {
         return isMaterial(obj) && obj.shader === KnownShader.Basic;
     }
+    /** Type guard checking whether `obj` implements the {@link LineMaterial} contract. */
     function isLineMaterial(obj) {
         return isMaterial(obj) && obj.shader === KnownShader.Line;
     }
+    /** Type guard checking whether `obj` implements the {@link LambertMaterial} contract. */
     function isLambertMaterial(obj) {
         return isMaterial(obj) && obj.shader === KnownShader.Lambert;
     }
+    /** Type guard checking whether `obj` implements the {@link PhongMaterial} contract. */
     function isPhongMaterial(obj) {
         return isMaterial(obj) && obj.shader === KnownShader.Phong;
     }
+    /** Type guard checking whether `obj` implements the {@link StandardMaterial} contract. */
     function isStandardMaterial(obj) {
         return isMaterial(obj) && obj.shader === KnownShader.Standard;
     }
+    /** Type guard checking whether `obj` implements the {@link ShaderMaterial} contract. */
     function isShaderMaterial(obj) {
         return isMaterial(obj) && obj.shader === KnownShader.Custom;
     }
     //namespace Pacem.Components.Drawing3D {
+    /**
+     * Abstract base of the declarative material custom elements — {@link BasicMaterialElement}, {@link LambertMaterialElement},
+     * {@link LineMaterialElement}, {@link PhongMaterialElement} and {@link StandardMaterialElement} — that assemble a
+     * {@link Material} (with its `shader`-specific extra properties) out of shared and shader-specific watched attributes,
+     * ready to be assigned to a `Pacem3DMeshElement`'s `material`/`backMaterial` property.
+     */
     class MaterialElement extends pacemCore.PacemEventTarget {
+        /** @param shader The {@link KnownShader} this element's {@link createMaterial} produces. */
         constructor(shader) {
             super();
             this.#shader = shader;
         }
         #shader;
+        /** Gets the shading model this element produces materials for. */
         get shader() {
             return this.#shader;
         }
@@ -947,11 +1058,13 @@
             super.viewActivatedCallback();
             this.updateMaterial();
         }
+        /** Recomputes {@link material} via {@link createMaterial}, flagging it as {@link StalePropertyFlag.Material}. */
         updateMaterial() {
             this.createMaterial().then(m => {
                 this.material = pacemCore.Utils.extend(m, { flags: [StalePropertyFlag.Material] });
             });
         }
+        /** Builds the base {@link Material} out of the shared watched attributes (`opacity`, `wireframe`, `color`, `hide`, `map`); overridden by subclasses to add their shader-specific properties. */
         async createMaterial() {
             return {
                 opacity: this.opacity ?? 1.0,
@@ -991,6 +1104,7 @@
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components.Drawing3D {
+    /** `<pacem-3d-material-basic>`: produces a {@link BasicMaterial} (unlit shading model): rendered at flat color, unaffected by scene lighting. */
     let BasicMaterialElement = class BasicMaterialElement extends MaterialElement {
         constructor() {
             super(KnownShader.Basic);
@@ -1007,10 +1121,12 @@
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components.Drawing3D {
+    /** `<pacem-3d-material-lambert>`: produces a {@link LambertMaterial} (Lambertian shading model): matte, non-specular reflection of scene lighting, with no glossy highlights. */
     let LambertMaterialElement = class LambertMaterialElement extends MaterialElement {
         constructor() {
             super(KnownShader.Lambert);
         }
+        /** Builds the {@link LambertMaterial}, adding `emissiveColor`, `reflectivity` and `refractionRatio` to the base {@link Material}. */
         async createMaterial() {
             return pacemCore.Utils.extend({
                 emissiveColor: this.emissiveColor || '#000',
@@ -1051,6 +1167,7 @@
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components.Drawing3D {
+    /** `<pacem-3d-material-line>`: produces a {@link LineMaterial} for rendering {@link PacemLineElement} polylines (stroke width, joins, caps, dash pattern). */
     let LineMaterialElement = class LineMaterialElement extends MaterialElement {
         constructor() {
             super(KnownShader.Line);
@@ -1068,6 +1185,7 @@
                 }
             }
         }
+        /** Builds the {@link LineMaterial}, adding `lineWidth`, `lineJoin`, `lineCap` and `dashArray` to the base {@link Material}. */
         async createMaterial() {
             return pacemCore.Utils.extend({
                 lineWidth: this.lineWidth ?? 1,
@@ -1105,10 +1223,12 @@
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components.Drawing3D {
+    /** `<pacem-3d-material-phong>`: produces a {@link PhongMaterial} (Phong shading model): diffuse reflection plus a specular highlight of adjustable shininess. */
     let PhongMaterialElement = class PhongMaterialElement extends MaterialElement {
         constructor() {
             super(KnownShader.Phong);
         }
+        /** Builds the {@link PhongMaterial}, adding the diffuse (`emissiveColor`, `reflectivity`, `refractionRatio`) and specular (`specularColor`, `shininess`, `flatShading`) properties to the base {@link Material}. */
         async createMaterial() {
             return pacemCore.Utils.extend({
                 emissiveColor: this.emissiveColor || '#000',
@@ -1164,10 +1284,12 @@
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components.Drawing3D {
+    /** `<pacem-3d-material-standard>`: produces a {@link StandardMaterial} using a physically-based (metalness/roughness) shading model. */
     let StandardMaterialElement = class StandardMaterialElement extends MaterialElement {
         constructor() {
             super(KnownShader.Standard);
         }
+        /** Builds the {@link StandardMaterial}, adding `emissiveColor`, `refractionRatio`, `metalness`, `roughness` and `flatShading` to the base {@link Material}. */
         async createMaterial() {
             return pacemCore.Utils.extend({
                 emissiveColor: this.emissiveColor || '#000',
@@ -1218,6 +1340,12 @@
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components.Drawing3D {
+    /**
+     * Abstract base of the declarative geometric-primitive custom elements — {@link PacemBoxElement}, {@link PacemConeElement},
+     * {@link PacemCylinderElement}, {@link PacemLineElement}, {@link PacemPlaneElement}, {@link PacemSphereElement},
+     * {@link PacemTorusElement} and the {@link PolyhedronElement} family — that compute a {@link NodeGeometry} out of their
+     * own shape parameters, ready to be assigned to a `Pacem3DMeshElement`'s `geometry` property.
+     */
     class Pacem3DPrimitiveElement extends pacemCore.PacemEventTarget {
         viewActivatedCallback() {
             super.viewActivatedCallback();
@@ -1231,6 +1359,13 @@
     ], Pacem3DPrimitiveElement.prototype, "geometry", void 0);
 
     //namespace Pacem.Drawing3D {
+    /**
+     * Property decorator factory that turns the decorated field into an accessor backed by a private field, invoking
+     * `callback` with the property name and old/new values whenever it is set to a different value. Used by
+     * {@link NodeGeometry}/{@link LineGeometry}/{@link MeshGeometry} to flag themselves as dirty ({@link StalePropertyFlag.Geometry})
+     * whenever their vertex data changes.
+     * @param callback Invoked (with `this` bound to the decorated instance) on every effective change of the property.
+     */
     function NotifyChange(callback) {
         return (target, prop, descriptor) => {
             const backingField = `_${prop}_${pacemCore.Utils.uniqueCode()}_backingField`;
@@ -1265,10 +1400,15 @@
         else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
+    /**
+     * Abstract base for the concrete geometry classes ({@link LineGeometry}, {@link MeshGeometry}) that back a
+     * {@link Pacem3DMeshElement}'s `geometry` property, providing shared bounding-volume computation helpers.
+     */
     class NodeGeometry {
         constructor(positions = []) {
             this.positions = positions;
         }
+        /** Computes the centroid (average) of the given positions. */
         static barycenter(positions) {
             var bary = { x: 0, y: 0, z: 0 };
             if (!pacemCore.Utils.isNullOrEmpty(positions)) {
@@ -1286,6 +1426,7 @@
             }
             return bary;
         }
+        /** Computes the axis-aligned {@link Box3D} enclosing the given positions. */
         static boundingBox(positions) {
             const output = {
                 minX: +Infinity, minY: +Infinity, minZ: +Infinity,
@@ -1304,6 +1445,7 @@
             }
             return output;
         }
+        /** Marks the geometry as stale, flagging it with {@link StalePropertyFlag.Geometry} for the next render. */
         setAsDirty() {
             setSelfAsDirty.call(this);
         }
@@ -1312,27 +1454,32 @@
         const me = this;
         me.flags = [/* no further specifications, other than 'geometry' */ StalePropertyFlag.Geometry];
     }
+    /** A {@link NodeGeometry} rendered as a polyline through its {@link positions} (no faces/triangles). */
     class LineGeometry extends NodeGeometry {
     }
     __decorate$c([
         NotifyChange(setSelfAsDirty)
     ], LineGeometry.prototype, "positions", void 0);
+    /** A {@link MeshGeometry} implementation with lazily-computed {@link barycenter}/{@link boundingBox} and settable {@link boundingSphere}, used as the `geometry` of a {@link Pacem3DMeshElement}. */
     class MeshGeometry extends NodeGeometry {
         #boundingBox;
         #boundingSphere;
         #barycenter;
+        /** Gets or sets the centroid of {@link positions}; computed on first access if not explicitly set. */
         get barycenter() {
             return this.#barycenter ??= NodeGeometry.barycenter(this.positions);
         }
         set barycenter(point) {
             this.#barycenter = point;
         }
+        /** Gets or sets the axis-aligned bounding box; computed from {@link positions} on first access if not explicitly set. */
         get boundingBox() {
             return this.#boundingBox ??= NodeGeometry.boundingBox(this.positions);
         }
         set boundingBox(bbox) {
             this.#boundingBox = bbox;
         }
+        /** Gets or sets the bounding sphere. */
         get boundingSphere() {
             return this.#boundingSphere;
         }
@@ -1367,7 +1514,9 @@
     };
     var PacemBoxElement_1;
     //namespace Pacem.Components.Drawing3D {
+    /** `<pacem-3d-primitive-box>`: computes the {@link MeshGeometry} of a rectangular cuboid (box). */
     let PacemBoxElement = PacemBoxElement_1 = class PacemBoxElement extends Pacem3DPrimitiveElement {
+        /** Builds the {@link MeshGeometry} of a box with the given size and per-axis segment subdivisions (all default to `1`). */
         static createMeshGeometry(width, height, depth, widthSegments, heightSegments, depthSegments) {
             const w = width || 1, h = height || 1, d = depth || 1, sw = widthSegments || 1, sh = heightSegments || 1, sd = depthSegments || 1;
             const positions = [];
@@ -1541,6 +1690,7 @@
             //
             return geom;
         }
+        /** Computes the box geometry from the default (unset) shape parameters. */
         createDefaultGeometry() {
             return PacemBoxElement_1.createMeshGeometry();
         }
@@ -1588,7 +1738,9 @@
     };
     var PacemConeElement_1;
     //namespace Pacem.Components.Drawing3D {
+    /** `<pacem-3d-primitive-cone>`: computes the {@link MeshGeometry} of a cone (a circular base tapering to an apex point). */
     let PacemConeElement = PacemConeElement_1 = class PacemConeElement extends Pacem3DPrimitiveElement {
+        /** Builds the {@link MeshGeometry} of a cone with the given base radius, height, side count, lateral-surface segments and base-cap segments. */
         static createMeshGeometry(radius = 1, height = 1, sides = 18, heightSegments = 5, capSegments = 1) {
             const r = radius;
             const nodes = [], uv = [], indices = [];
@@ -1699,6 +1851,7 @@
             // TODO: barycenter, boundingBox, boundingSphere
             return geom;
         }
+        /** Computes the cone geometry from the default (unset) shape parameters. */
         createDefaultGeometry() {
             return PacemConeElement_1.createMeshGeometry();
         }
@@ -1742,7 +1895,9 @@
     };
     var PacemCylinderElement_1;
     //namespace Pacem.Components.Drawing3D {
+    /** `<pacem-3d-primitive-cylinder>`: computes the {@link MeshGeometry} of a cylinder (two parallel circular caps joined by a straight lateral surface). */
     let PacemCylinderElement = PacemCylinderElement_1 = class PacemCylinderElement extends Pacem3DPrimitiveElement {
+        /** Builds the {@link MeshGeometry} of a cylinder with the given radius, height, side count, lateral-surface segments and cap segments. */
         static createMeshGeometry(radius = 1, height = 1, sides = 18, heightSegments = 5, capSegments = 1) {
             const r = radius;
             const nodes = [], uv = [], indices = [];
@@ -1899,6 +2054,7 @@
             // TODO: barycenter, boundingBox, boundingSphere
             return geom;
         }
+        /** Computes the cylinder geometry from the default (unset) shape parameters. */
         createDefaultGeometry() {
             return PacemCylinderElement_1.createMeshGeometry();
         }
@@ -1943,10 +2099,13 @@
     var PacemLineElement_1;
     //namespace Pacem.Components.Drawing3D {
     const DEFAULT_LINE = [{ x: 0, y: 0, z: 0 }, { x: 0, y: 1, z: 0 }];
+    /** `<pacem-3d-primitive-line>`: computes the {@link LineGeometry} of a polyline connecting a sequence of points. */
     let PacemLineElement = PacemLineElement_1 = class PacemLineElement extends Pacem3DPrimitiveElement {
+        /** Builds the {@link LineGeometry} out of the given vertices (a single segment from `(0,0,0)` to `(0,1,0)` when omitted). */
         static createLineGeometry(positions) {
             return new LineGeometry(positions || DEFAULT_LINE);
         }
+        /** Computes the line geometry from the default (unset) vertex positions. */
         createDefaultGeometry() {
             return PacemLineElement_1.createLineGeometry();
         }
@@ -1974,7 +2133,9 @@
     };
     var PacemPlaneElement_1;
     //namespace Pacem.Components.Drawing3D {
+    /** `<pacem-3d-primitive-plane>`: computes the {@link MeshGeometry} of a flat rectangular surface lying on the xz plane. */
     let PacemPlaneElement = PacemPlaneElement_1 = class PacemPlaneElement extends Pacem3DPrimitiveElement {
+        /** Builds the {@link MeshGeometry} of a flat rectangle with the given width, length and per-axis segment subdivisions (defaulting to `1`x`1`, 4 segments each way). */
         static createMeshGeometry(width, length, widthSegments, lengthSegments) {
             width ||= 1.0;
             length ||= 1.0;
@@ -2019,6 +2180,7 @@
             // TODO: barycenter, boundingBox, boundingSphere
             return geom;
         }
+        /** Computes the plane geometry from the default (unset) shape parameters. */
         createDefaultGeometry() {
             return PacemPlaneElement_1.createMeshGeometry();
         }
@@ -2074,6 +2236,12 @@
         }
     };
     const Point3D = pacemNumerical.Geometry.LinearAlgebra.Vector3D;
+    /**
+     * Abstract base of the regular-polyhedron (Platonic solid) primitive custom elements — {@link PacemTetrahedronElement},
+     * {@link PacemOctahedronElement}, {@link PacemHexahedronElement}, {@link PacemIcosahedronElement} and
+     * {@link PacemDodecahedronElement} — each computing the {@link MeshGeometry} of a solid inscribed in a sphere of the
+     * given {@link radius}.
+     */
     class PolyhedronElement extends Pacem3DPrimitiveElement {
         propertyChangedCallback(name, old, val, first) {
             super.propertyChangedCallback(name, old, val, first);
@@ -2084,6 +2252,7 @@
         _assignMeshGeometry(radius) {
             this.geometry = this.createMeshGeometry(radius > .0 ? radius : 1.0);
         }
+        /** Computes the polyhedron geometry using a radius of `1` when {@link radius} hasn't been explicitly set. */
         createDefaultGeometry() {
             return this.createMeshGeometry(1.0);
         }
@@ -2092,7 +2261,9 @@
         pacemCore.Watch({ emit: false, converter: pacemCore.PropertyConverters.Number })
     ], PolyhedronElement.prototype, "radius", void 0);
     // #region Tetrahedron
+    /** `<pacem-3d-primitive-tetrahedron>`: computes the {@link MeshGeometry} of a regular tetrahedron (a Platonic solid with 4 triangular faces). */
     let PacemTetrahedronElement = PacemTetrahedronElement_1 = class PacemTetrahedronElement extends PolyhedronElement {
+        /** Builds the {@link MeshGeometry} of a tetrahedron inscribed in a sphere of the given radius (defaults to `1`). */
         static createMeshGeometry(radius) {
             radius ||= 1.0;
             const nodesCoordsString = "0 0.5774 -0.8165, 0 0.5774 0.8165, 0.8165 -0.5774 0, -0.8165 -0.5774 0";
@@ -2129,7 +2300,9 @@
     ], PacemTetrahedronElement);
     // #endregion
     // #region Octahedron
+    /** `<pacem-3d-primitive-octahedron>`: computes the {@link MeshGeometry} of a regular octahedron (a Platonic solid with 8 triangular faces). */
     let PacemOctahedronElement = PacemOctahedronElement_1 = class PacemOctahedronElement extends PolyhedronElement {
+        /** Builds the {@link MeshGeometry} of an octahedron inscribed in a sphere of the given radius (defaults to `1`). */
         static createMeshGeometry(radius) {
             radius ||= 1.0;
             // -------------------------------------------------------------------------------------------------
@@ -2168,7 +2341,9 @@
     ], PacemOctahedronElement);
     // #endregion
     // #region Hexahedron
+    /** `<pacem-3d-primitive-hexahedron>`: computes the {@link MeshGeometry} of a regular hexahedron (a Platonic solid with 6 square faces, i.e. a cube). */
     let PacemHexahedronElement = PacemHexahedronElement_1 = class PacemHexahedronElement extends PolyhedronElement {
+        /** Builds the {@link MeshGeometry} of a cube inscribed in a sphere of the given radius (defaults to `1`), as an equal-sided {@link PacemBoxElement}. */
         static createMeshGeometry(radius) {
             radius ||= 1.0;
             const inv_sqrt3 = 1.0 / Math.sqrt(3.0);
@@ -2186,7 +2361,9 @@
     ], PacemHexahedronElement);
     // #endregion
     // #region Icosahedron
+    /** `<pacem-3d-primitive-icosahedron>`: computes the {@link MeshGeometry} of a regular icosahedron (a Platonic solid with 20 triangular faces). */
     let PacemIcosahedronElement = PacemIcosahedronElement_1 = class PacemIcosahedronElement extends PolyhedronElement {
+        /** Builds the {@link MeshGeometry} of an icosahedron inscribed in a sphere of the given radius (defaults to `1`). */
         static createMeshGeometry(radius) {
             radius ||= 1.0;
             const nodesCoordsString = "0 0.850651 -0.525731, 0 0.850651 0.525731, 0.850651 0.525731 0, 0.525731 0 -0.850651, -0.525731 0 -0.850651, -0.850651 0.525731 0, -0.525731 0 0.850651, 0.525731 0 0.850651, 0.850651 -0.525731 0, 0 -0.850651 0.525731, 0 -0.850651 -0.525731, -0.850651 -0.525731 0";
@@ -2246,7 +2423,9 @@
     ], PacemIcosahedronElement);
     // #endregion
     // #region Dodecahedron
+    /** `<pacem-3d-primitive-dodecahedron>`: computes the {@link MeshGeometry} of a regular dodecahedron (a Platonic solid with 12 pentagonal faces). */
     let PacemDodecahedronElement = PacemDodecahedronElement_1 = class PacemDodecahedronElement extends PolyhedronElement {
+        /** Builds the {@link MeshGeometry} of a dodecahedron inscribed in a sphere of the given radius (defaults to `1`). */
         static createMeshGeometry(radius) {
             radius ||= 1.0;
             const n1 = Point3D.from(0.356822 * radius, 0.934172 * radius, 0 * radius);
@@ -2371,7 +2550,9 @@
     };
     var PacemSphereElement_1;
     //namespace Pacem.Components.Drawing3D {
+    /** `<pacem-3d-primitive-sphere>`: computes the {@link MeshGeometry} of a UV sphere. */
     let PacemSphereElement = PacemSphereElement_1 = class PacemSphereElement extends Pacem3DPrimitiveElement {
+        /** Builds the {@link MeshGeometry} of a sphere with the given radius (defaults to `1`) and tessellation (defaults to `8`). */
         static createMeshGeometry(radius = 1, segs = 8) {
             //
             const nodes = [];
@@ -2453,6 +2634,7 @@
             computeSharpVertexNormals(geom);
             return geom;
         }
+        /** Computes the sphere geometry from the default (unset) shape parameters. */
         createDefaultGeometry() {
             return PacemSphereElement_1.createMeshGeometry();
         }
@@ -2484,7 +2666,9 @@
     };
     var PacemTorusElement_1;
     //namespace Pacem.Components.Drawing3D {
+    /** `<pacem-3d-primitive-torus>`: computes the {@link MeshGeometry} of a torus (donut shape): a tube revolved around a central axis. */
     let PacemTorusElement = PacemTorusElement_1 = class PacemTorusElement extends Pacem3DPrimitiveElement {
+        /** Builds the {@link MeshGeometry} of a torus with the given outer/inner radii and ring/tube segment counts. */
         static createMeshGeometry(radius = 1, innerRadius = .25, segments = 24, sides = 12) {
             //
             const nodes = [];
@@ -2535,6 +2719,7 @@
             computeSharpVertexNormals(geom);
             return geom;
         }
+        /** Computes the torus geometry from the default (unset) shape parameters. */
         createDefaultGeometry() {
             return PacemTorusElement_1.createMeshGeometry();
         }
@@ -2582,21 +2767,29 @@
         const clipY = y / rect.height * -2 + 1;
         return { x: clipX, y: clipY };
     }
+    /** Shared helpers used by the concrete `pacem-3d` rendering-backend adapters (Three.js, WebGPU): type guards, buffer flattening, camera lookup and pointer-to-clip-space conversion. */
     class AdapterUtils {
+        /** Returns whether the given object is a {@link MeshGeometry} (has `positions` and `triangleIndices` arrays). */
         static isMeshGeometry(obj) {
             return 'positions' in obj && pacemCore.Utils.isArray(obj.positions)
                 && 'triangleIndices' in obj && pacemCore.Utils.isArray(obj.triangleIndices);
         }
+        /** Returns whether the given object is a {@link Vector3D} (has numeric `x`/`y`/`z`). */
         static isVector3D(obj) {
             return 'x' in obj && typeof obj.x === 'number'
                 && 'y' in obj && typeof obj.y === 'number'
                 && 'z' in obj && typeof obj.z === 'number';
         }
+        /** Returns whether the given object is an {@link Rgba} color (has numeric `r`/`g`/`b`). */
         static isRgba(obj) {
             return 'r' in obj && typeof obj.r === 'number'
                 && 'g' in obj && typeof obj.g === 'number'
                 && 'b' in obj && typeof obj.b === 'number';
         }
+        /**
+         * Flattens an array of 3D vectors, UV coordinates, or RGBA colors into a single flat number array (interleaved components), ready for a GPU buffer.
+         * @param array Array of {@link Vector3D}, {@link UVMap} entries, or {@link Rgba} values to flatten
+         */
         static flattenVectorArray(array) {
             const retval = [];
             for (let v of array) {
@@ -2612,6 +2805,10 @@
             }
             return retval;
         }
+        /**
+         * Returns the first non-hidden {@link Camera} among the given renderables, if any.
+         * @param items Renderable items to search
+         */
         static findCamera(items) {
             return (items || []).find(r => isCamera(r) && !r.hide);
         }
@@ -2861,6 +3058,12 @@
             throw new Error('The wait for THREE adapter initialization timed out.');
         }
     }
+    /**
+     * `<pacem-3d-three-adapter>`: {@link Pacem3DAdapterElement} rendering backend built on top of the
+     * {@link https://threejs.org/ | Three.js}/WebGL library (lazily loaded from a CDN on first use). Translates the
+     * {@link RenderableElement} scene graph into `THREE.Object3D`s, renders them with a `THREE.WebGLRenderer` and
+     * supports mouse-driven orbit controls via {@link orbit}.
+     */
     let Pacem3DThreeAdapterElement = class Pacem3DThreeAdapterElement extends Pacem3DAdapterElement {
         constructor() {
             super(...arguments);
@@ -3284,43 +3487,74 @@
     ], Pacem3DThreeAdapterElement);
 
     //namespace Pacem.Drawing3D.WebGPU {
+    /** Prefix prepended to every WebGPU resource label ({@link GPURenderPipeline}s, bind groups, layouts, shader modules, ...) created by this adapter, so they're easy to spot in browser devtools/profilers. */
     const LABEL_PREFIX = 'pacem-3d-';
+    /** Maximum value representable by a 32-bit unsigned integer (2^32 - 1). Used as the color-picking "no object" sentinel `u32` id. */
     const U32_MAX = 4_294_967_295;
     // #region vertex state
+    /** Vertex buffer slot (index into {@link GPUVertexState.buffers}) carrying mesh vertex positions (or the packed position+normal+uv buffer, see {@link PipelineOptions.packedVertices}). */
     const VERTEX_BUFFER_INDEX_MESH_POSITION = 0;
+    /** Vertex buffer slot (index into {@link GPUVertexState.buffers}) carrying mesh vertex normals, when vertices aren't packed. */
     const VERTEX_BUFFER_INDEX_MESH_NORMAL = 1;
+    /** Vertex buffer slot (index into {@link GPUVertexState.buffers}) carrying mesh UV coordinates, when vertices aren't packed. */
     const VERTEX_BUFFER_INDEX_MESH_UV = 2;
+    /** `@location` index of the surface normal in the generated WGSL `VertexOutput` struct. */
     const VERTEX_OUTPUT_LOCATION_NORMAL = 0;
+    /** `@location` index of the world-space vertex position in the generated WGSL `VertexOutput` struct. */
     const VERTEX_OUTPUT_LOCATION_VERTEX = 1;
+    /** `@location` index of the UV coordinate in the generated WGSL `VertexOutput` struct. */
     const VERTEX_OUTPUT_LOCATION_UV = 2;
+    /** `@location` index of the vertex/triangle index in the generated WGSL `VertexOutput` struct. */
     const VERTEX_OUTPUT_LOCATION_INDEX = 3;
+    /** `@location` index of the picking ray data in the generated WGSL `VertexOutput` struct. */
     const VERTEX_OUTPUT_LOCATION_RAY = 4;
+    /** `@location` index of the instance index in the generated WGSL `VertexOutput` struct. */
     const VERTEX_OUTPUT_LOCATION_INSTANCE = 5;
+    /** `@group` index of the world/normal transform uniform bind group. */
     const UNIFORM_GROUP_INDEX_TRANSFORM = 1;
+    /** `@group` index of the camera view/projection uniform bind group. */
     const UNIFORM_GROUP_INDEX_CAMERA = 0;
+    /** `@group` index of the pointer/interaction uniform bind group. Deliberately aliased to {@link UNIFORM_GROUP_INDEX_CAMERA} so interaction data shares the camera's binding group. */
     const UNIFORM_GROUP_INDEX_INTERACTION = UNIFORM_GROUP_INDEX_CAMERA; // put it in camera same binding group
+    /** `@group` index of the line-geometry storage bind group (positions + line properties). */
     const STORAGE_GROUP_INDEX_LINE = 2;
+    /** `@group` index of the color-picking (object-id) uniform bind group. */
     const UNIFORM_GROUP_INDEX_COLORPICKING = 2;
+    /** `@binding` index of the world/normal transform uniform, within {@link UNIFORM_GROUP_INDEX_TRANSFORM}. */
     const UNIFORM_BINDING_INDEX_TRANSFORM = 0;
+    /** `@binding` index of the camera view/projection uniform, within {@link UNIFORM_GROUP_INDEX_CAMERA}. */
     const UNIFORM_BINDING_INDEX_CAMERA = 0;
+    /** `@binding` index of the pointer/interaction uniform, within {@link UNIFORM_GROUP_INDEX_INTERACTION}. */
     const UNIFORM_BINDING_INDEX_INTERACTION = 1;
     // #endregion
     // #region fragment state
+    /** `@group` index of the material (storage buffer + optional texture/sampler) bind group. */
     const MATERIAL_GROUP_INDEX = 2;
+    /** `@group` index of the per-light uniform bind group, immediately following {@link MATERIAL_GROUP_INDEX}. */
     const UNIFORM_GROUP_INDEX_LIGHTING = MATERIAL_GROUP_INDEX + 1;
+    /** `@binding` index of the material storage buffer, within {@link MATERIAL_GROUP_INDEX}. */
     const STORAGE_MATERIAL_INDEX = 0;
+    /** `@binding` index of the material's texture sampler, within {@link MATERIAL_GROUP_INDEX}. */
     const SAMPLER_BINDING_INDEX = 1;
+    /** `@binding` index of the material's texture, within {@link MATERIAL_GROUP_INDEX}. */
     const TEXTURE_BINDING_INDEX = 2;
+    /** WGSL identifier used to reference the running vertex/fragment color in generated shader fragments (spliced in and out by texture/lighting stages). */
     const VERTEX_COLOR_REFERENCE = 'color';
+    /** WGSL identifier used to reference the accumulated ambient-light contribution in generated fragment shader code. */
     const AMBIENT_COLOR_REFERENCE = 'ambient';
+    /** WGSL identifier used to reference the accumulated (directional/omni) lighting contribution in generated fragment shader code. */
     const LIGHTING_COLOR_REFERENCE = 'lighting';
     // #endregion
     // #region WGSL
+    /** Name of the WGSL struct describing per-vertex input attributes, used by generated vertex shader code. */
     const WGSL_VERTEXINPUT_STRUCT_NAME = 'VertexInput';
+    /** Name of the WGSL struct describing vertex-stage output / fragment-stage input, used by generated vertex and fragment shader code. */
     const WGSL_VERTEXOUTPUT_STRUCT_NAME = 'VertexOutput';
+    /** Name of the WGSL struct describing the pointer/interaction uniform data, used by generated shader code. */
     const WGSL_INTERACTIONDATA_STRUCT_NAME = 'InteractionData';
     // #endregion
     // Kinda polyfill for WebGPU constants, as TypeScript 6.0 does include WebGPU types but does NOT include these constants for magic numbers:
+    /** Polyfill for the WebGPU `GPUBufferUsage` bitflags (`lib.dom` declares the `GPUBufferUsageFlags` type but not these numeric flag values). Combine with `|` when creating a {@link GPUBuffer}, e.g. `GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST`. */
     var GPUBufferUsage;
     (function (GPUBufferUsage) {
         GPUBufferUsage[GPUBufferUsage["COPY_SRC"] = 4] = "COPY_SRC";
@@ -3334,6 +3568,7 @@
         GPUBufferUsage[GPUBufferUsage["UNIFORM"] = 64] = "UNIFORM";
         GPUBufferUsage[GPUBufferUsage["VERTEX"] = 32] = "VERTEX";
     })(GPUBufferUsage || (GPUBufferUsage = {}));
+    /** Polyfill for the WebGPU `GPUTextureUsage` bitflags (`lib.dom` declares the `GPUTextureUsageFlags` type but not these numeric flag values). Combine with `|` when creating a {@link GPUTexture}. */
     var GPUTextureUsage;
     (function (GPUTextureUsage) {
         GPUTextureUsage[GPUTextureUsage["COPY_SRC"] = 1] = "COPY_SRC";
@@ -3342,18 +3577,21 @@
         GPUTextureUsage[GPUTextureUsage["STORAGE_BINDING"] = 8] = "STORAGE_BINDING";
         GPUTextureUsage[GPUTextureUsage["TEXTURE_BINDING"] = 4] = "TEXTURE_BINDING";
     })(GPUTextureUsage || (GPUTextureUsage = {}));
+    /** Polyfill for the WebGPU `GPUShaderStage` bitflags (`lib.dom` declares the `GPUShaderStageFlags` type but not these numeric flag values). Combine with `|` in {@link GPUBindGroupLayoutEntry.visibility}, e.g. `GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT`. */
     var GPUShaderStage;
     (function (GPUShaderStage) {
         GPUShaderStage[GPUShaderStage["VERTEX"] = 1] = "VERTEX";
         GPUShaderStage[GPUShaderStage["FRAGMENT"] = 2] = "FRAGMENT";
         GPUShaderStage[GPUShaderStage["COMPUTE"] = 4] = "COMPUTE";
     })(GPUShaderStage || (GPUShaderStage = {}));
+    /** Polyfill for the WebGPU `GPUMapMode` flags (`lib.dom` declares the type but not these numeric values). Used with {@link GPUBuffer.mapAsync}. */
     var GPUMapMode;
     (function (GPUMapMode) {
         GPUMapMode[GPUMapMode["READ"] = 1] = "READ";
         GPUMapMode[GPUMapMode["WRITE"] = 2] = "WRITE";
     })(GPUMapMode || (GPUMapMode = {}));
 
+    /** Categorizes a bind group by the role of the resources it carries (mesh transforms, camera, texture, light, interaction data), used to look up {@link BindGroupDefinition}s via {@link WGSL.bindings}. */
     var WGSLBindingType;
     (function (WGSLBindingType) {
         WGSLBindingType["Mesh"] = "mesh";
@@ -3364,7 +3602,20 @@
     })(WGSLBindingType || (WGSLBindingType = {}));
 
     //namespace Pacem.Drawing3D.WebGPU {
+    /**
+     * Low-level factory for typed {@link GPUBuffer}s (vertex, uniform, storage, index) used throughout the WebGPU backend
+     * to upload CPU-side geometry/material/uniform data to the GPU. Vertex and index buffers are populated immediately
+     * (via `mappedAtCreation`); uniform and storage buffers are allocated empty, sized to `data`, and are expected to be
+     * populated later via {@link GPUQueue.writeBuffer} (see {@link Buffer}/`abstractions.ts` and the `fresh`-tracking
+     * buffer accessors in `renderablebuffer.ts`).
+     */
     class Buffers {
+        /**
+         * Creates a {@link GPUBuffer} usable as a vertex buffer (`VERTEX | COPY_DST`), writing `data` into it immediately.
+         * @param device The {@link GPUDevice} to allocate the buffer on.
+         * @param data Vertex attribute data (e.g. flattened positions/normals/uv coordinates).
+         * @param label Optional debug label.
+         */
         static create(device, data, label = '') {
             const buffer = device.createBuffer({
                 size: data.byteLength, label,
@@ -3387,6 +3638,12 @@
                 usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
             });
         }
+        /**
+         * Creates a {@link GPUBuffer} usable as an index buffer (`INDEX | COPY_DST`), writing `data` into it immediately.
+         * @param device The {@link GPUDevice} to allocate the buffer on.
+         * @param data 16-bit vertex indices.
+         * @param label Optional debug label.
+         */
         static createIndexed(device, data, label = '') {
             const buffer = device.createBuffer({
                 size: data.byteLength, label,
@@ -3398,6 +3655,10 @@
             return buffer;
         }
     }
+    /**
+     * Helpers to build {@link GPUVertexBufferLayout}s describing how a vertex buffer's contents map to shader `@location`
+     * inputs, for use in a {@link GPURenderPipelineDescriptor.vertex} state.
+     */
     class BufferLayouts {
         static createVertex(shaderLocationStart = 0, size = 3, ...sizes) {
             const attributes = [];
@@ -3419,6 +3680,7 @@
         }
     }
 
+    /** Fallback options used by {@link getBasicMaterialFragmentWgsl}: mirrors the `VERTEX_OUTPUT_LOCATION_*` layout produced by `mesh-vertex.ts` and reads the diffuse color from {@link MATERIAL_GROUP_INDEX}/{@link STORAGE_MATERIAL_INDEX}. */
     const DefaultBasicMaterialFragmentOptions = {
         outputNormalLocation: VERTEX_OUTPUT_LOCATION_NORMAL,
         outputVertexLocation: VERTEX_OUTPUT_LOCATION_VERTEX,
@@ -3429,9 +3691,16 @@
         storageMaterialGroupIndex: MATERIAL_GROUP_INDEX,
         storageMaterialBindingIndex: STORAGE_MATERIAL_INDEX,
     };
+    /** Joins a {@link WGSLFragmentExtra} string array (`definitions`/`bindings`) with CRLF newlines, or returns an empty string when omitted. */
     function adaptWGSLStringArray$1(array = []) {
         return array.join('\r\n');
     }
+    /**
+     * Turns a {@link WGSLFragmentExtra.modifiers} array into a block of WGSL statements to inline into `main`. Entries
+     * already ending with `;` are emitted verbatim; bare expressions are wrapped into `${VERTEX_COLOR_REFERENCE} = <expr>;`
+     * so lighting/texture snippets (see {@link ambientLight}/{@link directionalLight}/{@link omniLight}/{@link textureMap})
+     * can either replace or contribute to the running `color`/`ambient`/`lighting` accumulators.
+     */
     function adaptWGSLModifierStringArray$1(array = []) {
         let output = '';
         for (let modifier of array) {
@@ -3445,6 +3714,21 @@
         }
         return output;
     }
+    /**
+     * Composes the fragment shader for the "basic" (unlit-by-default) material: it reads a flat `diffuseColor` from a
+     * storage buffer, then lets `extensions.modifiers` (lighting/texture snippets) accumulate into the `color`,
+     * `ambient` and `lighting` WGSL variables ({@link VERTEX_COLOR_REFERENCE}/{@link AMBIENT_COLOR_REFERENCE}/{@link LIGHTING_COLOR_REFERENCE}).
+     * If nothing wrote a `lighting` color (alpha stays `0`), it is treated as fully lit (`white`) so the material
+     * renders unshaded when no light snippet is attached; the final output is `color * lighting + ambient`.
+     *
+     * Splices `extensions.definitions`/`extensions.bindings`/`extensions.modifiers` (see {@link WGSLFragmentExtra}) into
+     * the `// definitions`, `// bindings` and body sections of the generated source, alongside the fixed
+     * `diffuseColor` storage binding and the `@fragment fn main` signature matching `mesh-vertex.ts`'s `VertexOutput`.
+     *
+     * @param extensions Extra WGSL `definitions`/`bindings`/`modifiers` to merge in (e.g. lighting/texture contributions).
+     * @param options Location/binding overrides; defaults to {@link DefaultBasicMaterialFragmentOptions}, matching the vertex-stage outputs produced by `mesh-vertex.ts`.
+     * @returns Complete WGSL fragment-shader source with a single `@fragment fn main` entry point returning `@location(0) vec4f`.
+     */
     function getBasicMaterialFragmentWgsl(extensions = {}, options = DefaultBasicMaterialFragmentOptions) {
         const opts = pacemCore.Utils.extend({}, DefaultBasicMaterialFragmentOptions, options);
         const definitions = adaptWGSLStringArray$1(extensions.definitions), bindings = adaptWGSLStringArray$1(extensions.bindings), modifiers = adaptWGSLModifierStringArray$1(extensions.modifiers);
@@ -3481,15 +3765,22 @@ const white = vec4f(1,1,1,1);
 }`;
     }
 
+    /** Fallback options used by {@link getLineMaterialFragmentWgsl}: reads instance/vertex index from locations 0/1 (matching `line-vertex.ts`'s `VertexOutput`) and the color storage buffer at {@link STORAGE_GROUP_INDEX_LINE}` + 1`/{@link STORAGE_MATERIAL_INDEX}. */
     const DefaultLineMaterialFragmentOptions = {
         outputInstanceIndexLocation: 0,
         outputVertexIndexLocation: 1,
         storageMaterialGroupIndex: STORAGE_GROUP_INDEX_LINE + 1,
         storageMaterialBindingIndex: STORAGE_MATERIAL_INDEX,
     };
+    /** Joins a {@link WGSLFragmentExtra} string array (`definitions`/`bindings`) with CRLF newlines, or returns an empty string when omitted. */
     function adaptWGSLStringArray(array = []) {
         return array.join('\r\n');
     }
+    /**
+     * Turns a {@link WGSLFragmentExtra.modifiers} array into a block of WGSL statements to inline into `main`. Entries
+     * already ending with `;` are emitted verbatim (assumed to be full statements); bare expressions are wrapped into
+     * `output = <expr>;` so each modifier can either replace or contribute to the fragment's `output` color variable.
+     */
     function adaptWGSLModifierStringArray(array = []) {
         let output = '';
         for (let modifier of array) {
@@ -3503,6 +3794,20 @@ const white = vec4f(1,1,1,1);
         }
         return output;
     }
+    /**
+     * Composes the fragment shader for line/polyline rendering: it looks up the current vertex's color from a
+     * per-vertex `vertexColors` storage buffer (indexed modulo its length via `getVertexColor`, so a shorter palette
+     * cycles/repeats across a longer line) and returns it as `@location(0) vec4f`, honoring any `extensions.modifiers`
+     * applied afterwards (e.g. dashing, fading).
+     *
+     * Splices `extensions.definitions`/`extensions.bindings`/`extensions.modifiers` (see {@link WGSLFragmentExtra},
+     * typically produced by the light snippets in this folder) into the `// definitions`, `// bindings` and body
+     * sections of the generated source, in addition to the fixed `vertexColors` storage binding.
+     *
+     * @param extensions Extra WGSL `definitions`/`bindings`/`modifiers` to merge in (e.g. lighting contributions).
+     * @param options Binding/location overrides; defaults to {@link DefaultLineMaterialFragmentOptions}, matching the vertex-stage outputs produced by `line-vertex.ts`.
+     * @returns Complete WGSL fragment-shader source with a single `@fragment fn main` entry point.
+     */
     function getLineMaterialFragmentWgsl(extensions = {}, options = DefaultLineMaterialFragmentOptions) {
         const opts = pacemCore.Utils.extend({}, DefaultLineMaterialFragmentOptions, options);
         const definitions = adaptWGSLStringArray(extensions.definitions), bindings = adaptWGSLStringArray(extensions.bindings), modifiers = adaptWGSLModifierStringArray(extensions.modifiers);
@@ -3534,7 +3839,18 @@ fn getVertexColor(index: u32) -> vec4f {
     }
 
     //namespace Pacem.Drawing3D.WebGPU {
+    /**
+     * Factory that converts a scene-facing {@link Material3D} (`../../materials/material.ts`) into its WebGPU-side
+     * counterpart ({@link Material}, `abstractions.ts`): a {@link BasicMaterial} or {@link LineMaterial} wrapping the GPU
+     * buffer/texture/WGSL-fragment logic consumed when building render pipelines (see `pipelinefactory.ts`).
+     */
     class Materials {
+        /**
+         * Wraps `material` in the {@link Material} implementation matching its `shader`.
+         * @param material The scene material to wrap.
+         * @returns A {@link BasicMaterial} or {@link LineMaterial}, depending on `material.shader`.
+         * @throws {TypeError} If `material.shader` isn't one of the supported {@link KnownShader} values.
+         */
         static create(material) {
             if (isBasicMaterial(material)) {
                 return new BasicMaterial(material);
@@ -3576,6 +3892,11 @@ fn getVertexColor(index: u32) -> vec4f {
             return retval;
         }
     }
+    /**
+     * WebGPU-side counterpart of a {@link BasicMaterial3D}: supplies the diffuse-color storage buffer (inherited from
+     * {@link MaterialBase.buffer}) and, when the material has a `texture`, allocates the backing {@link GPUTexture}
+     * (pixel data is copied in later by the mesh pipeline's material bind-group setup, see `pipelinefactory.ts`).
+     */
     class BasicMaterial extends MaterialBase {
         get shader() {
             return KnownShader.Basic;
@@ -3586,6 +3907,10 @@ fn getVertexColor(index: u32) -> vec4f {
                 throw new TypeError("Basic material expected.");
             }
         }
+        /**
+         * Allocates the (uninitialized) {@link GPUTexture} for the material's `texture`, if any.
+         * @param key Must be `'texture'`; any other {@link MaterialKey} (or a material without a `texture`) yields `null`.
+         */
         texture({ device }, key = 'texture') {
             const material = this.material;
             if (key === 'texture' && !pacemCore.Utils.isNull(material.texture)) {
@@ -3600,8 +3925,14 @@ fn getVertexColor(index: u32) -> vec4f {
             return null;
         }
         // TODO: put it in the material instance/interface
+        /** Basic-material fragment shader WGSL source generator; see `wgsl/basic-material-fragment.ts`. */
         static { this.fragment = getBasicMaterialFragmentWgsl; }
     }
+    /**
+     * WebGPU-side counterpart of a {@link LineMaterial3D}: supplies the diffuse-color storage buffer (inherited from
+     * {@link MaterialBase.buffer}) plus a dedicated `'line'` uniform buffer holding the canvas size and half line-width,
+     * consumed by the line vertex shader (`wgsl/line-vertex.ts`).
+     */
     class LineMaterial extends MaterialBase {
         get shader() {
             return KnownShader.Line;
@@ -3612,6 +3943,12 @@ fn getVertexColor(index: u32) -> vec4f {
                 throw new TypeError("Line material expected.");
             }
         }
+        /**
+         * Returns the `'line'` uniform buffer (canvas width/height and half line-width) for `key === 'line'`; otherwise
+         * defers to the inherited diffuse-color buffer.
+         * @param ctx WebGPU context supplying the device and canvas.
+         * @param key Which buffer to build; only `'line'` is handled specially.
+         */
         buffer(ctx, key) {
             switch (key) {
                 case 'line':
@@ -3623,18 +3960,38 @@ fn getVertexColor(index: u32) -> vec4f {
                     return super.buffer(ctx);
             }
         }
+        /** Lines have no texture support; always returns `null`. */
         texture(_) {
             return null;
         }
+        /** Line-material fragment shader WGSL source generator; see `wgsl/line-material-fragment.ts`. */
         static { this.fragment = getLineMaterialFragmentWgsl; }
     }
 
     //namespace Pacem.Drawing3D.WebGPU {
+    /** Placeholder identifiers (`input`, `data`) fed to a {@link VertexInputModifierDelegate}/{@link VertexOutputModifierDelegate} callback when {@link extractMeshVertexModifierFunctionComponents} needs to materialize its WGSL source before parsing it. */
     const defaultVertexGeometryModifierArgs = ['input', 'data'];
     //const defaultVertexGeometryModifier: VertexInputModifierDelegate = (...defaultVertexGeometryModifierArgs) => {
     //    const [inputRef, dataRef] = defaultVertexGeometryModifierArgs;
     //    return `fn echo(${inputRef}: ${WGSL_VERTEXINPUT_STRUCT_NAME}, ${dataRef}: ${WGSL_INTERACTIONDATA_STRUCT_NAME}) -> ${WGSL_VERTEXINPUT_STRUCT_NAME} { return ${inputRef}; }`;
     //};
+    /**
+     * Parses a user-supplied vertex-stage modifier (see {@link VertexInputModifierDelegate}/{@link VertexOutputModifierDelegate},
+     * consumed by `mesh-vertex.ts`'s `getMeshVertexWgsl`) into its WGSL function name, parameter names and body, so the
+     * caller can inline it as a standalone `fn` definition and reference it by name from the generated vertex shader.
+     *
+     * If `wgsl` is a callback rather than a raw string, it is first invoked with the placeholder argument names in
+     * {@link defaultVertexGeometryModifierArgs} to obtain its WGSL source. The resulting source is then matched against
+     * `fn <name>(<arg0>: <ArgType>, <arg1>: InteractionData) -> <ArgType> { <body> }`, where `<ArgType>` must be either
+     * `VertexInput` ({@link WGSL_VERTEXINPUT_STRUCT_NAME}) or `VertexOutput` ({@link WGSL_VERTEXOUTPUT_STRUCT_NAME}) and
+     * must match on both sides of the signature (an input modifier both takes and returns `VertexInput`, an output
+     * modifier both takes and returns `VertexOutput`), with the second parameter always typed
+     * {@link WGSL_INTERACTIONDATA_STRUCT_NAME}.
+     *
+     * @param wgsl Raw WGSL function source, or a delegate that produces it when called with `(inputRef, interactionDataRef)`.
+     * @returns The parsed function's `name`, its two parameter `args` (in order), and its `body` (the statements between the braces, trimmed).
+     * @throws If the source doesn't match the required single-function signature, or if its parameter types are inconsistent with the modifier contract.
+     */
     function extractMeshVertexModifierFunctionComponents(wgsl) {
         if (typeof wgsl !== 'string') {
             wgsl = wgsl(...defaultVertexGeometryModifierArgs);
@@ -3661,6 +4018,7 @@ fn getVertexColor(index: u32) -> vec4f {
         }
     }
 
+    /** Fallback options used by {@link getMeshVertexWgsl}: the standard `VERTEX_OUTPUT_LOCATION_*`/`VERTEX_BUFFER_INDEX_MESH_*` layout and the transform/camera/interaction uniform coordinates shared across mesh pipelines. */
     const DefaultMeshVertexOptions = {
         outputNormalLocation: VERTEX_OUTPUT_LOCATION_NORMAL,
         outputVertexLocation: VERTEX_OUTPUT_LOCATION_VERTEX,
@@ -3678,6 +4036,23 @@ fn getVertexColor(index: u32) -> vec4f {
         uniformInteractionBindingIndex: UNIFORM_BINDING_INDEX_INTERACTION,
         uniformInteractionGroupIndex: UNIFORM_GROUP_INDEX_INTERACTION,
     };
+    /**
+     * Composes the standard vertex shader used to draw mesh geometry: it transforms each vertex position by the
+     * world/view/projection matrices, transforms the normal by the (precomputed) normal matrix, passes UVs through
+     * unchanged, and computes an eye-to-vertex `ray` (normalized `worldPosition - camera.position`) plus the built-in
+     * vertex/instance indices — everything the fragment shaders in this folder (see `basic-material-fragment.ts`,
+     * `standard-material-fragment.ts`) expect to find on `VertexOutput`.
+     *
+     * Declares the `VertexOutput`/`VertexInput`/`Transforms`/`Camera`/`InteractionData` WGSL structs (using the
+     * `WGSL_*_STRUCT_NAME` constants so downstream shaders can reference them by the same names), binds the
+     * `transforms`/`camera`/`interaction` uniforms at the configured `@group`/`@binding` coordinates, and — if
+     * `options.inputModifier`/`options.outputModifier` are supplied (raw WGSL or a {@link VertexInputModifierDelegate}/{@link VertexOutputModifierDelegate}) —
+     * parses them via {@link extractMeshVertexModifierFunctionComponents} and inlines them as extra `fn` definitions
+     * invoked before returning, letting user code rewrite the input geometry or tweak the computed output per-vertex.
+     *
+     * @param options Location/binding overrides and optional input/output WGSL modifiers; defaults to {@link DefaultMeshVertexOptions}.
+     * @returns Complete WGSL vertex-shader source with a single `@vertex fn main` entry point returning `VertexOutput`.
+     */
     function getMeshVertexWgsl(options = DefaultMeshVertexOptions) {
         if (options != DefaultMeshVertexOptions) {
             options = pacemCore.Utils.extend({}, DefaultMeshVertexOptions, options);
@@ -3769,6 +4144,7 @@ ${modifierFnOutput}
 }`;
     }
 
+    /** Fallback options used by {@link getDefaultLineVertexWgsl}/{@link getFatLineVertexWgsl}: positions/dimensions read from {@link STORAGE_GROUP_INDEX_LINE}, transform/camera uniforms from the shared {@link UNIFORM_GROUP_INDEX_TRANSFORM}/{@link UNIFORM_GROUP_INDEX_CAMERA} coordinates. */
     const DefaultLineVertexOptions = {
         inputPositionLocation: VERTEX_BUFFER_INDEX_MESH_POSITION,
         outputInstanceIndexLocation: 0,
@@ -3782,6 +4158,7 @@ ${modifierFnOutput}
         uniformWorldGroupIndex: UNIFORM_GROUP_INDEX_TRANSFORM,
         uniformWorldBindingIndex: UNIFORM_BINDING_INDEX_TRANSFORM,
     };
+    /** Builds the `VertexOutput` struct shared by both line vertex shaders below: clip-space `position` plus flat `instance`/`index` varyings, at the configured output locations, consumed by `line-material-fragment.ts`. */
     function getVertexOutputStructDefinition(opts) {
         return `struct ${WGSL_VERTEXOUTPUT_STRUCT_NAME} {
     @builtin(position) position : vec4f,                                                // clip space position
@@ -3789,6 +4166,19 @@ ${modifierFnOutput}
     @location(${opts.outputVertexIndexLocation}) @interpolate(flat) index : u32,        // vertex index
 }`;
     }
+    /**
+     * Composes the vertex shader for thin (native-line-width, 1px) line rendering: each vertex reads its `x`/`y`/`z`
+     * directly out of a flattened `positions: array<f32>` storage buffer (three floats per point, indexed by the
+     * built-in `vertex_index`) rather than a vertex-buffer attribute, then applies the usual world/view/projection
+     * transform chain. `instance_index` is passed through unchanged so the fragment stage
+     * (`line-material-fragment.ts`) can look up a per-vertex color.
+     *
+     * Declares `VertexOutput`/`Transforms`/`Camera` WGSL structs and binds `transforms`/`camera`/`positions` at the
+     * configured `@group`/`@binding` coordinates.
+     *
+     * @param options Location/binding overrides; defaults to {@link DefaultLineVertexOptions}.
+     * @returns Complete WGSL vertex-shader source with a single `@vertex fn main` entry point returning `VertexOutput`.
+     */
     function getDefaultLineVertexWgsl(options = DefaultLineVertexOptions) {
         const opts = pacemCore.Utils.extend({}, DefaultLineVertexOptions, options);
         return `${getVertexOutputStructDefinition(opts)}
@@ -3825,6 +4215,25 @@ struct Camera {
         index);
 }`;
     }
+    /**
+     * Composes the vertex shader for "fat" (screen-space-thickness) line rendering: unlike
+     * {@link getDefaultLineVertexWgsl}, it expects to be invoked with 6 vertices per line segment (a quad split into
+     * two triangles, per the index-to-corner mapping documented in `computeOffsetPosition`'s inline diagram) and
+     * offsets each corner perpendicular to the segment's screen-space direction by half of a uniform pixel width, so
+     * the line renders at a constant on-screen thickness regardless of distance from the camera.
+     *
+     * `computeClipPosition` reads a point's `x`/`y`/`z` out of the flattened `positions: array<f32>` storage buffer
+     * (as in {@link getDefaultLineVertexWgsl}) and transforms it to clip space; `computeOffsetPosition` then derives
+     * the two endpoints' NDC direction, builds a perpendicular offset scaled by `dimensions.halfLineWidth` and the
+     * viewport size, and picks/offsets the correct quad corner based on `vertex_index` (segment endpoint is
+     * `instance_index`/`instance_index + 1`).
+     *
+     * Declares `VertexOutput`/`Transforms`/`Camera`/`Pixels` WGSL structs and binds `transforms`/`camera`/`positions`/`dimensions`
+     * at the configured `@group`/`@binding` coordinates (`dimensions` carries `viewportWidth`, `viewportHeight` and `halfLineWidth` in pixels).
+     *
+     * @param options Location/binding overrides; defaults to {@link DefaultLineVertexOptions}.
+     * @returns Complete WGSL vertex-shader source with a single `@vertex fn main` entry point returning `VertexOutput`.
+     */
     function getFatLineVertexWgsl(options = DefaultLineVertexOptions) {
         const opts = pacemCore.Utils.extend({}, DefaultLineVertexOptions, options);
         return `${getVertexOutputStructDefinition(opts)}
@@ -3942,7 +4351,17 @@ fn computeOffsetPosition(p0: vec4f, p1: vec4f, index: u32) -> vec4f {
 
     //namespace Pacem.Drawing3D.WebGPU {
     /**
-     * Generate a WGSL piece of code that eases 3D picking using color strategy.
+     * Composes the fragment shader used by the {@link Raycaster} off-screen pass for GPU-based, color-coded object
+     * picking: instead of computing a lit color, it simply outputs the renderable's own numeric `id` (bound as a
+     * `ColorPicker` uniform) into a single-channel `r32uint` render target, so the CPU side can later read back the
+     * pixel under the pointer and resolve it to the {@link Renderable} that was drawn there.
+     *
+     * Declares the `ColorPicker` struct (`id: u32`) and its `var<uniform>` binding at `@binding(0)` within the given
+     * `@group`; unlike the material fragments in this folder it takes no {@link WGSLFragmentExtra} — it is not meant to
+     * be extended with lighting/texture snippets.
+     *
+     * @param groupIndex `@group` index at which the per-renderable `ColorPicker` uniform is bound; defaults to {@link UNIFORM_GROUP_INDEX_COLORPICKING}.
+     * @returns Complete WGSL fragment-shader source with a single `@fragment fn main` entry point returning `@location(0) u32`.
      */
     function getColorPickingFragmentWgsl(groupIndex = UNIFORM_GROUP_INDEX_COLORPICKING) {
         return `struct ColorPicker {
@@ -3958,9 +4377,25 @@ fn computeOffsetPosition(p0: vec4f, p1: vec4f, index: u32) -> vec4f {
   `;
     }
 
+    /** Fallback references used by {@link textureMap} when not overridden: reads UV coordinates from the `uv` varying. */
     const DefaultTextureMapReferences = {
         uv: 'uv',
     };
+    /**
+     * Builds a {@link WGSLFragmentExtra} that samples a 2D texture and tints it by a base color: `textureSample(tex, sampler, uv) * inputColor`.
+     * Declares a fresh `sampler`/`texture_2d<f32>` pair (uniquely named per call via {@link Utils.uniqueCode}) as `bindings`
+     * at consecutive `@binding` indices (`binding` for the sampler, `binding + 1` for the texture) within the given
+     * `@group`, and emits no `definitions`.
+     *
+     * As `modifiers`, either a single bare sample-and-multiply expression (single consumer), or, when
+     * `references.outputColors` lists multiple output variable names, one assignment per name — the first computes the
+     * sample, the rest copy it — so several downstream color channels (e.g. diffuse and ambient) can share one texture fetch.
+     *
+     * @param references WGSL identifiers for the UV coordinates (`uv`, defaults to `'uv'`), the base color to tint (`inputColor`, required) and, optionally, one or more output variable names (`outputColors`) to assign the sampled color to.
+     * @param group `@group` index at which the generated sampler/texture pair is bound.
+     * @param binding `@binding` index (within `group`) for the sampler; the texture is bound at `binding + 1`. Defaults to {@link SAMPLER_BINDING_INDEX}.
+     * @returns Fragment-shader `bindings`/`modifiers` meant to be spliced into a material fragment shader (see {@link getBasicMaterialFragmentWgsl}/{@link getStandardMaterialFragmentWgsl}).
+     */
     function textureMap(references = DefaultTextureMapReferences, group, binding = SAMPLER_BINDING_INDEX) {
         const key = pacemCore.Utils.uniqueCode();
         const samplerReference = `sampler_${key}`;
@@ -3984,9 +4419,27 @@ fn computeOffsetPosition(p0: vec4f, p1: vec4f, index: u32) -> vec4f {
         };
     }
 
+    /** Fallback references used by {@link directionalLight} when not overridden: reads the world-space `normal` varying and treats the base color as `white`. */
     const DefaultDirectionalLightReferences = {
         normal: 'normal', inputColor: 'white'
     };
+    /**
+     * Builds a {@link WGSLFragmentExtra} implementing a directional (sun-like, parallel-rays) light: a Lambertian
+     * diffuse term computed from the dot product between the surface normal and the (negated, normalized) light
+     * direction, modulated by the light's color and intensity. Unlike {@link omniLight}, it carries no position/falloff
+     * or specular term.
+     *
+     * Emits, as `definitions`, a `DirectionalLight` struct (`color: vec4f`, `direction: vec3f`, `intensity: f32`) and a
+     * `computeDirectional` helper function; as `bindings`, a `var<uniform>` declaration for the light data at the given
+     * `@group`/`@binding` coordinates; and, as `modifiers`, either a statement that accumulates the contribution into
+     * `references.outputColor` (`+=`) when provided, or a bare expression otherwise (for single-light use sites that
+     * assign it directly).
+     *
+     * @param references WGSL identifiers for the surface normal (`normal`), the base color to shade (`inputColor`) and, optionally, the color variable to accumulate into (`outputColor`).
+     * @param group `@group` index at which the generated `DirectionalLight` uniform is bound.
+     * @param binding `@binding` index (within `group`) at which the generated `DirectionalLight` uniform is bound.
+     * @returns Fragment-shader `definitions`/`bindings`/`modifiers` meant to be spliced into a material fragment shader (see {@link getBasicMaterialFragmentWgsl}/{@link getStandardMaterialFragmentWgsl}).
+     */
     function directionalLight(references, group, binding) {
         const key = pacemCore.Utils.uniqueCode();
         const lightReference = `directional_${key}`;
@@ -4015,9 +4468,27 @@ fn computeOffsetPosition(p0: vec4f, p1: vec4f, index: u32) -> vec4f {
         };
     }
 
+    /** Fallback references used by {@link omniLight} when not overridden: reads the world-space `normal`/`vertex`/`ray` varyings, treats the base color as `white` and disables the specular term (`empty` color, `0` shininess). */
     const DefaultOmniLightReferences = {
         normal: 'normal', position: 'vertex', ray: 'ray', inputColor: 'white', specularColor: 'empty', shininess: '0'
     };
+    /**
+     * Builds a {@link WGSLFragmentExtra} implementing an omnidirectional (point) light with a Blinn-Phong-like
+     * specular term: a Lambertian diffuse factor from the normal-to-light direction (light position minus surface
+     * position, i.e. no distance falloff), plus a specular highlight from the half-vector between the light direction
+     * and the eye-to-vertex ray, scaled by `shininess`. Unlike {@link directionalLight}, the light has a `position` in
+     * world space rather than a constant direction.
+     *
+     * Emits, as `definitions`, an `OmniLight` struct (`color: vec4f`, `position: vec3f`, `intensity: f32`) and a
+     * `computeOmni` helper function; as `bindings`, a `var<uniform>` declaration for the light data at the given
+     * `@group`/`@binding` coordinates; and, as `modifiers`, either a statement that accumulates the contribution into
+     * `references.outputColor` (`+=`) when provided, or a bare expression otherwise.
+     *
+     * @param references WGSL identifiers for the surface normal (`normal`), world-space position (`position`), eye-to-vertex ray (`ray`), base color (`inputColor`), specular color (`specularColor`), shininess factor (`shininess`) and, optionally, the color variable to accumulate into (`outputColor`).
+     * @param group `@group` index at which the generated `OmniLight` uniform is bound.
+     * @param binding `@binding` index (within `group`) at which the generated `OmniLight` uniform is bound.
+     * @returns Fragment-shader `definitions`/`bindings`/`modifiers` meant to be spliced into a material fragment shader (see {@link getBasicMaterialFragmentWgsl}/{@link getStandardMaterialFragmentWgsl}).
+     */
     function omniLight(references, group, binding) {
         const key = pacemCore.Utils.uniqueCode();
         const lightReference = `omni_${key}`;
@@ -4054,6 +4525,20 @@ fn computeOffsetPosition(p0: vec4f, p1: vec4f, index: u32) -> vec4f {
         };
     }
 
+    /**
+     * Builds a {@link WGSLFragmentExtra} implementing the ambient light contribution to a fragment shader: it multiplies the
+     * fragment's base color by a uniform light color/intensity, uniformly across the surface (no dependency on normal or
+     * view direction, unlike {@link directionalLight}/{@link omniLight}).
+     *
+     * Emits, as `definitions`, an `AmbientLight` struct (`color: vec4f`, `intensity: f32`) and a `computeAmbient` helper
+     * function; as `bindings`, a `var<uniform>` declaration for the light data at the given `@group`/`@binding`
+     * coordinates; and, as `modifiers`, a statement assigning the computed color into `references.outputColor`.
+     *
+     * @param references WGSL identifiers for the color to shade (`inputColor`) and the variable to assign the ambient-lit result to (`outputColor`). Both are required.
+     * @param group `@group` index at which the generated `AmbientLight` uniform is bound.
+     * @param binding `@binding` index (within `group`) at which the generated `AmbientLight` uniform is bound.
+     * @returns Fragment-shader `definitions`/`bindings`/`modifiers` meant to be spliced into a material fragment shader (see {@link getBasicMaterialFragmentWgsl}/{@link getStandardMaterialFragmentWgsl}).
+     */
     function ambientLight(references, group, binding) {
         const key = pacemCore.Utils.uniqueCode();
         const lightReference = `ambient_${key}`;
@@ -4080,6 +4565,11 @@ fn computeOffsetPosition(p0: vec4f, p1: vec4f, index: u32) -> vec4f {
     const Vector3D$3 = pacemNumerical.Geometry.LinearAlgebra.Vector3D;
     const Matrix3D$2 = pacemNumerical.Geometry.LinearAlgebra.Matrix3D;
     const DEFAULT_SIZE = { width: 1, height: 1 };
+    /**
+     * Factory that converts a scene-facing {@link Camera3D} (`../../types.ts`) into its WebGPU-side counterpart
+     * ({@link Camera}, `abstractions.ts`): either a {@link PerspectiveCamera} or an {@link OrthographicCamera}, exposing
+     * `view()`/`projection()` matrices consumed when building the camera's uniform buffer (see `renderablebuffer.ts`).
+     */
     class Cameras {
         /**
          * Creates a new webgpu {@link Camera} given a canonic one.
@@ -4153,13 +4643,24 @@ fn computeOffsetPosition(p0: vec4f, p1: vec4f, index: u32) -> vec4f {
         assertNearFarCorrectness(near, far);
         return Matrix3D$2.from(2 / (right - left), 0, 0, 0, 0, 2 / (top - bottom), 0, 0, 0, 0, 1 / (near - far), 0, (left + right) / (left - right), (top + bottom) / (bottom - top), near / (near - far), 1);
     }
+    /**
+     * WebGPU-side counterpart of an {@link OrthographicCamera3D}: computes the view matrix from `position`/`lookAt`/`up`,
+     * and an orthographic projection matrix from the camera's `left`/`right`/`top`/`bottom`/`near`/`far` planes, scaled
+     * by the eye-to-target distance and (if given) the viewport aspect ratio.
+     */
     class OrthographicCamera {
         constructor(_camera) {
             this._camera = _camera;
         }
+        /** Computes the view matrix for `camera`; see {@link view} for a bound instance-method equivalent. */
         static view(camera) {
             return view(camera.position, camera.lookAt, camera.up);
         }
+        /**
+         * Computes the orthographic projection matrix for `camera`.
+         * @param camera Source orthographic camera.
+         * @param size Viewport size, used to correct the projected frustum for aspect ratio; defaults to a 1:1 viewport.
+         */
         static projection(camera, size = DEFAULT_SIZE) {
             const eye = camera.position, target = camera.lookAt;
             const z = Vector3D$3.subtract(target, eye);
@@ -4173,27 +4674,42 @@ fn computeOffsetPosition(p0: vec4f, p1: vec4f, index: u32) -> vec4f {
             const right = camera.right * w, left = camera.left * w;
             return orthographic(left, right, top, bottom, camera.near, camera.far);
         }
+        /** Computes the view matrix for the wrapped camera. See {@link Camera.view}. */
         view() {
             return OrthographicCamera.view(this._camera);
         }
+        /** Computes the orthographic projection matrix for the wrapped camera. See {@link Camera.projection}. */
         projection(size) {
             return OrthographicCamera.projection(this._camera, size);
         }
     }
+    /**
+     * WebGPU-side counterpart of a {@link PerspectiveCamera3D}: computes the view matrix from `position`/`lookAt`/`up`,
+     * and a perspective projection matrix from the camera's vertical field of view, aspect ratio and near/far clip planes.
+     */
     class PerspectiveCamera {
         constructor(_camera) {
             this._camera = _camera;
         }
+        /** Computes the view matrix for `camera`; see {@link view} for a bound instance-method equivalent. */
         static view(camera) {
             return view(camera.position, camera.lookAt, camera.up);
         }
+        /**
+         * Computes the perspective projection matrix for `camera`, combining its `aspectRatio` with `size`'s
+         * (`size.width / size.height`) to correct for non-square viewports.
+         * @param camera Source perspective camera.
+         * @param size Viewport size, used to correct for aspect ratio; defaults to a 1:1 viewport.
+         */
         static projection(camera, size = DEFAULT_SIZE) {
             const aspectRatio = (size.width / size.height) / camera.aspectRatio;
             return perspective(camera.fov, aspectRatio, camera.near, camera.far);
         }
+        /** Computes the view matrix for the wrapped camera. See {@link Camera.view}. */
         view() {
             return PerspectiveCamera.view(this._camera);
         }
+        /** Computes the perspective projection matrix for the wrapped camera. See {@link Camera.projection}. */
         projection(size) {
             return PerspectiveCamera.projection(this._camera, size);
         }
@@ -4228,6 +4744,13 @@ fn computeOffsetPosition(p0: vec4f, p1: vec4f, index: u32) -> vec4f {
         }
         throw new Error(`Renderable is not supported.`);
     }
+    /**
+     * Drives one render (or raycast) pass over a fixed snapshot of the scene: iterates the meshes accumulated in a
+     * {@link RenderableBufferSet}, invoking a callback for each mesh together with the shared camera and lights, and
+     * seals (clears the stale-property flags of) every buffer that participated in a successful draw. Rebuilt by
+     * `renderer.ts`'s `RendererClass` whenever the scene graph changes (see `update`), and driven once per frame by
+     * `RendererClass.render`/`RendererClass.raycast`.
+     */
     class RenderLooper {
         constructor(_set) {
             this._set = _set;
@@ -4236,6 +4759,13 @@ fn computeOffsetPosition(p0: vec4f, p1: vec4f, index: u32) -> vec4f {
         get items() {
             return this._set;
         }
+        /**
+         * Invokes `render(mesh, camera, lights)` for every non-disposed mesh buffer in the set, skipping meshes for
+         * which `render` returns `false` (e.g. hidden items). After each successful call, clears the
+         * {@link StalePropertyFlag}s on the mesh buffer and, the first time each occurs, on the shared camera/light
+         * buffers; group buffers are always sealed at the end regardless of whether any mesh rendered.
+         * @param render Callback invoked once per mesh with its buffer, the (single) camera buffer and all light buffers; return `false` to skip that mesh (its flags are left untouched).
+         */
         loop(render) {
             const { meshes, cameras, groups, lights } = this._set;
             const camera = cameras[0];
@@ -4266,7 +4796,18 @@ fn computeOffsetPosition(p0: vec4f, p1: vec4f, index: u32) -> vec4f {
             }
         }
     }
+    /**
+     * Factory for {@link ManagedBuffer}s wrapping non-{@link Renderable} scene data — geometry ({@link NodeGeometry}/
+     * {@link MeshGeometry}), material ({@link Material3D}) and interaction (pointer/time/viewport) state — so this data
+     * can be shared and cached across the {@link RenderableBuffer}s that reference it (e.g. a geometry instance reused by
+     * several meshes), rather than re-uploaded to the GPU per mesh.
+     */
     class ManagedBuffers {
+        /**
+         * Wraps `item` in the {@link ManagedBuffer} implementation matching its runtime type.
+         * @param item A geometry ({@link NodeGeometry}/{@link MeshGeometry}), material ({@link Material3D}) or {@link Interaction} instance.
+         * @throws {Error} If `item`'s type isn't recognized.
+         */
         static create(item) {
             if (isGeometry(item)) {
                 item.key ??= 'geometry_' + pacemCore.Utils.uniqueCode();
@@ -4281,10 +4822,28 @@ fn computeOffsetPosition(p0: vec4f, p1: vec4f, index: u32) -> vec4f {
             throw new Error(`Object is not supported.`);
         }
     }
+    /**
+     * Factory and stale-flag utilities for {@link RenderableBuffer}s wrapping {@link Renderable} scene items (groups,
+     * meshes, cameras, lights). Callers (see `renderer.ts`'s `RendererClass`) cache one buffer per item across frames, so
+     * the underlying GPU resources persist until the item is removed from the scene.
+     */
     class RenderableBuffers {
+        /**
+         * Wraps `item` in the {@link RenderableBuffer} implementation matching its kind (group/mesh/camera/light),
+         * recursively wrapping a group's children.
+         * @param item The scene renderable to wrap.
+         * @param args Extra constructor arguments forwarded to mesh buffers (the shared geometry/material {@link ManagedBuffer} caches; see `renderer.ts`).
+         * @throws {Error} If `item`'s type isn't recognized.
+         */
         static create(item, ...args) {
             return createRenderableBuffer(item, null, ...args);
         }
+        /**
+         * Clears the {@link StalePropertyFlag}s on `buffer`'s underlying item, marking it as up to date until the next
+         * scene-graph mutation flags it again.
+         * @param buffer The buffer whose item's flags should be cleared.
+         * @param includeParent Whether to also clear the parent group buffer's flags, recursively up the hierarchy.
+         */
         static clearFlags(buffer, includeParent = false) {
             buffer.item.flags.splice(0);
             if (includeParent) {
@@ -4294,6 +4853,11 @@ fn computeOffsetPosition(p0: vec4f, p1: vec4f, index: u32) -> vec4f {
                 }
             }
         }
+        /**
+         * Returns the union of `buffer`'s own {@link StalePropertyFlag}s with those of all its ancestor group buffers —
+         * the effective set of "what changed" a re-render of this item needs to account for.
+         * @param buffer The buffer to compute the effective flag set for.
+         */
         static allFlags(buffer) {
             const bufferBase = buffer;
             const parentBufferBase = bufferBase.parent;
@@ -5046,8 +5610,17 @@ fn computeOffsetPosition(p0: vec4f, p1: vec4f, index: u32) -> vec4f {
         }
     };
     const EMPTY_BIND_DELEGATE = (_) => { };
+    /**
+     * Factory for {@link RenderPipeline}s: given a {@link Context} and a set of {@link RenderableBuffer}s (a mesh/line plus its
+     * camera and lights), builds the WGSL shaders, {@link GPUBindGroupLayout}s, {@link GPUPipelineLayout} and the underlying
+     * {@link GPURenderPipeline}(s) needed to draw (and, separately, color-pick/raycast) that combination. Built pipelines are
+     * memoized per {@link Context} and reused as long as the shader "recipe" (mesh material/shader, light count/types, WGSL
+     * modifier version) doesn't change. This is the machinery {@link Pacem3DWebgpuAdapterElement}'s {@link Renderer} implementation
+     * (`renderer.ts`) drives every frame.
+     */
     class RenderPipelines {
         static { this._memoizer = new WeakMap(); }
+        /** Clears the {@link RenderPipeline} cache associated with the given {@link Context} (e.g. on device loss/adapter teardown). Does not explicitly destroy the underlying GPU objects — they're released with the {@link GPUDevice}. */
         static dispose(ctx) {
             const memoizer = this._memoizer;
             const cache = memoizer.get(ctx);
@@ -5056,6 +5629,12 @@ fn computeOffsetPosition(p0: vec4f, p1: vec4f, index: u32) -> vec4f {
                 memoizer.delete(ctx);
             }
         }
+        /**
+         * Builds (or reuses, via {@link create}'s cache) the render pipeline for `items` and wraps it as a color-picking-only
+         * {@link RenderPipeline}, whose `frame` delegate draws object ids into an `r32uint` target instead of the normal color target.
+         * Returns `null` if the resolved pipeline isn't a mesh or line pipeline (i.e. doesn't support raycasting).
+         * @param items The mesh/line, camera and lights to raycast, in the same shape expected by {@link create}.
+         */
         static createColorPicking(ctx, items) {
             const renderPipeline = RenderPipelines.create(ctx, items);
             if (renderPipeline instanceof MeshRenderPipelineClass
@@ -5066,6 +5645,20 @@ fn computeOffsetPosition(p0: vec4f, p1: vec4f, index: u32) -> vec4f {
             }
             return null;
         }
+        /**
+         * Builds (or returns the memoized) {@link RenderPipeline} for the given renderables: the first buffer must wrap a
+         * {@link Mesh} (with either a {@link MeshGeometry} or a {@link LineMaterial}), followed by its {@link Camera} buffer
+         * and zero or more {@link Light} buffers. Generates the mesh/line's WGSL vertex and fragment shaders (via
+         * {@link MeshWGSLBuilder}/{@link LineWGSLBuilder}), compiles them into {@link GPUShaderModule}s, creates the
+         * {@link GPUBindGroupLayout}s/{@link GPUPipelineLayout} and the resulting {@link GPURenderPipeline} (plus a matching
+         * color-picking pipeline). The pipeline is cached per {@link Context} keyed by shader "recipe" + WGSL modifiers version,
+         * so repeated calls with an equivalent recipe skip rebuilding.
+         * @param ctx WebGPU context (device/canvas/format) to build the pipeline against.
+         * @param items `[mesh, camera, ...lights]` renderable buffers.
+         * @param pipelineOptions Optional overrides for primitive topology, multisampling, vertex packing and WGSL modifiers.
+         * @returns The built (or cached) {@link RenderPipeline}.
+         * @throws {Error} If no mesh is provided, the mesh's geometry/material combination isn't supported, or the first argument isn't a mesh.
+         */
         static create(ctx, [mesh, camera, ...lights], pipelineOptions) {
             const memoizer = RenderPipelines._memoizer;
             let cache = memoizer.get(ctx);
@@ -6206,6 +6799,12 @@ fn computeOffsetPosition(p0: vec4f, p1: vec4f, index: u32) -> vec4f {
     // #endregion
 
     //namespace Pacem.Drawing3D.WebGPU {
+    /**
+     * Factory/registry for {@link Raycaster}s: builds (or returns the memoized) color-picking {@link Raycaster} for a
+     * given {@link Context}, used by the {@link Renderer}'s `raycast` implementation (`renderer.ts`) to hit-test pointer
+     * clicks/hovers against rendered items. Raycasters are memoized per {@link Context} so their off-screen render
+     * target/readback buffer are reused across calls instead of being reallocated every raycast.
+     */
     class Raycasters {
         // learn from:
         // https://webglfundamentals.org/webgl/lessons/webgl-qna-how-to-get-the-3d-coordinates-of-a-mouse-click.html
@@ -6213,6 +6812,7 @@ fn computeOffsetPosition(p0: vec4f, p1: vec4f, index: u32) -> vec4f {
         // https://shi-yan.github.io/webgpuunleashed/Control/object_picking.html
         // https://gist.github.com/greggman/57c3c0d3cf1db14f1baad2d9b0094397 (color picking)
         static { this._memoizer = new WeakMap(); }
+        /** Destroys and clears all {@link Raycaster}s memoized for `ctx` (e.g. on device loss/adapter teardown). */
         static dispose(ctx) {
             const memoizer = this._memoizer;
             if (memoizer.has(ctx)) {
@@ -6397,12 +6997,28 @@ fn computeOffsetPosition(p0: vec4f, p1: vec4f, index: u32) -> vec4f {
 
     //namespace Pacem.Drawing3D.WebGPU {
     const Vector3D$1 = pacemNumerical.Geometry.LinearAlgebra.Vector3D;
+    /** Reason a WebGPU {@link Renderer} failed to initialize, as reported via a rejected {@link Renderers.create} promise (see {@link WebGPUIssue}). */
     var WebGPUIssueCause;
     (function (WebGPUIssueCause) {
+        /** `navigator.gpu` is unavailable — the browser/OS doesn't support WebGPU at all. */
         WebGPUIssueCause[WebGPUIssueCause["NotSupported"] = 0] = "NotSupported";
+        /** WebGPU is supported, but no {@link GPUAdapter}/{@link GPUDevice} could be obtained (e.g. disabled via flags, denied, or hardware unsupported). */
         WebGPUIssueCause[WebGPUIssueCause["Disabled"] = 1] = "Disabled";
     })(WebGPUIssueCause || (WebGPUIssueCause = {}));
+    /**
+     * Factory for the WebGPU {@link Renderer} consumed by {@link Pacem3DWebgpuAdapterElement}. Requests a
+     * {@link GPUAdapter}/{@link GPUDevice}, configures the stage canvas's {@link GPUCanvasContext}, and wraps everything
+     * in a {@link Renderer} implementation that owns: the per-frame render/raycast loop (via {@link RenderLooper}), the
+     * mesh/geometry/material buffer caches ({@link RenderableBuffers}/{@link ManagedBuffers}), the multisample/depth
+     * render targets, and pointer hit-testing ({@link Raycasters}).
+     */
     class Renderers {
+        /**
+         * Creates and asynchronously initializes a WebGPU {@link Renderer} for `stage`'s canvas.
+         * @param stage The owning `<pacem-3d>` element whose wrapper hosts the render canvas.
+         * @param config Whether to enable per-frame WebGPU validation error scopes (a perf hog — debug builds only) and optional WGSL shader modifiers.
+         * @returns A promise resolving to the ready {@link Renderer}, or rejecting with a {@link WebGPUIssue} if WebGPU isn't supported or no adapter/device could be obtained.
+         */
         static create(stage, config) {
             return new Promise((resolve, reject) => {
                 if (!navigator.gpu) {
@@ -6834,11 +7450,13 @@ fn computeOffsetPosition(p0: vec4f, p1: vec4f, index: u32) -> vec4f {
     const WEBGPU_RAYCAST_CALLBACK_PROP = 'WebGPURaycastCallback';
     const WEBGPU_RAYCAST_PIXEL_PROP = 'WebGPURaycastPixel';
     const GETVAL = pacemCore.CustomElementUtils.getAttachedPropertyValue, SETVAL = pacemCore.CustomElementUtils.setAttachedPropertyValue, DELVAL = pacemCore.CustomElementUtils.deleteAttachedPropertyValue;
+    /** `<pacem-3d-wgsl-script>`: declares a WGSL snippet (vertex input/output or fragment stage) that a parent {@link Pacem3DWebgpuAdapterElement} splices into its render pipeline shaders, tracked via a content {@link version} hash. */
     let Pacem3DWgslScriptElement = class Pacem3DWgslScriptElement extends pacemCore.Components.PacemItemElement {
         findContainer() {
             return pacemCore.CustomElementUtils.findAncestor(this, n => n instanceof Pacem3DWebgpuAdapterElement);
         }
         #version = '';
+        /** @readonly Gets a hash of the current {@link wgsl} content, changing whenever it does. */
         get version() {
             return this.#version;
         }
@@ -6881,6 +7499,12 @@ fn computeOffsetPosition(p0: vec4f, p1: vec4f, index: u32) -> vec4f {
     Pacem3DWgslScriptElement = __decorate$2([
         pacemCore.CustomElement({ tagName: pacemCore.P + '-3d-wgsl-script' })
     ], Pacem3DWgslScriptElement);
+    /**
+     * `<pacem-3d-webgpu-adapter>`: {@link Pacem3DAdapterElement} rendering backend built directly on the browser's
+     * WebGPU API. Manages one {@link Renderer} per stage it is assigned to, hosts child {@link Pacem3DWgslScriptElement}
+     * shader customizations (via {@link modifiers}), and falls back gracefully (see {@link supported}/{@link active})
+     * when WebGPU isn't available.
+     */
     let Pacem3DWebgpuAdapterElement = class Pacem3DWebgpuAdapterElement extends Pacem3DAdapterElement {
         constructor() {
             super(...arguments);
@@ -6902,9 +7526,11 @@ fn computeOffsetPosition(p0: vec4f, p1: vec4f, index: u32) -> vec4f {
             renderer?.resize(size);
         }
         #items;
+        /** @readonly Gets the child {@link Pacem3DWgslScriptElement} shader-customization items currently registered. */
         get items() {
             return this.#items;
         }
+        /** Registers a child {@link Pacem3DWgslScriptElement}, re-parsing the WGSL {@link modifiers} it contributes. */
         register(item) {
             const items = this.#items;
             if (item instanceof Pacem3DWgslScriptElement && !items.includes(item)) {
@@ -6915,6 +7541,7 @@ fn computeOffsetPosition(p0: vec4f, p1: vec4f, index: u32) -> vec4f {
             }
             return false;
         }
+        /** Unregisters a previously-registered {@link Pacem3DWgslScriptElement}, re-parsing the WGSL {@link modifiers} accordingly. */
         unregister(item) {
             const items = this.#items;
             const ndx = items.indexOf(item);
@@ -6930,9 +7557,11 @@ fn computeOffsetPosition(p0: vec4f, p1: vec4f, index: u32) -> vec4f {
         #renderers;
         #supported;
         #active;
+        /** @readonly Gets whether WebGPU is supported by the current browser/device. */
         get supported() {
             return this.#supported;
         }
+        /** @readonly Gets whether the adapter is currently able to render (false once a {@link WebGPUIssue} disables it). */
         get active() {
             return this.#active;
         }
@@ -7395,6 +8024,11 @@ fn computeOffsetPosition(p0: vec4f, p1: vec4f, index: u32) -> vec4f {
             scene.removeEventListener('render', this._renderHandler, false);
         }
     }
+    /**
+     * `<pacem-3d-orbit-camera>`: a behavior element that, applied to a {@link Pacem3DCameraElement}, attaches pointer/wheel
+     * driven orbit (rotate/pan/zoom around a target) interaction by instantiating and configuring an
+     * {@link OrbitCameraBehavior} for each decorated element.
+     */
     let PacemOrbitCameraBehaviorElement = class PacemOrbitCameraBehaviorElement extends pacemCore.Behaviors.PacemBehavior {
         constructor() {
             super(...arguments);
@@ -7575,7 +8209,12 @@ fn computeOffsetPosition(p0: vec4f, p1: vec4f, index: u32) -> vec4f {
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Drawing3D {
+    /** Parses the text content of a Wavefront `.obj` file into a {@link MeshGeometry} (vertices, triangle indices, UVs and normals). */
     class OBJParser {
+        /**
+         * Parses `v` (vertex), `vt` (texture coordinate), `vn` (normal) and `f` (face) records out of `content`,
+         * triangulating any face with more than 3 vertices (fan triangulation).
+         */
         static parse(content) {
             // vertices
             const vertices = [];
@@ -7648,7 +8287,12 @@ fn computeOffsetPosition(p0: vec4f, p1: vec4f, index: u32) -> vec4f {
             return new MeshGeometry(vertices, positions, uv, normals);
         }
     }
+    /** Model-file parsing entry point, registered as the `parse3D` markup transformer for converting raw asset text into a {@link NodeGeometry} or {@link Material}. */
     class Parser3D {
+        /**
+         * Parses `content` according to `type` into a {@link NodeGeometry} (currently only the `'obj'` Wavefront format,
+         * via {@link OBJParser}) or a {@link Material}. Throws for any other/unsupported `type` (e.g. `'mtl'`, not yet implemented).
+         */
         static parseGeometry(content, type) {
             switch (type.toLowerCase()) {
                 case 'obj':