@newkrok/nape-js 3.4.13 → 3.5.0

package/dist/index.d.ts

@@ -182,6 +182,12 @@ declare class Vec2 {
      * @internal
      */
     get _inner(): NapeInner;
+    /**
+     * Creates a Vec2 with the given components. Defaults to (0, 0).
+     *
+     * @param x - The x component (default 0).
+     * @param y - The y component (default 0).
+     */
     constructor(x?: number, y?: number);
     /** @internal Check that this Vec2 has not been disposed. */
     private _checkDisposed;
@@ -202,66 +208,230 @@ declare class Vec2 {
     private static _poolGet;
     /** @internal Wrap a ZPP_Vec2 (or legacy compiled Vec2) with caching. */
     static _wrap(inner: any): Vec2;
-    /** Obtain a Vec2 from the object pool (or create a new one). */
+    /**
+     * Allocate a Vec2 from the public object pool. If `weak` is true, the vector
+     * auto-disposes after a single API call.
+     *
+     * @param x - The x component (default 0).
+     * @param y - The y component (default 0).
+     * @param weak - If true, the returned Vec2 is auto-disposed after one use (default false).
+     * @returns A pooled or newly created Vec2.
+     * @example
+     * const v = Vec2.get(3, 4);
+     * // use v ...
+     * v.dispose();
+     */
     static get(x?: number, y?: number, weak?: boolean): Vec2;
-    /** Obtain a weak Vec2 that auto-disposes after a single use. */
+    /**
+     * Allocate a weak Vec2 (auto-disposes after a single use).
+     *
+     * @param x - The x component (default 0).
+     * @param y - The y component (default 0).
+     * @returns A weak, pooled Vec2 that is automatically disposed after one API call.
+     */
     static weak(x?: number, y?: number): Vec2;
-    /** Create a Vec2 from polar coordinates. */
+    /**
+     * Create a Vec2 from polar coordinates (length and angle in radians).
+     *
+     * @param length - The magnitude of the resulting vector.
+     * @param angle - The angle in radians, measured counter-clockwise from the +x axis.
+     * @param weak - If true, the returned Vec2 is auto-disposed after one use (default false).
+     * @returns A new Vec2 with components `(length * cos(angle), length * sin(angle))`.
+     * @example
+     * const v = Vec2.fromPolar(1, Math.PI / 4); // 45-degree unit vector
+     */
     static fromPolar(length: number, angle: number, weak?: boolean): Vec2;
-    /** Squared distance between two Vec2s. */
+    /**
+     * Squared Euclidean distance between two Vec2s. Avoids a square root when
+     * only comparison is needed.
+     *
+     * @param a - The first Vec2.
+     * @param b - The second Vec2.
+     * @returns The squared distance `(a.x - b.x)² + (a.y - b.y)²`.
+     */
     static dsq(a: Vec2, b: Vec2): number;
-    /** Euclidean distance between two Vec2s. */
+    /**
+     * Euclidean distance between two Vec2s.
+     *
+     * @param a - The first Vec2.
+     * @param b - The second Vec2.
+     * @returns The distance `sqrt((a.x - b.x)² + (a.y - b.y)²)`.
+     */
     static distance(a: Vec2, b: Vec2): number;
+    /** The x component. */
     get x(): number;
+    /** The x component. */
     set x(value: number);
+    /** The y component. */
     get y(): number;
+    /** The y component. */
     set y(value: number);
-    /** Magnitude of the vector. */
+    /** Magnitude (Euclidean length) of the vector. */
     get length(): number;
-    /** Setting length scales the vector to the given magnitude. */
+    /**
+     * Setting length scales the vector to the given magnitude. Throws if the
+     * vector is zero-length.
+     *
+     * @param value - The desired magnitude. Must not be NaN.
+     */
     set length(value: number);
-    /** Angle of the vector in radians (measured from the +x axis). */
+    /**
+     * Angle of the vector in radians, measured counter-clockwise from the +x
+     * axis. Returns 0 for the zero vector.
+     */
     get angle(): number;
-    /** Setting angle preserves magnitude but rotates to the given angle. */
+    /**
+     * Setting angle preserves the vector's magnitude and rotates it to the given
+     * angle.
+     *
+     * @param value - The desired angle in radians. Must not be NaN.
+     */
     set angle(value: number);
-    /** Squared length — avoids a square root when only comparison is needed. */
+    /**
+     * Returns the squared magnitude. Faster than `length` as it avoids a square
+     * root.
+     *
+     * @returns `x² + y²`.
+     */
     lsq(): number;
-    /** Copy values from another vector into this one (in-place). Returns this. */
+    /**
+     * Copy another Vec2's components into this vector in-place.
+     *
+     * @param vector - The source Vec2 to copy from.
+     * @returns `this` for chaining.
+     */
     set(vector: Vec2): this;
-    /** Set both components at once (in-place). Returns this. */
+    /**
+     * Set both components at once in-place.
+     *
+     * @param x - The new x component.
+     * @param y - The new y component.
+     * @returns `this` for chaining.
+     */
     setxy(x: number, y: number): this;
-    /** Return a new copy of this vector. */
+    /**
+     * Return a new Vec2 with the same components.
+     *
+     * @param weak - If true, the returned Vec2 is auto-disposed after one use (default false).
+     * @returns A copy of this vector.
+     */
     copy(weak?: boolean): Vec2;
-    /** Rotate this vector by the given angle in radians (in-place). Returns this. */
+    /**
+     * Rotate this vector by `angle` radians in-place.
+     *
+     * @param angle - The rotation angle in radians.
+     * @returns `this` for chaining.
+     */
     rotate(angle: number): this;
-    /** Reflect this vector about the given axis vector (returns new Vec2). */
+    /**
+     * Reflect `vec` about this vector as a normal axis.
+     *
+     * @param vec - The Vec2 to reflect.
+     * @param weak - If true, the returned Vec2 is auto-disposed after one use (default false).
+     * @returns A new Vec2 that is the reflection of `vec` about this vector.
+     */
     reflect(vec: Vec2, weak?: boolean): Vec2;
-    /** Normalize this vector to unit length (in-place). Returns this. */
+    /**
+     * Normalise this vector to unit length in-place. Throws for zero-length
+     * vectors.
+     *
+     * @returns `this` for chaining.
+     */
     normalise(): this;
-    /** Return a new unit-length vector with the same direction. */
+    /**
+     * Return a new unit-length vector with the same direction. Throws for
+     * zero-length vectors.
+     *
+     * @param weak - If true, the returned Vec2 is auto-disposed after one use (default false).
+     * @returns A normalised copy of this vector.
+     */
     unit(weak?: boolean): Vec2;
-    /** Return a new vector = this + other. */
+    /**
+     * Return a new Vec2 equal to `this + other`.
+     *
+     * @param vector - The Vec2 to add.
+     * @param weak - If true, the returned Vec2 is auto-disposed after one use (default false).
+     * @returns A new Vec2 with components `(this.x + other.x, this.y + other.y)`.
+     */
     add(vector: Vec2, weak?: boolean): Vec2;
-    /** Return a new vector = this + other * scalar. */
+    /**
+     * Return a new Vec2 equal to `this + other × scalar`.
+     *
+     * @param vector - The Vec2 to scale and add.
+     * @param scalar - The multiplier applied to `vector` before addition.
+     * @param weak - If true, the returned Vec2 is auto-disposed after one use (default false).
+     * @returns A new Vec2 with components `(this.x + vector.x * scalar, this.y + vector.y * scalar)`.
+     */
     addMul(vector: Vec2, scalar: number, weak?: boolean): Vec2;
-    /** Return a new vector = this - other. */
+    /**
+     * Return a new Vec2 equal to `this − other`.
+     *
+     * @param vector - The Vec2 to subtract.
+     * @param weak - If true, the returned Vec2 is auto-disposed after one use (default false).
+     * @returns A new Vec2 with components `(this.x - other.x, this.y - other.y)`.
+     */
     sub(vector: Vec2, weak?: boolean): Vec2;
-    /** Return a new vector = this * scalar. */
+    /**
+     * Return a new Vec2 equal to `this × scalar`.
+     *
+     * @param scalar - The multiplier.
+     * @param weak - If true, the returned Vec2 is auto-disposed after one use (default false).
+     * @returns A new Vec2 with components `(this.x * scalar, this.y * scalar)`.
+     */
     mul(scalar: number, weak?: boolean): Vec2;
-    /** this += other (in-place). Returns this. */
+    /**
+     * Add another Vec2 to this in-place (`this += other`).
+     *
+     * @param vector - The Vec2 to add.
+     * @returns `this` for chaining.
+     */
     addeq(vector: Vec2): this;
-    /** this -= other (in-place). Returns this. */
+    /**
+     * Subtract another Vec2 from this in-place (`this -= other`).
+     *
+     * @param vector - The Vec2 to subtract.
+     * @returns `this` for chaining.
+     */
     subeq(vector: Vec2): this;
-    /** this *= scalar (in-place). Returns this. */
+    /**
+     * Multiply this Vec2 by a scalar in-place (`this ×= scalar`).
+     *
+     * @param scalar - The multiplier.
+     * @returns `this` for chaining.
+     */
     muleq(scalar: number): this;
-    /** Dot product of this and other. */
+    /**
+     * Dot product of this and another Vec2.
+     *
+     * @param vector - The other Vec2.
+     * @returns `this.x * other.x + this.y * other.y`.
+     */
     dot(vector: Vec2): number;
-    /** 2D cross product (returns scalar: this.x*other.y - this.y*other.x). */
+    /**
+     * 2D cross product (`this.x × other.y − this.y × other.x`). Returns a
+     * scalar.
+     *
+     * @param vector - The other Vec2.
+     * @returns The scalar cross product.
+     */
     cross(vector: Vec2): number;
-    /** Return the perpendicular vector (rotated 90deg counter-clockwise). */
+    /**
+     * Return the perpendicular vector, rotated 90° counter-clockwise.
+     *
+     * @param weak - If true, the returned Vec2 is auto-disposed after one use (default false).
+     * @returns A new Vec2 with components `(-this.y, this.x)`.
+     */
     perp(weak?: boolean): Vec2;
-    /** Release this vector back to the object pool. */
+    /**
+     * Return this Vec2 to the object pool. Throws if already disposed or
+     * immutable.
+     */
     dispose(): void;
+    /**
+     * String representation in the form `{ x: … y: … }`.
+     *
+     * @returns A human-readable string of this vector's components.
+     */
     toString(): string;
 }
 /** @internal Opaque handle for any Haxe-compiled nape object. */
@@ -310,6 +480,12 @@ declare class Vec3 {
      * @internal
      */
     get _inner(): NapeInner;
+    /**
+     * Create a Vec3 with the given components. Defaults to (0, 0, 0).
+     * @param x - The x component.
+     * @param y - The y component.
+     * @param z - The z component.
+     */
     constructor(x?: number, y?: number, z?: number);
     /** @internal Check that this Vec3 has not been disposed. */
     private _checkDisposed;
@@ -317,28 +493,70 @@ declare class Vec3 {
     private _checkImmutable;
     /** @internal Wrap a ZPP_Vec3 (or legacy compiled Vec3) with caching. */
     static _wrap(inner: any): Vec3;
-    /** Obtain a Vec3 from the object pool (or create a new one). */
+    /**
+     * Allocate a Vec3 from the public object pool, or create a new one if the pool is empty.
+     * @param x - Initial x component (default 0).
+     * @param y - Initial y component (default 0).
+     * @param z - Initial z component (default 0).
+     * @returns A Vec3 initialised with the given components.
+     */
     static get(x?: number, y?: number, z?: number): Vec3;
+    /** The x component. */
     get x(): number;
+    /** The x component. */
     set x(value: number);
+    /** The y component. */
     get y(): number;
+    /** The y component. */
     set y(value: number);
+    /** The z component. */
     get z(): number;
+    /** The z component. */
     set z(value: number);
-    /** Magnitude of the 3D vector. */
+    /**
+     * Magnitude of the 3D vector.
+     * @returns The Euclidean length `sqrt(x² + y² + z²)`.
+     */
     get length(): number;
-    /** Setting length scales the vector to the given magnitude. */
+    /**
+     * Scale the vector to the given magnitude.
+     * @throws If the vector has zero length.
+     */
     set length(value: number);
-    /** Squared length — avoids a square root when only comparison is needed. */
+    /**
+     * Squared magnitude. Faster than `length` as it avoids a square root.
+     * @returns `x² + y² + z²`.
+     */
     lsq(): number;
-    /** Copy values from another Vec3 into this one (in-place). Returns this. */
+    /**
+     * Copy another Vec3's components into this one in-place.
+     * @param vector - The source Vec3 to copy from.
+     * @returns `this` for chaining.
+     */
     set(vector: Vec3): this;
-    /** Set all three components at once (in-place). Returns this. */
+    /**
+     * Set all three components at once in-place.
+     * @param x - The new x component.
+     * @param y - The new y component.
+     * @param z - The new z component.
+     * @returns `this` for chaining.
+     */
     setxyz(x: number, y: number, z: number): this;
-    /** Return the x,y components as a Vec2. */
+    /**
+     * Return the x and y components as a new Vec2.
+     * @param weak - If true, the returned Vec2 is a weak (pooled) reference.
+     * @returns A new Vec2 containing this vector's x and y components.
+     */
     xy(weak?: boolean): Vec2;
-    /** Release this Vec3 back to the object pool. */
+    /**
+     * Return this Vec3 to the object pool.
+     * @throws If this Vec3 has already been disposed.
+     */
     dispose(): void;
+    /**
+     * String representation `{ x: … y: … z: … }`.
+     * @returns A human-readable string of the three components.
+     */
     toString(): string;
 }
 
@@ -386,40 +604,154 @@ declare class Mat23 {
     static __name__: string[];
     zpp_inner: ZPP_Mat23;
     get _inner(): NapeInner;
+    /**
+     * Create a Mat23 with the given components. Defaults to the identity matrix `[1 0 0; 0 1 0]`.
+     * @param a - Component at row 0, col 0.
+     * @param b - Component at row 0, col 1.
+     * @param c - Component at row 1, col 0.
+     * @param d - Component at row 1, col 1.
+     * @param tx - Translation component along x.
+     * @param ty - Translation component along y.
+     */
     constructor(a?: number, b?: number, c?: number, d?: number, tx?: number, ty?: number);
+    /**
+     * Create a pure rotation matrix for the given angle in radians.
+     * @param angle - Rotation angle in radians.
+     * @returns A new Mat23 representing the rotation.
+     */
     static rotation(angle: number): Mat23;
+    /**
+     * Create a pure translation matrix.
+     * @param tx - Translation along x.
+     * @param ty - Translation along y.
+     * @returns A new Mat23 representing the translation.
+     */
     static translation(tx: number, ty: number): Mat23;
+    /**
+     * Create a pure scale matrix.
+     * @param sx - Scale factor along x.
+     * @param sy - Scale factor along y.
+     * @returns A new Mat23 representing the scale.
+     */
     static scale(sx: number, sy: number): Mat23;
     static _wrap(inner: any): Mat23;
     private _setProp;
+    /** Matrix component at row 0, col 0. The matrix layout is `[a b tx; c d ty]`. */
     get a(): number;
+    /** Matrix component at row 0, col 0. The matrix layout is `[a b tx; c d ty]`. */
     set a(v: number);
+    /** Matrix component at row 0, col 1. The matrix layout is `[a b tx; c d ty]`. */
     get b(): number;
+    /** Matrix component at row 0, col 1. The matrix layout is `[a b tx; c d ty]`. */
     set b(v: number);
+    /** Matrix component at row 1, col 0. The matrix layout is `[a b tx; c d ty]`. */
     get c(): number;
+    /** Matrix component at row 1, col 0. The matrix layout is `[a b tx; c d ty]`. */
     set c(v: number);
+    /** Matrix component at row 1, col 1. The matrix layout is `[a b tx; c d ty]`. */
     get d(): number;
+    /** Matrix component at row 1, col 1. The matrix layout is `[a b tx; c d ty]`. */
     set d(v: number);
+    /** Translation component along x. The matrix layout is `[a b tx; c d ty]`. */
     get tx(): number;
+    /** Translation component along x. The matrix layout is `[a b tx; c d ty]`. */
     set tx(v: number);
+    /** Translation component along y. The matrix layout is `[a b tx; c d ty]`. */
     get ty(): number;
+    /** Translation component along y. The matrix layout is `[a b tx; c d ty]`. */
     set ty(v: number);
+    /** The determinant of the linear 2×2 part (ad − bc). */
     get determinant(): number;
+    /**
+     * Return a new Mat23 with the same components.
+     * @returns A deep copy of this matrix.
+     */
     copy(): Mat23;
+    /**
+     * Copy all components from another Mat23 into this one in-place.
+     * @param matrix - The source matrix to copy from.
+     * @returns `this` for chaining.
+     */
     set(matrix: Mat23): this;
+    /**
+     * Set all six components at once in-place.
+     * @param a - Component at row 0, col 0.
+     * @param b - Component at row 0, col 1.
+     * @param c - Component at row 1, col 0.
+     * @param d - Component at row 1, col 1.
+     * @param tx - Translation along x.
+     * @param ty - Translation along y.
+     * @returns `this` for chaining.
+     */
     setAs(a?: number, b?: number, c?: number, d?: number, tx?: number, ty?: number): this;
+    /**
+     * Reset to the identity matrix in-place.
+     * @returns `this` for chaining.
+     */
     reset(): this;
+    /**
+     * Return `true` if the matrix is singular (non-invertible) within the engine's epsilon threshold.
+     * @returns `true` when the matrix cannot be safely inverted.
+     */
     singular(): boolean;
+    /**
+     * Return the inverse of this matrix.
+     * @returns A new Mat23 that is the inverse of this one.
+     * @throws If the matrix is singular.
+     */
     inverse(): Mat23;
+    /**
+     * Return the transpose of this matrix.
+     * @returns A new Mat23 that is the transpose of this one.
+     */
     transpose(): Mat23;
+    /**
+     * Return `matrix × this` (apply this matrix first, then `matrix`).
+     * @param matrix - The matrix to concatenate on the left.
+     * @returns A new Mat23 representing the combined transformation.
+     */
     concat(matrix: Mat23): Mat23;
+    /**
+     * Transform a Vec2 by this matrix. If `noTranslation` is true, only the linear 2×2 part is applied.
+     * @param point - The Vec2 to transform.
+     * @param noTranslation - When true, the translation components (tx, ty) are ignored.
+     * @param weak - If true, the returned Vec2 is a weak (pooled) reference.
+     * @returns A new Vec2 with the transformed coordinates.
+     */
     transform(point: Vec2, noTranslation?: boolean, weak?: boolean): Vec2;
+    /**
+     * Apply the inverse transformation to a Vec2. Throws if the matrix is singular.
+     * @param point - The Vec2 to transform.
+     * @param noTranslation - When true, the translation components (tx, ty) are ignored.
+     * @param weak - If true, the returned Vec2 is a weak (pooled) reference.
+     * @returns A new Vec2 with the inverse-transformed coordinates.
+     */
     inverseTransform(point: Vec2, noTranslation?: boolean, weak?: boolean): Vec2;
+    /**
+     * Return `true` if the matrix is equiorthogonal (uniform scale, no shear).
+     * @returns `true` when the matrix has equal scale on both axes and no shear.
+     */
     equiorthogonal(): boolean;
+    /**
+     * Return `true` if the matrix is orthogonal (unit-scale rotation, no shear).
+     * @returns `true` when the column vectors are orthonormal.
+     */
     orthogonal(): boolean;
     private _orthogonaliseImpl;
+    /**
+     * Adjust the matrix in-place to be equiorthogonal (uniform scale, no shear).
+     * @returns `this` for chaining.
+     */
     equiorthogonalise(): this;
+    /**
+     * Adjust the matrix in-place to be orthogonal (normalise column vectors).
+     * @returns `this` for chaining.
+     */
     orthogonalise(): this;
+    /**
+     * String representation `{ a: … b: … c: … d: … tx: … ty: … }`.
+     * @returns A human-readable string of the matrix components.
+     */
     toString(): string;
 }
 
@@ -618,26 +950,72 @@ declare class AABB {
      * @internal
      */
     get _inner(): NapeInner;
+    /**
+     * Create an AABB at position (x, y) with the given width and height. All
+     * values default to 0.
+     *
+     * @param x - The x position of the left edge (default 0).
+     * @param y - The y position of the top edge (default 0).
+     * @param width - The width of the box (default 0). Must be ≥ 0.
+     * @param height - The height of the box (default 0). Must be ≥ 0.
+     */
     constructor(x?: number, y?: number, width?: number, height?: number);
     /** @internal Wrap a ZPP_AABB (or legacy compiled AABB) with caching. */
     static _wrap(inner: any): AABB;
+    /** The x position of the left edge (minx). Setting shifts the box horizontally. */
     get x(): number;
+    /** The x position of the left edge (minx). Setting shifts the box horizontally. */
     set x(x: number);
+    /** The y position of the top edge (miny). Setting shifts the box vertically. */
     get y(): number;
+    /** The y position of the top edge (miny). Setting shifts the box vertically. */
     set y(y: number);
+    /** Width of the box (maxx − minx). Must be ≥ 0. */
     get width(): number;
+    /** Width of the box (maxx − minx). Must be ≥ 0. */
     set width(width: number);
+    /** Height of the box (maxy − miny). Must be ≥ 0. */
     get height(): number;
+    /** Height of the box (maxy − miny). Must be ≥ 0. */
     set height(height: number);
+    /**
+     * The top-left corner as a Vec2 (minx, miny). The returned Vec2 is a live
+     * view; mutating it updates the AABB.
+     */
     get min(): any;
+    /**
+     * Set the top-left corner. The new min must not exceed the current max.
+     *
+     * @param min - A Vec2 whose components become the new (minx, miny).
+     */
     set min(min: any);
+    /**
+     * The bottom-right corner as a Vec2 (maxx, maxy). The returned Vec2 is a
+     * live view; mutating it updates the AABB.
+     */
     get max(): any;
+    /**
+     * Set the bottom-right corner. The new max must not be below the current
+     * min.
+     *
+     * @param max - A Vec2 whose components become the new (maxx, maxy).
+     */
     set max(max: any);
     /** @internal Assign source Vec2 values to target Vec2 wrapper. */
     private _assignVec2;
     /** @internal Dispose a weak Vec2 back to the pool. */
     private _disposeVec2;
+    /**
+     * Return a new AABB with the same bounds.
+     *
+     * @returns A copy of this AABB.
+     */
     copy(): AABB;
+    /**
+     * String representation in the form `{ x: … y: … w: … h: … }`.
+     *
+     * @returns A human-readable string of this AABB's position and dimensions.
+     */
     toString(): string;
 }
 
@@ -666,14 +1044,47 @@ declare class MatMN {
     static __name__: string[];
     zpp_inner: ZPP_MatMN;
     get _inner(): NapeInner;
+    /**
+     * Create a zero-filled M×N matrix. Both dimensions must be ≥ 1.
+     * @param rows - Number of rows (must be ≥ 1).
+     * @param cols - Number of columns (must be ≥ 1).
+     */
     constructor(rows: number, cols: number);
     static _wrap(inner: ZPP_MatMN | MatMN | null): MatMN;
+    /** Number of rows. */
     get rows(): number;
+    /** Number of columns. */
     get cols(): number;
+    /**
+     * Read the element at (row, col). Zero-based indices.
+     * @param row - Zero-based row index.
+     * @param col - Zero-based column index.
+     * @returns The element value at the given position.
+     */
     x(row: number, col: number): number;
+    /**
+     * Write `value` to the element at (row, col). Returns the written value.
+     * @param row - Zero-based row index.
+     * @param col - Zero-based column index.
+     * @param value - The value to write.
+     * @returns The written value.
+     */
     setx(row: number, col: number, value: number): number;
+    /**
+     * String representation with rows separated by semicolons.
+     * @returns A human-readable string of the matrix elements.
+     */
     toString(): string;
+    /**
+     * Return a new transposed matrix (N×M).
+     * @returns A new MatMN that is the transpose of this one.
+     */
     transpose(): MatMN;
+    /**
+     * Return the matrix product `this × matrix`. Column count of this must equal row count of `matrix`.
+     * @param matrix - The right-hand matrix to multiply by.
+     * @returns A new MatMN representing the product.
+     */
     mul(matrix: MatMN): MatMN;
 }
 
@@ -758,19 +1169,53 @@ declare class Ray {
     zpp_inner: ZPP_Ray;
     /** Backward-compat alias for compiled code. */
     get _inner(): this;
+    /**
+     * Create a Ray from an origin point and a direction vector.
+     * Both must be non-null, non-disposed Vec2s.
+     * @param origin - The start point of the ray in world coordinates.
+     * @param direction - The direction vector (need not be unit length).
+     */
     constructor(origin: Vec2, direction: Vec2);
     /** @internal */
     static _wrap(inner: ZPP_Ray | Ray | null): Ray;
+    /**
+     * Create a Ray from a line segment.
+     * The ray origin is `start`, direction is `end − start`, and `maxDistance` is the segment length.
+     * @param start - The start point of the segment.
+     * @param end - The end point of the segment.
+     * @returns A new Ray spanning the segment.
+     */
     static fromSegment(start: Vec2, end: Vec2): Ray;
+    /** The ray's start point in world coordinates. */
     get origin(): Vec2;
+    /** The ray's start point in world coordinates. */
     set origin(value: Vec2);
+    /** The ray's direction vector (need not be unit length; the engine normalises internally). */
     get direction(): Vec2;
+    /** The ray's direction vector (need not be unit length; the engine normalises internally). */
     set direction(value: Vec2);
+    /** Maximum travel distance for raycasting queries. Defaults to `Infinity`. */
     get maxDistance(): number;
+    /** Maximum travel distance for raycasting queries. Defaults to `Infinity`. */
     set maxDistance(value: number);
+    /** Arbitrary user data attached to this Ray. */
     get userData(): Record<string, unknown>;
+    /**
+     * Compute the axis-aligned bounding box that encloses the ray from origin to `maxDistance`.
+     * @returns A new AABB wrapping the ray's extent.
+     */
     aabb(): AABB;
+    /**
+     * Return the world-space point at `distance` along the ray.
+     * @param distance - Distance from the ray origin along the ray direction.
+     * @param weak - If true, the returned Vec2 is a weak (pooled) reference.
+     * @returns The point `origin + distance * normalised_direction`.
+     */
     at(distance: number, weak?: boolean): Vec2;
+    /**
+     * Return a new Ray with the same origin, direction, and maxDistance.
+     * @returns A deep copy of this Ray.
+     */
     copy(): Ray;
     /** @internal */ get_origin(): Vec2;
     /** @internal */ set_origin(v: Vec2): Vec2;
@@ -1197,10 +1642,22 @@ declare class ZPP_Constraint {
 }
 
 /**
- * Base class for all constraints / joints.
+ * Base class for all physics constraints (joints).
+ *
+ * Constraints restrict the relative motion of two bodies. This class provides
+ * properties common to all joint types: `active`, `stiff`, `frequency`,
+ * `damping`, `maxForce`, `maxError`, `breakUnderForce`, `breakUnderError`,
+ * `removeOnBreak`, `isSleeping`, `space`, `compound`, `cbTypes`, and `userData`.
+ *
+ * Cannot be instantiated directly — use one of the concrete joint subclasses:
+ * {@link AngleJoint}, {@link DistanceJoint}, {@link LineJoint}, {@link MotorJoint},
+ * {@link PivotJoint}, {@link PulleyJoint}, {@link WeldJoint}, or {@link UserConstraint}.
+ *
+ * **Soft vs. stiff constraints:**
+ * - `stiff = true` (default): the constraint is enforced rigidly.
+ * - `stiff = false`: uses a spring model with `frequency` (Hz) and `damping` (ratio).
  *
  * Fully modernized — uses ZPP_Constraint directly (extracted to TypeScript).
- * Not instantiated directly; only via joint subclasses.
  */
 declare class Constraint {
     static __name__: string[];
@@ -1219,36 +1676,145 @@ declare class Constraint {
     protected constructor();
     /** @internal */
     static _wrap(inner: any): Constraint;
+    /**
+     * The space this constraint belongs to, or `null` if not in a space.
+     *
+     * Assign to add/remove the constraint from a space:
+     * ```ts
+     * joint.space = mySpace;  // adds to space
+     * joint.space = null;     // removes from space
+     * ```
+     * Cannot be set if the constraint belongs to a {@link Compound}.
+     */
     get space(): Space | null;
     set space(value: Space | null);
+    /**
+     * The compound this constraint belongs to, or `null`.
+     * When set, the constraint's `space` is managed by the compound.
+     */
     get compound(): Compound | null;
     set compound(value: Compound | null);
+    /**
+     * Whether the constraint is currently active (enforced by the solver).
+     *
+     * Deactivating a constraint suspends it without removing it from the space.
+     * @defaultValue `true`
+     */
     get active(): boolean;
     set active(value: boolean);
+    /**
+     * When `true` the constraint is completely ignored by the engine — bodies are
+     * not woken, no impulse is applied, and no callbacks fire.
+     * @defaultValue `false`
+     */
     get ignore(): boolean;
     set ignore(value: boolean);
+    /**
+     * When `true` (default) the constraint is stiff/rigid.
+     * When `false` the constraint uses a soft spring model driven by
+     * `frequency` and `damping`.
+     * @defaultValue `true`
+     */
     get stiff(): boolean;
     set stiff(value: boolean);
+    /**
+     * Spring frequency in Hz for soft constraints (`stiff = false`).
+     *
+     * Higher values make the spring stiffer; lower values make it bouncier.
+     * Must be `> 0`. Ignored when `stiff` is `true`.
+     * @defaultValue `10`
+     */
     get frequency(): number;
     set frequency(value: number);
+    /**
+     * Damping ratio for soft constraints (`stiff = false`).
+     *
+     * `0` = undamped (oscillates freely), `1` = critically damped.
+     * Values `> 1` are overdamped. Must be `>= 0`. Ignored when `stiff` is `true`.
+     * @defaultValue `1`
+     */
     get damping(): number;
     set damping(value: number);
+    /**
+     * Maximum force (in Newtons) the constraint may apply per step.
+     *
+     * When the required force exceeds this value the constraint becomes slack.
+     * If `breakUnderForce` is `true` the constraint breaks instead.
+     * Must be `>= 0`. `Infinity` disables the limit.
+     * @defaultValue `Infinity`
+     */
     get maxForce(): number;
     set maxForce(value: number);
+    /**
+     * Maximum positional error (in pixels) allowed before breaking.
+     *
+     * Only meaningful when `breakUnderError` is `true`.
+     * Must be `>= 0`. `Infinity` disables the limit.
+     * @defaultValue `Infinity`
+     */
     get maxError(): number;
     set maxError(value: number);
+    /**
+     * When `true`, the constraint breaks (fires a `BREAK` event) if the applied
+     * force exceeds `maxForce` in a single step.
+     * @defaultValue `false`
+     */
     get breakUnderForce(): boolean;
     set breakUnderForce(value: boolean);
+    /**
+     * When `true`, the constraint breaks if the positional error exceeds `maxError`.
+     * @defaultValue `false`
+     */
     get breakUnderError(): boolean;
     set breakUnderError(value: boolean);
+    /**
+     * When `true` (default), the constraint is automatically removed from its space
+     * when it breaks. Set to `false` to keep it in the space after breaking.
+     * @defaultValue `true`
+     */
     get removeOnBreak(): boolean;
     set removeOnBreak(value: boolean);
+    /**
+     * Whether the constraint's simulation component is currently sleeping.
+     *
+     * Only valid when the constraint is active and in a space — throws otherwise.
+     */
     get isSleeping(): boolean;
+    /**
+     * Arbitrary user data attached to this constraint.
+     * Lazily initialized to `{}` on first access.
+     */
     get userData(): Record<string, unknown>;
+    /**
+     * The set of {@link CbType}s assigned to this constraint.
+     * Used to filter which listeners respond to this constraint's events.
+     */
     get cbTypes(): object;
+    /**
+     * The impulse applied by this constraint in the last simulation step.
+     *
+     * The shape of the returned {@link MatMN} depends on the constraint's degrees of
+     * freedom (e.g., 1×1 for AngleJoint/MotorJoint, 2×1 for PivotJoint/LineJoint,
+     * 3×1 for WeldJoint).
+     */
     impulse(): MatMN | null;
+    /**
+     * The impulse applied to `body` by this constraint in the last simulation step,
+     * expressed as a {@link Vec3} `(fx, fy, torque)`.
+     *
+     * @param body - Must be one of the bodies linked to this constraint.
+     */
     bodyImpulse(_body: Body): Vec3 | null;
+    /**
+     * Invokes `fn` once for each distinct body linked to this constraint.
+     *
+     * @param fn - Function to call for each body.
+     */
     visitBodies(_fn: (body: Body) => void): void;
+    /**
+     * Creates and returns a copy of this constraint with the same parameters.
+     * The copy is not automatically added to a space.
+     */
     copy(): Constraint;
     toString(): string;
 }
@@ -1554,77 +2120,275 @@ declare class Broadphase {
 }
 
 /**
- * Interaction type filter for interaction listeners.
+ * Enumeration of interaction categories used to filter {@link InteractionListener}
+ * and {@link PreListener} callbacks.
  *
- * - `COLLISION` — collision interactions only
- * - `SENSOR`    — sensor interactions only
- * - `FLUID`     — fluid interactions only
- * - `ANY`       — any interaction type
+ * - `COLLISION` — physical collisions between solid shapes
+ * - `SENSOR`    — sensor (trigger) interactions where shapes overlap but don't resolve
+ * - `FLUID`     — fluid buoyancy/drag interactions
+ * - `ANY`       — all of the above
  *
  * Converted from nape-compiled.js lines 1785–1883.
  */
 declare class InteractionType {
     static __name__: string[];
     constructor();
+    /** Physical collision between solid shapes (default for most shapes). */
     static get COLLISION(): InteractionType;
+    /** Sensor/trigger overlap — shapes overlap but collision is not resolved. */
     static get SENSOR(): InteractionType;
+    /** Fluid buoyancy/drag interaction between a fluid shape and a body. */
     static get FLUID(): InteractionType;
+    /** Matches all interaction types (COLLISION, SENSOR, and FLUID). */
     static get ANY(): InteractionType;
     toString(): string;
 }
 
 /**
- * The physics world. Add bodies and constraints, then call `step()` each frame.
- *
- * Fully modernized — uses ZPP_Space directly (extracted to TypeScript).
+ * The physics world. Add bodies, shapes, and constraints, then call `step()` each frame to advance the simulation.
  */
 declare class Space {
     zpp_inner: ZPP_Space;
+    /**
+     * @param gravity - Initial gravity vector (default (0, 0)).
+     * @param broadphase - Broadphase algorithm to use.
+     */
     constructor(gravity?: Vec2, broadphase?: Broadphase);
     /** @internal */
     get _inner(): this;
     /** @internal */
     static _wrap(inner: NapeInner): Space;
+    /** Arbitrary user data attached to this Space. */
     get userData(): Record<string, unknown>;
+    /**
+     * World gravity applied to all dynamic bodies each step. Live Vec2.
+     * @throws If set to null or a disposed Vec2.
+     */
     get gravity(): Vec2;
     set gravity(value: Vec2);
+    /** The broadphase algorithm currently in use (SWEEP_AND_PRUNE or DYNAMIC_AABB_TREE). */
     get broadphase(): Broadphase;
+    /** If true, contact points are sorted for determinism. Default: true. */
     get sortContacts(): boolean;
     set sortContacts(value: boolean);
+    /**
+     * Global angular drag coefficient applied to all bodies.
+     * @throws If set to NaN.
+     */
     get worldAngularDrag(): number;
     set worldAngularDrag(value: number);
+    /**
+     * Global linear drag coefficient applied to all bodies.
+     * @throws If set to NaN.
+     */
     get worldLinearDrag(): number;
     set worldLinearDrag(value: number);
+    /** Read-only list of all Compound objects in this space. */
     get compounds(): object;
+    /** Read-only list of all Body objects directly in this space. */
     get bodies(): object;
+    /** Read-only list of bodies that are awake and actively simulated. */
     get liveBodies(): object;
+    /** Read-only list of all Constraint objects in this space. */
     get constraints(): object;
+    /** Read-only list of active (awake) constraints. */
     get liveConstraints(): object;
+    /** The static world body that acts as an immovable anchor for constraints. */
     get world(): Body;
+    /** Read-only list of all active collision/fluid arbiters. */
     get arbiters(): object;
+    /** Read-only list of all event listeners registered to this space. */
     get listeners(): object;
+    /** Number of `step()` calls made so far. */
     get timeStamp(): number;
+    /** Cumulative time simulated (sum of all `deltaTime` values passed to `step()`). */
     get elapsedTime(): number;
+    /**
+     * Advance the simulation by `deltaTime` seconds.
+     * `velocityIterations` and `positionIterations` control solver accuracy (default 10 each).
+     * @param deltaTime - Time step in seconds; must be strictly positive and not NaN.
+     * @param velocityIterations - Number of velocity solver iterations (minimum 1).
+     * @param positionIterations - Number of position solver iterations (minimum 1).
+     * @throws If `deltaTime` is NaN, non-positive, or any iteration count is less than 1.
+     */
     step(deltaTime: number, velocityIterations?: number, positionIterations?: number): void;
+    /**
+     * Remove all bodies, constraints, and compounds from this space.
+     * @throws If called during a `step()`.
+     */
     clear(): void;
+    /**
+     * Call `lambda` for every body in the space, including those inside compounds.
+     * @param lambda - Callback invoked with each Body.
+     * @throws If `lambda` is null.
+     */
     visitBodies(lambda: (body: Body) => void): void;
+    /**
+     * Call `lambda` for every constraint in the space, including those inside compounds.
+     * @param lambda - Callback invoked with each Constraint.
+     * @throws If `lambda` is null.
+     */
     visitConstraints(lambda: (constraint: Constraint) => void): void;
+    /**
+     * Call `lambda` for every compound in the space (recursively).
+     * @param lambda - Callback invoked with each Compound.
+     * @throws If `lambda` is null.
+     */
     visitCompounds(lambda: (compound: Compound) => void): void;
+    /**
+     * Determine the type of interaction between two shapes (COLLISION, FLUID, SENSOR, or null if they don't interact).
+     * @param shape1 - The first shape; must belong to a Body.
+     * @param shape2 - The second shape; must belong to a Body.
+     * @returns The InteractionType, or null if the shapes would not interact.
+     * @throws If either shape is null or not attached to a Body.
+     */
     interactionType(shape1: Shape, shape2: Shape): InteractionType | null;
+    /**
+     * Return all shapes whose geometry contains the given world-space point.
+     * @param point - The world-space point to test.
+     * @param filter - Optional interaction filter to restrict results.
+     * @param output - Optional existing ShapeList to accumulate results into.
+     * @returns A ShapeList of matching shapes.
+     * @throws If `point` is null or disposed.
+     */
     shapesUnderPoint(point: Vec2, filter?: InteractionFilter | null, output?: object | null): object;
+    /**
+     * Return all bodies that have at least one shape containing the given world-space point.
+     * @param point - The world-space point to test.
+     * @param filter - Optional interaction filter to restrict results.
+     * @param output - Optional existing BodyList to accumulate results into.
+     * @returns A BodyList of matching bodies.
+     * @throws If `point` is null or disposed.
+     */
     bodiesUnderPoint(point: Vec2, filter?: InteractionFilter | null, output?: object | null): object;
+    /**
+     * Return all shapes that overlap with the given AABB.
+     * @param aabb - The axis-aligned bounding box to test against.
+     * @param containment - If true, only shapes fully contained within the AABB are returned.
+     * @param strict - If true, exact shape geometry is tested; otherwise only AABBs are compared.
+     * @param filter - Optional interaction filter to restrict results.
+     * @param output - Optional existing ShapeList to accumulate results into.
+     * @returns A ShapeList of matching shapes.
+     * @throws If `aabb` is null or degenerate (zero width or height).
+     */
     shapesInAABB(aabb: AABB, containment?: boolean, strict?: boolean, filter?: InteractionFilter | null, output?: object | null): object;
+    /**
+     * Return all bodies that have at least one shape overlapping the given AABB.
+     * @param aabb - The axis-aligned bounding box to test against.
+     * @param containment - If true, only shapes fully contained within the AABB count.
+     * @param strict - If true, exact shape geometry is tested; otherwise only AABBs are compared.
+     * @param filter - Optional interaction filter to restrict results.
+     * @param output - Optional existing BodyList to accumulate results into.
+     * @returns A BodyList of matching bodies.
+     * @throws If `aabb` is null or degenerate (zero width or height).
+     */
     bodiesInAABB(aabb: AABB, containment?: boolean, strict?: boolean, filter?: InteractionFilter | null, output?: object | null): object;
+    /**
+     * Return all shapes that overlap with a circle defined by `position` and `radius`.
+     * @param position - World-space centre of the query circle.
+     * @param radius - Radius of the query circle; must be strictly positive and not NaN.
+     * @param containment - If true, only shapes fully contained within the circle are returned.
+     * @param filter - Optional interaction filter to restrict results.
+     * @param output - Optional existing ShapeList to accumulate results into.
+     * @returns A ShapeList of matching shapes.
+     * @throws If `position` is null/disposed, or `radius` is NaN or non-positive.
+     */
     shapesInCircle(position: Vec2, radius: number, containment?: boolean, filter?: InteractionFilter | null, output?: object | null): object;
+    /**
+     * Return all bodies that have at least one shape overlapping a query circle.
+     * @param position - World-space centre of the query circle.
+     * @param radius - Radius of the query circle; must be strictly positive and not NaN.
+     * @param containment - If true, only shapes fully contained within the circle count.
+     * @param filter - Optional interaction filter to restrict results.
+     * @param output - Optional existing BodyList to accumulate results into.
+     * @returns A BodyList of matching bodies.
+     * @throws If `position` is null/disposed, or `radius` is NaN or non-positive.
+     */
     bodiesInCircle(position: Vec2, radius: number, containment?: boolean, filter?: InteractionFilter | null, output?: object | null): object;
+    /**
+     * Return all shapes in the space that overlap with `shape`.
+     * @param shape - The query shape; must be attached to a Body.
+     * @param containment - If true, only shapes fully contained within `shape` are returned.
+     * @param filter - Optional interaction filter to restrict results.
+     * @param output - Optional existing ShapeList to accumulate results into.
+     * @returns A ShapeList of overlapping shapes.
+     * @throws If `shape` is null, not attached to a Body, or is an invalid polygon.
+     */
     shapesInShape(shape: Shape, containment?: boolean, filter?: InteractionFilter | null, output?: object | null): object;
+    /**
+     * Return all bodies in the space that have at least one shape overlapping `shape`.
+     * @param shape - The query shape; must be attached to a Body.
+     * @param containment - If true, only shapes fully contained within `shape` count.
+     * @param filter - Optional interaction filter to restrict results.
+     * @param output - Optional existing BodyList to accumulate results into.
+     * @returns A BodyList of overlapping bodies.
+     * @throws If `shape` is null, not attached to a Body, or is an invalid polygon.
+     */
     bodiesInShape(shape: Shape, containment?: boolean, filter?: InteractionFilter | null, output?: object | null): object;
+    /**
+     * Return all shapes in the space that overlap with any shape attached to `body`.
+     * Equivalent to calling `shapesInShape` for each of `body`'s shapes and merging results.
+     * @param body - The body whose shapes are used as the query region.
+     * @param filter - Optional interaction filter to restrict results.
+     * @param output - Optional existing ShapeList to accumulate results into.
+     * @returns A ShapeList of overlapping shapes.
+     * @throws If `body` is null.
+     */
     shapesInBody(body: Body, filter?: InteractionFilter | null, output?: object | null): object;
+    /**
+     * Return all bodies in the space that overlap with any shape attached to `body`.
+     * Equivalent to calling `bodiesInShape` for each of `body`'s shapes and merging results.
+     * @param body - The body whose shapes are used as the query region.
+     * @param filter - Optional interaction filter to restrict results.
+     * @param output - Optional existing BodyList to accumulate results into.
+     * @returns A BodyList of overlapping bodies.
+     * @throws If `body` is null.
+     */
     bodiesInBody(body: Body, filter?: InteractionFilter | null, output?: object | null): object;
+    /**
+     * Sweep `shape` along its current velocity for `deltaTime` seconds and return the first hit.
+     * @param shape - The shape to sweep; must belong to a Body.
+     * @param deltaTime - Duration of the sweep; must be non-negative.
+     * @param liveSweep - If true, other body velocities are considered during the sweep.
+     * @param filter - Optional interaction filter to restrict results.
+     * @returns The first RayResult hit, or null if nothing was struck.
+     * @throws If `shape` is null, not attached to a Body, or `deltaTime` is negative/NaN.
+     */
     convexCast(shape: Shape, deltaTime: number, liveSweep?: boolean, filter?: InteractionFilter | null): object | null;
+    /**
+     * Sweep `shape` along its current velocity for `deltaTime` seconds and return all hits.
+     * @param shape - The shape to sweep; must belong to a Body.
+     * @param deltaTime - Duration of the sweep; must be non-negative.
+     * @param liveSweep - If true, other body velocities are considered during the sweep.
+     * @param filter - Optional interaction filter to restrict results.
+     * @param output - Optional existing RayResultList to accumulate results into.
+     * @returns A RayResultList of all hits encountered during the sweep.
+     * @throws If `shape` is null, not attached to a Body, or `deltaTime` is negative/NaN.
+     */
     convexMultiCast(shape: Shape, deltaTime: number, liveSweep?: boolean, filter?: InteractionFilter | null, output?: object | null): object;
+    /**
+     * Cast a ray into the space and return the closest hit.
+     * @param ray - The ray to cast.
+     * @param inner - If true, shapes are tested from the inside as well (useful for concave queries).
+     * @param filter - Optional interaction filter to restrict results.
+     * @returns The closest RayResult, or null if nothing was hit.
+     * @throws If `ray` is null.
+     */
     rayCast(ray: Ray, inner?: boolean, filter?: InteractionFilter | null): object | null;
+    /**
+     * Cast a ray into the space and return all hits.
+     * @param ray - The ray to cast.
+     * @param inner - If true, shapes are tested from the inside as well.
+     * @param filter - Optional interaction filter to restrict results.
+     * @param output - Optional existing RayResultList to accumulate results into.
+     * @returns A RayResultList of all shapes the ray intersected.
+     * @throws If `ray` is null.
+     */
     rayMultiCast(ray: Ray, inner?: boolean, filter?: InteractionFilter | null, output?: object | null): object;
+    /**
+     * Returns a brief string summary of this space.
+     * @returns A string in the form `Space(bodies=N)`.
+     */
     toString(): string;
 }
 
@@ -2083,107 +2847,350 @@ declare class GravMassMode {
 }
 
 /**
- * A rigid body in the physics simulation.
- *
- * Fully modernized — all methods implemented directly using ZPP_Body.
+ * A rigid body in the physics simulation. Add shapes to give it geometry, then add it to a `Space` to participate in simulation.
  */
 declare class Body extends Interactor {
     static __name__: string[];
     static __super__: typeof Interactor;
     /** Direct access to the extracted internal ZPP_Body. */
     zpp_inner: ZPP_Body;
+    /** If true, this body is included in debug rendering. */
     debugDraw: boolean;
+    /**
+     * @param type - Body type (DYNAMIC by default).
+     * @param position - Initial world-space position (defaults to origin).
+     */
     constructor(type?: BodyType, position?: Vec2);
     /** @internal */
     static _wrap(inner: NapeInner): Body;
+    /** The body type: DYNAMIC, STATIC, or KINEMATIC. Cannot be changed mid-step. */
     get type(): BodyType;
     set type(value: BodyType);
+    /** Return true if this body is static. */
     isStatic(): boolean;
+    /** Return true if this body is dynamic. */
     isDynamic(): boolean;
+    /** Return true if this body is kinematic. */
     isKinematic(): boolean;
+    /** World-space position of the body's origin. Live Vec2 — mutating it moves the body. */
     get position(): Vec2;
     set position(value: Vec2);
+    /**
+     * Rotation of the body in radians.
+     * @throws If set on a static body that is already in a space.
+     */
     get rotation(): number;
     set rotation(value: number);
+    /** Linear velocity in world space (units/s). Live Vec2. Static bodies cannot have velocity. */
     get velocity(): Vec2;
     set velocity(value: Vec2);
+    /** Angular velocity in radians per second. */
     get angularVel(): number;
     set angularVel(value: number);
+    /** Desired velocity for kinematic bodies; the engine tries to match this each step. */
     get kinematicVel(): Vec2;
     set kinematicVel(value: Vec2);
+    /** Desired angular velocity for kinematic bodies. */
     get kinAngVel(): number;
     set kinAngVel(value: number);
+    /** Surface velocity used in friction calculations. */
     get surfaceVel(): Vec2;
     set surfaceVel(value: Vec2);
+    /** Accumulated force applied to this body for the current step (cleared after each step). */
     get force(): Vec2;
     set force(value: Vec2);
+    /** Accumulated torque applied to this body for the current step (only for DYNAMIC bodies). */
     get torque(): number;
     set torque(value: number);
+    /**
+     * Mass in kg. Must be finite and > 0. Setting switches massMode to FIXED.
+     * @throws If the body is the world body, or if no shapes are present in DEFAULT mass mode.
+     */
     get mass(): number;
     set mass(value: number);
+    /**
+     * Moment of inertia. Must be finite and > 0. Setting switches inertiaMode to FIXED.
+     * @throws If the body is the world body, or if no shapes are present in DEFAULT inertia mode.
+     */
     get inertia(): number;
     set inertia(value: number);
+    /** Effective mass used by the constraint solver (accounts for allowMovement). */
     get constraintMass(): number;
+    /** Effective inertia used by the constraint solver (accounts for allowRotation). */
     get constraintInertia(): number;
+    /** Gravitational mass. Defaults to the same as `mass`. */
     get gravMass(): number;
     set gravMass(value: number);
+    /** Scale factor applied to gravMass relative to the dynamic mass. */
     get gravMassScale(): number;
     set gravMassScale(value: number);
+    /** If true, continuous collision detection (CCD) is enabled for this body. */
     get isBullet(): boolean;
     set isBullet(value: boolean);
+    /** If true, CCD is disabled even if `isBullet` is set. */
     get disableCCD(): boolean;
     set disableCCD(value: boolean);
+    /** If false, translational motion is frozen (infinite effective mass). */
     get allowMovement(): boolean;
     set allowMovement(value: boolean);
+    /** If false, rotational motion is frozen (infinite effective inertia). */
     get allowRotation(): boolean;
     set allowRotation(value: boolean);
+    /**
+     * True if the body is currently sleeping.
+     * @throws If the body is not in a Space.
+     */
     get isSleeping(): boolean;
+    /** List of shapes attached to this body. */
     get shapes(): NapeList<Shape>;
+    /** The Space this body belongs to. Setting adds/removes it from the space. */
     get space(): Space;
     set space(value: Space | null);
+    /** The Compound this body belongs to, or null. */
     get compound(): Compound | null;
     set compound(value: Compound | null);
+    /**
+     * World-space AABB enclosing all shapes.
+     * @throws If this is the world body.
+     */
     get bounds(): AABB;
+    /** Constraint-solved velocity (read-only view used by the solver). */
     get constraintVelocity(): Vec2;
+    /**
+     * Local-space centre of mass (read-only, lazy-computed from shapes).
+     * @throws If this is the world body.
+     */
     get localCOM(): Vec2;
+    /**
+     * World-space centre of mass (read-only, lazy-computed).
+     * @throws If this is the world body.
+     */
     get worldCOM(): Vec2;
+    /** Controls how mass is computed: DEFAULT (from shapes) or FIXED (manually set). */
     get massMode(): MassMode;
     set massMode(value: MassMode);
+    /** Controls how inertia is computed: DEFAULT or FIXED. */
     get inertiaMode(): InertiaMode;
     set inertiaMode(value: InertiaMode);
+    /** Controls gravitational mass: DEFAULT, FIXED, or SCALED. */
     get gravMassMode(): GravMassMode;
     set gravMassMode(value: GravMassMode);
+    /**
+     * Create a deep copy of this body (shapes, mass properties, etc.).
+     * @returns A new Body with identical configuration.
+     * @throws If this is the world body.
+     */
     copy(): Body;
+    /**
+     * String identifier like `(dynamic)#42`.
+     * @returns A human-readable description of this body.
+     */
     toString(): string;
+    /**
+     * Manually integrate the body's position and rotation by `deltaTime` seconds (outside of `Space.step`).
+     * @param deltaTime - Time in seconds to integrate over.
+     * @returns `this` for chaining.
+     * @throws If `deltaTime` is NaN.
+     */
     integrate(deltaTime: number): Body;
+    /**
+     * Transform a point from local body space to world space.
+     * @param point - The point in local space.
+     * @param weak - If true, the returned Vec2 is a weak (pooled) reference.
+     * @returns The transformed point in world space.
+     */
     localPointToWorld(point: Vec2, weak?: boolean): Vec2;
+    /**
+     * Transform a point from world space to local body space.
+     * @param point - The point in world space.
+     * @param weak - If true, the returned Vec2 is a weak (pooled) reference.
+     * @returns The transformed point in local space.
+     */
     worldPointToLocal(point: Vec2, weak?: boolean): Vec2;
+    /**
+     * Rotate a vector from local body space to world space (no translation).
+     * @param vector - The vector in local space.
+     * @param weak - If true, the returned Vec2 is a weak (pooled) reference.
+     * @returns The rotated vector in world space.
+     */
     localVectorToWorld(vector: Vec2, weak?: boolean): Vec2;
+    /**
+     * Rotate a vector from world space to local body space (no translation).
+     * @param vector - The vector in world space.
+     * @param weak - If true, the returned Vec2 is a weak (pooled) reference.
+     * @returns The rotated vector in local space.
+     */
     worldVectorToLocal(vector: Vec2, weak?: boolean): Vec2;
+    /**
+     * Apply a linear (and optionally angular) impulse to the body.
+     * If `pos` is given, it creates a torque about the body's centre.
+     * If `sleepable` is true, sleeping bodies are not woken.
+     * @param impulse - The linear impulse vector (world space).
+     * @param pos - Optional world-space point of application.
+     * @param sleepable - If true, the body will not be woken if sleeping.
+     * @returns `this` for chaining.
+     */
     applyImpulse(impulse: Vec2, pos?: Vec2, sleepable?: boolean): Body;
+    /**
+     * Apply a direct angular impulse (change in angular velocity × inertia).
+     * @param impulse - The angular impulse magnitude.
+     * @param sleepable - If true, the body will not be woken if sleeping.
+     * @returns `this` for chaining.
+     */
     applyAngularImpulse(impulse: number, sleepable?: boolean): Body;
+    /**
+     * Set linear and angular velocity so the body reaches the given target pose in `deltaTime` seconds.
+     * Useful for kinematic or manually driven bodies.
+     * @param targetPosition - Desired world-space position.
+     * @param targetRotation - Desired rotation in radians.
+     * @param deltaTime - Time in seconds over which to reach the target.
+     * @returns `this` for chaining.
+     * @throws If `targetPosition` is null or `deltaTime` is zero.
+     */
     setVelocityFromTarget(targetPosition: Vec2, targetRotation: number, deltaTime: number): Body;
+    /**
+     * Translate all shapes attached to this body in local space by `translation`.
+     * @param translation - Offset vector in local space.
+     * @returns `this` for chaining.
+     */
     translateShapes(translation: Vec2): Body;
+    /**
+     * Rotate all shapes attached to this body in local space by `angle` radians.
+     * @param angle - Rotation in radians.
+     * @returns `this` for chaining.
+     */
     rotateShapes(angle: number): Body;
+    /**
+     * Scale all shapes attached to this body in local space.
+     * @param scaleX - Horizontal scale factor.
+     * @param scaleY - Vertical scale factor.
+     * @returns `this` for chaining.
+     */
     scaleShapes(scaleX: number, scaleY: number): Body;
+    /**
+     * Apply an affine transform matrix to all shapes in local space.
+     * @param matrix - The 2D affine transformation matrix.
+     * @returns `this` for chaining.
+     */
     transformShapes(matrix: Mat23): Body;
+    /**
+     * Translate all shapes and adjust the body position so the local centre of mass coincides with the body origin.
+     * @returns `this` for chaining.
+     * @throws If the body has no shapes.
+     */
     align(): Body;
+    /**
+     * Rotate the body about a world-space pivot point by `angle` radians.
+     * Moves the body's position and increments its rotation.
+     * @param centre - World-space pivot point.
+     * @param angle - Rotation in radians.
+     * @returns `this` for chaining.
+     * @throws If `centre` is null or `angle` is NaN.
+     */
     rotate(centre: Vec2, angle: number): Body;
+    /**
+     * Set the same `Material` on every shape attached to this body.
+     * @param material - The material to apply.
+     * @returns `this` for chaining.
+     */
     setShapeMaterials(material: Material): Body;
+    /**
+     * Set the same `InteractionFilter` on every shape attached to this body.
+     * @param filter - The interaction filter to apply.
+     * @returns `this` for chaining.
+     */
     setShapeFilters(filter: InteractionFilter): Body;
+    /**
+     * Set the same `FluidProperties` on every shape attached to this body.
+     * @param fluidProperties - The fluid properties to apply.
+     * @returns `this` for chaining.
+     */
     setShapeFluidProperties(fluidProperties: FluidProperties): Body;
+    /**
+     * Test whether a world-space point lies inside any shape attached to this body.
+     * @param point - The point to test in world space.
+     * @returns True if the point is inside at least one shape.
+     */
     contains(point: Vec2): boolean;
+    /**
+     * Return the set of bodies connected to this body via constraints.
+     * @param depth - Maximum traversal depth (-1 means unlimited).
+     * @param output - Optional existing list to accumulate results into.
+     * @returns A BodyList of connected bodies.
+     */
     connectedBodies(depth?: number, output?: object | null): object;
+    /**
+     * Return the set of bodies currently interacting with this body via arbiters.
+     * @param type - Filter by interaction type (COLLISION, FLUID, SENSOR), or null for all.
+     * @param _depth - Unused; reserved for future use.
+     * @param output - Optional existing list to accumulate results into.
+     * @returns A BodyList of interacting bodies.
+     */
     interactingBodies(type?: InteractionType | null, _depth?: number, output?: object | null): object;
+    /**
+     * Sum of normal (penetration-resolving) impulses received from collision arbiters this step.
+     * @param body - If provided, only arbiters shared with `body` are summed.
+     * @param freshOnly - If true, only newly created arbiters are considered.
+     * @returns A Vec3 where x/y are the linear component and z is the angular component.
+     */
     normalImpulse(body?: Body | null, freshOnly?: boolean): Vec3;
+    /**
+     * Sum of tangent (friction) impulses received from collision arbiters this step.
+     * @param body - If provided, only arbiters shared with `body` are summed.
+     * @param freshOnly - If true, only newly created arbiters are considered.
+     * @returns A Vec3 where x/y are the linear component and z is the angular component.
+     */
     tangentImpulse(body?: Body | null, freshOnly?: boolean): Vec3;
+    /**
+     * Sum of total contact impulses (normal + tangent) from collision arbiters this step.
+     * @param body - If provided, only arbiters shared with `body` are summed.
+     * @param freshOnly - If true, only newly created arbiters are considered.
+     * @returns A Vec3 where x/y are the linear component and z is the angular component.
+     */
     totalContactsImpulse(body?: Body | null, freshOnly?: boolean): Vec3;
+    /**
+     * Sum of rolling (angular friction) impulses from collision arbiters this step.
+     * @param body - If provided, only arbiters shared with `body` are summed.
+     * @param freshOnly - If true, only newly created arbiters are considered.
+     * @returns The total rolling impulse scalar.
+     */
     rollingImpulse(body?: Body | null, freshOnly?: boolean): number;
+    /**
+     * Sum of buoyancy impulses received from fluid arbiters this step.
+     * @param body - If provided, only arbiters shared with `body` are summed.
+     * @returns A Vec3 where x/y are the linear component and z is the angular component.
+     */
     buoyancyImpulse(body?: Body | null): Vec3;
+    /**
+     * Sum of fluid drag impulses received from fluid arbiters this step.
+     * @param body - If provided, only arbiters shared with `body` are summed.
+     * @returns A Vec3 where x/y are the linear component and z is the angular component.
+     */
     dragImpulse(body?: Body | null): Vec3;
+    /**
+     * Sum of total fluid impulses (buoyancy + drag) from fluid arbiters this step.
+     * @param body - If provided, only arbiters shared with `body` are summed.
+     * @returns A Vec3 where x/y are the linear component and z is the angular component.
+     */
     totalFluidImpulse(body?: Body | null): Vec3;
+    /**
+     * Sum of impulses applied to this body by all attached constraints this step.
+     * @returns A Vec3 where x/y are the linear component and z is the angular component.
+     */
     constraintsImpulse(): Vec3;
+    /**
+     * Sum of all impulses (contacts + constraints) applied to this body this step, excluding sensor arbiters.
+     * @param body - If provided, only arbiters shared with `body` are summed.
+     * @param freshOnly - If true, only newly created contact arbiters are considered.
+     * @returns A Vec3 where x/y are the linear component and z is the angular component.
+     */
     totalImpulse(body?: Body | null, freshOnly?: boolean): Vec3;
+    /**
+     * Compute a heuristic crush factor indicating how strongly this body is being compressed from multiple directions.
+     * A value near zero means balanced forces; larger values indicate compression.
+     * @returns The crush factor (dimensionless).
+     * @throws If the body is not in a Space.
+     */
     crushFactor(): number;
     private _getArbiters;
     private _getConstraints;
@@ -2207,48 +3214,99 @@ declare class ShapeType {
 }
 
 /**
- * Base class for physics shapes (Circle, Polygon).
- *
- * Fully modernized — all getters/setters access the ZPP_Shape inner directly.
+ * Base class for physics shapes (Circle, Polygon). Never instantiated directly — use
+ * `new Circle(...)` or `Polygon.box(...)` etc.
  */
 declare class Shape extends Interactor {
     /** @internal – shapes are created via Circle or Polygon constructors. */
     protected constructor();
     /** @internal */
     static _wrap(inner: NapeInner): Shape;
+    /** The shape type: CIRCLE or POLYGON. */
     get type(): ShapeType;
+    /** Returns true if this is a Circle shape. */
     isCircle(): boolean;
+    /** Returns true if this is a Polygon shape. */
     isPolygon(): boolean;
+    /**
+     * The Body this shape belongs to. Setting moves the shape between bodies.
+     */
     get body(): Body;
     set body(value: Body | null);
+    /** Cast to Circle, or null if this is not a circle. */
     get castCircle(): Shape | null;
+    /** Cast to Polygon, or null if this is not a polygon. */
     get castPolygon(): Shape | null;
+    /** World-space centre of mass of this shape (read-only, lazy-computed). */
     get worldCOM(): Vec2;
+    /**
+     * Local-space centre of mass. Can be set to override the default shape centroid.
+     */
     get localCOM(): Vec2;
     set localCOM(value: Vec2);
+    /** Cross-sectional area of this shape. */
     get area(): number;
+    /** Contribution to moment of inertia (about local centroid, unit density). */
     get inertia(): number;
+    /** Angular drag coefficient for this shape. */
     get angDrag(): number;
+    /** The Material assigned to this shape (controls friction, elasticity, density). */
     get material(): Material;
     set material(value: Material);
+    /** The InteractionFilter controlling which shapes interact with this one. */
     get filter(): InteractionFilter;
     set filter(value: InteractionFilter);
+    /** Fluid simulation properties for this shape. Auto-created on first access. */
     get fluidProperties(): FluidProperties;
     set fluidProperties(value: FluidProperties);
-    /** Callback types assigned to this shape. */
+    /** Set of callback types registered on this shape for event dispatch. */
     get cbTypes(): CbTypeSet;
+    /** If true, this shape participates in fluid interaction. */
     get fluidEnabled(): boolean;
     set fluidEnabled(value: boolean);
+    /** If true, this shape acts as a sensor (no physical response, only callbacks). */
     get sensorEnabled(): boolean;
     set sensorEnabled(value: boolean);
+    /** World-space AABB of this shape (updated each step). */
     get bounds(): AABB;
+    /**
+     * Translate the shape's local vertices by the given vector (in-place).
+     * @param translation - The displacement vector to apply.
+     * @returns `this` for chaining.
+     */
     translate(translation: Vec2): Shape;
+    /**
+     * Scale the shape's local geometry. Circles require uniform scaling.
+     * @param scaleX - Horizontal scale factor (must be non-zero).
+     * @param scaleY - Vertical scale factor (must be non-zero).
+     * @returns `this` for chaining.
+     */
     scale(scaleX: number, scaleY: number): Shape;
+    /**
+     * Rotate the shape's local vertices by `angle` radians.
+     * @param angle - Rotation in radians.
+     * @returns `this` for chaining.
+     */
     rotate(angle: number): Shape;
+    /**
+     * Apply a Mat23 affine transform to the shape's local geometry.
+     * @param matrix - The transformation matrix (must be non-singular; Circles require equiorthogonal).
+     * @returns `this` for chaining.
+     */
     transform(matrix: {
         _inner: NapeInner;
     }): Shape;
+    /**
+     * Return true if the given world-space point lies inside this shape.
+     * Requires the shape to be attached to a Body.
+     * @param point - The world-space point to test.
+     * @returns True if the point is inside this shape.
+     */
     contains(point: Vec2): boolean;
+    /**
+     * Create a deep copy of this shape with the same type, geometry, material, and filter.
+     * @returns A new Shape instance independent of this one.
+     */
     copy(): Shape;
     toString(): string;
     /** @internal */ get_type(): ShapeType;
@@ -2439,20 +3497,24 @@ declare class ZPP_Circle {
 }
 
 /**
- * A circular physics shape.
- *
- * Fully modernized — constructor and radius getter/setter use ZPP_Circle
- * directly. Shape-level properties still delegate through compiled Shape
- * prototype methods (copied to Circle.prototype at module load time).
+ * A circular physics shape. The simplest and most performant collision shape.
  */
 declare class Circle extends Shape {
     static __name__: string[];
     static __super__: any;
     /** Direct access to the extracted internal ZPP_Circle. */
     zpp_inner_zn: ZPP_Circle;
+    /**
+     * Create a circle with the given radius and optional local centre-of-mass offset.
+     * @param radius - Circle radius (must be > 0).
+     * @param localCOM - Local centre offset (defaults to origin).
+     * @param material - Material to assign (uses default if omitted).
+     * @param filter - InteractionFilter to assign (uses default if omitted).
+     */
     constructor(radius?: number, localCOM?: Vec2, material?: Material, filter?: InteractionFilter);
     /** @internal */
     static _wrap(inner: NapeInner): Circle;
+    /** The circle's radius. Must be > 0. */
     get radius(): number;
     set radius(value: number);
 }
@@ -2574,28 +3636,61 @@ declare class ZPP_Polygon {
 
 /**
  * A convex polygon physics shape.
- *
- * Fully modernized — uses ZPP_Polygon directly (extracted to TypeScript).
- * Use the static helper methods (`box`, `rect`, `regular`) for common shapes.
  */
 declare class Polygon extends Shape {
     static __name__: string[];
     static __super__: any;
     /** Direct access to the extracted internal ZPP_Polygon. */
     zpp_inner_zn: ZPP_Polygon;
+    /**
+     * Create a Polygon from a list of Vec2 vertices. Vertices must form a convex polygon
+     * in counter-clockwise order.
+     * @param localVerts - Vertices as `Array<Vec2>`, `Vec2List`, or `GeomPoly`.
+     * @param material - Material to assign (uses default if omitted).
+     * @param filter - InteractionFilter to assign (uses default if omitted).
+     */
     constructor(localVerts?: Vec2[] | any, material?: Material, filter?: InteractionFilter);
     /** @internal */
     static _wrap(inner: NapeInner): Polygon;
+    /**
+     * Create an axis-aligned rectangle at the given position.
+     * @param x - Left edge x coordinate.
+     * @param y - Top edge y coordinate.
+     * @param width - Rectangle width.
+     * @param height - Rectangle height.
+     * @param weak - If true, returned Vec2s are marked weak and will be auto-disposed.
+     * @returns Array of four Vec2 corner vertices.
+     */
     static rect(x: number, y: number, width: number, height: number, weak?: boolean): Vec2[];
+    /**
+     * Create an axis-aligned rectangular polygon centred at the origin.
+     * @param width - Rectangle width.
+     * @param height - Rectangle height (defaults to `width` for a square).
+     * @param weak - If true, returned Vec2s are marked weak and will be auto-disposed.
+     * @returns Array of four Vec2 corner vertices.
+     */
     static box(width: number, height?: number, weak?: boolean): Vec2[];
+    /**
+     * Create a regular polygon (or ellipse approximation) centred at the origin.
+     * @param xRadius - Horizontal radius of the circumscribed ellipse.
+     * @param yRadius - Vertical radius of the circumscribed ellipse.
+     * @param edgeCount - Number of sides (must be >= 3).
+     * @param angleOffset - Rotation offset in radians applied to all vertices (default 0).
+     * @param weak - If true, returned Vec2s are marked weak and will be auto-disposed.
+     * @returns Array of `edgeCount` Vec2 vertices.
+     */
     static regular(xRadius: number, yRadius: number, edgeCount: number, angleOffset?: number, weak?: boolean): Vec2[];
-    /** Read-only list of local-space vertices. */
+    /** The list of local-space vertices defining this polygon's shape. */
     get localVerts(): any;
-    /** Read-only list of world-space vertices (computed after stepping). */
+    /** World-space vertices of this polygon, updated each simulation step. */
     get worldVerts(): any;
-    /** Read-only edge list. */
+    /** The list of edges derived from this polygon's vertices. */
     get edges(): any;
-    /** Validate the polygon geometry. */
+    /**
+     * Validate the polygon geometry and return a string describing any issues, or
+     * `"valid"` if the polygon is well-formed.
+     * @returns A validation result string from the underlying ZPP_Polygon.
+     */
     validity(): any;
     /** @internal */ get_localVerts(): any;
     /** @internal */ get_worldVerts(): any;
@@ -2792,10 +3887,14 @@ declare class ZPP_Arbiter {
 }
 
 /**
- * A collision arbiter between two shapes in contact.
+ * An arbiter representing a physical collision between two solid shapes.
  *
- * Provides access to contact points, collision normal, friction, elasticity,
- * and impulse information. Some properties are mutable only in pre-handlers.
+ * Provides access to contact points, collision normal, friction coefficients,
+ * elasticity, and impulse data. Properties marked _mutable in pre-handler_ can
+ * only be set within a {@link PreListener} handler.
+ *
+ * Obtain via {@link Arbiter.collisionArbiter} or by casting from a callback's
+ * arbiter list.
  *
  * Fully modernized — uses extracted ZPP_ColArbiter directly.
  */
@@ -2803,8 +3902,15 @@ declare class CollisionArbiter extends Arbiter {
     static __name__: string[];
     static __super__: typeof Arbiter;
     constructor();
+    /**
+     * The list of active contact points between the two shapes.
+     * Contains 1 or 2 {@link Contact} objects depending on the collision geometry.
+     */
     get contacts(): object;
-    /** Collision normal vector. */
+    /**
+     * Collision normal vector pointing from `shape1` toward `shape2`.
+     * Read-only; available after the arbiter is active.
+     */
     get normal(): Vec2;
     /** Sum of the radii of the two shapes at the collision point. */
     get radius(): number;
@@ -2812,29 +3918,57 @@ declare class CollisionArbiter extends Arbiter {
     get referenceEdge1(): Edge | null;
     /** Reference edge of shape2 (if polygon), or null. */
     get referenceEdge2(): Edge | null;
-    /** Coefficient of restitution (elasticity). Mutable in pre-handler only. */
+    /**
+     * Coefficient of restitution (bounciness).
+     *
+     * Combined from the two shapes' `elasticity` values. Can be overridden
+     * inside a pre-handler. Must be `>= 0`.
+     *
+     * _Mutable in pre-handler only._
+     */
     get elasticity(): number;
     set elasticity(value: number);
-    /** Dynamic friction coefficient. Mutable in pre-handler only. */
+    /**
+     * Dynamic (kinetic) friction coefficient — applied when the contact is sliding.
+     * Combined from the two shapes' material values. _Mutable in pre-handler only._
+     */
     get dynamicFriction(): number;
     set dynamicFriction(value: number);
-    /** Static friction coefficient. Mutable in pre-handler only. */
+    /**
+     * Static friction coefficient — applied when the contact is at rest.
+     * Combined from the two shapes' material values. _Mutable in pre-handler only._
+     */
     get staticFriction(): number;
     set staticFriction(value: number);
-    /** Rolling friction coefficient. Mutable in pre-handler only. */
+    /**
+     * Rolling friction coefficient — resists rolling motion.
+     * Combined from the two shapes' material values. _Mutable in pre-handler only._
+     */
     get rollingFriction(): number;
     set rollingFriction(value: number);
     /** Whether the first contact point lies on a polygon vertex (poly-circle only). */
     firstVertex(): boolean;
     /** Whether the second contact point lies on a polygon vertex (poly-circle only). */
     secondVertex(): boolean;
-    /** Normal impulse accumulated across all contacts. */
+    /**
+     * Impulse applied in the normal (collision) direction, summed over all contacts.
+     * @param body - One of the two bodies, or `null` for the combined value.
+     * @param freshOnly - Only include new contact points. Default `false`.
+     */
     normalImpulse(body?: Body | null, freshOnly?: boolean): Vec3;
-    /** Tangent (friction) impulse accumulated across all contacts. */
+    /**
+     * Friction impulse applied in the tangent direction, summed over all contacts.
+     * @param body - One of the two bodies, or `null` for the combined value.
+     * @param freshOnly - Only include new contact points. Default `false`.
+     */
     tangentImpulse(body?: Body | null, freshOnly?: boolean): Vec3;
     /** Total impulse (normal + tangent + rolling) accumulated across all contacts. */
     totalImpulse(body?: Body | null, freshOnly?: boolean): Vec3;
-    /** Rolling impulse for this collision. */
+    /**
+     * Rolling impulse applied by this collision.
+     * @param body - One of the two bodies, or `null` for the combined value.
+     * @param freshOnly - Only include new contact points. Default `false`.
+     */
     rollingImpulse(body?: Body | null, freshOnly?: boolean): number;
     /** @internal Throw if not in pre-handler mutable window. */
     private _mutableCheck;
@@ -2843,10 +3977,13 @@ declare class CollisionArbiter extends Arbiter {
 }
 
 /**
- * A fluid arbiter between two shapes with fluid interaction.
+ * An arbiter representing a fluid interaction between a fluid shape and a body.
+ *
+ * Provides access to buoyancy and drag impulses, the overlap area, and the
+ * centre of overlap. Properties marked _mutable in pre-handler_ can only be
+ * set within a {@link PreListener} handler.
  *
- * Provides access to buoyancy/drag impulses, overlap area, and position.
- * Some properties are mutable only in pre-handlers.
+ * Obtain via {@link Arbiter.fluidArbiter} or by casting from a callback arbiter.
  *
  * Fully modernized — uses extracted ZPP_FluidArbiter directly.
  */
@@ -2854,45 +3991,76 @@ declare class FluidArbiter extends Arbiter {
     static __name__: string[];
     static __super__: typeof Arbiter;
     constructor();
-    /** Centre of the overlap region. Mutable in pre-handler only. */
+    /**
+     * Centre of the overlap region between the fluid and the body shape.
+     * _Mutable in pre-handler only._
+     */
     get position(): Vec2;
     set position(value: Vec2);
-    /** Area of the overlap region. Mutable in pre-handler only. */
+    /**
+     * Area of the overlap region in pixels². Used to compute buoyancy force.
+     * Must be strictly positive and finite.
+     * _Mutable in pre-handler only._
+     */
     get overlap(): number;
     set overlap(value: number);
-    /** Buoyancy impulse applied by this fluid arbiter. */
+    /**
+     * Buoyancy impulse applied in the last step as `(fx, fy, torque)`.
+     * @param body - One of the two bodies, or `null` for the combined value.
+     */
     buoyancyImpulse(body?: Body | null): Vec3;
-    /** Drag impulse applied by this fluid arbiter. */
+    /**
+     * Linear and angular drag impulse applied in the last step as `(fx, fy, torque)`.
+     * @param body - One of the two bodies, or `null` for the combined value.
+     */
     dragImpulse(body?: Body | null): Vec3;
     /** Total impulse (buoyancy + drag). */
     totalImpulse(body?: Body | null, _freshOnly?: boolean): Vec3;
 }
 
 /**
- * Return value flags for PreListener handlers.
+ * Return value for {@link PreListener} handlers — controls whether the interaction
+ * is resolved this step and in future steps.
  *
- * - `ACCEPT`      — accept the interaction
- * - `IGNORE`      — ignore the interaction
- * - `ACCEPT_ONCE` — accept once, then revert
- * - `IGNORE_ONCE` — ignore once, then revert
+ * - `ACCEPT`      — resolve the interaction (default if handler returns `null`)
+ * - `IGNORE`      — suppress the interaction permanently until the next `BEGIN`
+ * - `ACCEPT_ONCE` — accept this step only, then revert to the previous flag
+ * - `IGNORE_ONCE` — ignore this step only, then revert to the previous flag
+ *
+ * Use `IGNORE`/`ACCEPT` for stateful decisions (e.g., one-way platforms).
+ * Use `*_ONCE` variants for single-step overrides.
  *
  * Converted from nape-compiled.js lines 2504–2591.
  */
 declare class PreFlag {
     static __name__: string[];
     constructor();
+    /** Accept and resolve the interaction normally. */
     static get ACCEPT(): PreFlag;
+    /** Suppress the interaction permanently until the next `BEGIN` event. */
     static get IGNORE(): PreFlag;
+    /** Accept this step only; revert to the previous flag next step. */
     static get ACCEPT_ONCE(): PreFlag;
+    /** Ignore this step only; revert to the previous flag next step. */
     static get IGNORE_ONCE(): PreFlag;
     toString(): string;
 }
 
 /**
- * Represents an interaction arbiter between two shapes.
+ * Represents an active interaction between two shapes.
+ *
+ * Arbiters are created and pooled internally by the engine — they cannot be
+ * instantiated directly. Access them via:
+ * - `space.arbiters` — all active arbiters in the simulation
+ * - `body.arbiters` — arbiters involving a specific body
+ * - `InteractionCallback.arbiters` — arbiters in an interaction callback
+ * - `PreCallback.arbiter` — the arbiter in a pre-handler
  *
- * Arbiters are pooled internally by the engine — they cannot be created directly.
- * Access arbiters via `Space.arbiters`, `Body.arbiters`, or callback handlers.
+ * Use {@link Arbiter.collisionArbiter} or {@link Arbiter.fluidArbiter} to cast
+ * to a subtype for type-specific properties.
+ *
+ * **Warning:** do not hold references to `Arbiter` objects after the current
+ * simulation step — they are pooled and may be reused.
  *
  * Fully modernized — uses extracted ZPP_Arbiter directly.
  */
@@ -2903,9 +4071,15 @@ declare class Arbiter {
     /** @internal Backward-compat: compiled code accesses `obj.zpp_inner`. */
     get _inner(): NapeInner;
     constructor();
-    /** Whether this arbiter is currently sleeping. */
+    /**
+     * Whether both interacting bodies are currently sleeping.
+     * Throws if the arbiter is not active.
+     */
     get isSleeping(): boolean;
-    /** The type of this arbiter (COLLISION, SENSOR, or FLUID). */
+    /**
+     * The interaction type of this arbiter.
+     * @see {@link ArbiterType}
+     */
     get type(): ArbiterType;
     /** Cast to CollisionArbiter if this is a collision, else null. */
     get collisionArbiter(): CollisionArbiter | null;
@@ -2928,8 +4102,15 @@ declare class Arbiter {
     /** Whether this is a sensor arbiter. */
     isSensorArbiter(): boolean;
     /**
-     * Total impulse of this arbiter. Base implementation returns Vec3(0,0,0).
-     * Overridden by CollisionArbiter and FluidArbiter.
+     * Total impulse applied by this arbiter in the last step as `(fx, fy, torque)`.
+     *
+     * Pass a `body` to get the impulse applied specifically to that body.
+     * Pass `freshOnly = true` to include only new contact points (not persistent ones).
+     *
+     * Overridden by {@link CollisionArbiter} and {@link FluidArbiter}.
+     *
+     * @param body - One of the two interacting bodies, or `null` for the combined impulse.
+     * @param freshOnly - When `true`, only count fresh (new) contacts. Default `false`.
      */
     totalImpulse(body?: Body | null, _freshOnly?: boolean): Vec3;
     toString(): string;
@@ -3133,27 +4314,43 @@ declare class Contact {
 }
 
 /**
- * Callback event types.
+ * Enumeration of physics callback event types.
  *
- * - `BEGIN`   — interaction just started
- * - `ONGOING` — interaction continues
- * - `END`     — interaction just ended
- * - `WAKE`    — body/constraint woke up
- * - `SLEEP`   — body/constraint went to sleep
- * - `BREAK`   — constraint was broken
- * - `PRE`     — pre-interaction callback
+ * Use these singletons to specify which phase of an interaction a listener
+ * should respond to:
+ *
+ * - `BEGIN`   — fired once when two interactors first make contact
+ * - `ONGOING` — fired every simulation step while the interaction persists
+ * - `END`     — fired once when two interactors separate
+ * - `WAKE`    — fired when a body or constraint wakes from sleep
+ * - `SLEEP`   — fired when a body or constraint falls asleep
+ * - `BREAK`   — fired when a constraint exceeds its `maxForce`/`maxError` and breaks
+ * - `PRE`     — fired before collision resolution; allows per-step accept/ignore decisions
+ *
+ * Valid events per listener type:
+ * - {@link BodyListener}: `WAKE`, `SLEEP`
+ * - {@link ConstraintListener}: `WAKE`, `SLEEP`, `BREAK`
+ * - {@link InteractionListener}: `BEGIN`, `ONGOING`, `END`
+ * - {@link PreListener}: always `PRE` (set internally)
  *
  * Converted from nape-compiled.js lines 516–657.
  */
 declare class CbEvent {
     static __name__: string[];
     constructor();
+    /** Interaction-start event. Fired once when two interactors first make contact. */
     static get BEGIN(): CbEvent;
+    /** Interaction-continue event. Fired every step while the interaction persists. */
     static get ONGOING(): CbEvent;
+    /** Interaction-end event. Fired once when two interactors separate. */
     static get END(): CbEvent;
+    /** Wake event. Fired when a body or constraint wakes from sleep. */
     static get WAKE(): CbEvent;
+    /** Sleep event. Fired when a body or constraint falls asleep. */
     static get SLEEP(): CbEvent;
+    /** Break event. Fired when a constraint exceeds its `maxForce` or `maxError` limit. */
     static get BREAK(): CbEvent;
+    /** Pre-interaction event. Fired before collision resolution; handler can accept or ignore. */
     static get PRE(): CbEvent;
     toString(): string;
 }
@@ -3446,7 +4643,18 @@ declare class ZPP_CbType {
 }
 
 /**
- * Composite callback option type — allows including and excluding CbTypes.
+ * Composite callback option type — combines include and exclude {@link CbType} lists
+ * to express complex listener filter conditions.
+ *
+ * An interaction satisfies an `OptionType` when the interactor has **at least one**
+ * of the included types and **none** of the excluded types.
+ *
+ * @example
+ * ```ts
+ * // Listen only for bodies that are "enemy" but not "boss"
+ * const filter = new OptionType(enemyType).excluding(bossType);
+ * const listener = new BodyListener(CbEvent.WAKE, filter, (cb) => { ... });
+ * ```
  *
  * Converted from nape-compiled.js lines 2647–2698.
  */
@@ -3454,18 +4662,55 @@ declare class OptionType {
     static __name__: string[];
     zpp_inner: ZPP_OptionType;
     get _inner(): NapeInner;
+    /**
+     * Creates an `OptionType` optionally seeded with initial include/exclude entries.
+     *
+     * @param includes - Initial type(s) to include.
+     * @param excludes - Initial type(s) to exclude.
+     */
     constructor(includes?: CbType | OptionType, excludes?: CbType | OptionType);
+    /** Live list of `CbType`s that an interactor must have at least one of. */
     get includes(): object;
+    /** Live list of `CbType`s that an interactor must have none of. */
     get excludes(): object;
+    /**
+     * Adds `includes` to the include list and returns `this` for chaining.
+     *
+     * @param includes - `CbType` or `OptionType` whose types should be added to includes.
+     */
     including(includes: CbType | OptionType): this;
+    /**
+     * Adds `excludes` to the exclude list and returns `this` for chaining.
+     *
+     * @param excludes - `CbType` or `OptionType` whose types should be added to excludes.
+     */
     excluding(excludes: CbType | OptionType): this;
     toString(): string;
     static _wrap(inner: any): OptionType;
 }
 
 /**
- * Callback type — used to tag interactors so that listeners
- * can filter which interactions they respond to.
+ * Callback type tag — used to label bodies, shapes, and constraints so that
+ * listeners can selectively respond to interactions involving specific objects.
+ *
+ * Objects can carry multiple `CbType`s (via their `cbTypes` list). Listeners
+ * match against those types using {@link OptionType} include/exclude filters,
+ * or using the built-in singletons (`ANY_BODY`, `ANY_SHAPE`, etc.).
+ *
+ * @example
+ * ```ts
+ * const playerType = new CbType();
+ * body.cbTypes.add(playerType);
+ *
+ * const listener = new InteractionListener(
+ *   CbEvent.BEGIN,
+ *   InteractionType.COLLISION,
+ *   playerType,
+ *   null,
+ *   (cb) => { console.log('player hit something'); },
+ * );
+ * space.listeners.add(listener);
+ * ```
  *
  * Converted from nape-compiled.js lines 689–770.
  */
@@ -3474,15 +4719,62 @@ declare class CbType {
     zpp_inner: ZPP_CbType;
     get _inner(): NapeInner;
     constructor();
+    /**
+     * Built-in type automatically assigned to every {@link Body}.
+     * Use in listeners to respond to all bodies without a custom `CbType`.
+     */
     static get ANY_BODY(): CbType;
+    /**
+     * Built-in type automatically assigned to every {@link Constraint}.
+     *
+     * **Note:** Constraints do NOT automatically carry `ANY_CONSTRAINT` in their
+     * `cbTypes` list — you must add a custom CbType manually if you want to filter
+     * constraint events.
+     */
     static get ANY_CONSTRAINT(): CbType;
+    /**
+     * Built-in type automatically assigned to every {@link Shape}.
+     * Use in listeners to respond to all shapes without a custom `CbType`.
+     */
     static get ANY_SHAPE(): CbType;
+    /**
+     * Built-in type automatically assigned to every {@link Compound}.
+     * Use in listeners to respond to all compounds without a custom `CbType`.
+     */
     static get ANY_COMPOUND(): CbType;
+    /** Unique numeric identifier for this `CbType` instance. */
     get id(): number;
+    /**
+     * Arbitrary user data attached to this `CbType`.
+     *
+     * Lazily initialized to `{}` on first access. Use to store application-level
+     * metadata associated with the type.
+     */
     get userData(): Record<string, unknown>;
+    /**
+     * Live list of all interactors (bodies/shapes/compounds) currently tagged
+     * with this `CbType`. Read-only.
+     */
     get interactors(): object;
+    /**
+     * Live list of all constraints currently tagged with this `CbType`. Read-only.
+     */
     get constraints(): object;
+    /**
+     * Creates a new {@link OptionType} that includes this type and also `includes`.
+     *
+     * Shorthand for `new OptionType(this).including(includes)`.
+     *
+     * @param includes - Additional `CbType` or `OptionType` to require.
+     */
     including(includes: CbType | OptionType): OptionType;
+    /**
+     * Creates a new {@link OptionType} that includes this type but excludes `excludes`.
+     *
+     * Shorthand for `new OptionType(this).excluding(excludes)`.
+     *
+     * @param excludes - `CbType` or `OptionType` to reject.
+     */
     excluding(excludes: CbType | OptionType): OptionType;
     toString(): string;
     static _wrap(inner: any): CbType;
@@ -3517,27 +4809,68 @@ declare class ListenerType {
  * Fully modernized from nape-compiled.js lines 231–433.
  */
 
+/**
+ * Base class for all physics event listeners.
+ *
+ * Cannot be instantiated directly — use one of the concrete subclasses:
+ * {@link BodyListener}, {@link ConstraintListener}, {@link InteractionListener},
+ * or {@link PreListener}.
+ *
+ * Provides common properties (`type`, `event`, `precedence`, `space`) shared
+ * by all listener types.
+ *
+ * Fully modernized from nape-compiled.js lines 231–433.
+ */
 declare class Listener {
     static __name__: string[];
     zpp_inner: ZPP_Listener;
     get _inner(): this;
     constructor();
     static _wrap(inner: ZPP_Listener | Listener | null | undefined): Listener;
+    /** The type of this listener (BODY, CONSTRAINT, INTERACTION, or PRE). */
     get type(): ListenerType;
+    /**
+     * The event this listener responds to.
+     *
+     * Valid values depend on the concrete listener type — see {@link CbEvent}.
+     * Changing this while the listener is assigned to a space re-registers it.
+     */
     get event(): CbEvent;
     set event(event: CbEvent);
+    /**
+     * Execution priority of this listener relative to other listeners for the
+     * same event. Higher values execute first.
+     *
+     * @defaultValue `0`
+     */
     get precedence(): number;
     set precedence(precedence: number);
+    /**
+     * The space this listener is currently registered in, or `null` if not registered.
+     *
+     * Assign to register/unregister the listener in a space:
+     * ```ts
+     * listener.space = mySpace;  // register
+     * listener.space = null;     // unregister
+     * ```
+     */
     get space(): Space | null;
     set space(space: Space | null);
     toString(): string;
 }
 
 /**
- * Base class for all physics engine callbacks.
+ * Base class for all physics engine callback objects.
  *
- * Cannot be instantiated directly — instances are created internally by the engine
- * and passed to listener handlers.
+ * Callback instances are created internally by the engine and passed to listener
+ * handler functions. They must not be stored beyond the scope of the handler —
+ * they are pooled and reused after the handler returns.
+ *
+ * Concrete subclasses:
+ * - {@link BodyCallback} — passed to {@link BodyListener} handlers
+ * - {@link ConstraintCallback} — passed to {@link ConstraintListener} handlers
+ * - {@link InteractionCallback} — passed to {@link InteractionListener} handlers
+ * - {@link PreCallback} — passed to {@link PreListener} handlers
  *
  * Converted from nape-compiled.js lines 212–238.
  */
@@ -3545,20 +4878,24 @@ declare class Callback {
     static __name__: string[];
     zpp_inner: ZPP_Callback | null;
     constructor();
+    /** The event type that caused this callback to fire (e.g., `CbEvent.BEGIN`). */
     get event(): CbEvent;
+    /** The listener that this callback was fired from. */
     get listener(): Listener;
     toString(): string;
 }
 
 /**
- * Callback for body events (WAKE/SLEEP).
+ * Callback object passed to {@link BodyListener} handlers.
  *
- * Cannot be instantiated directly — instances are created internally by the engine.
+ * Provides the body that triggered the event. Do not store this object beyond
+ * the handler scope — it is pooled and reused.
  *
  * Converted from nape-compiled.js lines 239–261.
  */
 declare class BodyCallback extends Callback {
     static __name__: string[];
+    /** The body that woke or fell asleep. */
     get body(): Body;
     toString(): string;
 }
@@ -3569,27 +4906,67 @@ declare class BodyCallback extends Callback {
  * Fully modernized from nape-compiled.js lines 434–515.
  */
 
+/**
+ * Listener for body lifecycle events.
+ *
+ * Fires when a body matching the `options` filter wakes or sleeps.
+ *
+ * Valid events: {@link CbEvent.WAKE}, {@link CbEvent.SLEEP}.
+ *
+ * @example
+ * ```ts
+ * const listener = new BodyListener(
+ *   CbEvent.WAKE,
+ *   CbType.ANY_BODY,
+ *   (cb) => { console.log(cb.body, 'woke up'); },
+ * );
+ * space.listeners.add(listener);
+ * ```
+ *
+ * Fully modernized from nape-compiled.js lines 434–515.
+ */
 declare class BodyListener extends Listener {
     static __name__: string[];
     zpp_inner_zn: ZPP_BodyListener;
+    /**
+     * @param event - Must be `CbEvent.WAKE` or `CbEvent.SLEEP`.
+     * @param options - `CbType` or `OptionType` filter, or `null` to match all bodies.
+     * @param handler - Called with a {@link BodyCallback} each time the event fires.
+     * @param precedence - Execution order relative to other listeners (higher = first). Default `0`.
+     */
     constructor(event: CbEvent, options: OptionType | CbType | null, handler: (cb: BodyCallback) => void, precedence?: number);
+    /**
+     * The filter used to match bodies. Returns an {@link OptionType} representing
+     * the current include/exclude configuration.
+     */
     get options(): OptionType;
     set options(options: OptionType | CbType);
+    /** The callback function invoked when the event fires. Cannot be set to null. */
     get handler(): (cb: BodyCallback) => void;
     set handler(handler: (cb: BodyCallback) => void);
 }
 
 /**
- * Callback for interaction events (BEGIN/END/ONGOING).
+ * Callback object passed to {@link InteractionListener} handlers.
  *
- * Cannot be instantiated directly — instances are created internally by the engine.
+ * Provides both interactors and the list of active arbiters between them.
+ * Do not store this object beyond the handler scope — it is pooled and reused.
  *
  * Converted from nape-compiled.js lines 1398–1445.
  */
 declare class InteractionCallback extends Callback {
     static __name__: string[];
+    /** The first interactor involved in the interaction. */
     get int1(): Interactor;
+    /** The second interactor involved in the interaction. */
     get int2(): Interactor;
+    /**
+     * The list of arbiters currently active between `int1` and `int2`.
+     *
+     * For `ONGOING` callbacks, arbiters are valid for the entire step.
+     * For `BEGIN`/`END` callbacks, the list reflects the state at the moment
+     * the event fired.
+     */
     get arbiters(): object;
     toString(): string;
 }
@@ -3600,31 +4977,75 @@ declare class InteractionCallback extends Callback {
  * Fully modernized from nape-compiled.js lines 659–1091.
  */
 
+/**
+ * Listener for interaction events between two interactors.
+ *
+ * Fires when two objects matching `options1` and `options2` start, continue, or
+ * stop interacting with each other according to `interactionType`.
+ *
+ * Valid events: {@link CbEvent.BEGIN}, {@link CbEvent.ONGOING}, {@link CbEvent.END}.
+ *
+ * - `BEGIN` fires once when the interaction starts.
+ * - `ONGOING` fires every simulation step while the interaction persists.
+ * - `END` fires once when the interaction ends.
+ *
+ * @example
+ * ```ts
+ * const listener = new InteractionListener(
+ *   CbEvent.BEGIN,
+ *   InteractionType.COLLISION,
+ *   playerType,
+ *   groundType,
+ *   (cb) => { console.log('player landed'); },
+ * );
+ * space.listeners.add(listener);
+ * ```
+ *
+ * Fully modernized from nape-compiled.js lines 659–1091.
+ */
 declare class InteractionListener extends Listener {
     static __name__: string[];
     zpp_inner_zn: ZPP_InteractionListener;
+    /**
+     * @param event - Must be `CbEvent.BEGIN`, `CbEvent.ONGOING`, or `CbEvent.END`.
+     * @param interactionType - The kind of interaction to listen for (COLLISION, SENSOR, FLUID, or ANY).
+     * @param options1 - Filter for the first interactor, or `null` to match any.
+     * @param options2 - Filter for the second interactor, or `null` to match any.
+     * @param handler - Called with an {@link InteractionCallback} each time the event fires.
+     * @param precedence - Execution order relative to other listeners (higher = first). Default `0`.
+     */
     constructor(event: CbEvent, interactionType: InteractionType, options1: OptionType | CbType | null, options2: OptionType | CbType | null, handler: (cb: InteractionCallback) => void, precedence?: number);
+    /** Filter for the first interactor. Order between `options1`/`options2` does not matter. */
     get options1(): OptionType;
     set options1(options1: OptionType | CbType);
+    /** Filter for the second interactor. Order between `options1`/`options2` does not matter. */
     get options2(): OptionType;
     set options2(options2: OptionType | CbType);
+    /** The callback function invoked when the event fires. Cannot be set to null. */
     get handler(): (cb: InteractionCallback) => void;
     set handler(handler: (cb: InteractionCallback) => void);
+    /** The type of interaction this listener responds to (COLLISION, SENSOR, FLUID, or ANY). */
     get interactionType(): InteractionType | null;
     set interactionType(interactionType: InteractionType | null);
+    /**
+     * When `true`, `ONGOING` callbacks are also fired while both interactors are sleeping.
+     * Default is `false` (callbacks are suppressed when both are asleep).
+     */
     get allowSleepingCallbacks(): boolean;
     set allowSleepingCallbacks(value: boolean);
 }
 
 /**
- * Callback for constraint events (WAKE/SLEEP/BREAK).
+ * Callback object passed to {@link ConstraintListener} handlers.
  *
- * Cannot be instantiated directly — instances are created internally by the engine.
+ * Provides the constraint that triggered the event. Do not store this object
+ * beyond the handler scope — it is pooled and reused.
  *
  * Converted from nape-compiled.js lines 1262–1292.
  */
 declare class ConstraintCallback extends Callback {
     static __name__: string[];
+    /** The constraint that woke, fell asleep, or broke. */
     get constraint(): Constraint;
     toString(): string;
 }
@@ -3635,28 +5056,72 @@ declare class ConstraintCallback extends Callback {
  * Fully modernized from nape-compiled.js lines 546–649.
  */
 
+/**
+ * Listener for constraint lifecycle events.
+ *
+ * Fires when a constraint matching the `options` filter wakes, sleeps, or breaks.
+ *
+ * Valid events: {@link CbEvent.WAKE}, {@link CbEvent.SLEEP}, {@link CbEvent.BREAK}.
+ *
+ * A `BREAK` event fires when the constraint exceeds its `maxForce` or `maxError` limit.
+ * If `removeOnBreak` is `true` on the constraint it is also removed from the space.
+ *
+ * @example
+ * ```ts
+ * const listener = new ConstraintListener(
+ *   CbEvent.BREAK,
+ *   myConstraintType,
+ *   (cb) => { console.log(cb.constraint, 'broke!'); },
+ * );
+ * space.listeners.add(listener);
+ * ```
+ *
+ * Fully modernized from nape-compiled.js lines 546–649.
+ */
 declare class ConstraintListener extends Listener {
     static __name__: string[];
     zpp_inner_zn: ZPP_ConstraintListener;
+    /**
+     * @param event - Must be `CbEvent.WAKE`, `CbEvent.SLEEP`, or `CbEvent.BREAK`.
+     * @param options - `CbType` or `OptionType` filter, or `null` to match all constraints.
+     * @param handler - Called with a {@link ConstraintCallback} each time the event fires.
+     * @param precedence - Execution order relative to other listeners (higher = first). Default `0`.
+     */
     constructor(event: CbEvent, options: OptionType | CbType | null, handler: (cb: ConstraintCallback) => void, precedence?: number);
+    /**
+     * The filter used to match constraints. Returns an {@link OptionType} representing
+     * the current include/exclude configuration.
+     */
     get options(): OptionType;
     set options(options: OptionType | CbType);
+    /** The callback function invoked when the event fires. Cannot be set to null. */
     get handler(): (cb: ConstraintCallback) => void;
     set handler(handler: (cb: ConstraintCallback) => void);
 }
 
 /**
- * Callback for pre-interaction events.
+ * Callback object passed to {@link PreListener} handlers.
+ *
+ * Provides both interactors, the arbiter, and a `swapped` flag indicating
+ * whether the pair order was swapped relative to the listener's `options1`/`options2`.
  *
- * Cannot be instantiated directly — instances are created internally by the engine.
+ * The handler should return a {@link PreFlag} to control the interaction.
+ * Do not store this object beyond the handler scope — it is pooled and reused.
  *
  * Converted from nape-compiled.js lines 2590–2634.
  */
 declare class PreCallback extends Callback {
     static __name__: string[];
+    /** The arbiter representing the potential interaction. Use to inspect collision normal, etc. */
     get arbiter(): Arbiter;
+    /** The first interactor in the pair (matches `options1` unless `swapped` is `true`). */
     get int1(): Interactor;
+    /** The second interactor in the pair (matches `options2` unless `swapped` is `true`). */
     get int2(): Interactor;
+    /**
+     * `true` when the pair order is swapped relative to the listener's `options1`/`options2`.
+     * Check this if you need to know which interactor matched which filter.
+     */
     get swapped(): boolean;
     toString(): string;
 }
@@ -3669,18 +5134,74 @@ declare class PreCallback extends Callback {
  * Fully modernized from nape-compiled.js lines 1142–1338.
  */
 
+/**
+ * Pre-interaction listener — called before collision resolution each step.
+ *
+ * The handler receives a {@link PreCallback} and returns a {@link PreFlag} that
+ * determines whether and how the interaction should be processed:
+ * - `PreFlag.ACCEPT` — resolve the interaction normally (default).
+ * - `PreFlag.IGNORE` — suppress the interaction permanently (until next `BEGIN`).
+ * - `PreFlag.ACCEPT_ONCE` — accept this step, then revert to default.
+ * - `PreFlag.IGNORE_ONCE` — ignore this step only.
+ *
+ * Returning `null` is equivalent to `ACCEPT`.
+ *
+ * The event is always {@link CbEvent.PRE} and cannot be changed.
+ *
+ * **Pure mode**: when `pure` is `true` the engine caches the handler result and
+ * does not re-invoke it until the result is reset. This is an optimisation — only
+ * use `pure` when the handler will always return the same flag for a given pair.
+ *
+ * @example
+ * ```ts
+ * const preListener = new PreListener(
+ *   InteractionType.COLLISION,
+ *   playerType,
+ *   onewayPlatformType,
+ *   (cb) => cb.arbiter.collisionArbiter!.normal.y > 0
+ *     ? PreFlag.ACCEPT
+ *     : PreFlag.IGNORE,
+ * );
+ * space.listeners.add(preListener);
+ * ```
+ *
+ * Fully modernized from nape-compiled.js lines 1142–1338.
+ */
 declare class PreListener extends Listener {
     static __name__: string[];
     zpp_inner_zn: ZPP_InteractionListener;
+    /**
+     * @param interactionType - The kind of interaction to intercept (COLLISION, SENSOR, FLUID, or ANY).
+     * @param options1 - Filter for the first interactor, or `null` to match any.
+     * @param options2 - Filter for the second interactor, or `null` to match any.
+     * @param handler - Called each step; return a {@link PreFlag} to control the interaction.
+     * @param precedence - Execution order relative to other listeners (higher = first). Default `0`.
+     * @param pure - Enable caching of the handler result. Default `false`.
+     */
     constructor(interactionType: InteractionType, options1: OptionType | CbType | null, options2: OptionType | CbType | null, handler: (cb: PreCallback) => PreFlag | null, precedence?: number, pure?: boolean);
+    /** Filter for the first interactor. Order does not matter. */
     get options1(): OptionType;
     set options1(options1: OptionType | CbType);
+    /** Filter for the second interactor. Order does not matter. */
     get options2(): OptionType;
     set options2(options2: OptionType | CbType);
+    /**
+     * The handler called before each collision resolution step.
+     * Return a {@link PreFlag} to accept/ignore the interaction, or `null` to accept.
+     */
     get handler(): (cb: PreCallback) => PreFlag | null;
     set handler(handler: (cb: PreCallback) => PreFlag | null);
+    /**
+     * When `true`, the engine caches the handler return value and does not
+     * re-invoke the handler until the cached result is invalidated.
+     *
+     * Only use `pure` mode when the handler always returns the same flag for a
+     * given pair of interactors. Setting `pure` to `false` immediately invalidates
+     * any cached result.
+     */
     get pure(): boolean;
     set pure(pure: boolean);
+    /** The type of interaction this pre-listener intercepts (COLLISION, SENSOR, FLUID, or ANY). */
     get interactionType(): InteractionType | null;
     set interactionType(interactionType: InteractionType | null);
 }
@@ -3747,25 +5268,53 @@ declare class ZPP_PivotJoint extends ZPP_Constraint {
 }
 
 /**
- * A pivot (pin) joint that constrains two bodies to share an anchor point.
+ * A pivot (pin) joint that constrains two anchor points — one on each body — to
+ * remain coincident in world space.
+ *
+ * This is the most common joint type and is used to simulate hinges, pins, and
+ * revolute connections between bodies.
+ *
+ * The constraint eliminates 2 translational degrees of freedom but leaves
+ * rotation free.
+ *
+ * @example
+ * ```ts
+ * // Pin body2 to body1's local origin
+ * const joint = new PivotJoint(
+ *   body1, body2,
+ *   Vec2.weak(0, 0),  // anchor on body1 (local)
+ *   Vec2.weak(0, 0),  // anchor on body2 (local)
+ * );
+ * joint.space = space;
+ * ```
  *
  * Fully modernized — uses ZPP_PivotJoint directly (extracted to TypeScript).
  */
 declare class PivotJoint extends Constraint {
     zpp_inner: ZPP_PivotJoint;
+    /**
+     * @param body1 - First body, or `null` for a static world anchor.
+     * @param body2 - Second body, or `null` for a static world anchor.
+     * @param anchor1 - Anchor point in `body1`'s local space (disposed if weak).
+     * @param anchor2 - Anchor point in `body2`'s local space (disposed if weak).
+     */
     constructor(body1: Body | null, body2: Body | null, anchor1: Vec2, anchor2: Vec2);
     /** @internal */
     static _wrap(inner: any): PivotJoint;
+    /** First body. `null` treats the anchor as a static world point. */
     get body1(): Body;
     set body1(value: Body | null);
     /** @internal */
     private _setBody1;
+    /** Second body. `null` treats the anchor as a static world point. */
     get body2(): Body;
     set body2(value: Body | null);
     /** @internal */
     private _setBody2;
+    /** Anchor point on `body1` in local coordinates. */
     get anchor1(): Vec2;
     set anchor1(value: Vec2);
+    /** Anchor point on `body2` in local coordinates. */
     get anchor2(): Vec2;
     set anchor2(value: Vec2);
     impulse(): MatMN;
@@ -3851,31 +5400,70 @@ declare class ZPP_DistanceJoint extends ZPP_Constraint {
 }
 
 /**
- * Constrains the distance between two anchor points on two bodies.
+ * Constrains the distance between two anchor points (one on each body) within a range.
+ *
+ * Enforces: `jointMin ≤ distance(anchor1, anchor2) ≤ jointMax`
+ *
+ * When `jointMin === jointMax` the distance is fixed (like a rigid rod).
+ * When `jointMin < jointMax` the joint acts as a slack rope / elastic band.
+ *
+ * Anchors are specified in each body's local coordinate space.
+ *
+ * @example
+ * ```ts
+ * // Attach two bodies with a fixed-length rod
+ * const joint = new DistanceJoint(
+ *   body1, body2,
+ *   Vec2.weak(0, 0),   // anchor on body1 (local)
+ *   Vec2.weak(0, 0),   // anchor on body2 (local)
+ *   50, 50,            // fixed distance
+ * );
+ * joint.space = space;
+ * ```
  *
  * Fully modernized — uses ZPP_DistanceJoint directly (extracted to TypeScript).
  */
 declare class DistanceJoint extends Constraint {
     zpp_inner: ZPP_DistanceJoint;
+    /**
+     * @param body1 - First body, or `null` for a static world anchor.
+     * @param body2 - Second body, or `null` for a static world anchor.
+     * @param anchor1 - Anchor point in `body1`'s local space (disposed if weak).
+     * @param anchor2 - Anchor point in `body2`'s local space (disposed if weak).
+     * @param jointMin - Minimum allowed distance (must be `>= 0`).
+     * @param jointMax - Maximum allowed distance (must be `>= jointMin`).
+     */
     constructor(body1: Body | null, body2: Body | null, anchor1: Vec2, anchor2: Vec2, jointMin: number, jointMax: number);
     /** @internal */
     static _wrap(inner: any): DistanceJoint;
+    /** First body. `null` treats the anchor as a static world point. */
     get body1(): Body;
     set body1(value: Body | null);
     /** @internal */
     private _setBody1;
+    /** Second body. `null` treats the anchor as a static world point. */
     get body2(): Body;
     set body2(value: Body | null);
     /** @internal */
     private _setBody2;
+    /** Anchor point on `body1` in local coordinates. Modifying this wakes the constraint. */
     get anchor1(): Vec2;
     set anchor1(value: Vec2);
+    /** Anchor point on `body2` in local coordinates. Modifying this wakes the constraint. */
     get anchor2(): Vec2;
     set anchor2(value: Vec2);
+    /** Minimum allowed distance between anchors (pixels, must be `>= 0`). */
     get jointMin(): number;
     set jointMin(value: number);
+    /** Maximum allowed distance between anchors (pixels, must be `>= jointMin`). */
     get jointMax(): number;
     set jointMax(value: number);
+    /**
+     * Returns `true` when the current distance is within `[jointMin, jointMax]`
+     * and no corrective impulse was applied last step.
+     *
+     * @throws if either body is `null`.
+     */
     isSlack(): boolean;
     impulse(): MatMN;
     bodyImpulse(body: Body): Vec3;
@@ -3940,29 +5528,69 @@ declare class ZPP_AngleJoint extends ZPP_Constraint {
 }
 
 /**
- * Constrains the relative angle between two bodies.
+ * Constrains the relative angle between two bodies within a range.
+ *
+ * The constraint enforces:
+ * `jointMin ≤ body2.rotation - ratio * body1.rotation ≤ jointMax`
+ *
+ * When `jointMin === jointMax` the relative angle is fixed exactly.
+ * When `jointMin < jointMax` the joint acts as a rotational limit.
+ *
+ * @example
+ * ```ts
+ * // Limit the angle between two bodies to ±45 degrees
+ * const joint = new AngleJoint(
+ *   body1, body2,
+ *   -Math.PI / 4,  // jointMin
+ *   Math.PI / 4,   // jointMax
+ * );
+ * joint.space = space;
+ * ```
  *
  * Fully modernized — uses ZPP_AngleJoint directly (extracted to TypeScript).
  */
 declare class AngleJoint extends Constraint {
     zpp_inner: ZPP_AngleJoint;
+    /**
+     * @param body1 - First body, or `null` for a static anchor.
+     * @param body2 - Second body, or `null` for a static anchor.
+     * @param jointMin - Minimum allowed relative angle (radians).
+     * @param jointMax - Maximum allowed relative angle (radians).
+     * @param ratio - Gear ratio applied to `body1`'s rotation. Default `1.0`.
+     */
     constructor(body1: Body | null, body2: Body | null, jointMin: number, jointMax: number, ratio?: number);
     /** @internal */
     static _wrap(inner: any): AngleJoint;
+    /** First body in the constraint. Setting `null` treats it as a static world-anchored reference. */
     get body1(): Body;
     set body1(value: Body | null);
     /** @internal */
     private _setBody1;
+    /** Second body in the constraint. Setting `null` treats it as a static world-anchored reference. */
     get body2(): Body;
     set body2(value: Body | null);
     /** @internal */
     private _setBody2;
+    /** Minimum allowed relative angle in radians (`jointMin ≤ jointMax`). */
     get jointMin(): number;
     set jointMin(value: number);
+    /** Maximum allowed relative angle in radians (`jointMin ≤ jointMax`). */
     get jointMax(): number;
     set jointMax(value: number);
+    /**
+     * Gear ratio applied to `body1`'s rotation.
+     *
+     * The constraint enforces `jointMin ≤ body2.rotation - ratio * body1.rotation ≤ jointMax`.
+     * @defaultValue `1.0`
+     */
     get ratio(): number;
     set ratio(value: number);
+    /**
+     * Returns `true` when the current relative angle is within `[jointMin, jointMax]`
+     * and no corrective impulse was applied last step.
+     *
+     * @throws if either body is `null`.
+     */
     isSlack(): boolean;
     impulse(): MatMN;
     bodyImpulse(body: Body): Vec3;
@@ -4040,28 +5668,59 @@ declare class ZPP_WeldJoint extends ZPP_Constraint {
 }
 
 /**
- * Weld joint — constrains two bodies to maintain a fixed relative
- * position and angle (like gluing them together).
+ * Weld joint — constrains two bodies to maintain a fixed relative position and
+ * relative angle, effectively gluing them together while still treating them as
+ * separate physics objects.
+ *
+ * The `phase` parameter sets the desired relative angle offset in radians.
+ * When `phase = 0` both bodies maintain the angle difference they had at the
+ * time the joint was created.
+ *
+ * @example
+ * ```ts
+ * const joint = new WeldJoint(
+ *   body1, body2,
+ *   Vec2.weak(10, 0),  // attach point on body1
+ *   Vec2.weak(-10, 0), // attach point on body2
+ * );
+ * joint.space = space;
+ * ```
  *
  * Fully modernized — uses ZPP_WeldJoint directly (extracted to TypeScript).
  */
 declare class WeldJoint extends Constraint {
     zpp_inner: ZPP_WeldJoint;
+    /**
+     * @param body1 - First body, or `null` for a static world anchor.
+     * @param body2 - Second body, or `null` for a static world anchor.
+     * @param anchor1 - Anchor point in `body1`'s local space (disposed if weak).
+     * @param anchor2 - Anchor point in `body2`'s local space (disposed if weak).
+     * @param phase - Target relative angle offset in radians. Default `0.0`.
+     */
     constructor(body1: Body | null, body2: Body | null, anchor1: Vec2, anchor2: Vec2, phase?: number);
     /** @internal */
     static _wrap(inner: any): WeldJoint;
+    /** First body. `null` treats the anchor as a static world point. */
     get body1(): Body;
     set body1(value: Body | null);
     /** @internal */
     private _setBody1;
+    /** Second body. `null` treats the anchor as a static world point. */
     get body2(): Body;
     set body2(value: Body | null);
     /** @internal */
     private _setBody2;
+    /** Anchor point on `body1` in local coordinates. */
     get anchor1(): Vec2;
     set anchor1(value: Vec2);
+    /** Anchor point on `body2` in local coordinates. */
     get anchor2(): Vec2;
     set anchor2(value: Vec2);
+    /**
+     * Target relative angle offset in radians.
+     * `0` means both bodies maintain their original angle difference.
+     * @defaultValue `0.0`
+     */
     get phase(): number;
     set phase(value: number);
     impulse(): MatMN;
@@ -4111,25 +5770,60 @@ declare class ZPP_MotorJoint extends ZPP_Constraint {
 }
 
 /**
- * Motor joint — applies angular velocity to rotate bodies relative to each other.
+ * Motor joint — drives the relative angular velocity between two bodies toward
+ * a target `rate`, subject to `maxForce`.
+ *
+ * The motor enforces: `body2.angularVel - ratio * body1.angularVel → rate`
+ *
+ * This is a velocity-level constraint (not positional), so it does not enforce
+ * a particular relative angle — it continuously applies torque to reach `rate`.
+ * Use an {@link AngleJoint} in addition if you also need an angle limit.
+ *
+ * @example
+ * ```ts
+ * // Spin body2 at 2 rad/s relative to body1, limited to 500 N force
+ * const motor = new MotorJoint(body1, body2, 2.0);
+ * motor.maxForce = 500;
+ * motor.space = space;
+ * ```
  *
  * Fully modernized — uses ZPP_MotorJoint directly (extracted to TypeScript).
  */
 declare class MotorJoint extends Constraint {
     zpp_inner: ZPP_MotorJoint;
+    /**
+     * @param body1 - First body, or `null` for a static world reference.
+     * @param body2 - Second body, or `null` for a static world reference.
+     * @param rate - Target relative angular velocity (rad/s). Default `0.0`.
+     * @param ratio - Gear ratio applied to `body1`'s angular velocity. Default `1.0`.
+     */
     constructor(body1: Body | null, body2: Body | null, rate?: number, ratio?: number);
     /** @internal */
     static _wrap(inner: any): MotorJoint;
+    /** First body (its angular velocity is scaled by `ratio`). */
     get body1(): Body;
     set body1(value: Body | null);
     /** @internal */
     private _setBody1;
+    /** Second body (driven toward the target angular velocity). */
     get body2(): Body;
     set body2(value: Body | null);
     /** @internal */
     private _setBody2;
+    /**
+     * Target relative angular velocity in rad/s.
+     *
+     * Positive values rotate `body2` counter-clockwise relative to `body1`.
+     * @defaultValue `0.0`
+     */
     get rate(): number;
     set rate(value: number);
+    /**
+     * Gear ratio applied to `body1`'s angular velocity.
+     *
+     * The motor drives: `body2.angularVel - ratio * body1.angularVel → rate`
+     * @defaultValue `1.0`
+     */
     get ratio(): number;
     set ratio(value: number);
     impulse(): MatMN;
@@ -4226,32 +5920,64 @@ declare class ZPP_LineJoint extends ZPP_Constraint {
 }
 
 /**
- * Line joint — constrains body2's anchor to slide along a line
- * defined by body1's anchor and direction.
+ * Line joint — constrains `body2`'s anchor to slide along a line defined by
+ * `body1`'s anchor and `direction`, within `[jointMin, jointMax]`.
+ *
+ * The direction is specified in `body1`'s local space. The joint allows one
+ * translational degree of freedom (along the line) and removes the other.
+ *
+ * @example
+ * ```ts
+ * // Allow body2 to slide vertically relative to body1
+ * const joint = new LineJoint(
+ *   body1, body2,
+ *   Vec2.weak(0, 0),    // anchor on body1
+ *   Vec2.weak(0, 0),    // anchor on body2
+ *   Vec2.weak(0, 1),    // direction (local to body1)
+ *   -50, 50,            // allowed travel range
+ * );
+ * joint.space = space;
+ * ```
  *
  * Fully modernized — uses ZPP_LineJoint directly (extracted to TypeScript).
  */
 declare class LineJoint extends Constraint {
     zpp_inner: ZPP_LineJoint;
+    /**
+     * @param body1 - First body (defines the line), or `null` for a static world line.
+     * @param body2 - Second body (slides along the line), or `null` for a static anchor.
+     * @param anchor1 - Origin of the line in `body1`'s local space (disposed if weak).
+     * @param anchor2 - Anchor on `body2` in `body2`'s local space (disposed if weak).
+     * @param direction - Direction of the line in `body1`'s local space (disposed if weak).
+     * @param jointMin - Minimum allowed displacement along the line.
+     * @param jointMax - Maximum allowed displacement along the line.
+     */
     constructor(body1: Body | null, body2: Body | null, anchor1: Vec2, anchor2: Vec2, direction: Vec2, jointMin: number, jointMax: number);
     /** @internal */
     static _wrap(inner: any): LineJoint;
+    /** Body that defines the line's origin and direction. */
     get body1(): Body;
     set body1(value: Body | null);
     /** @internal */
     private _setBody1;
+    /** Body whose anchor slides along the line. */
     get body2(): Body;
     set body2(value: Body | null);
     /** @internal */
     private _setBody2;
+    /** Origin of the line on `body1` in local coordinates. */
     get anchor1(): Vec2;
     set anchor1(value: Vec2);
+    /** Anchor point on `body2` in local coordinates. */
     get anchor2(): Vec2;
     set anchor2(value: Vec2);
+    /** Direction of the line in `body1`'s local space. Does not need to be normalised. */
     get direction(): Vec2;
     set direction(value: Vec2);
+    /** Minimum displacement along the line direction. */
     get jointMin(): number;
     set jointMin(value: number);
+    /** Maximum displacement along the line direction. */
     get jointMax(): number;
     set jointMax(value: number);
     impulse(): MatMN;
@@ -4352,24 +6078,58 @@ declare class ZPP_PulleyJoint extends ZPP_Constraint {
 }
 
 /**
- * Pulley joint — constrains the weighted sum of distances between
- * four anchor points on four bodies.
+ * Pulley joint — constrains the weighted sum of two distances to remain within
+ * `[jointMin, jointMax]`:
+ *
+ * `jointMin ≤ distance(anchor1, anchor2) + ratio * distance(anchor3, anchor4) ≤ jointMax`
+ *
+ * This models a rope-and-pulley system where lifting one side lowers the other.
+ * All four anchors are in the local space of their respective bodies.
+ *
+ * @example
+ * ```ts
+ * // Classic pulley: as body2 moves away from anchor1, body4 moves toward anchor3
+ * const joint = new PulleyJoint(
+ *   body1, body2, body3, body4,
+ *   Vec2.weak(0,0), Vec2.weak(0,0),
+ *   Vec2.weak(0,0), Vec2.weak(0,0),
+ *   0, 200, // total rope length
+ * );
+ * joint.space = space;
+ * ```
  *
  * Fully modernized — uses ZPP_PulleyJoint directly (extracted to TypeScript).
  */
 declare class PulleyJoint extends Constraint {
     zpp_inner: ZPP_PulleyJoint;
+    /**
+     * @param body1 - First body (pulley side 1), or `null` for a static anchor.
+     * @param body2 - Second body (pulley side 1), or `null` for a static anchor.
+     * @param body3 - Third body (pulley side 2), or `null` for a static anchor.
+     * @param body4 - Fourth body (pulley side 2), or `null` for a static anchor.
+     * @param anchor1 - Anchor on `body1` in local space (disposed if weak).
+     * @param anchor2 - Anchor on `body2` in local space (disposed if weak).
+     * @param anchor3 - Anchor on `body3` in local space (disposed if weak).
+     * @param anchor4 - Anchor on `body4` in local space (disposed if weak).
+     * @param jointMin - Minimum allowed total rope length (must be `>= 0`).
+     * @param jointMax - Maximum allowed total rope length (must be `>= jointMin`).
+     * @param ratio - Weight of the second distance segment. Default `1.0`.
+     */
     constructor(body1: Body | null, body2: Body | null, body3: Body | null, body4: Body | null, anchor1: Vec2, anchor2: Vec2, anchor3: Vec2, anchor4: Vec2, jointMin: number, jointMax: number, ratio?: number);
     /** @internal Helper to set an anchor during construction. */
     private _setAnchorInit;
     /** @internal */
     static _wrap(inner: any): PulleyJoint;
+    /** First body of the first rope segment. `null` = static world point. */
     get body1(): Body;
     set body1(value: Body | null);
+    /** Second body of the first rope segment. `null` = static world point. */
     get body2(): Body;
     set body2(value: Body | null);
+    /** First body of the second rope segment. `null` = static world point. */
     get body3(): Body;
     set body3(value: Body | null);
+    /** Second body of the second rope segment. `null` = static world point. */
     get body4(): Body;
     set body4(value: Body | null);
     /** @internal */
@@ -4380,20 +6140,38 @@ declare class PulleyJoint extends Constraint {
     private _setBody3;
     /** @internal */
     private _setBody4;
+    /** Anchor on `body1` in local coordinates. */
     get anchor1(): Vec2;
     set anchor1(value: Vec2);
+    /** Anchor on `body2` in local coordinates. */
     get anchor2(): Vec2;
     set anchor2(value: Vec2);
+    /** Anchor on `body3` in local coordinates. */
     get anchor3(): Vec2;
     set anchor3(value: Vec2);
+    /** Anchor on `body4` in local coordinates. */
     get anchor4(): Vec2;
     set anchor4(value: Vec2);
+    /** Minimum allowed total rope length (must be `>= 0`). */
     get jointMin(): number;
     set jointMin(value: number);
+    /** Maximum allowed total rope length (must be `>= jointMin`). */
     get jointMax(): number;
     set jointMax(value: number);
+    /**
+     * Weight of the second rope segment in the total length sum.
+     *
+     * The constraint enforces: `distance(a1,a2) + ratio * distance(a3,a4)` within bounds.
+     * @defaultValue `1.0`
+     */
     get ratio(): number;
     set ratio(value: number);
+    /**
+     * Returns `true` when the total rope length is within bounds and no corrective
+     * impulse was applied last step.
+     *
+     * @throws if any of the four bodies is `null`.
+     */
     isSlack(): boolean;
     impulse(): MatMN;
     bodyImpulse(body: Body): Vec3;