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

package/dist/esm/constants.js

@@ -1,7 +1,9 @@
 /*!
- * @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
  */
+/** Middle segment shared by every custom element tag name in this package (e.g. `pacem-3d`, `pacem-3d-mesh`). */
 export const TAG_MIDDLE_NAME = "3d";
+/** Conversion factor from degrees to radians. */
 export const DEG2RAD = Math.PI / 180;

package/dist/esm/converters.js

@@ -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
  */
@@ -7,10 +7,12 @@ import { Utils } from '@pacem/pacem-core';
 import { parseAsNumericalArray } from '@pacem/pacem-foundation';
 import { Geometry } from '@pacem/pacem-numerical';
 //namespace Pacem.Drawing3D {
+/** Converts a `"x y z"` attribute string to/from a {@link Vector3D}. */
 export const Point3DConverter = {
     convert: (attr) => Geometry.LinearAlgebra.Vector3D.parse(attr),
     convertBack: (prop) => `${prop.x || 0} ${prop.y || 0} ${prop.z || 0}`
 };
+/** Converts a `"x y z"` (3 components) or `"n"` (single uniform component, broadcast to all 3 axes) attribute string to/from a {@link Vector3D}. Used e.g. for `scale`/`offset`. */
 export const Point3DOrNumberConverter = {
     convert: (attr) => {
         const arr = parseAsNumericalArray(attr);
@@ -29,10 +31,12 @@ export const Point3DOrNumberConverter = {
     },
     convertBack: (prop) => `${prop.x || 0} ${prop.y || 0} ${prop.z || 0}`
 };
+/** Converts a `"x y z w"` attribute string to/from a {@link Quaternion}. Used e.g. for `rotate`. */
 export const QuaternionConverter = {
     convert: (attr) => Geometry.LinearAlgebra.Quaternion.parse(attr),
     convertBack: (prop) => `${prop.x || 0} ${prop.y || 0} ${prop.z || 0} ${prop.w || 0}`
 };
+/** Converts an attribute string to/from either a `boolean` (`"true"`/`"false"`) or a `number`. */
 export const BooleanOrNumberConverter = {
     convert: (attr) => {
         if (attr === 'true')

package/dist/esm/decorators.js

@@ -1,10 +1,17 @@
 /*!
- * @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
  */
 import { Utils } from '@pacem/pacem-core';
 //namespace Pacem.Drawing3D {
+/**
+ * Property decorator factory that turns the decorated field into an accessor backed by a private field, invoking
+ * `callback` with the property name and old/new values whenever it is set to a different value. Used by
+ * {@link NodeGeometry}/{@link LineGeometry}/{@link MeshGeometry} to flag themselves as dirty ({@link StalePropertyFlag.Geometry})
+ * whenever their vertex data changes.
+ * @param callback Invoked (with `this` bound to the decorated instance) on every effective change of the property.
+ */
 export function NotifyChange(callback) {
     return (target, prop, descriptor) => {
         const backingField = `_${prop}_${Utils.uniqueCode()}_backingField`;

package/dist/esm/detector.js

@@ -1,11 +1,12 @@
 /*!
- * @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
  */
 //namespace Pacem.Components.Drawing3D {
 /** @deprecated*/
 export class Pacem3DDetector {
+    /** Probes the browser for WebGL support by attempting to create a rendering context, populating {@link info} and {@link supported}. */
     constructor() {
         this._detected = {
             supported: false, info: {}
@@ -69,9 +70,11 @@ export class Pacem3DDetector {
             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;
     }

package/dist/esm/geometry.js

@@ -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
  */
@@ -12,10 +12,15 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { Utils } from '@pacem/pacem-core';
 import { StalePropertyFlag } from './types';
 import { NotifyChange } from './decorators';
+/**
+ * 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.
+ */
 export class NodeGeometry {
     constructor(positions = []) {
         this.positions = positions;
     }
+    /** Computes the centroid (average) of the given positions. */
     static barycenter(positions) {
         var bary = { x: 0, y: 0, z: 0 };
         if (!Utils.isNullOrEmpty(positions)) {
@@ -33,6 +38,7 @@ export class NodeGeometry {
         }
         return bary;
     }
+    /** Computes the axis-aligned {@link Box3D} enclosing the given positions. */
     static boundingBox(positions) {
         const output = {
             minX: +Infinity, minY: +Infinity, minZ: +Infinity,
@@ -51,6 +57,7 @@ export class NodeGeometry {
         }
         return output;
     }
+    /** Marks the geometry as stale, flagging it with {@link StalePropertyFlag.Geometry} for the next render. */
     setAsDirty() {
         setSelfAsDirty.call(this);
     }
@@ -59,27 +66,32 @@ function setSelfAsDirty() {
     const me = this;
     me.flags = [/* no further specifications, other than 'geometry' */ StalePropertyFlag.Geometry];
 }
+/** A {@link NodeGeometry} rendered as a polyline through its {@link positions} (no faces/triangles). */
 export class LineGeometry extends NodeGeometry {
 }
 __decorate([
     NotifyChange(setSelfAsDirty)
 ], LineGeometry.prototype, "positions", void 0);
+/** A {@link MeshGeometry} implementation with lazily-computed {@link barycenter}/{@link boundingBox} and settable {@link boundingSphere}, used as the `geometry` of a {@link Pacem3DMeshElement}. */
 export class MeshGeometry extends NodeGeometry {
     #boundingBox;
     #boundingSphere;
     #barycenter;
+    /** Gets or sets the centroid of {@link positions}; computed on first access if not explicitly set. */
     get barycenter() {
         return this.#barycenter ??= NodeGeometry.barycenter(this.positions);
     }
     set barycenter(point) {
         this.#barycenter = point;
     }
+    /** Gets or sets the axis-aligned bounding box; computed from {@link positions} on first access if not explicitly set. */
     get boundingBox() {
         return this.#boundingBox ??= NodeGeometry.boundingBox(this.positions);
     }
     set boundingBox(bbox) {
         this.#boundingBox = bbox;
     }
+    /** Gets or sets the bounding sphere. */
     get boundingSphere() {
         return this.#boundingSphere;
     }

package/dist/esm/index-components-drawing3d.js

@@ -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
  */

package/dist/esm/index-components.js

@@ -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
  */

package/dist/esm/index-drawing3d.js

@@ -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
  */

package/dist/esm/index-iife.js

@@ -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
  */

package/dist/esm/index-root.js

@@ -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
  */

package/dist/esm/index.js

@@ -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
  */

package/dist/esm/stage.js

@@ -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
  */
@@ -13,6 +13,12 @@ import { CustomElement, P, PCSS, Defaults, ViewChild, Watch, PropertyConverters,
 import { RenderableEvent, DragEvent, RenderableElement } from './types';
 import { TAG_MIDDLE_NAME } from './constants';
 //namespace Pacem.Components.Drawing3D {
+/**
+ * `<pacem-3d>`: the root 3d stage element. Hosts the {@link RenderableElement} scene graph (groups, meshes, lights,
+ * cameras) declared as children or provided via {@link datasource}, delegates all actual scene-building/rendering/
+ * hit-testing to the pluggable {@link adapter} ({@link Pacem3DAdapterElement}), and dispatches pointer interaction
+ * events ({@link RenderableEvent}/{@link DragEvent}) for the items under the cursor.
+ */
 let Pacem3DElement = class Pacem3DElement extends Components.PacemItemsContainerElement {
     constructor() {
         super(...arguments);
@@ -77,9 +83,11 @@ let Pacem3DElement = class Pacem3DElement extends Components.PacemItemsContainer
     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);
     }
@@ -224,9 +232,11 @@ let Pacem3DElement = class Pacem3DElement extends Components.PacemItemsContainer
         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 (!Utils.isNull(item)) {
             const adapter = this.adapter;

package/dist/esm/types.js

@@ -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
  */
@@ -14,38 +14,49 @@ import { Geometry } from '@pacem/pacem-numerical';
 import { Point3DConverter, Point3DOrNumberConverter, QuaternionConverter } from './converters';
 import { Pacem3DElement } from './stage';
 import { TAG_MIDDLE_NAME } from './constants';
+/** Type guard checking whether `object` implements the {@link Stage} contract. */
 export function isStage(object) {
     return !Utils.isNull(object) && 'render' in object && typeof object['render'] === 'function';
 }
+/** Type guard checking whether `object` implements the {@link Renderable} contract (i.e. it is attached to a valid {@link Stage}). */
 export function isRenderable(object) {
     return isStage(object?.stage);
 }
+/** Type guard checking whether `object` implements the {@link Ui3DObject} contract (i.e. it exposes a {@link Ui3DObject.transformMatrix}). */
 export function isUi3DObject(object) {
     return 'transformMatrix' in object && isRenderable(object);
 }
+/** Type guard checking whether `object` implements the {@link Camera} contract. */
 export function isCamera(object) {
     return 'type' in object && 'up' in object && 'lookAt' in object && isRenderable(object);
 }
+/** Type guard checking whether `object` is a {@link PerspectiveCamera}. */
 export function isPerspectiveCamera(object) {
     return isCamera(object) && 'type' in object && object.type === 'perspective';
 }
+/** Type guard checking whether `object` is an {@link OrthographicCamera}. */
 export function isOrthographicCamera(object) {
     return isCamera(object) && 'type' in object && object.type === 'orthographic';
 }
+/** Type guard checking whether `object` implements the {@link Light} contract. */
 export function isLight(object) {
     return 'type' in object && (object.type === 'ambient' || object.type === 'omni' || object.type === 'direction' || object.type == 'spot') && isRenderable(object);
 }
+/** Type guard checking whether `object` implements the {@link Mesh} contract. */
 export function isMesh(object) {
     return 'geometry' in object && isUi3DObject(object);
 }
+/** Type guard checking whether `object` implements the {@link NodeGeometry} contract. */
 export function isGeometry(object) {
     return 'positions' in object && Utils.isArray(object.positions);
 }
+/** Type guard checking whether `object` implements the {@link MeshGeometry} contract (a {@link NodeGeometry} with triangle indices/normals/UVs). */
 export function isMeshGeometry(object) {
     return ('triangleIndices' in object && Utils.isArray(object.triangleIndices)
         || 'normals' in object && Utils.isArray(object.normals)
         || 'textureCoordinates' in object && Utils.isArray(object.textureCoordinates)) && isGeometry(object);
 }
+/** Type guard checking whether `object` implements the {@link Group} contract. */
 export function isGroup(object) {
     return 'childRenderables' in object && Utils.isArray(object['childRenderables']) && isUi3DObject(object);
 }
@@ -81,6 +92,7 @@ export function computePlaneNormal(a, b, c) {
     const orthogonal = Geometry.LinearAlgebra.Vector3D.cross(vAB, vAC);
     return Geometry.LinearAlgebra.Vector3D.unit(orthogonal);
 }
+/** Base class for the custom UI events dispatched by 3d elements/the stage, carrying the source pointer's projected {@link point} in 3d world space alongside the original DOM event. */
 export class UI3DEvent extends CustomUIEvent {
     constructor(type, eventInit, originalEvent, point) {
         super(type, eventInit, originalEvent);
@@ -92,24 +104,36 @@ export class UI3DEvent extends CustomUIEvent {
         return this.#point;
     }
 }
+/** Event dispatched while a {@link Renderable} item is being dragged (`itemdragstart`/`itemdrag`/`itemdragend`-like events), carrying a {@link DragEventArgs} payload. */
 export class DragEvent extends UI3DEvent {
 }
+/** Event dispatched for pointer interactions (click/over/out/down/up) with a {@link Renderable} item, carrying the item itself as its `detail`. */
 export class RenderableEvent extends UI3DEvent {
     constructor(type, args, originalEvent, p) {
         super(type, { detail: args, bubbles: true, cancelable: true }, originalEvent, p);
     }
 }
+/** Identifies which aspect of a {@link Renderable} changed since the last render, so the adapter can update only the stale part of the underlying native object. */
 export var StalePropertyFlag;
 (function (StalePropertyFlag) {
+    /** The object's {@link Renderable.position} changed. */
     StalePropertyFlag["Position"] = "position";
+    /** The object's {@link Ui3DObject.transformMatrix} (rotate/scale/offset) changed. */
     StalePropertyFlag["Transform"] = "transform";
+    /** The mesh/line {@link NodeGeometry} changed. */
     StalePropertyFlag["Geometry"] = "geometry";
+    /** The group's child collection changed. */
     StalePropertyFlag["Children"] = "children";
+    /** The mesh's {@link Material}/{@link Mesh.backMaterial} changed. */
     StalePropertyFlag["Material"] = "material";
+    /** A {@link Light}-specific property (color, intensity, target, ...) changed. */
     StalePropertyFlag["Light"] = "light";
+    /** A {@link Camera}-specific property (near, far, fov, frustum, ...) changed. */
     StalePropertyFlag["Camera"] = "camera";
+    /** The object's {@link Renderable.hide} visibility changed. */
     StalePropertyFlag["Visibility"] = "visibility";
 })(StalePropertyFlag || (StalePropertyFlag = {}));
+/** Type guard checking whether `object` implements the {@link Interaction} contract. */
 export function isInteraction(object) {
     return typeof object === 'object' && 'time' in object && typeof object['time'] === 'number';
 }
@@ -124,12 +148,20 @@ const Constants = {
     GROUP_SELECTOR: P + '-' + TAG_MIDDLE_NAME + '-group',
     DEFAULT_COORDS: { x: 0, y: 0, z: 0 }
 };
+/**
+ * Abstract base of every scene-graph custom element usable inside a {@link Pacem3DElement} stage (groups, meshes,
+ * native objects, lights, cameras). Implements {@link Renderable}, wires the element into the ancestor stage/parent
+ * chain, and tracks which aspects of the object are stale (via {@link StalePropertyFlag}) so the active
+ * {@link Pacem3DAdapterElement} can update only what changed on the next render.
+ */
 export class RenderableElement extends Components.PacemCrossItemsContainerElement {
     constructor() {
         super(...arguments);
+        /** Gets or sets the element's position, in 3d world (or parent-local) space. */
         this.position = Constants.DEFAULT_COORDS;
         this.#staleFlags = [];
     }
+    /** When implemented in a derived class (e.g. {@link Pacem3DGroupElement}), determines whether `_` may be nested under this element. Denies any child by default. */
     validate(_) {
         // by default no children allowed (Group will except)
         return false;
@@ -138,9 +170,11 @@ export class RenderableElement extends Components.PacemCrossItemsContainerElemen
         // override
         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);
     }
@@ -164,6 +198,7 @@ export class RenderableElement extends Components.PacemCrossItemsContainerElemen
         }
     }
     #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;
     }
@@ -187,6 +222,11 @@ __decorate([
 __decorate([
     Watch({ emit: false, converter: PropertyConverters.Boolean })
 ], RenderableElement.prototype, "inert", void 0);
+/**
+ * Abstract base of every {@link RenderableElement} that also carries an affine 3d transform (rotate/scale/offset,
+ * combined into {@link transformMatrix}). Extended by {@link Pacem3DGroupElement}, {@link Pacem3DMeshElement} and
+ * {@link Pacem3DObjectElement}.
+ */
 export class Ui3DElement extends RenderableElement {
     // #endregion
     propertyChangedCallback(name, old, val, first) {
@@ -258,12 +298,14 @@ __decorate([
 __decorate([
     Watch({ emit: false, converter: PropertyConverters.Number })
 ], Ui3DElement.prototype, "translateZ", void 0);
+/** `<pacem-3d-group>`: a {@link Ui3DElement} container that groups child {@link RenderableElement}s (declarative or from {@link datasource}) so its own transform applies to all of them. */
 let Pacem3DGroupElement = class Pacem3DGroupElement extends Ui3DElement {
     validate(child) {
         // overrides default denial
         return child instanceof RenderableElement;
     }
     #children = [];
+    /** @readonly Gets the renderable children currently belonging to the group. */
     get childRenderables() {
         return this.#children;
     }
@@ -285,6 +327,7 @@ Pacem3DGroupElement = __decorate([
     CustomElement({ tagName: Constants.GROUP_SELECTOR })
 ], Pacem3DGroupElement);
 export { Pacem3DGroupElement };
+/** `<pacem-3d-mesh>`: a {@link Ui3DElement} that renders a {@link NodeGeometry} (mesh or line) with a front/back {@link Material}. */
 let Pacem3DMeshElement = class Pacem3DMeshElement extends Ui3DElement {
     propertyChangedCallback(name, old, val, first) {
         super.propertyChangedCallback(name, old, val, first);
@@ -312,6 +355,7 @@ Pacem3DMeshElement = __decorate([
     CustomElement({ tagName: Constants.MESH_SELECTOR })
 ], Pacem3DMeshElement);
 export { Pacem3DMeshElement };
+/** `<pacem-3d-object>`: a {@link Ui3DElement} that loads/embeds a pre-built 3d asset (`obj`, `fbx`, or a native scene-graph object) instead of an explicit {@link Pacem3DMeshElement} geometry. */
 let Pacem3DObjectElement = class Pacem3DObjectElement extends Ui3DElement {
     propertyChangedCallback(name, old, val, first) {
         super.propertyChangedCallback(name, old, val, first);
@@ -330,12 +374,17 @@ Pacem3DObjectElement = __decorate([
     CustomElement({ tagName: Constants.OBJECT_SELECTOR })
 ], Pacem3DObjectElement);
 export { Pacem3DObjectElement };
+/** `<pacem-3d-light>`: a {@link RenderableElement} light source (point/omni, spot or directional) illuminating the scene. */
 let Pacem3DLightElement = class Pacem3DLightElement extends RenderableElement {
     constructor() {
         super(...arguments);
+        /** Gets or sets the light intensity/brightness. */
         this.intensity = .85;
+        /** Gets or sets the point the light is aimed at (spotlight-specific). */
         this.target = Constants.DEFAULT_COORDS;
+        /** Gets or sets the light color. */
         this.color = '#fff';
+        /** Gets or sets the kind of light source. */
         this.type = 'omni';
     }
     propertyChangedCallback(name, old, val, first) {
@@ -366,12 +415,21 @@ Pacem3DLightElement = __decorate([
     CustomElement({ tagName: Constants.LIGHT_SELECTOR })
 ], Pacem3DLightElement);
 export { Pacem3DLightElement };
+/**
+ * Abstract base of the camera custom elements ({@link Pacem3DPerspectiveCameraElement}, {@link Pacem3DOrthographicCameraElement})
+ * that can be added to a {@link Pacem3DElement} stage. Implements {@link Camera}, tracking the eye-to-target
+ * {@link boundingSphere} used e.g. by {@link Pacem3DAdapterElement.zoomFit}.
+ */
 export class Pacem3DCameraElement extends RenderableElement {
     constructor() {
         super(...arguments);
+        /** Gets or sets the near clipping plane distance. */
         this.near = 0.1;
+        /** Gets or sets the far clipping plane distance. */
         this.far = 1000.0;
+        /** Gets or sets the up vector, in world coordinates. */
         this.up = Geometry.LinearAlgebra.Vector3D.j();
+        /** Gets or sets the target the camera looks at, in world coordinates. */
         this.lookAt = Constants.DEFAULT_COORDS;
     }
     #sphere;
@@ -383,6 +441,7 @@ export class Pacem3DCameraElement 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;
     }
@@ -412,15 +471,20 @@ __decorate([
 __decorate([
     Watch({ emit: false, converter: Point3DConverter })
 ], Pacem3DCameraElement.prototype, "lookAt", void 0);
+/** `<pacem-3d-perspective-camera>`: a {@link Pacem3DCameraElement} that projects the scene through a perspective frustum (vanishing point), defined by {@link fov} and {@link aspect}. */
 let Pacem3DPerspectiveCameraElement = class Pacem3DPerspectiveCameraElement extends Pacem3DCameraElement {
     constructor() {
         super(...arguments);
+        /** Gets or sets the vertical field of view, in degrees. */
         this.fov = 45;
+        /** Gets or sets the viewport width/height ratio. */
         this.aspect = 1;
     }
+    /** @readonly Gets the camera discriminator: always `"perspective"`. */
     get type() {
         return "perspective";
     }
+    /** @readonly Gets the viewport width/height ratio (alias of {@link aspect}). */
     get aspectRatio() {
         return this.aspect;
     }
@@ -444,14 +508,20 @@ Pacem3DPerspectiveCameraElement = __decorate([
     CustomElement({ tagName: Constants.PERSPECTIVE_CAMERA_SELECTOR })
 ], Pacem3DPerspectiveCameraElement);
 export { Pacem3DPerspectiveCameraElement };
+/** `<pacem-3d-orthographic-camera>`: a {@link Pacem3DCameraElement} that projects the scene through a fixed, non-diminishing (parallel) frustum, defined by the {@link top}/{@link left}/{@link bottom}/{@link right} coordinates. */
 let Pacem3DOrthographicCameraElement = class Pacem3DOrthographicCameraElement extends Pacem3DCameraElement {
     constructor() {
         super(...arguments);
+        /** Gets or sets the top frustum coordinate (e.g. 1). */
         this.top = 1;
+        /** Gets or sets the left frustum coordinate (e.g. -1). */
         this.left = -1;
+        /** Gets or sets the bottom frustum coordinate (e.g. -1). */
         this.bottom = -1;
+        /** Gets or sets the right frustum coordinate (e.g. 1). */
         this.right = 1;
     }
+    /** @readonly Gets the camera discriminator: always `"orthographic"`. */
     get type() {
         return "orthographic";
     }
@@ -483,5 +553,11 @@ Pacem3DOrthographicCameraElement = __decorate([
     CustomElement({ tagName: Constants.ORTHO_CAMERA_SELECTOR })
 ], Pacem3DOrthographicCameraElement);
 export { Pacem3DOrthographicCameraElement };
+/**
+ * Pluggable rendering-backend contract assignable to a {@link Pacem3DElement}'s `adapter` property. Concrete adapters
+ * ({@link Pacem3DThreeAdapterElement} for Three.js/WebGL, {@link Pacem3DWebgpuAdapterElement} for WebGPU) are
+ * responsible for initializing/disposing the underlying native scene and DOM surface, sizing it, translating the
+ * {@link RenderableElement} scene graph into native objects, hit-testing (raycasting) and producing snapshot images.
+ */
 export class Pacem3DAdapterElement extends PacemEventTarget {
 }

package/package.json

@@ -4,6 +4,7 @@
     "dist/browser/*.*",
     "dist/bundle/*.*",
     "dist/esm/*.*",
+    "dist/docs/*.*",
     "typings/*.*",
     "README.md",
     "LICENSE",
@@ -25,7 +26,7 @@
       "types": "./typings/index.d.ts"
     }
   },
-  "version": "1.0.0-bessel",
+  "version": "1.0.0-dirac",
   "author": {
     "name": "Pacem",
     "url": "https://pacem.it"