hevy-shared 1.0.985 → 1.0.986

package/built/hevyTrainer.d.ts

@@ -1,4 +1,4 @@
-import { WeeklyTrainingFrequency, TrainingGoal, TrainingLevel, SimplifiedMuscleGroup, MuscleGroup, LibraryExercise, ExerciseCategory, GranularEquipment, HevyTrainerProgramEquipment, RestTimerLength } from '.';
+import { WeeklyTrainingFrequency, TrainingGoal, TrainingLevel, SimplifiedMuscleGroup, MuscleGroup, LibraryExercise, ExerciseCategory, GranularEquipment, HevyTrainerProgramEquipment, RestTimerLength, CardioPreference } from '.';
 export type HevyTrainerExerciseCategory = typeof hevyTrainerExerciseCategories[number];
 export type HevyTrainerRoutineName = typeof routineNames[number];
 export declare const workoutDurationOptions: readonly [40, 60, 80];
@@ -59,6 +59,7 @@ export interface ProgramGenerationParams<T extends HevyTrainerLibraryExercise> {
     exerciseStore: T[];
     focusMuscle?: SimplifiedMuscleGroup;
     excludedExerciseIds?: Set<string>;
+    cardioPreference: CardioPreference;
     /**
      * When enabled, includes exercise selection trace breadcrumbs in the result
      * for debugging. Intended for troubleshooting on backoffice; keep off in
@@ -66,7 +67,8 @@ export interface ProgramGenerationParams<T extends HevyTrainerLibraryExercise> {
      */
     debugExerciseSelectionTrace?: boolean;
 }
-export interface ProgramExerciseSelectionTraceRecord {
+export interface TemplateExerciseSelectionTraceRecord {
+    traceKind: 'template';
     routine: HevyTrainerRoutineName;
     prescriptionIndex: number;
     prescription: ExercisePrescription;
@@ -75,6 +77,16 @@ export interface ProgramExerciseSelectionTraceRecord {
     selectedExerciseId?: string;
     trace: ExerciseSelectionTrace;
 }
+export interface CardioExerciseSelectionTraceRecord {
+    traceKind: 'cardio';
+    routine: HevyTrainerRoutineName;
+    prescriptionIndex: number;
+    selectedExerciseId?: string;
+    equipments: GranularEquipment[];
+    level: TrainingLevel;
+    trace: ExerciseSelectionTrace;
+}
+export type ProgramExerciseSelectionTraceRecord = TemplateExerciseSelectionTraceRecord | CardioExerciseSelectionTraceRecord;
 export type TrainerProgramAttemptWithTraces = TrainerProgramAttempt & {
     exerciseSelectionTraces: ProgramExerciseSelectionTraceRecord[];
 };
@@ -145,7 +157,9 @@ export interface TrainerAlgorithmSettings {
     exercise_notes: ExerciseNotes;
     exercise_replacements: ExerciseReplacements;
 }
-export interface TrainerProgramExercise {
+/** Resistance prescriptions from templates (sets, reps, rest, notes). */
+export interface TrainerProgramResistanceExercise {
+    kind: 'resistance';
     exerciseTemplate: HevyTrainerLibraryExercise;
     muscleGroup: MuscleGroup | 'focus_muscle';
     category: HevyTrainerExerciseCategory;
@@ -156,6 +170,15 @@ export interface TrainerProgramExercise {
     restTimerSeconds: number;
     notes?: string;
 }
+/** Optional cardio attachment — no prescription semantics beyond exercise choice. */
+export interface TrainerProgramCardioExercise {
+    kind: 'cardio';
+    exerciseTemplate: HevyTrainerLibraryExercise;
+    durationSeconds: number;
+}
+export type TrainerProgramExercise = TrainerProgramResistanceExercise | TrainerProgramCardioExercise;
+export declare const isTrainerProgramResistanceExercise: (exercise: TrainerProgramExercise) => exercise is TrainerProgramResistanceExercise;
+export declare const isTrainerProgramCardioExercise: (exercise: TrainerProgramExercise) => exercise is TrainerProgramCardioExercise;
 export interface TrainerProgramRoutine {
     name: HevyTrainerRoutineName;
     exercises: TrainerProgramExercise[];
@@ -203,11 +226,12 @@ type PickExerciseResult<T extends HevyTrainerLibraryExercise> = {
     exercise?: T;
     trace: ExerciseSelectionTrace;
 };
-export declare function pickExerciseForPrescription<T extends HevyTrainerLibraryExercise>(params: ExerciseSelectionParams<T> & {
+export declare function pickTrainerExercise<T extends HevyTrainerLibraryExercise>(params: ExerciseSelectionParams<T> & {
     withTrace: true;
 }): PickExerciseResult<T>;
-export declare function pickExerciseForPrescription<T extends HevyTrainerLibraryExercise>(params: ExerciseSelectionParams<T>): T | undefined;
+export declare function pickTrainerExercise<T extends HevyTrainerLibraryExercise>(params: ExerciseSelectionParams<T>): T | undefined;
 export type HevyTrainerLibraryExercise = Pick<LibraryExercise, 'id' | 'title' | 'priority' | 'muscle_group' | 'other_muscles' | 'exercise_type' | 'equipment_category' | 'category' | 'level' | 'goal' | 'granular_equipments'>;
+export declare const DEFAULT_TRAINER_CARDIO_ATTACHMENT_DURATION_SECONDS = 600;
 export interface ExercisePrescriptionError {
     type: 'exercise_not_found';
     prescription: ExercisePrescription;

package/built/hevyTrainer.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getPrioritySortedExercises = exports.isEquipmentCompatible = exports.normalizeExerciseCategory = exports.getTrainerRestTimerSeconds = exports.getTrainerRepRange = exports.getTrainerSetCount = exports.programSplits = exports.frequencyMap = exports.routineNames = exports.defaultDurationPerFrequency = exports.hevyTrainerExerciseCategories = exports.granularEquipmentsToTrainerEquipments = exports.trainerEquipmentToGranularEquipments = exports.granularEquipmentDefaults = exports.trainerGymTypes = exports.workoutDurationOptions = void 0;
-exports.pickExerciseForPrescription = pickExerciseForPrescription;
+exports.DEFAULT_TRAINER_CARDIO_ATTACHMENT_DURATION_SECONDS = exports.getPrioritySortedExercises = exports.isEquipmentCompatible = exports.normalizeExerciseCategory = exports.getTrainerRestTimerSeconds = exports.getTrainerRepRange = exports.getTrainerSetCount = exports.isTrainerProgramCardioExercise = exports.isTrainerProgramResistanceExercise = exports.programSplits = exports.frequencyMap = exports.routineNames = exports.defaultDurationPerFrequency = exports.hevyTrainerExerciseCategories = exports.granularEquipmentsToTrainerEquipments = exports.trainerEquipmentToGranularEquipments = exports.granularEquipmentDefaults = exports.trainerGymTypes = exports.workoutDurationOptions = void 0;
+exports.pickTrainerExercise = pickTrainerExercise;
 exports.generateProgram = generateProgram;
 const _1 = require(".");
 exports.workoutDurationOptions = [40, 60, 80];
@@ -197,6 +197,10 @@ exports.programSplits = {
     5: ['push_1', 'pull_1', 'legs_1', 'upper_2', 'lower_2'],
     6: ['push_2_a', 'pull_2_a', 'legs_2_a', 'push_2_b', 'pull_2_b', 'legs_2_b'],
 };
+const isTrainerProgramResistanceExercise = (exercise) => exercise.kind === 'resistance';
+exports.isTrainerProgramResistanceExercise = isTrainerProgramResistanceExercise;
+const isTrainerProgramCardioExercise = (exercise) => exercise.kind === 'cardio';
+exports.isTrainerProgramCardioExercise = isTrainerProgramCardioExercise;
 const getTrainerSetCount = (trainerAlgorithmSettings, goal, frequency) => {
     return trainerAlgorithmSettings.sets[exports.frequencyMap[frequency]][goal];
 };
@@ -433,7 +437,8 @@ const isAlternativeIsolationExerciseMatch = (exercise, criteria) => {
 /**
  * Finds an exercise that matches the criteria and is not already used
  */
-const findMatchingExercise = (exercises, criteria, context) => {
+const findMatchingExercise = (exercises, //TODO: muscle group exercises
+criteria, context) => {
     return exercises.find((exercise) => {
         const matchesCriteria = isExerciseMatch(exercise, criteria);
         const isNotUsed = !isExerciseUsed(exercise, context);
@@ -450,7 +455,7 @@ const findAlternativeIsolationExercise = (exercises, criteria, context) => {
         return matchesCriteria && isNotUsed;
     });
 };
-const pickExerciseForPrescriptionWithTrace = (params) => {
+const pickTrainerExerciseWithTrace = (params) => {
     const { sortedExercises, handPickedExercises, criteria, context } = params;
     const trace = { entries: [] };
     const exercises = handPickedExercises
@@ -529,21 +534,70 @@ const pickExerciseForPrescriptionWithTrace = (params) => {
         ? { exercise, trace: Object.assign(Object.assign({}, trace), { selectedPass: 6 }) }
         : { exercise: undefined, trace };
 };
-function pickExerciseForPrescription(params) {
+function pickTrainerExercise(params) {
     if (params.withTrace) {
-        return pickExerciseForPrescriptionWithTrace(params);
+        return pickTrainerExerciseWithTrace(params);
     }
-    return pickExerciseForPrescriptionWithTrace(params).exercise;
+    return pickTrainerExerciseWithTrace(params).exercise;
 }
+const CARDIO_TRACE_INDEX_BEFORE_TEMPLATE = -1;
+exports.DEFAULT_TRAINER_CARDIO_ATTACHMENT_DURATION_SECONDS = 600;
+/** Inserts optional cardio before or after template exercises for one routine. */
+const attachOptionalCardioToRoutine = ({ cardioPreference, sortedExercises, criteria, debugExerciseSelectionTrace, exerciseSelectionTraces, routine, templatePrescriptionCount, routineExercises, }) => {
+    if (cardioPreference === 'no-cardio')
+        return;
+    // Cardio is reusable across routines, so program/routine used-id contexts are
+    // intentionally omitted — only the global excluded set applies.
+    const selectionParams = {
+        sortedExercises,
+        criteria: {
+            frequency: criteria.frequency,
+            goal: criteria.goal,
+            level: criteria.level,
+            equipments: criteria.equipments,
+            muscleGroup: 'cardio',
+            exerciseCategory: 'all',
+            routineBarbellExerciseCount: 0,
+        },
+        context: { excludedExerciseIds: criteria.excludedExerciseIds },
+    };
+    const selection = pickTrainerExercise(Object.assign(Object.assign({}, selectionParams), { withTrace: true }));
+    const cardioExercise = selection.exercise;
+    if (!cardioExercise)
+        return;
+    const slot = {
+        kind: 'cardio',
+        exerciseTemplate: cardioExercise,
+        durationSeconds: exports.DEFAULT_TRAINER_CARDIO_ATTACHMENT_DURATION_SECONDS,
+    };
+    if (cardioPreference === 'workout-start')
+        routineExercises.unshift(slot);
+    else
+        routineExercises.push(slot);
+    if (debugExerciseSelectionTrace) {
+        exerciseSelectionTraces.push({
+            traceKind: 'cardio',
+            routine,
+            prescriptionIndex: cardioPreference === 'workout-start'
+                ? CARDIO_TRACE_INDEX_BEFORE_TEMPLATE
+                : templatePrescriptionCount,
+            selectedExerciseId: cardioExercise.id,
+            equipments: criteria.equipments,
+            level: criteria.level,
+            trace: selection.trace,
+        });
+    }
+};
 function generateProgram(params) {
     var _a, _b;
-    const { trainerAlgorithmSettings, frequency, goal, level, equipments, workoutDurationMinutes, restTimerLength, exerciseStore, focusMuscle, excludedExerciseIds, debugExerciseSelectionTrace, } = params;
+    const { trainerAlgorithmSettings, frequency, goal, level, equipments, workoutDurationMinutes, restTimerLength, exerciseStore, focusMuscle, excludedExerciseIds, debugExerciseSelectionTrace, cardioPreference, } = params;
     const exerciseSelectionTraces = [];
     const routines = exports.programSplits[frequency];
     const program = {
         name: frequency,
         routines: [],
     };
+    // TODO: Rename sortedExercises to sortedExercisesByMuscleGroup or something similar
     const sortedExercises = (0, exports.getPrioritySortedExercises)(trainerAlgorithmSettings.exercise_priorities, exerciseStore);
     const programUsedExerciseIds = new Set();
     let programFocusMuscleExerciseCount = 0;
@@ -584,7 +638,7 @@ function generateProgram(params) {
             };
             let exercise;
             if (debugExerciseSelectionTrace) {
-                const selection = pickExerciseForPrescription({
+                const selection = pickTrainerExercise({
                     sortedExercises,
                     criteria,
                     context: {
@@ -596,6 +650,7 @@ function generateProgram(params) {
                 });
                 exercise = selection.exercise;
                 exerciseSelectionTraces.push({
+                    traceKind: 'template',
                     routine,
                     prescriptionIndex,
                     prescription: exercisePrescription,
@@ -606,7 +661,7 @@ function generateProgram(params) {
                 });
             }
             else {
-                exercise = pickExerciseForPrescription({
+                exercise = pickTrainerExercise({
                     sortedExercises,
                     criteria,
                     context: {
@@ -625,6 +680,7 @@ function generateProgram(params) {
                     programFocusMuscleExerciseCount++;
                 const repRange = (0, exports.getTrainerRepRange)(trainerAlgorithmSettings, goal, exercisePrescription.category);
                 routineExercises.push({
+                    kind: 'resistance',
                     exerciseTemplate: exercise,
                     muscleGroup: exercisePrescription.muscle_group,
                     category: exercisePrescription.category,
@@ -651,6 +707,16 @@ function generateProgram(params) {
                 });
             }
         }
+        attachOptionalCardioToRoutine({
+            cardioPreference,
+            sortedExercises,
+            criteria: { equipments, level, goal, frequency, excludedExerciseIds },
+            debugExerciseSelectionTrace,
+            exerciseSelectionTraces,
+            routine,
+            templatePrescriptionCount: routineTemplate.exercises.length,
+            routineExercises,
+        });
         program.routines.push({
             name: routine,
             notes: routineTemplate.notes,

package/built/index.d.ts

@@ -647,10 +647,12 @@ export declare const trainingGoals: readonly ["strength", "build_muscle", "fat_l
 export declare const trainingLevels: readonly ["beginner", "intermediate", "advanced"];
 export declare const exerciseCategories: readonly ["isolation", "compound", "assistance-compound"];
 export declare const restTimerLengths: readonly ["short", "medium", "long"];
+export declare const cardioPreferences: readonly ["no-cardio", "workout-start", "workout-end"];
 export type TrainingGoal = Lookup<typeof trainingGoals>;
 export type TrainingLevel = Lookup<typeof trainingLevels>;
 export type ExerciseCategory = Lookup<typeof exerciseCategories>;
 export type RestTimerLength = typeof restTimerLengths[number];
+export type CardioPreference = typeof cardioPreferences[number];
 export type HevyTrainerProgramEquipment = Extract<Equipment, 'barbell' | 'dumbbell' | 'machine'>;
 export declare const hevyTrainerProgramEquipments: readonly ["barbell", "dumbbell", "machine"];
 export declare const granularEquipments: readonly ["barbell", "dumbbell", "kettlebell", "plate", "medicine_ball", "ez_bar", "landmine", "trap_bar", "pullup_bar", "dip_bar", "squat_rack", "flat_bench", "adjustable_bench", "dual_cable_machine", "single_cable_machine", "lat_pulldown_cable", "leg_press_machine", "smith_machine", "t_bar", "plate_machines", "stack_machines", "treadmill", "elliptical_trainer", "rowing_machine", "spinning", "stair_machine", "air_bike", "suspension_band", "resistance_band", "battle_rope", "rings", "jump_rope"];
@@ -1277,11 +1279,13 @@ export interface HevyTrainerProgram {
     routines: HevyTrainerRoutine[];
     focus_muscle?: SimplifiedMuscleGroup;
     next_workout_index: number;
-    workout_duration_minutes?: WorkoutDurationMinutes;
+    workout_duration_minutes: WorkoutDurationMinutes;
     rest_timer_length: RestTimerLength;
+    cardio_preference: CardioPreference;
 }
 export interface PostHevyTrainerProgramRequestBody {
     program: {
+        version: 1;
         title: string;
         level: TrainingLevel;
         goal: TrainingGoal;
@@ -1289,13 +1293,15 @@ export interface PostHevyTrainerProgramRequestBody {
         weekly_frequency: WeeklyTrainingFrequency;
         focus_muscle?: SimplifiedMuscleGroup;
         routines: RoutineUpdate[];
-        next_workout_index?: number;
-        workout_duration_minutes?: WorkoutDurationMinutes;
+        next_workout_index: number;
+        workout_duration_minutes: WorkoutDurationMinutes;
         rest_timer_length: RestTimerLength;
+        cardio_preference: CardioPreference;
     };
 }
 export interface UpdateHevyTrainerProgramRequestBody {
     program: {
+        version: 1;
         programId: string;
         title: string;
         level: TrainingLevel;
@@ -1303,9 +1309,10 @@ export interface UpdateHevyTrainerProgramRequestBody {
         equipments: GranularEquipment[];
         weekly_frequency: WeeklyTrainingFrequency;
         focus_muscle?: SimplifiedMuscleGroup;
-        next_workout_index?: number;
-        workout_duration_minutes?: WorkoutDurationMinutes;
-        rest_timer_length?: RestTimerLength;
+        next_workout_index: number;
+        workout_duration_minutes: WorkoutDurationMinutes;
+        rest_timer_length: RestTimerLength;
+        cardio_preference: CardioPreference;
         routines: {
             id: string;
             title: string;

package/built/index.js

@@ -14,8 +14,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isHeartRateSamples = exports.isPublicWorkout = exports.isSetType = exports.isRPE = exports.validRpeValues = exports.isSetPersonalRecordType = exports.weeklyTrainingFrequencies = exports.isGranularEquipment = exports.granularEquipments = exports.hevyTrainerProgramEquipments = exports.restTimerLengths = exports.exerciseCategories = exports.trainingLevels = exports.trainingGoals = exports.isCustomExerciseType = exports.customExericseTypes = exports.isExerciseType = exports.exerciseTypes = exports.isExerciseRepType = exports.exerciseRepTypes = exports.isEquipmentFilter = exports.equipmentFilters = exports.isEquipment = exports.equipments = exports.simplifiedMuscleGroupToMuscleGroups = exports.isMuscleGroupFilter = exports.muscleGroupFilters = exports.isMuscleGroup = exports.muscleGroups = exports.isSimplifiedMuscleGroup = exports.simplifiedMuscleGroups = exports.miscellaneousMuscles = exports.chestMuscles = exports.backMuscles = exports.legMuscles = exports.armMuscles = exports.shoulderMuscles = exports.coreMuscles = exports.DefaultClientConfiguration = exports.parseClientAuthTokenResponse = exports.isCoachRole = exports.isErrorResponse = exports.isLivePRVolumeOption = exports.isTimerVolumeOption = exports.isWeekday = exports.orderedWeekdays = exports.isBodyMeasurementUnit = exports.isDistanceUnitShort = exports.isDistanceUnit = exports.isWeightUnit = void 0;
-exports.isOAuthScope = exports.supportedScopes = exports.isSuggestedUserSource = exports.isValidUserWorkoutMetricsType = exports.isBodyMeasurementKey = exports.measurementsList = exports.isHevyTrainerRoutine = exports.isWorkoutBiometrics = void 0;
+exports.isPublicWorkout = exports.isSetType = exports.isRPE = exports.validRpeValues = exports.isSetPersonalRecordType = exports.weeklyTrainingFrequencies = exports.isGranularEquipment = exports.granularEquipments = exports.hevyTrainerProgramEquipments = exports.cardioPreferences = exports.restTimerLengths = exports.exerciseCategories = exports.trainingLevels = exports.trainingGoals = exports.isCustomExerciseType = exports.customExericseTypes = exports.isExerciseType = exports.exerciseTypes = exports.isExerciseRepType = exports.exerciseRepTypes = exports.isEquipmentFilter = exports.equipmentFilters = exports.isEquipment = exports.equipments = exports.simplifiedMuscleGroupToMuscleGroups = exports.isMuscleGroupFilter = exports.muscleGroupFilters = exports.isMuscleGroup = exports.muscleGroups = exports.isSimplifiedMuscleGroup = exports.simplifiedMuscleGroups = exports.miscellaneousMuscles = exports.chestMuscles = exports.backMuscles = exports.legMuscles = exports.armMuscles = exports.shoulderMuscles = exports.coreMuscles = exports.DefaultClientConfiguration = exports.parseClientAuthTokenResponse = exports.isCoachRole = exports.isErrorResponse = exports.isLivePRVolumeOption = exports.isTimerVolumeOption = exports.isWeekday = exports.orderedWeekdays = exports.isBodyMeasurementUnit = exports.isDistanceUnitShort = exports.isDistanceUnit = exports.isWeightUnit = void 0;
+exports.isOAuthScope = exports.supportedScopes = exports.isSuggestedUserSource = exports.isValidUserWorkoutMetricsType = exports.isBodyMeasurementKey = exports.measurementsList = exports.isHevyTrainerRoutine = exports.isWorkoutBiometrics = exports.isHeartRateSamples = void 0;
 const typeUtils_1 = require("./typeUtils");
 __exportStar(require("./schemas"), exports);
 __exportStar(require("./constants"), exports);
@@ -230,6 +230,11 @@ exports.exerciseCategories = [
     'assistance-compound',
 ];
 exports.restTimerLengths = ['short', 'medium', 'long'];
+exports.cardioPreferences = [
+    'no-cardio',
+    'workout-start',
+    'workout-end',
+];
 exports.hevyTrainerProgramEquipments = [
     'barbell',
     'dumbbell',

package/built/tests/hevyTrainer.test.js

@@ -381,11 +381,11 @@ const chestOnlySorted = (exercises) => {
     }, {});
     return Object.assign(Object.assign({}, empty), { chest: exercises });
 };
-describe('pickExerciseForPrescription', () => {
+describe('pickTrainerExercise', () => {
     it('pass 1: returns the first matching exercise that is not used in the program', () => {
         const used = makeExercise({ id: 'used' });
         const fresh = makeExercise({ id: 'fresh' });
-        const result = (0, hevyTrainer_1.pickExerciseForPrescription)({
+        const result = (0, hevyTrainer_1.pickTrainerExercise)({
             sortedExercises: chestOnlySorted([used, fresh]),
             criteria: baseCriteria(),
             context: {
@@ -396,7 +396,7 @@ describe('pickExerciseForPrescription', () => {
     });
     it('pass 2: falls back to exercises not used in the current routine when all are used in the program', () => {
         const onlyExercise = makeExercise({ id: 'only' });
-        const result = (0, hevyTrainer_1.pickExerciseForPrescription)({
+        const result = (0, hevyTrainer_1.pickTrainerExercise)({
             sortedExercises: chestOnlySorted([onlyExercise]),
             criteria: baseCriteria(),
             context: {
@@ -411,7 +411,7 @@ describe('pickExerciseForPrescription', () => {
     it('excludes exercises in `excludedExerciseIds` across all passes', () => {
         const excluded = makeExercise({ id: 'excluded' });
         const alternative = makeExercise({ id: 'alt' });
-        const result = (0, hevyTrainer_1.pickExerciseForPrescription)({
+        const result = (0, hevyTrainer_1.pickTrainerExercise)({
             sortedExercises: chestOnlySorted([excluded, alternative]),
             criteria: baseCriteria(),
             context: {
@@ -421,7 +421,7 @@ describe('pickExerciseForPrescription', () => {
         expect(result === null || result === void 0 ? void 0 : result.id).toBe('alt');
     });
     it('returns undefined when no exercise satisfies any pass', () => {
-        const result = (0, hevyTrainer_1.pickExerciseForPrescription)({
+        const result = (0, hevyTrainer_1.pickTrainerExercise)({
             sortedExercises: chestOnlySorted([]),
             criteria: baseCriteria(),
             context: {},
@@ -437,7 +437,7 @@ describe('pickExerciseForPrescription', () => {
             id: 'bw',
             granular_equipments: [],
         });
-        const result = (0, hevyTrainer_1.pickExerciseForPrescription)({
+        const result = (0, hevyTrainer_1.pickTrainerExercise)({
             sortedExercises: chestOnlySorted([needsBarbell, bodyweight]),
             criteria: baseCriteria({ equipments: [] }),
             context: {},
@@ -448,7 +448,7 @@ describe('pickExerciseForPrescription', () => {
         const wrongLevel = makeExercise({ id: 'wrong', level: ['advanced'] });
         const wrongGoal = makeExercise({ id: 'wrongGoal', goal: ['fat_loss'] });
         const rightOne = makeExercise({ id: 'right' });
-        const result = (0, hevyTrainer_1.pickExerciseForPrescription)({
+        const result = (0, hevyTrainer_1.pickTrainerExercise)({
             sortedExercises: chestOnlySorted([wrongLevel, wrongGoal, rightOne]),
             criteria: baseCriteria({ level: 'beginner', goal: 'strength' }),
             context: {},
@@ -458,7 +458,7 @@ describe('pickExerciseForPrescription', () => {
     it('considers handpicked exercises before sortedExercises', () => {
         const hand = makeExercise({ id: 'hand' });
         const sorted = makeExercise({ id: 'sorted' });
-        const result = (0, hevyTrainer_1.pickExerciseForPrescription)({
+        const result = (0, hevyTrainer_1.pickTrainerExercise)({
             sortedExercises: chestOnlySorted([sorted]),
             handPickedExercises: [hand],
             criteria: baseCriteria(),
@@ -473,7 +473,7 @@ describe('pickExerciseForPrescription', () => {
             id: 'compound',
             category: 'compound',
         });
-        const result = (0, hevyTrainer_1.pickExerciseForPrescription)({
+        const result = (0, hevyTrainer_1.pickTrainerExercise)({
             sortedExercises: chestOnlySorted([compoundOnly]),
             criteria: baseCriteria({ exerciseCategory: 'isolation' }),
             context: {},
@@ -491,7 +491,7 @@ describe('pickExerciseForPrescription', () => {
             return acc;
         }, {});
         sorted.shoulders = [secondaryChest];
-        const result = (0, hevyTrainer_1.pickExerciseForPrescription)({
+        const result = (0, hevyTrainer_1.pickTrainerExercise)({
             sortedExercises: sorted,
             criteria: baseCriteria({ muscleGroup: 'chest' }),
             context: {},
@@ -502,7 +502,7 @@ describe('pickExerciseForPrescription', () => {
         const barbellExercise = (id) => makeExercise({ id, equipment_category: 'barbell' });
         it('allows barbell exercises regardless of count when frequency > 1', () => {
             const ex = barbellExercise('bench');
-            const result = (0, hevyTrainer_1.pickExerciseForPrescription)({
+            const result = (0, hevyTrainer_1.pickTrainerExercise)({
                 sortedExercises: chestOnlySorted([ex]),
                 criteria: baseCriteria({
                     frequency: 3,
@@ -515,7 +515,7 @@ describe('pickExerciseForPrescription', () => {
         });
         it('allows barbell exercises under the cap when frequency === 1', () => {
             const ex = barbellExercise('bench');
-            const result = (0, hevyTrainer_1.pickExerciseForPrescription)({
+            const result = (0, hevyTrainer_1.pickTrainerExercise)({
                 sortedExercises: chestOnlySorted([ex]),
                 criteria: baseCriteria({
                     frequency: 1,
@@ -528,7 +528,7 @@ describe('pickExerciseForPrescription', () => {
         });
         it('rejects barbell exercises at or over the cap when a substitute is available', () => {
             const ex = barbellExercise('bench');
-            const result = (0, hevyTrainer_1.pickExerciseForPrescription)({
+            const result = (0, hevyTrainer_1.pickTrainerExercise)({
                 sortedExercises: chestOnlySorted([ex]),
                 criteria: baseCriteria({
                     frequency: 1,
@@ -542,7 +542,7 @@ describe('pickExerciseForPrescription', () => {
         });
         it('still allows barbell exercises over the cap when the user has no substitutes', () => {
             const ex = barbellExercise('bench');
-            const result = (0, hevyTrainer_1.pickExerciseForPrescription)({
+            const result = (0, hevyTrainer_1.pickTrainerExercise)({
                 sortedExercises: chestOnlySorted([ex]),
                 criteria: baseCriteria({
                     frequency: 1,
@@ -558,7 +558,7 @@ describe('pickExerciseForPrescription', () => {
     it('returns a trace when `withTrace: true` and records the winning pass', () => {
         var _a;
         const fresh = makeExercise({ id: 'fresh' });
-        const result = (0, hevyTrainer_1.pickExerciseForPrescription)({
+        const result = (0, hevyTrainer_1.pickTrainerExercise)({
             sortedExercises: chestOnlySorted([fresh]),
             criteria: baseCriteria(),
             context: {},
@@ -572,7 +572,7 @@ describe('pickExerciseForPrescription', () => {
         });
     });
     it('returns a trace with no selected pass when nothing matches', () => {
-        const result = (0, hevyTrainer_1.pickExerciseForPrescription)({
+        const result = (0, hevyTrainer_1.pickTrainerExercise)({
             sortedExercises: chestOnlySorted([]),
             criteria: baseCriteria(),
             context: {},
@@ -608,6 +608,7 @@ describe('generateProgram', () => {
             workoutDurationMinutes: 60,
             restTimerLength: 'medium',
             exerciseStore: [chestExercise],
+            cardioPreference: 'no-cardio',
         });
         expect(result.success).toBe(true);
         if (!result.success)
@@ -619,6 +620,9 @@ describe('generateProgram', () => {
         expect(routine.notes).toBe('Hit the chest hard.');
         expect(routine.exercises).toHaveLength(1);
         const [exercise] = routine.exercises;
+        expect(exercise.kind).toBe('resistance');
+        if (exercise.kind !== 'resistance')
+            return;
         expect(exercise.exerciseTemplate.id).toBe('bench');
         expect(exercise.category).toBe('compound');
         expect(exercise.muscleGroup).toBe('chest');
@@ -642,6 +646,7 @@ describe('generateProgram', () => {
             workoutDurationMinutes: 60,
             restTimerLength: 'medium',
             exerciseStore: [],
+            cardioPreference: 'no-cardio',
         });
         expect(result.success).toBe(false);
         if (result.success)
@@ -683,6 +688,7 @@ describe('generateProgram', () => {
                 workoutDurationMinutes,
                 restTimerLength: 'medium',
                 exerciseStore: [makeExercise({ id: 'bench' })],
+                cardioPreference: 'no-cardio',
             });
             const routine = (result.success ? result.program : result.partialProgram)
                 .routines[0];
@@ -751,6 +757,7 @@ describe('generateProgram', () => {
                     makeExercise({ id: 'bench-2', priority: 2 }),
                     makeExercise({ id: 'bench-3', priority: 1 }),
                 ],
+                cardioPreference: 'no-cardio',
             });
             expect(result.success).toBe(true);
             if (!result.success)
@@ -758,7 +765,10 @@ describe('generateProgram', () => {
             // Only the 40- and 60-minute prescriptions survive; the 80-minute one
             // is filtered out. Order is preserved.
             const placed = result.program.routines[0].exercises;
-            expect(placed.map((e) => e.warmupSetCount)).toEqual([1, 2]);
+            expect(placed.every((e) => e.kind === 'resistance')).toBe(true);
+            expect(placed
+                .filter(hevyTrainer_1.isTrainerProgramResistanceExercise)
+                .map((e) => e.warmupSetCount)).toEqual([1, 2]);
         });
     });
     it('skips focus_muscle prescriptions when no focusMuscle is provided', () => {
@@ -777,6 +787,7 @@ describe('generateProgram', () => {
             exerciseStore: [
                 makeExercise({ id: 'biceps-curl', muscle_group: 'biceps' }),
             ],
+            cardioPreference: 'no-cardio',
         });
         expect(result.success).toBe(true);
         if (!result.success)
@@ -803,11 +814,15 @@ describe('generateProgram', () => {
             restTimerLength: 'medium',
             exerciseStore: [bicepsCurl],
             focusMuscle: 'arms',
+            cardioPreference: 'no-cardio',
         });
         expect(result.success).toBe(true);
         if (!result.success)
             return;
         const [exercise] = result.program.routines[0].exercises;
+        expect(exercise.kind).toBe('resistance');
+        if (exercise.kind !== 'resistance')
+            return;
         expect(exercise.exerciseTemplate.id).toBe('biceps-curl');
         expect(exercise.muscleGroup).toBe('focus_muscle');
     });
@@ -825,6 +840,7 @@ describe('generateProgram', () => {
             restTimerLength: 'medium',
             exerciseStore: [excluded, alt],
             excludedExerciseIds: new Set(['excluded']),
+            cardioPreference: 'no-cardio',
         });
         expect(result.success).toBe(true);
         if (!result.success)
@@ -844,10 +860,12 @@ describe('generateProgram', () => {
             restTimerLength: 'medium',
             exerciseStore: [chest],
             debugExerciseSelectionTrace: true,
+            cardioPreference: 'no-cardio',
         });
         expect(result.success).toBe(true);
         expect(result.exerciseSelectionTraces).toHaveLength(1);
         const [trace] = result.exerciseSelectionTraces;
+        expect(trace.traceKind).toBe('template');
         expect(trace.routine).toBe('full_body_1');
         expect(trace.selectedExerciseId).toBe('bench');
         expect(trace.trace.selectedPass).toBe(1);
@@ -876,10 +894,213 @@ describe('generateProgram', () => {
                 makeExercise({ id: 'bench-2' }),
             ],
             debugExerciseSelectionTrace: true,
+            cardioPreference: 'no-cardio',
         });
         expect(result.success).toBe(true);
         expect(result.exerciseSelectionTraces.map((t) => t.prescriptionIndex)).toEqual([0, 1]);
     });
+    it('records a single cardio trace entry on pass 1', () => {
+        const settings = makeSettings();
+        settings.templates.full_body_1 = {
+            exercises: [{ muscle_group: 'chest', category: 'compound' }],
+        };
+        settings.exercise_priorities.chest = ['bench'];
+        settings.exercise_priorities.cardio = ['run'];
+        const result = (0, hevyTrainer_1.generateProgram)({
+            trainerAlgorithmSettings: settings,
+            frequency: 1,
+            goal: 'strength',
+            level: 'beginner',
+            equipments: [],
+            workoutDurationMinutes: 60,
+            restTimerLength: 'medium',
+            exerciseStore: [
+                makeExercise({ id: 'bench', muscle_group: 'chest' }),
+                makeExercise({
+                    id: 'run',
+                    muscle_group: 'cardio',
+                    category: 'compound',
+                    equipment_category: 'other',
+                }),
+            ],
+            debugExerciseSelectionTrace: true,
+            cardioPreference: 'workout-start',
+        });
+        expect(result.success).toBe(true);
+        if (!result.success)
+            return;
+        const cardioTrace = result.exerciseSelectionTraces.find((t) => t.traceKind === 'cardio');
+        expect(cardioTrace).toBeDefined();
+        expect(cardioTrace.prescriptionIndex).toBe(-1);
+        expect(cardioTrace.trace.entries).toHaveLength(1);
+        expect(cardioTrace.trace.selectedPass).toBe(1);
+        expect(cardioTrace.trace.entries[0].selectedExerciseId).toBe('run');
+        expect(cardioTrace.equipments).toEqual([]);
+        expect(cardioTrace.level).toBe('beginner');
+    });
+    it('uses the same prioritized cardio exercise on every routine (not blocked by program reuse)', () => {
+        const settings = makeSettings();
+        settings.templates.full_body_2_a = {
+            exercises: [{ muscle_group: 'chest', category: 'compound' }],
+        };
+        settings.templates.full_body_2_b = {
+            exercises: [{ muscle_group: 'chest', category: 'compound' }],
+        };
+        settings.exercise_priorities.chest = ['bench-a', 'bench-b'];
+        settings.exercise_priorities.cardio = ['run'];
+        const result = (0, hevyTrainer_1.generateProgram)({
+            trainerAlgorithmSettings: settings,
+            frequency: 2,
+            goal: 'strength',
+            level: 'beginner',
+            equipments: [],
+            workoutDurationMinutes: 60,
+            restTimerLength: 'medium',
+            exerciseStore: [
+                makeExercise({ id: 'bench-a', muscle_group: 'chest' }),
+                makeExercise({ id: 'bench-b', muscle_group: 'chest' }),
+                makeExercise({
+                    id: 'run',
+                    muscle_group: 'cardio',
+                    category: 'compound',
+                    equipment_category: 'other',
+                }),
+            ],
+            cardioPreference: 'workout-start',
+        });
+        expect(result.success).toBe(true);
+        if (!result.success)
+            return;
+        expect(result.program.routines[0].exercises[0]).toMatchObject({
+            kind: 'cardio',
+            exerciseTemplate: { id: 'run' },
+        });
+        expect(result.program.routines[1].exercises[0]).toMatchObject({
+            kind: 'cardio',
+            exerciseTemplate: { id: 'run' },
+        });
+    });
+    it('skips cardio exercises that need equipment the user does not have', () => {
+        const settings = makeSettings();
+        settings.templates.full_body_1 = {
+            exercises: [{ muscle_group: 'chest', category: 'compound' }],
+        };
+        settings.exercise_priorities.chest = ['bench'];
+        settings.exercise_priorities.cardio = ['treadmill-run', 'body-run'];
+        const result = (0, hevyTrainer_1.generateProgram)({
+            trainerAlgorithmSettings: settings,
+            frequency: 1,
+            goal: 'strength',
+            level: 'beginner',
+            equipments: [],
+            workoutDurationMinutes: 60,
+            restTimerLength: 'medium',
+            exerciseStore: [
+                makeExercise({ id: 'bench', muscle_group: 'chest' }),
+                makeExercise({
+                    id: 'treadmill-run',
+                    muscle_group: 'cardio',
+                    category: 'compound',
+                    equipment_category: 'other',
+                    granular_equipments: ['treadmill'],
+                }),
+                makeExercise({
+                    id: 'body-run',
+                    muscle_group: 'cardio',
+                    category: 'compound',
+                    equipment_category: 'other',
+                }),
+            ],
+            cardioPreference: 'workout-start',
+        });
+        expect(result.success).toBe(true);
+        if (!result.success)
+            return;
+        expect(result.program.routines[0].exercises[0]).toMatchObject({
+            kind: 'cardio',
+            exerciseTemplate: { id: 'body-run' },
+        });
+    });
+    it('skips globally excluded cardio and uses the next priority exercise', () => {
+        const settings = makeSettings();
+        settings.templates.full_body_1 = {
+            exercises: [{ muscle_group: 'chest', category: 'compound' }],
+        };
+        settings.exercise_priorities.chest = ['bench'];
+        settings.exercise_priorities.cardio = ['run-a', 'run-b'];
+        const result = (0, hevyTrainer_1.generateProgram)({
+            trainerAlgorithmSettings: settings,
+            frequency: 1,
+            goal: 'strength',
+            level: 'beginner',
+            equipments: [],
+            workoutDurationMinutes: 60,
+            restTimerLength: 'medium',
+            exerciseStore: [
+                makeExercise({ id: 'bench', muscle_group: 'chest' }),
+                makeExercise({
+                    id: 'run-a',
+                    muscle_group: 'cardio',
+                    category: 'compound',
+                    equipment_category: 'other',
+                }),
+                makeExercise({
+                    id: 'run-b',
+                    muscle_group: 'cardio',
+                    category: 'compound',
+                    equipment_category: 'other',
+                }),
+            ],
+            excludedExerciseIds: new Set(['run-a']),
+            cardioPreference: 'workout-start',
+        });
+        expect(result.success).toBe(true);
+        if (!result.success)
+            return;
+        expect(result.program.routines[0].exercises[0]).toMatchObject({
+            kind: 'cardio',
+            exerciseTemplate: { id: 'run-b' },
+        });
+    });
+    it('keeps global trace order aligned with routine generation (no cross-routine unshift)', () => {
+        const settings = makeSettings();
+        settings.templates.full_body_2_a = {
+            exercises: [{ muscle_group: 'chest', category: 'compound' }],
+        };
+        settings.templates.full_body_2_b = {
+            exercises: [{ muscle_group: 'chest', category: 'compound' }],
+        };
+        settings.exercise_priorities.chest = ['bench-a', 'bench-b'];
+        settings.exercise_priorities.cardio = ['run'];
+        const result = (0, hevyTrainer_1.generateProgram)({
+            trainerAlgorithmSettings: settings,
+            frequency: 2,
+            goal: 'strength',
+            level: 'beginner',
+            equipments: [],
+            workoutDurationMinutes: 60,
+            restTimerLength: 'medium',
+            exerciseStore: [
+                makeExercise({ id: 'bench-a', muscle_group: 'chest' }),
+                makeExercise({ id: 'bench-b', muscle_group: 'chest' }),
+                makeExercise({
+                    id: 'run',
+                    muscle_group: 'cardio',
+                    category: 'compound',
+                    equipment_category: 'other',
+                }),
+            ],
+            debugExerciseSelectionTrace: true,
+            cardioPreference: 'workout-start',
+        });
+        expect(result.success).toBe(true);
+        if (!result.success)
+            return;
+        const idxA = result.exerciseSelectionTraces.findIndex((t) => t.routine === 'full_body_2_a');
+        const idxB = result.exerciseSelectionTraces.findIndex((t) => t.routine === 'full_body_2_b');
+        expect(idxA).toBeGreaterThanOrEqual(0);
+        expect(idxB).toBeGreaterThan(idxA);
+    });
     describe('barbell cap at frequency === 1 (end-to-end)', () => {
         it('drops the 4th+ barbell prescription when the user has a substitute', () => {
             const settings = makeSettings();
@@ -907,6 +1128,7 @@ describe('generateProgram', () => {
                 workoutDurationMinutes: 60,
                 restTimerLength: 'medium',
                 exerciseStore: exercises,
+                cardioPreference: 'no-cardio',
             });
             expect(result.success).toBe(false);
             if (result.success)
@@ -937,6 +1159,7 @@ describe('generateProgram', () => {
                 workoutDurationMinutes: 60,
                 restTimerLength: 'medium',
                 exerciseStore: exercises,
+                cardioPreference: 'no-cardio',
             });
             expect(result.success).toBe(true);
             if (!result.success)
@@ -990,24 +1213,21 @@ describe('generateProgram', () => {
                 exerciseStore: exercises,
                 focusMuscle: 'arms',
                 debugExerciseSelectionTrace: true,
+                cardioPreference: 'no-cardio',
             });
             const traces = result.exerciseSelectionTraces;
             // Counter increments once per placed focus_muscle prescription, so the
             // 4th prescription wraps back to the first entry of
             // simplifiedMuscleGroupToMuscleGroups.arms ('biceps').
-            expect(traces.map((t) => t.resolvedMuscleGroup)).toEqual([
-                'biceps',
-                'triceps',
-                'forearms',
-                'biceps',
-            ]);
+            expect(traces
+                .filter((t) => t.traceKind === 'template')
+                .map((t) => t.resolvedMuscleGroup)).toEqual(['biceps', 'triceps', 'forearms', 'biceps']);
             // The first three passes should land on the priority-matching exercise
             // (each muscle's only exercise is picked by pass 1).
-            expect(traces.slice(0, 3).map((t) => t.selectedExerciseId)).toEqual([
-                'biceps-ex',
-                'triceps-ex',
-                'forearms-ex',
-            ]);
+            expect(traces
+                .filter((t) => t.traceKind === 'template')
+                .slice(0, 3)
+                .map((t) => t.selectedExerciseId)).toEqual(['biceps-ex', 'triceps-ex', 'forearms-ex']);
         });
         it('does not advance the focus_muscle counter when a prescription is skipped for template mismatch', () => {
             // 5-day split: push_1, pull_1, legs_1, upper_2, lower_2.
@@ -1051,6 +1271,7 @@ describe('generateProgram', () => {
                 exerciseStore: exercises,
                 focusMuscle: 'legs',
                 debugExerciseSelectionTrace: true,
+                cardioPreference: 'no-cardio',
             });
             expect(result.success).toBe(true);
             if (!result.success)
@@ -1062,7 +1283,9 @@ describe('generateProgram', () => {
                 'legs_1',
                 'lower_2',
             ]);
-            expect(result.exerciseSelectionTraces.map((t) => t.resolvedMuscleGroup)).toEqual(['quadriceps', 'hamstrings']);
+            expect(result.exerciseSelectionTraces
+                .filter((t) => t.traceKind === 'template')
+                .map((t) => t.resolvedMuscleGroup)).toEqual(['quadriceps', 'hamstrings']);
         });
     });
     describe('isFocusMuscleExtraExerciseAllowed template compatibility', () => {
@@ -1088,6 +1311,7 @@ describe('generateProgram', () => {
                 exerciseStore: [candidateExercise],
                 focusMuscle,
                 debugExerciseSelectionTrace: true,
+                cardioPreference: 'no-cardio',
             });
             // Find the routine we targeted (it may not be first in the split).
             const routine = (result.success ? result.program : result.partialProgram).routines.find((r) => r.name === routineName);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hevy-shared",
-  "version": "1.0.985",
+  "version": "1.0.986",
   "description": "",
   "main": "built/index.js",
   "types": "built/index.d.ts",