move the shared TOML helpers into the utility namespace

The names are generic (makeError, requireInt, parseFile), and at global scope
with external linkage they would form an overload set with the same-named
anonymous-namespace helpers in VisualsLoader.cpp and BalancingConfig.cpp the
moment either file includes TomlHelpers.h — silently, since the signatures
differ. Namespacing keeps that door shut.

Call sites are qualified explicitly rather than pulled in with a using
directive, matching how utility::getRandomInt and friends are already called.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YHcUerKAZKWNvSKJxYKbnG

src/lib/config/CMakeLists.txt

@@ -13,6 +13,7 @@ SET(HDRS
     ${CMAKE_CURRENT_SOURCE_DIR}/SurfaceMask.h
     ${CMAKE_CURRENT_SOURCE_DIR}/BlueprintSerializer.h
     ${CMAKE_CURRENT_SOURCE_DIR}/ShipLayoutBlueprintSerializer.h
+    ${CMAKE_CURRENT_SOURCE_DIR}/TomlHelpers.h
     PARENT_SCOPE
 )
 
@@ -20,9 +21,17 @@ SET(SRCS
     ${SRCS}
     ${CMAKE_CURRENT_SOURCE_DIR}/Formula.cpp
     ${CMAKE_CURRENT_SOURCE_DIR}/ConfigLoader.cpp
+    ${CMAKE_CURRENT_SOURCE_DIR}/ConfigLoaderWorld.cpp
+    ${CMAKE_CURRENT_SOURCE_DIR}/ConfigLoaderBuildings.cpp
+    ${CMAKE_CURRENT_SOURCE_DIR}/ConfigLoaderRecipes.cpp
+    ${CMAKE_CURRENT_SOURCE_DIR}/ConfigLoaderShips.cpp
+    ${CMAKE_CURRENT_SOURCE_DIR}/ConfigLoaderStations.cpp
+    ${CMAKE_CURRENT_SOURCE_DIR}/ConfigLoaderModules.cpp
+    ${CMAKE_CURRENT_SOURCE_DIR}/ConfigLoaderUnlocks.cpp
     ${CMAKE_CURRENT_SOURCE_DIR}/SurfaceMask.cpp
     ${CMAKE_CURRENT_SOURCE_DIR}/BlueprintSerializer.cpp
     ${CMAKE_CURRENT_SOURCE_DIR}/ShipLayoutBlueprintSerializer.cpp
+    ${CMAKE_CURRENT_SOURCE_DIR}/TomlHelpers.cpp
     PARENT_SCOPE
 )
 

src/lib/config/ConfigLoader.cpp

@@ -1,779 +1,10 @@
 #include "ConfigLoader.h"
 
-#include <cstdint>
-#include <sstream>
-#include <stdexcept>
 #include <string>
 #include <unordered_set>
-#include <utility>
 #include <vector>
 
-#include <QPoint>
-
-#include "toml.hpp"
-
-#include "Rotation.h"
-#include "ShipLayout.h"
-
-namespace
-{
-
-// --- Error helpers --------------------------------------------------------
-
-std::runtime_error makeError(const std::string& file,
-                             const std::string& path,
-                             const std::string& why)
-{
-    return std::runtime_error("Config: " + file + ": '" + path + "' " + why);
-}
-
-// --- Typed accessors (throw on missing or wrong type) ---------------------
-
-int64_t requireInt(const toml::node_view<toml::node>& node,
-                   const std::string& file,
-                   const std::string& path)
-{
-    const std::optional<int64_t> value = node.value<int64_t>();
-    if (!value)
-    {
-        throw makeError(file, path, "missing or not an integer");
-    }
-    return *value;
-}
-
-double requireDouble(const toml::node_view<toml::node>& node,
-                     const std::string& file,
-                     const std::string& path)
-{
-    if (const std::optional<double> v = node.value<double>())
-    {
-        return *v;
-    }
-    if (const std::optional<int64_t> v = node.value<int64_t>())
-    {
-        return static_cast<double>(*v);
-    }
-    throw makeError(file, path, "missing or not a number");
-}
-
-std::string requireString(const toml::node_view<toml::node>& node,
-                          const std::string& file,
-                          const std::string& path)
-{
-    const std::optional<std::string> value = node.value<std::string>();
-    if (!value)
-    {
-        throw makeError(file, path, "missing or not a string");
-    }
-    return *value;
-}
-
-bool requireBool(const toml::node_view<toml::node>& node,
-                 const std::string& file,
-                 const std::string& path)
-{
-    const std::optional<bool> value = node.value<bool>();
-    if (!value)
-    {
-        throw makeError(file, path, "missing or not a boolean");
-    }
-    return *value;
-}
-
-const toml::array& requireArray(const toml::node_view<toml::node>& node,
-                                const std::string& file,
-                                const std::string& path)
-{
-    const toml::array* arr = node.as_array();
-    if (arr == nullptr)
-    {
-        throw makeError(file, path, "missing or not an array");
-    }
-    return *arr;
-}
-
-const toml::table& requireTable(const toml::node_view<toml::node>& node,
-                                const std::string& file,
-                                const std::string& path)
-{
-    const toml::table* tbl = node.as_table();
-    if (tbl == nullptr)
-    {
-        throw makeError(file, path, "missing or not a table");
-    }
-    return *tbl;
-}
-
-Formula requireFormula(const toml::node_view<toml::node>& node,
-                       const std::string& file,
-                       const std::string& path)
-{
-    const std::string source = requireString(node, file, path);
-    try
-    {
-        return Formula::compile(source);
-    }
-    catch (const std::exception& e)
-    {
-        throw makeError(file, path, std::string("formula error: ") + e.what());
-    }
-}
-
-std::vector<std::string> requireStringArray(const toml::node_view<toml::node>& node,
-                                            const std::string& file,
-                                            const std::string& path)
-{
-    const toml::array& arr = requireArray(node, file, path);
-    std::vector<std::string> result;
-    result.reserve(arr.size());
-    for (std::size_t i = 0; i < arr.size(); ++i)
-    {
-        const std::string elemPath = path + "[" + std::to_string(i) + "]";
-        const std::optional<std::string> s = arr[i].value<std::string>();
-        if (!s)
-        {
-            throw makeError(file, elemPath, "not a string");
-        }
-        result.push_back(*s);
-    }
-    return result;
-}
-
-std::vector<RecipeIngredient> parseIngredients(const toml::array& arr,
-                                               const std::string& file,
-                                               const std::string& path)
-{
-    std::vector<RecipeIngredient> result;
-    result.reserve(arr.size());
-    for (std::size_t i = 0; i < arr.size(); ++i)
-    {
-        const std::string elemPath = path + "[" + std::to_string(i) + "]";
-        const toml::table* t = arr[i].as_table();
-        if (t == nullptr)
-        {
-            throw makeError(file, elemPath, "not a table");
-        }
-
-        // We need a mutable node_view to reuse our helpers, which is fine
-        // because the helpers never mutate.
-        toml::table& mt = const_cast<toml::table&>(*t);
-
-        RecipeIngredient ing;
-        ing.item = requireString(mt["item"], file, elemPath + ".item");
-        ing.amount = static_cast<int>(requireInt(mt["amount"], file, elemPath + ".amount"));
-        result.push_back(std::move(ing));
-    }
-    return result;
-}
-
-std::vector<RecipeOutput> parseRecipeOutputs(const toml::array& arr,
-                                             const std::string& file,
-                                             const std::string& path)
-{
-    std::vector<RecipeOutput> result;
-    result.reserve(arr.size());
-    for (std::size_t i = 0; i < arr.size(); ++i)
-    {
-        const std::string elemPath = path + "[" + std::to_string(i) + "]";
-        const toml::table* t = arr[i].as_table();
-        if (t == nullptr)
-        {
-            throw makeError(file, elemPath, "not a table");
-        }
-        toml::table& mt = const_cast<toml::table&>(*t);
-
-        RecipeOutput out;
-        out.item = requireString(mt["item"], file, elemPath + ".item");
-        out.amount = static_cast<int>(requireInt(mt["amount"], file, elemPath + ".amount"));
-        if (const std::optional<double> p = mt["probability"].value<double>())
-        {
-            out.probability = *p;
-        }
-        else if (const std::optional<int64_t> p = mt["probability"].value<int64_t>())
-        {
-            out.probability = static_cast<double>(*p);
-        }
-        result.push_back(std::move(out));
-    }
-    return result;
-}
-
-toml::table parseFile(const std::string& path, const std::string& file)
-{
-    try
-    {
-        return toml::parse_file(path);
-    }
-    catch (const toml::parse_error& e)
-    {
-        std::ostringstream oss;
-        oss << "Config: " << file << ": TOML parse error: " << e.description()
-            << " at " << e.source().begin;
-        throw std::runtime_error(oss.str());
-    }
-}
-
-Rotation parseRotationString(const std::string& s)
-{
-    if (s == "east")  { return Rotation::East;  }
-    if (s == "south") { return Rotation::South; }
-    if (s == "west")  { return Rotation::West;  }
-    return Rotation::North;
-}
-
-std::vector<PlacedModule> parsePlacedModules(const toml::array& arr,
-                                             const std::string& file,
-                                             const std::string& path)
-{
-    std::vector<PlacedModule> result;
-    result.reserve(arr.size());
-    for (std::size_t i = 0; i < arr.size(); ++i)
-    {
-        const std::string elemPath = path + "[" + std::to_string(i) + "]";
-        const toml::table* t = arr[i].as_table();
-        if (t == nullptr) { continue; }
-        toml::table& mt = const_cast<toml::table&>(*t);
-
-        const std::optional<std::string> type = mt["type"].value<std::string>();
-        const std::optional<int64_t>     x    = mt["x"].value<int64_t>();
-        const std::optional<int64_t>     y    = mt["y"].value<int64_t>();
-        const std::optional<std::string> rot  = mt["rotation"].value<std::string>();
-        if (!type || !x || !y || !rot) { continue; }
-
-        PlacedModule pm;
-        pm.moduleId = *type;
-        pm.position = QPoint(static_cast<int>(*x), static_cast<int>(*y));
-        pm.rotation = parseRotationString(*rot);
-        result.push_back(std::move(pm));
-    }
-    return result;
-}
-
-}  // namespace
-
-
-// --- Per-file loaders -----------------------------------------------------
-
-WorldConfig ConfigLoader::loadWorld(const std::string& path)
-{
-    const std::string file = "world.toml";
-    toml::table tbl = parseFile(path, file);
-
-    WorldConfig cfg;
-
-    cfg.heightTiles                = static_cast<int>(requireInt(tbl["world"]["height_tiles"], file, "world.height_tiles"));
-    cfg.refundPercentage           = static_cast<int>(requireInt(tbl["world"]["refund_percentage"], file, "world.refund_percentage"));
-    cfg.deconstructionTimeSeconds  = requireDouble(tbl["world"]["deconstruction_time_seconds"], file, "world.deconstruction_time_seconds");
-    cfg.startingBuildingBlocks     = static_cast<int>(requireInt(tbl["world"]["starting_building_blocks"], file, "world.starting_building_blocks"));
-    cfg.debrisDespawnSeconds        = requireDouble(tbl["world"]["debris_despawn_seconds"], file, "world.debris_despawn_seconds");
-    cfg.scrapPerThreat             = requireDouble(tbl["world"]["scrap_per_threat"], file, "world.scrap_per_threat");
-    cfg.tileSize_m                 = requireDouble(tbl["world"]["tile_size_m"], file, "world.tile_size_m");
-    cfg.beltSpeed_tps              = requireDouble(tbl["world"]["belt_speed_mps"], file, "world.belt_speed_mps") / cfg.tileSize_m;
-    cfg.tunnelMaxDistance_tiles    = static_cast<int>(requireInt(tbl["world"]["tunnel_max_distance_tiles"], file, "world.tunnel_max_distance_tiles"));
-    cfg.departureIntervalSeconds   = requireDouble(tbl["world"]["departure_interval_seconds"], file, "world.departure_interval_seconds");
-    cfg.orbitFactor                = requireDouble(tbl["world"]["orbit_factor"], file, "world.orbit_factor");
-    cfg.rallyOrbitRadius_tiles     = requireDouble(tbl["world"]["rally_orbit_radius_tiles"], file, "world.rally_orbit_radius_tiles");
-
-    if (const std::optional<std::string> tip =
-            tbl["world"]["building_blocks_tooltip"].value<std::string>())
-    {
-        cfg.buildingBlocksTooltip = *tip;
-    }
-
-    if (const std::optional<std::string> tip =
-            tbl["world"]["artifact_tooltip"].value<std::string>())
-    {
-        cfg.artifactTooltip = *tip;
-    }
-
-    cfg.regions.asteroidWidth_tiles     = static_cast<int>(requireInt(tbl["regions"]["asteroid_width_tiles"],      file, "regions.asteroid_width_tiles"));
-    cfg.regions.playerBufferWidth_tiles = static_cast<int>(requireInt(tbl["regions"]["player_buffer_width_tiles"], file, "regions.player_buffer_width_tiles"));
-    cfg.regions.contestZoneWidth_tiles  = static_cast<int>(requireInt(tbl["regions"]["contest_zone_width_tiles"],  file, "regions.contest_zone_width_tiles"));
-    cfg.regions.enemyBufferWidth_tiles  = static_cast<int>(requireInt(tbl["regions"]["enemy_buffer_width_tiles"],  file, "regions.enemy_buffer_width_tiles"));
-
-    cfg.expansion.columnsPerExpansion_tiles   = static_cast<int>(requireInt(tbl["expansion"]["columns_per_expansion_tiles"], file, "expansion.columns_per_expansion_tiles"));
-    cfg.expansion.costBuildingBlocksFormula   = requireFormula(tbl["expansion"]["cost_building_blocks_formula"],            file, "expansion.cost_building_blocks_formula");
-
-    cfg.push.pushExpandColumns_tiles = static_cast<int>(requireInt(tbl["push"]["push_expand_columns_tiles"], file, "push.push_expand_columns_tiles"));
-    cfg.push.bossAdvanceSeconds = requireDouble(tbl["push"]["boss_advance_seconds"], file, "push.boss_advance_seconds");
-
-    cfg.waves.threatRateFormula         = requireFormula(tbl["waves"]["threat_rate_formula"],         file, "waves.threat_rate_formula");
-    cfg.waves.gapMinSeconds             = requireDouble(tbl["waves"]["gap_min_seconds"],              file, "waves.gap_min_seconds");
-    cfg.waves.gapMaxSeconds             = requireDouble(tbl["waves"]["gap_max_seconds"],              file, "waves.gap_max_seconds");
-    cfg.waves.spawnDurationSeconds      = requireDouble(tbl["waves"]["spawn_duration_seconds"],       file, "waves.spawn_duration_seconds");
-    cfg.waves.bossCountdownSeconds      = requireDouble(tbl["waves"]["boss_countdown_seconds"],       file, "waves.boss_countdown_seconds");
-    cfg.waves.bossThreatDurationSeconds = requireDouble(tbl["waves"]["boss_threat_duration_seconds"], file, "waves.boss_threat_duration_seconds");
-    cfg.waves.bossQuietBeforeSeconds    = requireDouble(tbl["waves"]["boss_quiet_before_seconds"],    file, "waves.boss_quiet_before_seconds");
-    cfg.waves.bossQuietAfterSeconds     = requireDouble(tbl["waves"]["boss_quiet_after_seconds"],     file, "waves.boss_quiet_after_seconds");
-
-    if (cfg.waves.gapMinSeconds > cfg.waves.gapMaxSeconds)
-    {
-        throw makeError(file, "waves", "gap_min_seconds > gap_max_seconds");
-    }
-
-    cfg.targeting.targetScoreFormula      = requireFormula(tbl["targeting"]["target_score_formula"],      file, "targeting.target_score_formula");
-    cfg.targeting.overclaimPenaltyFormula = requireFormula(tbl["targeting"]["overclaim_penalty_formula"], file, "targeting.overclaim_penalty_formula");
-    cfg.targeting.hysteresis              = requireDouble(tbl["targeting"]["target_hysteresis"],          file, "targeting.target_hysteresis");
-
-    cfg.artifacts.artifactChanceFormula = requireFormula(tbl["artifacts"]["artifact_chance_formula"], file, "artifacts.artifact_chance_formula");
-    cfg.artifacts.artifactWinCount      = static_cast<int>(requireInt(tbl["artifacts"]["artifact_win_count"], file, "artifacts.artifact_win_count"));
-
-    cfg.scroll.panSpeedSlow_tps       = requireDouble(tbl["scroll"]["pan_speed_slow_tiles_per_second"], file, "scroll.pan_speed_slow_tiles_per_second");
-    cfg.scroll.panSpeedFast_tps       = requireDouble(tbl["scroll"]["pan_speed_fast_tiles_per_second"], file, "scroll.pan_speed_fast_tiles_per_second");
-    cfg.scroll.panRampBandWidth_tiles = static_cast<int>(requireInt(tbl["scroll"]["pan_ramp_band_width_tiles"], file, "scroll.pan_ramp_band_width_tiles"));
-
-    return cfg;
-}
-
-BuildingsConfig ConfigLoader::loadBuildings(const std::string& path)
-{
-    const std::string file = "buildings.toml";
-    toml::table tbl = parseFile(path, file);
-
-    BuildingsConfig cfg;
-    const toml::array& arr = requireArray(tbl["building"], file, "building");
-
-    for (std::size_t i = 0; i < arr.size(); ++i)
-    {
-        const std::string elemPath = "building[" + std::to_string(i) + "]";
-        const toml::table* bt = arr[i].as_table();
-        if (bt == nullptr)
-        {
-            throw makeError(file, elemPath, "not a table");
-        }
-        toml::table& mt = const_cast<toml::table&>(*bt);
-
-        BuildingDef def;
-        def.id                      = requireString(mt["id"],                        file, elemPath + ".id");
-        def.cost                    = static_cast<int>(requireInt(mt["cost"],        file, elemPath + ".cost"));
-        def.playerPlaceable         = requireBool(mt["player_placeable"],            file, elemPath + ".player_placeable");
-        def.constructionTimeSeconds = requireDouble(mt["construction_time_seconds"], file, elemPath + ".construction_time_seconds");
-        def.surfaceMask             = requireStringArray(mt["surface_mask"],         file, elemPath + ".surface_mask");
-
-        if (mt.contains("output_buffer_capacity"))
-        {
-            def.outputBufferCapacity = static_cast<int>(
-                requireInt(mt["output_buffer_capacity"], file, elemPath + ".output_buffer_capacity"));
-        }
-
-        if (mt.contains("tooltip"))
-        {
-            def.tooltip = requireString(mt["tooltip"], file, elemPath + ".tooltip");
-        }
-
-        const std::optional<BuildingType> parsedType = parseBuildingType(def.id);
-        if (!parsedType)
-        {
-            throw makeError(file, elemPath + ".id", "unknown building id '" + def.id + "'");
-        }
-        def.type = *parsedType;
-
-        cfg.buildings.push_back(std::move(def));
-    }
-
-    return cfg;
-}
-
-RecipesConfig ConfigLoader::loadRecipes(const std::string& path)
-{
-    const std::string file = "recipes.toml";
-    toml::table tbl = parseFile(path, file);
-
-    RecipesConfig cfg;
-    const toml::array& arr = requireArray(tbl["recipe"], file, "recipe");
-
-    for (std::size_t i = 0; i < arr.size(); ++i)
-    {
-        const std::string elemPath = "recipe[" + std::to_string(i) + "]";
-        const toml::table* rt = arr[i].as_table();
-        if (rt == nullptr)
-        {
-            throw makeError(file, elemPath, "not a table");
-        }
-        toml::table& mt = const_cast<toml::table&>(*rt);
-
-        RecipeDef def;
-        def.id              = requireString(mt["id"],              file, elemPath + ".id");
-        def.durationSeconds = requireDouble(mt["duration_seconds"], file, elemPath + ".duration_seconds");
-
-        const std::string buildingId = requireString(mt["building"], file, elemPath + ".building");
-        const std::optional<BuildingType> parsedType = parseBuildingType(buildingId);
-        if (!parsedType)
-        {
-            throw makeError(file, elemPath + ".building",
-                            "unknown building id '" + buildingId + "'");
-        }
-        def.building = *parsedType;
-
-        if (def.building == BuildingType::Assembler && mt.contains("unlocked_at_start"))
-        {
-            def.unlockedAtStart = requireBool(mt["unlocked_at_start"], file,
-                elemPath + ".unlocked_at_start");
-        }
-
-        // inputs may be omitted (e.g. miner recipes). An empty array is fine.
-        if (mt.contains("inputs"))
-        {
-            const toml::array& inputs = requireArray(mt["inputs"], file, elemPath + ".inputs");
-            def.inputs = parseIngredients(inputs, file, elemPath + ".inputs");
-        }
-
-        const toml::array& outputs = requireArray(mt["outputs"], file, elemPath + ".outputs");
-        def.outputs = parseRecipeOutputs(outputs, file, elemPath + ".outputs");
-
-        // Optional icon item id (REQ-UI-RECIPE-ICON); defaults to the first output
-        // in the UI when unset. Not validated against known items here — a missing
-        // icon is not an error (REQ-UI-ITEM-ICON).
-        if (mt.contains("icon"))
-        {
-            def.icon = requireString(mt["icon"], file, elemPath + ".icon");
-        }
-
-        cfg.recipes.push_back(std::move(def));
-    }
-
-    return cfg;
-}
-
-ShipsConfig ConfigLoader::loadShips(const std::string& path)
-{
-    const std::string file = "ships.toml";
-    toml::table tbl = parseFile(path, file);
-
-    ShipsConfig cfg;
-    const toml::array& arr = requireArray(tbl["ship"], file, "ship");
-
-    for (std::size_t i = 0; i < arr.size(); ++i)
-    {
-        const std::string elemPath = "ship[" + std::to_string(i) + "]";
-        const toml::table* st = arr[i].as_table();
-        if (st == nullptr)
-        {
-            throw makeError(file, elemPath, "not a table");
-        }
-        toml::table& mt = const_cast<toml::table&>(*st);
-
-        ShipDef def;
-        def.id                 = requireString(mt["id"],                 file, elemPath + ".id");
-        def.layout             = requireStringArray(mt["layout"],       file, elemPath + ".layout");
-
-        // Schematic
-        {
-            const std::string bpPath = elemPath + ".schematic";
-            const toml::table& bpTable = requireTable(mt["schematic"], file, bpPath);
-            toml::table& bpMt = const_cast<toml::table&>(bpTable);
-
-            const toml::array& materials = requireArray(bpMt["materials"], file, bpPath + ".materials");
-            def.schematic.materials = parseIngredients(materials, file, bpPath + ".materials");
-            def.schematic.productionTimeSeconds = requireDouble(
-                bpMt["production_time_seconds"], file, bpPath + ".production_time_seconds");
-        }
-
-        // Health
-        {
-            const std::string hPath = elemPath + ".health";
-            const toml::table& hTable = requireTable(mt["health"], file, hPath);
-            toml::table& hMt = const_cast<toml::table&>(hTable);
-            def.health.hp = static_cast<float>(requireDouble(hMt["hp"], file, hPath + ".hp"));
-        }
-
-        // Movement
-        {
-            const std::string mPath = elemPath + ".movement";
-            const toml::table& mTable = requireTable(mt["movement"], file, mPath);
-            toml::table& mMt = const_cast<toml::table&>(mTable);
-            def.movement.speed_mps                    = static_cast<float>(requireDouble(mMt["speed_mps"],                    file, mPath + ".speed_mps"));
-            def.movement.mainAcceleration_mpss        = static_cast<float>(requireDouble(mMt["main_acceleration_mpss"],        file, mPath + ".main_acceleration_mpss"));
-            def.movement.maneuveringAcceleration_mpss = static_cast<float>(requireDouble(mMt["maneuvering_acceleration_mpss"], file, mPath + ".maneuvering_acceleration_mpss"));
-            def.movement.angularAcceleration_radpss   = static_cast<float>(requireDouble(mMt["angular_acceleration_radpss"],   file, mPath + ".angular_acceleration_radpss"));
-            def.movement.maxRotationSpeed_radps       = static_cast<float>(requireDouble(mMt["max_rotation_speed_radps"],       file, mPath + ".max_rotation_speed_radps"));
-        }
-
-        // Sensor
-        {
-            const std::string snsPath = elemPath + ".sensor";
-            const toml::table& snsTable = requireTable(mt["sensor"], file, snsPath);
-            toml::table& snsMt = const_cast<toml::table&>(snsTable);
-            def.sensor.sensorRange_m = static_cast<float>(requireDouble(snsMt["sensor_range_m"], file, snsPath + ".sensor_range_m"));
-        }
-
-        // Optional: default_modules (REQ-WAV-DEFAULT-MODULES)
-        if (mt.contains("default_modules"))
-        {
-            const toml::array& modArr = requireArray(mt["default_modules"], file,
-                elemPath + ".default_modules");
-            def.defaultModules = parsePlacedModules(modArr, file,
-                elemPath + ".default_modules");
-        }
-
-        cfg.ships.push_back(std::move(def));
-    }
-
-    return cfg;
-}
-
-StationsConfig ConfigLoader::loadStations(const std::string& path)
-{
-    const std::string file = "stations.toml";
-    toml::table tbl = parseFile(path, file);
-
-    StationsConfig cfg;
-
-    // HQ
-    {
-        const std::string p = "hq";
-        cfg.hq.surfaceMask = requireStringArray(tbl[p]["surface_mask"], file, p + ".surface_mask");
-        cfg.hq.hpFormula   = requireFormula(tbl[p]["hp_formula"],       file, p + ".hp_formula");
-    }
-
-    // Player station
-    {
-        const std::string p = "player_station";
-        cfg.playerStation.surfaceMask     = requireStringArray(tbl[p]["surface_mask"], file, p + ".surface_mask");
-        cfg.playerStation.level           = static_cast<int>(requireInt(tbl[p]["level"], file, p + ".level"));
-        cfg.playerStation.hpFormula       = requireFormula(tbl[p]["hp_formula"],        file, p + ".hp_formula");
-        cfg.playerStation.damageFormula   = requireFormula(tbl[p]["damage_formula"],    file, p + ".damage_formula");
-        cfg.playerStation.rangeFormula    = requireFormula(tbl[p]["range_m_formula"],     file, p + ".range_m_formula");
-        cfg.playerStation.fireRateFormula = requireFormula(tbl[p]["fire_rate_hz_formula"], file, p + ".fire_rate_hz_formula");
-        cfg.playerStation.scrapDropFormula = requireFormula(tbl[p]["scrap_drop_formula"], file, p + ".scrap_drop_formula");
-    }
-
-    // Enemy station
-    {
-        const std::string p = "enemy_station";
-        cfg.enemyStation.surfaceMask      = requireStringArray(tbl[p]["surface_mask"], file, p + ".surface_mask");
-        cfg.enemyStation.hpFormula        = requireFormula(tbl[p]["hp_formula"],         file, p + ".hp_formula");
-        cfg.enemyStation.damageFormula    = requireFormula(tbl[p]["damage_formula"],     file, p + ".damage_formula");
-        cfg.enemyStation.rangeFormula     = requireFormula(tbl[p]["range_m_formula"],      file, p + ".range_m_formula");
-        cfg.enemyStation.fireRateFormula  = requireFormula(tbl[p]["fire_rate_hz_formula"],  file, p + ".fire_rate_hz_formula");
-        cfg.enemyStation.scrapDropFormula = requireFormula(tbl[p]["scrap_drop_formula"], file, p + ".scrap_drop_formula");
-    }
-
-    return cfg;
-}
-
-// Known category→stat mappings for module stat modifier discovery.
-// addedKeySuffix: unit suffix appended before "_formula" for additive modifier keys only.
-// Multiplicative modifier keys are always dimensionless and carry no suffix.
-struct StatEntry
-{
-    const char* category;
-    const char* stat;
-    const char* addedKeySuffix;
-};
-
-static const StatEntry kKnownStats[] = {
-    {"health",   "hp",                        ""},
-    {"movement", "speed",                     "_mps"},
-    {"movement", "main_acceleration",         "_mpss"},
-    {"movement", "maneuvering_acceleration",  "_mpss"},
-    {"sensor",   "sensor_range",              "_m"},
-    {"weapon",   "damage",                    ""},
-    {"weapon",   "attack_range",              "_m"},
-    {"weapon",   "attack_rate",               "_hz"},
-    {"salvage",  "collection_range",          "_m"},
-    {"salvage",  "collection_rate",           "_hz"},
-    {"cargo",    "cargo_capacity",            ""},
-    {"repair",   "repair_rate",               "_hz"},
-    {"repair",   "repair_range",              "_m"},
-};
-
-ModulesConfig ConfigLoader::loadModules(const std::string& path)
-{
-    const std::string file = "modules.toml";
-    toml::table tbl = parseFile(path, file);
-
-    ModulesConfig cfg;
-
-    if (!tbl.contains("module"))
-    {
-        return cfg;
-    }
-
-    const toml::array& arr = requireArray(tbl["module"], file, "module");
-
-    for (std::size_t i = 0; i < arr.size(); ++i)
-    {
-        const std::string elemPath = "module[" + std::to_string(i) + "]";
-        const toml::table* st = arr[i].as_table();
-        if (st == nullptr)
-        {
-            throw makeError(file, elemPath, "not a table");
-        }
-        toml::table& mt = const_cast<toml::table&>(*st);
-
-        ModuleDef def;
-        def.id                      = requireString(mt["id"], file, elemPath + ".id");
-        def.surfaceMask             = requireStringArray(mt["surface_mask"], file, elemPath + ".surface_mask");
-        def.productionTimeSeconds = requireDouble(
-            mt["production_time_seconds"], file, elemPath + ".production_time_seconds");
-        def.fillColor             = requireString(mt["fill_color"], file, elemPath + ".fill_color");
-        def.glyph                 = requireString(mt["glyph"], file, elemPath + ".glyph");
-
-        if (mt.contains("tooltip"))
-        {
-            def.tooltip = requireString(mt["tooltip"], file, elemPath + ".tooltip");
-        }
-
-        // Materials
-        {
-            const toml::array& materials = requireArray(mt["materials"], file, elemPath + ".materials");
-            def.materials = parseIngredients(materials, file, elemPath + ".materials");
-        }
-
-        // Stat modifiers from [module.<category>] sub-tables
-        for (const StatEntry& se : kKnownStats)
-        {
-            if (!mt.contains(se.category))
-            {
-                continue;
-            }
-            const toml::table& catTable = requireTable(mt[se.category], file,
-                elemPath + "." + se.category);
-            toml::table& catMt = const_cast<toml::table&>(catTable);
-
-            const std::string addedKey      = std::string("added_") + se.stat + se.addedKeySuffix;
-            const std::string multipliedKey = std::string("multiplied_") + se.stat + se.addedKeySuffix;
-
-            if (catMt.contains(addedKey))
-            {
-                ModuleStatModifier mod;
-                mod.stat         = se.stat;
-                mod.modifierType = "additive";
-                mod.value        = requireDouble(catMt[addedKey], file,
-                    elemPath + "." + se.category + "." + addedKey);
-                def.statModifiers.push_back(std::move(mod));
-            }
-
-            if (catMt.contains(multipliedKey))
-            {
-                ModuleStatModifier mod;
-                mod.stat         = se.stat;
-                mod.modifierType = "multiplicative";
-                mod.value        = requireDouble(catMt[multipliedKey], file,
-                    elemPath + "." + se.category + "." + multipliedKey);
-                def.statModifiers.push_back(std::move(mod));
-            }
-        }
-
-        // Weapon capability section: [module.weapon] with base stat formulas
-        if (mt.contains("weapon"))
-        {
-            const std::string wPath = elemPath + ".weapon";
-            const toml::table& wTable = requireTable(mt["weapon"], file, wPath);
-            toml::table& wMt = const_cast<toml::table&>(wTable);
-            if (wMt.contains("damage") || wMt.contains("attack_range_m")
-                || wMt.contains("attack_rate_hz"))
-            {
-                ModuleWeaponCapability cap;
-                cap.damage        = static_cast<float>(requireDouble(wMt["damage"],
-                    file, wPath + ".damage"));
-                cap.attackRange_m = static_cast<float>(requireDouble(wMt["attack_range_m"],
-                    file, wPath + ".attack_range_m"));
-                cap.attackRate_hz = static_cast<float>(requireDouble(wMt["attack_rate_hz"],
-                    file, wPath + ".attack_rate_hz"));
-                def.weaponCapability = std::move(cap);
-            }
-        }
-
-        // Salvage capability section: [module.salvage] with base stat formulas
-        if (mt.contains("salvage"))
-        {
-            const std::string sPath = elemPath + ".salvage";
-            const toml::table& sTable = requireTable(mt["salvage"], file, sPath);
-            toml::table& sMt = const_cast<toml::table&>(sTable);
-            if (sMt.contains("collection_range_m") || sMt.contains("cargo_capacity")
-                || sMt.contains("collection_rate_hz"))
-            {
-                ModuleSalvageCapability cap;
-                cap.collectionRange_m = static_cast<float>(requireDouble(sMt["collection_range_m"],
-                    file, sPath + ".collection_range_m"));
-                cap.cargoCapacity     = static_cast<float>(requireDouble(sMt["cargo_capacity"],
-                    file, sPath + ".cargo_capacity"));
-                cap.collectionRate_hz = static_cast<float>(requireDouble(sMt["collection_rate_hz"],
-                    file, sPath + ".collection_rate_hz"));
-                def.salvageCapability = std::move(cap);
-            }
-        }
-
-        // Repair capability section: [module.repair] with base stat formulas
-        if (mt.contains("repair"))
-        {
-            const std::string rPath = elemPath + ".repair";
-            const toml::table& rTable = requireTable(mt["repair"], file, rPath);
-            toml::table& rMt = const_cast<toml::table&>(rTable);
-            if (rMt.contains("repair_rate_hz") || rMt.contains("repair_range_m"))
-            {
-                ModuleRepairCapability cap;
-                cap.repairRate_hz   = static_cast<float>(requireDouble(rMt["repair_rate_hz"],
-                    file, rPath + ".repair_rate_hz"));
-                cap.repairAmountHp  = static_cast<float>(requireDouble(rMt["repair_amount_hp"],
-                    file, rPath + ".repair_amount_hp"));
-                cap.repairRange_m   = static_cast<float>(requireDouble(rMt["repair_range_m"],
-                    file, rPath + ".repair_range_m"));
-                def.repairCapability = std::move(cap);
-            }
-        }
-
-        cfg.modules.push_back(std::move(def));
-    }
-
-    return cfg;
-}
-
-UnlocksConfig ConfigLoader::loadUnlocks(const std::string& path)
-{
-    const std::string file = "unlocks.toml";
-    toml::table tbl = parseFile(path, file);
-
-    UnlocksConfig cfg;
-    if (!tbl.contains("unlock"))
-    {
-        return cfg;
-    }
-
-    const toml::array& arr = requireArray(tbl["unlock"], file, "unlock");
-
-    for (std::size_t i = 0; i < arr.size(); ++i)
-    {
-        const std::string elemPath = "unlock[" + std::to_string(i) + "]";
-        const toml::table* ut = arr[i].as_table();
-        if (ut == nullptr)
-        {
-            throw makeError(file, elemPath, "not a table");
-        }
-        toml::table& mt = const_cast<toml::table&>(*ut);
-
-        UnlockGroupDef def;
-        def.id           = requireString(mt["id"], file, elemPath + ".id");
-        def.stationLevel = static_cast<int>(
-            requireInt(mt["station_level"], file, elemPath + ".station_level"));
-        if (mt.contains("requires"))
-        {
-            def.requiredGroupIds = requireStringArray(mt["requires"], file, elemPath + ".requires");
-        }
-        if (mt.contains("ships"))
-        {
-            def.ships = requireStringArray(mt["ships"], file, elemPath + ".ships");
-        }
-        if (mt.contains("modules"))
-        {
-            def.modules = requireStringArray(mt["modules"], file, elemPath + ".modules");
-        }
-        if (mt.contains("buildings"))
-        {
-            def.buildings = requireStringArray(mt["buildings"], file, elemPath + ".buildings");
-        }
-        if (mt.contains("recipes"))
-        {
-            def.recipes = requireStringArray(mt["recipes"], file, elemPath + ".recipes");
-        }
-
-        cfg.groups.push_back(std::move(def));
-    }
-
-    return cfg;
-}
+#include "TomlHelpers.h"
 
 namespace
 {
@@ -815,11 +46,11 @@ void validateUnlocks(const GameConfig& cfg)
         {
             if (valid.count(id) == 0)
             {
-                throw makeError(file, gPath, "grants unknown " + kind + " '" + id + "'");
+                throw utility::makeError(file, gPath, "grants unknown " + kind + " '" + id + "'");
             }
             if (!granted.insert(id).second)
             {
-                throw makeError(file, gPath,
+                throw utility::makeError(file, gPath,
                     "grants " + kind + " '" + id + "' which is already granted by another unlock group");
             }
         }
@@ -830,13 +61,13 @@ void validateUnlocks(const GameConfig& cfg)
         const std::string gPath = "unlock '" + group.id + "'";
         if (!groupIds.insert(group.id).second)
         {
-            throw makeError(file, gPath, "duplicate unlock group id");
+            throw utility::makeError(file, gPath, "duplicate unlock group id");
         }
 
         if (group.ships.empty() && group.modules.empty()
             && group.buildings.empty() && group.recipes.empty())
         {
-            throw makeError(file, gPath, "grants no items (must grant at least one)");
+            throw utility::makeError(file, gPath, "grants no items (must grant at least one)");
         }
 
         checkGrants(group.ships,     shipIds,            grantedShipIds,     "ship",             gPath);
@@ -852,7 +83,7 @@ void validateUnlocks(const GameConfig& cfg)
         {
             if (groupIds.count(req) == 0)
             {
-                throw makeError(file, "unlock '" + group.id + "'.requires",
+                throw utility::makeError(file, "unlock '" + group.id + "'.requires",
                     "references unknown unlock group '" + req + "'");
             }
         }

src/lib/config/ConfigLoaderBuildings.cpp

@@ -0,0 +1,58 @@
+#include "ConfigLoader.h"
+
+#include <optional>
+#include <string>
+#include <utility>
+
+#include "toml.hpp"
+
+#include "TomlHelpers.h"
+
+BuildingsConfig ConfigLoader::loadBuildings(const std::string& path)
+{
+    const std::string file = "buildings.toml";
+    toml::table tbl = utility::parseFile(path, file);
+
+    BuildingsConfig cfg;
+    const toml::array& arr = utility::requireArray(tbl["building"], file, "building");
+
+    for (std::size_t i = 0; i < arr.size(); ++i)
+    {
+        const std::string elemPath = "building[" + std::to_string(i) + "]";
+        const toml::table* bt = arr[i].as_table();
+        if (bt == nullptr)
+        {
+            throw utility::makeError(file, elemPath, "not a table");
+        }
+        toml::table& mt = const_cast<toml::table&>(*bt);
+
+        BuildingDef def;
+        def.id                      = utility::requireString(mt["id"],                        file, elemPath + ".id");
+        def.cost                    = static_cast<int>(utility::requireInt(mt["cost"],        file, elemPath + ".cost"));
+        def.playerPlaceable         = utility::requireBool(mt["player_placeable"],            file, elemPath + ".player_placeable");
+        def.constructionTimeSeconds = utility::requireDouble(mt["construction_time_seconds"], file, elemPath + ".construction_time_seconds");
+        def.surfaceMask             = utility::requireStringArray(mt["surface_mask"],         file, elemPath + ".surface_mask");
+
+        if (mt.contains("output_buffer_capacity"))
+        {
+            def.outputBufferCapacity = static_cast<int>(
+                utility::requireInt(mt["output_buffer_capacity"], file, elemPath + ".output_buffer_capacity"));
+        }
+
+        if (mt.contains("tooltip"))
+        {
+            def.tooltip = utility::requireString(mt["tooltip"], file, elemPath + ".tooltip");
+        }
+
+        const std::optional<BuildingType> parsedType = parseBuildingType(def.id);
+        if (!parsedType)
+        {
+            throw utility::makeError(file, elemPath + ".id", "unknown building id '" + def.id + "'");
+        }
+        def.type = *parsedType;
+
+        cfg.buildings.push_back(std::move(def));
+    }
+
+    return cfg;
+}

src/lib/config/ConfigLoaderModules.cpp

@@ -0,0 +1,182 @@
+#include "ConfigLoader.h"
+
+#include <string>
+#include <utility>
+
+#include "toml.hpp"
+
+#include "TomlHelpers.h"
+
+namespace
+{
+
+// Known category→stat mappings for module stat modifier discovery.
+// addedKeySuffix: unit suffix appended before "_formula" for additive modifier keys only.
+// Multiplicative modifier keys are always dimensionless and carry no suffix.
+struct StatEntry
+{
+    const char* category;
+    const char* stat;
+    const char* addedKeySuffix;
+};
+
+static const StatEntry kKnownStats[] = {
+    {"health",   "hp",                        ""},
+    {"movement", "speed",                     "_mps"},
+    {"movement", "main_acceleration",         "_mpss"},
+    {"movement", "maneuvering_acceleration",  "_mpss"},
+    {"sensor",   "sensor_range",              "_m"},
+    {"weapon",   "damage",                    ""},
+    {"weapon",   "attack_range",              "_m"},
+    {"weapon",   "attack_rate",               "_hz"},
+    {"salvage",  "collection_range",          "_m"},
+    {"salvage",  "collection_rate",           "_hz"},
+    {"cargo",    "cargo_capacity",            ""},
+    {"repair",   "repair_rate",               "_hz"},
+    {"repair",   "repair_range",              "_m"},
+};
+
+}  // namespace
+
+ModulesConfig ConfigLoader::loadModules(const std::string& path)
+{
+    const std::string file = "modules.toml";
+    toml::table tbl = utility::parseFile(path, file);
+
+    ModulesConfig cfg;
+
+    if (!tbl.contains("module"))
+    {
+        return cfg;
+    }
+
+    const toml::array& arr = utility::requireArray(tbl["module"], file, "module");
+
+    for (std::size_t i = 0; i < arr.size(); ++i)
+    {
+        const std::string elemPath = "module[" + std::to_string(i) + "]";
+        const toml::table* st = arr[i].as_table();
+        if (st == nullptr)
+        {
+            throw utility::makeError(file, elemPath, "not a table");
+        }
+        toml::table& mt = const_cast<toml::table&>(*st);
+
+        ModuleDef def;
+        def.id                      = utility::requireString(mt["id"], file, elemPath + ".id");
+        def.surfaceMask             = utility::requireStringArray(mt["surface_mask"], file, elemPath + ".surface_mask");
+        def.productionTimeSeconds = utility::requireDouble(
+            mt["production_time_seconds"], file, elemPath + ".production_time_seconds");
+        def.fillColor             = utility::requireString(mt["fill_color"], file, elemPath + ".fill_color");
+        def.glyph                 = utility::requireString(mt["glyph"], file, elemPath + ".glyph");
+
+        if (mt.contains("tooltip"))
+        {
+            def.tooltip = utility::requireString(mt["tooltip"], file, elemPath + ".tooltip");
+        }
+
+        // Materials
+        {
+            const toml::array& materials = utility::requireArray(mt["materials"], file, elemPath + ".materials");
+            def.materials = utility::parseIngredients(materials, file, elemPath + ".materials");
+        }
+
+        // Stat modifiers from [module.<category>] sub-tables
+        for (const StatEntry& se : kKnownStats)
+        {
+            if (!mt.contains(se.category))
+            {
+                continue;
+            }
+            const toml::table& catTable = utility::requireTable(mt[se.category], file,
+                elemPath + "." + se.category);
+            toml::table& catMt = const_cast<toml::table&>(catTable);
+
+            const std::string addedKey      = std::string("added_") + se.stat + se.addedKeySuffix;
+            const std::string multipliedKey = std::string("multiplied_") + se.stat + se.addedKeySuffix;
+
+            if (catMt.contains(addedKey))
+            {
+                ModuleStatModifier mod;
+                mod.stat         = se.stat;
+                mod.modifierType = "additive";
+                mod.value        = utility::requireDouble(catMt[addedKey], file,
+                    elemPath + "." + se.category + "." + addedKey);
+                def.statModifiers.push_back(std::move(mod));
+            }
+
+            if (catMt.contains(multipliedKey))
+            {
+                ModuleStatModifier mod;
+                mod.stat         = se.stat;
+                mod.modifierType = "multiplicative";
+                mod.value        = utility::requireDouble(catMt[multipliedKey], file,
+                    elemPath + "." + se.category + "." + multipliedKey);
+                def.statModifiers.push_back(std::move(mod));
+            }
+        }
+
+        // Weapon capability section: [module.weapon] with base stat formulas
+        if (mt.contains("weapon"))
+        {
+            const std::string wPath = elemPath + ".weapon";
+            const toml::table& wTable = utility::requireTable(mt["weapon"], file, wPath);
+            toml::table& wMt = const_cast<toml::table&>(wTable);
+            if (wMt.contains("damage") || wMt.contains("attack_range_m")
+                || wMt.contains("attack_rate_hz"))
+            {
+                ModuleWeaponCapability cap;
+                cap.damage        = static_cast<float>(utility::requireDouble(wMt["damage"],
+                    file, wPath + ".damage"));
+                cap.attackRange_m = static_cast<float>(utility::requireDouble(wMt["attack_range_m"],
+                    file, wPath + ".attack_range_m"));
+                cap.attackRate_hz = static_cast<float>(utility::requireDouble(wMt["attack_rate_hz"],
+                    file, wPath + ".attack_rate_hz"));
+                def.weaponCapability = std::move(cap);
+            }
+        }
+
+        // Salvage capability section: [module.salvage] with base stat formulas
+        if (mt.contains("salvage"))
+        {
+            const std::string sPath = elemPath + ".salvage";
+            const toml::table& sTable = utility::requireTable(mt["salvage"], file, sPath);
+            toml::table& sMt = const_cast<toml::table&>(sTable);
+            if (sMt.contains("collection_range_m") || sMt.contains("cargo_capacity")
+                || sMt.contains("collection_rate_hz"))
+            {
+                ModuleSalvageCapability cap;
+                cap.collectionRange_m = static_cast<float>(utility::requireDouble(sMt["collection_range_m"],
+                    file, sPath + ".collection_range_m"));
+                cap.cargoCapacity     = static_cast<float>(utility::requireDouble(sMt["cargo_capacity"],
+                    file, sPath + ".cargo_capacity"));
+                cap.collectionRate_hz = static_cast<float>(utility::requireDouble(sMt["collection_rate_hz"],
+                    file, sPath + ".collection_rate_hz"));
+                def.salvageCapability = std::move(cap);
+            }
+        }
+
+        // Repair capability section: [module.repair] with base stat formulas
+        if (mt.contains("repair"))
+        {
+            const std::string rPath = elemPath + ".repair";
+            const toml::table& rTable = utility::requireTable(mt["repair"], file, rPath);
+            toml::table& rMt = const_cast<toml::table&>(rTable);
+            if (rMt.contains("repair_rate_hz") || rMt.contains("repair_range_m"))
+            {
+                ModuleRepairCapability cap;
+                cap.repairRate_hz   = static_cast<float>(utility::requireDouble(rMt["repair_rate_hz"],
+                    file, rPath + ".repair_rate_hz"));
+                cap.repairAmountHp  = static_cast<float>(utility::requireDouble(rMt["repair_amount_hp"],
+                    file, rPath + ".repair_amount_hp"));
+                cap.repairRange_m   = static_cast<float>(utility::requireDouble(rMt["repair_range_m"],
+                    file, rPath + ".repair_range_m"));
+                def.repairCapability = std::move(cap);
+            }
+        }
+
+        cfg.modules.push_back(std::move(def));
+    }
+
+    return cfg;
+}

src/lib/config/ConfigLoaderRecipes.cpp

@@ -0,0 +1,109 @@
+#include "ConfigLoader.h"
+
+#include <cstdint>
+#include <optional>
+#include <string>
+#include <utility>
+#include <vector>
+
+#include "toml.hpp"
+
+#include "TomlHelpers.h"
+
+namespace
+{
+
+std::vector<RecipeOutput> parseRecipeOutputs(const toml::array& arr,
+                                             const std::string& file,
+                                             const std::string& path)
+{
+    std::vector<RecipeOutput> result;
+    result.reserve(arr.size());
+    for (std::size_t i = 0; i < arr.size(); ++i)
+    {
+        const std::string elemPath = path + "[" + std::to_string(i) + "]";
+        const toml::table* t = arr[i].as_table();
+        if (t == nullptr)
+        {
+            throw utility::makeError(file, elemPath, "not a table");
+        }
+        toml::table& mt = const_cast<toml::table&>(*t);
+
+        RecipeOutput out;
+        out.item = utility::requireString(mt["item"], file, elemPath + ".item");
+        out.amount = static_cast<int>(utility::requireInt(mt["amount"], file, elemPath + ".amount"));
+        if (const std::optional<double> p = mt["probability"].value<double>())
+        {
+            out.probability = *p;
+        }
+        else if (const std::optional<int64_t> p = mt["probability"].value<int64_t>())
+        {
+            out.probability = static_cast<double>(*p);
+        }
+        result.push_back(std::move(out));
+    }
+    return result;
+}
+
+}  // namespace
+
+RecipesConfig ConfigLoader::loadRecipes(const std::string& path)
+{
+    const std::string file = "recipes.toml";
+    toml::table tbl = utility::parseFile(path, file);
+
+    RecipesConfig cfg;
+    const toml::array& arr = utility::requireArray(tbl["recipe"], file, "recipe");
+
+    for (std::size_t i = 0; i < arr.size(); ++i)
+    {
+        const std::string elemPath = "recipe[" + std::to_string(i) + "]";
+        const toml::table* rt = arr[i].as_table();
+        if (rt == nullptr)
+        {
+            throw utility::makeError(file, elemPath, "not a table");
+        }
+        toml::table& mt = const_cast<toml::table&>(*rt);
+
+        RecipeDef def;
+        def.id              = utility::requireString(mt["id"],              file, elemPath + ".id");
+        def.durationSeconds = utility::requireDouble(mt["duration_seconds"], file, elemPath + ".duration_seconds");
+
+        const std::string buildingId = utility::requireString(mt["building"], file, elemPath + ".building");
+        const std::optional<BuildingType> parsedType = parseBuildingType(buildingId);
+        if (!parsedType)
+        {
+            throw utility::makeError(file, elemPath + ".building",
+                            "unknown building id '" + buildingId + "'");
+        }
+        def.building = *parsedType;
+
+        if (def.building == BuildingType::Assembler && mt.contains("unlocked_at_start"))
+        {
+            def.unlockedAtStart = utility::requireBool(mt["unlocked_at_start"], file,
+                elemPath + ".unlocked_at_start");
+        }
+
+        // inputs may be omitted (e.g. miner recipes). An empty array is fine.
+        if (mt.contains("inputs"))
+        {
+            const toml::array& inputs = utility::requireArray(mt["inputs"], file, elemPath + ".inputs");
+            def.inputs = utility::parseIngredients(inputs, file, elemPath + ".inputs");
+        }
+
+        const toml::array& outputs = utility::requireArray(mt["outputs"], file, elemPath + ".outputs");
+        def.outputs = parseRecipeOutputs(outputs, file, elemPath + ".outputs");
+
+        // Optional icon item id (REQ-UI-RECIPE-ICON); defaults to the first output
+        // in the UI when unset. Not validated against known items here — a missing
+        // icon is not an error (REQ-UI-ITEM-ICON).
+        if (mt.contains("icon"))
+        {
+            def.icon = utility::requireString(mt["icon"], file, elemPath + ".icon");
+        }
+
+        cfg.recipes.push_back(std::move(def));
+    }
+
+    return cfg;
+}

src/lib/config/ConfigLoaderShips.cpp

@@ -0,0 +1,133 @@
+#include "ConfigLoader.h"
+
+#include <cstdint>
+#include <optional>
+#include <string>
+#include <utility>
+#include <vector>
+
+#include <QPoint>
+
+#include "toml.hpp"
+
+#include "Rotation.h"
+#include "ShipLayout.h"
+#include "TomlHelpers.h"
+
+namespace
+{
+
+Rotation parseRotationString(const std::string& s)
+{
+    if (s == "east")  { return Rotation::East;  }
+    if (s == "south") { return Rotation::South; }
+    if (s == "west")  { return Rotation::West;  }
+    return Rotation::North;
+}
+
+std::vector<PlacedModule> parsePlacedModules(const toml::array& arr,
+                                             const std::string& file,
+                                             const std::string& path)
+{
+    std::vector<PlacedModule> result;
+    result.reserve(arr.size());
+    for (std::size_t i = 0; i < arr.size(); ++i)
+    {
+        const std::string elemPath = path + "[" + std::to_string(i) + "]";
+        const toml::table* t = arr[i].as_table();
+        if (t == nullptr) { continue; }
+        toml::table& mt = const_cast<toml::table&>(*t);
+
+        const std::optional<std::string> type = mt["type"].value<std::string>();
+        const std::optional<int64_t>     x    = mt["x"].value<int64_t>();
+        const std::optional<int64_t>     y    = mt["y"].value<int64_t>();
+        const std::optional<std::string> rot  = mt["rotation"].value<std::string>();
+        if (!type || !x || !y || !rot) { continue; }
+
+        PlacedModule pm;
+        pm.moduleId = *type;
+        pm.position = QPoint(static_cast<int>(*x), static_cast<int>(*y));
+        pm.rotation = parseRotationString(*rot);
+        result.push_back(std::move(pm));
+    }
+    return result;
+}
+
+}  // namespace
+
+ShipsConfig ConfigLoader::loadShips(const std::string& path)
+{
+    const std::string file = "ships.toml";
+    toml::table tbl = utility::parseFile(path, file);
+
+    ShipsConfig cfg;
+    const toml::array& arr = utility::requireArray(tbl["ship"], file, "ship");
+
+    for (std::size_t i = 0; i < arr.size(); ++i)
+    {
+        const std::string elemPath = "ship[" + std::to_string(i) + "]";
+        const toml::table* st = arr[i].as_table();
+        if (st == nullptr)
+        {
+            throw utility::makeError(file, elemPath, "not a table");
+        }
+        toml::table& mt = const_cast<toml::table&>(*st);
+
+        ShipDef def;
+        def.id                 = utility::requireString(mt["id"],                 file, elemPath + ".id");
+        def.layout             = utility::requireStringArray(mt["layout"],       file, elemPath + ".layout");
+
+        // Schematic
+        {
+            const std::string bpPath = elemPath + ".schematic";
+            const toml::table& bpTable = utility::requireTable(mt["schematic"], file, bpPath);
+            toml::table& bpMt = const_cast<toml::table&>(bpTable);
+
+            const toml::array& materials = utility::requireArray(bpMt["materials"], file, bpPath + ".materials");
+            def.schematic.materials = utility::parseIngredients(materials, file, bpPath + ".materials");
+            def.schematic.productionTimeSeconds = utility::requireDouble(
+                bpMt["production_time_seconds"], file, bpPath + ".production_time_seconds");
+        }
+
+        // Health
+        {
+            const std::string hPath = elemPath + ".health";
+            const toml::table& hTable = utility::requireTable(mt["health"], file, hPath);
+            toml::table& hMt = const_cast<toml::table&>(hTable);
+            def.health.hp = static_cast<float>(utility::requireDouble(hMt["hp"], file, hPath + ".hp"));
+        }
+
+        // Movement
+        {
+            const std::string mPath = elemPath + ".movement";
+            const toml::table& mTable = utility::requireTable(mt["movement"], file, mPath);
+            toml::table& mMt = const_cast<toml::table&>(mTable);
+            def.movement.speed_mps                    = static_cast<float>(utility::requireDouble(mMt["speed_mps"],                    file, mPath + ".speed_mps"));
+            def.movement.mainAcceleration_mpss        = static_cast<float>(utility::requireDouble(mMt["main_acceleration_mpss"],        file, mPath + ".main_acceleration_mpss"));
+            def.movement.maneuveringAcceleration_mpss = static_cast<float>(utility::requireDouble(mMt["maneuvering_acceleration_mpss"], file, mPath + ".maneuvering_acceleration_mpss"));
+            def.movement.angularAcceleration_radpss   = static_cast<float>(utility::requireDouble(mMt["angular_acceleration_radpss"],   file, mPath + ".angular_acceleration_radpss"));
+            def.movement.maxRotationSpeed_radps       = static_cast<float>(utility::requireDouble(mMt["max_rotation_speed_radps"],       file, mPath + ".max_rotation_speed_radps"));
+        }
+
+        // Sensor
+        {
+            const std::string snsPath = elemPath + ".sensor";
+            const toml::table& snsTable = utility::requireTable(mt["sensor"], file, snsPath);
+            toml::table& snsMt = const_cast<toml::table&>(snsTable);
+            def.sensor.sensorRange_m = static_cast<float>(utility::requireDouble(snsMt["sensor_range_m"], file, snsPath + ".sensor_range_m"));
+        }
+
+        // Optional: default_modules (REQ-WAV-DEFAULT-MODULES)
+        if (mt.contains("default_modules"))
+        {
+            const toml::array& modArr = utility::requireArray(mt["default_modules"], file,
+                elemPath + ".default_modules");
+            def.defaultModules = parsePlacedModules(modArr, file,
+                elemPath + ".default_modules");
+        }
+
+        cfg.ships.push_back(std::move(def));
+    }
+
+    return cfg;
+}

src/lib/config/ConfigLoaderStations.cpp

@@ -0,0 +1,47 @@
+#include "ConfigLoader.h"
+
+#include <string>
+
+#include "toml.hpp"
+
+#include "TomlHelpers.h"
+
+StationsConfig ConfigLoader::loadStations(const std::string& path)
+{
+    const std::string file = "stations.toml";
+    toml::table tbl = utility::parseFile(path, file);
+
+    StationsConfig cfg;
+
+    // HQ
+    {
+        const std::string p = "hq";
+        cfg.hq.surfaceMask = utility::requireStringArray(tbl[p]["surface_mask"], file, p + ".surface_mask");
+        cfg.hq.hpFormula   = utility::requireFormula(tbl[p]["hp_formula"],       file, p + ".hp_formula");
+    }
+
+    // Player station
+    {
+        const std::string p = "player_station";
+        cfg.playerStation.surfaceMask     = utility::requireStringArray(tbl[p]["surface_mask"], file, p + ".surface_mask");
+        cfg.playerStation.level           = static_cast<int>(utility::requireInt(tbl[p]["level"], file, p + ".level"));
+        cfg.playerStation.hpFormula       = utility::requireFormula(tbl[p]["hp_formula"],        file, p + ".hp_formula");
+        cfg.playerStation.damageFormula   = utility::requireFormula(tbl[p]["damage_formula"],    file, p + ".damage_formula");
+        cfg.playerStation.rangeFormula    = utility::requireFormula(tbl[p]["range_m_formula"],     file, p + ".range_m_formula");
+        cfg.playerStation.fireRateFormula = utility::requireFormula(tbl[p]["fire_rate_hz_formula"], file, p + ".fire_rate_hz_formula");
+        cfg.playerStation.scrapDropFormula = utility::requireFormula(tbl[p]["scrap_drop_formula"], file, p + ".scrap_drop_formula");
+    }
+
+    // Enemy station
+    {
+        const std::string p = "enemy_station";
+        cfg.enemyStation.surfaceMask      = utility::requireStringArray(tbl[p]["surface_mask"], file, p + ".surface_mask");
+        cfg.enemyStation.hpFormula        = utility::requireFormula(tbl[p]["hp_formula"],         file, p + ".hp_formula");
+        cfg.enemyStation.damageFormula    = utility::requireFormula(tbl[p]["damage_formula"],     file, p + ".damage_formula");
+        cfg.enemyStation.rangeFormula     = utility::requireFormula(tbl[p]["range_m_formula"],      file, p + ".range_m_formula");
+        cfg.enemyStation.fireRateFormula  = utility::requireFormula(tbl[p]["fire_rate_hz_formula"],  file, p + ".fire_rate_hz_formula");
+        cfg.enemyStation.scrapDropFormula = utility::requireFormula(tbl[p]["scrap_drop_formula"], file, p + ".scrap_drop_formula");
+    }
+
+    return cfg;
+}

src/lib/config/ConfigLoaderUnlocks.cpp

@@ -0,0 +1,62 @@
+#include "ConfigLoader.h"
+
+#include <string>
+#include <utility>
+
+#include "toml.hpp"
+
+#include "TomlHelpers.h"
+
+UnlocksConfig ConfigLoader::loadUnlocks(const std::string& path)
+{
+    const std::string file = "unlocks.toml";
+    toml::table tbl = utility::parseFile(path, file);
+
+    UnlocksConfig cfg;
+    if (!tbl.contains("unlock"))
+    {
+        return cfg;
+    }
+
+    const toml::array& arr = utility::requireArray(tbl["unlock"], file, "unlock");
+
+    for (std::size_t i = 0; i < arr.size(); ++i)
+    {
+        const std::string elemPath = "unlock[" + std::to_string(i) + "]";
+        const toml::table* ut = arr[i].as_table();
+        if (ut == nullptr)
+        {
+            throw utility::makeError(file, elemPath, "not a table");
+        }
+        toml::table& mt = const_cast<toml::table&>(*ut);
+
+        UnlockGroupDef def;
+        def.id           = utility::requireString(mt["id"], file, elemPath + ".id");
+        def.stationLevel = static_cast<int>(
+            utility::requireInt(mt["station_level"], file, elemPath + ".station_level"));
+        if (mt.contains("requires"))
+        {
+            def.requiredGroupIds = utility::requireStringArray(mt["requires"], file, elemPath + ".requires");
+        }
+        if (mt.contains("ships"))
+        {
+            def.ships = utility::requireStringArray(mt["ships"], file, elemPath + ".ships");
+        }
+        if (mt.contains("modules"))
+        {
+            def.modules = utility::requireStringArray(mt["modules"], file, elemPath + ".modules");
+        }
+        if (mt.contains("buildings"))
+        {
+            def.buildings = utility::requireStringArray(mt["buildings"], file, elemPath + ".buildings");
+        }
+        if (mt.contains("recipes"))
+        {
+            def.recipes = utility::requireStringArray(mt["recipes"], file, elemPath + ".recipes");
+        }
+
+        cfg.groups.push_back(std::move(def));
+    }
+
+    return cfg;
+}

src/lib/config/ConfigLoaderWorld.cpp

@@ -0,0 +1,79 @@
+#include "ConfigLoader.h"
+
+#include <optional>
+#include <string>
+
+#include "toml.hpp"
+
+#include "TomlHelpers.h"
+
+WorldConfig ConfigLoader::loadWorld(const std::string& path)
+{
+    const std::string file = "world.toml";
+    toml::table tbl = utility::parseFile(path, file);
+
+    WorldConfig cfg;
+
+    cfg.heightTiles                = static_cast<int>(utility::requireInt(tbl["world"]["height_tiles"], file, "world.height_tiles"));
+    cfg.refundPercentage           = static_cast<int>(utility::requireInt(tbl["world"]["refund_percentage"], file, "world.refund_percentage"));
+    cfg.deconstructionTimeSeconds  = utility::requireDouble(tbl["world"]["deconstruction_time_seconds"], file, "world.deconstruction_time_seconds");
+    cfg.startingBuildingBlocks     = static_cast<int>(utility::requireInt(tbl["world"]["starting_building_blocks"], file, "world.starting_building_blocks"));
+    cfg.debrisDespawnSeconds        = utility::requireDouble(tbl["world"]["debris_despawn_seconds"], file, "world.debris_despawn_seconds");
+    cfg.scrapPerThreat             = utility::requireDouble(tbl["world"]["scrap_per_threat"], file, "world.scrap_per_threat");
+    cfg.tileSize_m                 = utility::requireDouble(tbl["world"]["tile_size_m"], file, "world.tile_size_m");
+    cfg.beltSpeed_tps              = utility::requireDouble(tbl["world"]["belt_speed_mps"], file, "world.belt_speed_mps") / cfg.tileSize_m;
+    cfg.tunnelMaxDistance_tiles    = static_cast<int>(utility::requireInt(tbl["world"]["tunnel_max_distance_tiles"], file, "world.tunnel_max_distance_tiles"));
+    cfg.departureIntervalSeconds   = utility::requireDouble(tbl["world"]["departure_interval_seconds"], file, "world.departure_interval_seconds");
+    cfg.orbitFactor                = utility::requireDouble(tbl["world"]["orbit_factor"], file, "world.orbit_factor");
+    cfg.rallyOrbitRadius_tiles     = utility::requireDouble(tbl["world"]["rally_orbit_radius_tiles"], file, "world.rally_orbit_radius_tiles");
+
+    if (const std::optional<std::string> tip =
+            tbl["world"]["building_blocks_tooltip"].value<std::string>())
+    {
+        cfg.buildingBlocksTooltip = *tip;
+    }
+
+    if (const std::optional<std::string> tip =
+            tbl["world"]["artifact_tooltip"].value<std::string>())
+    {
+        cfg.artifactTooltip = *tip;
+    }
+
+    cfg.regions.asteroidWidth_tiles     = static_cast<int>(utility::requireInt(tbl["regions"]["asteroid_width_tiles"],      file, "regions.asteroid_width_tiles"));
+    cfg.regions.playerBufferWidth_tiles = static_cast<int>(utility::requireInt(tbl["regions"]["player_buffer_width_tiles"], file, "regions.player_buffer_width_tiles"));
+    cfg.regions.contestZoneWidth_tiles  = static_cast<int>(utility::requireInt(tbl["regions"]["contest_zone_width_tiles"],  file, "regions.contest_zone_width_tiles"));
+    cfg.regions.enemyBufferWidth_tiles  = static_cast<int>(utility::requireInt(tbl["regions"]["enemy_buffer_width_tiles"],  file, "regions.enemy_buffer_width_tiles"));
+
+    cfg.expansion.columnsPerExpansion_tiles   = static_cast<int>(utility::requireInt(tbl["expansion"]["columns_per_expansion_tiles"], file, "expansion.columns_per_expansion_tiles"));
+    cfg.expansion.costBuildingBlocksFormula   = utility::requireFormula(tbl["expansion"]["cost_building_blocks_formula"],            file, "expansion.cost_building_blocks_formula");
+
+    cfg.push.pushExpandColumns_tiles = static_cast<int>(utility::requireInt(tbl["push"]["push_expand_columns_tiles"], file, "push.push_expand_columns_tiles"));
+    cfg.push.bossAdvanceSeconds = utility::requireDouble(tbl["push"]["boss_advance_seconds"], file, "push.boss_advance_seconds");
+
+    cfg.waves.threatRateFormula         = utility::requireFormula(tbl["waves"]["threat_rate_formula"],         file, "waves.threat_rate_formula");
+    cfg.waves.gapMinSeconds             = utility::requireDouble(tbl["waves"]["gap_min_seconds"],              file, "waves.gap_min_seconds");
+    cfg.waves.gapMaxSeconds             = utility::requireDouble(tbl["waves"]["gap_max_seconds"],              file, "waves.gap_max_seconds");
+    cfg.waves.spawnDurationSeconds      = utility::requireDouble(tbl["waves"]["spawn_duration_seconds"],       file, "waves.spawn_duration_seconds");
+    cfg.waves.bossCountdownSeconds      = utility::requireDouble(tbl["waves"]["boss_countdown_seconds"],       file, "waves.boss_countdown_seconds");
+    cfg.waves.bossThreatDurationSeconds = utility::requireDouble(tbl["waves"]["boss_threat_duration_seconds"], file, "waves.boss_threat_duration_seconds");
+    cfg.waves.bossQuietBeforeSeconds    = utility::requireDouble(tbl["waves"]["boss_quiet_before_seconds"],    file, "waves.boss_quiet_before_seconds");
+    cfg.waves.bossQuietAfterSeconds     = utility::requireDouble(tbl["waves"]["boss_quiet_after_seconds"],     file, "waves.boss_quiet_after_seconds");
+
+    if (cfg.waves.gapMinSeconds > cfg.waves.gapMaxSeconds)
+    {
+        throw utility::makeError(file, "waves", "gap_min_seconds > gap_max_seconds");
+    }
+
+    cfg.targeting.targetScoreFormula      = utility::requireFormula(tbl["targeting"]["target_score_formula"],      file, "targeting.target_score_formula");
+    cfg.targeting.overclaimPenaltyFormula = utility::requireFormula(tbl["targeting"]["overclaim_penalty_formula"], file, "targeting.overclaim_penalty_formula");
+    cfg.targeting.hysteresis              = utility::requireDouble(tbl["targeting"]["target_hysteresis"],          file, "targeting.target_hysteresis");
+
+    cfg.artifacts.artifactChanceFormula = utility::requireFormula(tbl["artifacts"]["artifact_chance_formula"], file, "artifacts.artifact_chance_formula");
+    cfg.artifacts.artifactWinCount      = static_cast<int>(utility::requireInt(tbl["artifacts"]["artifact_win_count"], file, "artifacts.artifact_win_count"));
+
+    cfg.scroll.panSpeedSlow_tps       = utility::requireDouble(tbl["scroll"]["pan_speed_slow_tiles_per_second"], file, "scroll.pan_speed_slow_tiles_per_second");
+    cfg.scroll.panSpeedFast_tps       = utility::requireDouble(tbl["scroll"]["pan_speed_fast_tiles_per_second"], file, "scroll.pan_speed_fast_tiles_per_second");
+    cfg.scroll.panRampBandWidth_tiles = static_cast<int>(utility::requireInt(tbl["scroll"]["pan_ramp_band_width_tiles"], file, "scroll.pan_ramp_band_width_tiles"));
+
+    return cfg;
+}

src/lib/config/TomlHelpers.cpp

@@ -0,0 +1,172 @@
+#include "TomlHelpers.h"
+
+#include <sstream>
+#include <utility>
+
+namespace utility
+{
+
+// --- Error helpers --------------------------------------------------------
+
+std::runtime_error makeError(const std::string& file,
+                             const std::string& path,
+                             const std::string& why)
+{
+    return std::runtime_error("Config: " + file + ": '" + path + "' " + why);
+}
+
+// --- Typed accessors (throw on missing or wrong type) ---------------------
+
+int64_t requireInt(const toml::node_view<toml::node>& node,
+                   const std::string& file,
+                   const std::string& path)
+{
+    const std::optional<int64_t> value = node.value<int64_t>();
+    if (!value)
+    {
+        throw makeError(file, path, "missing or not an integer");
+    }
+    return *value;
+}
+
+double requireDouble(const toml::node_view<toml::node>& node,
+                     const std::string& file,
+                     const std::string& path)
+{
+    if (const std::optional<double> v = node.value<double>())
+    {
+        return *v;
+    }
+    if (const std::optional<int64_t> v = node.value<int64_t>())
+    {
+        return static_cast<double>(*v);
+    }
+    throw makeError(file, path, "missing or not a number");
+}
+
+std::string requireString(const toml::node_view<toml::node>& node,
+                          const std::string& file,
+                          const std::string& path)
+{
+    const std::optional<std::string> value = node.value<std::string>();
+    if (!value)
+    {
+        throw makeError(file, path, "missing or not a string");
+    }
+    return *value;
+}
+
+bool requireBool(const toml::node_view<toml::node>& node,
+                 const std::string& file,
+                 const std::string& path)
+{
+    const std::optional<bool> value = node.value<bool>();
+    if (!value)
+    {
+        throw makeError(file, path, "missing or not a boolean");
+    }
+    return *value;
+}
+
+const toml::array& requireArray(const toml::node_view<toml::node>& node,
+                                const std::string& file,
+                                const std::string& path)
+{
+    const toml::array* arr = node.as_array();
+    if (arr == nullptr)
+    {
+        throw makeError(file, path, "missing or not an array");
+    }
+    return *arr;
+}
+
+const toml::table& requireTable(const toml::node_view<toml::node>& node,
+                                const std::string& file,
+                                const std::string& path)
+{
+    const toml::table* tbl = node.as_table();
+    if (tbl == nullptr)
+    {
+        throw makeError(file, path, "missing or not a table");
+    }
+    return *tbl;
+}
+
+Formula requireFormula(const toml::node_view<toml::node>& node,
+                       const std::string& file,
+                       const std::string& path)
+{
+    const std::string source = requireString(node, file, path);
+    try
+    {
+        return Formula::compile(source);
+    }
+    catch (const std::exception& e)
+    {
+        throw makeError(file, path, std::string("formula error: ") + e.what());
+    }
+}
+
+std::vector<std::string> requireStringArray(const toml::node_view<toml::node>& node,
+                                            const std::string& file,
+                                            const std::string& path)
+{
+    const toml::array& arr = requireArray(node, file, path);
+    std::vector<std::string> result;
+    result.reserve(arr.size());
+    for (std::size_t i = 0; i < arr.size(); ++i)
+    {
+        const std::string elemPath = path + "[" + std::to_string(i) + "]";
+        const std::optional<std::string> s = arr[i].value<std::string>();
+        if (!s)
+        {
+            throw makeError(file, elemPath, "not a string");
+        }
+        result.push_back(*s);
+    }
+    return result;
+}
+
+std::vector<RecipeIngredient> parseIngredients(const toml::array& arr,
+                                               const std::string& file,
+                                               const std::string& path)
+{
+    std::vector<RecipeIngredient> result;
+    result.reserve(arr.size());
+    for (std::size_t i = 0; i < arr.size(); ++i)
+    {
+        const std::string elemPath = path + "[" + std::to_string(i) + "]";
+        const toml::table* t = arr[i].as_table();
+        if (t == nullptr)
+        {
+            throw makeError(file, elemPath, "not a table");
+        }
+
+        // We need a mutable node_view to reuse our helpers, which is fine
+        // because the helpers never mutate.
+        toml::table& mt = const_cast<toml::table&>(*t);
+
+        RecipeIngredient ing;
+        ing.item = requireString(mt["item"], file, elemPath + ".item");
+        ing.amount = static_cast<int>(requireInt(mt["amount"], file, elemPath + ".amount"));
+        result.push_back(std::move(ing));
+    }
+    return result;
+}
+
+toml::table parseFile(const std::string& path, const std::string& file)
+{
+    try
+    {
+        return toml::parse_file(path);
+    }
+    catch (const toml::parse_error& e)
+    {
+        std::ostringstream oss;
+        oss << "Config: " << file << ": TOML parse error: " << e.description()
+            << " at " << e.source().begin;
+        throw std::runtime_error(oss.str());
+    }
+}
+
+}  // namespace utility

src/lib/config/TomlHelpers.h

@@ -0,0 +1,70 @@
+#pragma once
+
+#include <cstdint>
+#include <stdexcept>
+#include <string>
+#include <vector>
+
+#include "toml.hpp"
+
+#include "Formula.h"
+#include "RecipesConfig.h"  // for RecipeIngredient
+
+// Shared TOML-parsing helpers used by two or more ConfigLoader per-domain
+// loaders. Helpers used by exactly one domain stay local to that domain's
+// .cpp file instead.
+//
+// Namespaced because the names are generic: VisualsLoader.cpp and
+// BalancingConfig.cpp each have their own same-named helpers in anonymous
+// namespaces, and unqualified globals here would form an overload set with
+// them the moment either file includes this header.
+namespace utility
+{
+
+// --- Error helpers ----------------------------------------------------------
+
+std::runtime_error makeError(const std::string& file,
+                             const std::string& path,
+                             const std::string& why);
+
+// --- Typed accessors (throw on missing or wrong type) -----------------------
+
+int64_t requireInt(const toml::node_view<toml::node>& node,
+                   const std::string& file,
+                   const std::string& path);
+
+double requireDouble(const toml::node_view<toml::node>& node,
+                     const std::string& file,
+                     const std::string& path);
+
+std::string requireString(const toml::node_view<toml::node>& node,
+                          const std::string& file,
+                          const std::string& path);
+
+bool requireBool(const toml::node_view<toml::node>& node,
+                 const std::string& file,
+                 const std::string& path);
+
+const toml::array& requireArray(const toml::node_view<toml::node>& node,
+                                const std::string& file,
+                                const std::string& path);
+
+const toml::table& requireTable(const toml::node_view<toml::node>& node,
+                                const std::string& file,
+                                const std::string& path);
+
+Formula requireFormula(const toml::node_view<toml::node>& node,
+                       const std::string& file,
+                       const std::string& path);
+
+std::vector<std::string> requireStringArray(const toml::node_view<toml::node>& node,
+                                            const std::string& file,
+                                            const std::string& path);
+
+std::vector<RecipeIngredient> parseIngredients(const toml::array& arr,
+                                               const std::string& file,
+                                               const std::string& path);
+
+toml::table parseFile(const std::string& path, const std::string& file);
+
+}  // namespace utility