@aura3d/engine 1.5.2 → 2.0.1

package/dist/engine/agent-api/GameGenreKits.js

@@ -1,4 +1,5 @@
 import { validatePlatformerMotion } from "./PlatformerMotion.js";
+import { createGameArcadeVehicle, createGameKinematicBody } from "./GameRuntime.js";
 const DEFAULT_LOCOMOTION_CLIP_MAP = {
     idle: "idle",
     run: "run",
@@ -176,7 +177,30 @@ export function createGamePlatformerKit(level = {}) {
     const playerHeight = config.playerSize[1];
     const surfaceQuery = createGamePlatformerSurfaceQuery(level);
     let state = createPlatformerState(config);
+    const createBody = () => createGameKinematicBody({
+        id: `${config.id}-player`,
+        position: [state.player.x, state.player.y, 0],
+        velocity: [state.player.vx, state.player.vy, 0],
+        size: [playerWidth, playerHeight, 0.25],
+        gravity: config.gravity,
+        groundY: -1_000_000,
+        friction: 0,
+        maxSpeed: Math.max(config.moveSpeed, config.dashSpeed),
+        jumpVelocity: config.jumpVelocity,
+        coyoteMs: config.coyoteMs,
+        jumpBufferMs: config.jumpBufferMs
+    });
+    let body = createBody();
     let events = [];
+    const syncPlayerFromBody = () => {
+        const next = body.snapshot();
+        state.player.x = next.position[0];
+        state.player.y = next.position[1];
+        state.player.vx = next.velocity[0];
+        state.player.vy = next.velocity[1];
+        state.player.facing = next.facing;
+        state.player.grounded = next.grounded;
+    };
     const snapshot = () => ({
         kind: "aura-game-platformer-kit",
         levelId: config.id,
@@ -215,15 +239,17 @@ export function createGamePlatformerKit(level = {}) {
             vy: 0,
             facing: state.player.facing,
             grounded: false,
-            coyote: 0,
-            jumpBuffer: 0,
             dashCooldown: 0,
             ridingPlatformId: undefined
         };
+        body = createBody();
         // Ignore held directional input briefly after a death so a key that caused
         // the miss cannot immediately carry the fresh spawn off its supporting
         // surface before the player or an automated driver can react.
-        state.respawnControlLock = 0.3;
+        // A released direction unlocks immediately; the bounded fallback keeps
+        // continuous-input AI/autoplay controllers from remaining locked forever.
+        state.respawnControlLock = 0.75;
+        state.respawnAwaitingNeutralInput = true;
         emit("respawn", state.checkpointId);
     };
     return {
@@ -237,6 +263,7 @@ export function createGamePlatformerKit(level = {}) {
             if (input.reset === true) {
                 events = [];
                 state = createPlatformerState(config);
+                body = createBody();
                 emit("reset");
                 return snapshot();
             }
@@ -255,44 +282,46 @@ export function createGamePlatformerKit(level = {}) {
                 ? previousMoving.find((platform) => platform.id === state.player.ridingPlatformId)
                 : undefined;
             if (carried && carriedPrevious && state.player.grounded) {
-                state.player.x += carried.x - carriedPrevious.x;
-                state.player.y += platformTop(carried) - platformTop(carriedPrevious);
+                body.position = [
+                    body.position[0] + carried.x - carriedPrevious.x,
+                    body.position[1] + platformTop(carried) - platformTop(carriedPrevious),
+                    body.position[2]
+                ];
+                syncPlayerFromBody();
             }
             state.respawnControlLock = Math.max(0, state.respawnControlLock - step);
-            const controlsLocked = state.respawnControlLock > 0;
-            const moveX = controlsLocked ? 0 : clampNumber(input.moveX ?? 0, -1, 1);
-            if (Math.abs(moveX) > 0.01)
-                state.player.facing = moveX >= 0 ? 1 : -1;
-            state.player.vx = moveX * config.moveSpeed;
-            state.player.coyote = state.player.grounded ? config.coyoteMs / 1000 : Math.max(0, state.player.coyote - step);
-            state.player.jumpBuffer = input.jumpPressed ? config.jumpBufferMs / 1000 : Math.max(0, state.player.jumpBuffer - step);
+            const requestedMoveX = clampNumber(input.moveX ?? 0, -1, 1);
+            if (state.respawnAwaitingNeutralInput && Math.abs(requestedMoveX) <= 0.01) {
+                state.respawnAwaitingNeutralInput = false;
+            }
+            if (state.respawnControlLock <= 0)
+                state.respawnAwaitingNeutralInput = false;
+            const controlsLocked = state.respawnAwaitingNeutralInput;
+            const moveX = controlsLocked ? 0 : requestedMoveX;
+            body.move(moveX, config.moveSpeed);
+            if (input.jumpPressed)
+                body.requestJump();
             state.player.dashCooldown = Math.max(0, state.player.dashCooldown - step);
             if (!controlsLocked && input.dashPressed && state.player.dashCooldown <= 0) {
-                state.player.vx = state.player.facing * config.dashSpeed;
+                body.dash([body.facing, 0, 0], config.dashSpeed);
                 state.player.dashCooldown = 0.38;
                 emit("dash");
             }
-            if (state.player.jumpBuffer > 0 && (state.player.grounded || state.player.coyote > 0)) {
-                state.player.vy = config.jumpVelocity;
-                state.player.grounded = false;
+            if (body.consumeJump(config.jumpVelocity)) {
                 state.player.ridingPlatformId = undefined;
-                state.player.coyote = 0;
-                state.player.jumpBuffer = 0;
                 emit("jump");
             }
-            const gravity = input.fastFall && state.player.vy < 0 ? config.gravity * 1.6 : config.gravity;
-            state.player.vy += gravity * step;
-            state.player.x += state.player.vx * step;
-            state.player.y += state.player.vy * step;
-            state.player.grounded = false;
+            if (input.fastFall && body.velocity[1] < 0) {
+                body.velocity = [body.velocity[0], body.velocity[1] + config.gravity * 0.6 * step, body.velocity[2]];
+            }
+            body.update(step);
+            syncPlayerFromBody();
             state.player.ridingPlatformId = undefined;
             const platforms = [...config.platforms, ...moving];
             const groundContact = surfaceQuery.groundContact({ player: state.player, previousPlayer, additionalSurfaces: moving });
             if (groundContact.grounded && groundContact.surfaceId && groundContact.surfaceTop !== undefined) {
-                state.player.y = groundContact.surfaceTop;
-                state.player.vy = 0;
-                state.player.grounded = true;
-                state.player.coyote = config.coyoteMs / 1000;
+                body.snapToGround(groundContact.surfaceTop);
+                syncPlayerFromBody();
                 state.player.ridingPlatformId = moving.some((candidate) => candidate.id === groundContact.surfaceId) ? groundContact.surfaceId : undefined;
                 if (!previousPlayer.grounded)
                     emit("land", groundContact.surfaceId);
@@ -333,6 +362,7 @@ export function createGamePlatformerKit(level = {}) {
         reset(checkpointId) {
             events = [];
             state = createPlatformerState(config, checkpointId);
+            body = createBody();
             return snapshot();
         },
         snapshot,
@@ -408,11 +438,22 @@ export function createGameAssetBoundPlatformerLevel(options) {
      * Public asset-bound levels are therefore validated here. `motionTuning: "reported"`
      * keeps the report without throwing, for a route that is deliberately mid-migration.
      */
+    /*
+     * The character's height comes from the level itself, so a route does not have to
+     * restate it for the check to be character-aware. Without this the floaty ceiling is
+     * measured against the tallest step alone, and a mesh-extracted course whose steps are
+     * shorter than the character (Skyline: 0.36 steps, 0.52 hero) rejects every jump that
+     * is actually visible next to the player.
+     */
+    const characterHeight = (level.playerSize ?? DEFAULT_PLATFORMER_LEVEL.playerSize)?.[1];
     const motionReport = validatePlatformerMotion(platforms, {
         gravity: level.gravity ?? DEFAULT_PLATFORMER_LEVEL.gravity,
         jumpVelocity: level.jumpVelocity ?? DEFAULT_PLATFORMER_LEVEL.jumpVelocity,
         moveSpeed
-    }, options.motionLimits ?? {});
+    }, {
+        ...(characterHeight === undefined ? {} : { characterHeight }),
+        ...(options.motionLimits ?? {})
+    });
     if (!motionReport.passes && (options.motionTuning ?? "enforced") === "enforced") {
         const failures = motionReport.checks.filter((check) => !check.passes);
         throw new Error(`game.assetBoundPlatformerLevel motion tuning is inconsistent with the level geometry: ${failures.map((check) => `${check.id} (${check.detail})`).join("; ")}. Suggested fix: derive gravity, jumpVelocity and moveSpeed with solvePlatformerMotion(level.platforms, { targetSessionSeconds }).`);
@@ -488,20 +529,43 @@ export function createGameRacingSurfaceQuery(route) {
     const roadHalfWidth = (isAssetBoundRacingRoute(route)
         ? Math.max(0.002, route.width ?? 1.2)
         : Math.max(0.25, route.width ?? 1.2)) * 0.5;
+    const closed = route.closed !== false;
+    function sampleAt(progress) {
+        const normalized = normalizeProgress(progress);
+        const distance = normalized * length;
+        let index = segments.findIndex((candidate) => distance >= candidate.start && distance <= candidate.start + candidate.length);
+        if (index < 0)
+            index = segments.length - 1;
+        const segment = segments[index];
+        const t = clampNumber((distance - segment.start) / segment.length, 0, 1);
+        return {
+            x: segment.from.x + (segment.to.x - segment.from.x) * t,
+            y: segment.from.y + (segment.to.y - segment.from.y) * t,
+            progress: normalized,
+            heading: segment.heading,
+            curvature: arcCurvature(segments, length, distance, closed)
+        };
+    }
     return {
         kind: "aura-game-racing-surface-query",
         certified: isAssetBoundRacingRoute(route),
+        length,
+        roadHalfWidth,
         query(position) {
             const nearest = nearestRacePoint(segments, length, position);
+            const line = sampleAt(nearest.progress);
             return {
                 onTrack: nearest.offset <= roadHalfWidth,
                 progress: nearest.progress,
                 distance: nearest.distance,
                 trackOffset: nearest.offset,
                 signedTrackOffset: nearest.signedOffset,
-                roadHalfWidth
+                roadHalfWidth,
+                tangentHeading: line.heading,
+                curvature: line.curvature
             };
-        }
+        },
+        sampleAt
     };
 }
 export function createGameRacingKit(options) {
@@ -524,12 +588,30 @@ export function createGameRacingKit(options) {
     const steerRate = options.steerRate ?? 2.7;
     const boostAcceleration = options.boostAcceleration ?? 9;
     const offTrackDrag = options.offTrackDrag ?? 5.5;
+    const boundaryInset = Math.max(0, options.boundaryInset ?? 0);
+    const recoveryHeadingLimit = options.recoveryHeadingLimit === undefined
+        ? undefined
+        // Narrow asset-bound circuits may need a much tighter recovery corridor than
+        // 0.1 rad (~5.7°): a long open-wheel chassis can put its outside-front contact
+        // beyond the mesh while its centre is already recovered. Preserve the caller's
+        // physical footprint decision down to a one-hundredth radian.
+        : clampNumber(options.recoveryHeadingLimit, 0.01, Math.PI);
     const checkpointRadius = options.checkpointRadius ?? 0.07;
     const lapsToWin = Math.max(1, options.lapsToWin ?? 1);
+    const motion = createGameArcadeVehicle({
+        maxSpeed,
+        acceleration,
+        brakeStrength,
+        reverseSpeed,
+        drag,
+        steerRate,
+        boostAcceleration
+    });
     let events = [];
     let state = createRaceState(options.startProgress ?? 0);
     function createRaceState(progress) {
         const sample = sampleRaceRoute(segments, length, progress);
+        const vehicle = motion.reset({ x: sample.x, z: sample.y, heading: sample.heading });
         return {
             frame: 0,
             time: 0,
@@ -537,15 +619,15 @@ export function createGameRacingKit(options) {
             checkpoint: 0,
             lapTime: 0,
             bestTime: undefined,
-            speed: 0,
-            drift: 0,
+            speed: vehicle.speed,
+            drift: vehicle.drift,
             offTrack: false,
             progress: normalizeProgress(progress),
             distance: normalizeProgress(progress) * length,
             trackOffset: 0,
             signedTrackOffset: 0,
-            position: { x: sample.x, y: sample.y },
-            heading: sample.heading,
+            position: { x: vehicle.x, y: vehicle.z },
+            heading: vehicle.heading,
             status: "running"
         };
     }
@@ -563,14 +645,44 @@ export function createGameRacingKit(options) {
     const placeAtProgress = (progress, offset = 0) => {
         const sample = sampleRaceRoute(segments, length, progress);
         const normal = { x: -Math.sin(sample.heading), y: Math.cos(sample.heading) };
+        const vehicle = motion.reset({
+            x: sample.x + normal.x * offset,
+            z: sample.y + normal.y * offset,
+            heading: sample.heading,
+            speed: state.speed,
+            drift: state.drift
+        });
         state = {
             ...state,
             progress: normalizeProgress(progress),
             distance: normalizeProgress(progress) * length,
             trackOffset: Math.abs(offset),
             signedTrackOffset: offset,
-            position: { x: sample.x + normal.x * offset, y: sample.y + normal.y * offset },
-            heading: sample.heading
+            position: { x: vehicle.x, y: vehicle.z },
+            heading: vehicle.heading
+        };
+        return snapshot();
+    };
+    const resolveContact = (position, correction = {}) => {
+        const contact = surfaceQuery.query(position);
+        const vehicle = motion.constrain({
+            x: position.x,
+            z: position.y,
+            heading: correction.heading,
+            speedMultiplier: correction.speedMultiplier,
+            driftMultiplier: correction.driftMultiplier
+        });
+        state = {
+            ...state,
+            speed: vehicle.speed,
+            drift: vehicle.drift,
+            heading: vehicle.heading,
+            position: { x: vehicle.x, y: vehicle.z },
+            progress: contact.progress,
+            distance: contact.distance,
+            trackOffset: contact.trackOffset,
+            signedTrackOffset: contact.signedTrackOffset,
+            offTrack: !contact.onTrack
         };
         return snapshot();
     };
@@ -592,47 +704,75 @@ export function createGameRacingKit(options) {
             state = { ...state, frame: state.frame + 1, time: state.time + step, lapTime: state.lapTime + step };
             const throttle = typeof input.throttle === "boolean" ? (input.throttle ? 1 : 0) : clampNumber(input.throttle ?? 0, 0, 1);
             const brake = typeof input.brake === "boolean" ? (input.brake ? 1 : 0) : clampNumber(input.brake ?? 0, 0, 1);
-            let speed = state.speed + throttle * acceleration * step - brake * brakeStrength * step;
-            if (input.boost && state.drift > 0.18)
-                speed += boostAcceleration * step;
-            speed -= Math.sign(speed) * Math.min(Math.abs(speed), drag * step);
-            speed = clampNumber(speed, -reverseSpeed, maxSpeed);
             const steer = clampNumber(input.steer ?? 0, -1, 1);
-            const drift = clampNumber(state.drift + ((input.drift && Math.abs(steer) > 0.1 && speed > 2) ? step * 1.8 : -step * 1.2), 0, 1);
-            const heading = state.heading + steer * steerRate * (0.28 + Math.min(1, Math.abs(speed) / maxSpeed)) * (1 + drift * 0.55) * step * (speed < 0 ? -1 : 1);
+            let vehicle = motion.step(step, {
+                throttle,
+                brake,
+                steer,
+                drifting: input.drift,
+                boost: input.boost
+            });
             let position = {
-                x: state.position.x + Math.cos(heading) * speed * step,
-                y: state.position.y + Math.sin(heading) * speed * step
+                x: vehicle.x,
+                y: vehicle.z
             };
             let contact = surfaceQuery.query(position);
-            const offTrack = !contact.onTrack;
+            const vehicleCenterHalfWidth = boundaryInset > 0
+                ? Math.max(0.001, contact.roadHalfWidth - Math.min(boundaryInset, contact.roadHalfWidth * 0.95))
+                : contact.roadHalfWidth * 0.98;
+            // A certified recovery clamps the centre exactly onto the admissible boundary.
+            // Floating-point projection can return that same point a few ulps outside on the
+            // next frame, which previously left `offTrack` latched forever after one touch.
+            // Keep the tolerance proportional to the sampled road width so it is scale-safe
+            // while remaining far smaller than a visible tyre/contact-patch displacement.
+            const boundaryTolerance = Math.max(1e-6, contact.roadHalfWidth * 0.002);
+            const offTrack = !contact.onTrack || contact.trackOffset > vehicleCenterHalfWidth + boundaryTolerance;
             if (offTrack) {
-                speed *= Math.max(0, 1 - offTrackDrag * step);
                 if (!state.offTrack)
                     emit("off-track");
                 if (surfaceQuery.certified) {
                     const center = sampleRaceRoute(segments, length, contact.progress);
                     const dx = position.x - center.x;
                     const dy = position.y - center.y;
-                    const scale = contact.trackOffset > 0 ? (contact.roadHalfWidth * 0.98) / contact.trackOffset : 0;
+                    // Recover slightly inside the admissible centre corridor, not exactly on its
+                    // mathematical edge. A boundary-only clamp lets an inertial vehicle re-trigger
+                    // recovery every frame and never reaches a visibly settled "on road" state.
+                    const recoveryHalfWidth = vehicleCenterHalfWidth * 0.92;
+                    const scale = contact.trackOffset > 0 ? recoveryHalfWidth / contact.trackOffset : 0;
                     position = { x: center.x + dx * scale, y: center.y + dy * scale };
                     contact = surfaceQuery.query(position);
                 }
+                const headingError = normalizeRacingAngle(vehicle.heading - contact.tangentHeading);
+                const recoveryHeading = recoveryHeadingLimit === undefined
+                    ? undefined
+                    : contact.tangentHeading + clampNumber(headingError, -recoveryHeadingLimit, recoveryHeadingLimit);
+                vehicle = motion.constrain({
+                    x: position.x,
+                    z: position.y,
+                    heading: recoveryHeading,
+                    speedMultiplier: Math.max(0, 1 - offTrackDrag * step),
+                    driftMultiplier: recoveryHeadingLimit === undefined ? 1 : Math.max(0, 1 - step * 2.5)
+                });
             }
             state = {
                 ...state,
-                speed,
-                drift,
-                heading,
-                position,
+                speed: vehicle.speed,
+                drift: vehicle.drift,
+                heading: vehicle.heading,
+                position: { x: vehicle.x, y: vehicle.z },
                 progress: contact.progress,
                 distance: contact.distance,
                 trackOffset: contact.trackOffset,
                 signedTrackOffset: contact.signedTrackOffset,
                 offTrack
             };
-            const target = checkpoints[state.checkpoint] ?? 1;
-            if (progressDistance(state.progress, target) <= checkpointRadius && !offTrack) {
+            // Once every ordered checkpoint in the lap is credited there is no next
+            // checkpoint. Falling back to progress `1` made every frame near the finish
+            // line increment the counter again when a noisy nearest-segment projection
+            // delayed the lap-wrap transition (Turbo visibly reached "Gate 62" in one
+            // stint despite having six gates).
+            const target = checkpoints[state.checkpoint];
+            if (target !== undefined && progressDistance(state.progress, target) <= checkpointRadius && !offTrack) {
                 emit("checkpoint", `checkpoint-${state.checkpoint + 1}`);
                 state = { ...state, checkpoint: state.checkpoint + 1 };
             }
@@ -652,6 +792,7 @@ export function createGameRacingKit(options) {
             }
             return snapshot();
         },
+        resolveContact,
         reset(progress = options.startProgress ?? 0) {
             events = [];
             state = createRaceState(progress);
@@ -677,6 +818,14 @@ export function createGameRacingKit(options) {
         }
     };
 }
+function normalizeRacingAngle(angle) {
+    let normalized = angle;
+    while (normalized > Math.PI)
+        normalized -= Math.PI * 2;
+    while (normalized < -Math.PI)
+        normalized += Math.PI * 2;
+    return normalized;
+}
 const FALLING_BLOCK_SHAPES = {
     I: [
         [{ x: 0, y: 1 }, { x: 1, y: 1 }, { x: 2, y: 1 }, { x: 3, y: 1 }],
@@ -999,14 +1148,13 @@ function createPlatformerState(config, checkpointId = "start") {
             vy: 0,
             facing: 1,
             grounded: false,
-            coyote: 0,
-            jumpBuffer: 0,
             dashCooldown: 0
         },
         score: 0,
         lives: config.lives,
         deaths: 0,
         respawnControlLock: 0,
+        respawnAwaitingNeutralInput: false,
         checkpointId,
         collected: new Set(),
         activatedCheckpoints: checkpointId === "start" ? new Set() : new Set([checkpointId])
@@ -1067,6 +1215,100 @@ function platformerPlayerRect(player, width, height) {
 function rectsOverlap(a, b) {
     return a.x < b.x + b.width && a.x + a.width > b.x && a.y < b.y + b.height && a.y + a.height > b.y;
 }
+/**
+ * Shortest signed angle from `from` to `to`, radians, in (-pi, pi].
+ *
+ * Steering toward a heading requires the *shortest* way round. Subtracting raw headings makes a car
+ * whose target is just across the +/-pi wrap take the long way and spin.
+ */
+function signedAngleDelta(from, to) {
+    let delta = (to - from) % (Math.PI * 2);
+    if (delta > Math.PI)
+        delta -= Math.PI * 2;
+    if (delta <= -Math.PI)
+        delta += Math.PI * 2;
+    return delta;
+}
+/**
+ * Signed curvature of the racing line, as 1/radius in route units, measured over an arc window.
+ *
+ * A polyline has no curvature within a segment and an undefined spike at each vertex. Attributing
+ * the whole heading change at a vertex to that vertex — the obvious approach, and the one this
+ * previously used — makes curvature a function of where the author happened to place vertices
+ * rather than of the shape of the road. On a 33-point circuit that produced an impulse train:
+ * curvature read 0 along a segment then spiked, so the radius reported for one continuous corner
+ * swung 0.69 -> 3.01 -> 6.03 -> 16.17 -> 7.24 within 60 frames. Adjacent samples 0.094 units apart
+ * differed by 2.068 in curvature — larger than the p99 curvature of the whole track, so the signal
+ * was mostly discretisation artefact.
+ *
+ * Both consumers of curvature are harmed by that, and neither can defend itself:
+ *
+ * - A speed profile solves corner entry speed as `sqrt(lateralLimit * radius)`. Fed a spike, it
+ *   demands a near-stop at an arbitrary vertex and full speed one sample later.
+ * - A steering feedforward sets `atan(wheelbase * curvature)`. Fed a spike, it commands full lock
+ *   for a few frames and zero for the rest, so the car saws through corners and runs wide — the
+ *   "car will not turn / slides off on turns" symptom, from the geometry layer rather than the tyre
+ *   model that usually gets blamed for it.
+ *
+ * The fix is to measure curvature the way it is defined — over an arc, not at a point. Three points
+ * spaced `window` along the line give the Menger curvature, which is the signed reciprocal radius
+ * of the circle through them. The window is `CURVATURE_WINDOW_SEGMENTS` times the mean segment
+ * length, so it adapts to how finely the route is authored instead of assuming a vertex density.
+ *
+ * Widening the window trades resolution for smoothness, and the trade has a floor and a ceiling:
+ * too narrow and the artefact survives, too wide and a real hairpin is averaged away into a corner
+ * the car takes far too fast. On the certified circuit, 2x cuts the adjacent-sample jump 21x
+ * (2.068 -> 0.098) while *preserving* corner magnitude (p90 |k| 0.736 -> 0.808); 3x smooths further
+ * but understates the tightest corner by 19% (max |k| 0.808 -> 0.565, i.e. minimum radius 1.00 ->
+ * 1.51), which would have the profile carry ~23% too much speed into the hairpin. Hence 2x.
+ */
+const CURVATURE_WINDOW_SEGMENTS = 2;
+function positionAtDistance(segments, totalLength, distance, closed) {
+    const along = closed
+        ? ((distance % totalLength) + totalLength) % totalLength
+        : clampNumber(distance, 0, totalLength);
+    let index = segments.findIndex((candidate) => along >= candidate.start && along <= candidate.start + candidate.length);
+    if (index < 0)
+        index = segments.length - 1;
+    const segment = segments[index];
+    const t = clampNumber((along - segment.start) / segment.length, 0, 1);
+    return {
+        x: segment.from.x + (segment.to.x - segment.from.x) * t,
+        y: segment.from.y + (segment.to.y - segment.from.y) * t
+    };
+}
+function arcCurvature(segments, totalLength, distance, closed) {
+    if (segments.length < 2 || totalLength <= 1e-9)
+        return 0;
+    const meanSegment = totalLength / segments.length;
+    /*
+     * On an open path the window has to shrink near the ends rather than clamp: clamping would
+     * collapse two of the three samples onto the same point and report 0 curvature exactly where a
+     * track often turns most.
+     */
+    const room = closed ? totalLength / 3 : Math.min(distance, totalLength - distance);
+    const window = Math.min(meanSegment * CURVATURE_WINDOW_SEGMENTS, Math.max(1e-6, room));
+    if (window <= 1e-6)
+        return 0;
+    const a = positionAtDistance(segments, totalLength, distance - window, closed);
+    const b = positionAtDistance(segments, totalLength, distance, closed);
+    const c = positionAtDistance(segments, totalLength, distance + window, closed);
+    const abx = b.x - a.x;
+    const aby = b.y - a.y;
+    const bcx = c.x - b.x;
+    const bcy = c.y - b.y;
+    const acx = c.x - a.x;
+    const acy = c.y - a.y;
+    /*
+     * Menger curvature: 4 * area / (|ab| |bc| |ca|), signed by the cross product so a left-hand
+     * corner is positive. The cross product is twice the triangle area, hence the factor 2 here.
+     */
+    const cross = abx * bcy - aby * bcx;
+    const denominator = Math.hypot(abx, aby) * Math.hypot(bcx, bcy) * Math.hypot(acx, acy);
+    if (denominator <= 1e-12)
+        return 0;
+    return (2 * cross) / denominator;
+}
 function createRaceSegments(route) {
     const points = [...route.points];
     if (points.length < 2)