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

package/typings/index.d.ts

@@ -11,27 +11,46 @@ import { Rect } from '@pacem/pacem-foundation';
 import { Rgba } from '@pacem/pacem-foundation';
 import { Size } from '@pacem/pacem-foundation';
 
+/** 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. */
 declare class AdapterUtils {
+    /** Returns whether the given object is a {@link MeshGeometry} (has `positions` and `triangleIndices` arrays). */
     static isMeshGeometry(obj: any): obj is MeshGeometry;
+    /** Returns whether the given object is a {@link Vector3D} (has numeric `x`/`y`/`z`). */
     static isVector3D(obj: any): obj is Vector3D;
+    /** Returns whether the given object is an {@link Rgba} color (has numeric `r`/`g`/`b`). */
     static isRgba(obj: any): obj is Rgba;
+    /**
+     * 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: Vector3D[] | UVMap | Rgba[]): number[];
+    /**
+     * Returns the first non-hidden {@link Camera} among the given renderables, if any.
+     * @param items Renderable items to search
+     */
     static findCamera(items: Renderable[]): Camera;
+    /** Converts a viewport-relative point into WebGL/WebGPU clip space (-1..1 on both axes). */
     clipPixel(viewportPoint: Point): Point;
+    /** Converts a pointer event's page coordinates into clip space, relative to the given canvas. */
     clipPixel(evt: PointerEventLike, canvas: HTMLCanvasElement): Point;
+    /** Converts a pointer event's page coordinates into clip space, relative to the given viewport rectangle. */
     clipPixel(evt: PointerEventLike, viewport: Rect): Point;
 }
 
+/** A {@link Material} using the unlit ("basic") shading model: rendered at flat {@link Material.color}, unaffected by scene lighting. */
 declare interface BasicMaterial extends Material {
     readonly shader: KnownShader.Basic;
 }
 
+/** `<pacem-3d-material-basic>`: produces a {@link BasicMaterial} (unlit shading model): rendered at flat color, unaffected by scene lighting. */
 declare class BasicMaterialElement extends MaterialElement {
     constructor();
 }
 
+/** Converts an attribute string to/from either a `boolean` (`"true"`/`"false"`) or a `number`. */
 declare const BooleanOrNumberConverter: PropertyConverter;
 
+/** Axis-aligned bounding box in 3d world space. */
 declare interface Box3D {
     minX: number;
     minY: number;
@@ -41,12 +60,15 @@ declare interface Box3D {
     maxZ: number;
 }
 
+/** A {@link Renderable} viewpoint used to render the scene: perspective ({@link PerspectiveCamera}) or orthographic ({@link OrthographicCamera}). */
 declare interface Camera extends Renderable {
     /** Target in world coordinates. */
     lookAt: Vector3D;
     /** Up vector in world coordinates. */
     up: Vector3D;
+    /** Near clipping plane distance. */
     near: number;
+    /** Far clipping plane distance. */
     far: number;
 }
 
@@ -70,6 +92,7 @@ declare function computePlaneNormal(a: Vector3D, b: Vector3D, c: Vector3D): Vect
  */
 declare function computeSharpVertexNormals(geometry: MeshGeometry): void;
 
+/** A {@link Material} whose shading model accounts for diffuse (matte) reflection of scene lighting. */
 declare interface DiffuseMaterial extends Material {
     /** Diffuse color, albedo. */
     emissiveColor?: string;
@@ -79,11 +102,15 @@ declare interface DiffuseMaterial extends Material {
     refractionRatio?: number;
 }
 
+/** Event dispatched while a {@link Renderable} item is being dragged (`itemdragstart`/`itemdrag`/`itemdragend`-like events), carrying a {@link DragEventArgs} payload. */
 declare class DragEvent_2 extends UI3DEvent<DragEventArgs> {
 }
 
+/** Payload carried by a {@link DragEvent}: the dragged {@link Renderable} item and its drag offset. */
 declare interface DragEventArgs {
+    /** Gets the drag displacement. */
     readonly offset: Point;
+    /** Gets the item being dragged. */
     readonly item: Renderable;
 }
 
@@ -260,58 +287,84 @@ export declare namespace Drawing3D_2 {
     }
 }
 
+/** User-supplied callback (see {@link WGSLModifierDelegates.fragment}) that returns extra WGSL statements to splice into the fragment stage. */
 declare type FragmentModifierDelegate = (...args: FragmentModifierDelegateArgs) => string;
 
+/** Tuple of WGSL identifiers passed to a {@link FragmentModifierDelegate}: world position, instance index, time, cursor and viewport-size references, so custom snippets can reference them. */
 declare type FragmentModifierDelegateArgs = [worldPositionRef: string, instanceIndexRef: string, timeRef: string, cursorRef: string, sizeRef: string];
 
+/** A {@link Ui3DObject} that contains other {@link Renderable}s, as produced by {@link Pacem3DGroupElement}. */
 declare interface Group extends Ui3DObject {
+    /** Gets the renderable children currently belonging to the group. */
     childRenderables: Renderable[];
 }
 
+/** Snapshot of the current pointer/viewport interaction state, as consumed by a WebGPU render pass for hit-testing/uniforms. */
 declare interface Interaction {
+    /** Timestamp (as returned by `performance.now()`) of the current frame. */
     time: number;
     cursor: Point;
     resolution: Size;
 }
 
+/** Type guard checking whether `obj` implements the {@link BasicMaterial} contract. */
 declare function isBasicMaterial(obj: any): obj is BasicMaterial;
 
+/** Type guard checking whether `object` implements the {@link Camera} contract. */
 declare function isCamera(object: any): object is Camera;
 
+/** Type guard checking whether `object` implements the {@link NodeGeometry} contract. */
 declare function isGeometry(object: any): object is NodeGeometry;
 
+/** Type guard checking whether `object` implements the {@link Group} contract. */
 declare function isGroup(object: any): object is Group;
 
+/** Type guard checking whether `object` implements the {@link Interaction} contract. */
 declare function isInteraction(object: any): object is Interaction;
 
+/** Type guard checking whether `obj` implements the {@link LambertMaterial} contract. */
 declare function isLambertMaterial(obj: any): obj is LambertMaterial;
 
+/** Type guard checking whether `object` implements the {@link Light} contract. */
 declare function isLight(object: any): object is Light;
 
+/** Type guard checking whether `obj` implements the {@link LineMaterial} contract. */
 declare function isLineMaterial(obj: any): obj is LineMaterial;
 
+/** Type guard checking whether `obj` implements the {@link Material} contract. */
 declare function isMaterial(obj: any): obj is Material;
 
+/** Type guard checking whether `object` implements the {@link Mesh} contract. */
 declare function isMesh(object: any): object is Mesh;
 
+/** Type guard checking whether `object` implements the {@link MeshGeometry} contract (a {@link NodeGeometry} with triangle indices/normals/UVs). */
 declare function isMeshGeometry(object: any): object is MeshGeometry;
 
+/** Type guard checking whether `object` is an {@link OrthographicCamera}. */
 declare function isOrthographicCamera(object: any): object is OrthographicCamera;
 
+/** Type guard checking whether `object` is a {@link PerspectiveCamera}. */
 declare function isPerspectiveCamera(object: any): object is PerspectiveCamera;
 
+/** Type guard checking whether `obj` implements the {@link PhongMaterial} contract. */
 declare function isPhongMaterial(obj: any): obj is PhongMaterial;
 
+/** Type guard checking whether `object` implements the {@link Renderable} contract (i.e. it is attached to a valid {@link Stage}). */
 declare function isRenderable(object: any): object is Renderable;
 
+/** Type guard checking whether `obj` implements the {@link ShaderMaterial} contract. */
 declare function isShaderMaterial(obj: any): obj is ShaderMaterial;
 
+/** Type guard checking whether `object` implements the {@link Stage} contract. */
 declare function isStage(object: any): object is Stage;
 
+/** Type guard checking whether `obj` implements the {@link StandardMaterial} contract. */
 declare function isStandardMaterial(obj: any): obj is StandardMaterial;
 
+/** Type guard checking whether `object` implements the {@link Ui3DObject} contract (i.e. it exposes a {@link Ui3DObject.transformMatrix}). */
 declare function isUi3DObject(object: any): object is Ui3DObject;
 
+/** Identifies the shading model (and, correspondingly, the concrete `Material` shape) applied to a mesh's faces. */
 declare enum KnownShader {
     Basic = "basic",
     Lambert = "lambert",
@@ -321,128 +374,216 @@ declare enum KnownShader {
     Custom = "custom"
 }
 
+/** A {@link DiffuseMaterial} using the Lambertian shading model: matte, non-specular reflection with no glossy highlights. */
 declare interface LambertMaterial extends DiffuseMaterial {
     readonly shader: KnownShader.Lambert;
 }
 
+/** `<pacem-3d-material-lambert>`: produces a {@link LambertMaterial} (Lambertian shading model): matte, non-specular reflection of scene lighting, with no glossy highlights. */
 declare class LambertMaterialElement extends MaterialElement {
     constructor();
+    /** Builds the {@link LambertMaterial}, adding `emissiveColor`, `reflectivity` and `refractionRatio` to the base {@link Material}. */
     protected createMaterial(): Promise<LambertMaterial>;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
+    /** Gets or sets the diffuse color (albedo). */
     emissiveColor: string;
+    /** Gets or sets the percentage of reflected light. */
     reflectivity: number;
+    /** Gets or sets the index of refraction. */
     refractionRatio: number;
 }
 
+/** A {@link Renderable} light source (spot, directional, point/omni or ambient), as produced by {@link Pacem3DLightElement}. */
 declare interface Light extends Renderable {
+    /** Gets or sets the light intensity/brightness. */
     intensity: number;
+    /** Gets or sets the point the light is aimed at (spotlight-specific). */
     target?: Vector3D;
+    /** Gets or sets the light color. */
     color: string;
+    /** Gets or sets the kind of light source. */
     type: 'spot' | 'direction' | 'omni' | 'ambient';
+    /** Distance at which the spotlight intensity starts to fall off (spotlight-specific). */
     attenuationStart?: number;
+    /** Distance beyond which the spotlight has no effect (spotlight-specific). */
     attenuationEnd?: number;
+    /** Cone angle, in degrees (spotlight-specific). */
     angle?: number;
 }
 
+/** A {@link NodeGeometry} rendered as a polyline through its {@link positions} (no faces/triangles). */
 declare class LineGeometry extends NodeGeometry {
+    /** Gets or sets the vertex positions, in local space; reassigning this array flags the geometry as dirty. */
     positions: Vector3D_2[];
 }
 
+/** A {@link Material} for rendering {@link PacemLineElement} polylines: stroke width, joins, caps and dash pattern. */
 declare interface LineMaterial extends Material {
     readonly shader: KnownShader.Line;
+    /** Gets or sets the stroke width, in local units. */
     lineWidth: number;
+    /** Gets or sets how consecutive line segments are joined. */
     lineJoin?: CanvasLineJoin;
+    /** Gets or sets how the line's endpoints are capped. */
     lineCap?: CanvasLineCap;
+    /** Gets or sets the alternating dash/gap lengths, or `undefined`/empty for a solid line. */
     dashArray?: number[];
 }
 
+/** `<pacem-3d-material-line>`: produces a {@link LineMaterial} for rendering {@link PacemLineElement} polylines (stroke width, joins, caps, dash pattern). */
 declare class LineMaterialElement extends MaterialElement {
     constructor();
+    /** Gets or sets the stroke width, in local units. */
     lineWidth: number;
+    /** Gets or sets how consecutive line segments are joined. */
     lineJoin?: CanvasLineJoin;
+    /** Gets or sets how the line's endpoints are capped. */
     lineCap?: CanvasLineCap;
+    /** Gets or sets the alternating dash/gap lengths (comma-separated as an attribute), or unset for a solid line. */
     dashArray?: number[];
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
+    /** Builds the {@link LineMaterial}, adding `lineWidth`, `lineJoin`, `lineCap` and `dashArray` to the base {@link Material}. */
     protected createMaterial(): Promise<LineMaterial>;
 }
 
+/** Plain-data contract shared by every shading model, produced by a {@link MaterialElement} and consumed by the rendering adapter. */
 declare interface Material {
+    /** Opacity, from `0` (fully transparent) to `1` (fully opaque). */
     opacity?: number;
+    /** Renders the faces as a wireframe (edges only) instead of solid, shaded surfaces. */
     wireframe?: boolean;
     /** Object color. */
     color?: string | Rgba;
+    /** Whether the object is rendered at all. */
     visible?: boolean;
     /** Texture map. */
     map?: string;
+    /** The decoded bitmap of {@link map}, loaded asynchronously. */
     texture?: ImageBitmap;
     /** Renders each face as flat. */
     flatShading?: boolean;
+    /** Identifies the shading model this material implements. */
     readonly shader: KnownShader;
+    /** Gets the list of {@link StalePropertyFlag}s accumulated since the material was last consumed by the adapter/renderer. */
     flags: StalePropertyFlag[];
 }
 
+/**
+ * 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.
+ */
 declare abstract class MaterialElement extends PacemEventTarget {
     #private;
+    /** @param shader The {@link KnownShader} this element's {@link createMaterial} produces. */
     constructor(shader: KnownShader);
+    /** Gets the shading model this element produces materials for. */
     get shader(): KnownShader;
     private _loadMap;
+    /** Gets or sets the computed {@link Material}, recomputed by {@link updateMaterial} whenever a shading attribute changes. */
     material: Material;
+    /** Gets or sets the opacity, from `0` (fully transparent) to `1` (fully opaque). */
     opacity: number;
+    /** Gets or sets whether faces render as a wireframe (edges only) instead of solid, shaded surfaces. */
     wireframe: boolean;
+    /** Gets or sets the object color (defaults to the `--pacem-color-primary` CSS custom property when unset). */
     color: string;
+    /** Gets or sets whether the object is hidden (not rendered). */
     hide: boolean;
+    /** Gets or sets the URL of the texture map to load into {@link Material.texture}. */
     map?: string;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
     viewActivatedCallback(): void;
+    /** Recomputes {@link material} via {@link createMaterial}, flagging it as {@link StalePropertyFlag.Material}. */
     protected updateMaterial(): void;
+    /** 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. */
     protected createMaterial(): Promise<Material>;
 }
 
+/** A 4x4 3d transform matrix (rotation, scale, translation). */
 declare type Matrix3D = Geometry.LinearAlgebra.Matrix3D;
 
+/** A {@link Ui3DObject} with a {@link NodeGeometry} (vertex data) and up to two {@link Material}s (front/back face), as produced by {@link Pacem3DMeshElement}. */
 declare interface Mesh extends Ui3DObject {
+    /** Gets or sets the vertex/index data defining the mesh's shape. */
     geometry: NodeGeometry;
+    /** Gets or sets the material applied to front-facing faces. */
     material?: Material;
+    /** Gets or sets the material applied to back-facing faces (defaults to {@link material} when unset). */
     backMaterial?: Material;
 }
 
+/** A {@link NodeGeometry} for triangulated surfaces: adds triangle vertex indices, per-vertex UV texture coordinates and normals. */
 declare interface MeshGeometry extends NodeGeometry {
+    /** Gets or sets the vertex indices forming the mesh's triangles (each consecutive triplet is one face). */
     triangleIndices: number[];
+    /** Gets or sets the per-vertex texture (u, v) coordinates. */
     textureCoordinates: UVMap;
+    /** Gets or sets the per-vertex normals, used for lighting. */
     normals: Vector3D_2[];
 }
 
+/** A {@link MeshGeometry} implementation with lazily-computed {@link barycenter}/{@link boundingBox} and settable {@link boundingSphere}, used as the `geometry` of a {@link Pacem3DMeshElement}. */
 declare class MeshGeometry extends NodeGeometry {
     #private;
+    /** Gets or sets the centroid of {@link positions}; computed on first access if not explicitly set. */
     get barycenter(): Vector3D_2;
     set barycenter(point: Vector3D_2);
+    /** Gets or sets the axis-aligned bounding box; computed from {@link positions} on first access if not explicitly set. */
     get boundingBox(): Box3D;
     set boundingBox(bbox: Box3D);
+    /** Gets or sets the bounding sphere. */
     get boundingSphere(): Sphere3D;
     set boundingSphere(sphere: Sphere3D);
     constructor(positions: Vector3D_2[], triangleIndices: number[], textureCoordinates?: UVMap, normals?: Vector3D_2[]);
+    /** Gets or sets the vertex positions, in local space; reassigning this array flags the geometry as dirty. */
     positions: Vector3D_2[];
+    /** Gets or sets the vertex indices forming the mesh's triangles; reassigning this array flags the geometry as dirty. */
     triangleIndices: number[];
+    /** Gets or sets the per-vertex texture (u, v) coordinates; reassigning this array flags the geometry as dirty. */
     textureCoordinates: UVMap;
+    /** Gets or sets the per-vertex normals; reassigning this array flags the geometry as dirty. */
     normals: Vector3D_2[];
 }
 
+/** Vertex data contract shared by all geometry kinds ({@link LineGeometry}, {@link MeshGeometry}): a set of positions plus their derived bounding volumes. */
 declare interface NodeGeometry {
+    /** Gets or sets the vertex positions, in local space. */
     positions: Vector3D_2[];
+    /** Gets or sets the axis-aligned bounding box, computed from {@link positions} when unset. */
     boundingBox?: Box3D;
+    /** Gets or sets the centroid of {@link positions}, computed on demand when unset. */
     barycenter?: Vector3D_2;
+    /** Gets or sets the bounding sphere. */
     boundingSphere?: Sphere3D;
+    /** Gets the list of {@link StalePropertyFlag}s accumulated since the geometry was last consumed by the adapter/renderer. */
     flags: StalePropertyFlag[];
+    /** Gets or sets an identity key, used by adapters/renderers to track the geometry across updates. */
     key?: string;
 }
 
+/**
+ * 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.
+ */
 declare abstract class NodeGeometry {
     constructor(positions?: Vector3D_2[]);
+    /** Computes the centroid (average) of the given positions. */
     static barycenter(positions: Vector3D_2[]): Vector3D_2;
+    /** Computes the axis-aligned {@link Box3D} enclosing the given positions. */
     static boundingBox(positions: Vector3D_2[]): Box3D;
+    /** Marks the geometry as stale, flagging it with {@link StalePropertyFlag.Geometry} for the next render. */
     protected setAsDirty(): void;
 }
 
+/**
+ * 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.
+ */
 declare function NotifyChange(callback: (property?: string, old?: any, val?: any) => void): (target: any, prop: string, descriptor?: PropertyDescriptor) => void;
 
 declare class OrbitCameraBehavior {
@@ -499,6 +640,7 @@ declare type OrbitCameraControl = {
     modifiers?: EventKeyModifier[];
 };
 
+/** A {@link Camera} that projects the scene with a fixed, non-diminishing frustum (parallel projection), as produced by {@link Pacem3DOrthographicCameraElement}. */
 declare interface OrthographicCamera extends Camera {
     type: "orthographic";
     /** Top frustum coordinate (e.g. 1). */
@@ -511,6 +653,12 @@ declare interface OrthographicCamera extends Camera {
     right: number;
 }
 
+/**
+ * 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.
+ */
 declare abstract class Pacem3DAdapterElement extends PacemEventTarget {
     /**
      * When implemented in a derived class, resizes the stage.
@@ -555,6 +703,10 @@ declare abstract class Pacem3DAdapterElement extends PacemEventTarget {
      * @param items
      */
     abstract zoomFit(scene: Pacem3DElement, ...items: Ui3DObject[]): Promise<void>;
+    /**
+     * When implemented in a derived class, projects a 3d world-space point onto the 2d viewport (screen) coordinates.
+     * @param point3D Point in 3d world space.
+     */
     abstract project(scene: Pacem3DElement, point3D: Vector3D): Point;
     /** Gets the native scene instance */
     abstract getScene(scene: Pacem3DElement): any;
@@ -565,13 +717,23 @@ declare abstract class Pacem3DAdapterElement extends PacemEventTarget {
     abstract dispose(scene: Pacem3DElement): void;
 }
 
+/**
+ * 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}.
+ */
 declare abstract class Pacem3DCameraElement extends RenderableElement implements Camera {
     #private;
+    /** Gets or sets the near clipping plane distance. */
     near: number;
+    /** Gets or sets the far clipping plane distance. */
     far: number;
+    /** Gets or sets the up vector, in world coordinates. */
     up: Vector3D;
+    /** Gets or sets the target the camera looks at, in world coordinates. */
     lookAt: Vector3D;
     private _resetBoundingSphere;
+    /** @readonly Gets the sphere centered on {@link lookAt} with radius equal to the eye-to-target distance. */
     get boundingSphere(): Sphere3D;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
 }
@@ -579,7 +741,9 @@ declare abstract class Pacem3DCameraElement extends RenderableElement implements
 /** @deprecated*/
 declare class Pacem3DDetector {
     private _detected;
+    /** Probes the browser for WebGL support by attempting to create a rendering context, populating {@link info} and {@link supported}. */
     constructor();
+    /** @readonly Gets the detected WebGL capabilities/limits, grouped by section (`main`, `bits`, `shader`, `tex`, `misc`). */
     get info(): {
         main?: any;
         bits?: any;
@@ -587,22 +751,36 @@ declare class Pacem3DDetector {
         tex?: any;
         misc?: any;
     };
+    /** @readonly Gets whether a WebGL rendering context could be created on this browser/device. */
     get supported(): boolean;
 }
 
+/**
+ * `<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.
+ */
 declare class Pacem3DElement extends Components_2.PacemItemsContainerElement<RenderableElement> implements Stage {
     #private;
     validate(item: RenderableElement): boolean;
     private _container;
     private _resizer;
+    /** Gets or sets whether the stage listens for pointer interactions (hover/click/drag) and dispatches the corresponding events. */
     interactive: boolean;
+    /** Gets or sets whether the stage background should be transparent. */
     transparent: boolean;
+    /** Gets or sets the stage background color (ignored when {@link transparent} is set). */
     background: string;
+    /** Gets or sets the {@link Pacem3DAdapterElement} rendering backend (e.g. a {@link Pacem3DThreeAdapterElement} or {@link Pacem3DWebgpuAdapterElement}) used to actually build/render the scene. */
     adapter: Pacem3DAdapterElement;
+    /** Gets or sets the renderable items, as an alternative/complement to declaring them in markup. */
     datasource: Renderable[];
     /** @deprecated */
     orbit: boolean;
+    /** @readonly Gets the DOM element the scene is mounted into. */
     get stage(): HTMLElement;
+    /** @readonly Gets the technology-dependent native scene instance, as reported by the active {@link adapter}. */
     get scene(): any;
     register(item: RenderableElement): boolean;
     unregister(item: RenderableElement): boolean;
@@ -620,64 +798,106 @@ declare class Pacem3DElement extends Components_2.PacemItemsContainerElement<Ren
     private _hitTestCallback;
     private _moveHandler;
     disconnectedCallback(): void;
+    /** @readonly Gets the current viewport size, as last reported by the internal resize observer. */
     get size(): Size;
     private _resizeHandler;
+    /** Renders the whole scene through the active {@link adapter}, or just updates the given `item` if provided. */
     render(item?: Renderable, deepUpdate?: boolean, now?: number): void;
     private _doRender;
 }
 
+/** `<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. */
 declare class Pacem3DGroupElement extends Ui3DElement implements Group {
     #private;
     validate(child: RenderableElement): boolean;
+    /** Gets or sets the renderable children, as an alternative to declaring them in markup. */
     datasource: Renderable[];
+    /** @readonly Gets the renderable children currently belonging to the group. */
     get childRenderables(): Renderable[];
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
 }
 
+/** `<pacem-3d-light>`: a {@link RenderableElement} light source (point/omni, spot or directional) illuminating the scene. */
 declare class Pacem3DLightElement extends RenderableElement implements Light {
+    /** Gets or sets the light intensity/brightness. */
     intensity: number;
+    /** Gets or sets the point the light is aimed at (spotlight-specific). */
     target: Vector3D;
+    /** Gets or sets the light color. */
     color: string;
+    /** Gets or sets the kind of light source. */
     type: 'spot' | 'direction' | 'omni';
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
 }
 
+/** `<pacem-3d-mesh>`: a {@link Ui3DElement} that renders a {@link NodeGeometry} (mesh or line) with a front/back {@link Material}. */
 declare class Pacem3DMeshElement extends Ui3DElement implements Mesh {
+    /** Gets or sets the vertex/index data defining the mesh's shape. */
     geometry: NodeGeometry;
+    /** Gets or sets the material applied to front-facing faces. */
     material: Material;
+    /** Gets or sets the material applied to back-facing faces (defaults to {@link material} when unset). */
     backMaterial: Material;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
 }
 
+/** `<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. */
 declare class Pacem3DObjectElement extends Ui3DElement {
+    /** Gets or sets the raw asset content (format depends on {@link type}) to parse/load. */
     content: any;
+    /** Gets or sets the format of {@link content} (e.g. `"obj"`, `"fbx"`, or `"native"` for an adapter-specific object). */
     type: string | "obj" | "fbx" | "native";
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
 }
 
+/** `<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. */
 declare class Pacem3DOrthographicCameraElement extends Pacem3DCameraElement implements OrthographicCamera {
+    /** Gets or sets the top frustum coordinate (e.g. 1). */
     top: number;
+    /** Gets or sets the left frustum coordinate (e.g. -1). */
     left: number;
+    /** Gets or sets the bottom frustum coordinate (e.g. -1). */
     bottom: number;
+    /** Gets or sets the right frustum coordinate (e.g. 1). */
     right: number;
+    /** @readonly Gets the camera discriminator: always `"orthographic"`. */
     get type(): "orthographic";
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
 }
 
+/** `<pacem-3d-perspective-camera>`: a {@link Pacem3DCameraElement} that projects the scene through a perspective frustum (vanishing point), defined by {@link fov} and {@link aspect}. */
 declare class Pacem3DPerspectiveCameraElement extends Pacem3DCameraElement implements PerspectiveCamera {
+    /** Gets or sets the vertical field of view, in degrees. */
     fov: number;
+    /** Gets or sets the viewport width/height ratio. */
     aspect: number;
+    /** @readonly Gets the camera discriminator: always `"perspective"`. */
     get type(): "perspective";
+    /** @readonly Gets the viewport width/height ratio (alias of {@link aspect}). */
     get aspectRatio(): number;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
 }
 
+/**
+ * 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.
+ */
 declare abstract class Pacem3DPrimitiveElement extends PacemEventTarget {
+    /** Gets or sets the computed vertex/index data describing the primitive's shape. */
     geometry: NodeGeometry;
     viewActivatedCallback(): void;
+    /** Computes the geometry to fall back to when {@link geometry} hasn't been explicitly set. */
     protected abstract createDefaultGeometry(): NodeGeometry;
 }
 
+/**
+ * `<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}.
+ */
 declare class Pacem3DThreeAdapterElement extends Pacem3DAdapterElement {
     private _assertMonoStage;
     dispose(scene: Pacem3DElement): void;
@@ -692,6 +912,7 @@ declare class Pacem3DThreeAdapterElement extends Pacem3DAdapterElement {
     private _orbitCtrls;
     private _objects;
     private _dict;
+    /** Gets or sets whether mouse-driven orbit controls (`THREE.OrbitControls`) are attached to the active camera. */
     orbit: boolean;
     getScene(scene: Pacem3DElement): any;
     raycast(scene: Pacem3DElement, point: Point, size: Size, callback: (result: RaycastResult) => void): void;
@@ -711,14 +932,25 @@ declare class Pacem3DThreeAdapterElement extends Pacem3DAdapterElement {
     render(): void;
 }
 
+/**
+ * `<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.
+ */
 declare class Pacem3DWebgpuAdapterElement extends Pacem3DAdapterElement implements ItemsContainer<Pacem3DWgslScriptElement> {
     #private;
     invalidateSize(stage: Pacem3DElement, size?: Size): void;
+    /** @readonly Gets the child {@link Pacem3DWgslScriptElement} shader-customization items currently registered. */
     get items(): Pacem3DWgslScriptElement[];
+    /** Registers a child {@link Pacem3DWgslScriptElement}, re-parsing the WGSL {@link modifiers} it contributes. */
     register(item: Pacem3DWgslScriptElement): boolean;
+    /** Unregisters a previously-registered {@link Pacem3DWgslScriptElement}, re-parsing the WGSL {@link modifiers} accordingly. */
     unregister(item: Pacem3DWgslScriptElement): boolean;
     private _scriptVersionChangeHandler;
+    /** @readonly Gets whether WebGPU is supported by the current browser/device. */
     get supported(): boolean;
+    /** @readonly Gets whether the adapter is currently able to render (false once a {@link WebGPUIssue} disables it). */
     get active(): boolean;
     private _webGPUNotSupported;
     initialize(scene: Pacem3DElement): Promise<HTMLCanvasElement | null>;
@@ -727,7 +959,9 @@ declare class Pacem3DWebgpuAdapterElement extends Pacem3DAdapterElement implemen
     disconnectedCallback(): void;
     dispose(scene: Pacem3DElement): void;
     private _reinitialize;
+    /** Gets or sets the WGSL snippets (vertex input/output, fragment) spliced into the render pipeline shaders, normally derived from the child {@link Pacem3DWgslScriptElement} items. Reassigning it reinitializes the renderer(s). */
     modifiers: WGSLModifierDelegates;
+    /** Gets or sets whether WebGPU API validation is enabled (useful for debugging, at a performance cost). Reassigning it reinitializes the renderer(s). */
     enableValidation: boolean;
     private _ensureRenderer;
     private _updatePipeline;
@@ -748,11 +982,15 @@ declare class Pacem3DWebgpuAdapterElement extends Pacem3DAdapterElement implemen
     getScene(stage: Pacem3DElement): any;
 }
 
+/** `<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. */
 declare class Pacem3DWgslScriptElement extends Components_2.PacemItemElement {
     #private;
     protected findContainer(): ItemsContainer<Pacem3DWgslScriptElement>;
+    /** @readonly Gets a hash of the current {@link wgsl} content, changing whenever it does. */
     get version(): string;
+    /** Gets or sets which pipeline stage this WGSL snippet modifies (e.g. `"vertex-input"`, `"vertex-output"`, `"fragment"`). */
     type: WGSLModifierScriptType;
+    /** Gets or sets the WGSL source code, normally mirrored from the element's text content. */
     wgsl: string;
     viewActivatedCallback(): void;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
@@ -760,76 +998,126 @@ declare class Pacem3DWgslScriptElement extends Components_2.PacemItemElement {
     disconnectedCallback(): void;
 }
 
+/** `<pacem-3d-primitive-box>`: computes the {@link MeshGeometry} of a rectangular cuboid (box). */
 declare class PacemBoxElement extends Pacem3DPrimitiveElement {
+    /** Gets or sets the size along the x axis. */
     width: number;
+    /** Gets or sets the size along the y axis. */
     height: number;
+    /** Gets or sets the size along the z axis. */
     depth: number;
+    /** Gets or sets the number of subdivisions along the width (x axis). */
     widthSegments: number;
+    /** Gets or sets the number of subdivisions along the height (y axis). */
     heightSegments: number;
+    /** Gets or sets the number of subdivisions along the depth (z axis). */
     depthSegments: number;
+    /** Builds the {@link MeshGeometry} of a box with the given size and per-axis segment subdivisions (all default to `1`). */
     static createMeshGeometry(width?: number, height?: number, depth?: number, widthSegments?: number, heightSegments?: number, depthSegments?: number): MeshGeometry;
+    /** Computes the box geometry from the default (unset) shape parameters. */
     protected createDefaultGeometry(): MeshGeometry;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
 }
 
+/** `<pacem-3d-primitive-cone>`: computes the {@link MeshGeometry} of a cone (a circular base tapering to an apex point). */
 declare class PacemConeElement extends Pacem3DPrimitiveElement {
+    /** Gets or sets the radius of the circular base. */
     radius: number;
+    /** Gets or sets the distance from the base to the apex. */
     height: number;
+    /** Gets or sets the number of straight sides (radial segments) approximating the circular base. */
     sides: number;
+    /** Gets or sets the number of subdivisions along the lateral surface, from base to apex. */
     heightSegments: number;
+    /** Gets or sets the number of concentric ring subdivisions of the base cap. */
     capSegments: number;
+    /** 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?: number, height?: number, sides?: number, heightSegments?: number, capSegments?: number): MeshGeometry;
+    /** Computes the cone geometry from the default (unset) shape parameters. */
     protected createDefaultGeometry(): MeshGeometry;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
 }
 
+/** `<pacem-3d-primitive-cylinder>`: computes the {@link MeshGeometry} of a cylinder (two parallel circular caps joined by a straight lateral surface). */
 declare class PacemCylinderElement extends Pacem3DPrimitiveElement {
+    /** Gets or sets the radius of the top and bottom circular caps. */
     radius: number;
+    /** Gets or sets the distance between the top and bottom caps. */
     height: number;
+    /** Gets or sets the number of straight sides (radial segments) approximating the circular caps. */
     sides: number;
+    /** Gets or sets the number of subdivisions along the lateral surface, from bottom to top. */
     heightSegments: number;
+    /** Gets or sets the number of concentric ring subdivisions of each cap. */
     capSegments: number;
+    /** Builds the {@link MeshGeometry} of a cylinder with the given radius, height, side count, lateral-surface segments and cap segments. */
     static createMeshGeometry(radius?: number, height?: number, sides?: number, heightSegments?: number, capSegments?: number): MeshGeometry;
+    /** Computes the cylinder geometry from the default (unset) shape parameters. */
     protected createDefaultGeometry(): MeshGeometry;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
 }
 
+/** `<pacem-3d-primitive-dodecahedron>`: computes the {@link MeshGeometry} of a regular dodecahedron (a Platonic solid with 12 pentagonal faces). */
 declare 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?: number): MeshGeometry;
     protected createMeshGeometry(radius?: number): MeshGeometry;
 }
 
+/** `<pacem-3d-primitive-hexahedron>`: computes the {@link MeshGeometry} of a regular hexahedron (a Platonic solid with 6 square faces, i.e. a cube). */
 declare 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?: number): MeshGeometry;
     protected createMeshGeometry(radius?: number): MeshGeometry;
 }
 
+/** `<pacem-3d-primitive-icosahedron>`: computes the {@link MeshGeometry} of a regular icosahedron (a Platonic solid with 20 triangular faces). */
 declare 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?: number): MeshGeometry;
     protected createMeshGeometry(radius?: number): MeshGeometry;
 }
 
+/** `<pacem-3d-primitive-line>`: computes the {@link LineGeometry} of a polyline connecting a sequence of points. */
 declare class PacemLineElement extends Pacem3DPrimitiveElement {
+    /** Gets or sets the ordered vertices of the polyline, in local space. */
     positions: Vector3D[];
+    /** 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?: Vector3D[]): LineGeometry;
+    /** Computes the line geometry from the default (unset) vertex positions. */
     protected createDefaultGeometry(): LineGeometry;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
 }
 
+/** `<pacem-3d-primitive-octahedron>`: computes the {@link MeshGeometry} of a regular octahedron (a Platonic solid with 8 triangular faces). */
 declare 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?: number): MeshGeometry;
     protected createMeshGeometry(radius?: number): MeshGeometry;
 }
 
+/**
+ * `<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.
+ */
 declare class PacemOrbitCameraBehaviorElement extends Behaviors.PacemBehavior {
     #private;
+    /** Gets or sets the maximum azimuth (horizontal orbit) angle, in degrees. */
     maxAzimuth: number;
+    /** Gets or sets the maximum polar (vertical orbit) angle, in degrees. */
     maxPolar: number;
+    /** Gets or sets the minimum azimuth (horizontal orbit) angle, in degrees. */
     minAzimuth: number;
+    /** Gets or sets the minimum polar (vertical orbit) angle, in degrees. */
     minPolar: number;
+    /** Gets or sets the pointer button/modifier configuration enabling zoom (mouse wheel). */
     zoomControl: OrbitCameraControl;
+    /** Gets or sets the pointer button/modifier configuration enabling rotation. */
     rotationControl: OrbitCameraControl;
+    /** Gets or sets the pointer button/modifier configuration enabling panning. */
     panControl: OrbitCameraControl;
+    /** Gets or sets whether (and how strongly) orbit movements ease out with inertia instead of stopping immediately; `true` uses the default friction factor, a `number` sets a custom one, `false` disables inertia. */
     inertia: boolean | number;
     private _readyHandler;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
@@ -840,124 +1128,195 @@ declare class PacemOrbitCameraBehaviorElement extends Behaviors.PacemBehavior {
     protected undecorate(element: Element): void;
 }
 
+/** `<pacem-3d-primitive-plane>`: computes the {@link MeshGeometry} of a flat rectangular surface lying on the xz plane. */
 declare class PacemPlaneElement extends Pacem3DPrimitiveElement {
+    /** Gets or sets the size along the x axis. */
     width: number;
+    /** Gets or sets the size along the z axis. */
     length: number;
+    /** Gets or sets the number of subdivisions along the width (x axis). */
     widthSegments: number;
+    /** Gets or sets the number of subdivisions along the length (z axis). */
     lengthSegments: number;
+    /** 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?: number, length?: number, widthSegments?: number, lengthSegments?: number): MeshGeometry;
+    /** Computes the plane geometry from the default (unset) shape parameters. */
     protected createDefaultGeometry(): MeshGeometry;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
 }
 
+/** `<pacem-3d-primitive-sphere>`: computes the {@link MeshGeometry} of a UV sphere. */
 declare class PacemSphereElement extends Pacem3DPrimitiveElement {
+    /** Gets or sets the radius. */
     radius: number;
+    /** Gets or sets the tessellation: the number of longitude divisions (and, derived from it, the latitude bands) around the sphere. */
     segments: number;
+    /** Builds the {@link MeshGeometry} of a sphere with the given radius (defaults to `1`) and tessellation (defaults to `8`). */
     static createMeshGeometry(radius?: number, segs?: number): MeshGeometry;
+    /** Computes the sphere geometry from the default (unset) shape parameters. */
     protected createDefaultGeometry(): MeshGeometry;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
 }
 
+/** `<pacem-3d-primitive-tetrahedron>`: computes the {@link MeshGeometry} of a regular tetrahedron (a Platonic solid with 4 triangular faces). */
 declare 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?: number): MeshGeometry;
     protected createMeshGeometry(radius?: number): MeshGeometry;
 }
 
+/** `<pacem-3d-primitive-torus>`: computes the {@link MeshGeometry} of a torus (donut shape): a tube revolved around a central axis. */
 declare class PacemTorusElement extends Pacem3DPrimitiveElement {
+    /** Gets or sets the outer radius: the distance from the torus' center to the center of the tube. */
     radius: number;
+    /** Gets or sets the inner (tube) radius: the thickness of the revolved tube. */
     innerRadius: number;
+    /** Gets or sets the number of radial segments around the main ring. */
     segments: number;
+    /** Gets or sets the number of segments around the tube's circular cross-section. */
     sides: number;
+    /** Builds the {@link MeshGeometry} of a torus with the given outer/inner radii and ring/tube segment counts. */
     static createMeshGeometry(radius?: number, innerRadius?: number, segments?: number, sides?: number): MeshGeometry;
+    /** Computes the torus geometry from the default (unset) shape parameters. */
     protected createDefaultGeometry(): MeshGeometry;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
 }
 
+/** A {@link Camera} that projects the scene with a perspective frustum (vanishing point), as produced by {@link Pacem3DPerspectiveCameraElement}. */
 declare interface PerspectiveCamera extends Camera {
     type: "perspective";
     /** Vertical field of view in degrees. */
     fov: number;
+    /** Viewport width/height ratio. */
     aspectRatio: number;
 }
 
+/** A {@link SpecularMaterial} using the Phong shading model: diffuse reflection plus a specular highlight of adjustable {@link SpecularMaterial.shininess}. */
 declare interface PhongMaterial extends SpecularMaterial {
     readonly shader: KnownShader.Phong;
 }
 
+/** `<pacem-3d-material-phong>`: produces a {@link PhongMaterial} (Phong shading model): diffuse reflection plus a specular highlight of adjustable shininess. */
 declare class PhongMaterialElement extends MaterialElement {
     constructor();
+    /** Builds the {@link PhongMaterial}, adding the diffuse (`emissiveColor`, `reflectivity`, `refractionRatio`) and specular (`specularColor`, `shininess`, `flatShading`) properties to the base {@link Material}. */
     protected createMaterial(): Promise<PhongMaterial>;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
+    /** Gets or sets the diffuse color (albedo). */
     emissiveColor: string;
+    /** Gets or sets the percentage of reflected light. */
     reflectivity: number;
+    /** Gets or sets the index of refraction. */
     refractionRatio: number;
+    /** Gets or sets the specular color, defining the color of reflections/highlights. */
     specularColor: string;
+    /** Gets or sets the specular exponent (glossiness): higher values produce smaller, sharper highlights. */
     shininess: number;
+    /** Gets or sets whether each face is rendered as flat (faceted) rather than smoothly interpolated. */
     flatShading: boolean;
 }
 
+/** Converts a `"x y z"` attribute string to/from a {@link Vector3D}. */
 declare const Point3DConverter: PropertyConverter;
 
+/** 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`. */
 declare const Point3DOrNumberConverter: PropertyConverter;
 
 declare type PointerEventLike = MouseEvent | PointerEvent | TouchEvent;
 
+/**
+ * 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}.
+ */
 declare abstract class PolyhedronElement extends Pacem3DPrimitiveElement {
+    /** Gets or sets the radius of the sphere the polyhedron's vertices lie on. */
     radius: number;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
     private _assignMeshGeometry;
+    /** Computes the polyhedron geometry using a radius of `1` when {@link radius} hasn't been explicitly set. */
     protected createDefaultGeometry(): MeshGeometry;
+    /** Computes the {@link MeshGeometry} of the polyhedron with the given radius. */
     protected abstract createMeshGeometry(radius: number): MeshGeometry;
 }
 
+/** A rotation expressed as a unit quaternion. */
 declare type Quaternion = Geometry.LinearAlgebra.Quaternion;
 
+/** Converts a `"x y z w"` attribute string to/from a {@link Quaternion}. Used e.g. for `rotate`. */
 declare const QuaternionConverter: PropertyConverter;
 
+/** Result of a {@link Pacem3DAdapterElement.raycast} hit-test: the hit {@link Renderable} object and the world-space point of intersection. */
 declare type RaycastResult = {
     object: Renderable;
     point: Vector3D;
 };
 
+/** Base contract of any object that can be part of the scene graph and rendered on a {@link Stage}. */
 declare interface Renderable {
+    /** Gets or sets the {@link Stage} this renderable is attached to. */
     stage?: Stage;
+    /** Gets or sets the object's position in 3d world (or parent-local) space. */
     position: Vector3D;
     /** Gets or sets whether the drawable is hit-testable. */
     inert?: boolean;
+    /** Gets or sets whether the object is hidden (excluded from rendering, but still part of the scene graph). */
     hide?: boolean;
+    /** Gets or sets an arbitrary user payload attached to the object. */
     tag?: any;
+    /** Gets the list of {@link StalePropertyFlag}s accumulated since the object was last rendered/updated by the adapter. */
     flags: StalePropertyFlag[];
+    /** Gets or sets an identity key, used by adapters/renderers to track the object across updates. */
     key?: string;
     /** @deprecated will be likely removed sooner or later to be handled outside the stage/adapter. */
     draggable?: boolean;
 }
 
+/**
+ * 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.
+ */
 declare abstract class RenderableElement extends Components_2.PacemCrossItemsContainerElement<RenderableElement> implements Renderable {
     #private;
+    /** When implemented in a derived class (e.g. {@link Pacem3DGroupElement}), determines whether `_` may be nested under this element. Denies any child by default. */
     validate(_: RenderableElement): boolean;
     protected findContainer(): Pacem3DElement | RenderableElement;
+    /** @readonly Gets the ancestor {@link Pacem3DElement} stage this element belongs to. */
     get stage(): Pacem3DElement;
+    /** @readonly Gets the closest ancestor {@link RenderableElement} (e.g. the containing group), if any. */
     get parent(): RenderableElement;
+    /** Gets or sets the element's position, in 3d world (or parent-local) space. */
     position: Vector3D;
+    /** Gets or sets an arbitrary user payload attached to the element. */
     tag: string;
+    /** Gets or sets whether the element is excluded from hit-testing/raycasting. */
     inert: boolean;
     disconnectedCallback(): void;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
+    /** @readonly Gets the list of {@link StalePropertyFlag}s accumulated since the element was last rendered/updated by the adapter. */
     get flags(): StalePropertyFlag[];
     /** Calls for a redraw of the current element in the next rendering process. */
     protected setAsDirty(...flags: StalePropertyFlag[]): void;
 }
 
+/** Event dispatched for pointer interactions (click/over/out/down/up) with a {@link Renderable} item, carrying the item itself as its `detail`. */
 declare class RenderableEvent extends UI3DEvent<Renderable> {
     constructor(type: string, args: Renderable, originalEvent: MouseEvent | TouchEvent | KeyboardEvent, p: Vector3D);
 }
 
+/** A {@link Material} rendered by a user-supplied GLSL vertex/fragment shader pair, bypassing the built-in shading models. */
 declare interface ShaderMaterial extends Material {
     readonly shader: KnownShader.Custom;
+    /** Gets or sets the GLSL source of the vertex shader. */
     vertexShader?: string;
+    /** Gets or sets the GLSL source of the fragment shader. */
     fragmentShader?: string;
 }
 
+/** A {@link DiffuseMaterial} that additionally models specular (glossy) highlights. */
 declare interface SpecularMaterial extends DiffuseMaterial {
     /** Specular color, defines the color of reflections. */
     specularColor?: string;
@@ -965,53 +1324,88 @@ declare interface SpecularMaterial extends DiffuseMaterial {
     shininess?: number;
 }
 
+/** Bounding sphere in 3d world space. */
 declare interface Sphere3D {
     center: Vector3D;
     radius: number;
 }
 
+/** Contract of the `<pacem-3d>` stage (see {@link Pacem3DElement}) as seen by adapters and renderables: the DOM/native surface, its size, and the entry point to trigger a (partial) render. */
 declare interface Stage extends EventTarget {
+    /** Renders the whole scene, or just the given item if provided. */
     render(item?: Renderable): any;
+    /** Gets the DOM element the scene is mounted into. */
     readonly stage: HTMLElement;
+    /** Gets the technology-dependent native scene instance (e.g. a `THREE.Scene`), as returned by the active {@link Pacem3DAdapterElement}. */
     readonly scene: any;
+    /** Gets the current viewport size. */
     readonly size: Size;
+    /** Gets or sets whether the stage background should be transparent. */
     transparent?: boolean;
+    /** Gets or sets the stage background color. */
     background?: string | Rgba;
 }
 
+/** 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. */
 declare enum StalePropertyFlag {
+    /** The object's {@link Renderable.position} changed. */
     Position = "position",
+    /** The object's {@link Ui3DObject.transformMatrix} (rotate/scale/offset) changed. */
     Transform = "transform",
+    /** The mesh/line {@link NodeGeometry} changed. */
     Geometry = "geometry",
+    /** The group's child collection changed. */
     Children = "children",
+    /** The mesh's {@link Material}/{@link Mesh.backMaterial} changed. */
     Material = "material",
+    /** A {@link Light}-specific property (color, intensity, target, ...) changed. */
     Light = "light",
+    /** A {@link Camera}-specific property (near, far, fov, frustum, ...) changed. */
     Camera = "camera",
+    /** The object's {@link Renderable.hide} visibility changed. */
     Visibility = "visibility"
 }
 
+/** A {@link DiffuseMaterial} using a physically-based (metalness/roughness) shading model. */
 declare interface StandardMaterial extends DiffuseMaterial {
     readonly shader: KnownShader.Phong;
+    /** Surface roughness, from `0` (mirror-smooth) to `1` (fully matte), controlling how spread-out specular highlights are. */
     roughness?: number;
+    /** How metallic the surface is, from `0` (dielectric) to `1` (fully metallic), controlling how much of {@link DiffuseMaterial.emissiveColor} tints reflections. */
     metalness?: number;
     /** Percentage of reflected light at grazing angles. */
     fresnel?: number;
 }
 
+/** `<pacem-3d-material-standard>`: produces a {@link StandardMaterial} using a physically-based (metalness/roughness) shading model. */
 declare class StandardMaterialElement extends MaterialElement {
     constructor();
+    /** Builds the {@link StandardMaterial}, adding `emissiveColor`, `refractionRatio`, `metalness`, `roughness` and `flatShading` to the base {@link Material}. */
     protected createMaterial(): Promise<PhongMaterial>;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
+    /** Gets or sets the diffuse color (albedo). */
     emissiveColor: string;
+    /** Gets or sets the index of refraction. */
     refractionRatio: number;
+    /** Gets or sets the surface roughness, from `0` (mirror-smooth) to `1` (fully matte). */
     roughness: number;
+    /** Gets or sets how metallic the surface is, from `0` (dielectric) to `1` (fully metallic). */
     metalness: number;
+    /** Gets or sets whether each face is rendered as flat (faceted) rather than smoothly interpolated. */
     flatShading: boolean;
 }
 
+/**
+ * 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}.
+ */
 declare abstract class Ui3DElement extends RenderableElement implements Ui3DObject {
+    /** Gets or sets the element's rotation, as a quaternion. */
     rotate: Geometry.LinearAlgebra.Quaternion;
+    /** Gets or sets the element's scale, per axis (or a single number for uniform scaling). */
     scale: Geometry.LinearAlgebra.Point3D;
+    /** Gets or sets the element's translation offset, applied on top of {@link RenderableElement.position}. */
     offset: Geometry.LinearAlgebra.Point3D;
     /** Gets the local transform 3D matrix (4x4). */
     transformMatrix: Geometry.LinearAlgebra.Matrix3D;
@@ -1031,6 +1425,7 @@ declare abstract class Ui3DElement extends RenderableElement implements Ui3DObje
     private _computeTransformMatrix;
 }
 
+/** 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. */
 declare abstract class UI3DEvent<T> extends CustomUIEvent<T> {
     #private;
     constructor(type: string, eventInit: CustomEventInit<T>, originalEvent: MouseEvent | TouchEvent | KeyboardEvent, point: Vector3D);
@@ -1038,10 +1433,15 @@ declare abstract class UI3DEvent<T> extends CustomUIEvent<T> {
     get point(): Vector3D;
 }
 
+/** A {@link Renderable} that also has an affine 3d transform (rotation, scale, translation) and a bounding volume. */
 declare interface Ui3DObject extends Renderable {
+    /** Gets or sets the object's rotation. */
     rotate?: Quaternion;
+    /** Gets or sets the object's scale, per axis. */
     scale?: Vector3D;
+    /** Gets or sets the object's translation offset, applied on top of {@link Renderable.position}. */
     offset?: Vector3D;
+    /** Gets or sets the composed local transform (scale, rotation, offset) matrix. */
     transformMatrix: Matrix3D;
     /** Gets the plain (untransformed via {@link transformMatrix}) bounding sphere. */
     readonly boundingSphere?: Sphere3D;
@@ -1049,20 +1449,30 @@ declare interface Ui3DObject extends Renderable {
     readonly boundingBox?: Box3D;
 }
 
+/** Per-vertex texture (u, v) coordinates, one {@link Point} per vertex. */
 declare type UVMap = Point[];
 
+/** A point/displacement in 3d world space, as `{x, y, z}`. */
 declare type Vector3D = Geometry.LinearAlgebra.Vector3D;
 
 declare type Vector3D_2 = Geometry.LinearAlgebra.Vector3D;
 
+/** User-supplied callback (see {@link WGSLModifierDelegates.vertexInput}) that returns extra WGSL statements to splice into the vertex-input stage. */
 declare type VertexInputModifierDelegate = (...args: VertexInputModifierDelegateArgs) => string;
 
+/** Tuple of WGSL identifiers passed to a {@link VertexInputModifierDelegate}: the name of the `VertexInput`-struct variable and of the interaction-data uniform, so custom snippets can reference them. */
 declare type VertexInputModifierDelegateArgs = [vertexInputRef: string, interactionDataRef: string];
 
+/** User-supplied callback (see {@link WGSLModifierDelegates.vertexOutput}) that returns extra WGSL statements to splice into the vertex-output stage. */
 declare type VertexOutputModifierDelegate = (...args: VertexOutputModifierDelegateArgs) => string;
 
+/** Tuple of WGSL identifiers passed to a {@link VertexOutputModifierDelegate}: the name of the `VertexOutput`-struct variable and of the interaction-data uniform, so custom snippets can reference them. */
 declare type VertexOutputModifierDelegateArgs = [vertexOutputRef: string, interactionDataRef: string];
 
+/**
+ * User-authored WGSL customizations spliced into the generated shaders (see {@link Pacem3DWebgpuAdapterElement.modifiers}), either as raw
+ * WGSL source strings or as delegate callbacks. `version` is a content hash used to invalidate cached pipelines when the customization changes.
+ */
 declare type WGSLModifierDelegates = {
     vertexInput?: string | VertexInputModifierDelegate;
     vertexOutput?: string | VertexOutputModifierDelegate;
@@ -1070,6 +1480,7 @@ declare type WGSLModifierDelegates = {
     version?: string;
 };
 
+/** Which pipeline stage a {@link Pacem3DWgslScriptElement}/{@link WGSLModifierDelegates} snippet customizes. */
 declare type WGSLModifierScriptType = 'vertex-input' | 'vertex-output' | 'fragment';