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

package/dist/bundle/pacem-3d.mjs

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-3d v1.0.0-bessel (https://js.pacem.it)
+ * @pacem/pacem-3d v1.0.0-dirac (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */
@@ -204,9 +204,11 @@ var Pacem3DElement = class Pacem3DElement2 extends Components.PacemItemsContaine
   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);
   }
@@ -342,9 +344,11 @@ var Pacem3DElement = class Pacem3DElement2 extends Components.PacemItemsContaine
     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 (!Utils2.isNull(item)) {
       const adapter = this.adapter;
@@ -510,15 +514,18 @@ var RenderableElement = class _RenderableElement extends Components2.PacemCrossI
     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(_) {
     return false;
   }
   findContainer() {
     return this.parent || this.stage;
   }
+  /** @readonly Gets the ancestor {@link Pacem3DElement} stage this element belongs to. */
   get stage() {
     return this["_scene"] = this["_scene"] || 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"] || CustomElementUtils.findAncestor(this, (i) => i instanceof _RenderableElement);
   }
@@ -542,6 +549,7 @@ var RenderableElement = class _RenderableElement extends Components2.PacemCrossI
     }
   }
   #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;
   }
@@ -637,6 +645,7 @@ var Pacem3DGroupElement = class Pacem3DGroupElement2 extends Ui3DElement {
     return child instanceof RenderableElement;
   }
   #children = [];
+  /** @readonly Gets the renderable children currently belonging to the group. */
   get childRenderables() {
     return this.#children;
   }
@@ -751,6 +760,7 @@ var Pacem3DCameraElement = class extends RenderableElement {
     const currentValue = this.#sphere = { center, radius };
     this.dispatchEvent(new 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;
   }
@@ -786,9 +796,11 @@ var Pacem3DPerspectiveCameraElement = class Pacem3DPerspectiveCameraElement2 ext
     this.fov = 45;
     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;
   }
@@ -819,6 +831,7 @@ var Pacem3DOrthographicCameraElement = class Pacem3DOrthographicCameraElement2 e
     this.bottom = -1;
     this.right = 1;
   }
+  /** @readonly Gets the camera discriminator: always `"orthographic"`. */
   get type() {
     return "orthographic";
   }
@@ -854,6 +867,7 @@ var Pacem3DAdapterElement = class extends PacemEventTarget {
 
 // packages/3d/dist/esm/detector.js
 var Pacem3DDetector = class {
+  /** Probes the browser for WebGL support by attempting to create a rendering context, populating {@link info} and {@link supported}. */
   constructor() {
     this._detected = {
       supported: false,
@@ -916,9 +930,11 @@ var Pacem3DDetector = class {
       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;
   }
@@ -967,11 +983,13 @@ function isShaderMaterial(obj) {
   return isMaterial(obj) && obj.shader === KnownShader.Custom;
 }
 var MaterialElement = class extends PacemEventTarget2 {
+  /** @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;
   }
@@ -1006,11 +1024,13 @@ var MaterialElement = class extends PacemEventTarget2 {
     super.viewActivatedCallback();
     this.updateMaterial();
   }
+  /** Recomputes {@link material} via {@link createMaterial}, flagging it as {@link StalePropertyFlag.Material}. */
   updateMaterial() {
     this.createMaterial().then((m) => {
       this.material = Utils4.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,
@@ -1072,6 +1092,7 @@ var LambertMaterialElement = class LambertMaterialElement2 extends MaterialEleme
   constructor() {
     super(KnownShader.Lambert);
   }
+  /** Builds the {@link LambertMaterial}, adding `emissiveColor`, `reflectivity` and `refractionRatio` to the base {@link Material}. */
   async createMaterial() {
     return Utils5.extend({
       emissiveColor: this.emissiveColor || "#000",
@@ -1130,6 +1151,7 @@ var LineMaterialElement = class LineMaterialElement2 extends MaterialElement {
       }
     }
   }
+  /** Builds the {@link LineMaterial}, adding `lineWidth`, `lineJoin`, `lineCap` and `dashArray` to the base {@link Material}. */
   async createMaterial() {
     return Utils6.extend({
       lineWidth: this.lineWidth ?? 1,
@@ -1173,6 +1195,7 @@ var PhongMaterialElement = class PhongMaterialElement2 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 Utils7.extend({
       emissiveColor: this.emissiveColor || "#000",
@@ -1233,6 +1256,7 @@ var StandardMaterialElement = class StandardMaterialElement2 extends MaterialEle
   constructor() {
     super(KnownShader.Standard);
   }
+  /** Builds the {@link StandardMaterial}, adding `emissiveColor`, `refractionRatio`, `metalness`, `roughness` and `flatShading` to the base {@link Material}. */
   async createMaterial() {
     return Utils8.extend({
       emissiveColor: this.emissiveColor || "#000",
@@ -1341,6 +1365,7 @@ var NodeGeometry = class {
   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 (!Utils11.isNullOrEmpty(positions)) {
@@ -1358,6 +1383,7 @@ var NodeGeometry = class {
     }
     return bary;
   }
+  /** Computes the axis-aligned {@link Box3D} enclosing the given positions. */
   static boundingBox(positions) {
     const output = {
       minX: Infinity,
@@ -1380,6 +1406,7 @@ var NodeGeometry = class {
     }
     return output;
   }
+  /** Marks the geometry as stale, flagging it with {@link StalePropertyFlag.Geometry} for the next render. */
   setAsDirty() {
     setSelfAsDirty.call(this);
   }
@@ -1400,18 +1427,21 @@ var MeshGeometry = class 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;
   }
@@ -1447,6 +1477,7 @@ var __decorate11 = function(decorators, target, key, desc) {
 };
 var PacemBoxElement_1;
 var PacemBoxElement = PacemBoxElement_1 = class PacemBoxElement2 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 = [];
@@ -1604,6 +1635,7 @@ var PacemBoxElement = PacemBoxElement_1 = class PacemBoxElement2 extends Pacem3D
     geom.boundingSphere = { center, radius: Math.sqrt(Math.pow(w2, 2) + Math.pow(h2, 2) + Math.pow(d2, 2)) };
     return geom;
   }
+  /** Computes the box geometry from the default (unset) shape parameters. */
   createDefaultGeometry() {
     return PacemBoxElement_1.createMeshGeometry();
   }
@@ -1653,6 +1685,7 @@ var __decorate12 = function(decorators, target, key, desc) {
 };
 var PacemConeElement_1;
 var PacemConeElement = PacemConeElement_1 = class PacemConeElement2 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 = [];
@@ -1746,6 +1779,7 @@ var PacemConeElement = PacemConeElement_1 = class PacemConeElement2 extends Pace
     computeSharpVertexNormals(geom);
     return geom;
   }
+  /** Computes the cone geometry from the default (unset) shape parameters. */
   createDefaultGeometry() {
     return PacemConeElement_1.createMeshGeometry();
   }
@@ -1791,6 +1825,7 @@ var __decorate13 = function(decorators, target, key, desc) {
 };
 var PacemCylinderElement_1;
 var PacemCylinderElement = PacemCylinderElement_1 = class PacemCylinderElement2 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 = [];
@@ -1926,6 +1961,7 @@ var PacemCylinderElement = PacemCylinderElement_1 = class PacemCylinderElement2
     computeSharpVertexNormals(geom);
     return geom;
   }
+  /** Computes the cylinder geometry from the default (unset) shape parameters. */
   createDefaultGeometry() {
     return PacemCylinderElement_1.createMeshGeometry();
   }
@@ -1972,9 +2008,11 @@ var __decorate14 = function(decorators, target, key, desc) {
 var PacemLineElement_1;
 var DEFAULT_LINE = [{ x: 0, y: 0, z: 0 }, { x: 0, y: 1, z: 0 }];
 var PacemLineElement = PacemLineElement_1 = class PacemLineElement2 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();
   }
@@ -2005,6 +2043,7 @@ var __decorate15 = function(decorators, target, key, desc) {
 };
 var PacemPlaneElement_1;
 var PacemPlaneElement = PacemPlaneElement_1 = class PacemPlaneElement2 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;
     length ||= 1;
@@ -2047,6 +2086,7 @@ var PacemPlaneElement = PacemPlaneElement_1 = class PacemPlaneElement2 extends P
     geom.key = `plane_${width}x${length}_w${widthSegments}_l${lengthSegments}`;
     return geom;
   }
+  /** Computes the plane geometry from the default (unset) shape parameters. */
   createDefaultGeometry() {
     return PacemPlaneElement_1.createMeshGeometry();
   }
@@ -2118,6 +2158,7 @@ var PolyhedronElement = class extends Pacem3DPrimitiveElement {
   _assignMeshGeometry(radius) {
     this.geometry = this.createMeshGeometry(radius > 0 ? radius : 1);
   }
+  /** Computes the polyhedron geometry using a radius of `1` when {@link radius} hasn't been explicitly set. */
   createDefaultGeometry() {
     return this.createMeshGeometry(1);
   }
@@ -2126,6 +2167,7 @@ __decorate16([
   Watch14({ emit: false, converter: PropertyConverters14.Number })
 ], PolyhedronElement.prototype, "radius", void 0);
 var PacemTetrahedronElement = PacemTetrahedronElement_1 = class PacemTetrahedronElement2 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;
     const nodesCoordsString = "0 0.5774 -0.8165, 0 0.5774 0.8165, 0.8165 -0.5774 0, -0.8165 -0.5774 0";
@@ -2160,6 +2202,7 @@ PacemTetrahedronElement = PacemTetrahedronElement_1 = __decorate16([
   CustomElement13({ tagName: P13 + "-" + TAG_MIDDLE_NAME + "-primitive-tetrahedron" })
 ], PacemTetrahedronElement);
 var PacemOctahedronElement = PacemOctahedronElement_1 = class PacemOctahedronElement2 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;
     const nodesCoordsString = "0 0.7071 -0.7071, 0 0.7071 0.7071, 1 0 0, 0 -0.7071 -0.7071, -1 0 0, 0 -0.7071 0.7071";
@@ -2194,6 +2237,7 @@ PacemOctahedronElement = PacemOctahedronElement_1 = __decorate16([
   CustomElement13({ tagName: P13 + "-" + TAG_MIDDLE_NAME + "-primitive-octahedron" })
 ], PacemOctahedronElement);
 var PacemHexahedronElement = PacemHexahedronElement_1 = class PacemHexahedronElement2 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;
     const inv_sqrt3 = 1 / Math.sqrt(3);
@@ -2210,6 +2254,7 @@ PacemHexahedronElement = PacemHexahedronElement_1 = __decorate16([
   CustomElement13({ tagName: P13 + "-" + TAG_MIDDLE_NAME + "-primitive-hexahedron" })
 ], PacemHexahedronElement);
 var PacemIcosahedronElement = PacemIcosahedronElement_1 = class PacemIcosahedronElement2 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;
     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";
@@ -2366,6 +2411,7 @@ PacemIcosahedronElement = PacemIcosahedronElement_1 = __decorate16([
   CustomElement13({ tagName: P13 + "-" + TAG_MIDDLE_NAME + "-primitive-icosahedron" })
 ], PacemIcosahedronElement);
 var PacemDodecahedronElement = PacemDodecahedronElement_1 = class PacemDodecahedronElement2 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;
     const n1 = Point3D.from(0.356822 * radius, 0.934172 * radius, 0 * radius);
@@ -2691,6 +2737,7 @@ var __decorate17 = function(decorators, target, key, desc) {
 };
 var PacemSphereElement_1;
 var PacemSphereElement = PacemSphereElement_1 = class PacemSphereElement2 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 = [];
     const uv = [];
@@ -2759,6 +2806,7 @@ var PacemSphereElement = PacemSphereElement_1 = class PacemSphereElement2 extend
     computeSharpVertexNormals(geom);
     return geom;
   }
+  /** Computes the sphere geometry from the default (unset) shape parameters. */
   createDefaultGeometry() {
     return PacemSphereElement_1.createMeshGeometry();
   }
@@ -2792,6 +2840,7 @@ var __decorate18 = function(decorators, target, key, desc) {
 };
 var PacemTorusElement_1;
 var PacemTorusElement = PacemTorusElement_1 = class PacemTorusElement2 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 = 0.25, segments = 24, sides = 12) {
     const nodes = [];
     const uv = [];
@@ -2836,6 +2885,7 @@ var PacemTorusElement = PacemTorusElement_1 = class PacemTorusElement2 extends P
     computeSharpVertexNormals(geom);
     return geom;
   }
+  /** Computes the torus geometry from the default (unset) shape parameters. */
   createDefaultGeometry() {
     return PacemTorusElement_1.createMeshGeometry();
   }
@@ -2886,15 +2936,22 @@ function _clipPoint(evt, rect) {
   return { x: clipX, y: clipY };
 }
 var AdapterUtils = class _AdapterUtils {
+  /** Returns whether the given object is a {@link MeshGeometry} (has `positions` and `triangleIndices` arrays). */
   static isMeshGeometry(obj) {
     return "positions" in obj && Utils12.isArray(obj.positions) && "triangleIndices" in obj && Utils12.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) {
@@ -2908,6 +2965,10 @@ var AdapterUtils = class _AdapterUtils {
     }
     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);
   }
@@ -3611,6 +3672,12 @@ var WGSLBindingType;
 
 // packages/3d/dist/esm/adapters/webgpu/buffers.js
 var Buffers = class {
+  /**
+   * 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,
@@ -3636,6 +3703,12 @@ var Buffers = class {
       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,
@@ -3793,6 +3866,12 @@ fn getVertexColor(index: u32) -> vec4f {
 
 // packages/3d/dist/esm/adapters/webgpu/materials.js
 var Materials = class {
+  /**
+   * 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);
@@ -3846,6 +3925,10 @@ var BasicMaterial = class extends MaterialBase {
       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" && !Utils16.isNull(material.texture)) {
@@ -3873,6 +3956,12 @@ var LineMaterial = class extends MaterialBase {
       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":
@@ -3884,6 +3973,7 @@ var LineMaterial = class extends MaterialBase {
         return super.buffer(ctx);
     }
   }
+  /** Lines have no texture support; always returns `null`. */
   texture(_) {
     return null;
   }
@@ -4412,9 +4502,15 @@ var OrthographicCamera = 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.subtract(target, eye);
@@ -4428,9 +4524,11 @@ var OrthographicCamera = class _OrthographicCamera {
     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);
   }
@@ -4439,16 +4537,25 @@ var PerspectiveCamera = 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);
   }
@@ -4497,6 +4604,13 @@ var RenderLooper = class {
   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];
@@ -4525,6 +4639,11 @@ var RenderLooper = class {
   }
 };
 var ManagedBuffers = class {
+  /**
+   * 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_" + Utils23.uniqueCode();
@@ -4540,9 +4659,22 @@ var ManagedBuffers = class {
   }
 };
 var RenderableBuffers = 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) {
@@ -4552,6 +4684,11 @@ var RenderableBuffers = class _RenderableBuffers {
       }
     }
   }
+  /**
+   * 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;
@@ -5258,6 +5395,7 @@ var RenderPipelines = class _RenderPipelines {
   static {
     this._memoizer = /* @__PURE__ */ 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);
@@ -5266,6 +5404,12 @@ var RenderPipelines = class _RenderPipelines {
       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 || renderPipeline instanceof LineRenderPipelineClass) {
@@ -5275,6 +5419,20 @@ var RenderPipelines = class _RenderPipelines {
     }
     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);
@@ -6370,6 +6528,7 @@ var Raycasters = class {
   static {
     this._memoizer = /* @__PURE__ */ 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)) {
@@ -6552,6 +6711,12 @@ var WebGPUIssueCause;
   WebGPUIssueCause2[WebGPUIssueCause2["Disabled"] = 1] = "Disabled";
 })(WebGPUIssueCause || (WebGPUIssueCause = {}));
 var Renderers = class {
+  /**
+   * 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) {
@@ -6967,6 +7132,7 @@ var Pacem3DWgslScriptElement = class Pacem3DWgslScriptElement2 extends Component
     return CustomElementUtils3.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;
   }
@@ -7030,9 +7196,11 @@ var Pacem3DWebgpuAdapterElement = class Pacem3DWebgpuAdapterElement2 extends Pac
     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)) {
@@ -7043,6 +7211,7 @@ var Pacem3DWebgpuAdapterElement = class Pacem3DWebgpuAdapterElement2 extends Pac
     }
     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);
@@ -7058,9 +7227,11 @@ var Pacem3DWebgpuAdapterElement = class Pacem3DWebgpuAdapterElement2 extends Pac
   #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;
   }
@@ -7660,6 +7831,10 @@ var __decorate22 = function(decorators, target, key, desc) {
   return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 var OBJParser = class {
+  /**
+   * 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) {
     const vertices = [];
     const vParser = /^v((\s+-?[\d\.]+){3})/gm;
@@ -7723,6 +7898,10 @@ var OBJParser = class {
   }
 };
 var Parser3D = class {
+  /**
+   * 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":