Function calculateNextPosition

calculateNextPosition(
    currentPos: number,
    direction: -1 | 1,
    stepSize: number,
    range: [number, number],
    discrete?: boolean,
    wrapAround?: boolean,
    snapStep?: number,
): number
Calculate the next position in a dimension after applying navigation step.

Handles dimension navigation with support for:
- Discrete (frame-based) and continuous (time-based) dimensions
- Boundary clamping or wrap-around behavior
- Rounding for discrete dimensions
- Min/max range enforcement
Parameters
- currentPos: number
  Current position value in dimension coordinates
- direction: -1 | 1
  Navigation direction: 1 for forward (]), -1 for backward ([)
- stepSize: number
  Step size to apply (from calculateStepSize)
- range: [number, number]
  Valid [min, max] bounds for this dimension
- discrete: boolean = false
  If true, rounds to the declared grid (snapStep) and treats range as an inclusive set of on-grid positions, so the cyclic period spans the range[0] + k·snapStep positions rather than the continuous max - min
- wrapAround: boolean = false
  If true, wraps at boundaries; if false, clamps to range
- snapStep: number = 1
  Grid the position snaps to for discrete dims (the dim's declared step; default 1 = classic integer frame indices). Uses the same range-min anchor as SceneDimsManager.setDimensionValue.
Returns number
New position after navigation, guaranteed to be within range
- Defined in src/scene/dims/step-math.ts:126