hevy-shared 1.0.982 → 1.0.984

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[];
@@ -208,6 +231,7 @@ export declare function pickExerciseForPrescription<T extends HevyTrainerLibrary
 }): PickExerciseResult<T>;
 export declare function pickExerciseForPrescription<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,6 +1,6 @@
 "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.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.pickExerciseForPrescription = pickExerciseForPrescription;
 exports.generateProgram = generateProgram;
 const _1 = require(".");
@@ -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);
@@ -535,15 +540,74 @@ function pickExerciseForPrescription(params) {
     }
     return pickExerciseForPrescriptionWithTrace(params).exercise;
 }
+const CARDIO_TRACE_INDEX_BEFORE_TEMPLATE = -1;
+exports.DEFAULT_TRAINER_CARDIO_ATTACHMENT_DURATION_SECONDS = 600;
+const appendCardioExerciseSelectionTrace = (traces, params) => {
+    traces.push({
+        traceKind: 'cardio',
+        routine: params.routine,
+        prescriptionIndex: params.prescriptionIndex,
+        selectedExerciseId: params.selectedExerciseId,
+        equipments: params.equipments,
+        level: params.level,
+        trace: {
+            entries: [
+                {
+                    pass: 1,
+                    label: 'cardio: first priority exercise matching equipment + level; globally excluded IDs skipped',
+                    candidatePoolSize: params.candidatePoolSize,
+                    selectedExerciseId: params.selectedExerciseId,
+                },
+            ],
+            selectedPass: 1,
+        },
+    });
+};
+/** Inserts optional cardio before or after template exercises for one routine. */
+const attachOptionalCardioToRoutine = ({ cardioPreference, cardioExercises, criteria, debugExerciseSelectionTrace, exerciseSelectionTraces, routine, templatePrescriptionCount, routineExercises, }) => {
+    if (cardioPreference === 'no-cardio')
+        return;
+    const cardioExercise = cardioExercises.find((ex) => {
+        var _a, _b, _c;
+        const equipmentCompatible = (0, exports.isEquipmentCompatible)(ex, criteria.equipments);
+        const levelCompatible = (_a = ex.level) === null || _a === void 0 ? void 0 : _a.includes(criteria.level);
+        const excluded = (_c = (_b = criteria.excludedExerciseIds) === null || _b === void 0 ? void 0 : _b.has(ex.id)) !== null && _c !== void 0 ? _c : false;
+        return equipmentCompatible && levelCompatible && !excluded;
+    });
+    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) {
+        appendCardioExerciseSelectionTrace(exerciseSelectionTraces, {
+            routine,
+            prescriptionIndex: cardioPreference === 'workout-start'
+                ? CARDIO_TRACE_INDEX_BEFORE_TEMPLATE
+                : templatePrescriptionCount,
+            selectedExerciseId: cardioExercise.id,
+            equipments: criteria.equipments,
+            level: criteria.level,
+            candidatePoolSize: cardioExercises.length,
+        });
+    }
+};
 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;
@@ -596,6 +660,7 @@ function generateProgram(params) {
                 });
                 exercise = selection.exercise;
                 exerciseSelectionTraces.push({
+                    traceKind: 'template',
                     routine,
                     prescriptionIndex,
                     prescription: exercisePrescription,
@@ -625,6 +690,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 +717,16 @@ function generateProgram(params) {
                 });
             }
         }
+        attachOptionalCardioToRoutine({
+            cardioPreference,
+            cardioExercises: sortedExercises.cardio,
+            criteria: { equipments, level, excludedExerciseIds },
+            debugExerciseSelectionTrace,
+            exerciseSelectionTraces,
+            routine,
+            templatePrescriptionCount: routineTemplate.exercises.length,
+            routineExercises,
+        });
         program.routines.push({
             name: routine,
             notes: routineTemplate.notes,

package/built/index.d.ts

@@ -651,6 +651,7 @@ 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 = 'no-cardio' | 'workout-start' | 'workout-end';
 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"];
@@ -965,6 +966,19 @@ export interface PostWorkoutRequestWorkout {
     is_biometrics_public: boolean;
     trainer_program_id: string | undefined;
 }
+export type WorkoutDataImporterReport = {
+    state: 'idle';
+} | {
+    state: 'waiting';
+} | {
+    state: 'import-exercises';
+} | {
+    state: 'import-workouts';
+    current: number;
+    total: number;
+} | {
+    state: 'rollback';
+} | never;
 export declare const isHeartRateSamples: (x: any) => x is HeartRateSample[];
 export declare const isWorkoutBiometrics: (x: any) => x is WorkoutBiometrics;
 export interface WorkoutBiometrics {
@@ -1264,11 +1278,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;
@@ -1276,13 +1292,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;
@@ -1290,9 +1308,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/tests/hevyTrainer.test.js

@@ -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 (no multi-pass picker)', () => {
+        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.982",
+  "version": "1.0.984",
   "description": "",
   "main": "built/index.js",
   "types": "built/index.d.ts",