tileset_compile_validators.hpp

Go to the documentation of this file.

#pragma once
 
#include <map>
#include <set>
#include <string>
#include <vector>
 
#include "gsl/pointers"
 
#include "porytiles/domain/algorithms/diagnostic_stencils.hpp"
#include "porytiles/domain/config/domain_config.hpp"
#include "porytiles/domain/models/animation.hpp"
#include "porytiles/domain/models/metatile.hpp"
#include "porytiles/domain/services/palette_printer.hpp"
#include "porytiles/domain/services/tile_printer.hpp"
#include "porytiles/utilities/filesystem_utils.hpp"
#include "porytiles/utilities/result/chainable_result.hpp"
#include "porytiles/utilities/string_utils.hpp"
#include "porytiles/xcut/config/unwrap_config.hpp"
#include "porytiles/xcut/diagnostics/user_diagnostics.hpp"
 
 
namespace porytiles {
 
struct TilesetCompileValidatorServices {
    const DomainConfig &config;
    const UserDiagnostics &diag;
    const TilePrinter &tile_printer;
    const PalettePrinter &palette_printer;
};
 
namespace details {
 
inline void report_validation_error_in_metatile(
    const TilesetCompileValidatorServices &services,
    const Metatile<Rgba32> &metatile,
    std::size_t metatile_index,
    std::size_t internal_tile_index,
    std::size_t row,
    std::size_t col,
    const std::string &diagnostic_code,
    const std::string &error_message,
    const Rgba32 &extrinsic_transparency)
{
    auto [layer, subtile] = metatile::from_internal_tile_index(internal_tile_index);
    std::vector errors = {services.diag.formatter().format(
        "{}: {}",
        FormatParam{
            metatile::message_header(services.diag.formatter(), metatile_index, layer, subtile, row, col), Style::bold},
        FormatParam{error_message})};
    std::vector highlight = services.tile_printer.print_metatile_pixel_highlight(
        metatile, layer, subtile, row, col, extrinsic_transparency);
    errors.append_range(highlight);
    services.diag.error(diagnostic_code, errors);
}
 
inline void report_validation_error_in_anim(
    const TilesetCompileValidatorServices &services,
    const PixelTile<Rgba32> &tile,
    const std::string &anim_name,
    const std::string &frame_name,
    std::size_t internal_tile_index,
    std::size_t row,
    std::size_t col,
    const std::string &diagnostic_code,
    const std::string &error_message,
    const Rgba32 &extrinsic_transparency)
{
    std::vector errors = {services.diag.formatter().format(
        "{}: {}",
        FormatParam{
            anim::message_header(services.diag.formatter(), anim_name, frame_name, internal_tile_index, row, col),
            Style::bold},
        FormatParam{error_message})};
    std::vector highlight = services.tile_printer.print_tile_pixel_highlight(tile, row, col, extrinsic_transparency);
    errors.append_range(highlight);
    services.diag.error(diagnostic_code, errors);
}
 
inline void report_validation_error_in_anim_tile(
    const TilesetCompileValidatorServices &services,
    const PixelTile<Rgba32> &tile,
    const std::string &anim_name,
    const std::string &frame_name,
    std::size_t internal_tile_index,
    const std::string &diagnostic_code,
    const std::string &error_message,
    const Rgba32 &extrinsic_transparency)
{
    std::vector errors = {services.diag.formatter().format(
        "{}: {}",
        FormatParam{
            anim::message_header(services.diag.formatter(), anim_name, frame_name, internal_tile_index), Style::bold},
        FormatParam{error_message})};
    std::vector tile_visual = services.tile_printer.print_tile(tile, extrinsic_transparency);
    errors.append_range(tile_visual);
    services.diag.error(diagnostic_code, errors);
}
 
inline void report_color_counts(
    const std::string &tag,
    const TilesetCompileValidatorServices &services,
    const std::map<Rgba32, unsigned int> &color_counts)
{
    std::vector<std::string> color_lines;
    color_lines.emplace_back("color counts:");
    auto counts = services.palette_printer.print_rgba_palette_counts(color_counts);
    color_lines.append_range(counts);
    services.diag.error_note(tag, color_lines);
}
 
} // namespace details
 
[[nodiscard]] inline ChainableResult<void> validate_metatile_count(
    const TilesetCompileValidatorServices &services,
    const std::string &tileset_name,
    bool is_secondary,
    const std::vector<Metatile<Rgba32>> &metatiles)
{
    PT_UNWRAP_TILESET_CONFIG_REF(services.config, num_metatiles_in_primary, tileset_name, void);
    PT_UNWRAP_TILESET_CONFIG_REF(services.config, num_metatiles_total, tileset_name, void);
 
    std::size_t metatile_limit = is_secondary ? (num_metatiles_total.value() - num_metatiles_in_primary.value())
                                              : num_metatiles_in_primary.value();
 
    if (metatiles.size() > metatile_limit) {
        services.diag.error(
            "metatile-limit-exceeded",
            "Too many metatiles ({}) in Porytiles component for tileset '{}'.",
            FormatParam{metatiles.size(), Style::bold},
            FormatParam{tileset_name, Style::bold});
 
        std::vector<std::string> note_text;
        if (is_secondary) {
            note_text.append_range(build_subtraction_limit_lines(
                services.diag.formatter(),
                "Metatile limit",
                metatile_limit,
                num_metatiles_total,
                num_metatiles_in_primary));
        }
        else {
            note_text.push_back(
                services.diag.formatter().format("Metatile limit is '{}'.", FormatParam{metatile_limit, Style::bold}));
            note_text.emplace_back("");
            note_text.append_range(format_config_note(services.diag.formatter(), num_metatiles_in_primary));
        }
        services.diag.error_note("metatile-limit-exceeded", note_text);
 
        return FormattableError{
            "Found '{}' metatiles, limit is '{}'.",
            FormatParam{metatiles.size(), Style::bold},
            FormatParam{metatile_limit, Style::bold}};
    }
 
    return {};
}
 
[[nodiscard]] inline ChainableResult<void> validate_porymap_palette(
    const TilesetCompileValidatorServices &services,
    const std::string &tileset_name,
    const Palette<Rgba32, palette::max_size> &palette,
    std::size_t palette_index)
{
    PT_UNWRAP_TILESET_CONFIG_REF(services.config, extrinsic_transparency, tileset_name, void);
 
    bool hit_error = false;
    const std::string filename = palette_filename(palette_index);
    std::vector<std::size_t> violating_slots{};
 
    if (palette.is_wildcard(0)) {
        panic("unexpected wildcard in Porymap palette slot 0");
    }
 
    // Check 1: Slot 0 should match extrinsic transparency (warning only)
    const Rgba32 slot0_color = palette.slot_zero_color();
    if (!slot0_color.is_extrinsically_transparent(extrinsic_transparency)) {
        std::vector<std::string> warning_lines;
        warning_lines.emplace_back(services.diag.formatter().format(
            "Porymap palette '{}' slot 0 color '{}' does not match extrinsic transparency '{}'",
            FormatParam{filename, Style::bold},
            FormatParam{slot0_color.to_jasc_str(), Style::bold},
            FormatParam{extrinsic_transparency.value().to_jasc_str(), Style::bold}));
        warning_lines.emplace_back("Slot 0 is typically reserved for the transparency color.");
        warning_lines.emplace_back("If you are using slot 0 for a .pla blend color, you can ignore this warning.");
        services.diag.warning("porymap-palette-slot-0", warning_lines);
 
        services.diag.warning_note(
            "porymap-palette-slot-0",
            build_porymap_palette_highlight_lines(
                services.diag.formatter(),
                services.palette_printer,
                "reserved transparency slot",
                palette,
                filename,
                std::vector<std::size_t>{0}));
        services.diag.warning_note(
            "porymap-palette-slot-0", format_config_note(services.diag.formatter(), extrinsic_transparency));
    }
 
    // Check 2: Non-slot-0 positions cannot contain extrinsic transparency
    for (std::size_t slot = 1; slot < palette.size(); ++slot) {
        if (palette.is_wildcard(slot)) {
            panic("unexpected wildcard in Porymap palette");
        }
        const Rgba32 color = palette.at(slot);
        if (color.is_extrinsically_transparent(extrinsic_transparency)) {
            hit_error = true;
            violating_slots.push_back(slot);
            std::vector<std::string> error_lines;
            error_lines.emplace_back(services.diag.formatter().format(
                "Porymap palette '{}' slot '{}' contains extrinsic transparency color '{}'",
                FormatParam{filename, Style::bold},
                FormatParam{slot, Style::bold},
                FormatParam{color.to_jasc_str(), Style::bold}));
            error_lines.emplace_back("Extrinsic transparency is not allowed in non-slot-0 positions.");
            services.diag.error("porymap-palette-transparency", error_lines);
        }
    }
 
    if (hit_error) {
        // Print the palette with violating slots highlighted
        services.diag.error_note(
            "porymap-palette-transparency",
            build_porymap_palette_highlight_lines(
                services.diag.formatter(),
                services.palette_printer,
                "slots with invalid extrinsic transparency",
                palette,
                filename,
                violating_slots));
        services.diag.error_note(
            "porymap-palette-transparency", format_config_note(services.diag.formatter(), extrinsic_transparency));
 
        return FormattableError{"Validation failed for Porymap palette '{}'.", FormatParam{filename, Style::bold}};
    }
 
    return {};
}
 
[[nodiscard]] inline ChainableResult<void> validate_porytiles_palette(
    const TilesetCompileValidatorServices &services,
    const std::string &tileset_name,
    const Palette<Rgba32, palette::max_size> &palette,
    std::size_t palette_index)
{
    PT_UNWRAP_TILESET_CONFIG_REF(services.config, extrinsic_transparency, tileset_name, void);
 
    bool hit_error = false;
    const std::string filename = palette_filename(palette_index);
    std::vector<std::size_t> violating_slots;
 
    // Check 1: Slot 0 should match extrinsic transparency (warning only)
    if (!palette.is_wildcard(0)) {
        const Rgba32 slot0_color = palette.slot_zero_color();
        if (!slot0_color.is_extrinsically_transparent(extrinsic_transparency)) {
            // Build the warning text
            std::vector<std::string> warning_text;
            warning_text.emplace_back(services.diag.formatter().format(
                "Porytiles palette '{}' slot 0 color '{}' does not match extrinsic transparency '{}'",
                FormatParam{filename, Style::bold},
                FormatParam{slot0_color.to_jasc_str(), Style::bold},
                FormatParam{extrinsic_transparency.value().to_jasc_str(), Style::bold}));
            warning_text.emplace_back("Slot 0 is typically reserved for the transparency color.");
            warning_text.emplace_back("If you are using slot 0 for a .pla blend color, you can ignore this warning.");
            services.diag.warning("porytiles-palette-slot-0", warning_text);
 
            // Print the palette and config notes.
            services.diag.warning_note(
                "porytiles-palette-slot-0",
                build_porytiles_palette_highlight_lines(
                    services.diag.formatter(),
                    services.palette_printer,
                    "reserved transparency slot",
                    palette,
                    filename,
                    std::vector<std::size_t>{0}));
            services.diag.warning_note(
                "porytiles-palette-slot-0", format_config_note(services.diag.formatter(), extrinsic_transparency));
        }
    }
 
    // Check 2: Non-slot-0 positions cannot contain extrinsic transparency
    for (std::size_t slot = 1; slot < palette.size(); ++slot) {
        if (palette.is_wildcard(slot)) {
            continue;
        }
        const Rgba32 color = palette.at(slot);
        if (color.is_extrinsically_transparent(extrinsic_transparency)) {
            hit_error = true;
            violating_slots.push_back(slot);
            std::vector<std::string> error_lines;
            error_lines.emplace_back(services.diag.formatter().format(
                "Porytiles palette '{}' slot '{}' contains extrinsic transparency color '{}'",
                FormatParam{filename, Style::bold},
                FormatParam{slot, Style::bold},
                FormatParam{color.to_jasc_str(), Style::bold}));
            error_lines.emplace_back("Extrinsic transparency is not allowed in non-slot-0 positions.");
            services.diag.error("porytiles-palette-transparency", error_lines);
        }
    }
 
    if (hit_error) {
        // Print the palette and config notes
        services.diag.error_note(
            "porytiles-palette-transparency",
            build_porytiles_palette_highlight_lines(
                services.diag.formatter(),
                services.palette_printer,
                "slots with invalid extrinsic transparency",
                palette,
                filename,
                violating_slots));
        services.diag.error_note(
            "porytiles-palette-transparency", format_config_note(services.diag.formatter(), extrinsic_transparency));
 
        return FormattableError{"Validation failed for Porytiles palette '{}'.", FormatParam{filename, Style::bold}};
    }
 
    return {};
}
 
[[nodiscard]] inline ChainableResult<void> validate_palette_hint(
    const TilesetCompileValidatorServices &services, const std::string &tileset_name, const PaletteHint &hint)
{
    PT_UNWRAP_TILESET_CONFIG_REF(services.config, extrinsic_transparency, tileset_name, void);
 
    bool hit_any_error = false;
    const std::string &hint_name = hint.name();
 
    if (hint.palette().size() >= palette::max_size) {
        services.diag.error(
            "palette-hint-size-violation",
            services.diag.formatter().format(
                "palette hint '{}' has size '{}', max allowed size is '{}'",
                FormatParam{hint_name, Style::bold},
                FormatParam{hint.palette().size(), Style::bold},
                FormatParam{palette::max_size - 1, Style::bold}));
        services.diag.error_note(
            "palette-hint-size-violation",
            build_palette_hint_highlight_lines(
                services.diag.formatter(),
                services.palette_printer,
                "invalid extra slots start here",
                hint,
                hint_name,
                std::vector{palette::max_size}));
        return FormattableError{"Validation failed for palette hint '{}'.", FormatParam{hint_name, Style::bold}};
    }
 
    std::set<Rgba32> seen_colors{};
    std::vector<std::size_t> violating_slots{};
 
    // Check 1: Extrinsic transparency not allowed in hints
    for (std::size_t slot = 0; slot < hint.palette().size(); ++slot) {
        if (hint.palette().is_wildcard(slot)) {
            continue;
        }
        const Rgba32 color = hint.palette().at(slot);
 
        if (color.is_extrinsically_transparent(extrinsic_transparency)) {
            hit_any_error = true;
            violating_slots.push_back(slot);
            std::vector<std::string> error_lines;
            error_lines.emplace_back(services.diag.formatter().format(
                "palette hint '{}' slot '{}' contains extrinsic transparency color '{}'",
                FormatParam{hint_name, Style::bold},
                FormatParam{slot, Style::bold},
                FormatParam{color.to_jasc_str(), Style::bold}));
            error_lines.emplace_back("Extrinsic transparency is not allowed in palette hints.");
            services.diag.error("palette-hint-transparency", error_lines);
        }
    }
    if (!violating_slots.empty()) {
        services.diag.error_note(
            "palette-hint-transparency",
            build_palette_hint_highlight_lines(
                services.diag.formatter(),
                services.palette_printer,
                "slots with invalid extrinsic transparency",
                hint,
                hint_name,
                violating_slots));
        services.diag.error_note(
            "palette-hint-transparency", format_config_note(services.diag.formatter(), extrinsic_transparency));
    }
    violating_slots.clear();
 
    // Check 2: No duplicate colors
    for (std::size_t slot = 0; slot < hint.palette().size(); ++slot) {
        if (hint.palette().is_wildcard(slot)) {
            continue;
        }
        const Rgba32 color = hint.palette().at(slot);
 
        if (seen_colors.contains(color)) {
            hit_any_error = true;
            violating_slots.push_back(slot);
            std::vector<std::string> error_lines;
            error_lines.emplace_back(services.diag.formatter().format(
                "palette hint '{}' contains duplicate color '{}' at slot '{}'",
                FormatParam{hint_name, Style::bold},
                FormatParam{color.to_jasc_str(), Style::bold},
                FormatParam{slot, Style::bold}));
            error_lines.emplace_back("Duplicate colors are not allowed in palette hints.");
            services.diag.error("palette-hint-duplicate-color", error_lines);
        }
        seen_colors.insert(color);
    }
    if (!violating_slots.empty()) {
        services.diag.error_note(
            "palette-hint-duplicate-color",
            build_palette_hint_highlight_lines(
                services.diag.formatter(),
                services.palette_printer,
                "slots with invalid duplicate colors",
                hint,
                hint_name,
                violating_slots));
    }
 
    if (hit_any_error) {
        return FormattableError{"Validation failed for palette hint '{}'.", FormatParam{hint_name, Style::bold}};
    }
    return {};
}
 
[[nodiscard]] inline ChainableResult<void> validate_alpha_channels(
    const TilesetCompileValidatorServices &services,
    const std::string &tileset_name,
    const std::vector<Metatile<Rgba32>> &metatiles,
    const std::map<std::string, Animation<Rgba32>> &anims)
{
    PT_UNWRAP_TILESET_CONFIG_REF(services.config, extrinsic_transparency, tileset_name, void);
 
    bool hit_error = false;
 
    // Validate metatiles
    std::size_t metatile_index = 0;
    for (const auto &metatile : metatiles) {
        const auto decomposed_metatile = metatile.decompose();
 
        // Iterate over each internal tile
        for (std::size_t internal_tile_index = 0; internal_tile_index < decomposed_metatile.size();
             ++internal_tile_index) {
            const auto &tile = decomposed_metatile[internal_tile_index];
 
            // Iterate over each pixel in the current internal tile
            for (std::size_t row = 0; row < tile::side_length_pix; ++row) {
                for (std::size_t col = 0; col < tile::side_length_pix; ++col) {
                    const auto &pixel = tile.at(row, col);
                    if (pixel.alpha() != Rgba32::alpha_opaque && pixel.alpha() != Rgba32::alpha_transparent) {
                        hit_error = true;
                        std::string error_message = services.diag.formatter().format(
                            "invalid alpha channel: {}", FormatParam{std::to_string(pixel.alpha()), Style::bold});
                        details::report_validation_error_in_metatile(
                            services,
                            metatile,
                            metatile_index,
                            internal_tile_index,
                            row,
                            col,
                            "alpha-channel-violation",
                            error_message,
                            extrinsic_transparency);
                    }
                }
            }
        }
        metatile_index++;
    }
 
    // Lambda to avoid duplicating logic
    auto validate_anim_frame = [&services, &hit_error, &extrinsic_transparency](
                                   const std::string &anim_name, const AnimFrame<Rgba32> &frame) -> void {
        const auto &frame_tiles = frame.tiles();
 
        // Loop over each internal frame tile
        for (std::size_t internal_tile_index = 0; internal_tile_index < frame_tiles.size(); ++internal_tile_index) {
            const auto &tile = frame_tiles.at(internal_tile_index);
 
            // loop over tile pixels, row-major
            for (std::size_t row = 0; row < tile::side_length_pix; ++row) {
                for (std::size_t col = 0; col < tile::side_length_pix; ++col) {
                    const auto &pixel = tile.at(row, col);
 
                    // validate
                    if (pixel.alpha() != Rgba32::alpha_opaque && pixel.alpha() != Rgba32::alpha_transparent) {
                        hit_error = true;
                        std::string error_message = services.diag.formatter().format(
                            "invalid alpha channel: {}", FormatParam{std::to_string(pixel.alpha()), Style::bold});
                        details::report_validation_error_in_anim(
                            services,
                            tile,
                            anim_name,
                            frame.frame_name(),
                            internal_tile_index,
                            row,
                            col,
                            "alpha-channel-violation",
                            error_message,
                            extrinsic_transparency);
                    }
                }
            }
        }
    };
 
    // Validate animations
    for (const auto &[anim_name, anim] : anims) {
        if (anim.has_key_frame()) {
            const auto &key_frame = anim.key_frame();
            validate_anim_frame(anim_name, key_frame);
        }
        for (const AnimFrame<Rgba32> &frame : anim.frames() | std::views::values) {
            validate_anim_frame(anim_name, frame);
        }
    }
 
    if (hit_error) {
        return FormattableError{"Found input pixel(s) with invalid alpha channel value(s)."};
    }
 
    return {};
}
 
[[nodiscard]] inline ChainableResult<void> validate_layer_mode(
    const TilesetCompileValidatorServices &services,
    const std::string &tileset_name,
    const std::vector<Metatile<Rgba32>> &metatiles)
{
    PT_UNWRAP_TILESET_CONFIG_REF(services.config, extrinsic_transparency, tileset_name, void);
    PT_UNWRAP_TILESET_CONFIG_REF(services.config, num_tiles_per_metatile, tileset_name, void);
    PT_UNWRAP_TILESET_CONFIG_REF(services.config, ignore_triple_layer_content, tileset_name, void);
    auto configured_layer_mode = layer_mode_from_val(num_tiles_per_metatile);
 
    // If layer mode is triple, just return
    if (configured_layer_mode == LayerMode::triple) {
        return {};
    }
 
    // With ignore on, triple content in dual mode is a warning, not an error
    const bool ignore_triple = ignore_triple_layer_content.value();
 
    bool hit_error = false;
    bool hit_violation = false;
    std::size_t metatile_index = 0;
 
    for (const auto &metatile : metatiles) {
        // Check each of the 4 tile positions (northwest, northeast, southwest, southeast) independently: a subtile is
        // a triple-layer region only when all three of its own layers carry content, regardless of its siblings.
        for (std::size_t subtile_idx = 0; subtile_idx < metatile::tiles_per_metatile_layer; ++subtile_idx) {
            const auto &bottom_tile = metatile.bottom(subtile_idx);
            const auto &middle_tile = metatile.middle(subtile_idx);
            const auto &top_tile = metatile.top(subtile_idx);
            const auto subtile = metatile::subtile_from_index(subtile_idx);
 
            // Check if each layer has at least one non-transparent pixel in this tile position
            const bool bottom_has_opaque = !bottom_tile.is_transparent(extrinsic_transparency.value());
            const bool middle_has_opaque = !middle_tile.is_transparent(extrinsic_transparency.value());
            const bool top_has_opaque = !top_tile.is_transparent(extrinsic_transparency.value());
 
            // If all three layers have opaque pixels in this tile position, this is a triple-layer region
            const bool triple_layer_region = bottom_has_opaque && middle_has_opaque && top_has_opaque;
 
            // Violation if the subtile is a triple-layer region in a dual-layer compilation. The
            // ignore_triple_layer_content config decides whether it generates a hard error or a warning.
            if (triple_layer_region && configured_layer_mode == LayerMode::dual) {
                hit_violation = true;
                std::vector lines = {services.diag.formatter().format(
                    "{}: {}",
                    FormatParam{
                        metatile::message_header(services.diag.formatter(), metatile_index, subtile), Style::bold},
                    FormatParam{"non-transparent content on all three layers"})};
                std::vector bottom_highlight = services.tile_printer.print_metatile_tile_highlight(
                    metatile, metatile::Layer::bottom, subtile, extrinsic_transparency);
                std::vector middle_highlight = services.tile_printer.print_metatile_tile_highlight(
                    metatile, metatile::Layer::middle, subtile, extrinsic_transparency);
                std::vector top_highlight = services.tile_printer.print_metatile_tile_highlight(
                    metatile, metatile::Layer::top, subtile, extrinsic_transparency);
                lines.append_range(bottom_highlight);
                lines.append_range(middle_highlight);
                lines.append_range(top_highlight);
                if (ignore_triple) {
                    services.diag.warning("layer-mode-violation", lines);
                }
                else {
                    hit_error = true;
                    services.diag.error("layer-mode-violation", lines);
                }
            }
        }
 
        metatile_index++;
    }
 
    if (hit_error) {
        std::vector<std::string> note_text;
        note_text.push_back(
            services.diag.formatter().format("Implied layer mode is '{}'.", FormatParam{LayerMode::dual, Style::bold}));
        note_text.emplace_back("");
        note_text.append_range(format_config_note(services.diag.formatter(), num_tiles_per_metatile));
        note_text.emplace_back("");
        note_text.emplace_back("Consider enabling triple-layer metatiles.");
        note_text.push_back(services.diag.formatter().format(
            "To enable layer mode '{}' for your project:", FormatParam{LayerMode::triple, Style::bold}));
        note_text.push_back(services.diag.formatter().format(
            "   - set '{}' = '{}'",
            FormatParam{num_tiles_per_metatile.canonical_name(), Style::bold},
            FormatParam{metatile::entries_per_metatile_triple, Style::bold}));
        note_text.push_back(services.diag.formatter().format(
            "   - follow the steps here: {}",
            FormatParam{"https://github.com/pret/pokeemerald/wiki/Triple-layer-metatiles", Style::underline}));
        note_text.emplace_back("");
        note_text.push_back(services.diag.formatter().format(
            "Alternatively, set '{}' to force compilation in dual-layer mode. Porytiles will then drop a layer per "
            "offending metatile, either by respecting a layer_type pin or by forcing each to layer type '{}'.",
            FormatParam{ignore_triple_layer_content.canonical_name(), Style::bold},
            FormatParam{to_string(LayerType::normal), Style::bold}));
 
        // Emit note
        services.diag.error_note("layer-mode-violation", note_text);
 
        return FormattableError{"Found metatile(s) with mismatched implied layer mode."};
    }
 
    // Config ignore_triple_layer_content on and at least one metatile had triple content: warn once that the dual
    // conversion will drop a layer group per offending metatile.
    if (hit_violation) {
        std::vector<std::string> note_text;
        note_text.push_back(services.diag.formatter().format(
            "Porytiles will drop a layer per offending metatile, either by respecting a layer_type pin or by forcing "
            "each to layer type '{}'. This violation was explicitly downgraded from error to warning by:",
            FormatParam{to_string(LayerType::normal), Style::bold}));
        note_text.emplace_back("");
        note_text.append_range(format_config_note(services.diag.formatter(), ignore_triple_layer_content));
        services.diag.warning_note("layer-mode-violation", note_text);
    }
 
    return {};
}
 
[[nodiscard]] inline ChainableResult<void> validate_tile_color_count(
    const TilesetCompileValidatorServices &services,
    const std::string &tileset_name,
    const std::vector<Metatile<Rgba32>> &metatiles,
    const std::map<std::string, Animation<Rgba32>> &anims)
{
    PT_UNWRAP_TILESET_CONFIG_REF(services.config, extrinsic_transparency, tileset_name, void);
 
    bool hit_error = false;
    std::size_t metatile_index = 0;
    for (const auto &metatile : metatiles) {
        const auto decomposed_metatile = metatile.decompose();
 
        // Iterate over each internal tile
        for (std::size_t internal_tile_index = 0; internal_tile_index < decomposed_metatile.size();
             ++internal_tile_index) {
            const auto &tile = decomposed_metatile[internal_tile_index];
            std::map<Rgba32, unsigned int> color_counts;
 
            // Iterate over each pixel in the current internal tile
            for (std::size_t row = 0; row < tile::side_length_pix; ++row) {
                for (std::size_t col = 0; col < tile::side_length_pix; ++col) {
                    const auto &pixel = tile.at(row, col);
                    if (pixel.alpha() != Rgba32::alpha_transparent && pixel != extrinsic_transparency.value()) {
                        color_counts[pixel]++;
                    }
 
                    if (color_counts.size() > palette::max_size - 1) {
                        hit_error = true;
                        std::string error_message = services.diag.formatter().format(
                            "found {}th unique tile color: {}",
                            FormatParam{palette::max_size},
                            FormatParam{pixel.to_jasc_str(), Style::bold});
                        details::report_validation_error_in_metatile(
                            services,
                            metatile,
                            metatile_index,
                            internal_tile_index,
                            row,
                            col,
                            "tile-color-count-violation",
                            error_message,
                            extrinsic_transparency);
                        details::report_color_counts("tile-color-count-violation", services, color_counts);
                        goto next_tile;
                    }
                }
            }
        next_tile:;
        }
        metatile_index++;
    }
 
    auto validate_anim_frame = [&services, &hit_error, &extrinsic_transparency](
                                   const std::string &anim_name, const AnimFrame<Rgba32> &frame) -> void {
        const auto &frame_tiles = frame.tiles();
        // Iterate over each internal tile
        for (std::size_t internal_tile_index = 0; internal_tile_index < frame_tiles.size(); ++internal_tile_index) {
            const auto &tile = frame_tiles[internal_tile_index];
            std::map<Rgba32, unsigned int> color_counts;
 
            // Iterate over each pixel in the current internal tile
            for (std::size_t row = 0; row < tile::side_length_pix; ++row) {
                for (std::size_t col = 0; col < tile::side_length_pix; ++col) {
                    const auto &pixel = tile.at(row, col);
                    if (pixel.alpha() != Rgba32::alpha_transparent && pixel != extrinsic_transparency.value()) {
                        color_counts[pixel]++;
                    }
 
                    if (color_counts.size() > palette::max_size - 1) {
                        hit_error = true;
                        std::string error_message = services.diag.formatter().format(
                            "found {}th unique frame tile color: {}",
                            FormatParam{palette::max_size},
                            FormatParam{pixel.to_jasc_str(), Style::bold});
                        details::report_validation_error_in_anim(
                            services,
                            tile,
                            anim_name,
                            frame.frame_name(),
                            internal_tile_index,
                            row,
                            col,
                            "tile-color-count-violation",
                            error_message,
                            extrinsic_transparency);
                        details::report_color_counts("tile-color-count-violation", services, color_counts);
                        goto next_tile;
                    }
                }
            }
        next_tile:;
        }
    };
 
    // Validate animations
    for (const auto &[anim_name, anim] : anims) {
        if (anim.has_key_frame()) {
            const auto &key_frame = anim.key_frame();
            validate_anim_frame(anim_name, key_frame);
        }
        for (const AnimFrame<Rgba32> &frame : anim.frames() | std::views::values) {
            validate_anim_frame(anim_name, frame);
        }
    }
 
    if (hit_error) {
        return FormattableError{
            "Found tile(s) with more than {} unique non-transparent pixels.", FormatParam{palette::max_size - 1}};
    }
 
    return {};
}
 
[[nodiscard]] ChainableResult<void> inline validate_global_color_count(
    const TilesetCompileValidatorServices &services,
    const std::string &tileset_name,
    bool is_secondary,
    const std::vector<Metatile<Rgba32>> &metatiles,
    const std::map<std::string, Animation<Rgba32>> &anims,
    const std::array<std::optional<Palette<Rgba32, palette::max_size>>, palette::num_palettes> &porytiles_palettes,
    const std::vector<PaletteHint> &hints)
{
    PT_UNWRAP_TILESET_CONFIG_REF(services.config, extrinsic_transparency, tileset_name, void);
    PT_UNWRAP_TILESET_CONFIG_REF(services.config, num_palettes_in_primary, tileset_name, void);
    PT_UNWRAP_TILESET_CONFIG_REF(services.config, num_palettes_total, tileset_name, void);
 
    ConfigValue<std::size_t> num_palettes_cfg = is_secondary ? num_palettes_total : num_palettes_in_primary;
    std::size_t count_max = num_palettes_cfg.value() * (palette::max_size - 1);
 
    std::map<Rgba32, unsigned int> color_counts{};
    bool hit_first_violation = false;
 
    // Count colors in the input metatiles
    std::size_t metatile_index = 0;
    for (const auto &metatile : metatiles) {
        const auto decomposed_metatile = metatile.decompose();
        for (std::size_t internal_tile_index = 0; internal_tile_index < decomposed_metatile.size();
             ++internal_tile_index) {
            const auto &tile = decomposed_metatile[internal_tile_index];
            for (std::size_t row = 0; row < tile::side_length_pix; ++row) {
                for (std::size_t col = 0; col < tile::side_length_pix; ++col) {
                    const auto &pixel = tile.at(row, col);
                    if (!pixel.is_transparent(extrinsic_transparency)) {
                        color_counts[pixel]++;
                    }
 
                    // Print the first violation only, but we'll keep counting across the rest of the metatiles so we
                    // can give a final tally.
                    if (color_counts.size() > count_max && !hit_first_violation) {
                        hit_first_violation = true;
                        std::string error_message = services.diag.formatter().format(
                            "found {}th globally unique color: {}",
                            FormatParam{palette::max_size},
                            FormatParam{pixel.to_jasc_str(), Style::bold});
                        details::report_validation_error_in_metatile(
                            services,
                            metatile,
                            metatile_index,
                            internal_tile_index,
                            row,
                            col,
                            "global-color-count-violation",
                            error_message,
                            extrinsic_transparency);
                    }
                }
            }
        }
        metatile_index++;
    }
 
    // Count colors in the input anims
    auto validate_anim_frame = [&services, &hit_first_violation, &color_counts, &count_max, &extrinsic_transparency](
                                   const std::string &anim_name, const AnimFrame<Rgba32> &frame) -> void {
        const auto &frame_tiles = frame.tiles();
        // Loop over each internal frame tile
        for (std::size_t internal_tile_index = 0; internal_tile_index < frame_tiles.size(); ++internal_tile_index) {
            const auto &tile = frame_tiles.at(internal_tile_index);
 
            // loop over tile pixels, row-major
            for (std::size_t row = 0; row < tile::side_length_pix; ++row) {
                for (std::size_t col = 0; col < tile::side_length_pix; ++col) {
                    const auto &pixel = tile.at(row, col);
 
                    if (!pixel.is_transparent(extrinsic_transparency)) {
                        color_counts[pixel]++;
                    }
 
                    // Print the first violation only, but we'll keep counting across the rest of the anims so we can
                    // give a final tally.
                    if (color_counts.size() > count_max && !hit_first_violation) {
                        hit_first_violation = true;
                        std::string error_message = services.diag.formatter().format(
                            "found {}th globally unique color: {}",
                            FormatParam{palette::max_size},
                            FormatParam{pixel.to_jasc_str(), Style::bold});
                        details::report_validation_error_in_anim(
                            services,
                            tile,
                            anim_name,
                            frame.frame_name(),
                            internal_tile_index,
                            row,
                            col,
                            "global-color-count-violation",
                            error_message,
                            extrinsic_transparency);
                    }
                }
            }
        }
    };
 
    for (const auto &[anim_name, anim] : anims) {
        if (anim.has_key_frame()) {
            const auto &key_frame = anim.key_frame();
            validate_anim_frame(anim_name, key_frame);
        }
        for (const AnimFrame<Rgba32> &frame : anim.frames() | std::views::values) {
            validate_anim_frame(anim_name, frame);
        }
    }
 
    // Finally, check Porytiles override palettes and hints. We check these last, since we've now seen all colors in the
    // actual input assets. This allows us to warn the user if they've specified manual colors that never actually
    // appear in the input assets.
    std::set<Rgba32> unused_manual_colors{};
    for (std::size_t palette_index = 0; palette_index < num_palettes_cfg; ++palette_index) {
        const std::string filename = palette_filename(palette_index);
 
        if (porytiles_palettes.at(palette_index).has_value()) {
            const auto &palette = porytiles_palettes.at(palette_index).value();
            std::vector<std::size_t> unused_slots{};
 
            for (std::size_t slot_index = 0; slot_index < palette.size(); ++slot_index) {
                if (palette.is_wildcard(slot_index)) {
                    continue;
                }
 
                const auto &pixel = palette.at(slot_index);
                // Warn user for nontransparent palette colors that satisfy either:
                //
                // 1. The palette color is not present in color_counts, i.e. it wasn't seen in any input assets.
                // 2. It's present in our unused_manual_colors set, which we update as we iterate over the palettes.
                //
                // Condition 2) is vital because it allows us to detect and report all instances of an unused color,
                // even if it was duplicated multiple times in the manual palettes.
                if ((!color_counts.contains(pixel) || unused_manual_colors.contains(pixel)) &&
                    !pixel.is_transparent(extrinsic_transparency)) {
                    services.diag.warning(
                        "unused-manual-color",
                        services.diag.formatter().format(
                            "color '{}' in slot '{}' of Porytiles palette '{}' is unused",
                            FormatParam{pixel, Style::bold},
                            FormatParam{slot_index, Style::bold},
                            FormatParam{filename, Style::bold}));
                    unused_slots.push_back(slot_index);
                    unused_manual_colors.insert(pixel);
                }
 
                // Increment count for color.
                if (!pixel.is_transparent(extrinsic_transparency)) {
                    color_counts[pixel]++;
                }
 
                // Print the first violation only, but we'll keep counting across the rest of the palettes so we can
                // give a final tally.
                if (color_counts.size() > count_max && !hit_first_violation) {
                    hit_first_violation = true;
                    std::string error_message = services.diag.formatter().format(
                        "in Porytiles palette '{}': found {}th globally unique color: {}",
                        FormatParam{filename, Style::bold},
                        FormatParam{palette::max_size},
                        FormatParam{pixel.to_jasc_str(), Style::bold});
                    services.diag.error("global-color-count-violation", error_message);
                    std::vector<std::size_t> violating_slot{};
                    violating_slot.push_back(slot_index);
                    services.diag.error_note(
                        "global-color-count-violation",
                        build_porytiles_palette_highlight_lines(
                            services.diag.formatter(),
                            services.palette_printer,
                            "violating slot",
                            palette,
                            filename,
                            violating_slot));
                }
            } // END: loop over all slots in override palette
 
            // Print note highlighting all unused slots in this palette
            if (!unused_slots.empty()) {
                services.diag.warning_note(
                    "unused-manual-color",
                    build_porytiles_palette_highlight_lines(
                        services.diag.formatter(),
                        services.palette_printer,
                        "slots with unused colors",
                        palette,
                        filename,
                        unused_slots));
            }
            unused_slots.clear();
        }
    } // END: loop over all override palettes
 
    for (const auto &hint : hints) {
        std::vector<std::size_t> unused_slots{};
 
        for (std::size_t slot_index = 0; slot_index < hint.palette().size(); ++slot_index) {
            const auto &pixel = hint.palette().at(slot_index);
 
            // Warn user for nontransparent palette colors that satisfy either:
            //
            // 1. The palette color is not present in color_counts, i.e. it wasn't seen in any input assets.
            // 2. It's present in our unused_manual_colors set, which we update as we iterate over the palettes.
            //
            // Condition 2) is vital because it allows us to detect and report all instances of an unused color,
            // even if it was duplicated multiple times in the manual palettes.
            if ((!color_counts.contains(pixel) || unused_manual_colors.contains(pixel)) &&
                !pixel.is_transparent(extrinsic_transparency)) {
                services.diag.warning(
                    "unused-manual-color",
                    services.diag.formatter().format(
                        "color '{}' in slot '{}' of palette hint '{}' is unused",
                        FormatParam{pixel, Style::bold},
                        FormatParam{slot_index, Style::bold},
                        FormatParam{hint.name(), Style::bold}));
                unused_slots.push_back(slot_index);
                unused_manual_colors.insert(pixel);
            }
 
            // Increment count for color.
            if (!pixel.is_transparent(extrinsic_transparency)) {
                color_counts[pixel]++;
            }
 
            // Print the first violation only, but we'll keep counting across the rest of the hints so we can
            // give a final tally.
            if (color_counts.size() > count_max && !hit_first_violation) {
                hit_first_violation = true;
                std::string error_message = services.diag.formatter().format(
                    "in palette hint '{}': found {}th globally unique color: {}",
                    FormatParam{hint.name(), Style::bold},
                    FormatParam{palette::max_size},
                    FormatParam{pixel.to_jasc_str(), Style::bold});
                services.diag.error("global-color-count-violation", error_message);
                std::vector<std::size_t> violating_slot{};
                violating_slot.push_back(slot_index);
                services.diag.error_note(
                    "global-color-count-violation",
                    build_palette_hint_highlight_lines(
                        services.diag.formatter(),
                        services.palette_printer,
                        "violating slot",
                        hint,
                        hint.name(),
                        violating_slot));
            }
        } // END: loop over all slots in palette hint
 
        // Print note highlighting all unused slots in this palette
        if (!unused_slots.empty()) {
            services.diag.warning_note(
                "unused-manual-color",
                build_palette_hint_highlight_lines(
                    services.diag.formatter(),
                    services.palette_printer,
                    "slots with unused colors",
                    hint,
                    hint.name(),
                    unused_slots));
        }
        unused_slots.clear();
    } // END: loop over all palette hints
 
    if (color_counts.size() > count_max) {
        services.diag.error(
            "global-color-count-violation",
            services.diag.formatter().format(
                "global color count violation: found '{}' unique colors, limit is '{}'",
                FormatParam{color_counts.size(), Style::bold},
                FormatParam{count_max, Style::bold}));
        details::report_color_counts("global-color-count-violation", services, color_counts);
        services.diag.error_note(
            "global-color-count-violation",
            build_global_color_limit_lines(services.diag.formatter(), count_max, num_palettes_cfg));
        return FormattableError{
            "Found '{}' unique colors globally, limit is '{}'.",
            FormatParam{color_counts.size(), Style::bold},
            FormatParam{count_max, Style::bold}};
    }
 
    return {};
}
 
[[nodiscard]] inline ChainableResult<void> validate_precision_loss(
    const TilesetCompileValidatorServices &services,
    const std::string &tileset_name,
    const std::vector<Metatile<Rgba32>> &metatiles,
    const std::map<std::string, Animation<Rgba32>> &anims,
    const std::array<std::optional<Palette<Rgba32, palette::max_size>>, palette::num_palettes> &porytiles_palettes,
    const std::vector<PaletteHint> &hints,
    const std::optional<std::array<Palette<Rgba32, palette::max_size>, palette::num_palettes>> &porymap_palettes)
{
    return {};
}
 
[[nodiscard]] inline ChainableResult<void> validate_anim_frames(
    const TilesetCompileValidatorServices &services,
    const std::string &tileset_name,
    const std::map<std::string, Animation<Rgba32>> &anims)
{
    PT_UNWRAP_TILESET_CONFIG_REF(services.config, extrinsic_transparency, tileset_name, void);
    PT_UNWRAP_TILESET_CONFIG_REF(services.config, global_frame_linking, tileset_name, void);
    PT_UNWRAP_TILESET_CONFIG_REF(services.config, per_anim_overrides, tileset_name, void);
 
    bool hit_error = false;
 
    // Validation 0: Warn when animations with automatic frame linking are missing a key frame.
    //
    // In automatic mode, key.png is used to determine which tiles in tiles.png are animation tiles. Without it,
    // the first regular frame is used as a representative and animation tiles will not be linked to any metatiles.
    // This is allowed so users can incrementally build animation assets before committing to linking.
    for (const auto &[anim_name, anim] : anims) {
        bool has_per_anim_override = per_anim_overrides.value().contains(anim_name);
        const ConfigValue<FrameLinking> effective_linking =
            (has_per_anim_override && per_anim_overrides.value().at(anim_name).linking.has_value())
                ? per_anim_overrides.derive(per_anim_overrides.value().at(anim_name).linking)
                : global_frame_linking;
 
        if (effective_linking == FrameLinking::automatic && !anim.has_key_frame()) {
            std::vector<std::string> warning_lines;
            warning_lines.emplace_back(services.diag.formatter().format(
                "Animation '{}' has frame_linking '{}' but no key frame (key.png) was found.",
                FormatParam{anim_name, Style::bold},
                FormatParam{"automatic", Style::bold}));
            warning_lines.emplace_back("Animation tiles will not be linked to any metatiles.");
            services.diag.warning("missing-key-frame", warning_lines);
 
            if (has_per_anim_override) {
                std::vector<std::string> note_lines;
                note_lines.push_back(services.diag.formatter().format(
                    "Per-animation override for '{}' sets frame_linking to '{}'.",
                    FormatParam{anim_name, Style::bold},
                    FormatParam{"automatic", Style::bold}));
                note_lines.emplace_back("");
                note_lines.append_range(format_config_note(services.diag.formatter(), per_anim_overrides));
                services.diag.warning_note("missing-key-frame", note_lines);
            }
            else {
                services.diag.warning_note(
                    "missing-key-frame", format_config_note(services.diag.formatter(), global_frame_linking));
            }
        }
    }
 
    // Validation 1: Ensure no animation key frame tile is fully transparent.
    //
    // Key frames are used to index into animations from the layer sheet. If a key frame tile were transparent,
    // Porytiles couldn't distinguish it from the default transparent tile (tile 0). This restriction only applies to
    // actual key frames (key.png), not to representative frames used as fallbacks when no key frame is present.
    //
    // We collect all violations before failing so the user can see all problematic tiles at once.
    for (const auto &[anim_name, anim] : anims) {
        if (!anim.has_key_frame()) {
            continue;
        }
 
        const auto &key_frame = anim.key_frame();
        const auto &tiles = key_frame.tiles();
 
        for (std::size_t tile_idx = 0; tile_idx < tiles.size(); ++tile_idx) {
            const auto &tile = tiles.at(tile_idx);
 
            if (tile.is_transparent(extrinsic_transparency.value())) {
                hit_error = true;
                std::string error_message = "key frame tile is fully transparent";
                details::report_validation_error_in_anim_tile(
                    services,
                    tile,
                    anim_name,
                    key_frame.frame_name(),
                    tile_idx,
                    "transparent-key-frame",
                    error_message,
                    extrinsic_transparency);
 
                services.diag.error_note(
                    "transparent-key-frame",
                    std::vector<std::string>{
                        "Key frame tiles cannot be fully transparent because they would be indistinguishable "
                        "from the actual transparent tile on the layer PNGs."});
            }
        }
    }
 
    if (hit_error) {
        return FormattableError{"Found animation(s) with transparent key frame tile(s)."};
    }
 
    // Validation 2: Ensure there are no duplicate key frame tiles across all animations.
    //
    // Each key frame tile must be unique so that Porytiles can properly identify which animation a tile belongs to. We
    // collect all key frame tiles into a map and report any that appear in multiple locations.
    std::map<PixelTile<Rgba32>, std::vector<std::pair<std::string, std::size_t>>> key_frame_occurrences;
 
    for (const auto &[anim_name, anim] : anims) {
        if (!anim.has_key_frame()) {
            continue;
        }
 
        const auto &key_frame = anim.key_frame();
        const auto &tiles = key_frame.tiles();
 
        for (std::size_t tile_idx = 0; tile_idx < tiles.size(); ++tile_idx) {
            const auto &tile = tiles.at(tile_idx);
            key_frame_occurrences[tile].emplace_back(anim_name, tile_idx);
        }
    }
 
    for (const auto &[tile, occurrences] : key_frame_occurrences) {
        if (occurrences.size() > 1) {
            hit_error = true;
 
            // Report error for first occurrence
            const auto &[first_anim, first_idx] = occurrences.at(0);
            std::string error_message = "duplicate key frame tile";
            details::report_validation_error_in_anim_tile(
                services,
                tile,
                first_anim,
                "key",
                first_idx,
                "duplicate-key-frame",
                error_message,
                extrinsic_transparency);
 
            // Build note showing all locations where this tile appears
            std::vector<std::string> note_lines;
            note_lines.emplace_back("This tile appears as a key frame in multiple locations:");
            for (const auto &[anim_name, tile_idx] : occurrences) {
                note_lines.push_back(services.diag.formatter().format(
                    "   - anim '{}' subtile {}", FormatParam{anim_name, Style::bold}, FormatParam{tile_idx}));
            }
            note_lines.emplace_back("");
            note_lines.emplace_back(
                "Each key frame tile must be unique so that Porytiles can identify which "
                "animation a tile belongs to at runtime.");
            services.diag.error_note("duplicate-key-frame", note_lines);
        }
    }
 
    // Validation 3: Verify composite frame color counts.
    //
    // Each animation's composite frame aggregates all colors from all frames at each tile position. Since the palette
    // index is fixed for the entire animation lifecycle, each composite tile cannot exceed 15 unique colors.
    //
    // We iterate pixel by pixel across all frames for each tile position, tracking actual color counts. When a
    // violation is detected, we show the specific subtile and highlight the pixel that caused the overflow.
    for (const auto &[anim_name, anim] : anims) {
        if (!anim.has_key_frame()) {
            continue;
        }
 
        const auto &key_frame = anim.key_frame();
        const std::size_t tile_count = key_frame.tile_count();
 
        for (std::size_t tile_idx = 0; tile_idx < tile_count; ++tile_idx) {
            // Track color counts across all frames for this tile position
            std::map<Rgba32, unsigned int> color_counts;
 
            // Track violation details (frame name, tile, row, col) for later reporting
            bool found_violation = false;
            std::string violation_frame_name;
            const PixelTile<Rgba32> *violation_tile = nullptr;
            std::size_t violation_row = 0;
            std::size_t violation_col = 0;
            Rgba32 violation_pixel;
 
            // Helper lambda to process a tile's pixels
            auto process_tile_pixels = [&](const PixelTile<Rgba32> &tile, const std::string &frame_name) {
                for (std::size_t row = 0; row < tile::side_length_pix; ++row) {
                    for (std::size_t col = 0; col < tile::side_length_pix; ++col) {
                        const auto &pixel = tile.at(row, col);
                        if (!pixel.is_transparent(extrinsic_transparency)) {
                            color_counts[pixel]++;
                        }
 
                        // Record the first violation but continue counting for accurate totals
                        if (color_counts.size() > palette::max_size - 1 && !found_violation) {
                            found_violation = true;
                            violation_frame_name = frame_name;
                            violation_tile = &tile;
                            violation_row = row;
                            violation_col = col;
                            violation_pixel = pixel;
                        }
                    }
                }
            };
 
            // Process key frame pixels
            process_tile_pixels(key_frame.tile_at(tile_idx), key_frame.frame_name());
 
            // Process regular frame pixels
            for (const auto &[frame_name, frame] : anim.frames()) {
                process_tile_pixels(frame.tile_at(tile_idx), frame_name);
            }
 
            // Report violation after processing all frames (so we have complete color counts)
            if (found_violation) {
                hit_error = true;
 
                std::string error_message = services.diag.formatter().format(
                    "found {}th unique composite frame tile color: {}",
                    FormatParam{palette::max_size},
                    FormatParam{violation_pixel.to_jasc_str(), Style::bold});
                details::report_validation_error_in_anim(
                    services,
                    *violation_tile,
                    anim_name,
                    violation_frame_name,
                    tile_idx,
                    violation_row,
                    violation_col,
                    "composite-color-count-violation",
                    error_message,
                    extrinsic_transparency);
 
                std::vector<std::string> note_lines;
                note_lines.emplace_back(
                    "The composite frame aggregates all colors across all animation frames for each tile position. "
                    "Since the palette index is fixed for the entire animation lifecycle, each composite tile cannot "
                    "exceed 15 colors.");
                services.diag.error_note("composite-color-count-violation", note_lines);
 
                // Print all frame tiles at this position to show what's contributing colors
                std::vector<std::string> frame_tiles_note;
                frame_tiles_note.emplace_back("Tiles at this position across all frames:");
 
                // Print key frame tile
                frame_tiles_note.emplace_back("");
                frame_tiles_note.push_back(services.diag.formatter().format(
                    "Frame '{}' subtile {}:", FormatParam{key_frame.frame_name(), Style::bold}, FormatParam{tile_idx}));
                auto key_tile_visual =
                    services.tile_printer.print_tile(key_frame.tile_at(tile_idx), extrinsic_transparency);
                frame_tiles_note.append_range(key_tile_visual);
 
                // Print regular frame tiles
                for (const auto &[frame_name, frame] : anim.frames()) {
                    frame_tiles_note.emplace_back("");
                    frame_tiles_note.push_back(services.diag.formatter().format(
                        "Frame '{}' subtile {}:", FormatParam{frame_name, Style::bold}, FormatParam{tile_idx}));
                    auto frame_tile_visual =
                        services.tile_printer.print_tile(frame.tile_at(tile_idx), extrinsic_transparency);
                    frame_tiles_note.append_range(frame_tile_visual);
                }
 
                services.diag.error_note("composite-color-count-violation", frame_tiles_note);
 
                details::report_color_counts("composite-color-count-violation", services, color_counts);
            }
        }
    }
 
    if (hit_error) {
        return FormattableError{"Animation frame validation failed."};
    }
 
    return {};
}
 
} // namespace porytiles