@codexo/exojs-physics 0.15.2 → 0.16.0

package/dist/esm/shapes/SegmentShape.js

@@ -0,0 +1,62 @@
+import { Shape } from "./Shape.js";
+
+//#region src/shapes/SegmentShape.ts
+/** Segments shorter than this (px) have no well-defined orientation. */
+const minimumLength = .001;
+/**
+* A zero-thickness boundary between two local-space endpoints: level edges,
+* one-off walls, the geometry a body may not cross.
+*
+* It has no interior, so {@link Shape.massProperties} is `null` and the shape
+* contributes collision only - a `dynamic` body needs at least one mass-bearing
+* collider alongside it.
+*
+* A segment blocks from **both** sides. There is no inside for it to be outside
+* of, and a one-sided segment would be a gameplay rule in a geometry costume:
+* express that with the world's `contactModifier`, which decides per contact and
+* per step whether it is solved.
+*
+* Being zero-thickness makes it the worst case for discrete detection - a body
+* that crosses it entirely within one fixed step misses it. Continuous collision
+* covers a fast body against a segment; a fast segment is not swept.
+*/
+var SegmentShape = class SegmentShape extends Shape {
+	type = "segment";
+	/** Local endpoints, flattened - the same layout a polygon uses. */
+	vertices;
+	/** The two opposite outward unit normals, flattened. */
+	normals;
+	length;
+	boundingRadius;
+	/** Always `null`: a boundary has no interior and therefore no mass. */
+	massProperties = null;
+	constructor(x0, y0, x1, y1) {
+		super();
+		if (!Number.isFinite(x0) || !Number.isFinite(y0) || !Number.isFinite(x1) || !Number.isFinite(y1)) throw new RangeError(`SegmentShape: endpoints must be finite, received (${x0}, ${y0}) and (${x1}, ${y1}).`);
+		const ex = x1 - x0;
+		const ey = y1 - y0;
+		const length = Math.hypot(ex, ey);
+		if (length < minimumLength) throw new RangeError(`SegmentShape: the endpoints are coincident (length ${length}).`);
+		const nx = ey / length;
+		const ny = -ex / length;
+		this.length = length;
+		this.vertices = Object.freeze([
+			x0,
+			y0,
+			x1,
+			y1
+		]);
+		this.normals = Object.freeze([
+			nx,
+			ny,
+			-nx,
+			-ny
+		]);
+		this.boundingRadius = Math.max(Math.hypot(x0, y0), Math.hypot(x1, y1));
+		if (new.target === SegmentShape) Object.freeze(this);
+	}
+};
+
+//#endregion
+export { SegmentShape };
+//# sourceMappingURL=SegmentShape.js.map

package/dist/esm/shapes/SegmentShape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SegmentShape.js","names":[],"sources":["../../../src/shapes/SegmentShape.ts"],"sourcesContent":["import { Shape } from './Shape';\n\n/** Segments shorter than this (px) have no well-defined orientation. */\nconst minimumLength = 1e-3;\n\n/**\n * A zero-thickness boundary between two local-space endpoints: level edges,\n * one-off walls, the geometry a body may not cross.\n *\n * It has no interior, so {@link Shape.massProperties} is `null` and the shape\n * contributes collision only - a `dynamic` body needs at least one mass-bearing\n * collider alongside it.\n *\n * A segment blocks from **both** sides. There is no inside for it to be outside\n * of, and a one-sided segment would be a gameplay rule in a geometry costume:\n * express that with the world's `contactModifier`, which decides per contact and\n * per step whether it is solved.\n *\n * Being zero-thickness makes it the worst case for discrete detection - a body\n * that crosses it entirely within one fixed step misses it. Continuous collision\n * covers a fast body against a segment; a fast segment is not swept.\n */\nexport class SegmentShape extends Shape {\n  public readonly type = 'segment' as const;\n\n  /** Local endpoints, flattened - the same layout a polygon uses. */\n  public readonly vertices: readonly number[];\n\n  /** The two opposite outward unit normals, flattened. */\n  public readonly normals: readonly number[];\n\n  public readonly length: number;\n  public readonly boundingRadius: number;\n\n  /** Always `null`: a boundary has no interior and therefore no mass. */\n  public readonly massProperties = null;\n\n  public constructor(x0: number, y0: number, x1: number, y1: number) {\n    super();\n\n    if (!Number.isFinite(x0) || !Number.isFinite(y0) || !Number.isFinite(x1) || !Number.isFinite(y1)) {\n      throw new RangeError(`SegmentShape: endpoints must be finite, received (${x0}, ${y0}) and (${x1}, ${y1}).`);\n    }\n\n    const ex = x1 - x0;\n    const ey = y1 - y0;\n    const length = Math.hypot(ex, ey);\n\n    if (length < minimumLength) {\n      throw new RangeError(`SegmentShape: the endpoints are coincident (length ${length}).`);\n    }\n\n    // Same convention as PolygonShape: the outward normal of the counter-clockwise\n    // edge i → i+1 is (eY, -eX). A two-vertex ring has two opposite edges.\n    const nx = ey / length;\n    const ny = -ex / length;\n\n    this.length = length;\n    this.vertices = Object.freeze([x0, y0, x1, y1]);\n    this.normals = Object.freeze([nx, ny, -nx, -ny]);\n    this.boundingRadius = Math.max(Math.hypot(x0, y0), Math.hypot(x1, y1));\n\n    // A subclass still has its own fields to write, so it freezes itself once\n    // its constructor is done.\n    if (new.target === SegmentShape) {\n      Object.freeze(this);\n    }\n  }\n}\n"],"mappings":";;;;AAGA,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;AAmBtB,IAAa,eAAb,MAAa,qBAAqB,MAAM;CACtC,AAAgB,OAAO;;CAGvB,AAAgB;;CAGhB,AAAgB;CAEhB,AAAgB;CAChB,AAAgB;;CAGhB,AAAgB,iBAAiB;CAEjC,AAAO,YAAY,IAAY,IAAY,IAAY,IAAY;EACjE,MAAM;EAEN,IAAI,CAAC,OAAO,SAAS,EAAE,KAAK,CAAC,OAAO,SAAS,EAAE,KAAK,CAAC,OAAO,SAAS,EAAE,KAAK,CAAC,OAAO,SAAS,EAAE,GAC7F,MAAM,IAAI,WAAW,qDAAqD,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,GAAG,GAAG;EAG5G,MAAM,KAAK,KAAK;EAChB,MAAM,KAAK,KAAK;EAChB,MAAM,SAAS,KAAK,MAAM,IAAI,EAAE;EAEhC,IAAI,SAAS,eACX,MAAM,IAAI,WAAW,sDAAsD,OAAO,GAAG;EAKvF,MAAM,KAAK,KAAK;EAChB,MAAM,KAAK,CAAC,KAAK;EAEjB,KAAK,SAAS;EACd,KAAK,WAAW,OAAO,OAAO;GAAC;GAAI;GAAI;GAAI;EAAE,CAAC;EAC9C,KAAK,UAAU,OAAO,OAAO;GAAC;GAAI;GAAI,CAAC;GAAI,CAAC;EAAE,CAAC;EAC/C,KAAK,iBAAiB,KAAK,IAAI,KAAK,MAAM,IAAI,EAAE,GAAG,KAAK,MAAM,IAAI,EAAE,CAAC;EAIrE,IAAI,eAAe,cACjB,OAAO,OAAO,IAAI;CAEtB;AACF"}

package/dist/esm/shapes/Shape.d.ts

@@ -1,26 +1,37 @@
 /** Discriminant for the concrete shape kinds supported in the MVP. */
-export type ShapeType = 'circle' | 'polygon';
+export type ShapeType = 'circle' | 'capsule' | 'segment' | 'polygon' | 'chain';
 /**
- * Immutable local-space collision geometry. A `Shape` carries no transform — a
- * {@link Collider} positions it in a body. Shapes also expose the area-based
- * mass properties (`area`, `centroid`, `unitInertia`) the body uses to derive
- * mass and rotational inertia from a density; these are computed once at
- * construction and frozen.
+ * Area-based mass properties of a solid shape, from which a {@link Collider}'s
+ * density derives the owning body's mass and rotational inertia. Computed once
+ * at shape construction and frozen.
+ */
+export interface ShapeMassProperties {
+    /** Surface area in px². `mass = density × area`. */
+    readonly area: number;
+    /** X of the area centroid in local space. */
+    readonly centroidX: number;
+    /** Y of the area centroid in local space. */
+    readonly centroidY: number;
+    /**
+     * Second moment of area about the centroid (∫ r² dA). Multiplying by density
+     * yields the shape's rotational inertia contribution about its centroid.
+     */
+    readonly unitInertia: number;
+}
+/**
+ * Immutable local-space collision geometry. A `Shape` carries no transform - a
+ * {@link Collider} positions it in a body.
  *
- * `unitInertia` is the second moment of area about the shape's own centroid
- * (∫ r² dA). Multiplying by density yields the rotational inertia contribution
- * of the shape about its centroid.
+ * Having an interior is a capability, not a given: solid shapes expose
+ * {@link massProperties}, while boundary geometry (a segment, a chain of edges)
+ * reports `null` and contributes nothing to the owning body's mass. Read the
+ * property rather than assuming an area exists.
  */
 export declare abstract class Shape {
     abstract readonly type: ShapeType;
     /** Radius of the smallest circle about the local origin enclosing the shape. */
     abstract readonly boundingRadius: number;
-    /** Surface area in px². `mass = density × area`. */
-    abstract readonly area: number;
-    /** X of the area centroid in local space. */
-    abstract readonly centroidX: number;
-    /** Y of the area centroid in local space. */
-    abstract readonly centroidY: number;
-    /** Second moment of area (∫ r² dA) about the centroid; `inertia = density × unitInertia`. */
-    abstract readonly unitInertia: number;
+    /** Area-based mass properties, or `null` for boundary geometry with no interior. */
+    abstract readonly massProperties: ShapeMassProperties | null;
 }
+//# sourceMappingURL=Shape.d.ts.map

package/dist/esm/shapes/Shape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Shape.d.ts","sourceRoot":"","sources":["../../../src/shapes/Shape.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;AAE/E;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6CAA6C;IAC7C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,6CAA6C;IAC7C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;GAQG;AACH,8BAAsB,KAAK;IACzB,kBAAyB,IAAI,EAAE,SAAS,CAAC;IAEzC,gFAAgF;IAChF,kBAAyB,cAAc,EAAE,MAAM,CAAC;IAEhD,oFAAoF;IACpF,kBAAyB,cAAc,EAAE,mBAAmB,GAAG,IAAI,CAAC;CACrE"}

package/dist/esm/shapes/Shape.js

@@ -1,16 +1,15 @@
+//#region src/shapes/Shape.ts
 /**
- * Immutable local-space collision geometry. A `Shape` carries no transform — a
- * {@link Collider} positions it in a body. Shapes also expose the area-based
- * mass properties (`area`, `centroid`, `unitInertia`) the body uses to derive
- * mass and rotational inertia from a density; these are computed once at
- * construction and frozen.
- *
- * `unitInertia` is the second moment of area about the shape's own centroid
- * (∫ r² dA). Multiplying by density yields the rotational inertia contribution
- * of the shape about its centroid.
- */
-class Shape {
-}
+* Immutable local-space collision geometry. A `Shape` carries no transform - a
+* {@link Collider} positions it in a body.
+*
+* Having an interior is a capability, not a given: solid shapes expose
+* {@link massProperties}, while boundary geometry (a segment, a chain of edges)
+* reports `null` and contributes nothing to the owning body's mass. Read the
+* property rather than assuming an area exists.
+*/
+var Shape = class {};
 
+//#endregion
 export { Shape };
-//# sourceMappingURL=Shape.js.map
+//# sourceMappingURL=Shape.js.map

package/dist/esm/shapes/Shape.js.map

@@ -1 +1 @@
-{"version":3,"file":"Shape.js","sources":["../../../../src/shapes/Shape.ts"],"sourcesContent":[null],"names":[],"mappings":"AAGA;;;;;;;;;;AAUG;MACmB,KAAK,CAAA;AAiB1B;;;;"}
+{"version":3,"file":"Shape.js","names":[],"sources":["../../../src/shapes/Shape.ts"],"sourcesContent":["/** Discriminant for the concrete shape kinds supported in the MVP. */\nexport type ShapeType = 'circle' | 'capsule' | 'segment' | 'polygon' | 'chain';\n\n/**\n * Area-based mass properties of a solid shape, from which a {@link Collider}'s\n * density derives the owning body's mass and rotational inertia. Computed once\n * at shape construction and frozen.\n */\nexport interface ShapeMassProperties {\n  /** Surface area in px². `mass = density × area`. */\n  readonly area: number;\n  /** X of the area centroid in local space. */\n  readonly centroidX: number;\n  /** Y of the area centroid in local space. */\n  readonly centroidY: number;\n  /**\n   * Second moment of area about the centroid (∫ r² dA). Multiplying by density\n   * yields the shape's rotational inertia contribution about its centroid.\n   */\n  readonly unitInertia: number;\n}\n\n/**\n * Immutable local-space collision geometry. A `Shape` carries no transform - a\n * {@link Collider} positions it in a body.\n *\n * Having an interior is a capability, not a given: solid shapes expose\n * {@link massProperties}, while boundary geometry (a segment, a chain of edges)\n * reports `null` and contributes nothing to the owning body's mass. Read the\n * property rather than assuming an area exists.\n */\nexport abstract class Shape {\n  public abstract readonly type: ShapeType;\n\n  /** Radius of the smallest circle about the local origin enclosing the shape. */\n  public abstract readonly boundingRadius: number;\n\n  /** Area-based mass properties, or `null` for boundary geometry with no interior. */\n  public abstract readonly massProperties: ShapeMassProperties | null;\n}\n"],"mappings":";;;;;;;;;;AA+BA,IAAsB,QAAtB,MAA4B,CAQ5B"}

package/dist/esm/shapes/convexParts.d.ts

@@ -0,0 +1,21 @@
+import type { PointLike } from '@codexo/exojs';
+import { PolygonShape } from './PolygonShape';
+/**
+ * Turn one possibly-concave outline into the convex solver shapes that
+ * represent it. Attach all of them to a single body: together they are the
+ * original area, and a `PolygonShape` stays exactly one convex shape rather
+ * than secretly standing for several.
+ *
+ * The number of shapes and their order follow from the current decomposition
+ * and are not a stable contract; the preserved properties are the area, the
+ * centre of mass and the rotational inertia of the compound.
+ *
+ * An already-convex outline yields exactly one shape, so a caller that does not
+ * know whether its input is convex can route everything through here.
+ *
+ * @throws RangeError on a non-finite coordinate, on fewer than three distinct
+ * non-collinear vertices, on a self-intersecting outline, or when a part comes
+ * out too degenerate for {@link PolygonShape}.
+ */
+export declare const toConvexPolygonShapes: (vertices: ReadonlyArray<Readonly<PointLike>>) => PolygonShape[];
+//# sourceMappingURL=convexParts.d.ts.map

package/dist/esm/shapes/convexParts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convexParts.d.ts","sourceRoot":"","sources":["../../../src/shapes/convexParts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAG/C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,qBAAqB,GAAI,UAAU,aAAa,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,KAAG,YAAY,EAC3B,CAAC"}

package/dist/esm/shapes/convexParts.js

@@ -0,0 +1,26 @@
+import { PolygonShape } from "./PolygonShape.js";
+import { decomposeToConvexParts } from "./decompose.js";
+
+//#region src/shapes/convexParts.ts
+/**
+* Turn one possibly-concave outline into the convex solver shapes that
+* represent it. Attach all of them to a single body: together they are the
+* original area, and a `PolygonShape` stays exactly one convex shape rather
+* than secretly standing for several.
+*
+* The number of shapes and their order follow from the current decomposition
+* and are not a stable contract; the preserved properties are the area, the
+* centre of mass and the rotational inertia of the compound.
+*
+* An already-convex outline yields exactly one shape, so a caller that does not
+* know whether its input is convex can route everything through here.
+*
+* @throws RangeError on a non-finite coordinate, on fewer than three distinct
+* non-collinear vertices, on a self-intersecting outline, or when a part comes
+* out too degenerate for {@link PolygonShape}.
+*/
+const toConvexPolygonShapes = (vertices) => decomposeToConvexParts(vertices).map((part) => new PolygonShape(part));
+
+//#endregion
+export { toConvexPolygonShapes };
+//# sourceMappingURL=convexParts.js.map

package/dist/esm/shapes/convexParts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"convexParts.js","names":[],"sources":["../../../src/shapes/convexParts.ts"],"sourcesContent":["import type { PointLike } from '@codexo/exojs';\n\nimport { decomposeToConvexParts } from './decompose';\nimport { PolygonShape } from './PolygonShape';\n\n/**\n * Turn one possibly-concave outline into the convex solver shapes that\n * represent it. Attach all of them to a single body: together they are the\n * original area, and a `PolygonShape` stays exactly one convex shape rather\n * than secretly standing for several.\n *\n * The number of shapes and their order follow from the current decomposition\n * and are not a stable contract; the preserved properties are the area, the\n * centre of mass and the rotational inertia of the compound.\n *\n * An already-convex outline yields exactly one shape, so a caller that does not\n * know whether its input is convex can route everything through here.\n *\n * @throws RangeError on a non-finite coordinate, on fewer than three distinct\n * non-collinear vertices, on a self-intersecting outline, or when a part comes\n * out too degenerate for {@link PolygonShape}.\n */\nexport const toConvexPolygonShapes = (vertices: ReadonlyArray<Readonly<PointLike>>): PolygonShape[] =>\n  decomposeToConvexParts(vertices).map(part => new PolygonShape(part));\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAsBA,MAAa,yBAAyB,aACpC,uBAAuB,QAAQ,CAAC,CAAC,KAAI,SAAQ,IAAI,aAAa,IAAI,CAAC"}

package/dist/esm/shapes/decompose.d.ts

@@ -0,0 +1,24 @@
+import type { PointLike } from '@codexo/exojs';
+/**
+ * Split a simple polygon into convex parts.
+ *
+ * The input may be concave, wound either way, and may carry duplicate or
+ * collinear vertices; it must not intersect itself. The result is a list of
+ * strictly convex, counter-clockwise parts whose union is the input and whose
+ * interiors do not overlap. An already-convex input yields exactly one part.
+ *
+ * Deterministic: the same cleaned input always produces the same parts. The
+ * number of parts and their order are an artefact of the current algorithm and
+ * must not be relied on - assert convexity, preserved area and preserved mass
+ * properties instead.
+ *
+ * Cost is O(n²) in the vertex count (self-intersection check and ear clipping),
+ * which suits import-time geometry rather than a per-step path.
+ *
+ * @throws RangeError if a coordinate is not finite, if fewer than three
+ * distinct non-collinear vertices remain after cleanup, or if the outline
+ * intersects itself.
+ * @internal
+ */
+export declare const decomposeToConvexParts: (vertices: ReadonlyArray<Readonly<PointLike>>) => PointLike[][];
+//# sourceMappingURL=decompose.d.ts.map

package/dist/esm/shapes/decompose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decompose.d.ts","sourceRoot":"","sources":["../../../src/shapes/decompose.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAmB/C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,sBAAsB,GAAI,UAAU,aAAa,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,KAAG,SAAS,EAAE,EAqChG,CAAC"}

package/dist/esm/shapes/decompose.js

@@ -0,0 +1,272 @@
+import { triangulate } from "@codexo/exojs";
+
+//#region src/shapes/decompose.ts
+/** Vertices closer than this (px) are welded into one. */
+const weldEpsilon = 1e-4;
+/**
+* Sine-of-turn threshold below which three consecutive vertices count as
+* collinear. Compared against the normalised cross product so the test is
+* scale-free: a 10 px polygon and a 10 000 px one accept the same shapes.
+*/
+const collinearEpsilon = 1e-7;
+/**
+* Fraction of the outline's area below which a triangulation face counts as
+* empty. Ear clipping emits its last triangle without an orientation test, so a
+* polygon whose final three vertices end up collinear yields one zero-area face
+* - it covers nothing and must not become a collider.
+*/
+const degenerateAreaFraction = 1e-9;
+/**
+* Split a simple polygon into convex parts.
+*
+* The input may be concave, wound either way, and may carry duplicate or
+* collinear vertices; it must not intersect itself. The result is a list of
+* strictly convex, counter-clockwise parts whose union is the input and whose
+* interiors do not overlap. An already-convex input yields exactly one part.
+*
+* Deterministic: the same cleaned input always produces the same parts. The
+* number of parts and their order are an artefact of the current algorithm and
+* must not be relied on - assert convexity, preserved area and preserved mass
+* properties instead.
+*
+* Cost is O(n²) in the vertex count (self-intersection check and ear clipping),
+* which suits import-time geometry rather than a per-step path.
+*
+* @throws RangeError if a coordinate is not finite, if fewer than three
+* distinct non-collinear vertices remain after cleanup, or if the outline
+* intersects itself.
+* @internal
+*/
+const decomposeToConvexParts = (vertices) => {
+	const points = normalize(vertices);
+	const count = points.length / 2;
+	assertSimple(points);
+	if (isStrictlyConvex(points)) return [toPoints(points, sequence(count))];
+	const indices = triangulate(points);
+	if (indices.length !== (count - 2) * 3) throw new RangeError(`decomposeToConvexParts: could not triangulate the outline (${indices.length / 3} of ${count - 2} triangles); check it for near-degenerate geometry.`);
+	const sourceArea = Math.abs(signedArea(points));
+	const cycles = mergeTriangles(points, indices, sourceArea * degenerateAreaFraction);
+	const parts = cycles.map((cycle) => toPoints(points, cycle));
+	const partArea = cycles.reduce((sum, cycle) => sum + Math.abs(cycleArea(points, cycle)), 0);
+	if (parts.length === 0 || Math.abs(partArea - sourceArea) > sourceArea * 1e-6) throw new RangeError(`decomposeToConvexParts: the parts cover ${partArea.toFixed(4)} of the outline's ${sourceArea.toFixed(4)}; the outline is too degenerate to decompose.`);
+	return parts;
+};
+/**
+* Weld coincident vertices, drop collinear ones and canonicalise to
+* counter-clockwise, returning a flat `[x0, y0, x1, y1, ...]` array.
+*/
+const normalize = (vertices) => {
+	const points = [];
+	for (const vertex of vertices) {
+		if (!Number.isFinite(vertex.x) || !Number.isFinite(vertex.y)) throw new RangeError(`decomposeToConvexParts: vertex has a non-finite component (${vertex.x}, ${vertex.y}).`);
+		if (points.length === 0) {
+			points.push(vertex.x, vertex.y);
+			continue;
+		}
+		if (Math.hypot(vertex.x - points[points.length - 2], vertex.y - points[points.length - 1]) >= weldEpsilon) points.push(vertex.x, vertex.y);
+	}
+	if (points.length >= 4 && Math.hypot(points[0] - points[points.length - 2], points[1] - points[points.length - 1]) < weldEpsilon) points.length -= 2;
+	if (signedArea(points) < 0) reverseWinding(points);
+	dropCollinear(points);
+	if (points.length < 6) throw new RangeError(`decomposeToConvexParts: needs at least 3 distinct, non-collinear vertices, received ${points.length / 2} after cleanup.`);
+	if (Math.abs(signedArea(points)) <= weldEpsilon) throw new RangeError("decomposeToConvexParts: the outline encloses no area.");
+	return points;
+};
+/**
+* Remove every vertex whose two edges are collinear. Repeats until stable: one
+* removal can make its neighbour collinear in turn.
+*/
+const dropCollinear = (points) => {
+	let removed = true;
+	while (removed && points.length >= 6) {
+		removed = false;
+		for (let i = 0; i < points.length / 2; i++) {
+			const count = points.length / 2;
+			if (count < 3) break;
+			const p = (i + count - 1) % count;
+			const n = (i + 1) % count;
+			if (isCollinear(points, p, i, n)) {
+				points.splice(i * 2, 2);
+				removed = true;
+				i--;
+			}
+		}
+	}
+};
+const isCollinear = (points, a, b, c) => {
+	const e1x = points[b * 2] - points[a * 2];
+	const e1y = points[b * 2 + 1] - points[a * 2 + 1];
+	const e2x = points[c * 2] - points[b * 2];
+	const e2y = points[c * 2 + 1] - points[b * 2 + 1];
+	const lengths = Math.hypot(e1x, e1y) * Math.hypot(e2x, e2y);
+	return lengths === 0 || Math.abs(e1x * e2y - e1y * e2x) <= collinearEpsilon * lengths;
+};
+/**
+* Reject an outline that crosses or touches itself. Every pair of non-adjacent
+* edges must be disjoint - a shared point between them is exactly what makes a
+* polygon non-simple, and both ear clipping and the solver assume it cannot
+* happen.
+*/
+const assertSimple = (points) => {
+	const count = points.length / 2;
+	for (let i = 0; i < count; i++) {
+		const iNext = (i + 1) % count;
+		for (let j = i + 1; j < count; j++) {
+			const jNext = (j + 1) % count;
+			if (i === j || iNext === j || jNext === i) continue;
+			if (segmentsIntersect(points, i, iNext, j, jNext)) throw new RangeError("decomposeToConvexParts: the outline intersects itself; only simple polygons can be decomposed.");
+		}
+	}
+};
+/** `true` when segments `a→b` and `c→d` share any point, touching included. */
+const segmentsIntersect = (points, a, b, c, d) => {
+	const o1 = orientation(points, a, b, c);
+	const o2 = orientation(points, a, b, d);
+	const o3 = orientation(points, c, d, a);
+	const o4 = orientation(points, c, d, b);
+	if (o1 !== o2 && o3 !== o4) return true;
+	return o1 === 0 && onSegment(points, a, b, c) || o2 === 0 && onSegment(points, a, b, d) || o3 === 0 && onSegment(points, c, d, a) || o4 === 0 && onSegment(points, c, d, b);
+};
+/** Sign of the turn `a → b → c`: `1` left, `-1` right, `0` collinear. */
+const orientation = (points, a, b, c) => {
+	const cross = (points[b * 2] - points[a * 2]) * (points[c * 2 + 1] - points[a * 2 + 1]) - (points[b * 2 + 1] - points[a * 2 + 1]) * (points[c * 2] - points[a * 2]);
+	const scale = Math.hypot(points[b * 2] - points[a * 2], points[b * 2 + 1] - points[a * 2 + 1]) * Math.hypot(points[c * 2] - points[a * 2], points[c * 2 + 1] - points[a * 2 + 1]);
+	if (scale === 0 || Math.abs(cross) <= collinearEpsilon * scale) return 0;
+	return cross > 0 ? 1 : -1;
+};
+/** `true` when `p` lies within the bounding box of the collinear segment `a→b`. */
+const onSegment = (points, a, b, p) => points[p * 2] >= Math.min(points[a * 2], points[b * 2]) - weldEpsilon && points[p * 2] <= Math.max(points[a * 2], points[b * 2]) + weldEpsilon && points[p * 2 + 1] >= Math.min(points[a * 2 + 1], points[b * 2 + 1]) - weldEpsilon && points[p * 2 + 1] <= Math.max(points[a * 2 + 1], points[b * 2 + 1]) + weldEpsilon;
+/**
+* Hertel-Mehlhorn: start from the triangulation and drop every internal
+* diagonal whose two faces merge into a still-convex polygon. Diagonals are
+* visited in a fixed key order, so the outcome depends only on the cleaned
+* input.
+*/
+const mergeTriangles = (points, indices, degenerateArea) => {
+	const cycles = /* @__PURE__ */ new Map();
+	const owners = /* @__PURE__ */ new Map();
+	const parent = [];
+	const find = (id) => {
+		let root = id;
+		while (parent[root] !== root) root = parent[root];
+		return root;
+	};
+	const stride = points.length / 2;
+	const diagonalKey = (a, b) => a < b ? a * stride + b : b * stride + a;
+	for (let t = 0; t < indices.length; t += 3) {
+		const id = t / 3;
+		const cycle = [
+			indices[t],
+			indices[t + 1],
+			indices[t + 2]
+		];
+		if (Math.abs(cycleArea(points, cycle)) <= degenerateArea) continue;
+		parent[id] = id;
+		cycles.set(id, cycle);
+		for (let e = 0; e < 3; e++) {
+			const key = diagonalKey(cycle[e], cycle[(e + 1) % 3]);
+			const owner = owners.get(key);
+			if (owner === void 0) owners.set(key, [id]);
+			else owner.push(id);
+		}
+	}
+	for (const key of [...owners.keys()].sort((x, y) => x - y)) {
+		const owner = owners.get(key);
+		if (owner.length !== 2) continue;
+		const rootA = find(owner[0]);
+		const rootB = find(owner[1]);
+		if (rootA === rootB) continue;
+		const cycleA = cycles.get(rootA);
+		const cycleB = cycles.get(rootB);
+		const merged = mergeAcross(points, cycleA, cycleB, Math.floor(key / stride), key % stride);
+		if (merged === null) continue;
+		const keep = rootA < rootB ? rootA : rootB;
+		const drop = rootA < rootB ? rootB : rootA;
+		cycles.set(keep, merged);
+		cycles.delete(drop);
+		parent[drop] = keep;
+	}
+	return [...cycles.values()];
+};
+/**
+* Join two convex cycles across the shared edge between `u` and `v`, or `null`
+* when the union would not be strictly convex. Rejecting a merely collinear
+* junction is deliberate: the resulting part is handed to `PolygonShape`, which
+* refuses collinear edges.
+*/
+const mergeAcross = (points, cycleA, cycleB, u, v) => {
+	let a = u;
+	let b = v;
+	let start = directedEdgeIndex(cycleA, a, b);
+	if (start === -1) {
+		a = v;
+		b = u;
+		start = directedEdgeIndex(cycleA, a, b);
+	}
+	const back = start === -1 ? -1 : directedEdgeIndex(cycleB, b, a);
+	if (start === -1 || back === -1) return null;
+	const merged = [];
+	for (let i = 0; i < cycleA.length; i++) merged.push(cycleA[(start + 1 + i) % cycleA.length]);
+	for (let i = 2; i < cycleB.length; i++) merged.push(cycleB[(back + i) % cycleB.length]);
+	return isCycleStrictlyConvex(points, merged) ? merged : null;
+};
+/** Index of `a` in `cycle` when `b` immediately follows it, else `-1`. */
+const directedEdgeIndex = (cycle, a, b) => {
+	for (let i = 0; i < cycle.length; i++) if (cycle[i] === a && cycle[(i + 1) % cycle.length] === b) return i;
+	return -1;
+};
+const isCycleStrictlyConvex = (points, cycle) => {
+	for (let i = 0; i < cycle.length; i++) {
+		const a = cycle[i];
+		const b = cycle[(i + 1) % cycle.length];
+		const c = cycle[(i + 2) % cycle.length];
+		if (orientation(points, a, b, c) <= 0) return false;
+	}
+	return true;
+};
+const isStrictlyConvex = (points) => isCycleStrictlyConvex(points, sequence(points.length / 2));
+const sequence = (count) => {
+	const out = [];
+	for (let i = 0; i < count; i++) out.push(i);
+	return out;
+};
+const toPoints = (points, cycle) => cycle.map((index) => ({
+	x: points[index * 2],
+	y: points[index * 2 + 1]
+}));
+/** Shoelace signed area of an index cycle over `points`. */
+const cycleArea = (points, cycle) => {
+	let sum = 0;
+	for (let i = 0; i < cycle.length; i++) {
+		const a = cycle[i];
+		const b = cycle[(i + 1) % cycle.length];
+		sum += points[a * 2] * points[b * 2 + 1] - points[b * 2] * points[a * 2 + 1];
+	}
+	return sum / 2;
+};
+/** Shoelace signed area of a flat point ring; positive is counter-clockwise. */
+const signedArea = (points) => {
+	const count = points.length / 2;
+	let sum = 0;
+	for (let i = 0; i < count; i++) {
+		const j = (i + 1) % count;
+		sum += points[i * 2] * points[j * 2 + 1] - points[j * 2] * points[i * 2 + 1];
+	}
+	return sum / 2;
+};
+const reverseWinding = (points) => {
+	const count = points.length / 2;
+	for (let i = 0; i < Math.floor(count / 2); i++) {
+		const j = count - 1 - i;
+		const ix = points[i * 2];
+		const iy = points[i * 2 + 1];
+		points[i * 2] = points[j * 2];
+		points[i * 2 + 1] = points[j * 2 + 1];
+		points[j * 2] = ix;
+		points[j * 2 + 1] = iy;
+	}
+};
+
+//#endregion
+export { decomposeToConvexParts };
+//# sourceMappingURL=decompose.js.map

package/dist/esm/shapes/decompose.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decompose.js","names":[],"sources":["../../../src/shapes/decompose.ts"],"sourcesContent":["import type { PointLike } from '@codexo/exojs';\nimport { triangulate } from '@codexo/exojs';\n\n/** Vertices closer than this (px) are welded into one. */\nconst weldEpsilon = 1e-4;\n/**\n * Sine-of-turn threshold below which three consecutive vertices count as\n * collinear. Compared against the normalised cross product so the test is\n * scale-free: a 10 px polygon and a 10 000 px one accept the same shapes.\n */\nconst collinearEpsilon = 1e-7;\n/**\n * Fraction of the outline's area below which a triangulation face counts as\n * empty. Ear clipping emits its last triangle without an orientation test, so a\n * polygon whose final three vertices end up collinear yields one zero-area face\n * - it covers nothing and must not become a collider.\n */\nconst degenerateAreaFraction = 1e-9;\n\n/**\n * Split a simple polygon into convex parts.\n *\n * The input may be concave, wound either way, and may carry duplicate or\n * collinear vertices; it must not intersect itself. The result is a list of\n * strictly convex, counter-clockwise parts whose union is the input and whose\n * interiors do not overlap. An already-convex input yields exactly one part.\n *\n * Deterministic: the same cleaned input always produces the same parts. The\n * number of parts and their order are an artefact of the current algorithm and\n * must not be relied on - assert convexity, preserved area and preserved mass\n * properties instead.\n *\n * Cost is O(n²) in the vertex count (self-intersection check and ear clipping),\n * which suits import-time geometry rather than a per-step path.\n *\n * @throws RangeError if a coordinate is not finite, if fewer than three\n * distinct non-collinear vertices remain after cleanup, or if the outline\n * intersects itself.\n * @internal\n */\nexport const decomposeToConvexParts = (vertices: ReadonlyArray<Readonly<PointLike>>): PointLike[][] => {\n  const points = normalize(vertices);\n  const count = points.length / 2;\n\n  assertSimple(points);\n\n  if (isStrictlyConvex(points)) {\n    return [toPoints(points, sequence(count))];\n  }\n\n  const indices = triangulate(points);\n\n  // Ear clipping stops early rather than throwing when it cannot find an ear,\n  // so a short index list is how a polygon that survived the checks above but is\n  // still numerically degenerate shows up. Accepting it would silently drop area.\n  if (indices.length !== (count - 2) * 3) {\n    throw new RangeError(\n      `decomposeToConvexParts: could not triangulate the outline (${indices.length / 3} of ${count - 2} triangles); check it for near-degenerate geometry.`,\n    );\n  }\n\n  const sourceArea = Math.abs(signedArea(points));\n  const cycles = mergeTriangles(points, indices, sourceArea * degenerateAreaFraction);\n  const parts = cycles.map(cycle => toPoints(points, cycle));\n\n  // Post-condition rather than trust: ear clipping and the merge pass both work\n  // on floating-point turns, and any future change that started losing area\n  // would otherwise show up as a silently smaller collider.\n  const partArea = cycles.reduce((sum, cycle) => sum + Math.abs(cycleArea(points, cycle)), 0);\n\n  if (parts.length === 0 || Math.abs(partArea - sourceArea) > sourceArea * 1e-6) {\n    throw new RangeError(\n      `decomposeToConvexParts: the parts cover ${partArea.toFixed(4)} of the outline's ${sourceArea.toFixed(4)}; the outline is too degenerate to decompose.`,\n    );\n  }\n\n  return parts;\n};\n\n/**\n * Weld coincident vertices, drop collinear ones and canonicalise to\n * counter-clockwise, returning a flat `[x0, y0, x1, y1, ...]` array.\n */\nconst normalize = (vertices: ReadonlyArray<Readonly<PointLike>>): number[] => {\n  const points: number[] = [];\n\n  for (const vertex of vertices) {\n    if (!Number.isFinite(vertex.x) || !Number.isFinite(vertex.y)) {\n      throw new RangeError(`decomposeToConvexParts: vertex has a non-finite component (${vertex.x}, ${vertex.y}).`);\n    }\n\n    if (points.length === 0) {\n      points.push(vertex.x, vertex.y);\n\n      continue;\n    }\n\n    if (Math.hypot(vertex.x - points[points.length - 2]!, vertex.y - points[points.length - 1]!) >= weldEpsilon) {\n      points.push(vertex.x, vertex.y);\n    }\n  }\n\n  // A trailing vertex coinciding with the first closes the ring explicitly; the\n  // ring is implicit here.\n  if (points.length >= 4 && Math.hypot(points[0]! - points[points.length - 2]!, points[1]! - points[points.length - 1]!) < weldEpsilon) {\n    points.length -= 2;\n  }\n\n  if (signedArea(points) < 0) {\n    reverseWinding(points);\n  }\n\n  dropCollinear(points);\n\n  if (points.length < 6) {\n    throw new RangeError(`decomposeToConvexParts: needs at least 3 distinct, non-collinear vertices, received ${points.length / 2} after cleanup.`);\n  }\n\n  if (Math.abs(signedArea(points)) <= weldEpsilon) {\n    throw new RangeError('decomposeToConvexParts: the outline encloses no area.');\n  }\n\n  return points;\n};\n\n/**\n * Remove every vertex whose two edges are collinear. Repeats until stable: one\n * removal can make its neighbour collinear in turn.\n */\nconst dropCollinear = (points: number[]): void => {\n  let removed = true;\n\n  while (removed && points.length >= 6) {\n    removed = false;\n\n    for (let i = 0; i < points.length / 2; i++) {\n      const count = points.length / 2;\n\n      if (count < 3) {\n        break;\n      }\n\n      const p = (i + count - 1) % count;\n      const n = (i + 1) % count;\n\n      if (isCollinear(points, p, i, n)) {\n        points.splice(i * 2, 2);\n        removed = true;\n        i--;\n      }\n    }\n  }\n};\n\nconst isCollinear = (points: number[], a: number, b: number, c: number): boolean => {\n  const e1x = points[b * 2]! - points[a * 2]!;\n  const e1y = points[b * 2 + 1]! - points[a * 2 + 1]!;\n  const e2x = points[c * 2]! - points[b * 2]!;\n  const e2y = points[c * 2 + 1]! - points[b * 2 + 1]!;\n  const lengths = Math.hypot(e1x, e1y) * Math.hypot(e2x, e2y);\n\n  return lengths === 0 || Math.abs(e1x * e2y - e1y * e2x) <= collinearEpsilon * lengths;\n};\n\n/**\n * Reject an outline that crosses or touches itself. Every pair of non-adjacent\n * edges must be disjoint - a shared point between them is exactly what makes a\n * polygon non-simple, and both ear clipping and the solver assume it cannot\n * happen.\n */\nconst assertSimple = (points: number[]): void => {\n  const count = points.length / 2;\n\n  for (let i = 0; i < count; i++) {\n    const iNext = (i + 1) % count;\n\n    for (let j = i + 1; j < count; j++) {\n      const jNext = (j + 1) % count;\n\n      // Edges sharing a vertex always \"touch\" at it; only non-adjacent pairs\n      // carry information.\n      if (i === j || iNext === j || jNext === i) {\n        continue;\n      }\n\n      if (segmentsIntersect(points, i, iNext, j, jNext)) {\n        throw new RangeError('decomposeToConvexParts: the outline intersects itself; only simple polygons can be decomposed.');\n      }\n    }\n  }\n};\n\n/** `true` when segments `a→b` and `c→d` share any point, touching included. */\nconst segmentsIntersect = (points: number[], a: number, b: number, c: number, d: number): boolean => {\n  const o1 = orientation(points, a, b, c);\n  const o2 = orientation(points, a, b, d);\n  const o3 = orientation(points, c, d, a);\n  const o4 = orientation(points, c, d, b);\n\n  if (o1 !== o2 && o3 !== o4) {\n    return true;\n  }\n\n  return (\n    (o1 === 0 && onSegment(points, a, b, c)) ||\n    (o2 === 0 && onSegment(points, a, b, d)) ||\n    (o3 === 0 && onSegment(points, c, d, a)) ||\n    (o4 === 0 && onSegment(points, c, d, b))\n  );\n};\n\n/** Sign of the turn `a → b → c`: `1` left, `-1` right, `0` collinear. */\nconst orientation = (points: number[], a: number, b: number, c: number): number => {\n  const cross =\n    (points[b * 2]! - points[a * 2]!) * (points[c * 2 + 1]! - points[a * 2 + 1]!) -\n    (points[b * 2 + 1]! - points[a * 2 + 1]!) * (points[c * 2]! - points[a * 2]!);\n  const scale =\n    Math.hypot(points[b * 2]! - points[a * 2]!, points[b * 2 + 1]! - points[a * 2 + 1]!) *\n    Math.hypot(points[c * 2]! - points[a * 2]!, points[c * 2 + 1]! - points[a * 2 + 1]!);\n\n  if (scale === 0 || Math.abs(cross) <= collinearEpsilon * scale) {\n    return 0;\n  }\n\n  return cross > 0 ? 1 : -1;\n};\n\n/** `true` when `p` lies within the bounding box of the collinear segment `a→b`. */\nconst onSegment = (points: number[], a: number, b: number, p: number): boolean =>\n  points[p * 2]! >= Math.min(points[a * 2]!, points[b * 2]!) - weldEpsilon &&\n  points[p * 2]! <= Math.max(points[a * 2]!, points[b * 2]!) + weldEpsilon &&\n  points[p * 2 + 1]! >= Math.min(points[a * 2 + 1]!, points[b * 2 + 1]!) - weldEpsilon &&\n  points[p * 2 + 1]! <= Math.max(points[a * 2 + 1]!, points[b * 2 + 1]!) + weldEpsilon;\n\n/**\n * Hertel-Mehlhorn: start from the triangulation and drop every internal\n * diagonal whose two faces merge into a still-convex polygon. Diagonals are\n * visited in a fixed key order, so the outcome depends only on the cleaned\n * input.\n */\nconst mergeTriangles = (points: number[], indices: Uint32Array, degenerateArea: number): number[][] => {\n  const cycles = new Map<number, number[]>();\n  const owners = new Map<number, number[]>();\n  // Union-find over part ids: a merged part keeps the lower id, and every\n  // diagonal recorded against the absorbed one resolves through here.\n  const parent: number[] = [];\n\n  const find = (id: number): number => {\n    let root = id;\n\n    while (parent[root] !== root) {\n      root = parent[root]!;\n    }\n\n    return root;\n  };\n\n  const stride = points.length / 2;\n  const diagonalKey = (a: number, b: number): number => (a < b ? a * stride + b : b * stride + a);\n\n  for (let t = 0; t < indices.length; t += 3) {\n    const id = t / 3;\n    const cycle = [indices[t]!, indices[t + 1]!, indices[t + 2]!];\n\n    if (Math.abs(cycleArea(points, cycle)) <= degenerateArea) {\n      continue;\n    }\n\n    parent[id] = id;\n    cycles.set(id, cycle);\n\n    for (let e = 0; e < 3; e++) {\n      const key = diagonalKey(cycle[e]!, cycle[(e + 1) % 3]!);\n      const owner = owners.get(key);\n\n      if (owner === undefined) {\n        owners.set(key, [id]);\n      } else {\n        owner.push(id);\n      }\n    }\n  }\n\n  for (const key of [...owners.keys()].sort((x, y) => x - y)) {\n    const owner = owners.get(key)!;\n\n    if (owner.length !== 2) {\n      continue;\n    }\n\n    const rootA = find(owner[0]!);\n    const rootB = find(owner[1]!);\n\n    if (rootA === rootB) {\n      continue;\n    }\n\n    const cycleA = cycles.get(rootA)!;\n    const cycleB = cycles.get(rootB)!;\n    const merged = mergeAcross(points, cycleA, cycleB, Math.floor(key / stride), key % stride);\n\n    if (merged === null) {\n      continue;\n    }\n\n    const keep = rootA < rootB ? rootA : rootB;\n    const drop = rootA < rootB ? rootB : rootA;\n\n    cycles.set(keep, merged);\n    cycles.delete(drop);\n    parent[drop] = keep;\n  }\n\n  return [...cycles.values()];\n};\n\n/**\n * Join two convex cycles across the shared edge between `u` and `v`, or `null`\n * when the union would not be strictly convex. Rejecting a merely collinear\n * junction is deliberate: the resulting part is handed to `PolygonShape`, which\n * refuses collinear edges.\n */\nconst mergeAcross = (points: number[], cycleA: number[], cycleB: number[], u: number, v: number): number[] | null => {\n  // Both cycles are counter-clockwise and share the undirected edge, so exactly\n  // one of them traverses it as `a → b` and the other as `b → a`.\n  let a = u;\n  let b = v;\n  let start = directedEdgeIndex(cycleA, a, b);\n\n  if (start === -1) {\n    a = v;\n    b = u;\n    start = directedEdgeIndex(cycleA, a, b);\n  }\n\n  const back = start === -1 ? -1 : directedEdgeIndex(cycleB, b, a);\n\n  if (start === -1 || back === -1) {\n    return null;\n  }\n\n  // Walk A once starting at b (so it ends on a), then splice in B's vertices\n  // strictly between a and b.\n  const merged: number[] = [];\n\n  for (let i = 0; i < cycleA.length; i++) {\n    merged.push(cycleA[(start + 1 + i) % cycleA.length]!);\n  }\n\n  for (let i = 2; i < cycleB.length; i++) {\n    merged.push(cycleB[(back + i) % cycleB.length]!);\n  }\n\n  return isCycleStrictlyConvex(points, merged) ? merged : null;\n};\n\n/** Index of `a` in `cycle` when `b` immediately follows it, else `-1`. */\nconst directedEdgeIndex = (cycle: number[], a: number, b: number): number => {\n  for (let i = 0; i < cycle.length; i++) {\n    if (cycle[i] === a && cycle[(i + 1) % cycle.length] === b) {\n      return i;\n    }\n  }\n\n  return -1;\n};\n\nconst isCycleStrictlyConvex = (points: number[], cycle: number[]): boolean => {\n  for (let i = 0; i < cycle.length; i++) {\n    const a = cycle[i]!;\n    const b = cycle[(i + 1) % cycle.length]!;\n    const c = cycle[(i + 2) % cycle.length]!;\n\n    if (orientation(points, a, b, c) <= 0) {\n      return false;\n    }\n  }\n\n  return true;\n};\n\nconst isStrictlyConvex = (points: number[]): boolean => isCycleStrictlyConvex(points, sequence(points.length / 2));\n\nconst sequence = (count: number): number[] => {\n  const out: number[] = [];\n\n  for (let i = 0; i < count; i++) {\n    out.push(i);\n  }\n\n  return out;\n};\n\nconst toPoints = (points: number[], cycle: number[]): PointLike[] => cycle.map(index => ({ x: points[index * 2]!, y: points[index * 2 + 1]! }));\n\n/** Shoelace signed area of an index cycle over `points`. */\nconst cycleArea = (points: number[], cycle: number[]): number => {\n  let sum = 0;\n\n  for (let i = 0; i < cycle.length; i++) {\n    const a = cycle[i]!;\n    const b = cycle[(i + 1) % cycle.length]!;\n\n    sum += points[a * 2]! * points[b * 2 + 1]! - points[b * 2]! * points[a * 2 + 1]!;\n  }\n\n  return sum / 2;\n};\n\n/** Shoelace signed area of a flat point ring; positive is counter-clockwise. */\nconst signedArea = (points: number[]): number => {\n  const count = points.length / 2;\n  let sum = 0;\n\n  for (let i = 0; i < count; i++) {\n    const j = (i + 1) % count;\n\n    sum += points[i * 2]! * points[j * 2 + 1]! - points[j * 2]! * points[i * 2 + 1]!;\n  }\n\n  return sum / 2;\n};\n\nconst reverseWinding = (points: number[]): void => {\n  const count = points.length / 2;\n\n  for (let i = 0; i < Math.floor(count / 2); i++) {\n    const j = count - 1 - i;\n    const ix = points[i * 2]!;\n    const iy = points[i * 2 + 1]!;\n\n    points[i * 2] = points[j * 2]!;\n    points[i * 2 + 1] = points[j * 2 + 1]!;\n    points[j * 2] = ix;\n    points[j * 2 + 1] = iy;\n  }\n};\n"],"mappings":"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"}

package/dist/esm/shapes/index.d.ts

@@ -1,5 +1,9 @@
 export type { AnyShape } from './AnyShape';
 export { BoxShape } from './BoxShape';
+export { CapsuleShape } from './CapsuleShape';
+export { ChainShape, type ChainShapeOptions } from './ChainShape';
 export { CircleShape } from './CircleShape';
 export { PolygonShape } from './PolygonShape';
+export { SegmentShape } from './SegmentShape';
 export { Shape, type ShapeType } from './Shape';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/shapes/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/shapes/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,KAAK,EAAE,KAAK,SAAS,EAAE,MAAM,SAAS,CAAC"}

package/dist/esm/solver/ContactSolver.d.ts

@@ -11,7 +11,7 @@ import type { ContactRecord } from '../ContactGraph';
  *
  * The position constraint is folded into the velocity solve as a **soft bias**
  * (a damped-spring push-out whose stiffness is decoupled from the iteration
- * count), recomputed each pass from the live per-body delta position/rotation —
+ * count), recomputed each pass from the live per-body delta position/rotation -
  * so there is no separate NGS geometric pass. The contact anchors are rotated by
  * the live sub-step rotation each pass, so a tilting stack's restoring torque is
  * computed against its current orientation (without this the tilt grows instead
@@ -19,8 +19,9 @@ import type { ContactRecord } from '../ContactGraph';
  * 2×2 block LCP** (Box2D-style), which propagates stack loads far better than
  * solving the points sequentially; the block path carries the soft push-out as
  * its velocity target (hard mass scale), while single-point contacts use the full
- * soft mass/impulse scaling. Accumulated impulses are written back to each
- * {@link ContactRecord} for warm-starting the next frame.
+ * soft mass/impulse scaling for as long as their push-out target stays inside
+ * the cap, and the hard scale once it is clamped. Accumulated impulses are
+ * written back to each {@link ContactRecord} for warm-starting the next frame.
  *
  * Internal to {@link NativePhysicsBackend}; not part of the public surface.
  */
@@ -64,6 +65,13 @@ export declare class ContactSolver {
      * pushes out the penetration and bleeds a little stored impulse (the damped
      * spring). The relax pass passes `useBias=false`, collapsing it to the hard
      * `−normalMass·vn` (no bias, full mass, no impulse decay).
+     *
+     * A point whose push-out target was clamped to `maxBiasVelocity` is solved
+     * with the hard scale as well: the soft scaling models a spring, and once the
+     * target is capped the point would otherwise reach only a fraction of an
+     * already limited push-out. That deficit grows with the load, so past the
+     * acceleration at which the cap binds the contact would sink without bound
+     * instead of settling into a slightly deeper limit cycle.
      */
     private _solveNormalSequential;
     /**
@@ -74,8 +82,6 @@ export declare class ContactSolver {
      * soft push-out as its target but solves with a hard mass scale.
      */
     private _solveNormalBlock;
-    /** Apply the two-point block impulse deltas `(d1, d2)` along the normal at both contact points. */
-    private _applyBlock;
     private _acquire;
     /**
      * Pooled constraint at `ci`. Every caller indexes within `0..this._count-1`
@@ -85,3 +91,4 @@ export declare class ContactSolver {
      */
     private _at;
 }
+//# sourceMappingURL=ContactSolver.d.ts.map