@pibbl/core 0.0.1

package/dist/features/physics/2d-geometry.d.ts

@@ -0,0 +1,216 @@
+import type { boundsOfShape2D, massProperties2D, transformShape2D } from "./lib/2d/shapes.js";
+import type { queryAabb2D, raycast2D } from "./2d.js";
+import type { raycastShape2D, shapeCastAgainstShape2D } from "./lib/2d/collision/casts.js";
+import type { PibblPhysicsCollisionEvent2D, PibblPhysicsQueryHit2D } from "./lib/2d/types.js";
+import type { PibblPhysicsContactInspection2D } from "./lib/2d/inspection-types.js";
+/**
+ * An x/y pair in the 2D physics coordinate system.
+ *
+ * @see {@link PibblPhysicsPose2D}
+ * @see {@link PibblPhysicsAabb2D}
+ * @see {@link PibblPhysicsRay2D}
+ */
+export type PibblPhysicsVector2 = readonly [x: number, y: number];
+/**
+ * Position and rotation in degrees for a 2D shape or body.
+ *
+ * @see {@link PibblPhysicsVector2}
+ * @see {@link PibblPhysicsTransform2D}
+ * @see {@link containsPoint2D}
+ */
+export interface PibblPhysicsPose2D {
+    /** Position of the geometry, source, or selected resize handle. See {@link PibblPhysicsVector2}. */
+    readonly position: PibblPhysicsVector2;
+    /** Rotation in degrees. See {@link PibblPhysicsPose2D}. */
+    readonly rotationDegrees: number;
+}
+/**
+ * A rigid 2D transform expressed as position and rotation in degrees.
+ *
+ * @see {@link PibblPhysicsPose2D}
+ * @see {@link transformShape2D}
+ */
+export type PibblPhysicsTransform2D = PibblPhysicsPose2D;
+/**
+ * Axis-aligned bounds expressed as minimum and maximum coordinates.
+ *
+ * @see {@link PibblPhysicsVector2}
+ * @see {@link boundsOfShape2D}
+ * @see {@link queryAabb2D}
+ */
+export interface PibblPhysicsAabb2D {
+    /** Lower bound of the coordinate or sampling interval. See {@link PibblPhysicsVector2}. */
+    readonly min: PibblPhysicsVector2;
+    /** Upper bound of the coordinate or sampling interval. See {@link PibblPhysicsVector2}. */
+    readonly max: PibblPhysicsVector2;
+}
+/**
+ * Origin, direction, and maximum travel distance of a 2D query ray.
+ *
+ * @see {@link PibblPhysicsVector2}
+ * @see {@link raycastShape2D}
+ * @see {@link raycast2D}
+ */
+export interface PibblPhysicsRay2D {
+    /** Origin of the transform or geometric query. See {@link PibblPhysicsVector2}. */
+    readonly origin: PibblPhysicsVector2;
+    /** Direction in which this operation proceeds. See {@link PibblPhysicsVector2}. */
+    readonly direction: PibblPhysicsVector2;
+    /** Maximum distance accepted by the query. See {@link PibblPhysicsRay2D}. */
+    readonly maxDistance: number;
+}
+declare const physicsShape2DBrand: unique symbol;
+/**
+ * An immutable branded shape created by the public 2D geometry constructors.
+ *
+ * @see {@link containsPoint2D}
+ * @see {@link distanceBetweenShapes2D}
+ * @see {@link overlapShapes2D}
+ */
+export interface PibblPhysicsShape2D {
+    readonly [physicsShape2DBrand]: true;
+}
+/**
+ * Area, centroid, mass, and rotational inertia derived from a shape and density.
+ *
+ * @see {@link PibblPhysicsVector2}
+ * @see {@link massProperties2D}
+ */
+export interface PibblPhysicsMassProperties2D {
+    /** Area enclosed by the shape. See {@link PibblPhysicsMassProperties2D}. */
+    readonly area: number;
+    /** Area-weighted center of the shape. See {@link PibblPhysicsVector2}. */
+    readonly centroid: PibblPhysicsVector2;
+    /** Mass used by the spring or physics calculation. See {@link PibblPhysicsMassProperties2D}. */
+    readonly mass: number;
+    /** Moment of inertia about the shape's center of mass. See {@link PibblPhysicsMassProperties2D}. */
+    readonly rotationalInertia: number;
+}
+/**
+ * Signed separation, witness points, and normal between two posed shapes.
+ *
+ * @see {@link PibblPhysicsVector2}
+ * @see {@link distanceBetweenShapes2D}
+ */
+export interface PibblPhysicsDistance2D {
+    /** Signed distance between the witness points. See {@link PibblPhysicsDistance2D}. */
+    readonly separation: number;
+    /** Witness point on the first shape. See {@link PibblPhysicsVector2}. */
+    readonly pointOnFirst: PibblPhysicsVector2;
+    /** Witness point on the second shape. See {@link PibblPhysicsVector2}. */
+    readonly pointOnSecond: PibblPhysicsVector2;
+    /** Direction from the second shape toward the first. */
+    readonly normal: PibblPhysicsVector2;
+}
+/**
+ * A pair of contact witness points and their signed separation.
+ *
+ * @see {@link PibblPhysicsVector2}
+ * @see {@link PibblPhysicsShapeContact2D}
+ * @see {@link PibblPhysicsCollisionEvent2D}
+ * @see {@link PibblPhysicsContactInspection2D}
+ */
+export interface PibblPhysicsContactPoint2D {
+    /** Witness point on the first shape. See {@link PibblPhysicsVector2}. */
+    readonly pointOnFirst: PibblPhysicsVector2;
+    /** Witness point on the second shape. See {@link PibblPhysicsVector2}. */
+    readonly pointOnSecond: PibblPhysicsVector2;
+    /** Signed distance between the witness points. See {@link PibblPhysicsContactPoint2D}. */
+    readonly separation: number;
+}
+/**
+ * Contact normal and witness-point pairs for two overlapping or touching shapes.
+ *
+ * @see {@link PibblPhysicsVector2}
+ * @see {@link PibblPhysicsContactPoint2D}
+ * @see {@link contactBetweenShapes2D}
+ */
+export interface PibblPhysicsShapeContact2D {
+    /** Direction from the second shape toward the first. */
+    readonly normal: PibblPhysicsVector2;
+    /**
+     * Points defining the geometry or reported by the contact query. See
+     * {@link PibblPhysicsContactPoint2D}.
+     */
+    readonly points: readonly PibblPhysicsContactPoint2D[];
+}
+/**
+ * Point, normal, distance, and time of impact returned by a geometry cast.
+ *
+ * @see {@link PibblPhysicsVector2}
+ * @see {@link raycastShape2D}
+ * @see {@link shapeCastAgainstShape2D}
+ * @see {@link PibblPhysicsQueryHit2D}
+ */
+export interface PibblPhysicsShapeHit2D {
+    /** A point in the operation's coordinate system. See {@link PibblPhysicsVector2}. */
+    readonly point: PibblPhysicsVector2;
+    /** Contact or surface normal returned by this query. See {@link PibblPhysicsVector2}. */
+    readonly normal: PibblPhysicsVector2;
+    /**
+     * Distance measured in this query or guide's coordinate system. See {@link PibblPhysicsShapeHit2D}
+     * .
+     */
+    readonly distance: number;
+    /** Position along the cast at which contact first occurs. See {@link PibblPhysicsShapeHit2D}. */
+    readonly timeOfImpact: number;
+}
+export { arcShape2D, boundsOfShape2D, boxShape2D, capsuleShape2D, chainShape2D, circleShape2D, ellipseShape2D, massProperties2D, polygonShape2D, roundedBoxShape2D, segmentShape2D, transformShape2D, wedgeShape2D, } from './lib/2d/shapes.js';
+export { raycastShape2D, shapeCastAgainstShape2D, } from './lib/2d/collision/casts.js';
+/**
+ * Tests whether a point lies within a posed shape without creating a physics world.
+ *
+ * @param shape - Shape to test. See {@link PibblPhysicsShape2D}.
+ * @param pose - Shape pose. See {@link PibblPhysicsPose2D}.
+ * @param point - Point in the same coordinate space as the posed shape. See
+ * {@link PibblPhysicsVector2} .
+ * @returns Whether the posed shape contains the point.
+ *
+ * @see {@link PibblPhysicsShape2D}
+ * @see {@link PibblPhysicsPose2D}
+ * @see {@link PibblPhysicsVector2}
+ */
+export declare function containsPoint2D(shape: PibblPhysicsShape2D, pose: PibblPhysicsPose2D, point: PibblPhysicsVector2): boolean;
+/**
+ * Computes signed separation and witness geometry between two posed shapes.
+ *
+ * @param first - First shape. See {@link PibblPhysicsShape2D}.
+ * @param firstPose - Pose of the first shape. See {@link PibblPhysicsPose2D}.
+ * @param second - Second shape. See {@link PibblPhysicsShape2D}.
+ * @param secondPose - Pose of the second shape. See {@link PibblPhysicsPose2D}.
+ * @returns Distance and closest-point information for the two posed shapes. See
+ * {@link PibblPhysicsDistance2D} .
+ *
+ * @see {@link PibblPhysicsShape2D}
+ * @see {@link PibblPhysicsPose2D}
+ * @see {@link PibblPhysicsDistance2D}
+ */
+export declare function distanceBetweenShapes2D(first: PibblPhysicsShape2D, firstPose: PibblPhysicsPose2D, second: PibblPhysicsShape2D, secondPose: PibblPhysicsPose2D): PibblPhysicsDistance2D;
+/**
+ * Tests whether two posed shapes overlap without creating a physics world.
+ *
+ * @param first - First shape. See {@link PibblPhysicsShape2D}.
+ * @param firstPose - Pose of the first shape. See {@link PibblPhysicsPose2D}.
+ * @param second - Second shape. See {@link PibblPhysicsShape2D}.
+ * @param secondPose - Pose of the second shape. See {@link PibblPhysicsPose2D}.
+ * @returns Whether the two posed shapes overlap.
+ *
+ * @see {@link PibblPhysicsShape2D}
+ * @see {@link PibblPhysicsPose2D}
+ */
+export declare function overlapShapes2D(first: PibblPhysicsShape2D, firstPose: PibblPhysicsPose2D, second: PibblPhysicsShape2D, secondPose: PibblPhysicsPose2D): boolean;
+/**
+ * Computes contact geometry for two posed shapes, or null when they do not contact.
+ *
+ * @param first - First shape. See {@link PibblPhysicsShape2D}.
+ * @param firstPose - Pose of the first shape. See {@link PibblPhysicsPose2D}.
+ * @param second - Second shape. See {@link PibblPhysicsShape2D}.
+ * @param secondPose - Pose of the second shape. See {@link PibblPhysicsPose2D}.
+ * @returns Contact information, or null when the shapes do not contact. See
+ * {@link PibblPhysicsShapeContact2D} .
+ *
+ * @see {@link PibblPhysicsShape2D}
+ * @see {@link PibblPhysicsPose2D}
+ * @see {@link PibblPhysicsShapeContact2D}
+ */
+export declare function contactBetweenShapes2D(first: PibblPhysicsShape2D, firstPose: PibblPhysicsPose2D, second: PibblPhysicsShape2D, secondPose: PibblPhysicsPose2D): PibblPhysicsShapeContact2D | null;

package/dist/features/physics/2d-geometry.js

@@ -0,0 +1,59 @@
+import {
+  arcShape2D,
+  boundsOfShape2D,
+  boxShape2D,
+  capsuleShape2D,
+  chainShape2D,
+  circleShape2D,
+  ellipseShape2D,
+  massProperties2D,
+  polygonShape2D,
+  roundedBoxShape2D,
+  segmentShape2D,
+  transformShape2D,
+  wedgeShape2D
+} from "./lib/2d/shapes.js";
+import {
+  contactBetweenPreparedShapes2D,
+  containsPointInShape2D,
+  distanceBetweenPreparedShapes2D,
+  overlapPreparedShapes2D
+} from "./lib/2d/collision/pairs.js";
+import {
+  raycastShape2D,
+  shapeCastAgainstShape2D
+} from "./lib/2d/collision/casts.js";
+function containsPoint2D(shape, pose, point) {
+  return containsPointInShape2D(shape, pose, point);
+}
+function distanceBetweenShapes2D(first, firstPose, second, secondPose) {
+  return distanceBetweenPreparedShapes2D(first, firstPose, second, secondPose);
+}
+function overlapShapes2D(first, firstPose, second, secondPose) {
+  return overlapPreparedShapes2D(first, firstPose, second, secondPose);
+}
+function contactBetweenShapes2D(first, firstPose, second, secondPose) {
+  return contactBetweenPreparedShapes2D(first, firstPose, second, secondPose);
+}
+export {
+  arcShape2D,
+  boundsOfShape2D,
+  boxShape2D,
+  capsuleShape2D,
+  chainShape2D,
+  circleShape2D,
+  contactBetweenShapes2D,
+  containsPoint2D,
+  distanceBetweenShapes2D,
+  ellipseShape2D,
+  massProperties2D,
+  overlapShapes2D,
+  polygonShape2D,
+  raycastShape2D,
+  roundedBoxShape2D,
+  segmentShape2D,
+  shapeCastAgainstShape2D,
+  transformShape2D,
+  wedgeShape2D
+};
+//# sourceMappingURL=2d-geometry.js.map

package/dist/features/physics/2d-geometry.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/features/physics/2d-geometry.ts"],
+  "sourcesContent": ["import type { boundsOfShape2D, massProperties2D, transformShape2D } from './lib/2d/shapes.js';\nimport type { queryAabb2D, raycast2D } from './2d.js';\nimport type { raycastShape2D, shapeCastAgainstShape2D } from './lib/2d/collision/casts.js';\nimport type { PibblPhysicsCollisionEvent2D, PibblPhysicsQueryHit2D } from './lib/2d/types.js';\nimport type { PibblPhysicsContactInspection2D } from './lib/2d/inspection-types.js';\n/**\n * An x/y pair in the 2D physics coordinate system.\n *\n * @see {@link PibblPhysicsPose2D}\n * @see {@link PibblPhysicsAabb2D}\n * @see {@link PibblPhysicsRay2D}\n */\nexport type PibblPhysicsVector2 = readonly [x: number, y: number];\n\n/**\n * Position and rotation in degrees for a 2D shape or body.\n *\n * @see {@link PibblPhysicsVector2}\n * @see {@link PibblPhysicsTransform2D}\n * @see {@link containsPoint2D}\n */\nexport interface PibblPhysicsPose2D {\n  /** Position of the geometry, source, or selected resize handle. See {@link PibblPhysicsVector2}. */\n  readonly position: PibblPhysicsVector2;\n  /** Rotation in degrees. See {@link PibblPhysicsPose2D}. */\n  readonly rotationDegrees: number;\n}\n\n/**\n * A rigid 2D transform expressed as position and rotation in degrees.\n *\n * @see {@link PibblPhysicsPose2D}\n * @see {@link transformShape2D}\n */\nexport type PibblPhysicsTransform2D = PibblPhysicsPose2D;\n\n/**\n * Axis-aligned bounds expressed as minimum and maximum coordinates.\n *\n * @see {@link PibblPhysicsVector2}\n * @see {@link boundsOfShape2D}\n * @see {@link queryAabb2D}\n */\nexport interface PibblPhysicsAabb2D {\n  /** Lower bound of the coordinate or sampling interval. See {@link PibblPhysicsVector2}. */\n  readonly min: PibblPhysicsVector2;\n  /** Upper bound of the coordinate or sampling interval. See {@link PibblPhysicsVector2}. */\n  readonly max: PibblPhysicsVector2;\n}\n\n/**\n * Origin, direction, and maximum travel distance of a 2D query ray.\n *\n * @see {@link PibblPhysicsVector2}\n * @see {@link raycastShape2D}\n * @see {@link raycast2D}\n */\nexport interface PibblPhysicsRay2D {\n  /** Origin of the transform or geometric query. See {@link PibblPhysicsVector2}. */\n  readonly origin: PibblPhysicsVector2;\n  /** Direction in which this operation proceeds. See {@link PibblPhysicsVector2}. */\n  readonly direction: PibblPhysicsVector2;\n  /** Maximum distance accepted by the query. See {@link PibblPhysicsRay2D}. */\n  readonly maxDistance: number;\n}\n\ndeclare const physicsShape2DBrand: unique symbol;\n/**\n * An immutable branded shape created by the public 2D geometry constructors.\n *\n * @see {@link containsPoint2D}\n * @see {@link distanceBetweenShapes2D}\n * @see {@link overlapShapes2D}\n */\nexport interface PibblPhysicsShape2D {\n  readonly [physicsShape2DBrand]: true;\n}\n\n/**\n * Area, centroid, mass, and rotational inertia derived from a shape and density.\n *\n * @see {@link PibblPhysicsVector2}\n * @see {@link massProperties2D}\n */\nexport interface PibblPhysicsMassProperties2D {\n  /** Area enclosed by the shape. See {@link PibblPhysicsMassProperties2D}. */\n  readonly area: number;\n  /** Area-weighted center of the shape. See {@link PibblPhysicsVector2}. */\n  readonly centroid: PibblPhysicsVector2;\n  /** Mass used by the spring or physics calculation. See {@link PibblPhysicsMassProperties2D}. */\n  readonly mass: number;\n  /** Moment of inertia about the shape's center of mass. See {@link PibblPhysicsMassProperties2D}. */\n  readonly rotationalInertia: number;\n}\n\n/**\n * Signed separation, witness points, and normal between two posed shapes.\n *\n * @see {@link PibblPhysicsVector2}\n * @see {@link distanceBetweenShapes2D}\n */\nexport interface PibblPhysicsDistance2D {\n  /** Signed distance between the witness points. See {@link PibblPhysicsDistance2D}. */\n  readonly separation: number;\n  /** Witness point on the first shape. See {@link PibblPhysicsVector2}. */\n  readonly pointOnFirst: PibblPhysicsVector2;\n  /** Witness point on the second shape. See {@link PibblPhysicsVector2}. */\n  readonly pointOnSecond: PibblPhysicsVector2;\n  /** Direction from the second shape toward the first. */\n  readonly normal: PibblPhysicsVector2;\n}\n\n/**\n * A pair of contact witness points and their signed separation.\n *\n * @see {@link PibblPhysicsVector2}\n * @see {@link PibblPhysicsShapeContact2D}\n * @see {@link PibblPhysicsCollisionEvent2D}\n * @see {@link PibblPhysicsContactInspection2D}\n */\nexport interface PibblPhysicsContactPoint2D {\n  /** Witness point on the first shape. See {@link PibblPhysicsVector2}. */\n  readonly pointOnFirst: PibblPhysicsVector2;\n  /** Witness point on the second shape. See {@link PibblPhysicsVector2}. */\n  readonly pointOnSecond: PibblPhysicsVector2;\n  /** Signed distance between the witness points. See {@link PibblPhysicsContactPoint2D}. */\n  readonly separation: number;\n}\n\n/**\n * Contact normal and witness-point pairs for two overlapping or touching shapes.\n *\n * @see {@link PibblPhysicsVector2}\n * @see {@link PibblPhysicsContactPoint2D}\n * @see {@link contactBetweenShapes2D}\n */\nexport interface PibblPhysicsShapeContact2D {\n  /** Direction from the second shape toward the first. */\n  readonly normal: PibblPhysicsVector2;\n  /**\n   * Points defining the geometry or reported by the contact query. See\n   * {@link PibblPhysicsContactPoint2D}.\n   */\n  readonly points: readonly PibblPhysicsContactPoint2D[];\n}\n\n/**\n * Point, normal, distance, and time of impact returned by a geometry cast.\n *\n * @see {@link PibblPhysicsVector2}\n * @see {@link raycastShape2D}\n * @see {@link shapeCastAgainstShape2D}\n * @see {@link PibblPhysicsQueryHit2D}\n */\nexport interface PibblPhysicsShapeHit2D {\n  /** A point in the operation's coordinate system. See {@link PibblPhysicsVector2}. */\n  readonly point: PibblPhysicsVector2;\n  /** Contact or surface normal returned by this query. See {@link PibblPhysicsVector2}. */\n  readonly normal: PibblPhysicsVector2;\n  /**\n   * Distance measured in this query or guide's coordinate system. See {@link PibblPhysicsShapeHit2D}\n   * .\n   */\n  readonly distance: number;\n  /** Position along the cast at which contact first occurs. See {@link PibblPhysicsShapeHit2D}. */\n  readonly timeOfImpact: number;\n}\n\nexport {\n  arcShape2D,\n  boundsOfShape2D,\n  boxShape2D,\n  capsuleShape2D,\n  chainShape2D,\n  circleShape2D,\n  ellipseShape2D,\n  massProperties2D,\n  polygonShape2D,\n  roundedBoxShape2D,\n  segmentShape2D,\n  transformShape2D,\n  wedgeShape2D,\n} from './lib/2d/shapes.js';\n\nimport {\n  contactBetweenPreparedShapes2D,\n  containsPointInShape2D,\n  distanceBetweenPreparedShapes2D,\n  overlapPreparedShapes2D,\n} from './lib/2d/collision/pairs.js';\nexport {\n  raycastShape2D,\n  shapeCastAgainstShape2D,\n} from './lib/2d/collision/casts.js';\n\n/**\n * Tests whether a point lies within a posed shape without creating a physics world.\n *\n * @param shape - Shape to test. See {@link PibblPhysicsShape2D}.\n * @param pose - Shape pose. See {@link PibblPhysicsPose2D}.\n * @param point - Point in the same coordinate space as the posed shape. See\n * {@link PibblPhysicsVector2} .\n * @returns Whether the posed shape contains the point.\n *\n * @see {@link PibblPhysicsShape2D}\n * @see {@link PibblPhysicsPose2D}\n * @see {@link PibblPhysicsVector2}\n */\nexport function containsPoint2D(\n  shape: PibblPhysicsShape2D,\n  pose: PibblPhysicsPose2D,\n  point: PibblPhysicsVector2,\n): boolean {\n  return containsPointInShape2D(shape, pose, point);\n}\n\n/**\n * Computes signed separation and witness geometry between two posed shapes.\n *\n * @param first - First shape. See {@link PibblPhysicsShape2D}.\n * @param firstPose - Pose of the first shape. See {@link PibblPhysicsPose2D}.\n * @param second - Second shape. See {@link PibblPhysicsShape2D}.\n * @param secondPose - Pose of the second shape. See {@link PibblPhysicsPose2D}.\n * @returns Distance and closest-point information for the two posed shapes. See\n * {@link PibblPhysicsDistance2D} .\n *\n * @see {@link PibblPhysicsShape2D}\n * @see {@link PibblPhysicsPose2D}\n * @see {@link PibblPhysicsDistance2D}\n */\nexport function distanceBetweenShapes2D(\n  first: PibblPhysicsShape2D,\n  firstPose: PibblPhysicsPose2D,\n  second: PibblPhysicsShape2D,\n  secondPose: PibblPhysicsPose2D,\n): PibblPhysicsDistance2D {\n  return distanceBetweenPreparedShapes2D(first, firstPose, second, secondPose);\n}\n\n/**\n * Tests whether two posed shapes overlap without creating a physics world.\n *\n * @param first - First shape. See {@link PibblPhysicsShape2D}.\n * @param firstPose - Pose of the first shape. See {@link PibblPhysicsPose2D}.\n * @param second - Second shape. See {@link PibblPhysicsShape2D}.\n * @param secondPose - Pose of the second shape. See {@link PibblPhysicsPose2D}.\n * @returns Whether the two posed shapes overlap.\n *\n * @see {@link PibblPhysicsShape2D}\n * @see {@link PibblPhysicsPose2D}\n */\nexport function overlapShapes2D(\n  first: PibblPhysicsShape2D,\n  firstPose: PibblPhysicsPose2D,\n  second: PibblPhysicsShape2D,\n  secondPose: PibblPhysicsPose2D,\n): boolean {\n  return overlapPreparedShapes2D(first, firstPose, second, secondPose);\n}\n\n/**\n * Computes contact geometry for two posed shapes, or null when they do not contact.\n *\n * @param first - First shape. See {@link PibblPhysicsShape2D}.\n * @param firstPose - Pose of the first shape. See {@link PibblPhysicsPose2D}.\n * @param second - Second shape. See {@link PibblPhysicsShape2D}.\n * @param secondPose - Pose of the second shape. See {@link PibblPhysicsPose2D}.\n * @returns Contact information, or null when the shapes do not contact. See\n * {@link PibblPhysicsShapeContact2D} .\n *\n * @see {@link PibblPhysicsShape2D}\n * @see {@link PibblPhysicsPose2D}\n * @see {@link PibblPhysicsShapeContact2D}\n */\nexport function contactBetweenShapes2D(\n  first: PibblPhysicsShape2D,\n  firstPose: PibblPhysicsPose2D,\n  second: PibblPhysicsShape2D,\n  secondPose: PibblPhysicsPose2D,\n): PibblPhysicsShapeContact2D | null {\n  return contactBetweenPreparedShapes2D(first, firstPose, second, secondPose);\n}\n"],
+  "mappings": "AAwKA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAEP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AACP;AAAA,EACE;AAAA,EACA;AAAA,OACK;AAeA,SAAS,gBACd,OACA,MACA,OACS;AACT,SAAO,uBAAuB,OAAO,MAAM,KAAK;AAClD;AAgBO,SAAS,wBACd,OACA,WACA,QACA,YACwB;AACxB,SAAO,gCAAgC,OAAO,WAAW,QAAQ,UAAU;AAC7E;AAcO,SAAS,gBACd,OACA,WACA,QACA,YACS;AACT,SAAO,wBAAwB,OAAO,WAAW,QAAQ,UAAU;AACrE;AAgBO,SAAS,uBACd,OACA,WACA,QACA,YACmC;AACnC,SAAO,+BAA+B,OAAO,WAAW,QAAQ,UAAU;AAC5E;",
+  "names": []
+}

package/dist/features/physics/2d-geometry.mjs

@@ -0,0 +1 @@
+export * from './2d-geometry.js';

package/dist/features/physics/2d-testing.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Deterministic test support for public 2D physics compositions.
+ *
+ * The harness drives Pibbl's existing realm scheduler. `advanceFrames()` advances
+ * host frames; a physics world may run zero, one, or several fixed ticks in a
+ * host frame according to its public fixed-step configuration.
+ */
+import { type PibblNode } from "@pibbl/core";
+/**
+ * Caller-owned canvas, root factory, and observation callback for deterministic physics testing.
+ *
+ * @see {@link PibblNode}
+ * @see {@link createPhysicsTestHarness2D}
+ */
+export interface PibblPhysicsTestHarness2DOptions<Observation> {
+    /** The caller owns this canvas; disposing the harness never removes it. */
+    readonly canvas: HTMLCanvasElement;
+    /**
+     * Creates a new public Pibbl root for the initial mount and each reset.
+     * @returns The Pibbl root tree mounted by the test harness. See {@link PibblNode}.
+     */
+    readonly root: () => PibblNode;
+    /**
+     * Reads application state after a frame or action.
+     * @returns The semantic state to expose through the harness's observe method.
+     */
+    readonly observe: () => Observation;
+}
+/**
+ * A disposable test mount with explicit host-frame advancement and public-state observations.
+ *
+ * @see {@link createPhysicsTestHarness2D}
+ */
+export interface PibblPhysicsTestHarness2D<Observation> {
+    /** Number of host callbacks currently requested by Pibbl (zero or one). */
+    readonly pendingFrames: number;
+    /**
+     * Delivers one already-requested host frame at the current host time.
+     * @returns Whether a pending frame was flushed.
+     */
+    flush(): boolean;
+    /**
+     * Advances up to `count` requested host frames by `milliseconds` each.
+     * This advances the host clock, not a guaranteed count of physics fixed ticks.
+     * @param count - Number of frames to advance.
+     * @param milliseconds - Duration of each frame in milliseconds.
+     * @returns The number of frames advanced.
+     */
+    advanceFrames(count: number, milliseconds?: number): number;
+    /**
+     * Runs an application action and delivers one resulting frame at the current time.
+     * @param callback - Action to run within the harness's deterministic scheduling context.
+     * @returns The action's return value.
+     */
+    act<Result>(callback: () => Result): Result;
+    /**
+     * Reads the caller-provided public observation without scheduling work.
+     * @returns The current observation from the configured observer.
+     */
+    observe(): Observation;
+    /** Disposes the mounted root and mounts a new one without moving host time backward. */
+    reset(): void;
+    /** Disposes the root and restores the previous realm scheduler driver. */
+    dispose(): void;
+}
+/**
+ * Creates an isolated manual-clock test mount for one Pibbl 2D physics composition.
+ *
+ * It refuses a realm with an existing root because a Pibbl realm deliberately has
+ * one scheduler. Use ordinary browser tests when a test needs multiple roots.
+ *
+ * @param options - Caller-owned canvas, root factory, and semantic state observer. See
+ * {@link PibblPhysicsTestHarness2DOptions} .
+ * @returns A harness owning the test mount and scheduler lifetime; dispose it after use. See
+ * {@link PibblPhysicsTestHarness2D} .
+ *
+ * @see {@link PibblPhysicsTestHarness2DOptions}
+ * @see {@link PibblPhysicsTestHarness2D}
+ */
+export declare function createPhysicsTestHarness2D<Observation>(options: PibblPhysicsTestHarness2DOptions<Observation>): PibblPhysicsTestHarness2D<Observation>;

package/dist/features/physics/2d-testing.js

@@ -0,0 +1,141 @@
+import { pibbl } from "@pibbl/core";
+import {
+  PibblInternalManualSchedulerDriver,
+  pibblInternalInstallTestSchedulerDriver,
+  pibblInternalSnapshotRealmScheduler
+} from "@pibbl/core/internal";
+const DEFAULT_FRAME_MILLISECONDS = 1e3 / 60;
+function createPhysicsTestHarness2D(options) {
+  const before = pibblInternalSnapshotRealmScheduler();
+  if (before.registeredRoots !== 0) {
+    throw new Error(
+      "createPhysicsTestHarness2D() requires an isolated Pibbl realm; dispose existing Pibbl roots before creating the harness."
+    );
+  }
+  if (before.phase !== "idle" || before.pendingHostFrames !== 0) {
+    throw new Error(
+      "createPhysicsTestHarness2D() cannot replace the Pibbl clock while realm work is active."
+    );
+  }
+  const driver = new PibblInternalManualSchedulerDriver();
+  let restoreDriver;
+  let controller;
+  let disposed = false;
+  let hostTime = 0;
+  try {
+    restoreDriver = pibblInternalInstallTestSchedulerDriver(driver);
+    controller = mountRoot(options);
+  } catch (error) {
+    try {
+      controller?.dispose();
+    } finally {
+      controller = void 0;
+      restoreSchedulerDriver();
+    }
+    throw error;
+  }
+  const requireLive = () => {
+    if (disposed) {
+      throw new Error("This Pibbl physics 2D test harness has been disposed.");
+    }
+  };
+  const flush = () => {
+    requireLive();
+    if (driver.pendingHostFrames === 0) return false;
+    driver.flush(hostTime);
+    return true;
+  };
+  return Object.freeze({
+    get pendingFrames() {
+      return driver.pendingHostFrames;
+    },
+    flush,
+    advanceFrames(count, milliseconds = DEFAULT_FRAME_MILLISECONDS) {
+      requireLive();
+      requireFrameCount(count);
+      requireMilliseconds(milliseconds);
+      let advanced = 0;
+      for (let index = 0; index < count; index++) {
+        if (driver.pendingHostFrames === 0) break;
+        const nextHostTime = hostTime + milliseconds;
+        if (!Number.isFinite(nextHostTime)) {
+          throw new RangeError(
+            "advanceFrames() cannot advance the host clock beyond a finite time."
+          );
+        }
+        hostTime = nextHostTime;
+        driver.flush(hostTime);
+        advanced++;
+      }
+      return advanced;
+    },
+    act(callback) {
+      requireLive();
+      const result = callback();
+      flush();
+      return result;
+    },
+    observe() {
+      requireLive();
+      return options.observe();
+    },
+    reset() {
+      requireLive();
+      const previousController = controller;
+      controller = void 0;
+      try {
+        previousController?.dispose();
+        controller = mountRoot(options);
+      } catch (error) {
+        disposed = true;
+        try {
+          restoreSchedulerDriver();
+        } catch (restoreError) {
+          throw new AggregateError(
+            [error, restoreError],
+            "Pibbl physics 2D test harness reset failed and could not restore the scheduler driver.",
+            { cause: restoreError }
+          );
+        }
+        throw error;
+      }
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      const currentController = controller;
+      controller = void 0;
+      try {
+        currentController?.dispose();
+      } finally {
+        restoreSchedulerDriver();
+      }
+    }
+  });
+  function restoreSchedulerDriver() {
+    const restore = restoreDriver;
+    restoreDriver = void 0;
+    restore?.();
+  }
+}
+function mountRoot(options) {
+  return pibbl(options.canvas, options.root());
+}
+function requireFrameCount(count) {
+  if (!Number.isSafeInteger(count) || count < 0) {
+    throw new RangeError(
+      "advanceFrames(count) requires a non-negative safe integer."
+    );
+  }
+}
+function requireMilliseconds(milliseconds) {
+  if (!Number.isFinite(milliseconds) || milliseconds < 0) {
+    throw new RangeError(
+      "advanceFrames(milliseconds) requires a finite non-negative number."
+    );
+  }
+}
+export {
+  createPhysicsTestHarness2D
+};
+//# sourceMappingURL=2d-testing.js.map

package/dist/features/physics/2d-testing.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/features/physics/2d-testing.ts"],
+  "sourcesContent": ["/**\n * Deterministic test support for public 2D physics compositions.\n *\n * The harness drives Pibbl's existing realm scheduler. `advanceFrames()` advances\n * host frames; a physics world may run zero, one, or several fixed ticks in a\n * host frame according to its public fixed-step configuration.\n */\nimport { pibbl, type PibblController, type PibblNode } from \"@pibbl/core\";\nimport {\n  PibblInternalManualSchedulerDriver,\n  pibblInternalInstallTestSchedulerDriver,\n  pibblInternalSnapshotRealmScheduler,\n} from \"@pibbl/core/internal\";\n\n/**\n * Caller-owned canvas, root factory, and observation callback for deterministic physics testing.\n *\n * @see {@link PibblNode}\n * @see {@link createPhysicsTestHarness2D}\n */\nexport interface PibblPhysicsTestHarness2DOptions<Observation> {\n  /** The caller owns this canvas; disposing the harness never removes it. */\n  readonly canvas: HTMLCanvasElement;\n  /**\n   * Creates a new public Pibbl root for the initial mount and each reset.\n   * @returns The Pibbl root tree mounted by the test harness. See {@link PibblNode}.\n   */\n  readonly root: () => PibblNode;\n  /**\n   * Reads application state after a frame or action.\n   * @returns The semantic state to expose through the harness's observe method.\n   */\n  readonly observe: () => Observation;\n}\n\n/**\n * A disposable test mount with explicit host-frame advancement and public-state observations.\n *\n * @see {@link createPhysicsTestHarness2D}\n */\nexport interface PibblPhysicsTestHarness2D<Observation> {\n  /** Number of host callbacks currently requested by Pibbl (zero or one). */\n  readonly pendingFrames: number;\n  /**\n   * Delivers one already-requested host frame at the current host time.\n   * @returns Whether a pending frame was flushed.\n   */\n  flush(): boolean;\n  /**\n   * Advances up to `count` requested host frames by `milliseconds` each.\n   * This advances the host clock, not a guaranteed count of physics fixed ticks.\n   * @param count - Number of frames to advance.\n   * @param milliseconds - Duration of each frame in milliseconds.\n   * @returns The number of frames advanced.\n   */\n  advanceFrames(count: number, milliseconds?: number): number;\n  /**\n   * Runs an application action and delivers one resulting frame at the current time.\n   * @param callback - Action to run within the harness's deterministic scheduling context.\n   * @returns The action's return value.\n   */\n  act<Result>(callback: () => Result): Result;\n  /**\n   * Reads the caller-provided public observation without scheduling work.\n   * @returns The current observation from the configured observer.\n   */\n  observe(): Observation;\n  /** Disposes the mounted root and mounts a new one without moving host time backward. */\n  reset(): void;\n  /** Disposes the root and restores the previous realm scheduler driver. */\n  dispose(): void;\n}\n\nconst DEFAULT_FRAME_MILLISECONDS = 1000 / 60;\n\n/**\n * Creates an isolated manual-clock test mount for one Pibbl 2D physics composition.\n *\n * It refuses a realm with an existing root because a Pibbl realm deliberately has\n * one scheduler. Use ordinary browser tests when a test needs multiple roots.\n *\n * @param options - Caller-owned canvas, root factory, and semantic state observer. See\n * {@link PibblPhysicsTestHarness2DOptions} .\n * @returns A harness owning the test mount and scheduler lifetime; dispose it after use. See\n * {@link PibblPhysicsTestHarness2D} .\n *\n * @see {@link PibblPhysicsTestHarness2DOptions}\n * @see {@link PibblPhysicsTestHarness2D}\n */\nexport function createPhysicsTestHarness2D<Observation>(\n  options: PibblPhysicsTestHarness2DOptions<Observation>,\n): PibblPhysicsTestHarness2D<Observation> {\n  const before = pibblInternalSnapshotRealmScheduler();\n  if (before.registeredRoots !== 0) {\n    throw new Error(\n      \"createPhysicsTestHarness2D() requires an isolated Pibbl realm; dispose existing Pibbl roots before creating the harness.\",\n    );\n  }\n  if (before.phase !== \"idle\" || before.pendingHostFrames !== 0) {\n    throw new Error(\n      \"createPhysicsTestHarness2D() cannot replace the Pibbl clock while realm work is active.\",\n    );\n  }\n\n  const driver = new PibblInternalManualSchedulerDriver();\n  let restoreDriver: (() => void) | undefined;\n  let controller: PibblController | undefined;\n  let disposed = false;\n  let hostTime = 0;\n\n  try {\n    restoreDriver = pibblInternalInstallTestSchedulerDriver(driver);\n    controller = mountRoot(options);\n  } catch (error) {\n    try {\n      controller?.dispose();\n    } finally {\n      controller = undefined;\n      restoreSchedulerDriver();\n    }\n    throw error;\n  }\n\n  const requireLive = (): void => {\n    if (disposed) {\n      throw new Error(\"This Pibbl physics 2D test harness has been disposed.\");\n    }\n  };\n  const flush = (): boolean => {\n    requireLive();\n    if (driver.pendingHostFrames === 0) return false;\n    driver.flush(hostTime);\n    return true;\n  };\n\n  return Object.freeze({\n    get pendingFrames(): number {\n      return driver.pendingHostFrames;\n    },\n    flush,\n    advanceFrames(\n      count: number,\n      milliseconds = DEFAULT_FRAME_MILLISECONDS,\n    ): number {\n      requireLive();\n      requireFrameCount(count);\n      requireMilliseconds(milliseconds);\n      let advanced = 0;\n      for (let index = 0; index < count; index++) {\n        if (driver.pendingHostFrames === 0) break;\n        const nextHostTime = hostTime + milliseconds;\n        if (!Number.isFinite(nextHostTime)) {\n          throw new RangeError(\n            \"advanceFrames() cannot advance the host clock beyond a finite time.\",\n          );\n        }\n        hostTime = nextHostTime;\n        driver.flush(hostTime);\n        advanced++;\n      }\n      return advanced;\n    },\n    act<Result>(callback: () => Result): Result {\n      requireLive();\n      const result = callback();\n      flush();\n      return result;\n    },\n    observe(): Observation {\n      requireLive();\n      return options.observe();\n    },\n    reset(): void {\n      requireLive();\n      const previousController = controller;\n      controller = undefined;\n      try {\n        previousController?.dispose();\n        controller = mountRoot(options);\n      } catch (error) {\n        disposed = true;\n        try {\n          restoreSchedulerDriver();\n        } catch (restoreError) {\n          throw new AggregateError(\n            [error, restoreError],\n            \"Pibbl physics 2D test harness reset failed and could not restore the scheduler driver.\",\n            { cause: restoreError },\n          );\n        }\n        throw error;\n      }\n    },\n    dispose(): void {\n      if (disposed) return;\n      disposed = true;\n      const currentController = controller;\n      controller = undefined;\n      try {\n        currentController?.dispose();\n      } finally {\n        restoreSchedulerDriver();\n      }\n    },\n  });\n\n  function restoreSchedulerDriver(): void {\n    const restore = restoreDriver;\n    restoreDriver = undefined;\n    restore?.();\n  }\n}\n\nfunction mountRoot<Observation>(\n  options: PibblPhysicsTestHarness2DOptions<Observation>,\n): PibblController {\n  return pibbl(options.canvas, options.root());\n}\n\nfunction requireFrameCount(count: number): void {\n  if (!Number.isSafeInteger(count) || count < 0) {\n    throw new RangeError(\n      \"advanceFrames(count) requires a non-negative safe integer.\",\n    );\n  }\n}\n\nfunction requireMilliseconds(milliseconds: number): void {\n  if (!Number.isFinite(milliseconds) || milliseconds < 0) {\n    throw new RangeError(\n      \"advanceFrames(milliseconds) requires a finite non-negative number.\",\n    );\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/features/physics/2d-testing.mjs

@@ -0,0 +1 @@
+export * from './2d-testing.js';