@inventure71/paddockjs 2.0.0 → 3.0.0

package/src/simulation/pit/pitService.js

@@ -2,6 +2,7 @@ import { applyWheelSurfaceState } from '../vehicle/wheelSurface.js';
 import { normalizePitCrewStats } from './pitState.js';
 import { beginPitPenaltyService } from './pitPenaltyService.js';
 import { beginTireService } from './pitTireService.js';
+import { syncPitCarKinematics } from './pitKinematics.js';
 import { getPitBoxRaceDistance } from './pitOccupancy.js';
 
 export { normalizePitCrewStats };
@@ -32,6 +33,7 @@ export function beginPitService(sim, car, box) {
   car.steeringAngle = 0;
   car.yawRate = 0;
   car.turnRadius = Infinity;
+  syncPitCarKinematics(car, { physicsMode: sim.physicsMode });
   applyWheelSurfaceState(car, sim.track);
   car.progress = car.trackState.distance;
   car.raceDistance = getPitBoxRaceDistance(sim, stop, box);

package/src/simulation/pit/pitTireService.js

@@ -6,6 +6,7 @@ import {
   pitMainLanePointAt,
   routePoint,
 } from './pitRouting.js';
+import { syncPitCarKinematics } from './pitKinematics.js';
 import { getPitBoxRaceDistance, getPitStopBox } from './pitOccupancy.js';
 import { calculatePitServiceProfile } from './pitServiceProfile.js';
 import { PIT_BOX_APPROACH_DISTANCE, PIT_EXIT_RELEASE_SPEED_KPH } from './pitServiceConstants.js';
@@ -79,6 +80,7 @@ export function finishPitExit(sim, car) {
   car.speed = Math.max(car.speed, kphToSimSpeed(PIT_EXIT_RELEASE_SPEED_KPH));
   car.throttle = 0.55;
   car.brake = 0;
+  syncPitCarKinematics(car, { physicsMode: sim.physicsMode });
   applyWheelSurfaceState(car, sim.track);
   car.progress = car.trackState.distance;
   car.raceDistance = Math.max(car.raceDistance ?? 0, stop.routeEndRaceDistance ?? car.raceDistance ?? 0);

package/src/simulation/race/raceLifecycle.js

@@ -2,6 +2,7 @@ import { offsetTrackPoint, pointAt } from '../track/trackModel.js';
 import { applyWheelSurfaceState } from '../vehicle/wheelSurface.js';
 import { clamp } from '../simMath.js';
 import { nearestTrackStateForCar } from '../track/trackStatePolicy.js';
+import { freezeVehicleMotion } from '../vehicle/vehicleKinematics.js';
 
 export function setPitLaneOpenState(sim, open) {
   const next = Boolean(open);
@@ -58,12 +59,7 @@ export function holdGridCars(sim) {
     car.x = position.x;
     car.y = position.y;
     car.heading = gridPoint.heading;
-    car.speed = 0;
-    car.throttle = 0;
-    car.brake = 1;
-    car.steeringAngle = 0;
-    car.yawRate = 0;
-    car.turnRadius = Infinity;
+    freezeVehicleMotion(car, { physicsMode: sim.physicsMode });
     car.progress = gridPoint.distance;
     car.raceDistance = car.gridDistance;
     applyWheelSurfaceState(car, sim.track);

package/src/simulation/race/raceProgress.js

@@ -14,13 +14,18 @@ import {
 } from '../timing/raceTiming.js';
 import { progressDelta } from './raceDistance.js';
 import { isRaceDnf } from './retirements.js';
+import { freezeVehicleMotion } from '../vehicle/vehicleKinematics.js';
 
 export function recalculateRaceStateForSimulation(sim, { updateDrs = true } = {}) {
   sim.cars.forEach((car) => {
     const previousRaceDistance = car.raceDistance;
     if (car.destroyed || car.outOfRace) {
       applyWheelSurfaceState(car, sim.track);
-      car.speed = 0;
+      freezeVehicleMotion(car, {
+        clearManualControls: true,
+        physicsMode: sim.physicsMode,
+        stabilityState: car.destroyed ? 'destroyed' : car.stabilityState,
+      });
       car.canAttack = false;
       car.drsEligible = false;
       car.drsActive = false;

package/src/simulation/race/raceSetup.js

@@ -29,7 +29,6 @@ export function initializeRaceSimulation(simulation, {
   track = null,
   trackSeed = null,
   trackGeneration = {},
-  trackQueryIndex = true,
   physicsMode = 'arcade',
   participantInteractions = {},
   replayGhosts = [],
@@ -43,11 +42,8 @@ export function initializeRaceSimulation(simulation, {
     ...builtTrack,
     pitLane: clonePitLaneModel(builtTrack.pitLane),
   };
-  const useTrackQueryIndex = trackQueryIndex !== false;
-  if (useTrackQueryIndex) {
-    const forkedCachedIndex = forkTrackQueryIndex(builtTrack.queryIndex);
-    attachTrackQueryIndex(simulation.track, forkedCachedIndex ?? createTrackQueryIndex(simulation.track));
-  }
+  const forkedCachedIndex = forkTrackQueryIndex(builtTrack.queryIndex, simulation.track);
+  attachTrackQueryIndex(simulation.track, forkedCachedIndex ?? createTrackQueryIndex(simulation.track));
   simulation.track.timingLines = createTimingLines(simulation.track);
   simulation.trackSeed = simulation.track.seed ?? trackSeed;
   simulation.rules = normalizeRaceRules(rules);

package/src/simulation/race/raceStep.js

@@ -40,7 +40,7 @@ export function runRaceStep(simulation, dt) {
     ];
   driveCars.forEach((car) => {
     if (car.destroyed || car.outOfRace) {
-      freezeRetiredCar(car);
+      freezeRetiredCar(car, { physicsMode: simulation.physicsMode });
       return;
     }
     const orderIndex = orderedIndexById.get(car.id);
@@ -59,7 +59,7 @@ export function runRaceStep(simulation, dt) {
       throttle: controls.throttle ?? 0,
       brake: controls.brake ?? 0,
     };
-    if (simulation.physicsMode === 'simulator') {
+    if (simulation.physicsMode === 'advanced') {
       applyWheelSurfaceState(car, simulation.track);
     }
     integrateVehiclePhysics(car, controls, delta, {

package/src/simulation/race/redFlag.js

@@ -1,11 +1,11 @@
+import { freezeVehicleMotion } from '../vehicle/vehicleKinematics.js';
+
 export function applyRedFlagHoldForSimulation(sim) {
   sim.cars.forEach((car) => {
     car.previousX = car.x;
     car.previousY = car.y;
     car.previousHeading = car.heading;
-    car.speed = 0;
-    car.throttle = 0;
-    car.brake = 1;
+    freezeVehicleMotion(car, { physicsMode: sim.physicsMode });
     car.drsActive = false;
     car.drsEligible = false;
     car.drsZoneId = null;

package/src/simulation/race/safetyCar.js

@@ -1,5 +1,6 @@
 import { pointAt } from '../track/trackModel.js';
 import { kphToSimSpeed } from '../units.js';
+import { freezeVehicleMotion, syncVehicleVelocityToHeading } from '../vehicle/vehicleKinematics.js';
 
 export function setSafetyCarState(sim, deployed) {
   const next = Boolean(deployed);
@@ -60,9 +61,7 @@ export function setRedFlagState(sim, deployed) {
     sim.raceControl.mode = 'red-flag';
     sim.raceControl.frozenOrder = sim.orderedCars().map((car) => car.id);
     sim.cars.forEach((car) => {
-      car.speed = 0;
-      car.throttle = 0;
-      car.brake = 1;
+      freezeVehicleMotion(car, { physicsMode: sim.physicsMode });
       car.drsActive = false;
       car.drsEligible = false;
       car.drsZoneId = null;
@@ -75,8 +74,15 @@ export function setRedFlagState(sim, deployed) {
       ? sim.orderedCars().map((car) => car.id)
       : null;
     sim.cars.forEach((car) => {
-      if (!car.finished) {
+      if (car.destroyed || car.outOfRace) {
+        freezeVehicleMotion(car, {
+          clearManualControls: true,
+          physicsMode: sim.physicsMode,
+          stabilityState: car.destroyed ? 'destroyed' : car.stabilityState,
+        });
+      } else if (!car.finished) {
         car.speed = Math.max(car.speed, kphToSimSpeed(60));
+        if (sim.physicsMode === 'advanced') syncVehicleVelocityToHeading(car);
         car.brake = 0;
         car.throttle = Math.max(car.throttle ?? 0, 0.35);
       }

package/src/simulation/race/stalledDnf.js

@@ -1,5 +1,6 @@
 import { markCarDnf } from './retirements.js';
 import { simSpeedToKph } from '../units.js';
+import { freezeVehicleMotion } from '../vehicle/vehicleKinematics.js';
 
 const LEGAL_STALL_SURFACES = new Set(['track', 'kerb', 'pit-entry', 'pit-lane', 'pit-exit', 'pit-box']);
 
@@ -48,7 +49,7 @@ function retireStalledCar(sim, car) {
   if (car.finished || car.destroyed || car.outOfRace) return;
   car.outOfRace = true;
   markCarDnf(sim, car, { reason: 'stalled-off-track' });
-  freezeRetiredCar(car);
+  freezeRetiredCar(car, { physicsMode: sim.physicsMode });
   sim.events.unshift({
     type: 'car-dnf',
     at: sim.time,
@@ -58,27 +59,17 @@ function retireStalledCar(sim, car) {
   });
 }
 
-export function freezeRetiredCar(car) {
-  car.speed = 0;
-  car.velocityX = 0;
-  car.velocityY = 0;
-  car.throttle = 0;
-  car.brake = 1;
-  car.appliedControls = { steering: 0, throttle: 0, brake: 1 };
-  car.manualControls = null;
+export function freezeRetiredCar(car, { physicsMode = 'arcade' } = {}) {
+  freezeVehicleMotion(car, {
+    clearManualControls: true,
+    physicsMode,
+    stabilityState: 'destroyed',
+  });
   car.canAttack = false;
   car.drsActive = false;
   car.drsEligible = false;
   car.drsZoneId = null;
   car.drsZoneEnabled = false;
-  car.steeringAngle = 0;
-  car.yawRate = 0;
-  car.longitudinalAcceleration = 0;
-  car.lateralAcceleration = 0;
-  car.longitudinalG = 0;
-  car.lateralG = 0;
-  car.tractionLimited = false;
-  car.stabilityState = 'destroyed';
 }
 
 function resetStallTimer(car) {

package/src/simulation/raceSimulation.js

@@ -152,6 +152,7 @@ export class F1RaceSimulation {
       cars: this.cars,
       computeLap: (raceDistance) => this.computeLap(raceDistance),
       nearestDistanceOnRoute,
+      physicsMode: this.physicsMode,
       progressDelta,
       raceControl: this.raceControl,
       releaseRaceStart: () => this.releaseRaceStart(),

package/src/simulation/rules/rulesReview.js

@@ -11,6 +11,9 @@ function forwardVector(car) {
 }
 
 function velocityVector(car) {
+  if (Number.isFinite(car.velocityX) && Number.isFinite(car.velocityY)) {
+    return { x: car.velocityX, y: car.velocityY };
+  }
   const forward = forwardVector(car);
   return { x: forward.x * car.speed, y: forward.y * car.speed };
 }

package/src/simulation/snapshots/raceSnapshots.js

@@ -47,6 +47,7 @@ export function createVehicleSnapshotDependencies(sim) {
     simSpeedToKph,
     simUnitsToMeters,
     VEHICLE_LIMITS,
+    physicsMode: sim.physicsMode,
   };
 }
 

package/src/simulation/timing/lapTelemetry.js

@@ -33,9 +33,10 @@ function getLapTelemetryPosition(track, raceDistance, totalLaps = Infinity) {
   };
 }
 
-function createSectorProgress(position, currentSectors = null) {
+function createSectorProgress(position, currentSectors = null, { preserveCompletedSectors = false } = {}) {
   const activeIndex = clamp((position.currentSector ?? 1) - 1, 0, TELEMETRY_SECTOR_COUNT - 1);
   return createEmptySectorTimes().map((_, index) => {
+    if (preserveCompletedSectors && Number.isFinite(currentSectors?.[index])) return 1;
     if (index < activeIndex && Number.isFinite(currentSectors?.[index])) return 1;
     if (index === activeIndex) return clamp(position.currentSectorProgress ?? 0, 0, 1);
     return 0;
@@ -99,11 +100,23 @@ export function updateLapTelemetry(car, previousRaceDistance, currentTime, track
   const previousUpdateTime = Number.isFinite(telemetry.lastUpdatedAt) ? telemetry.lastUpdatedAt : currentTime;
   const elapsedTime = Math.max(0, currentTime - previousUpdateTime);
 
-  if (!Number.isFinite(previousDistance) || !Number.isFinite(currentDistance) || travelled < -1e-3 || travelled > track.length / 2) {
+  if (
+    !Number.isFinite(previousDistance) ||
+    !Number.isFinite(currentDistance) ||
+    Math.abs(travelled) > track.length / 2
+  ) {
     resetLapTelemetry(car, currentTime, track, totalLaps);
     return;
   }
 
+  if (travelled < -1e-3) {
+    syncLapTelemetryPosition(telemetry, currentTime, currentRaceDistance, track, totalLaps, {
+      preserveCompletedSectors: true,
+    });
+    telemetry.lastUpdatedAt = currentTime;
+    return;
+  }
+
   const sectorLength = getSectorLength(track);
   if (travelled > 1e-6) {
     const firstBoundary = Math.floor(previousDistance / sectorLength) + 1;
@@ -155,28 +168,34 @@ function clearFutureSectorTelemetry(telemetry) {
   }
 }
 
-function syncLiveSectorTelemetry(telemetry) {
+function syncLiveSectorTelemetry(telemetry, { preserveCompletedSectors = false } = {}) {
   const activeIndex = clamp((telemetry.currentSector ?? 1) - 1, 0, TELEMETRY_SECTOR_COUNT - 1);
 
   telemetry.liveSectors = createEmptySectorTimes();
   telemetry.currentSectors.forEach((time, index) => {
-    if (index >= activeIndex) return;
+    if (!preserveCompletedSectors && index >= activeIndex) return;
     if (!Number.isFinite(time)) return;
     telemetry.liveSectors[index] = time;
   });
-  telemetry.liveSectors[activeIndex] = telemetry.currentSectorElapsed;
+  if (!Number.isFinite(telemetry.liveSectors[activeIndex])) {
+    telemetry.liveSectors[activeIndex] = telemetry.currentSectorElapsed;
+  }
 }
 
-function syncLapTelemetryPosition(telemetry, currentTime, currentRaceDistance, track, totalLaps) {
+function syncLapTelemetryPosition(telemetry, currentTime, currentRaceDistance, track, totalLaps, {
+  preserveCompletedSectors = false,
+} = {}) {
   const position = getLapTelemetryPosition(track, currentRaceDistance, totalLaps);
   telemetry.completedLaps = position.completedLaps;
   telemetry.currentLap = position.currentLap;
   telemetry.currentSector = position.currentSector;
   telemetry.currentSectorProgress = position.currentSectorProgress;
-  clearFutureSectorTelemetry(telemetry);
-  telemetry.sectorProgress = createSectorProgress(position, telemetry.currentSectors);
+  if (!preserveCompletedSectors) clearFutureSectorTelemetry(telemetry);
+  telemetry.sectorProgress = createSectorProgress(position, telemetry.currentSectors, {
+    preserveCompletedSectors,
+  });
   telemetry.completedLaps = Math.max(telemetry.completedLaps, Math.min(position.completedLaps, totalLaps));
   telemetry.currentLapTime = Math.max(0, currentTime - telemetry.currentLapStartedAt);
   telemetry.currentSectorElapsed = Math.max(0, currentTime - telemetry.currentSectorStartedAt);
-  syncLiveSectorTelemetry(telemetry);
+  syncLiveSectorTelemetry(telemetry, { preserveCompletedSectors });
 }

package/src/simulation/track/pitLaneLayout.js

@@ -1,9 +1,9 @@
 import { clamp } from '../simMath.js';
 import { metersToSimUnits } from '../units.js';
 import { WORLD, PIT_BOX_COUNT, PIT_BOX_DEPTH, PIT_BOX_LENGTH, PIT_BOX_PAIR_GAP, PIT_BOX_TO_LANE_GAP, PIT_ENTRY_SEARCH_AFTER, PIT_ENTRY_SEARCH_BEFORE, PIT_EXIT_SEARCH_AFTER, PIT_EXIT_SEARCH_BEFORE, PIT_LANE_EDGE_GAP, PIT_LANE_ENTRY_BUFFER, PIT_LANE_EXIT_BUFFER, PIT_LANE_FINISH_RATIO, PIT_LANE_OFFSET_SEARCH_STEP, PIT_LANE_WIDTH, PIT_SERVICE_AREA_DEPTH, PIT_SERVICE_AREA_LENGTH, PIT_SERVICE_QUEUE_GAP, PIT_TEAM_COUNT, PIT_TEAM_GAP, PIT_BOXES_PER_TEAM, PIT_WORKING_LANE_GAP, PIT_WORKING_LANE_WIDTH, PIT_ACCESS_MAX_LENGTH, PIT_ACCESS_MIN_LENGTH, PIT_ACCESS_TANGENT_RATIO, PIT_TRACK_CLEARANCE_MARGIN } from './trackConstants.js';
-import { clonePoint, distance, headingVector, interpolatePitPoint, normalizeVector, pointWorldClearance, projectPitPoint, createPointBounds } from './trackMath.js';
+import { clonePoint, distance, headingVector, interpolatePitPoint, nearestPointOnPolyline, normalizeVector, pointWorldClearance, projectPitPoint, createPointBounds } from './trackMath.js';
 import { findPitAccessConnection, createPitAccessRoadCenterline } from './pitLaneAccess.js';
-import { nearestTrackState, pointAt } from './spatialQueries.js';
+import { pointAt } from './spatialQueries.js';
 
 export function createStartStraightBasis(track) {
   const finish = pointAt(track, 0);
@@ -90,7 +90,7 @@ export function scorePitLanePlacement(track, side, laneOffset, layout) {
     minimumClearance = Math.min(minimumClearance, pointWorldClearance(lanePoint), pointWorldClearance(boxPoint));
     minimumTrackClearance = Math.min(
       minimumTrackClearance,
-      nearestTrackState(track, lanePoint).crossTrackError -
+      nearestMainTrackProjection(track, lanePoint).crossTrackError -
         (track.width / 2 + (track.kerbWidth ?? 0) + PIT_TRACK_CLEARANCE_MARGIN),
     );
   }
@@ -105,6 +105,10 @@ export function scorePitLanePlacement(track, side, laneOffset, layout) {
   };
 }
 
+function nearestMainTrackProjection(track, position) {
+  return nearestPointOnPolyline(track.samples, position) ?? { crossTrackError: Infinity };
+}
+
 export function choosePitLanePlacement(track, baseLaneOffset, layout) {
   const candidates = [];
   for (let offsetStep = 0; offsetStep <= 9; offsetStep += 1) {

package/src/simulation/track/spatialQueries.js

@@ -1,5 +1,5 @@
 import { clamp, normalizeAngle, wrapDistance } from '../simMath.js';
-import { NEAREST_HINT_WINDOW_SAMPLES, PIT_LANE_WIDTH } from './trackConstants.js';
+import { PIT_LANE_WIDTH } from './trackConstants.js';
 import { nearestPitLaneState } from './pitLaneState.js';
 import { queryNearestTrackProjection } from './trackQueryIndex.js';
 
@@ -91,13 +91,10 @@ export function createTrackState(track, position, best) {
 
 export function nearestTrackState(track, position, progressHint = null, options = {}) {
   const allowPitOverride = options.allowPitOverride !== false;
-  const best = options.indexMode === 'legacy'
-    ? nearestTrackSampleLegacy(track, position, progressHint)
-    : queryNearestTrackProjection(track, position, progressHint, {
-      indexMode: options.indexMode,
-      hintMaxDistance: options.hintMaxDistance,
-    }) ??
-    nearestTrackSampleLegacy(track, position, progressHint);
+  const best = queryNearestTrackProjection(track, position, progressHint);
+  if (!best) {
+    throw new Error('nearestTrackState requires a finite position and an indexed track model. Build tracks with buildTrackModel() or createRaceSimulation().');
+  }
   const trackState = createTrackState(track, position, best);
   if (!allowPitOverride) return trackState;
   const pitState = nearestPitLaneState(track, position);
@@ -125,26 +122,6 @@ export function nearestTrackState(track, position, progressHint = null, options
   };
 }
 
-function nearestTrackSampleLegacy(track, position, progressHint = null) {
-  let nearest = null;
-
-  if (Number.isFinite(progressHint)) {
-    const centerIndex = sampleIndexAtDistance(track, progressHint);
-    nearest = nearestSampleInRange(
-      track,
-      position,
-      centerIndex - NEAREST_HINT_WINDOW_SAMPLES,
-      centerIndex + NEAREST_HINT_WINDOW_SAMPLES,
-    );
-    const fallbackDistance = track.width / 2 + (track.kerbWidth ?? 0) + track.gravelWidth + track.runoffWidth + 180;
-    if (!nearest.best || nearest.bestDistance > fallbackDistance * fallbackDistance) {
-      nearest = null;
-    }
-  }
-
-  return nearest?.best ?? nearestSampleGlobal(track, position).best;
-}
-
 export function offsetTrackPoint(point, offset) {
   return {
     x: point.x + point.normalX * offset,

package/src/simulation/track/trackQueryGrid.js

@@ -0,0 +1,94 @@
+import { clamp } from '../simMath.js';
+import { ensureQueryScratch, ensureScratchArray, nextScratchEpoch } from './trackQueryScratch.js';
+
+export function createSpatialGrid(bounds, cellSize) {
+  const columns = Math.max(1, Math.ceil((bounds.maxX - bounds.minX) / cellSize));
+  const rows = Math.max(1, Math.ceil((bounds.maxY - bounds.minY) / cellSize));
+  return {
+    bounds,
+    cellSize,
+    columns,
+    rows,
+    cells: new Array(columns * rows),
+  };
+}
+
+export function insertIdIntoGridBounds(grid, id, bounds) {
+  const minCell = gridCellForPoint(grid, { x: bounds.minX, y: bounds.minY }, true);
+  const maxCell = gridCellForPoint(grid, { x: bounds.maxX, y: bounds.maxY }, true);
+  for (let row = minCell.row; row <= maxCell.row; row += 1) {
+    for (let column = minCell.column; column <= maxCell.column; column += 1) {
+      const cellIndex = row * grid.columns + column;
+      const cell = grid.cells[cellIndex];
+      if (cell) cell.push(id);
+      else grid.cells[cellIndex] = [id];
+    }
+  }
+}
+
+export function candidateIdsFromGrid(index, grid, position, neighborLimit) {
+  const center = gridCellForPoint(grid, position, false);
+  if (!center) return [];
+  const scratch = ensureQueryScratch(index);
+  const maxId = Math.max(index.centerline.segmentCount, index.pit?.roadSegments?.length ?? 0, index.pit?.boxCandidates?.length ?? 0);
+  const idMarks = ensureScratchArray(scratch, 'candidateMarks', maxId);
+  const ids = [];
+  for (let radius = 0; radius <= neighborLimit; radius += 1) {
+    const candidateEpoch = nextScratchEpoch(scratch, 'candidateEpoch', idMarks);
+    ids.length = 0;
+    for (let row = center.row - radius; row <= center.row + radius; row += 1) {
+      for (let column = center.column - radius; column <= center.column + radius; column += 1) {
+        if (column < 0 || row < 0 || column >= grid.columns || row >= grid.rows) continue;
+        const cell = grid.cells[row * grid.columns + column];
+        if (!cell) continue;
+        for (const id of cell) {
+          if (idMarks[id] === candidateEpoch) continue;
+          idMarks[id] = candidateEpoch;
+          ids.push(id);
+        }
+      }
+    }
+    if (ids.length) return ids.slice();
+  }
+  return [];
+}
+
+export function candidateIdsFromGridBounds(index, grid, bounds) {
+  if (
+    bounds.maxX < grid.bounds.minX ||
+    bounds.minX > grid.bounds.maxX ||
+    bounds.maxY < grid.bounds.minY ||
+    bounds.minY > grid.bounds.maxY
+  ) return [];
+  const minPoint = { x: bounds.minX, y: bounds.minY };
+  const maxPoint = { x: bounds.maxX, y: bounds.maxY };
+  const minCell = gridCellForPoint(grid, minPoint, true);
+  const maxCell = gridCellForPoint(grid, maxPoint, true);
+  const scratch = ensureQueryScratch(index);
+  const maxId = Math.max(index.centerline.segmentCount, index.pit?.roadSegments?.length ?? 0, index.pit?.boxCandidates?.length ?? 0);
+  const idMarks = ensureScratchArray(scratch, 'candidateMarks', maxId);
+  const candidateEpoch = nextScratchEpoch(scratch, 'candidateEpoch', idMarks);
+  const ids = [];
+  for (let row = minCell.row; row <= maxCell.row; row += 1) {
+    for (let column = minCell.column; column <= maxCell.column; column += 1) {
+      const cell = grid.cells[row * grid.columns + column];
+      if (!cell) continue;
+      for (const id of cell) {
+        if (idMarks[id] === candidateEpoch) continue;
+        idMarks[id] = candidateEpoch;
+        ids.push(id);
+      }
+    }
+  }
+  return ids;
+}
+
+export function gridCellForPoint(grid, point, clampToGrid) {
+  const column = Math.floor((point.x - grid.bounds.minX) / grid.cellSize);
+  const row = Math.floor((point.y - grid.bounds.minY) / grid.cellSize);
+  if (!clampToGrid && (column < 0 || row < 0 || column >= grid.columns || row >= grid.rows)) return null;
+  return {
+    column: clampToGrid ? clamp(column, 0, grid.columns - 1) : column,
+    row: clampToGrid ? clamp(row, 0, grid.rows - 1) : row,
+  };
+}