@flighthq/collision 0.3.0-next.906.07cea63 → 0.3.1-next.209.43ef1bc

package/dist/collideContactManifold.d.ts

@@ -0,0 +1,3 @@
+import type { CollisionContactManifold, CollisionShape } from '@flighthq/types/contract';
+export declare function collideContactManifold(a: Readonly<CollisionShape>, b: Readonly<CollisionShape>, out: CollisionContactManifold): boolean;
+//# sourceMappingURL=collideContactManifold.d.ts.map

package/dist/collideContactManifold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collideContactManifold.d.ts","sourceRoot":"","sources":["../src/collideContactManifold.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,cAAc,EAAsB,MAAM,0BAA0B,CAAC;AA0C7G,wBAAgB,sBAAsB,CACpC,CAAC,EAAE,QAAQ,CAAC,cAAc,CAAC,EAC3B,CAAC,EAAE,QAAQ,CAAC,cAAc,CAAC,EAC3B,GAAG,EAAE,wBAAwB,GAC5B,OAAO,CAiET"}

package/dist/collideContactManifold.js

@@ -0,0 +1,109 @@
+import { clearCollisionContactManifold } from './contactManifold';
+import { collideAabbAabbContactManifold, collideAabbObbContactManifold, collideAabbPolygonContactManifold, collideCircleAabbContactManifold, collideCircleCircleContactManifold, collideCircleObbContactManifold, collideCirclePolygonContactManifold, collideObbObbContactManifold, collideObbPolygonContactManifold, collidePolygonPolygonContactManifold, } from './shapeContact';
+// Generic narrow-phase contact test: the `testCollision` dispatcher's contact-resolving twin.
+// Dispatches on the two shapes' `kind`s and writes the full contact manifold pushing **A out of B**.
+// Shapes are ordered by kind rank before dispatch, and the normal is negated when the arguments
+// arrived reversed, exactly as `testCollision` does. Contact points are world-space and need no such
+// correction.
+//
+// **Argument order.** Overlap, normal, and depth are order-invariant for every pair (the normal
+// negates, nothing else moves). Contact points and their feature ids are order-invariant only for
+// pairs of DIFFERENT kinds, where the kind rank fixes which shape owns the reference face. For two
+// shapes of the SAME kind the caller's order decides: two coincident faces tie exactly on separation
+// (a box resting squarely on a box is the common case), the tie resolves toward the first argument,
+// and the reference shape is the one whose face the contact points then lie on. Reversing the
+// arguments moves the points to the opposite surface — one penetration depth away, both correct —
+// and renumbers their ids.
+//
+// This is a property of the pair, not a defect to fix here. Resolving it would need a tie-break
+// derived from the shapes' own coordinates, and any such rule is a pure function of values that flips
+// the moment those values cross — reintroducing, at dispatch, the frame-to-frame flapping that the
+// reference-face bias exists to prevent. Stability across frames needs memory of the previous frame,
+// which a stateless narrow phase does not have and a simulation does. So a caller that keys anything
+// on feature identity (a warm-start cache) must pass each pair in a STABLE order of its own — ordering
+// by persistent body identity, not by geometry, since only identity survives motion. `@flighthq/
+// physics2d` orders every pair by body index before it calls.
+//
+// Area-less kinds (`segment`, `point`) and unknown kinds carry no contact — the pair is reported as
+// non-overlapping. The direct per-pair functions remain the hot path.
+export function collideContactManifold(a, b, out) {
+    const rankA = contactShapeKindRank(a.kind);
+    const rankB = contactShapeKindRank(b.kind);
+    if (rankA < 0 || rankB < 0) {
+        clearCollisionContactManifold(out);
+        return false;
+    }
+    const swapped = rankA > rankB;
+    const lo = swapped ? b : a;
+    const hi = swapped ? a : b;
+    let overlapping = false;
+    switch (lo.kind) {
+        case 'circle':
+            switch (hi.kind) {
+                case 'circle':
+                    overlapping = collideCircleCircleContactManifold(lo, hi, out);
+                    break;
+                case 'aabb':
+                    overlapping = collideCircleAabbContactManifold(lo, hi, out);
+                    break;
+                case 'obb':
+                    overlapping = collideCircleObbContactManifold(lo, hi, out);
+                    break;
+                case 'polygon':
+                    overlapping = collideCirclePolygonContactManifold(lo, hi, out);
+                    break;
+            }
+            break;
+        case 'aabb':
+            switch (hi.kind) {
+                case 'aabb':
+                    overlapping = collideAabbAabbContactManifold(lo, hi, out);
+                    break;
+                case 'obb':
+                    overlapping = collideAabbObbContactManifold(lo, hi, out);
+                    break;
+                case 'polygon':
+                    overlapping = collideAabbPolygonContactManifold(lo, hi, out);
+                    break;
+            }
+            break;
+        case 'obb':
+            switch (hi.kind) {
+                case 'obb':
+                    overlapping = collideObbObbContactManifold(lo, hi, out);
+                    break;
+                case 'polygon':
+                    overlapping = collideObbPolygonContactManifold(lo, hi, out);
+                    break;
+            }
+            break;
+        case 'polygon':
+            if (hi.kind === 'polygon') {
+                overlapping = collidePolygonPolygonContactManifold(lo, hi, out);
+            }
+            break;
+    }
+    if (overlapping && swapped) {
+        out.normalX = -out.normalX;
+        out.normalY = -out.normalY;
+    }
+    return overlapping;
+}
+// Canonical dispatch rank of a shape kind, or -1 for kinds that carry no contact (segment, point,
+// and any custom kind). Ordering the pair by rank collapses the 4x4 kind matrix to its ten lower-
+// triangular contact pairs.
+function contactShapeKindRank(kind) {
+    switch (kind) {
+        case 'circle':
+            return 0;
+        case 'aabb':
+            return 1;
+        case 'obb':
+            return 2;
+        case 'polygon':
+            return 3;
+        default:
+            return -1;
+    }
+}
+//# sourceMappingURL=collideContactManifold.js.map

package/dist/collideContactManifold.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collideContactManifold.js","sourceRoot":"","sources":["../src/collideContactManifold.ts"],"names":[],"mappings":"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"}

package/dist/collisionShapeValidation.d.ts

@@ -0,0 +1,4 @@
+import type { CollisionShape, CollisionTestStatus } from '@flighthq/types/contract';
+export declare function getCollisionPolygonValidationStatus(points: readonly number[]): CollisionTestStatus | null;
+export declare function getCollisionShapeValidationStatus(shape: Readonly<CollisionShape>): CollisionTestStatus | null;
+//# sourceMappingURL=collisionShapeValidation.d.ts.map

package/dist/collisionShapeValidation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collisionShapeValidation.d.ts","sourceRoot":"","sources":["../src/collisionShapeValidation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAIpF,wBAAgB,mCAAmC,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,mBAAmB,GAAG,IAAI,CA2CzG;AAID,wBAAgB,iCAAiC,CAAC,KAAK,EAAE,QAAQ,CAAC,cAAc,CAAC,GAAG,mBAAmB,GAAG,IAAI,CAwC7G"}

package/dist/collisionShapeValidation.js

@@ -0,0 +1,99 @@
+// Validates the flat polygon contract and distinguishes zero-area/malformed input from a real but
+// non-convex polygon. Winding and collinear vertices are accepted when the polygon still has area.
+export function getCollisionPolygonValidationStatus(points) {
+    if (points.length < 6 || (points.length & 1) !== 0)
+        return 'degenerate-shape';
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    for (let i = 0; i < points.length; i += 2) {
+        const x = points[i];
+        const y = points[i + 1];
+        if (!Number.isFinite(x) || !Number.isFinite(y))
+            return 'degenerate-shape';
+        if (x < minX)
+            minX = x;
+        if (x > maxX)
+            maxX = x;
+        if (y < minY)
+            minY = y;
+        if (y > maxY)
+            maxY = y;
+    }
+    const extent = Math.max(maxX - minX, maxY - minY);
+    if (!(extent > 0))
+        return 'degenerate-shape';
+    const crossEpsilon = extent * extent * RELATIVE_EPSILON;
+    const xOrigin = points[0];
+    const yOrigin = points[1];
+    let areaTwice = 0;
+    let turnSign = 0;
+    const count = points.length >> 1;
+    for (let i = 0; i < count; i++) {
+        const previous = (i + count - 1) % count;
+        const next = (i + 1) % count;
+        const x = points[i << 1] - xOrigin;
+        const y = points[(i << 1) + 1] - yOrigin;
+        const nextX = points[next << 1] - xOrigin;
+        const nextY = points[(next << 1) + 1] - yOrigin;
+        areaTwice += x * nextY - y * nextX;
+        const ax = x - (points[previous << 1] - xOrigin);
+        const ay = y - (points[(previous << 1) + 1] - yOrigin);
+        const bx = nextX - x;
+        const by = nextY - y;
+        const cross = ax * by - ay * bx;
+        if (Math.abs(cross) <= crossEpsilon)
+            continue;
+        const sign = cross > 0 ? 1 : -1;
+        if (turnSign !== 0 && sign !== turnSign)
+            return 'non-convex-polygon';
+        turnSign = sign;
+    }
+    return Math.abs(areaTwice) <= crossEpsilon || turnSign === 0 ? 'degenerate-shape' : null;
+}
+// Returns the invalid/unsupported status that prevents a shape from participating in a manifold,
+// or null when it is a finite, positive-area member of the supported manifold shape set.
+export function getCollisionShapeValidationStatus(shape) {
+    switch (shape.kind) {
+        case 'circle':
+            return Number.isFinite(shape.x) && Number.isFinite(shape.y) && Number.isFinite(shape.radius) && shape.radius > 0
+                ? null
+                : 'degenerate-shape';
+        case 'aabb':
+            return Number.isFinite(shape.minX) &&
+                Number.isFinite(shape.minY) &&
+                Number.isFinite(shape.maxX) &&
+                Number.isFinite(shape.maxY) &&
+                shape.maxX > shape.minX &&
+                shape.maxY > shape.minY
+                ? null
+                : 'degenerate-shape';
+        case 'obb':
+            return Number.isFinite(shape.x) &&
+                Number.isFinite(shape.y) &&
+                Number.isFinite(shape.halfW) &&
+                Number.isFinite(shape.halfH) &&
+                Number.isFinite(shape.rotation) &&
+                shape.halfW > 0 &&
+                shape.halfH > 0
+                ? null
+                : 'degenerate-shape';
+        case 'polygon':
+            return getCollisionPolygonValidationStatus(shape.points);
+        case 'segment':
+            return Number.isFinite(shape.x0) &&
+                Number.isFinite(shape.y0) &&
+                Number.isFinite(shape.x1) &&
+                Number.isFinite(shape.y1) &&
+                (shape.x0 !== shape.x1 || shape.y0 !== shape.y1)
+                ? 'unsupported-shape-kind'
+                : 'degenerate-shape';
+        case 'point':
+            return Number.isFinite(shape.x) && Number.isFinite(shape.y) ? 'unsupported-shape-kind' : 'degenerate-shape';
+        default:
+            return 'unsupported-shape-kind';
+    }
+}
+const RELATIVE_EPSILON = 1e-12;
+//# sourceMappingURL=collisionShapeValidation.js.map

package/dist/collisionShapeValidation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collisionShapeValidation.js","sourceRoot":"","sources":["../src/collisionShapeValidation.ts"],"names":[],"mappings":"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"}

package/dist/contactFeatureId.d.ts

@@ -0,0 +1,3 @@
+export declare const FEATURE_INDEX_LIMIT: number;
+export declare function packContactFeatureId(referenceIsA: boolean, referenceEdge: number, incidentEdge: number, secondPoint: boolean): number;
+//# sourceMappingURL=contactFeatureId.d.ts.map

package/dist/contactFeatureId.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contactFeatureId.d.ts","sourceRoot":"","sources":["../src/contactFeatureId.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,mBAAmB,QAAU,CAAC;AAY3C,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,OAAO,EACrB,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,OAAO,GACnB,MAAM,CAOR"}

package/dist/contactFeatureId.js

@@ -0,0 +1,26 @@
+// Contact feature identity: the packing that lets a solver recognise, next frame, that it is looking
+// at the same contact and may reuse the impulse it converged on. Private to the package — the packed
+// value is opaque to callers, so only `CollisionContactPoint.featureId` crosses the boundary.
+// The largest vertex count whose face indices still pack without aliasing. Face indices take 25 bits
+// each, above a 1-bit contact-point slot and below the reference-shape bit. A convex polygon at this
+// bound carries 67 million coordinates.
+export const FEATURE_INDEX_LIMIT = 1 << 25;
+// Packs the four components that identify a contact feature — which shape owned the reference face,
+// which face of each shape met, and which end of the clipped span this point is — into one opaque
+// integer.
+//
+// Positional multiplication, not bit shifts. `<<` truncates to 32 bits, so a shift-packed id silently
+// WRAPS once a face index outgrows its field, and two unrelated face pairs collide on one id. That is
+// not a crash: it is a solver warm-starting a contact with an impulse belonging to somewhere else on
+// the shape, which surfaces as jitter that no stack trace explains. Here each field's scale exceeds
+// the largest value packed below it, so distinct components can never sum to the same id, and the
+// widest possible id is 2^52 - 1 — inside the exact-integer range, so no id is ever rounded.
+export function packContactFeatureId(referenceIsA, referenceEdge, incidentEdge, secondPoint) {
+    return ((referenceIsA ? FEATURE_REFERENCE_SCALE : 0) +
+        referenceEdge * FEATURE_EDGE_SCALE +
+        incidentEdge * 2 +
+        (secondPoint ? 1 : 0));
+}
+const FEATURE_EDGE_SCALE = FEATURE_INDEX_LIMIT * 2;
+const FEATURE_REFERENCE_SCALE = FEATURE_INDEX_LIMIT * FEATURE_EDGE_SCALE;
+//# sourceMappingURL=contactFeatureId.js.map

package/dist/contactFeatureId.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contactFeatureId.js","sourceRoot":"","sources":["../src/contactFeatureId.ts"],"names":[],"mappings":"AAAA,qGAAqG;AACrG,qGAAqG;AACrG,8FAA8F;AAE9F,qGAAqG;AACrG,qGAAqG;AACrG,wCAAwC;AACxC,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,IAAI,EAAE,CAAC;AAE3C,oGAAoG;AACpG,kGAAkG;AAClG,WAAW;AACX,EAAE;AACF,sGAAsG;AACtG,sGAAsG;AACtG,qGAAqG;AACrG,oGAAoG;AACpG,kGAAkG;AAClG,6FAA6F;AAC7F,MAAM,UAAU,oBAAoB,CAClC,YAAqB,EACrB,aAAqB,EACrB,YAAoB,EACpB,WAAoB;IAEpB,OAAO,CACL,CAAC,YAAY,CAAC,CAAC,CAAC,uBAAuB,CAAC,CAAC,CAAC,CAAC,CAAC;QAC5C,aAAa,GAAG,kBAAkB;QAClC,YAAY,GAAG,CAAC;QAChB,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CACtB,CAAC;AACJ,CAAC;AAED,MAAM,kBAAkB,GAAG,mBAAmB,GAAG,CAAC,CAAC;AACnD,MAAM,uBAAuB,GAAG,mBAAmB,GAAG,kBAAkB,CAAC"}

package/dist/contactManifold.d.ts

@@ -0,0 +1,4 @@
+import type { CollisionContactManifold } from '@flighthq/types/contract';
+export declare function clearCollisionContactManifold(out: CollisionContactManifold): void;
+export declare function createCollisionContactManifold(): CollisionContactManifold;
+//# sourceMappingURL=contactManifold.d.ts.map

package/dist/contactManifold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contactManifold.d.ts","sourceRoot":"","sources":["../src/contactManifold.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAyB,MAAM,0BAA0B,CAAC;AAUhG,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,wBAAwB,GAAG,IAAI,CAMjF;AAID,wBAAgB,8BAA8B,IAAI,wBAAwB,CASzE"}

package/dist/contactManifold.js

@@ -0,0 +1,30 @@
+// Lifecycle for the contact manifold the `collide*ContactManifold` functions write. The two contact
+// points are allocated once, here, and reused for the manifold's whole life — a solver's per-frame
+// narrow-phase loop over thousands of pairs allocates nothing.
+// Clears a manifold to the non-overlapping state: `overlapping` false, normal, depth, and point
+// count zero. The contact-point entries themselves are left untouched — `pointCount` alone bounds
+// what is readable, so clearing does not need to walk them and a stale point can never be read
+// through the documented contract.
+export function clearCollisionContactManifold(out) {
+    out.overlapping = false;
+    out.normalX = 0;
+    out.normalY = 0;
+    out.depth = 0;
+    out.pointCount = 0;
+}
+// Allocates a fresh contact manifold in the non-overlapping state, with its fixed two-point array
+// already populated, ready to be passed as an `out` parameter.
+export function createCollisionContactManifold() {
+    return {
+        overlapping: false,
+        normalX: 0,
+        normalY: 0,
+        depth: 0,
+        pointCount: 0,
+        points: [createContactPoint(), createContactPoint()],
+    };
+}
+function createContactPoint() {
+    return { x: 0, y: 0, depth: 0, featureId: 0 };
+}
+//# sourceMappingURL=contactManifold.js.map

package/dist/contactManifold.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contactManifold.js","sourceRoot":"","sources":["../src/contactManifold.ts"],"names":[],"mappings":"AAEA,oGAAoG;AACpG,mGAAmG;AACnG,+DAA+D;AAE/D,gGAAgG;AAChG,kGAAkG;AAClG,+FAA+F;AAC/F,mCAAmC;AACnC,MAAM,UAAU,6BAA6B,CAAC,GAA6B;IACzE,GAAG,CAAC,WAAW,GAAG,KAAK,CAAC;IACxB,GAAG,CAAC,OAAO,GAAG,CAAC,CAAC;IAChB,GAAG,CAAC,OAAO,GAAG,CAAC,CAAC;IAChB,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC;IACd,GAAG,CAAC,UAAU,GAAG,CAAC,CAAC;AACrB,CAAC;AAED,kGAAkG;AAClG,+DAA+D;AAC/D,MAAM,UAAU,8BAA8B;IAC5C,OAAO;QACL,WAAW,EAAE,KAAK;QAClB,OAAO,EAAE,CAAC;QACV,OAAO,EAAE,CAAC;QACV,KAAK,EAAE,CAAC;QACR,UAAU,EAAE,CAAC;QACb,MAAM,EAAE,CAAC,kBAAkB,EAAE,EAAE,kBAAkB,EAAE,CAAC;KACrD,CAAC;AACJ,CAAC;AAED,SAAS,kBAAkB;IACzB,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC;AAChD,CAAC"}

package/dist/contract.d.ts

@@ -1,6 +1,13 @@
+export * from './collideContactManifold';
+export * from './contactManifold';
+export * from './enableCollisionGuards';
+export * from './explainCollisionTest';
 export * from './manifold';
 export * from './pointContainment';
+export * from './raycastCollisionShape';
 export * from './segmentCollision';
 export * from './shapeCollision';
+export * from './shapeContact';
+export * from './sweepCollisionShape';
 export * from './testCollision';
 //# sourceMappingURL=contract.d.ts.map

package/dist/contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,mBAAmB,CAAC;AAClC,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,uBAAuB,CAAC;AACtC,cAAc,iBAAiB,CAAC"}

package/dist/contract.js

@@ -1,6 +1,13 @@
+export * from './collideContactManifold';
+export * from './contactManifold';
+export * from './enableCollisionGuards';
+export * from './explainCollisionTest';
 export * from './manifold';
 export * from './pointContainment';
+export * from './raycastCollisionShape';
 export * from './segmentCollision';
 export * from './shapeCollision';
+export * from './shapeContact';
+export * from './sweepCollisionShape';
 export * from './testCollision';
 //# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -1 +1 @@
-{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,mBAAmB,CAAC;AAClC,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,uBAAuB,CAAC;AACtC,cAAc,iBAAiB,CAAC"}

package/dist/convexVertices.d.ts

@@ -0,0 +1,4 @@
+import type { CollisionAabb, CollisionObb } from '@flighthq/types/contract';
+export declare function writeAabbVertices(aabb: Readonly<CollisionAabb>, out: Float64Array): void;
+export declare function writeObbVertices(obb: Readonly<CollisionObb>, out: Float64Array): void;
+//# sourceMappingURL=convexVertices.d.ts.map

package/dist/convexVertices.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convexVertices.d.ts","sourceRoot":"","sources":["../src/convexVertices.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAQ5E,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,QAAQ,CAAC,aAAa,CAAC,EAAE,GAAG,EAAE,YAAY,GAAG,IAAI,CAaxF;AAGD,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,QAAQ,CAAC,YAAY,CAAC,EAAE,GAAG,EAAE,YAAY,GAAG,IAAI,CAmBrF"}

package/dist/convexVertices.js

@@ -0,0 +1,41 @@
+// Materializes a box collider as the flat `[x0,y0,...]` vertex list the convex cores consume, so
+// AABB, OBB, and polygon all reduce to one representation. Package-internal: these are a detail of
+// how the SAT and contact-clipping cores read boxes, not part of the collision API. Both writers
+// emit their four corners in consistent winding, which the cores rely on to walk edges in order.
+// Writes the four corners of an axis-aligned box into `out` as a flat `[x0,y0,...]` list.
+export function writeAabbVertices(aabb, out) {
+    const minX = aabb.minX;
+    const minY = aabb.minY;
+    const maxX = aabb.maxX;
+    const maxY = aabb.maxY;
+    out[0] = minX;
+    out[1] = minY;
+    out[2] = maxX;
+    out[3] = minY;
+    out[4] = maxX;
+    out[5] = maxY;
+    out[6] = minX;
+    out[7] = maxY;
+}
+// Writes the four world-space corners of an oriented box into `out` as a flat `[x0,y0,...]` list.
+export function writeObbVertices(obb, out) {
+    const cx = obb.x;
+    const cy = obb.y;
+    const halfW = obb.halfW;
+    const halfH = obb.halfH;
+    const cos = Math.cos(obb.rotation);
+    const sin = Math.sin(obb.rotation);
+    const wx = cos * halfW;
+    const wy = sin * halfW;
+    const hx = -sin * halfH;
+    const hy = cos * halfH;
+    out[0] = cx - wx - hx;
+    out[1] = cy - wy - hy;
+    out[2] = cx + wx - hx;
+    out[3] = cy + wy - hy;
+    out[4] = cx + wx + hx;
+    out[5] = cy + wy + hy;
+    out[6] = cx - wx + hx;
+    out[7] = cy - wy + hy;
+}
+//# sourceMappingURL=convexVertices.js.map

package/dist/convexVertices.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"convexVertices.js","sourceRoot":"","sources":["../src/convexVertices.ts"],"names":[],"mappings":"AAEA,iGAAiG;AACjG,mGAAmG;AACnG,iGAAiG;AACjG,iGAAiG;AAEjG,0FAA0F;AAC1F,MAAM,UAAU,iBAAiB,CAAC,IAA6B,EAAE,GAAiB;IAChF,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;IACvB,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;IACvB,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;IACvB,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;IACvB,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IACd,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IACd,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IACd,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IACd,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IACd,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IACd,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IACd,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;AAChB,CAAC;AAED,kGAAkG;AAClG,MAAM,UAAU,gBAAgB,CAAC,GAA2B,EAAE,GAAiB;IAC7E,MAAM,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC;IACjB,MAAM,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC;IACjB,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC;IACxB,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC;IACxB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACnC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACnC,MAAM,EAAE,GAAG,GAAG,GAAG,KAAK,CAAC;IACvB,MAAM,EAAE,GAAG,GAAG,GAAG,KAAK,CAAC;IACvB,MAAM,EAAE,GAAG,CAAC,GAAG,GAAG,KAAK,CAAC;IACxB,MAAM,EAAE,GAAG,GAAG,GAAG,KAAK,CAAC;IACvB,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;IACtB,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;IACtB,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;IACtB,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;IACtB,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;IACtB,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;IACtB,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;IACtB,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;AACxB,CAAC"}

package/dist/enableCollisionGuards.d.ts

@@ -0,0 +1,4 @@
+export declare function areCollisionGuardsEnabled(): boolean;
+export declare function disableCollisionGuards(): void;
+export declare function enableCollisionGuards(): void;
+//# sourceMappingURL=enableCollisionGuards.d.ts.map

package/dist/enableCollisionGuards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enableCollisionGuards.d.ts","sourceRoot":"","sources":["../src/enableCollisionGuards.ts"],"names":[],"mappings":"AAOA,wBAAgB,yBAAyB,IAAI,OAAO,CAEnD;AAED,wBAAgB,sBAAsB,IAAI,IAAI,CAG7C;AAID,wBAAgB,qBAAqB,IAAI,IAAI,CAG5C"}

package/dist/enableCollisionGuards.js

@@ -0,0 +1,41 @@
+import { logOnce } from '@flighthq/log/contract';
+import { LogLevel } from '@flighthq/types/contract';
+import { getCollisionShapeValidationStatus } from './collisionShapeValidation';
+import { setCollisionTestGuard } from './testCollision';
+export function areCollisionGuardsEnabled() {
+    return collisionGuardsEnabled;
+}
+export function disableCollisionGuards() {
+    setCollisionTestGuard(null);
+    collisionGuardsEnabled = false;
+}
+// Installs opt-in diagnostics for invalid generic manifold inputs. Direct typed pair functions stay
+// logger-free, and applications that omit this module shed both the message text and @flighthq/log.
+export function enableCollisionGuards() {
+    setCollisionTestGuard(warnOnInvalidCollisionShapes);
+    collisionGuardsEnabled = true;
+}
+function warnOnInvalidCollisionShapes(a, b) {
+    const statusA = getCollisionShapeValidationStatus(a);
+    if (statusA === 'degenerate-shape' || statusA === 'non-convex-polygon') {
+        warnOnInvalidCollisionShape({ kind: a.kind, overlapping: false, shapeIndex: 0, status: statusA });
+        return;
+    }
+    const statusB = getCollisionShapeValidationStatus(b);
+    if (statusB === 'degenerate-shape' || statusB === 'non-convex-polygon') {
+        warnOnInvalidCollisionShape({ kind: b.kind, overlapping: false, shapeIndex: 1, status: statusB });
+    }
+}
+function warnOnInvalidCollisionShape(explanation) {
+    const message = explanation.status === 'non-convex-polygon'
+        ? 'testCollision: a polygon is non-convex and cannot produce a supported manifold — call explainCollisionTest(a, b) and replace the reported shape with a convex polygon.'
+        : 'testCollision: a shape is degenerate and cannot produce a manifold — call explainCollisionTest(a, b) and replace the reported shape with a finite positive-area collider.';
+    logOnce(`collision:${explanation.status}:${explanation.shapeIndex}:${explanation.kind}`, LogLevel.Warn, {
+        kind: explanation.kind,
+        message,
+        shapeIndex: explanation.shapeIndex,
+        status: explanation.status,
+    }, 'collision');
+}
+let collisionGuardsEnabled = false;
+//# sourceMappingURL=enableCollisionGuards.js.map

package/dist/enableCollisionGuards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"enableCollisionGuards.js","sourceRoot":"","sources":["../src/enableCollisionGuards.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAEjD,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAEpD,OAAO,EAAE,iCAAiC,EAAE,MAAM,4BAA4B,CAAC;AAC/E,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAExD,MAAM,UAAU,yBAAyB;IACvC,OAAO,sBAAsB,CAAC;AAChC,CAAC;AAED,MAAM,UAAU,sBAAsB;IACpC,qBAAqB,CAAC,IAAI,CAAC,CAAC;IAC5B,sBAAsB,GAAG,KAAK,CAAC;AACjC,CAAC;AAED,oGAAoG;AACpG,oGAAoG;AACpG,MAAM,UAAU,qBAAqB;IACnC,qBAAqB,CAAC,4BAA4B,CAAC,CAAC;IACpD,sBAAsB,GAAG,IAAI,CAAC;AAChC,CAAC;AAED,SAAS,4BAA4B,CAAC,CAA2B,EAAE,CAA2B;IAC5F,MAAM,OAAO,GAAG,iCAAiC,CAAC,CAAC,CAAC,CAAC;IACrD,IAAI,OAAO,KAAK,kBAAkB,IAAI,OAAO,KAAK,oBAAoB,EAAE,CAAC;QACvE,2BAA2B,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;QAClG,OAAO;IACT,CAAC;IACD,MAAM,OAAO,GAAG,iCAAiC,CAAC,CAAC,CAAC,CAAC;IACrD,IAAI,OAAO,KAAK,kBAAkB,IAAI,OAAO,KAAK,oBAAoB,EAAE,CAAC;QACvE,2BAA2B,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;IACpG,CAAC;AACH,CAAC;AAED,SAAS,2BAA2B,CAAC,WAA+C;IAClF,MAAM,OAAO,GACX,WAAW,CAAC,MAAM,KAAK,oBAAoB;QACzC,CAAC,CAAC,wKAAwK;QAC1K,CAAC,CAAC,2KAA2K,CAAC;IAClL,OAAO,CACL,aAAa,WAAW,CAAC,MAAM,IAAI,WAAW,CAAC,UAAU,IAAI,WAAW,CAAC,IAAI,EAAE,EAC/E,QAAQ,CAAC,IAAI,EACb;QACE,IAAI,EAAE,WAAW,CAAC,IAAI;QACtB,OAAO;QACP,UAAU,EAAE,WAAW,CAAC,UAAU;QAClC,MAAM,EAAE,WAAW,CAAC,MAAM;KAC3B,EACD,WAAW,CACZ,CAAC;AACJ,CAAC;AAED,IAAI,sBAAsB,GAAG,KAAK,CAAC"}

package/dist/explainCollisionTest.d.ts

@@ -0,0 +1,3 @@
+import type { CollisionShape, CollisionTestExplanation } from '@flighthq/types/contract';
+export declare function explainCollisionTest(a: Readonly<CollisionShape>, b: Readonly<CollisionShape>): CollisionTestExplanation;
+//# sourceMappingURL=explainCollisionTest.d.ts.map

package/dist/explainCollisionTest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explainCollisionTest.d.ts","sourceRoot":"","sources":["../src/explainCollisionTest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AAQzF,wBAAgB,oBAAoB,CAClC,CAAC,EAAE,QAAQ,CAAC,cAAc,CAAC,EAC3B,CAAC,EAAE,QAAQ,CAAC,cAAc,CAAC,GAC1B,wBAAwB,CAY1B"}

package/dist/explainCollisionTest.js

@@ -0,0 +1,21 @@
+import { getCollisionShapeValidationStatus } from './collisionShapeValidation';
+import { testCollision } from './testCollision';
+// Pure diagnostic twin of testCollision. It classifies invalid and unsupported inputs before
+// running the ordinary dispatcher, so callers can distinguish its silent false sentinel from a
+// legitimate separated pair without retaining state or enabling guards.
+export function explainCollisionTest(a, b) {
+    const statusA = getCollisionShapeValidationStatus(a);
+    if (statusA !== null)
+        return { kind: a.kind, overlapping: false, shapeIndex: 0, status: statusA };
+    const statusB = getCollisionShapeValidationStatus(b);
+    if (statusB !== null)
+        return { kind: b.kind, overlapping: false, shapeIndex: 1, status: statusB };
+    const overlapping = testCollision(a, b, { depth: 0, normalX: 0, normalY: 0, overlapping: false });
+    return {
+        kind: null,
+        overlapping,
+        shapeIndex: null,
+        status: overlapping ? 'overlapping' : 'separated',
+    };
+}
+//# sourceMappingURL=explainCollisionTest.js.map

package/dist/explainCollisionTest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explainCollisionTest.js","sourceRoot":"","sources":["../src/explainCollisionTest.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iCAAiC,EAAE,MAAM,4BAA4B,CAAC;AAC/E,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD,6FAA6F;AAC7F,+FAA+F;AAC/F,wEAAwE;AACxE,MAAM,UAAU,oBAAoB,CAClC,CAA2B,EAC3B,CAA2B;IAE3B,MAAM,OAAO,GAAG,iCAAiC,CAAC,CAAC,CAAC,CAAC;IACrD,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;IAClG,MAAM,OAAO,GAAG,iCAAiC,CAAC,CAAC,CAAC,CAAC;IACrD,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;IAClG,MAAM,WAAW,GAAG,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,CAAC;IAClG,OAAO;QACL,IAAI,EAAE,IAAI;QACV,WAAW;QACX,UAAU,EAAE,IAAI;QAChB,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,WAAW;KAClD,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { clearCollisionManifold, createCollisionManifold, getCollisionShapeContainsPoint, testAabbAabbCollision, testAabbObbCollision, testAabbPolygonCollision, testCircleAabbCollision, testCircleCircleCollision, testCircleObbCollision, testCirclePolygonCollision, testCollision, testObbObbCollision, testObbPolygonCollision, testPolygonPolygonCollision, testSegmentAabbCollision, testSegmentCircleCollision, testSegmentObbCollision, testSegmentPolygonCollision, testSegmentSegmentCollision, } from './contract';
+export { clearCollisionContactManifold, clearCollisionManifold, collideAabbAabbContactManifold, collideAabbObbContactManifold, collideAabbPolygonContactManifold, collideCircleAabbContactManifold, collideCircleCircleContactManifold, collideCircleObbContactManifold, collideCirclePolygonContactManifold, collideContactManifold, collideObbObbContactManifold, collideObbPolygonContactManifold, collidePolygonPolygonContactManifold, createCollisionContactManifold, createCollisionManifold, areCollisionGuardsEnabled, disableCollisionGuards, enableCollisionGuards, explainCollisionTest, getCollisionShapeContainsPoint, createCollisionRaycastHit, createCollisionTimeOfImpact, raycastCollisionShape, sweepCollisionShape, testAabbAabbCollision, testAabbObbCollision, testAabbPolygonCollision, testCircleAabbCollision, testCircleCircleCollision, testCircleObbCollision, testCirclePolygonCollision, testCollision, testObbObbCollision, testObbPolygonCollision, testPolygonPolygonCollision, testSegmentAabbCollision, testSegmentCircleCollision, testSegmentObbCollision, testSegmentPolygonCollision, testSegmentSegmentCollision, } from './contract';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,uBAAuB,EACvB,8BAA8B,EAC9B,qBAAqB,EACrB,oBAAoB,EACpB,wBAAwB,EACxB,uBAAuB,EACvB,yBAAyB,EACzB,sBAAsB,EACtB,0BAA0B,EAC1B,aAAa,EACb,mBAAmB,EACnB,uBAAuB,EACvB,2BAA2B,EAC3B,wBAAwB,EACxB,0BAA0B,EAC1B,uBAAuB,EACvB,2BAA2B,EAC3B,2BAA2B,GAC5B,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,6BAA6B,EAC7B,sBAAsB,EACtB,8BAA8B,EAC9B,6BAA6B,EAC7B,iCAAiC,EACjC,gCAAgC,EAChC,kCAAkC,EAClC,+BAA+B,EAC/B,mCAAmC,EACnC,sBAAsB,EACtB,4BAA4B,EAC5B,gCAAgC,EAChC,oCAAoC,EACpC,8BAA8B,EAC9B,uBAAuB,EACvB,yBAAyB,EACzB,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,EACpB,8BAA8B,EAC9B,yBAAyB,EACzB,2BAA2B,EAC3B,qBAAqB,EACrB,mBAAmB,EACnB,qBAAqB,EACrB,oBAAoB,EACpB,wBAAwB,EACxB,uBAAuB,EACvB,yBAAyB,EACzB,sBAAsB,EACtB,0BAA0B,EAC1B,aAAa,EACb,mBAAmB,EACnB,uBAAuB,EACvB,2BAA2B,EAC3B,wBAAwB,EACxB,0BAA0B,EAC1B,uBAAuB,EACvB,2BAA2B,EAC3B,2BAA2B,GAC5B,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,2 +1,2 @@
-export { clearCollisionManifold, createCollisionManifold, getCollisionShapeContainsPoint, testAabbAabbCollision, testAabbObbCollision, testAabbPolygonCollision, testCircleAabbCollision, testCircleCircleCollision, testCircleObbCollision, testCirclePolygonCollision, testCollision, testObbObbCollision, testObbPolygonCollision, testPolygonPolygonCollision, testSegmentAabbCollision, testSegmentCircleCollision, testSegmentObbCollision, testSegmentPolygonCollision, testSegmentSegmentCollision, } from './contract';
+export { clearCollisionContactManifold, clearCollisionManifold, collideAabbAabbContactManifold, collideAabbObbContactManifold, collideAabbPolygonContactManifold, collideCircleAabbContactManifold, collideCircleCircleContactManifold, collideCircleObbContactManifold, collideCirclePolygonContactManifold, collideContactManifold, collideObbObbContactManifold, collideObbPolygonContactManifold, collidePolygonPolygonContactManifold, createCollisionContactManifold, createCollisionManifold, areCollisionGuardsEnabled, disableCollisionGuards, enableCollisionGuards, explainCollisionTest, getCollisionShapeContainsPoint, createCollisionRaycastHit, createCollisionTimeOfImpact, raycastCollisionShape, sweepCollisionShape, testAabbAabbCollision, testAabbObbCollision, testAabbPolygonCollision, testCircleAabbCollision, testCircleCircleCollision, testCircleObbCollision, testCirclePolygonCollision, testCollision, testObbObbCollision, testObbPolygonCollision, testPolygonPolygonCollision, testSegmentAabbCollision, testSegmentCircleCollision, testSegmentObbCollision, testSegmentPolygonCollision, testSegmentSegmentCollision, } from './contract';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,uBAAuB,EACvB,8BAA8B,EAC9B,qBAAqB,EACrB,oBAAoB,EACpB,wBAAwB,EACxB,uBAAuB,EACvB,yBAAyB,EACzB,sBAAsB,EACtB,0BAA0B,EAC1B,aAAa,EACb,mBAAmB,EACnB,uBAAuB,EACvB,2BAA2B,EAC3B,wBAAwB,EACxB,0BAA0B,EAC1B,uBAAuB,EACvB,2BAA2B,EAC3B,2BAA2B,GAC5B,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,6BAA6B,EAC7B,sBAAsB,EACtB,8BAA8B,EAC9B,6BAA6B,EAC7B,iCAAiC,EACjC,gCAAgC,EAChC,kCAAkC,EAClC,+BAA+B,EAC/B,mCAAmC,EACnC,sBAAsB,EACtB,4BAA4B,EAC5B,gCAAgC,EAChC,oCAAoC,EACpC,8BAA8B,EAC9B,uBAAuB,EACvB,yBAAyB,EACzB,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,EACpB,8BAA8B,EAC9B,yBAAyB,EACzB,2BAA2B,EAC3B,qBAAqB,EACrB,mBAAmB,EACnB,qBAAqB,EACrB,oBAAoB,EACpB,wBAAwB,EACxB,uBAAuB,EACvB,yBAAyB,EACzB,sBAAsB,EACtB,0BAA0B,EAC1B,aAAa,EACb,mBAAmB,EACnB,uBAAuB,EACvB,2BAA2B,EAC3B,wBAAwB,EACxB,0BAA0B,EAC1B,uBAAuB,EACvB,2BAA2B,EAC3B,2BAA2B,GAC5B,MAAM,YAAY,CAAC"}

package/dist/pointContainment.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pointContainment.d.ts","sourceRoot":"","sources":["../src/pointContainment.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAQ/D,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CA2C7G"}
+{"version":3,"file":"pointContainment.d.ts","sourceRoot":"","sources":["../src/pointContainment.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAU/D,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CA8C7G"}